claude-code/claude-zh/rules/README.md

規範 (Rules)

結構

規範分為 通用 (common) 層級以及 特定語言 (language-specific) 目錄：

rules/
├── common/          # 與語言無關的原則 (務必安裝)
│   ├── coding-style.md
│   ├── git-workflow.md
│   ├── testing.md
│   ├── performance.md
│   ├── patterns.md
│   ├── hooks.md
│   ├── agents.md
│   └── security.md
├── typescript/      # TypeScript/JavaScript 特定規範
├── python/          # Python 特定規範
├── golang/          # Go 特定規範
└── swift/           # Swift 特定規範

• common/ 包含通用原則 — 不包含特定語言的程式碼範例。
• 語言目錄 擴展了通用規範，加入特定框架的模式、工具及程式碼範例。每個檔案都會參照其對應的通用規範檔案。

安裝

方法 1：安裝腳本 (推薦)

# 安裝通用規範 + 一個或多個特定語言規範組
./install.sh typescript
./install.sh python
./install.sh golang
./install.sh swift

# 一次安裝多個語言規範
./install.sh typescript python

方法 2：手動安裝

重要： 請複製整個目錄 — 不要 使用 /* 將檔案攤平。 通用目錄與特定語言目錄中包含名稱相同的檔案。 將它們攤平到同一個目錄會導致特定語言檔案覆寫通用規範，並破壞特定語言檔案中使用的相對路徑 ../common/ 參照。

# 安裝通用規範 (所有專案皆必需)
cp -r rules/common ~/claude/rules/common

# 根據您專案的技術棧安裝特定語言規範
cp -r rules/typescript ~/claude/rules/typescript
cp -r rules/python ~/claude/rules/python
cp -r rules/golang ~/claude/rules/golang
cp -r rules/swift ~/claude/rules/swift

# 注意！！請根據您的實際專案需求進行配置；此處的配置僅供參考。

規範 (Rules) vs 技能 (Skills)

• 規範 (Rules) 定義了廣泛適用的標準、慣例與檢核清單 (例如：「80% 測試覆蓋率」、「不包含硬編碼金鑰」)。
• 技能 (Skills) (skills/ 目錄) 為特定任務提供深入且具可操作性的參考資料 (例如：python-patterns, golang-testing)。

特定語言的規範檔案會在適當處參照相關技能。規範告訴您「該做什麼」；技能告訴您「該怎麼做」。

新增語言

若要新增對新語言 (例如 rust/) 的支援：

1. 建立 rules/rust/ 目錄。
2. 加入擴展通用規範的檔案：
   • coding-style.md — 格式化工具、慣用法、錯誤處理模式。
   • testing.md — 測試框架、覆蓋率工具、測試組織。
   • patterns.md — 特定語言的設計模式。
   • hooks.md — 用於格式化工具、Linter、型別檢查器的 PostToolUse 鉤子 (Hooks)。
   • security.md — 金鑰管理、安全掃描工具。
3. 每個檔案開頭應包含：

   > 本檔案擴展了 [common/xxx.md](../common/xxx.md)，包含 <語言名稱> 特定內容。
   

4. 參照現有技能 (若有)，或在 skills/ 下建立新技能。

規範優先級

當特定語言規範與通用規範發生衝突時，以特定語言規範優先 (特定規範覆蓋通用規範)。這遵循標準的分層配置模式 (類似於 CSS 權重或 .gitignore 優先級)。

• rules/common/ 定義適用於所有專案的通用預設值。
• rules/golang/、rules/python/、rules/typescript/ 等目錄在語言慣用法不同時會覆寫這些預設值。

範例

common/coding-style.md 建議將「不可變性 (Immutability)」作為預設原則。特定語言的 golang/coding-style.md 可以覆寫此點：

慣用的 Go 使用指標接收者 (Pointer receivers) 進行結構體修改 — 通用原則請參閱 common/coding-style.md，但在這裡優先使用 Go 慣用的修改方式。

通用規範中的覆寫註解

rules/common/ 中可能被特定語言檔案覆寫的規範會標註：

語言註解：對於此模式不屬於慣用法的語言，此規範可能會被特定語言規範覆寫。