ea7ce54912
## 概要
`resources/` ディレクトリを `builtins/` にリネームし、用途を明確化。同時に export-cc コマンドを拡張して全リソースをコピーするように修正する。
---
## タスク一覧
### 1. ディレクトリリネーム（優先度: 高）
| 変更前 | 変更後 |
|--------|--------|
| `resources/` | `builtins/` |
| `resources/global/{lang}/` | `builtins/{lang}/`（global/ 階層を除去） |
| `resources/project/` | `builtins/project/` |
| `resources/skill/` | `builtins/skill/` |
### 2. 不要ファイル削除（優先度: 高）
- `builtins/{lang}/prompts/` を削除
- 対象: `interactive-system.md`, `interactive-summary.md`
- 理由: コードから未参照、実体は `src/shared/prompts/`
### 3. コード修正 — パス参照（優先度: 高）
`resources` → `builtins`、`global/{lang}` → `{lang}` に更新:
| ファイル | 修正内容 |
|----------|----------|
| `src/infra/resources/index.ts` | `getResourcesDir()`, `getGlobalResourcesDir()`, `getLanguageResourcesDir()` 等のパス |
| `src/infra/config/paths.ts` | `getBuiltinPiecesDir()`, `getBuiltinPersonasDir()` |
| `src/infra/config/global/initialization.ts` | `copyLanguageConfigYaml()` |
| `src/infra/config/loaders/pieceCategories.ts` | `getLanguageResourcesDir()` 参照 |
| `src/features/config/ejectBuiltin.ts` | `getLanguageResourcesDir()` 参照 |
| `src/features/config/deploySkill.ts` | `getResourcesDir()` 参照 |
### 4. export-cc 修正（優先度: 高）
ファイル: `src/features/config/deploySkill.ts`
**現状**: pieces/ と personas/ のみコピー
**修正後**:
- `builtins/{lang}/` 全体を `~/.claude/skills/takt/` にコピー
- `skill/` のファイル（SKILL.md, references/, takt-command.md）は従来通り
- サマリー表示を新リソースタイプ（stances, instructions, knowledge 等）に対応
- confirm メッセージ修正:
- 現状: `'上書きしますか？'`
- 修正後: `'既存のスキルファイルをすべて削除し、最新版に置き換えます。続行しますか？'`
### 5. テスト修正（優先度: 中）
| ファイル | 修正内容 |
|----------|----------|
| `src/__tests__/initialization.test.ts` | `getLanguageResourcesDir` のパス期待値 |
| `src/__tests__/piece-category-config.test.ts` | mock パス |
| その他 `resources` パスを参照しているテスト | パス更新 |
### 6. ビルド・パッケージ設定（優先度: 中）
| ファイル | 修正内容 |
|----------|----------|
| `package.json` | `files` フィールドで `resources/` → `builtins/` |
| `tsconfig.json` | `resources/` への参照があれば更新 |
| `.gitignore` | 必要に応じて更新 |
### 7. ドキュメント（優先度: 低）
- `CLAUDE.md` の Directory Structure セクションを更新
- JSDoc コメントから `prompts/` 記述を削除
---
## 制約
- `builtins/{lang}/` のフラット構造は変更不可（ピースYAML内の相対パス依存）
- eject のセーフティ（skip-if-exists）は変更不要
- export-cc のセーフティ（SKILL.md 存在チェック + confirm）は維持
---
## 確認方法
- `npm run build` が成功すること
- `npm test` が全てパスすること
- `takt init` / `takt eject` / `takt export-cc` が正常動作すること
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/reports/` 等のディレクトリパス、テンプレート変数（`{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/` 等）が含まれていないか
|
||
- [ ] `####` 以下のネストがないか
|