# インストラクション スタイルガイド

このガイドは `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_iterations}` | 最大イテレーション数 |
| `{movement_iteration}` | ムーブメント単位のイテレーション数 |
| `{report_dir}` | レポートディレクトリ名 |
| `{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/reports/20250101-task/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}` を使う）
- [ ] そのムーブメントの手順に集中しているか（ルーティング指示なし）