docs(claude): CLAUDE.md 補上工具分工、專案慣例、授權規範、驗證指令與 Git/PR 流程 #63
@@ -52,6 +52,15 @@ Implement tasks from an OpenSpec change.
|
||||
- **spec-driven**: proposal, specs, design, tasks
|
||||
- Other schemas: follow the contextFiles from CLI output
|
||||
|
||||
<!-- CFDive 自訂區塊：由 `openspec update` 重新產生時會被覆蓋，更新後需重新加回（見 docs/analysis/2026-10-14-project-prompt-improvements.md S1） -->
|
||||
4b. **測試對應檢查（實作前必做，CLAUDE.md 規定）**
|
||||
|
||||
依 spec 與 tasks 檢查：
|
||||
- 列出每一個 `#### Scenario`（即 Acceptance Criteria），對應到 tasks.md 中至少一個 `[整合測試]` 或單元測試 task
|
||||
- 若有 Scenario 沒有對應測試 task：**停止實作**，列出缺漏清單，詢問使用者是否補上 tasks，不可自行略過
|
||||
- 若涉及權限行為，確認有跨角色（member / provider / admin / 未登入）的測試 task
|
||||
- 若 design.md 觸及安全觸發條件（外部輸入、資料庫讀寫、身份驗證/授權、檔案上傳、外部 API）但缺「安全確認」段落，同樣停止並回報
|
||||
|
||||
5. **Show current progress**
|
||||
|
||||
Display:
|
||||
@@ -143,6 +152,8 @@ What would you like to do?
|
||||
- Update task checkbox immediately after completing each task
|
||||
- Pause on errors, blockers, or unclear requirements - don't guess
|
||||
- Use contextFiles from CLI output, don't assume specific file names
|
||||
- (CFDive) Never start implementing while any Scenario lacks a corresponding test task; see step 4b
|
||||
- (CFDive) When all tasks are done, run the `verify-and-report` skill before suggesting archive
|
||||
|
||||
**Fluid Workflow Integration**
|
||||
|
||||
|
||||
@@ -6,21 +6,44 @@ argument-hint: [功能名稱]
|
||||
|
||||
## Instructions
|
||||
|
||||
1. 確認目前 git 狀態是否乾淨（`git status`）；若有未提交的變更，先詢問使用者要 stash 還是先提交，不可直接覆蓋。
|
||||
2. 執行以下指令同步 master：
|
||||
1. 檢查目前狀態：
|
||||
```
|
||||
git status --short
|
||||
git branch --show-current
|
||||
```
|
||||
- 若有未提交的變更，先詢問使用者要 stash 還是先提交，不可直接覆蓋。
|
||||
- 若目前**不在 master**，先詢問上一個分支的 PR 是否已合併，不可在未合併的分支上直接疊新功能。
|
||||
|
||||
2. 同步 master（遠端名稱為小寫 `vps`，是自架 Gitea；不要用 `origin`，那是 GitHub 鏡像）：
|
||||
```
|
||||
git checkout master
|
||||
git pull VPS master
|
||||
git pull vps master
|
||||
```
|
||||
3. 若使用者的請求中沒有明確功能名稱，先詢問功能名稱，並轉換為符合團隊命名慣例的分支名稱（英文、kebab-case，例如 `feature/dive-log-export`）。
|
||||
- 若 `git pull` 出現分歧或無法 fast-forward，停止並回報，不要自行 reset 或 force。
|
||||
|
||||
3. 決定分支名稱（英文、kebab-case）。若使用者沒有給功能名稱，先詢問。依性質選前綴：
|
||||
|
||||
| 性質 | 前綴 | 範例 |
|
||||
|------|------|------|
|
||||
| 新功能 | `feat/` | `feat/dive-log-export` |
|
||||
| 修正 | `fix/` | `fix/booking-oversell` |
|
||||
| 安全 | `security/` | `security/add-role-middleware` |
|
||||
| 文件、OpenSpec 規劃與歸檔、工具設定 | `docs/`、`chore/` | `chore/update-openspec-config` |
|
||||
| 測試 | `test/` | `test/ci-mysql-job` |
|
||||
| 效能 | `perf/` | `perf/cache-offer-list` |
|
||||
|
||||
4. 建立並切換新分支：
|
||||
```
|
||||
git checkout -b feature/<功能名稱>
|
||||
git checkout -b <前綴>/<功能名稱>
|
||||
```
|
||||
5. 分支建立完成後，向使用者確認分支已就緒，接著**必須**執行 `/opsx:propose <功能名稱>`（`<功能名稱>` 沿用步驟 3 決定的名稱）建立本次功能的 spec 提案草稿，不要自行用其他方式產生 proposal。
|
||||
6. spec 草稿完成後，依照 CLAUDE.md 的「OpenSpec 工作流規則 → Task 執行前」清單，確認 Acceptance Criteria 是否已定義且對應測試任務，未對應者提醒使用者補上，不進入實作階段。
|
||||
|
||||
5. 分支建立完成後，向使用者確認分支已就緒，接著**必須**執行 `/opsx:propose <功能名稱>`（`<功能名稱>` 沿用步驟 3 的名稱，不含前綴）建立本次功能的 spec 提案草稿，不要自行用其他方式產生 proposal。
|
||||
|
||||
6. spec 草稿完成後，依照 CLAUDE.md 的「OpenSpec 工作流規則 → Task 執行前」清單，確認每條 Acceptance Criteria（Scenario）是否都對應測試任務，未對應者提醒使用者補上，不進入實作階段。
|
||||
|
||||
## Notes
|
||||
|
||||
- 這個 skill 只負責「開分支 → 交接給 OpenSpec 流程」，不涉及 spec 內容本身的產出邏輯，避免與 CLAUDE.md 裡的 OpenSpec 規則重複維護。
|
||||
- 若專案的預設分支不是 `master`（例如 `main`），使用前請調整步驟 2、3 中的分支名稱。
|
||||
- 這個 skill 只負責「開分支 → 交接給 OpenSpec 流程」，不涉及 spec 內容本身的產出邏輯，避免與 CLAUDE.md 與 `openspec/config.yaml` 的規則重複維護。
|
||||
- OpenSpec 的規劃、實作、歸檔各自是獨立的 PR（見 CLAUDE.md「Git 與 PR 流程」）；本 skill 開的分支通常先用於「規劃」PR。
|
||||
- 不要在任何輸出中顯示 remote URL（可能含有憑證）。
|
||||
- 若專案的預設分支不是 `master`，使用前請調整步驟 2。
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
name: finish-and-pr
|
||||
description: 實作或文件變更完成後的收尾流程：確認驗證通過、依 Conventional Commits 提交、推送功能分支到 vps 並提示開 PR；PR 合併後協助清理本機分支。當使用者說「收尾」「提交並推上去」「準備開 PR」「PR 合併了幫我清理」時使用。
|
||||
argument-hint: [commit 描述，可省略]
|
||||
---
|
||||
|
||||
## Instructions
|
||||
|
||||
### A. 提交並推送
|
||||
|
||||
1. **確認分支與狀態**
|
||||
```
|
||||
git branch --show-current
|
||||
git status --short
|
||||
```
|
||||
- 目前在 `master`：**停止**，說明禁止直接提交到 master（push master 會觸發自動部署），詢問是否要先建立分支
|
||||
- 沒有任何變更：回報並結束
|
||||
|
||||
2. **確認驗證已完成**
|
||||
- 若本次對話尚未執行過 `verify-and-report`，先詢問使用者是否要先驗證；程式碼變更預設應該先驗證
|
||||
- 若驗證有失敗，**不要提交**，回報失敗內容
|
||||
|
||||
3. **確認提交內容**
|
||||
- 用 `git diff --stat` 檢視，檢查是否混入無關檔案（`.env`、`.phpunit.result.cache`、`storage/`、`node_modules/`、除錯用的暫存檔）
|
||||
- OpenSpec 的規劃、實作、歸檔應是各自獨立的 PR；若同一個分支混了不同階段，提醒使用者拆開
|
||||
- 逐一 `git add <檔案或目錄>`，避免 `git add -A` 把無關檔案帶進去
|
||||
|
||||
4. **提交**
|
||||
- 格式：`type(scope): 繁體中文描述`，type 與分支前綴一致（`feat`、`fix`、`chore`、`docs`、`security`、`test`、`perf`，另有 `ci`、`refactor`）
|
||||
- 使用者有提供描述就用，沒有就依 diff 擬一個並讓使用者確認
|
||||
- 不要使用 `--no-verify`、`--amend` 已推送的 commit
|
||||
|
||||
5. **推送功能分支（絕不推 master）**
|
||||
```
|
||||
git push -u vps <目前分支>
|
||||
```
|
||||
- 不要使用 `--force`；若被拒絕，回報原因，不要自行強推
|
||||
- 從 push 輸出中找 `Create a new pull request` 的連結，原樣提供給使用者；**不要自己組合或輸出 remote URL**（可能含憑證）
|
||||
|
||||
6. **提醒後續**
|
||||
- PR 由使用者在 Gitea 開立並合併（master 可能有分支保護）
|
||||
- 若是 OpenSpec change 的實作 PR，合併後下一步是另開 PR 執行歸檔（`/opsx:archive`）
|
||||
- 若本次變更值得再審查，可請 Pi agent 針對 `git diff master...HEAD` 做審查後再開 PR
|
||||
|
||||
### B. PR 合併後清理（使用者說已合併時）
|
||||
|
||||
1. 確認沒有未提交變更，然後：
|
||||
```
|
||||
git checkout master
|
||||
git pull vps master
|
||||
git fetch --prune vps
|
||||
```
|
||||
2. 確認該分支確實已合併：`git branch --merged master`
|
||||
3. 用 `git branch -d <分支>` 刪除本機分支；若 Git 拒絕（顯示未合併），**停止並回報**，不要改用 `-D`，除非使用者明確同意
|
||||
4. 回報目前 `master` 的最新 commit，以及是否與 `vps/master` 一致
|
||||
|
||||
## Notes
|
||||
|
||||
- 本 skill 不 merge、不 rebase、不 force push、不改寫已推送的歷史。
|
||||
- 禁止直接 push master，這是 CLAUDE.md 的明文規則。
|
||||
- 若工作區有與本次無關的未提交變更（例如使用者另外改的檔案），只提交與本次相關的檔案，並提醒其餘檔案未納入。
|
||||
@@ -56,6 +56,15 @@ Implement tasks from an OpenSpec change.
|
||||
- **spec-driven**: proposal, specs, design, tasks
|
||||
- Other schemas: follow the contextFiles from CLI output
|
||||
|
||||
<!-- CFDive 自訂區塊：由 `openspec update` 重新產生時會被覆蓋，更新後需重新加回（見 docs/analysis/2026-10-14-project-prompt-improvements.md S1） -->
|
||||
4b. **測試對應檢查（實作前必做，CLAUDE.md 規定）**
|
||||
|
||||
依 spec 與 tasks 檢查：
|
||||
- 列出每一個 `#### Scenario`（即 Acceptance Criteria），對應到 tasks.md 中至少一個 `[整合測試]` 或單元測試 task
|
||||
- 若有 Scenario 沒有對應測試 task：**停止實作**，列出缺漏清單，詢問使用者是否補上 tasks，不可自行略過
|
||||
- 若涉及權限行為，確認有跨角色（member / provider / admin / 未登入）的測試 task
|
||||
- 若 design.md 觸及安全觸發條件（外部輸入、資料庫讀寫、身份驗證/授權、檔案上傳、外部 API）但缺「安全確認」段落，同樣停止並回報
|
||||
|
||||
5. **Show current progress**
|
||||
|
||||
Display:
|
||||
@@ -147,6 +156,8 @@ What would you like to do?
|
||||
- Update task checkbox immediately after completing each task
|
||||
- Pause on errors, blockers, or unclear requirements - don't guess
|
||||
- Use contextFiles from CLI output, don't assume specific file names
|
||||
- (CFDive) Never start implementing while any Scenario lacks a corresponding test task; see step 4b
|
||||
- (CFDive) When all tasks are done, run the `verify-and-report` skill before suggesting archive
|
||||
|
||||
**Fluid Workflow Integration**
|
||||
|
||||
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
name: verify-and-report
|
||||
description: 完成一個 task 或整個 change 的實作後，執行測試與格式檢查，並依 CLAUDE.md 要求輸出固定格式的完工報告（spec 同步狀態、偏差點、AC 測試涵蓋、重複邏輯、命名一致性）。當使用者說「驗證」「檢查一下」「幫我出完工報告」，或 openspec-apply-change 全部 task 完成時使用。
|
||||
argument-hint: [change 名稱，可省略]
|
||||
---
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **確認範圍**
|
||||
```
|
||||
git branch --show-current
|
||||
git diff master...HEAD --stat
|
||||
git status --short
|
||||
```
|
||||
- 若在 `master` 上，停止並提醒使用者應該在功能分支上
|
||||
- 若有 change 名稱（或可從分支與 `openspec list` 推斷），讀取 `openspec/changes/<name>/` 的 proposal、specs、design、tasks
|
||||
|
||||
2. **執行驗證（失敗就如實回報，不要隱藏或重跑到過為止）**
|
||||
- `php artisan test`
|
||||
- 對本次變更的 PHP 檔執行 `./vendor/bin/pint --test <檔案>`（只檢查變更的檔案，不要全專案格式化）
|
||||
- `openspec validate --specs`
|
||||
- 若有前端變更：在 `frontend/` 執行 `npm run build` 確認可建置
|
||||
- 注意：`phpunit.xml` 強制使用 SQLite `:memory:`，`lockForUpdate` 等行鎖行為無法在此驗證，報告中不可宣稱「已驗證併發安全」
|
||||
|
||||
3. **AC 與測試涵蓋**
|
||||
- 逐條列出 spec 的 Scenario，指出對應的測試檔與方法（用 `rg` 找實際存在的測試，不要憑印象）
|
||||
- 找不到對應測試者標示「未涵蓋」並說明原因
|
||||
|
||||
4. **Spec 同步檢查**
|
||||
- 本次改動是否改變了既有 spec 描述的行為？列出需要更新的 `openspec/specs/<capability>/spec.md`
|
||||
- 實作與 spec 是否有偏差？列出偏差點，詢問是否更新 spec，不要自行改 spec
|
||||
- 若為新增或修改 API 端點，Swagger（`app/Docs/`）是否同步更新
|
||||
|
||||
5. **安全確認（僅在觸及觸發條件時）**
|
||||
若變更涉及外部輸入、資料庫讀寫、身份驗證/授權、檔案上傳、外部 API，依 CLAUDE.md「安全確認問題」逐項回答：驗證在哪一層、是否使用 Eloquent/Query Builder、權限檢查在哪一層、是否有 N+1、是否有 XSS 風險。
|
||||
新增的 member / provider 路由要特別確認角色檢查（CLAUDE.md「授權規範」）。
|
||||
|
||||
6. **維護性檢查**
|
||||
- 重複邏輯：本次新增的邏輯是否已存在於 codebase？用 `rg` 搜尋相似方法再判斷
|
||||
- 命名一致性：變數、函式、API endpoint 是否與現有命名一致
|
||||
|
||||
7. **輸出報告**，使用下列格式，全程使用繁體中文。
|
||||
|
||||
## 報告格式
|
||||
|
||||
```
|
||||
## 完工報告：<change 或 task 名稱>
|
||||
|
||||
### 驗證結果
|
||||
| 項目 | 結果 | 備註 |
|
||||
|------|------|------|
|
||||
| php artisan test | ✅ / ❌ N 個失敗 | |
|
||||
| pint | ✅ / ❌ | |
|
||||
| openspec validate | ✅ / ❌ | |
|
||||
|
||||
### AC 測試涵蓋
|
||||
| Scenario | 對應測試 | 狀態 |
|
||||
|----------|----------|------|
|
||||
|
||||
### Spec 同步狀態
|
||||
- 與 spec 一致 / 偏差點：...
|
||||
- 需更新的 spec 文件：...
|
||||
|
||||
### 安全確認（若適用）
|
||||
...
|
||||
|
||||
### 維護性
|
||||
- 重複邏輯：...
|
||||
- 命名一致性：...
|
||||
|
||||
### 未解決事項 / 我不確定的地方
|
||||
...
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- 不要為了讓測試通過而修改測試的預期結果；測試失敗要回報原因。
|
||||
- 本 skill 只負責檢查與回報，不修改程式、不 commit、不 push。要提交請接著使用 `finish-and-pr`。
|
||||
- 不要在輸出中顯示 remote URL（可能含有憑證）。
|
||||
Reference in New Issue
Block a user