CFDivePlatform/CLAUDE.md

CLAUDE.MD — 全域開發規則

語言設定

所有回應、說明、註解一律使用繁體中文。 程式碼內的變數名稱、函式名稱維持英文。

---

技術棧預設

• 後端：PHP 8.x / Laravel 11.44.7（主力）
• 前端：Vue 3 / React
• DB：MySQL 8.0（port 3306，透過 Docker 容器運行）
• IDE：Windsurf

---

禁止行為

• 禁止在未確認 spec 對應關係的情況下開始實作
• 禁止使用 raw SQL query（除非有明確說明理由）
• 禁止在前端直接使用 innerHTML 渲染未經處理的使用者輸入

---

安全強制規則（涉及以下情境時必須執行）

觸發條件：task 涉及以下任一項時，實作前必須先回答所有問題，未回答完畢不得開始實作。

觸發條件清單

• 接受外部輸入（表單、API 參數、URL query）
• 資料庫讀寫操作
• 身份驗證 / 授權邏輯
• 檔案上傳或處理
• 呼叫外部 API / Webhook

安全確認問題（觸發後必答）

輸入驗證

• 外部輸入有沒有經過 Validation？在哪一層？
• 有沒有直接拼接進 SQL 或 shell 指令？

資料庫

• 是否使用 Query Builder 或 Eloquent ORM？（禁止使用 raw query，除非有明確理由）
• 有沒有 N+1 查詢風險？

權限

• 這個操作需要什麼權限？權限檢查在哪一層執行？
• 有沒有可能被未授權使用者觸發？

前端（Vue/React）

• 有沒有直接將使用者輸入渲染進 DOM？（XSS 風險）
• API 呼叫有沒有帶正確的 Auth Header？

機敏資訊管理

• 密碼、API Key 等一律放 .env，不進版本控制
• 設定檔使用 ${VAR} 引用環境變數，實際值由 .env 注入

---

命名原則

• Function 名必須是動詞片語，且能完整描述其行為（getUserById 而非 getUser）
• Boolean 變數 / 屬性以 is / has / can 開頭（isActive、hasPermission）
• 禁止使用縮寫（usr、btn、tmp），除非是業界通用（id、url、api）
• Class 名是名詞，不帶 Manager / Helper / Utils 等空洞字尾——若需要，代表職責未釐清

---

Function 設計原則

• 單一職責：一個 function 只做一件事，能用一句話描述
• 長度警戒線：超過 20 行必須說明理由，或主動提示拆分
• 參數上限：超過 3 個參數時，考慮封裝為 DTO（Data Transfer Object）

---

註解原則

• 好的命名取代大部分的註解——若需要大量解釋，先重構命名
• 禁止「描述行為」的註解（// 遍歷陣列），只允許「解釋為什麼」的註解（// 此處使用 X 而非 Y，因為...）
• TODO 必須帶 issue 連結或日期，裸露的 TODO 視為技術債

---

SOLID 原則

原則	實踐方式
S 單一職責	每個 Controller 只處理一個資源；業務邏輯抽到 Service
O 開放封閉	新增功能透過擴充（新 Class / 新方法），不修改既有邏輯
L 里氏替換	子類別可完全替換父類別，不破壞預期行為
I 介面隔離	不強迫實作用不到的方法；介面依使用情境拆細
D 依賴反轉	依賴抽象（介面 / Contract）而非具體實作；透過 Laravel DI Container 注入

OOP 規範

• 封裝：內部狀態不直接暴露，透過方法存取
• 繼承：優先組合（Trait / Composition）而非繼承；繼承層數不超過 2 層
• 多型：相同介面的不同實作透過 binding 切換，不用 if/switch 判斷型別

---

OpenSpec 工作流規則

Task 執行前

每次執行 task 前，先確認：

1. 這個 task 對應哪一條 spec？（必須能指向具體文件與段落）
2. Acceptance Criteria 是否已定義且可測量？
3. 這個 task 完成後，哪些 spec 文件需要同步更新？

Task 執行後

完成任何 task 後，主動告知：

• 實作結果是否與 spec 描述一致
• 如有偏差，列出偏差點並詢問是否更新 spec
• 必須告知 spec 同步狀態：這個改動有沒有影響現有 spec 描述的行為？需要更新哪個文件？

---

維護性規則（所有 task 適用，非強制阻擋，但必須提醒）

每次 task 完成後，主動告知以下項目的狀態：

• 重複邏輯：這段邏輯是否已存在於 codebase 中，應該抽共用？
• 命名一致性：變數、函式、API endpoint 命名是否與現有規範一致？

---

溝通風格

• 發現問題直接說，不要繞彎
• 有不確定的地方，明確標注「我不確定，需要你確認」
• 不要重複確認已經決定的技術選擇