diff --git a/.claude/commands/opsx/apply.md b/.claude/commands/opsx/apply.md index ae14f0f..262c98e 100644 --- a/.claude/commands/opsx/apply.md +++ b/.claude/commands/opsx/apply.md @@ -52,6 +52,15 @@ Implement tasks from an OpenSpec change. - **spec-driven**: proposal, specs, design, tasks - Other schemas: follow the contextFiles from CLI output + +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** diff --git a/.claude/skills/branch-and-propose/SKILL.md b/.claude/skills/branch-and-propose/SKILL.md index bc604a5..b1bf048 100644 --- a/.claude/skills/branch-and-propose/SKILL.md +++ b/.claude/skills/branch-and-propose/SKILL.md @@ -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。 diff --git a/.claude/skills/finish-and-pr/SKILL.md b/.claude/skills/finish-and-pr/SKILL.md new file mode 100644 index 0000000..18d7097 --- /dev/null +++ b/.claude/skills/finish-and-pr/SKILL.md @@ -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 的明文規則。 +- 若工作區有與本次無關的未提交變更（例如使用者另外改的檔案），只提交與本次相關的檔案，並提醒其餘檔案未納入。 diff --git a/.claude/skills/openspec-apply-change/SKILL.md b/.claude/skills/openspec-apply-change/SKILL.md index 70fbdb8..6b3ab60 100644 --- a/.claude/skills/openspec-apply-change/SKILL.md +++ b/.claude/skills/openspec-apply-change/SKILL.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 + +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** diff --git a/.claude/skills/verify-and-report/SKILL.md b/.claude/skills/verify-and-report/SKILL.md new file mode 100644 index 0000000..ce1373c --- /dev/null +++ b/.claude/skills/verify-and-report/SKILL.md @@ -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//` 的 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//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. **輸出報告**，使用下列格式，全程使用繁體中文。 + +## 報告格式 + +``` +## 完工報告： + +### 驗證結果 +| 項目 | 結果 | 備註 | +|------|------|------| +| php artisan test | ✅ / ❌ N 個失敗 | | +| pint | ✅ / ❌ | | +| openspec validate | ✅ / ❌ | | + +### AC 測試涵蓋 +| Scenario | 對應測試 | 狀態 | +|----------|----------|------| + +### Spec 同步狀態 +- 與 spec 一致 / 偏差點：... +- 需更新的 spec 文件：... + +### 安全確認（若適用） +... + +### 維護性 +- 重複邏輯：... +- 命名一致性：... + +### 未解決事項 / 我不確定的地方 +... +``` + +## Notes + +- 不要為了讓測試通過而修改測試的預期結果；測試失敗要回報原因。 +- 本 skill 只負責檢查與回報，不修改程式、不 commit、不 push。要提交請接著使用 `finish-and-pr`。 +- 不要在輸出中顯示 remote URL（可能含有憑證）。