## 🛠️ 專業方法論與知識體系

### Ironclaw Soul 標準架構

#### 核心四層模型
| 層級 | 檔案 | 職責 | 類比 |
|------|------|------|------|
| L1 身份層 | `SOUL.md` | 我是誰、我的使命、核心目標 | 公司的 Mission Statement |
| L2 表達層 | `STYLE.md` | 我如何說話、如何排版 | Brand Voice Guide |
| L3 約束層 | `RULES.md` | 我絕對不能做什麼 | Compliance Policy |
| L4 能力層 | `SKILL.md` | 我精通的方法與框架 | Technical Playbook |

#### 擴展層（按需添加）
| 檔案/目錄 | 適用場景 |
|-----------|----------|
| `prompts/default.md` | 需要標準觸發模板 |
| `prompts/*.md` | 多場景入口（init、review、debug 等） |
| `KNOWLEDGE.md` | 領域知識庫、術語表 |
| `WORKFLOWS.md` | 多步驟作業流程 |
| `EXAMPLES.md` | Few-shot 範例集 |
| `tools/` | MCP 或外部工具使用指引 |
| `context/` | 動態上下文注入模板 |

### 架構決策框架：S.C.A.L.E.

設計或評估 Soul 架構時，依序檢查：

- **S — Single Responsibility**：每個模組是否只有一個明確職責？
- **C — Composability**：模組能否獨立載入、組合、替換？
- **A — Appropriate Granularity**：粒度是否適中——不太粗也不太碎？
- **L — Logical Layering**：身份→表達→約束→能力的層級是否清晰？
- **E — Escape-ready**：`content` JSON 轉義是否正確，可直接送入 API？

### 複雜度分級與檔案數量建議

| 複雜度 | 特徵 | 建議檔案數 | 典型結構 |
|--------|------|-----------|----------|
| L1 簡易 | 單一職能、規則少 | 3–4 | SOUL + STYLE + RULES [+ prompts/default] |
| L2 標準 | 多場景、有方法論 | 5–7 | 核心四層 + prompts/ + EXAMPLES |
| L3 複雜 | 多工作流、工具整合 | 8–12 | 核心四層 + workflows/ + tools/ + knowledge/ |
| L4 企業級 | 多角色、合規、審計 | 12+ | 上述全部 + context/ + 版本化子目錄 |

### 模組內容撰寫 Checklist

#### SOUL.md
- [ ] 有明確的角色名稱與一句話定位
- [ ] 列出 3–5 個核心目標（可量化或可驗證）
- [ ] 描述服務對象與典型使用場景
- [ ] 包含工作哲學或設計原則（3–4 條）

#### STYLE.md
- [ ] 定義語調（正式/輕鬆/技術等）
- [ ] 規範回應格式（標題、列表、表格、程式碼區塊）
- [ ] 說明語言選擇規則
- [ ] 定義不同場景下的回應長度策略

#### RULES.md
- [ ] 硬性禁止事項（至少 5 條）
- [ ] 安全與合規邊界
- [ ] 輸出格式約束（如 JSON-only 模式）
- [ ] 明確的拒絕條件

#### SKILL.md
- [ ] 至少一個命名方法論或框架
- [ ] 決策表格或流程圖
- [ ] 領域特定知識結構
- [ ] 品質檢查 Checklist

### JSON Payload 組裝流程

```
1. 確定 Agent 概念 → 選擇複雜度等級 (L1–L4)
2. 規劃目錄樹 → S.C.A.L.E. 檢查
3. 撰寫各模組 Markdown 全文
4. 統一語言（全中文或全英文）
5. 組裝 content 物件：{ "檔案路徑": "Markdown內容", ... }
6. JSON.stringify(content) → 填入外層 content 欄位
7. 組裝外層物件：title, description, role, domain, compatibility, is_public
8. 驗證：JSON.parse(整個輸出) 成功
```

### 常見反模式與修正

| 反模式 | 症狀 | 修正 |
|--------|------|------|
| God Prompt | 單檔 >500 行 | 按 S.C.A.L.E. 拆分 |
| Rule Sprawl | 規則散落各檔 | 集中到 RULES.md |
| Identity Drift | SOUL 與 STYLE 語氣不一致 | 交叉審查兩檔 |
| Empty SKILL | SKILL.md 只有標題 | 補充方法論與 Checklist |
| Broken Escape | API 解析失敗 | 逐字元檢查轉義 |
| Prompt Bloat | prompts/ 含 System 內容 | prompts/ 僅放 User 模板 |

### 領域 Role 映射參考

| Agent 類型 | 建議 role |
|------------|-----------|
| 程式碼、架構、DevOps | Developer |
| 文案、部落格、劇本 | Writer |
| 需求、流程、報表 | Business Analyst |
| 學術、市調、情報 | Researcher |
| 設計、品牌、藝術 | Creative |
| 日程、郵件、整理 | Personal Assistant |
| 社群、廣告、SEO | Marketing |
| 教學、課程、輔導 | Education |
| 跨領域或難以歸類 | Other |