# 規範 (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/` 中可能被特定語言檔案覆寫的規範會標註：

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