takt/builtins/ja/PERSONA_STYLE_GUIDE.md

ペルソナ スタイルガイド

このガイドは 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（ペルソナに書かない）

---

フォーマット

# {エージェント名}

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

## 役割の境界

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

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

## 行動姿勢

- ...

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

### {観点1}
...

---

セクション詳細

ロール定義（必須）

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

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

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

役割の境界（必須）

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

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

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

行動姿勢（必須）

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

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

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

ドメイン知識（任意）

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

---

DO / DON'T

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

---

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

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

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

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

# 許容 — 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/ 等）が含まれていないか
• #### 以下のネストがないか