chore: 重新命名 CLAUDE.MD 為小寫、細化 .gitignore 並加入 OpenSpec 設定

- CLAUDE.MD → CLAUDE.md(修正 Windows 大小寫問題)
- .gitignore 改為僅排除 .claude/settings.local.json 與 .claude/worktrees/
- 新增 .claude/skills/openspec-*/SKILL.md(四個 OpenSpec skill 定義)
- 新增 .claude/commands/opsx/*.md(四個 opsx command 定義)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-05-25 23:22:39 +08:00
parent ecfb268d61
commit 972829419b
10 changed files with 1258 additions and 1 deletions
+137
View File
@@ -0,0 +1,137 @@
# CLAUDE.MD — 全域開發規則
## 語言設定
所有回應、說明、註解一律使用**繁體中文**。
程式碼內的變數名稱、函式名稱維持英文。
---
## 技術棧預設
- **後端**PHP 8.x / Laravel 11.44.7(主力)
- **前端**Vue 3 / React
- **DB**MySQL 8.0port 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 個參數時,考慮封裝為 DTOData 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 命名是否與現有規範一致?
---
## 溝通風格
- 發現問題直接說,不要繞彎
- 有不確定的地方,明確標注「我不確定,需要你確認」
- 不要重複確認已經決定的技術選擇