From e6f59f25d3548ed1ba0cac1e907ac65179277b7a Mon Sep 17 00:00:00 2001 From: Hank Date: Wed, 14 Oct 2026 23:45:53 +0800 Subject: [PATCH 1/4] =?UTF-8?q?docs(claude):=20CLAUDE.md=20=E8=A3=9C?= =?UTF-8?q?=E4=B8=8A=E5=B7=A5=E5=85=B7=E5=88=86=E5=B7=A5=E3=80=81=E5=B0=88?= =?UTF-8?q?=E6=A1=88=E6=85=A3=E4=BE=8B=E3=80=81=E6=8E=88=E6=AC=8A=E8=A6=8F?= =?UTF-8?q?=E7=AF=84=E3=80=81=E9=A9=97=E8=AD=89=E6=8C=87=E4=BB=A4=E8=88=87?= =?UTF-8?q?=20Git/PR=20=E6=B5=81=E7=A8=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 4ebf6ec..49eb177 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -16,12 +16,23 @@ --- +## 工具分工 + +- **Claude Code**：主要的實作工具（OpenSpec 流程、寫程式、提交）。專案的 skill 與指令放在 `.claude/` +- **Pi agent**：目前用於審查（review）與環境、工具調整；不負責主要實作 +- `CLAUDE.md` 是兩個工具共同讀取的規則來源；`.claude/skills/`、`.claude/commands/` 僅 Claude Code 讀取，Pi 不會載入 +- 因此跨工具都必須遵守的規則一律寫在本檔，不要只寫在 skill 裡 + +--- + ## 禁止行為 - 禁止在未確認 spec 對應關係的情況下開始實作 - 禁止使用 raw SQL query（除非有明確說明理由） - 禁止在前端直接使用 `innerHTML` 渲染未經處理的使用者輸入 - 禁止在 Acceptance Criteria 未對應測試任務的情況下開始實作 +- 禁止直接 push 或 force push `master`（push master 會觸發自動部署，一律走 PR） +- 禁止在未檢查呼叫者角色的情況下新增 member / provider 路由（見「授權規範」） --- @@ -132,6 +143,45 @@ --- +## 專案慣例 + +- API 回應格式：成功 `{ status: true, message?, data }`；失敗 `{ status: false, message, errors? }` +- Controller 位於 `app/Http/Controllers/API/`；路由集中於 `routes/api.php` +- Swagger 註解集中於 `app/Docs/`，新增或修改端點時同步更新 +- OpenSpec 的專案背景與撰寫規則以 `openspec/config.yaml` 為準，本檔不重複維護 +- 目前尚無 `app/Services/`、`app/Http/Requests/`；新增業務邏輯時優先抽成 Service，不要再擴大 Controller（既有 `AuthController` 的重構見 `docs/analysis/2026-10-14-project-review-todo.md` M1） + +--- + +## 授權規範 + +- 已知缺口：`routes/api.php` 的 `member`、`provider` 路由群組只有 `auth:sanctum`，**沒有角色 middleware**；只有 `admin` 群組有 `EnsureAdmin`（待辦見 `docs/analysis/2026-10-14-project-review-todo.md` H1） +- 在 middleware 補上之前：新增或修改 member / provider 路由時，Controller 必須明確檢查呼叫者角色與資源所有權，不可假設路由群組已有保護 +- middleware 補上之後：新路由必須掛對應角色 middleware，並保留 Controller 內的資源所有權檢查 +- 每個涉及權限的路由都必須有跨角色測試（member / provider / admin / 未登入各自的預期結果，參考 `tests/Feature/AdminEndpointAuthTest.php`） + +--- + +## 驗證指令 + +- 測試：`php artisan test`（`phpunit.xml` 強制使用 SQLite `:memory:`，因此 `lockForUpdate` 等行鎖行為在測試中不具驗證力，不可據此宣稱已驗證併發安全） +- 格式：`./vendor/bin/pint --test <變更的檔案>`；只針對本次變更的檔案，避免全專案格式化造成無關 diff +- OpenSpec：`openspec validate --specs`、`openspec status --change ` +- 完成 task 後的回報格式見 `.claude/skills/verify-and-report/SKILL.md` + +--- + +## Git 與 PR 流程 + +- 遠端：`vps`（自架 Gitea，PR 與部署）為主；`origin`（GitHub）為鏡像，非必要不需推送 +- 分支前綴：`feat/`、`fix/`、`chore/`、`docs/`、`security/`、`test/`、`perf/`；kebab-case 英文 +- Commit：`type(scope): 繁體中文描述`，type 同分支前綴（另有 `ci`、`refactor`） +- OpenSpec 變更分成獨立 PR：change 規劃、實作、歸檔各自一個 PR，不混在一起 +- 功能分支推送到 `vps` 後由使用者在 Gitea 開 PR 並合併；合併後再 `git checkout master && git pull vps master`，並刪除本機分支 +- 不要在輸出或 commit 中顯示 remote URL（`git remote -v` 的輸出可能含有憑證） + +--- + ## 溝通風格 - 發現問題直接說，不要繞彎 From ee1ba1cef35bff7920d545c21789a7b3677595e1 Mon Sep 17 00:00:00 2001 From: Hank Date: Wed, 14 Oct 2026 23:45:53 +0800 Subject: [PATCH 2/4] =?UTF-8?q?chore(windsurf):=20=E7=A7=BB=E9=99=A4?= =?UTF-8?q?=E8=88=87=20CLAUDE.md=20=E8=A1=9D=E7=AA=81=E7=9A=84=20ponytail?= =?UTF-8?q?=20=E8=A6=8F=E5=89=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../rules/ponytail-lazy-senior-dev-mode.md | 26 ------------------- 1 file changed, 26 deletions(-) delete mode 100644 .windsurf/rules/ponytail-lazy-senior-dev-mode.md diff --git a/.windsurf/rules/ponytail-lazy-senior-dev-mode.md b/.windsurf/rules/ponytail-lazy-senior-dev-mode.md deleted file mode 100644 index e923f76..0000000 --- a/.windsurf/rules/ponytail-lazy-senior-dev-mode.md +++ /dev/null @@ -1,26 +0,0 @@ -# Ponytail, lazy senior dev mode - -You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written. - -## Before writing any code - -Stop at the first rung that holds: - -- Does this need to be built at all? (YAGNI) -- Does the standard library already do this? Use it. -- Does a native platform feature cover it? Use it. -- Does an already-installed dependency solve it? Use it. -- Can this be one line? Make it one line. -- Only then: write the minimum code that works. - -## Rules - - - No abstractions that weren't explicitly requested. - - No new dependency if it can be avoided. - - No boilerplate nobody asked for. - - Deletion over addition. Boring over clever. Fewest files possible. - - Question complex requests: "Do you actually need X, or does Y cover it?" - - Pick the edge-case-correct option when two stdlib approaches are the same size, lazy means less code, not the flimsier algorithm. - - Mark intentional simplifications with a ponytail: comment. If the shortcut has a known ceiling (global lock, O(n²) scan, naive heuristic), the comment names the ceiling and the upgrade path. - -Not lazy about: input validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs (the platform is never the spec ideal, a clock drifts, a sensor reads off), anything explicitly requested. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind, the smallest thing that fails if the logic breaks (an assert-based demo/self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test. From c1698a45b6ff6a39c0935e8ed4e033a6e33a236e Mon Sep 17 00:00:00 2001 From: Hank Date: Wed, 14 Oct 2026 23:45:54 +0800 Subject: [PATCH 3/4] =?UTF-8?q?chore(claude):=20=E4=BF=AE=E6=AD=A3=20branc?= =?UTF-8?q?h-and-propose=E3=80=81apply=20=E5=8A=A0=E5=85=A5=E6=B8=AC?= =?UTF-8?q?=E8=A9=A6=E5=B0=8D=E6=87=89=E6=AA=A2=E6=9F=A5=EF=BC=8C=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=20verify-and-report=20=E8=88=87=20finish-and-pr?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude/commands/opsx/apply.md | 11 +++ .claude/skills/branch-and-propose/SKILL.md | 41 +++++++--- .claude/skills/finish-and-pr/SKILL.md | 61 ++++++++++++++ .claude/skills/openspec-apply-change/SKILL.md | 11 +++ .claude/skills/verify-and-report/SKILL.md | 79 +++++++++++++++++++ 5 files changed, 194 insertions(+), 9 deletions(-) create mode 100644 .claude/skills/finish-and-pr/SKILL.md create mode 100644 .claude/skills/verify-and-report/SKILL.md 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（可能含有憑證）。 From a59179d96c059feac96b1e942677fcbe9a37c337 Mon Sep 17 00:00:00 2001 From: Hank Date: Wed, 14 Oct 2026 23:45:54 +0800 Subject: [PATCH 4/4] =?UTF-8?q?docs(analysis):=20=E6=9B=B4=E6=96=B0=20prom?= =?UTF-8?q?pt=20=E6=94=B9=E5=96=84=E8=A8=88=E7=95=AB=E9=80=B2=E5=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-10-14-project-prompt-improvements.md | 43 +++++++++++-------- 1 file changed, 25 insertions(+), 18 deletions(-) diff --git a/docs/analysis/2026-10-14-project-prompt-improvements.md b/docs/analysis/2026-10-14-project-prompt-improvements.md index addd895..2875856 100644 --- a/docs/analysis/2026-10-14-project-prompt-improvements.md +++ b/docs/analysis/2026-10-14-project-prompt-improvements.md @@ -27,23 +27,23 @@ ### 建議修改 #### 1. `openspec/config.yaml` -- [ ] 更新「已完成模組」：Admin Panel、預約與時段、即時訊息、評價與投票、通知、課程圖片、教練審核、S3 儲存、鎖定與限流、Token Refresh -- [ ] 更新「尚未實作」：金流整合、訂閱方案（`subscriptions`／`plans` 尚無 API） -- [ ] 修正前端儲存描述（以實際程式為準，改前先重新確認 coach 端） -- [ ] 加入 `rules.proposal`：必須列出受影響的主規格 -- [ ] 加入 `rules.specs`：每個 Requirement 至少一個 `#### Scenario`；Scenario 需可轉為測試 -- [ ] 加入 `rules.tasks`：每個 Scenario 至少對應一個 `[整合測試]` task，否則不得標記 apply-ready -- [ ] 加入 `rules.design`：觸及安全觸發條件時，必須附上「安全確認」段落（回應 P9） +- [x] 更新「已完成模組」：Admin Panel、預約與時段、即時訊息、評價與投票、通知、課程圖片、教練審核、S3 儲存、鎖定與限流、Token Refresh +- [x] 更新「尚未實作」：金流整合、訂閱方案（`subscriptions`／`plans` 尚無 API） +- [x] 修正前端儲存描述（以實際程式為準，改前先重新確認 coach 端） +- [x] 加入 `rules.proposal`：必須列出受影響的主規格 +- [x] 加入 `rules.specs`：每個 Requirement 至少一個 `#### Scenario`；Scenario 需可轉為測試 +- [x] 加入 `rules.tasks`：每個 Scenario 至少對應一個 `[整合測試]` task，否則不得標記 apply-ready +- [x] 加入 `rules.design`：觸及安全觸發條件時，必須附上「安全確認」段落（回應 P9） #### 2. `CLAUDE.md`（新增區塊，避免與 config.yaml 重複規則） -- [ ] **專案慣例**：API 回應 `{ status, message?, data }`、Controller 位於 `app/Http/Controllers/API/`、Swagger 註解位於 `app/Docs/` -- [ ] **驗證指令**：`php artisan test`、`./vendor/bin/pint`；說明測試預設使用 SQLite，涉及行鎖的測試需另行確認 -- [ ] **Git 流程**：分支前綴 `feat/`、`fix/`、`chore/`、`docs/`；commit 使用 Conventional Commits 加繁中描述；一律走 PR；**禁止直接 push master（會觸發自動部署）**；推送 remote 為 `vps` -- [ ] **授權規範**：新增路由必須掛角色 middleware，並附跨角色 403 測試 -- [ ] 以一句話指向 `openspec/config.yaml`，OpenSpec 細節規則只維護一份 +- [x] **專案慣例**：API 回應 `{ status, message?, data }`、Controller 位於 `app/Http/Controllers/API/`、Swagger 註解位於 `app/Docs/` +- [x] **驗證指令**：`php artisan test`、`./vendor/bin/pint`；說明測試預設使用 SQLite，涉及行鎖的測試需另行確認 +- [x] **Git 流程**：分支前綴 `feat/`、`fix/`、`chore/`、`docs/`；commit 使用 Conventional Commits 加繁中描述；一律走 PR；**禁止直接 push master（會觸發自動部署）**；推送 remote 為 `vps` +- [x] **授權規範**：新增路由必須掛角色 middleware，並附跨角色 403 測試 +- [x] 以一句話指向 `openspec/config.yaml`，OpenSpec 細節規則只維護一份 #### 3. `.windsurf/rules/` -- [ ] 三選一，**需你決定**： +- [x] 三選一（已決定：刪除 ponytail 規則；Pi 與 Claude Code 皆讀取 CLAUDE.md，不需另外相容）： - 刪除 ponytail 規則，改為指向 CLAUDE.md（建議，單一事實來源） - 保留但改寫，移除與 SOLID 衝突的條款 - 保留，但明確標註「僅用於快速原型，不用於本專案正式程式」 @@ -72,10 +72,10 @@ ### 建議修改 -- [ ] **修改 `openspec-apply-change`**：開始前檢查 tasks.md 中每個 Scenario／AC 是否有對應測試 task，缺漏則停止並回報 -- [ ] **修正 `branch-and-propose`**：`vps` 小寫、處理非 master 起點、說明分支前綴規則 -- [ ] **新增 `verify-and-report`**：執行 `php artisan test`、`pint`，並依 CLAUDE.md 輸出固定格式報告（spec 同步狀態、偏差點、重複邏輯、命名一致性、AC 測試涵蓋） -- [ ] **新增 `finish-and-pr`**：確認測試通過、依 Conventional Commits 提交、推送分支（不推 master）、提示開 PR；歸檔另走 `openspec-archive-change` +- [x] **修改 `openspec-apply-change`**：開始前檢查 tasks.md 中每個 Scenario／AC 是否有對應測試 task，缺漏則停止並回報 +- [x] **修正 `branch-and-propose`**：`vps` 小寫、處理非 master 起點、說明分支前綴規則 +- [x] **新增 `verify-and-report`**：執行 `php artisan test`、`pint`，並依 CLAUDE.md 輸出固定格式報告（spec 同步狀態、偏差點、重複邏輯、命名一致性、AC 測試涵蓋） +- [x] **新增 `finish-and-pr`**：確認測試通過、依 Conventional Commits 提交、推送分支（不推 master）、提示開 PR；歸檔另走 `openspec-archive-change` - [ ] **新增 `security-checklist`**：從 CLAUDE.md 抽出必答問題，碰到五類觸發條件時載入 - [ ] **新增 `add-endpoint`**：新增 API 端點的檢核流程 - [ ] 決定 `commands/opsx` 與 `skills/openspec-*` 是否保留雙份（由 OpenSpec CLI 產生，建議不手動合併，只記錄於升級流程） @@ -121,7 +121,14 @@ 6. 建立唯讀 subagent（spec-auditor、security-reviewer） 7. 視需要補 `security-checklist`、`add-endpoint` -## 需要你決定的事項 +## 進度紀錄（2026-10-14） + +- 已完成：config.yaml 更新、CLAUDE.md 補充、移除 `.windsurf` ponytail 規則、修正 `branch-and-propose`、`openspec-apply-change` 加入測試對應檢查、新增 `verify-and-report` 與 `finish-and-pr` +- 工具分工：Claude Code 為主要實作工具，Pi agent 目前用於審查與環境調整；`.claude/` 保留 +- 注意：`openspec-apply-change`（skill 與 `commands/opsx/apply.md`）為 OpenSpec 產生的檔案，已加入標註「CFDive 自訂區塊」，執行 `openspec update` 後需確認並重新加回 +- 尚待處理：subagent 定義、`security-checklist`、`add-endpoint` + +## 需要你決定的事項（歷史紀錄，下列 1 已決定） 1. `.windsurf` ponytail 規則：刪除、改寫、還是標註用途？ 2. subagent 存放位置與主要工具鏈（Claude Code、Pi、Windsurf）