CFDivePlatform/docs/analysis/2026-10-14-project-prompt-improvements.md

Project Prompt／Skill／Subagent 改善計畫

日期：2026-10-14 範圍：CLAUDE.md、openspec/config.yaml、.windsurf/rules/、.claude/skills/、.claude/commands/opsx/、subagent 定義。 性質：工作流與文件調整，不涉及應用程式行為，不需走 OpenSpec change，以 chore/ 分支提 PR 即可。 搭配閱讀：《2026-10-14-project-review-todo.md》。

---

一、Project Prompt

發現的問題

#	問題	影響	優先
P1	openspec/config.yaml 的 context 過期：寫「Admin Panel、預約/訂單系統、課程圖片上傳、教練審核流程」尚未實作，實際皆已完成並歸檔	每次 /opsx:propose 注入錯誤的專案狀態，AI 可能重做或誤判	高
P2	config.yaml 寫 localStorage key token、coach_token；實際 member 為 sessionStorage	同上	高
P3	.windsurf/rules/ponytail-lazy-senior-dev-mode.md 要求「No abstractions、fewest files」，與 CLAUDE.md 的 SOLID、Service 層、DTO、依賴反轉直接衝突	Windsurf 與 Claude Code 產出風格相反	高
P4	CLAUDE.md 未寫專案實際慣例（API 回應格式、目錄結構、Swagger 放 app/Docs/）	AI 需自行猜測	中
P5	未寫驗證指令與格式化要求（php artisan test、./vendor/bin/pint）	實作後沒有標準驗證步驟	中
P6	未寫 Git／PR 流程（分支命名、commit 格式、PR 目標 remote、禁止直接 push master）	目前只存在於 skill，一般對話不會觸發；push master 會直接觸發部署	高
P7	config.yaml 只有 rules.tasks，沒有 rules.proposal、rules.specs，無法在 spec 階段強制 AC 可測量	CLAUDE.md 的「AC 必須對應測試」只靠 AI 自覺	中
P8	沒有授權規範：新路由必須掛角色 middleware（見《project-review-todo》H1）	漏洞的根因	高
P9	安全確認清單未說明「答案要記錄在哪裡」	無法稽核	低
P10	CLAUDE.md 與 config.yaml 都有 OpenSpec 規則，且各寫各的	重複維護、容易不一致	低

建議修改

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）

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 細節規則只維護一份

3. .windsurf/rules/

• 三選一（已決定：刪除 ponytail 規則；Pi 與 Claude Code 皆讀取 CLAUDE.md，不需另外相容）：
  • 刪除 ponytail 規則，改為指向 CLAUDE.md（建議，單一事實來源）
  • 保留但改寫，移除與 SOLID 衝突的條款
  • 保留，但明確標註「僅用於快速原型，不用於本專案正式程式」
• 確認 docs/STARTUP.md 內容是否與 CLAUDE.md 重複

---

二、Skills

現況

• 5 個 skill：openspec-explore、openspec-propose、openspec-apply-change、openspec-archive-change（OpenSpec 官方產出，版本 1.3.1）及自訂的 branch-and-propose
• .claude/commands/opsx/* 與對應 skill 內容幾乎重複，僅差少數文句

發現的問題

#	問題	優先
S1	openspec-apply-change 沒有任何測試相關指令，與新增的「AC 必須對應測試」規則沒有連動	高
S2	branch-and-propose 使用 git pull VPS master，實際 remote 名稱為小寫 vps（Linux 區分大小寫）	中
S3	branch-and-propose 未處理「目前不在 master」的情況，也未說明分支命名前綴規則（只舉 feature/，實際慣例有 feat/、fix/、chore/）	中
S4	沒有「實作完成 → 驗證 → 提 PR」的收尾 skill	中
S5	CLAUDE.md 要求完成後回報 spec 同步狀態、重複邏輯、命名一致性、AC 測試涵蓋，目前沒有固定模板	中
S6	安全確認清單未做成可載入的 skill	低
S7	新增 API 端點的固定步驟（路由、角色 middleware、驗證、Swagger、測試）每次重複	低
S8	commands/opsx 與 skills/openspec-* 重複，OpenSpec 升級時可能只更新其中一邊	低

建議修改

• 修改 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
• 新增 security-checklist：從 CLAUDE.md 抽出必答問題，碰到五類觸發條件時載入
• 新增 add-endpoint：新增 API 端點的檢核流程
• 決定 commands/opsx 與 skills/openspec-* 是否保留雙份（由 OpenSpec CLI 產生，建議不手動合併，只記錄於升級流程）

---

三、Subagent

現況

專案層級沒有任何 subagent 定義（.pi/agents、.claude/agents 皆不存在）。

建議角色

角色	模式	建議模型層級／思考	用途
spec-auditor	唯讀	中階／medium	檢查 proposal、tasks 的 AC 是否對應測試，是否與主規格衝突
security-reviewer	唯讀	頂階／high	依 CLAUDE.md 安全清單審查 diff（輸入驗證、授權、N+1、XSS）
test-runner	執行	快速／low	跑測試並整理失敗原因，註明 SQLite 限制
backend-implementer	寫入	中階／medium	依 tasks.md 的 [後端] 項目實作
frontend-implementer	寫入	中階／medium	依 [前端] 項目實作
spec-syncer	寫入	中階／low	歸檔時把 delta 同步回 openspec/specs/

並行規則

• 唯讀角色可隨時並行
• backend-implementer 與 frontend-implementer 僅在 design.md 已定義 API 契約且檔案不重疊時並行，各用獨立 worktree
• test-runner 必須在實作完成後序列執行
• 所有寫入型 child 預設不 push、不 merge，由主 agent 驗證 diff 後整合

待辦

• 決定 subagent 定義的存放位置：已決定放 .pi/agents/（Pi 負責審查）；.claude/agents/ 暫不放
• 先建立兩個唯讀角色：改為移植自 ProjectC 的 spec-reviewer（對應 spec-auditor）與 strict-reviewer（涵蓋 security-reviewer 並加入測試執行）；design-hardener 暫不移植
• 試用一輪後再決定是否建立寫入型角色

---

四、建議執行順序

1. 更新 openspec/config.yaml context 與 rules（P1、P2、P7）
2. 決定並處理 .windsurf 衝突（P3）
3. 補 CLAUDE.md：Git 流程、授權規範、驗證指令、專案慣例（P4、P5、P6、P8）
4. 修 branch-and-propose、openspec-apply-change（S1、S2、S3）
5. 新增 verify-and-report、finish-and-pr（S4、S5）
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 CLI 已由 1.3.1 升級至 1.14.1（2026-10-14）：openspec update 重新產生 .claude/ 內的 OpenSpec skill 與指令，先前加在 openspec-apply-change 的「測試對應檢查」自訂區塊隨之移除，改放到 openspec/config.yaml 的 operations.apply.guidance（openspec update 不會覆蓋）；operations.archive.guidance 另提醒歸檔後更新 config.yaml 的 context
• 已知限制：operations.*.guidance 屬於「建議性」提示（OpenSpec 文件明寫為 prompt-level 行為契約，非可強制的檢查），硬性規則仍以 CLAUDE.md 為準
• 升級後 openspec validate --specs --strict 有 3 份 spec 的 Requirement 超過 500 字元會失敗（account-lockout、booking-lifecycle、image-baked-deployment）；一般模式 39 份全過。日後若要在 CI 使用 --strict，需先另開 change 拆分這些 Requirement
• Subagent：已移植 spec-reviewer、strict-reviewer 至 .pi/agents/，並在 CLAUDE.md 新增「審查流程」；尚未實際跑過，需以真實 change 或 H1 漏洞試跑驗證
• 尚待處理：security-checklist、add-endpoint、design-hardener（視需要）

需要你決定的事項（歷史紀錄，下列 1 已決定）

1. .windsurf ponytail 規則：刪除、改寫、還是標註用途？
2. subagent 存放位置與主要工具鏈（Claude Code、Pi、Windsurf）
3. config.yaml 中前端 token 儲存的描述：以現況為準，還是等 M4 統一後再寫？