## 🛠️ Ironclaw Soul 架構方法論

### 五階段設計流程

#### Phase 1：概念萃取（Concept Extraction）
從使用者輸入中提取：
- **角色本質**：這個 Agent 是誰？解決什麼問題？
- **目標受眾**：誰會與此 Agent 互動？
- **成功指標**：什麼樣的輸出算成功？
- **部署情境**：API 整合、聊天介面、工作流節點？
- **語言偏好**：繁中 / 英文 / 雙語

#### Phase 2：模組規劃（Module Planning）
依 Ironclaw 標準檔案樹規劃：

```
soul-package/
├── SOUL.md          # 身份、使命、哲學（WHY + WHO）
├── STYLE.md         # 語氣、格式、輸出模式（HOW to speak）
├── RULES.md         # 硬邊界、禁令、優先級（WHAT NOT）
├── SKILL.md         # 方法論、框架、檢查清單（HOW to work）
└── prompts/
    └── default.md   # 預設觸發模板（WHEN to activate）
```

**職責分離原則**：
| 檔案 | 放入 | 不放入 |
|------|------|--------|
| SOUL.md | 身份、價值觀、使命 | 格式規則、禁令清單 |
| STYLE.md | 語調、Markdown 格式 | 核心身份定義 |
| RULES.md | MUST/MUST NOT | 技能教學、語氣描述 |
| SKILL.md | 流程、框架、領域知識 | 人格特質 |
| prompts/ | 情境觸發、入門問題 | 通用規則 |

#### Phase 3：內容撰寫（Content Authoring）

**SOUL.md 撰寫要訣**：
- 開頭用一句話定義身份
- 包含 3–5 條核心使命
- 加入工作哲學或方法論標籤
- 描述啟動行為（收到請求後第一步做什麼）

**RULES.md 撰寫要訣**：
- 禁令用「❌」標記，必須用可驗證語句
- 加入衝突解決優先級
- 區分「技術約束」與「倫理約束」

**prompts/default.md 撰寫要訣**：
- 提供可直接貼給使用者的入門 prompt
- 包含變數佔位符（如 `{{角色概念}}`）
- 說明預期輸出格式

#### Phase 4：整合驗證（Integration Validation）

**JSON 驗證檢查清單**：
- [ ] 外層 JSON parse 成功
- [ ] `content` 字串 parse 後為 object
- [ ] 所有內部檔案 key 為有效路徑字串
- [ ] `role` 在允許枚舉內
- [ ] 無 markdown code fence 包裹
- [ ] 模組間無矛盾指令

**內容品質檢查清單**：
- [ ] SOUL.md 能獨立回答「你是誰」
- [ ] RULES.md 能獨立回答「你不能做什麼」
- [ ] STYLE.md 能獨立回答「你怎麼說話」
- [ ] 每個模組內容深度足夠，非 placeholder
- [ ] 技術術語拼寫正確

#### Phase 5：交付與迭代（Delivery & Iteration）
- 純 JSON 模式：直接輸出 payload
- 協作模式：先呈現架構概覽，再產出 JSON 或逐檔共創
- 主動標註可擴展模組（如 `prompts/advanced.md`, `KNOWLEDGE.md`）

### Role 選擇決策樹

```
角色主要產出是程式碼/架構？ → Developer
角色主要產出是文章/文案？   → Writer
角色主要產出是分析報告？   → Business Analyst / Researcher
角色主要產出是創意內容？   → Creative
角色主要處理日程/行政？     → Personal Assistant
角色主要做行銷推廣？       → Marketing
角色主要教學輔導？         → Education
以上皆不完全符合？           → Other
```

### Compatibility 建議原則
- 需要精準 JSON / 結構化輸出 → Claude 3.5 Sonnet
- 需要創意文案與細膩語氣 → GPT-4o
- 需要長上下文架構設計 → Claude 3.5 Sonnet / GPT-4o
- 需要多語言在地化 → Claude 3.5 Sonnet