# ペルソナ スタイルガイド

このガイドは `personas/` のファイルを作成・編集する際のルールを定義する。

## テンプレート

`templates/personas/` にテンプレートファイルを用意している。新規作成時はコピーして使う。

| テンプレート | 用途 | 使用例 |
|------------|------|--------|
| `simple.md` | ドメイン知識を持たない実行系エージェント | coder, planner, conductor, research-digger |
| `expert.md` | ドメイン知識を持つ専門エージェント | architecture-reviewer, security-reviewer, cqrs-es-reviewer |
| `character.md` | 固有の人格・口調を持つキャラクター型 | melchior, balthasar, casper |

---

## ペルソナとは

エージェントの identity と専門知識を定義するファイル。system prompt に配置される。

| 項目 | 内容 |
|------|------|
| 目的 | エージェントの identity と専門知識 |
| 配置 | system prompt（`{{agentDefinition}}`） |
| 対象 | 1つのエージェント |
| 判断基準 | 「この知識はこのエージェント固有か？」→ YES ならペルソナ |

### 実際の配置先

ペルソナは `src/shared/prompts/{lang}/perform_agent_system_prompt.md` の `{{agentDefinition}}` に展開される。

```
# TAKT
  ## TAKTの仕組み（ピース、ムーブメントの説明）
  ## 現在のコンテキスト（ピース名、ムーブメント名、処理フロー）
---
# {エージェント名}     ← ★ ペルソナがここに展開される
  ## 役割の境界
  ## 行動姿勢
  ## ドメイン知識
```

`# TAKT` と `# {エージェント名}` が同じ見出しレベルで並ぶ。`---` が境界。ペルソナの前に TAKT コンテキスト（ピース名、ムーブメント名、処理フロー全体）が既に提供されているため、ペルソナにこれらを再記述する必要はない。

### ポリシーとの分離

```
このルール/知識は…
├── 特定のエージェントだけが必要 → ペルソナ（ドメイン知識）
├── 複数のエージェントが共有 → ポリシー
└── 特定のピースの実行手順 → instruction_template（ペルソナに書かない）
```

---

## フォーマット

```markdown
# {エージェント名}

{1-2文のロール定義。「あなたは〜です。」で始める}

## 役割の境界

**やること:**
- ...

**やらないこと:**
- ...

## 行動姿勢

- ...

## ドメイン知識（該当するエージェントのみ）

### {観点1}
...
```

---

## セクション詳細

### ロール定義（必須）

- 1-2文で役割を宣言
- 「あなたは〜です。」で始める
- 専門性を明示する

```markdown
# 良い例
あなたはAI生成コードの専門家です。AIコーディングアシスタントが生成したコードを、人間が書いたコードではめったに見られないパターンや問題についてレビューします。

# 悪い例
あなたはレビュアーです。  ← 専門性が不明
```

### 役割の境界（必須）

- 「やること」「やらないこと」を箇条書きで列挙
- 「やらないこと」には担当エージェント名を明記する
- 他のエージェントの責務を侵食しないことを明示

```markdown
# 良い例
**やらないこと:**
- セキュリティ脆弱性のレビュー（Security Reviewerの仕事）
- AI特有のパターン検出（AI Antipattern Reviewerが担当）

# 悪い例
**やらないこと:**
- セキュリティのレビュー  ← 誰が担当か不明
```

### 行動姿勢（必須）

- そのエージェント固有の行動指針・AI悪癖の自覚
- ポリシーのルールと同じ概念を**1行の行動指針**として記載するのは適切（行動姿勢 = identity）
- ポリシーの**詳細ルール（コード例・判定基準・例外リスト）**をペルソナに記載するのは重複
- 箇条書き、3-8項目

```markdown
# 良い例（coder.md）
- 速さより丁寧さ。実装の楽さよりコードの正確さ
- 推測で実装せず、不明点は報告する
- 不確実なときにフォールバックで隠す → 禁止     ← 1行の行動指針はOK
- 後方互換・Legacy対応を勝手に追加する → 絶対禁止  ← 1行の行動指針はOK

# 悪い例
- フォールバック禁止パターン:                    ← ポリシーの詳細ルールの転記
  | パターン | 例 | 問題 |
  （テーブル・コード例が続く）
```

### ドメイン知識（任意）

- そのエージェントの専門分野に固有の知識
- テーブル、コード例を活用して具体的に
- ドメイン知識がないエージェント（planner 等）は省略可

---

## DO / DON'T

| DO | DON'T |
|----|-------|
| ロール定義は1-2文で簡潔に | 長い自己紹介を書く |
| 他エージェントの担当を「やらないこと」に明記 | 責務の境界を曖昧にする |
| ドメイン知識はテーブルとコード例で具体的に | 抽象的な原則だけ並べる |
| そのエージェント固有の知識のみ記載 | ポリシーの詳細ルール（コード例・テーブル）を転記 |
| 行動姿勢に1行の行動指針としてポリシーと同じ概念を記載 | 汎用的なコーディングルールの詳細を混ぜる |

---

## ペルソナに書いてはいけないもの

1. **ポリシーの詳細ルール**: コード例・判定基準・例外リスト等の詳細はポリシーの責務（1行の行動指針は行動姿勢に記載してよい）
2. **ピース固有の概念**: ムーブメント名、レポートファイル名、ステップ間ルーティング
3. **ツール固有の環境情報**: `.takt/runs/` 等のディレクトリパス、テンプレート変数（`{report_dir}` 等）
4. **実行手順**: 「まず〜を読み、次に〜を実行」のような手順はinstruction_templateの責務

### 例外: ドメイン知識としての重複

ポリシーと表面的に重複していても、**検出手法**として記載する場合は許容する。

```markdown
# 許容 — AI Antipattern Reviewer のフォールバック検出手法
# コーディングポリシーは「フォールバック禁止」というルール
# このペルソナは「どうやってフォールバックを検出するか」という手法

### フォールバック・デフォルト引数の濫用検出

検証アプローチ:
1. 変更差分で `??`、`||`、`= defaultValue` を grep
2. 各フォールバックについて: 必須データか？全呼び出し元が省略しているか？
```

行動姿勢での1行記載（「フォールバックで隠す → 禁止」）はペルソナの identity。詳細な判定基準・コード例はポリシーの責務。検出手法の記載（「grepで見つけてこう検証する」）はドメイン知識。

---

## 共通ルール

### 見出しの深さ

最大 `###` まで。`####` 以下は使わない。深くなる場合は構造を見直す。

### コード例

- 「良い例/悪い例」のペアで示す
- コメントで `// REJECT` `// OK` `// APPROVE` を付ける
- 言語は対象プロジェクトに合わせる（TypeScript が主）

### 文体

- 体言止めまたは「〜する」の常体
- 丁寧語（です・ます）は使わない
- 簡潔に。冗長な説明は避ける

### ファイル命名

- `{role}.md`（例: `coder.md`, `architecture-reviewer.md`）
- ハイフン区切り（スネークケース不可）
- 英語小文字のみ
- ディレクトリでグルーピングしない（フラット構造）

### ファイルサイズ

| 種別 | 目安 | 上限 |
|------|------|------|
| ドメイン知識なし | 30-50行 | 100行 |
| ドメイン知識あり | 50-300行 | 550行 |

ドメイン知識が多い専門レビュアー（architecture-reviewer, cqrs-es-reviewer 等）はファイルサイズが大きくなることがある。コード例が占める割合が高い場合は許容する。

---

## チェックリスト

- [ ] ロール定義が1-2文で書かれているか
- [ ] 「やること」「やらないこと」が明確に分かれているか
- [ ] 「やらないこと」に担当エージェント名が書かれているか
- [ ] 行動姿勢がポリシーの詳細ルール（コード例・テーブル・例外リスト）を転記していないか（1行の行動指針はOK）
- [ ] ドメイン知識がそのエージェント固有のものか
- [ ] ピース固有の概念（ムーブメント名、レポートファイル名等）が含まれていないか
- [ ] ツール固有のパス（`.takt/` 等）が含まれていないか
- [ ] `####` 以下のネストがないか