agent-bot/takt
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
takt/builtins/ja/INSTRUCTION_STYLE_GUIDE.md

11 KiB
Raw Blame History

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

このガイドは 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行で何をすべきかを簡潔に記述
  • 命令形（「〜してください。」）を使用
# 良い例
タスクを分析し、実装方針を立ててください。

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

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

注意事項・条件

  • 差し戻し、イテレーション回数、前提条件がある場合に記述
  • **注意:** または **重要:** の太字ラベルで強調
# 良い例
**注意:** 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/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} を使う）
  • そのムーブメントの手順に集中しているか（ルーティング指示なし）