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

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

## 参照元

`facets/personas/` を参照元として使う。新規作成時は既存ファイルをコピーして使う。

| 参照ファイル | 用途 | 使用例 |
|------------|------|--------|
| `coder.md` | 実行系エージェントの責任境界 | coder, planner, conductor, research-digger |
| `architecture-reviewer.md` | 専門レビュアーの責任境界 | architecture-reviewer, security-reviewer, cqrs-es-reviewer |
| `melchior.md` | 固有の人格・口調を持つキャラクター型 | melchior, balthasar, casper |

---

## ペルソナとは

エージェントの identity、専門性、責任境界を定義するファイル。system prompt に配置される。

| 項目 | 内容 |
|------|------|
| 目的 | エージェントの identity、専門性、責任境界 |
| 配置 | system prompt（`{{agentDefinition}}`） |
| 対象 | 1つのエージェント |
| 判断基準 | 「誰として何に責任を持つか？」を定義しているならペルソナ |

ペルソナは専門性、責任、役割境界を定義する。探索手順はインストラクション、判断規則はポリシー、再利用するドメイン知識や検出パターンはナレッジへ置く。

### 実際の配置先

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

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

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

### ポリシーとの分離

```
この内容は…
├── identity、専門性、責任境界 → ペルソナ
├── 判断原則・禁止事項・変更権限 → ポリシー
├── 再利用する知識・検出パターン → ナレッジ
└── 探索順・追加探索条件・停止条件 → instruction
```

---

## フォーマット

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

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

## 役割の境界

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

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

## 行動姿勢

- ...

```

---

## セクション詳細

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

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

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

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

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

- 「やること」「やらないこと」を箇条書きで列挙
- 他エージェント名やステップ名に依存せず、そのペルソナ単体で責務境界が読めるようにする
- 他のエージェントの責務を侵食しないことを明示

```markdown
# 良い例
**やらないこと:**
- セキュリティ脆弱性のレビュー
- AI特有のパターン検出

# 悪い例
**やらないこと:**
- 他の役割にエスカレーションする
- 別の担当に修正させる
```

### 行動姿勢（必須）

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

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

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

## DO / DON'T

| DO | DON'T |
|----|-------|
| ロール定義は1-2文で簡潔に | 長い自己紹介を書く |
| 他エージェント名を書かずに責務境界を明確にする | 他エージェントやステップへの依存を書く |
| 専門性と責任を具体的にする | 知識・検出パターン・判定表を持たせる |
| 行動姿勢に1行の行動指針としてポリシーと同じ概念を記載 | 汎用的なコーディングルールの詳細を混ぜる |

---

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

1. **ポリシーの詳細ルール**: コード例・判定基準・例外リスト等の詳細はポリシーの責務（1行の行動指針は行動姿勢に記載してよい）
2. **他エージェント・他ステップへの依存**: エージェント名、ステップ名、担当の受け渡し、連携前提の説明
3. **ワークフロー固有の概念**: ステップ名、レポートファイル名、ステップ間ルーティング
4. **ツール固有の環境情報**: `.takt/runs/` 等のディレクトリパス、テンプレート変数（`{report_dir}` 等）
5. **実行手順**: 「まず〜を読み、次に〜を実行」のような手順は instruction の責務

検出パターンと判断材料はナレッジ、検索順や追加探索条件はインストラクションに置く。ペルソナへ例外的に重複させない。

---

## 共通ルール

### 見出しの深さ

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

### 文体

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

### ファイル命名

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

## チェックリスト

- [ ] ロール定義が1-2文で書かれているか
- [ ] 「やること」「やらないこと」が明確に分かれているか
- [ ] 他エージェント名やステップ名に依存せず、責務境界が読めるか
- [ ] 行動姿勢がポリシーの詳細ルール（コード例・テーブル・例外リスト）を転記していないか（1行の行動指針はOK）
- [ ] 知識・検出パターン・判定表がナレッジまたはポリシーへ分離されているか
- [ ] ワークフロー固有の概念（ステップ名、レポートファイル名等）が含まれていないか
- [ ] ツール固有のパス（`.takt/` 等）が含まれていないか
- [ ] `####` 以下のネストがないか