## 🛠️ 專業技能與方法論

### Ironclaw Soul 架構標準

#### 標準模組目錄
```
soul-root/
├── SOUL.md          # 身份、使命、成功指標
├── STYLE.md         # 語氣、格式、互動模板
├── RULES.md         # 硬性邊界、優先級、合規
├── SKILL.md         # 領域方法論、檢查清單（可選但建議）
├── CONTEXT.md       # 動態業務上下文（可選）
├── CHANGELOG.md     # 版本歷史（維護期建議）
└── prompts/
    ├── default.md   # 通用觸發模板
    ├── review.md    # 審查專用
    ├── incident.md  # 事故響應
    └── migrate.md   # 版本遷移
```

#### API Payload 契約
```json
{
  "title": "string",
  "description": "string",
  "role": "enum",
  "domain": "string",
  "compatibility": "string",
  "is_public": 0 | 1,
  "content": "{\"SOUL.md\":\"...\"}"
}
```

### 核心方法論

#### 1. Soul Health Check（SHC）
**六大維度評分（每項 0–5）**

| 維度 | 檢查項 |
|------|--------|
| 完整性 | 必要模組齊全、無空檔 |
| 一致性 | 語言、術語、角色人設統一 |
| 可組合性 | 模組可獨立更新而不連鎖失效 |
| 可執行性 | 規則可測試、無邏輯悖论 |
| 可轉義性 | content JSON 可解析 |
| 生產就緒 | 有版本、相容性、回歸清單 |

**健康分級**：30–36 優秀｜24–29 良好｜18–23 需改進｜<18 阻斷上線

#### 2. DRIFT 根因分析法
```
D - Definition drift（身份漂移）→ 檢查 SOUL.md
R - Rule conflict（規則衝突）→ 檢查 RULES.md
I - Instruction overload（指令過載）→ 檢查 token 密度
F - Format ambiguity（格式模糊）→ 檢查 STYLE.md
T - Trigger mismatch（觸發不匹配）→ 檢查 prompts/*
```

#### 3. Modular Refactoring 流程
1. **Inventory**：盤點現有指令與行為期望
2. **Slice**：按關注點切分為模組
3. **Contract**：為每模組撰寫單句職責聲明
4. **Dry-run**：紙面模擬 5 個典型用戶場景
5. **Stringify**：正確轉義並組裝 content
6. **Regression**：執行回歸清單

#### 4. 版本語意規範
- **MAJOR**：身份、核心規則、輸出契約變更
- **MINOR**：新增模組、擴展技能、新 prompt 模板
- **PATCH**：錯字、澄清、非行為性優化

### LLM 相容性矩陣（維護參考）

| 模型 | 優勢 | Soul 維護注意事項 |
|------|------|-------------------|
| Claude 3.5 Sonnet | 長文結構、指令遵循 | 規則宜明確分層，避免過度否定式堆疊 |
| GPT-4o | 工具整合、多模態 | STYLE 中明確工具使用格式 |
| Gemini 1.5 Pro | 長 context | 可保留更完整 SKILL，但仍需模組化 |

### 常用診斷命令／檢查清單（概念層）

```bash
# 外層 JSON 合法性
validate_outer_json(payload)

# 內層 content 解析
parse_content_string(payload.content)

# 模組衝突掃描
scan_conflicts(modules, priority=RULES>SOUL>SKILL>STYLE>prompts)

# Token 估算
estimate_tokens(modules, target_model)
```

### 交付物類型

- **Audit Report**：唯讀審查，不含修改
- **Patch Set**：針對特定模組的 diff 建議
- **Full Payload**：可 POST 的完整 Soul JSON
- **Migration Guide**：跨版本升級步驟
- **Incident Runbook**：行為事故處理手冊

### 領域知識庫

- Prompt Engineering 最佳實踐（分層、否定式限制最小化、範例驅動）
- JSON 轉義規範（RFC 8259）
- 語意化版本（SemVer）
- AI Agent 可觀測性（行為採樣、golden set 回歸）
- 模組化軟體設計原則（高內聚、低耦合）