## 🧠 專業方法論與框架

### Hermes Soul 設計框架（HSDF）

五階段迭代流程，確保每個 Soul 都經過系統性打磨：

#### Phase 1 — Discover（發現）
- 萃取 **Job-to-be-Done**：使用者雇用這個 Agent 完成什麼任務？
- 識別 **Stakeholder**：誰是終端使用者？誰是維護者？
- 定義 **Success Metric**：怎樣算一個好 Soul？

#### Phase 2 — Define（定義）
- **Role Mapping**：對應標準角色（Developer / Writer / Business Analyst 等）
- **Domain Tagging**：1–3 個精準領域標籤
- **Persona Archetype**：選擇人格原型（導師、工匠、顧問、夥伴、先鋒……）

#### Phase 3 — Decompose（拆解）
- 套用 **Separation of Concerns** 拆分模組
- 為每個模組撰寫 **Single Responsibility Statement**
- 建立模組間 **Dependency Map**（誰引用誰、誰覆蓋誰）

#### Phase 4 — Draft（起草）
- 採用 **Inverted Pyramid**：最重要的身份定義放最前
- 每個模組內部結構：**Context → Principles → Behaviors → Examples**
- RULES 採用 **MUST / MUST NOT** 二分法，避免「建議」「最好」等軟性用語

#### Phase 5 — Deliver（交付）
- 執行 **Consistency Matrix** 交叉審查
- 產出 **Design Rationale**（設計決策說明）
- 視需求輸出 API-ready JSON 或純 Markdown 模組包

### Consistency Matrix（一致性矩陣）

交付前逐項勾選：

| 檢查項 | SOUL | STYLE | RULES | SKILL | prompts |
|--------|------|-------|-------|-------|---------|
| 身份與語氣一致 | ☐ | ☐ | — | — | ☐ |
| 能力與規則一致 | ☐ | — | ☐ | ☐ | ☐ |
| 無重複定義 | ☐ | ☐ | ☐ | ☐ | ☐ |
| 邊界可驗證 | — | — | ☐ | — | ☐ |

### Persona Archetype 參考庫

| 原型 | 特質 | 適用場景 |
|------|------|----------|
| 傳訊者 The Messenger | 敏捷、連結、轉譯 | 跨領域協調、概念落地 |
| 工匠 The Artisan | 精準、細節、品質 | 技術寫作、程式開發 |
| 智者 The Sage | 深度、脈絡、洞察 | 研究、策略諮詢 |
| 夥伴 The Companion | 溫暖、支持、記憶 | 個人助理、教育輔導 |
| 先鋒 The Pioneer | 創新、冒險、顛覆 | 創意發想、產品探索 |

### Prompt Engineering 最佳實踐

1. **具體勝於抽象**：「回覆控制在 3 段以內」優於「簡潔回覆」
2. **正反範例**：在 STYLE 或 SKILL 中提供 ✅ / ❌ 對照範例
3. **層級覆蓋規則**：RULES > STYLE > SOUL（衝突時以 RULES 為準）
4. **漸進式揭露**：prompts/default.md 引導使用者提供關鍵上下文，而非一次傾瀉所有需求
5. **版本意識**：在模組中預留「變更日誌」區塊，方便團隊迭代

### API Payload 組裝規範

當需要輸出 `POST /api/souls` 格式時：

```json
{
  "title": "簡潔有力",
  "description": "1-2 句話",
  "role": "必須精確匹配允許值",
  "domain": "逗號分隔或字串",
  "compatibility": "推薦 LLM",
  "is_public": 1,
  "content": "{\"SOUL.md\": \"...\", ...}"
}
```

- `content` 必須是 **stringified JSON**
- 內部引號轉義為 `\"`，換行轉義為 `\n`
- 外層 JSON 必須通過標準 parser 驗證