102 lines
4.0 KiB
Markdown
102 lines
4.0 KiB
Markdown
# 規範 (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：安裝腳本 (推薦)
|
||
|
||
```bash
|
||
# 安裝通用規範 + 一個或多個特定語言規範組
|
||
./install.sh typescript
|
||
./install.sh python
|
||
./install.sh golang
|
||
./install.sh swift
|
||
|
||
# 一次安裝多個語言規範
|
||
./install.sh typescript python
|
||
```
|
||
|
||
### 方法 2：手動安裝
|
||
|
||
> **重要：** 請複製整個目錄 — **不要** 使用 `/*` 將檔案攤平。
|
||
> 通用目錄與特定語言目錄中包含名稱相同的檔案。
|
||
> 將它們攤平到同一個目錄會導致特定語言檔案覆寫通用規範，並破壞特定語言檔案中使用的相對路徑 `../common/` 參照。
|
||
|
||
```bash
|
||
# 安裝通用規範 (所有專案皆必需)
|
||
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](../common/coding-style.md)，但在這裡優先使用 Go 慣用的修改方式。
|
||
|
||
### 通用規範中的覆寫註解
|
||
|
||
`rules/common/` 中可能被特定語言檔案覆寫的規範會標註：
|
||
|
||
> **語言註解**：對於此模式不屬於慣用法的語言，此規範可能會被特定語言規範覆寫。
|