229 lines
8.7 KiB
Markdown
229 lines
8.7 KiB
Markdown
# ペルソナ スタイルガイド
|
||
|
||
このガイドは `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/` 等）が含まれていないか
|
||
- [ ] `####` 以下のネストがないか
|