From 4aab94e07ada1a48cabc6ef1dd040126fb0f82b7 Mon Sep 17 00:00:00 2001
From: Hank <a6209123456789@yahoo.com.tw>
Date: Mon, 25 May 2026 02:19:24 +0800
Subject: [PATCH] =?UTF-8?q?docs:=E6=96=B0=E5=A2=9E=20CLAUDE.MD=20=E6=8A=80?=
 =?UTF-8?q?=E8=A1=93=E8=88=87=E9=96=8B=E7=99=BC=E8=A6=8F=E7=AF=84=E6=96=87?=
 =?UTF-8?q?=E4=BB=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.MD | 137 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 CLAUDE.MD

diff --git a/CLAUDE.MD b/CLAUDE.MD
new file mode 100644
index 0000000..cd280f6
--- /dev/null
+++ b/CLAUDE.MD
@@ -0,0 +1,137 @@
+# 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 命名是否與現有規範一致？
+
+---
+
+## 溝通風格
+
+- 發現問題直接說，不要繞彎
+- 有不確定的地方，明確標注「我不確定，需要你確認」
+- 不要重複確認已經決定的技術選擇
-- 
2.52.0