306 lines
11 KiB
Markdown
306 lines
11 KiB
Markdown
# インストラクション スタイルガイド
|
||
|
||
このガイドは `instructions/` のファイルを作成・編集する際のルールを定義する。
|
||
|
||
## テンプレート
|
||
|
||
`templates/instructions/` にテンプレートファイルを用意している。新規作成時は参照して使う。
|
||
|
||
| テンプレート | 用途 |
|
||
|------------|------|
|
||
| `plan.md` | 計画（タスク分析・要件整理） |
|
||
| `architect.md` | 設計（アーキテクチャ設計） |
|
||
| `implement.md` | 実装（コーディング + レポート埋め込み） |
|
||
| `review.md` | レビュー（parallel sub-step 汎用） |
|
||
| `ai-review-standalone.md` | AIレビュー（standalone、iteration tracking） |
|
||
| `ai-fix.md` | AI指摘修正（全ピース共通） |
|
||
| `fix.md` | レビュー指摘修正（汎用 fix / supervise fix） |
|
||
| `arbitrate.md` | 裁定（レビュアー vs コーダー） |
|
||
| `supervise.md` | 最終検証（レポート埋め込み） |
|
||
|
||
---
|
||
|
||
## インストラクションとは
|
||
|
||
ピースのムーブメントで実行する具体的な手順。`instruction_template` フィールドに直接記述するか、ファイル参照で使用する。
|
||
|
||
| 項目 | 内容 |
|
||
|------|------|
|
||
| 目的 | ムーブメントの実行手順と出力要件の定義 |
|
||
| 配置 | Phase 1 メッセージの `## Instructions`（`{{instructions}}`） |
|
||
| 対象 | 1つのムーブメント |
|
||
| 判断基準 | 「この手順は特定のムーブメント/ピースに固有か？」→ YES |
|
||
|
||
### 実際の配置先
|
||
|
||
インストラクションは `src/shared/prompts/{lang}/perform_phase1_message.md` の `{{instructions}}` に展開される。
|
||
|
||
```
|
||
## 実行コンテキスト（作業ディレクトリ）
|
||
## 実行ルール（git commit禁止、cd禁止、edit権限）
|
||
## Piece Context（ピース名、Iteration、Movement Iteration、Report Directory）
|
||
## User Request（自動注入）
|
||
## Previous Response（自動注入、pass_previous_response: true 時）
|
||
## Additional User Inputs（自動注入）
|
||
## Instructions
|
||
{{instructions}} ← ★ インストラクションがここに展開される
|
||
```
|
||
|
||
インストラクションの前に実行コンテキスト、ピース情報、ユーザーリクエスト、前回レスポンス等が既に提供されている。これらを再記述する必要はない。
|
||
|
||
### ペルソナ・ポリシーとの分離
|
||
|
||
```
|
||
この内容は…
|
||
├── エージェントの identity・専門知識 → ペルソナ
|
||
├── 複数エージェントの共有ルール → ポリシー
|
||
└── ムーブメント固有の手順・出力形式 → インストラクション
|
||
```
|
||
|
||
---
|
||
|
||
## エンジンの自動注入
|
||
|
||
2つのメカニズムがある。いずれもインストラクション内に手動で記述する必要はない。
|
||
|
||
### セクション注入（`## Instructions` の前に別セクションとして挿入）
|
||
|
||
`perform_phase1_message.md` のテンプレート側で処理される。instruction_template の外に配置される。
|
||
|
||
| セクション | 内容 | デフォルト |
|
||
|-----------|------|-----------|
|
||
| `## User Request` | ユーザーの元リクエスト | **常に表示** |
|
||
| `## Previous Response` | 前ムーブメントの出力 | **初回以外は常に表示**（`pass_previous_response` デフォルト: `true`） |
|
||
| `## Additional User Inputs` | 蓄積されたユーザー入力 | **常に表示** |
|
||
|
||
抑制したい場合は instruction_template 内にプレースホルダー（`{task}`, `{previous_response}`, `{user_inputs}`）を含めるか、`pass_previous_response: false` を設定する。通常は不要。
|
||
|
||
### テンプレート変数展開（instruction_template 内のプレースホルダーを置換）
|
||
|
||
InstructionBuilder が instruction_template 内の `{変数名}` を展開する。インストラクション内で使用可能。
|
||
|
||
| 変数 | 内容 |
|
||
|------|------|
|
||
| `{iteration}` | ピース全体のイテレーション数 |
|
||
| `{max_movements}` | 最大イテレーション数 |
|
||
| `{movement_iteration}` | ムーブメント単位のイテレーション数 |
|
||
| `{report_dir}` | レポートディレクトリ名（`.takt/runs/{slug}/reports`） |
|
||
| `{report:filename}` | 指定レポートの内容展開（ファイルが存在する場合） |
|
||
| `{cycle_count}` | ループモニターで検出されたサイクル回数（`loop_monitors` 専用） |
|
||
|
||
また、タグベースのルールがある場合は `[STEP:N]` タグの出力ルールが末尾に自動付加される。
|
||
|
||
---
|
||
|
||
## 書き方ルール
|
||
|
||
### 構造パターン
|
||
|
||
インストラクションは以下の構造に従う。すべてのセクションが必須ではない。
|
||
|
||
```
|
||
1. 目的の宣言（1-2行）
|
||
2. 注意事項・条件（該当する場合）
|
||
3. やること（手順 or 観点）
|
||
4. 出力契約（埋め込みの場合）
|
||
5. 必須出力（見出しを含める）
|
||
```
|
||
|
||
### 目的の宣言
|
||
|
||
- 冒頭1-2行で何をすべきかを簡潔に記述
|
||
- 命令形（「〜してください。」）を使用
|
||
|
||
```markdown
|
||
# 良い例
|
||
タスクを分析し、実装方針を立ててください。
|
||
|
||
# 良い例
|
||
テスト実行、ビルド確認、最終承認を行ってください。
|
||
|
||
# 悪い例
|
||
このムーブメントではタスクの分析を行います。 ← 説明文になっている
|
||
```
|
||
|
||
### 注意事項・条件
|
||
|
||
- 差し戻し、イテレーション回数、前提条件がある場合に記述
|
||
- `**注意:**` または `**重要:**` の太字ラベルで強調
|
||
|
||
```markdown
|
||
# 良い例
|
||
**注意:** Previous Responseがある場合は差し戻しのため、
|
||
その内容を踏まえて計画を見直してください（replan）。
|
||
|
||
# 良い例（イテレーション追跡）
|
||
**これは {movement_iteration} 回目の AI Review です。**
|
||
2回目以降は、前回の修正が実際には行われていなかったということです。
|
||
```
|
||
|
||
### やること
|
||
|
||
- 番号付きリストまたは箇条書きで手順/観点を列挙
|
||
- レビュー系は「レビュー観点」としてまとめる
|
||
|
||
```markdown
|
||
# 実行系（番号付きリスト）
|
||
**やること:**
|
||
1. タスクの要件を理解する
|
||
2. 影響範囲を特定する
|
||
3. 実装アプローチを決める
|
||
|
||
# レビュー系（箇条書き）
|
||
**レビュー観点:**
|
||
- 構造・設計の妥当性
|
||
- コード品質
|
||
- テストカバレッジ
|
||
```
|
||
|
||
### 出力契約埋め込み
|
||
|
||
- インストラクション内に出力契約を埋め込む場合がある
|
||
- コードブロック（```markdown）で囲む
|
||
- ラベル（`**Scope出力契約:**` 等）を付ける
|
||
|
||
```markdown
|
||
# 良い例
|
||
**Scope出力契約（実装開始時に作成）:**
|
||
\`\`\`markdown
|
||
# 変更スコープ宣言
|
||
...
|
||
\`\`\`
|
||
```
|
||
|
||
### 必須出力
|
||
|
||
- `**必須出力（見出しを含める）**` の見出しで出力要件を定義
|
||
- 見出しは `##` で指定（エージェントの出力にそのまま使われる）
|
||
- `- {プレースホルダー}` で各項目の説明
|
||
|
||
```markdown
|
||
**必須出力（見出しを含める）**
|
||
## 作業結果
|
||
- {実施内容の要約}
|
||
## 変更内容
|
||
- {変更内容の要約}
|
||
## テスト結果
|
||
- {実行コマンドと結果}
|
||
```
|
||
|
||
---
|
||
|
||
## DO / DON'T
|
||
|
||
| DO | DON'T |
|
||
|----|-------|
|
||
| 目的を冒頭1-2行で命令形で書く | 長い説明文で始める |
|
||
| 手順を番号付きリストで列挙 | 曖昧な指示を出す |
|
||
| テンプレート変数を正しく使う | 自動注入される変数を手動で書く |
|
||
| 出力契約は```markdownで囲む | プレーンテキストで出力契約を書く |
|
||
| 必須出力の見出しを `##` で指定 | 出力形式を指定しない |
|
||
| そのムーブメントの手順に集中 | ペルソナ（専門知識）の内容を混ぜる |
|
||
| `{report:filename}` でレポートを参照 | ファイルパスをハードコードする |
|
||
|
||
---
|
||
|
||
## インストラクションに書いてはいけないもの
|
||
|
||
1. **ペルソナの内容**: エージェントの専門知識、検出手法、行動姿勢
|
||
2. **ポリシーの内容**: DRY、Fail Fast 等の共有コーディング原則
|
||
3. **自動注入される内容**: `{task}`, `{previous_response}` のプレースホルダーを明示的に書かない（エンジンが自動付加する）
|
||
4. **他のムーブメント名の直接参照**: 「implement ムーブメントに戻る」等（ルーティングはルール定義の責務）
|
||
5. **ピース固有のルーティング**: 「APPROVE なら次へ」等（ルール条件の責務）
|
||
|
||
### 例外: レポート参照
|
||
|
||
`{report:filename}` を使ったレポート内容の展開は許容する。これはピース固有の概念だが、インストラクションの中核機能。
|
||
|
||
```markdown
|
||
# 許容
|
||
**参照するレポート:**
|
||
- AIレビュー結果: {report:ai-review.md}
|
||
|
||
# 非許容
|
||
**参照するレポート:**
|
||
- .takt/runs/20250101-task/reports/ai-review.md ← パスのハードコード
|
||
```
|
||
|
||
---
|
||
|
||
## カテゴリ別パターン
|
||
|
||
### 計画系（plan, plan-investigate, architect）
|
||
|
||
- 目的宣言 + やること（番号付き） + replan 注意事項
|
||
- 出力契約埋め込みなし（出力契約は output-contracts/ に分離）
|
||
- 5-20行
|
||
|
||
### 実装系（implement）
|
||
|
||
- 目的宣言 + テスト要件 + Scope/Decisions 出力契約埋め込み + 必須出力
|
||
- 出力契約を2つ埋め込む（Scope + Decisions）
|
||
- 30-50行
|
||
|
||
### レビュー系（review-*, ai-review）
|
||
|
||
- 目的宣言 + 「〜はレビューしない」の除外指示 + レビュー観点
|
||
- parallel sub-step の場合は短く（5-12行）
|
||
- standalone の場合はイテレーション追跡付き
|
||
|
||
### 修正系（fix, ai-fix, fix-supervisor）
|
||
|
||
- 修正指示 + 必須出力 + 証拠セクション
|
||
- ai-fix は特殊: 「修正済み認識」対策を含む（カスタマイズ不可）
|
||
- fix は「セッションの会話履歴を確認」の指示を含む
|
||
|
||
### 裁定系（arbitrate）
|
||
|
||
- 状況説明 + レポート参照 + 判断基準
|
||
- `{report:filename}` でレビュー結果を展開
|
||
|
||
### 検証系（supervise）
|
||
|
||
- 確認項目 + レポート確認指示 + Validation/Summary 出力契約埋め込み
|
||
- 30-55行
|
||
|
||
---
|
||
|
||
## 共通ルール
|
||
|
||
### 文体
|
||
|
||
- 丁寧語（「〜してください。」）を使用
|
||
- ペルソナ・ポリシーの常体とは異なる
|
||
- エージェントへの指示なので命令調
|
||
|
||
### ファイル命名
|
||
|
||
- `{role}.md` または `{role}-{modifier}.md`
|
||
- 例: `plan.md`, `plan-investigate.md`, `review-arch.md`
|
||
- ハイフン区切り
|
||
- 英語小文字のみ
|
||
|
||
### ファイルサイズ
|
||
|
||
| 種別 | 目安 | 上限 |
|
||
|------|------|------|
|
||
| レビュー sub-step | 5-12行 | 20行 |
|
||
| 計画・修正 | 10-20行 | 30行 |
|
||
| 実装・検証 | 30-50行 | 60行 |
|
||
| ai-fix（特殊） | 35-45行 | 50行 |
|
||
|
||
短いほどよい。冗長な説明は認知負荷を増やす。
|
||
|
||
---
|
||
|
||
## チェックリスト
|
||
|
||
- [ ] 冒頭1-2行で目的が命令形で書かれているか
|
||
- [ ] 自動注入される変数（{task}等）を手動で書いていないか
|
||
- [ ] ペルソナの内容（専門知識、行動姿勢）が混入していないか
|
||
- [ ] ポリシーの内容（共有コーディング原則）が混入していないか
|
||
- [ ] 出力契約埋め込みが```markdownで囲まれているか
|
||
- [ ] 必須出力の見出しが `##` で指定されているか
|
||
- [ ] ファイルパスがハードコードされていないか（`{report:filename}` を使う）
|
||
- [ ] そのムーブメントの手順に集中しているか（ルーティング指示なし）
|