takt/builtins/ja/INSTRUCTION_STYLE_GUIDE.md

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

このガイドは 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行で何をすべきかを簡潔に記述
• 命令形（「〜してください。」）を使用

# 良い例
タスクを分析し、実装方針を立ててください。

# 良い例
テスト実行、ビルド確認、最終承認を行ってください。

# 悪い例
このムーブメントではタスクの分析を行います。  ← 説明文になっている

注意事項・条件

• 差し戻し、イテレーション回数、前提条件がある場合に記述
• **注意:** または **重要:** の太字ラベルで強調

# 良い例
**注意:** Previous Responseがある場合は差し戻しのため、
その内容を踏まえて計画を見直してください（replan）。

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

やること

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

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

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

レポートフォーマット埋め込み

• インストラクション内にレポートフォーマットを埋め込む場合がある
• コードブロック（```markdown）で囲む
• ラベル（**Scopeレポートフォーマット:** 等）を付ける

# 良い例
**Scopeレポートフォーマット（実装開始時に作成）:**
\`\`\`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} を使ったレポート内容の展開は許容する。これはピース固有の概念だが、インストラクションの中核機能。

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

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

---

カテゴリ別パターン

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

• 目的宣言 + やること（番号付き） + replan 注意事項
• レポートフォーマット埋め込みなし（レポートは report-formats/ に分離）
• 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} を使う）
• そのムーブメントの手順に集中しているか（ルーティング指示なし）