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

このガイドは `instructions/` のファイルを作成・編集する際のルールを定義する。

## 参照元

`facets/instructions/` を参照元として使う。新規作成時は既存ファイルを参照して使う。

| 参照ファイル | 用途 |
|------------|------|
| `plan.md` | 計画（タスク分析・要件整理） |
| `architect.md` | 設計（アーキテクチャ設計） |
| `implement.md` | 実装（コーディング + レポート埋め込み） |
| `review-ai.md` | AIレビュー（parallel sub-step 汎用） |
| `ai-fix.md` | AI指摘修正（全ワークフロー共通） |
| `fix.md` | レビュー指摘修正（汎用 fix / supervise fix） |
| `arbitrate.md` | 裁定（レビュアー vs コーダー） |
| `supervise.md` | 最終検証（レポート埋め込み） |

---

## インストラクションとは

ワークフローのステップで実行する具体的な手順。`instruction` フィールドでファイル参照するか、インラインで直接記述する。

| 項目 | 内容 |
|------|------|
| 目的 | ステップの実行手順と出力要件の定義 |
| 配置 | Phase 1 メッセージの `## Instructions`（`{{instructions}}`） |
| 対象 | 1つのステップ |
| 判断基準 | 「この手順は特定のステップ/ワークフローに固有か？」→ YES |

探索を伴うステップでは、開始点、探索順、範囲を広げる条件、停止条件もインストラクションに置く。どの基準を適用して finding や編集を許可するかはポリシー、判断に必要なドメイン知識はナレッジの責務である。

共有インストラクションは、特定のポリシー名・ナレッジ名や、それらが必ず注入される組成を前提にしない。別facetの判断が必要ならworkflow YAMLからそのfacetを同じstepへ合成し、instruction本文には実際に行う操作と確認する事実だけを書く。「適用されるポリシーを使う」のように別facetを逆引きさせない。

自動注入される共通制約を、`workflow rule`、`Workflow-wide rule`、`shared workflow rules` などの内部機構名で参照しない。ステップ固有の手順は実際の操作と適用条件を直接記述し、共通の判断基準を instruction に再掲しない。

共通メッセージには、workflow YAML が選んだ判断基準と参考資料の本文が展開される。個別 instruction はその組成や読み込み手順を説明せず、元要件、変更契約、実在経路に対して実際に行う調査・判断・作業だけを記述する。参照資料の一部だけを使わせる必要がある場合も、内部の分類値を作らず、対象となる条件を通常の技術用語で直接示す。

### 実際の配置先

インストラクションは `src/shared/prompts/{lang}/perform_phase1_message.md` の `{{instructions}}` に展開される。

```
## 実行コンテキスト（作業ディレクトリ）
## 実行ルール（git commit禁止、cd禁止、edit権限）
## Workflow Context（ワークフロー名、Iteration、Step Iteration、Report Directory）
## User Request（自動注入）
## Previous Response（自動注入、pass_previous_response: true 時）
## Additional User Inputs（自動注入）
## Instructions
{{instructions}}  ← ★ インストラクションがここに展開される
```

インストラクションの前に実行コンテキスト、ワークフロー情報、ユーザーリクエスト、前回レスポンス等が既に提供されている。これらを再記述する必要はない。

### ペルソナ・ポリシーとの分離

```
この内容は…
├── エージェントの identity・専門性・責任境界 → ペルソナ
├── 複数エージェントの共有ルール → ポリシー
└── ステップ固有の手順・出力形式 → インストラクション
```

---

## エンジンの自動注入

2つのメカニズムがある。いずれもインストラクション内に手動で記述する必要はない。

### セクション注入（`## Instructions` の前に別セクションとして挿入）

`perform_phase1_message.md` 側で処理される。`instruction` の外に配置される。

| セクション | 内容 | デフォルト |
|-----------|------|-----------|
| `## User Request` | ユーザーの元リクエスト | **常に表示** |
| `## Previous Response` | 前ステップの出力 | **初回以外は常に表示**（`pass_previous_response` デフォルト: `true`） |
| `## Additional User Inputs` | 蓄積されたユーザー入力 | **常に表示** |

抑制したい場合は `instruction` 内にプレースホルダー（`{task}`, `{previous_response}`, `{user_inputs}`）を含めるか、`pass_previous_response: false` を設定する。通常は不要。自動注入では位置を制御できず、一次情報を特定位置へ置く必要がある場合だけ、対応するプレースホルダーを明示してよい。

### テンプレート変数展開（`instruction` 内のプレースホルダーを置換）

InstructionBuilder が `instruction` 内の `{変数名}` を展開する。インストラクション内で使用可能。

| 変数 | 内容 |
|------|------|
| `{iteration}` | ワークフロー全体のイテレーション数 |
| `{max_steps}` | 最大イテレーション数 |
| `{step_iteration}` | step 単位のイテレーション数 |
| `{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）。

# 良い例（イテレーション追跡）
**これは {step_iteration} 回目の AI Review です。**
2回目以降は、前回の修正が実際には行われていなかったということです。
```

### やること

- 番号付きリストまたは箇条書きで手順/観点を列挙
- レビュー系は「レビュー観点」としてまとめる

```markdown
# 実行系（番号付きリスト）
**やること:**
1. タスクの要件を理解する
2. 影響範囲を特定する
3. 実装アプローチを決める

# レビュー系（箇条書き）
**レビュー観点:**
- 構造・設計の妥当性
- コード品質
- テストカバレッジ
```

### 探索の設計

- 変更契約、変更境界、定義と参照を探索の開始点にする
- 所有者が不明、新しい境界、同じ契約の別実装、前提を反証する証拠がある場合は、必要に応じてリポジトリ全体へ意味ベースの検索を広げる
- 確認した経路を `変更対象 / 維持対象 / 対象外` に分類し、適用可能な基準を確認できたら探索を止める
- 注入された Policy / Knowledge は共通手順で全文確認する一方、リポジトリの全ファイル・全入口の列挙自体は目的にしない。広く読んだことは finding や編集範囲を広げる許可にならない

### 出力契約埋め込み

- インストラクション内に出力契約を埋め込む場合がある
- コードブロック（```markdown）で囲む
- ラベル（`**Scope出力契約:**` 等）を付ける

```markdown
# 良い例
**Scope出力契約（実装開始時に作成）:**
\`\`\`markdown
# 変更スコープ宣言
...
\`\`\`
```

### 必須出力

- `**必須出力（見出しを含める）**` の見出しで出力要件を定義
- 見出しは `##` で指定（エージェントの出力にそのまま使われる）
- `- {プレースホルダー}` で各項目の説明

```markdown
**必須出力（見出しを含める）**
## 作業結果
- {実施内容の要約}
## 変更内容
- {変更内容の要約}
## テスト結果
- {実行コマンドと結果}
```

---

## DO / DON'T

| DO | DON'T |
|----|-------|
| 目的を冒頭1-2行で命令形で書く | 長い説明文で始める |
| 手順を番号付きリストで列挙 | 曖昧な指示を出す |
| テンプレート変数を正しく使う | 自動注入される変数を手動で書く |
| 出力契約は```markdownで囲む | プレーンテキストで出力契約を書く |
| 必須出力の見出しを `##` で指定 | 出力形式を指定しない |
| そのステップの手順に集中 | ペルソナ（identity・専門性・責任境界）の内容を混ぜる |
| `{report:filename}` でレポートを参照 | ファイルパスをハードコードする |
| 必要なfacetはworkflow YAMLで合成する | 本文からpolicy・knowledge・facet・Phaseなどの組成を参照させる |
| workflow固有手順は専用instructionとして配列合成する | 汎用instructionへ初回・後続・routingなどの固有手順を混ぜる |

---

## インストラクションに書いてはいけないもの

1. **ペルソナの内容**: エージェントの identity、専門性、責任境界、行動姿勢
2. **ポリシーの内容**: DRY、Fail Fast 等の共有コーディング原則
3. **ナレッジの判定基準・パターン**: 観点リスト、判定基準テーブル、コード例
4. **自動注入される内容**: 通常は `{task}`, `{previous_response}` のプレースホルダーを明示的に書かない。位置制御または一次情報の明示配置が必要な場合のみ例外とする
5. **他のステップ名の直接参照**: 「implement ステップに戻る」等（ルーティングはルール定義の責務）
6. **ワークフロー固有のルーティング**: 「APPROVE なら次へ」等（ルール条件の責務）
7. **共有先で保証されない組成依存**: 特定のポリシー名・ナレッジ名、そのfacetの存在、特定workflowだけが提供する変数を前提にする記述
8. **メタ指示**: `適用 policy`、`include 済み`、`この instruction`、`後続 Phase`、`selector`など、実行時の事実ではなくプロンプト構成を参照させる記述
9. **汎用手順へのworkflow固有条件の混在**: 初回・後続、特定ラウンド、特定の提出元、遷移条件などを共有instructionへ埋め込む記述

### workflow固有手順の合成

汎用手順とworkflow固有手順の両方が必要なstepでは、別々のinstruction facetとして定義し、workflow YAMLで順序付き配列にする。

```yaml
instruction:
  - review-contract-paths
  - review-after-remediation
```

配列の各facetは単独の責務を持ち、同じ判断規則や手順を重複させない。状態遷移や分岐条件は`rules`へ置き、専用instructionにも書かない。

親workflowの`all_steps.rules`はworkflow callの子へ継承される。特定の役割だけが必要とする規則は、その役割を実行する最小のworkflowへ置く。通常のreviewerに裁定・修正台帳・最終確認の語彙を読ませない。

### レビュー系インストラクションでの観点列挙の禁止

レビュー系（review-*, ai-antipattern-review, audit-*-review）の instruction で「**レビュー観点:**」「**チェック項目:**」のような観点リストを列挙してはならない。

理由:
- 観点・判定基準は対応する Knowledge / Policy に既に揃っている
- instruction に観点を抜粋すると、policy / knowledge に章を追加しても instruction に反映されず drift する
- AI が観点リストを「許可リスト」として扱い、Knowledge / Policy 全章の他観点を見落とす

正しい書き方:

```markdown
# 良い例（フォーカス領域と探索条件を示し、判定基準は policy / knowledge に委ねる）
**アーキテクチャと設計**のレビューに集中してください。
共通手順で全文確認した Knowledge / Policy のうち、変更契約へ適用される基準を使って定義・参照から探索を始めてください。
所有者が不明、新しい境界、反証となる証拠がある場合にコード探索を広げ、非適用の章を機械的に finding へ変換しないでください。
```

```markdown
# 悪い例（観点を列挙して許可リスト化）
**レビュー観点:**
- 構造・設計の妥当性
- モジュール化（高凝集・低結合・循環依存）
- コード品質
- デッドコード
- ...
```

並列レビューで複数の reviewer を差別化するための「フォーカス領域」は 1 行のヒントに留める。詳細な観点・基準は Knowledge / Policy に置く。

### 共通手順の重複禁止

複数の instruction に同一の手順ブロック（「前回指摘の追跡」「設計判断の参照」など）が必要な場合は、共通 instruction partial へ集約する。手順を policy や persona へ移さず、同じ手順を複数箇所へ転記しない。

### 例外: レポート参照

`{report:filename}` を使ったレポート内容の展開は許容する。これはワークフロー固有の概念だが、インストラクションの中核機能。

```markdown
# 許容
**参照するレポート:**
- AIレビュー結果: {report:ai-antipattern-review.md}

# 非許容
**参照するレポート:**
- .takt/runs/20250101-task/reports/ai-antipattern-review.md  ← パスのハードコード
```

---

## カテゴリ別パターン

### 計画系（plan, plan-investigate, architect）

- 目的宣言 + やること（番号付き） + replan 注意事項
- 出力契約埋め込みなし（出力契約は output-contracts/ に分離）

### 実装系（implement）

- 目的宣言 + テスト要件 + Scope/Decisions 出力契約埋め込み + 必須出力
- 出力契約を2つ埋め込む（Scope + Decisions）

### レビュー系（review-*, ai-review）

- 目的宣言 + フォーカス領域 + 探索の開始・拡張・停止条件
- parallel sub-step は共有の探索手順を partial で再利用し、固有部分をフォーカス領域に限定する
- standalone の場合はイテレーション追跡付き

### 修正系（fix, ai-fix, fix-supervisor）

- 修正指示 + 必須出力 + 証拠セクション
- ai-fix は特殊: 「修正済み認識」対策を含む（カスタマイズ不可）
- fix は「セッションの会話履歴を確認」の指示を含む

### 裁定系（arbitrate）

- 状況説明 + レポート参照 + 判断基準
- `{report:filename}` でレビュー結果を展開

### 検証系（supervise）

- 確認項目 + レポート確認指示 + Validation/Summary 出力契約埋め込み

---

## 共通ルール

### 文体

- 丁寧語（「〜してください。」）を使用
- ペルソナ・ポリシーの常体とは異なる
- エージェントへの指示なので命令調

### ファイル命名

- `{role}.md` または `{role}-{modifier}.md`
  - 例: `plan.md`, `plan-investigate.md`, `review-arch.md`
- ハイフン区切り
- 英語小文字のみ

### 長さ

必要な手順と例外だけを残し、同じ判断規則や探索手順の言い換えを重ねない。行数で合否を決めず、責務が混在する場合は適切なfacetまたは共通partialへ分離する。

---

## チェックリスト

- [ ] 冒頭1-2行で目的が命令形で書かれているか
- [ ] 自動注入される変数（{task}等）を手動で書いていないか
- [ ] 自動注入される共通制約を内部機構名で参照せず、必要な手順を直接記述しているか
- [ ] 共有インストラクションが特定のfacet名や注入構成を前提にしていないか
- [ ] policy・knowledge・facet・Phase・selectorなどを逆引きさせるメタ指示がないか
- [ ] workflow固有手順を汎用instructionへ混ぜず、専用instructionとしてworkflow YAMLで配列合成しているか
- [ ] ペルソナの内容（identity、専門性、責任境界、行動姿勢）が混入していないか
- [ ] ポリシーの内容（共有コーディング原則）が混入していないか
- [ ] 出力契約埋め込みが```markdownで囲まれているか
- [ ] 必須出力の見出しが `##` で指定されているか
- [ ] ファイルパスがハードコードされていないか（`{report:filename}` を使う）
- [ ] そのステップの手順に集中しているか（ルーティング指示なし）