implement_plan

実装計画

thoughts/shared/plans/ にある、承認済みの技術計画を実装します。これらの計画には、具体的な変更と成功基準を含むフェーズがあります。

実行モード

実行モードは 2 つあります。

モード 1：直接実装（デフォルト）

小規模な計画（タスクが 3 つ以下）の場合、またはユーザーが直接実装を依頼した場合に使用します。

• 各フェーズを自分で実装します
• コンテキストはメインの会話に蓄積されます
• 手早く、対象を絞った実装に使用します

モード 2：エージェントオーケストレーション（大規模な計画に推奨）

タスクが 4 つ以上ある計画の場合、またはコンテキストの保持が重要な場合に使用します。

• 薄いオーケストレーターとして動作します
• エージェントが各タスクを実行し、引き継ぎ情報を作成します
• コンパクション耐性があります。コンテキストがコンパクションされても、引き継ぎ情報は保持されます
• 複数フェーズにわたる実装に使用します

エージェントオーケストレーションモードを使用するには、「この計画ではエージェントオーケストレーションを使用します」と伝え、以下の「エージェントオーケストレーション」セクションに従ってください。

---

開始する

計画のパスを受け取ったら、次の手順に従います。

• 計画をすべて読み、既存のチェックマーク（- [x]）がないか確認します
• 元のチケットと、計画で言及されているすべてのファイルを読みます
• ファイルはすべて読み切ってください。limit/offset パラメーターは決して使わず、完全なコンテキストを把握してください
• 各要素がどのように連携するかを十分に検討します
• 進捗を追跡するための todo リストを作成します

実装前のリスク確認

実装を開始する前に、詳細なプレモーテムを実行します。

/premortem deep <plan-path>

これは包括的なチェックリストに照らして計画を分析します。

• 技術的リスク（スケーラビリティ、依存関係、データ、セキュリティ）
• 統合リスク（破壊的変更、移行、ロールバック）
• プロセス上のリスク（要件の不明確さ、関係者からの意見）
• テスト上のリスク（カバレッジの不足、負荷テストの必要性）

重大度が HIGH のリスクが特定された場合：

• AskUserQuestion によってプレモーテムがブロックされます
• ユーザーは、リスクを明示的に受け入れるか、緩和策を追加するか、解決策を調査する必要があります
• 緩和策が追加された場合は、作業を続ける前に計画を更新します

プレモーテムを省略する場合：

• 計画に緩和策を含む「## Risks (Pre-Mortem)」セクションがすでにある場合
• ユーザーが明示的に省略を依頼した場合（--skip-premortem）

プレモーテムに合格したら、作業内容を把握している場合は実装を開始します。

計画のパスが指定されていない場合は、パスを尋ねてください。

実装方針

計画は慎重に作成されていますが、実際の状況は複雑なことがあります。次の方針に従ってください。

• 計画の意図に従いながら、実際に見つかった状況に合わせて調整します
• 次のフェーズに進む前に、各フェーズを完全に実装します
• より広いコードベースの文脈に照らして、作業が妥当であることを確認します
• セクションを完了したら、計画のチェックボックスを更新します

計画と実際の状況が完全には一致しない場合は、その理由を考え、明確に伝えてください。計画は指針ですが、適切な判断を行うことも重要です。

食い違いが見つかった場合：

• 停止して、計画に従えない理由を十分に検討します
• 問題を明確に提示します。

  Issue in Phase [N]:
  Expected: [what the plan says]
  Found: [actual situation]
  Why this matters: [explanation]
  
  How should I proceed?
  

検証方法

フェーズを実装した後：

• 成功基準のチェックを実行します（通常は make check test ですべて確認できます）
• 次に進む前に、問題を修正します
• 計画と todo の両方で進捗を更新します
• Edit を使って、計画ファイル内の完了項目にチェックを付けます
• 人による検証のために一時停止します：あるフェーズの自動検証がすべて完了したら、一時停止し、そのフェーズが手動テスト可能になったことを人に知らせます。次の形式を使用してください。

  Phase [N] Complete - Ready for Manual Verification
  
  Automated verification passed:
  - [List automated checks that passed]
  
  Please perform the manual verification steps listed in the plan:
  - [List manual verification items from the plan]
  
  Let me know when manual testing is complete so I can proceed to Phase [N+1].
  

複数のフェーズを続けて実行するよう指示された場合は、最後のフェーズまで一時停止を省略します。それ以外の場合は、1 つのフェーズだけを実行すると想定します。

ユーザーの確認が得られるまで、手動テストの手順にはチェックを付けないでください。

行き詰まった場合

期待どおりに動作しない場合：

• まず、関連するコードをすべて読み、理解したことを確認します
• 計画の作成後にコードベースが変化していないか検討します
• 食い違いを明確に提示し、指示を求めます

サブタスクは必要最小限にとどめ、主に対象を絞ったデバッグや、不慣れな領域の調査に使用します。

再開可能なエージェント

計画が plan-agent によって作成された場合、確認のために再開できることがあります。

1. .claude/cache/agents/agent-log.jsonl で plan-agent のエントリを確認します
2. agentId フィールドを探します
3. 計画を確認または更新するには：

   Task(
     resume="<agentId>",
     prompt="Phase 2 isn't matching the codebase. Can you clarify..."
   )
   

再開したエージェントは、以前のコンテキスト（調査、コードベースの分析）をすべて保持しています。

再開可能なエージェント：

• plan-agent - 実装計画を作成しました
• oracle - ベストプラクティスを調査しました
• debug-agent - 問題を調査しました

作業の再開

計画に既存のチェックマークがある場合：

• 完了済みの作業は完了しているものとして扱います
• 最初の未チェック項目から再開します
• 何か問題がありそうな場合のみ、以前の作業を検証します

単にチェックボックスを埋めるのではなく、解決策を実装していることを忘れないでください。最終目標を意識し、着実に前進してください。

---

エージェントオーケストレーションモード

大規模な計画（タスクが4つ以上）を実装する場合は、コンテキストの圧縮に耐えられるよう、エージェントオーケストレーションを使用します。

エージェントオーケストレーションを使う理由

問題： 長時間の実装では、コンテキストが蓄積されます。タスクの途中で自動圧縮が開始されると、実装コンテキストが失われます。コンテキストが80%に達した時点で作成された引き継ぎ情報は古くなります。

解決策： 実装をエージェントに委任します。各エージェントは次のことを行います。

• 新しいコンテキストで開始する
• 1つのタスクを実装する
• 完了時に引き継ぎ情報を作成する
• オーケストレーターに戻る

引き継ぎ情報はディスクに保存されます。圧縮が発生した場合は、引き継ぎ情報を読み直して作業を続けます。

セットアップ

1. 引き継ぎディレクトリを作成します：

   mkdir -p thoughts/handoffs/<session-name>
   

   継続性台帳に記載されているセッション名を使用します。

2. 実装エージェントのスキルを読みます：

   cat .claude/skills/implement_task/SKILL.md
   

   これにより、エージェントがどのように動作すべきかが定義されます。

前提条件：計画の検証

実装を始める前に、validate-agent を使用して計画が検証されていることを確認します。検証は独立したステップであり、ステータスが VALIDATED の引き継ぎ情報が作成されているはずです。

検証の引き継ぎ情報を確認します：

ls thoughts/handoffs/<session>/validation-*.md

検証情報がない場合は、先に検証を実行するよう提案します：

"This plan hasn't been validated yet. Would you like me to spawn validate-agent first?"

検証情報はあるものの、ステータスが NEEDS REVIEW の場合は、続行する前に問題点を提示します。

オーケストレーションのループ

計画内の各タスクについて、次の手順を実行します。

1. エージェントのコンテキストを準備します：

   • 継続性台帳を読みます（現在の状態）
   • 計画を読みます（全体的なコンテキスト）
   • 以前の引き継ぎ情報があれば読みます（thoughts/handoffs// 内）
   • 対象のタスクを特定します

2. 実装エージェントを起動します：

   Task(
     subagent_type="general-purpose",
     model="claude-opus-4-5-20251101",
     prompt="""
     [Paste contents of .claude/skills/implement_task/SKILL.md here]
   
     ---
   
     ## Your Context
   
     ### Continuity Ledger:
     [Paste ledger content]
   
     ### Plan:
     [Paste relevant plan section or full plan]
   
     ### Your Task:
     Task [N] of [Total]: [Task description from plan]
   
     ### Previous Handoff:
     [Paste previous task's handoff content, or "This is the first task - no previous handoff"]
   
     ### Handoff Directory:
     thoughts/handoffs/<session-name>/
   
     ### Handoff Filename:
     task-[NN]-[short-description].md
   
     ---
   
     Implement your task and create your handoff.
     """
   )
   

3. エージェントの結果を処理します：

   • エージェントの引き継ぎファイルを読みます
   • 台帳のチェックボックスを更新します：[x] Task N
   • 該当する場合は計画のチェックボックスも更新します
   • 次のタスクに進みます

4. エージェントが失敗した場合／ブロッカーが発生した場合：

   • 引き継ぎ情報を読みます（ステータスは「blocked」になります）
   • ブロッカーをユーザーに提示します
   • 再試行、スキップ、またはユーザーへの確認のいずれかを決定します

圧縮後の復旧

オーケストレーションの途中で自動圧縮が発生した場合：

1. 継続性台帳を読みます（SessionStart フックによって読み込まれます）
2. 引き継ぎディレクトリの一覧を表示します：

   ls -la thoughts/handoffs/<session-name>/
   

3. 最後の引き継ぎ情報を読み、どこまで進んでいたかを把握します
4. 次の未完了タスクからエージェントの起動を続けます

オーケストレーションセッションの例

User: /implement_plan thoughts/shared/plans/PLAN-add-auth.md

Claude: I'll use agent orchestration for this plan (6 tasks).

Setting up handoff directory...
[Creates thoughts/handoffs/add-auth/]

Task 1 of 6: Create user model
[Spawns agent with full context]
[Agent completes, creates task-01-user-model.md]

✅ Task 1 complete. Handoff: thoughts/handoffs/add-auth/task-01-user-model.md

Task 2 of 6: Add authentication middleware
[Spawns agent with previous handoff]
[Agent completes, creates task-02-auth-middleware.md]

✅ Task 2 complete. Handoff: thoughts/handoffs/add-auth/task-02-auth-middleware.md

--- AUTO COMPACT HAPPENS ---
[Context compressed, but handoffs persist]

Claude: [Reads ledger, sees tasks 1-2 done]
[Reads last handoff task-02-auth-middleware.md]

Resuming from Task 3 of 6: Create login endpoint
[Spawns agent]
...

引き継ぎチェーン

各エージェントは前の引き継ぎ情報を読み、作業を行い、次の引き継ぎ情報を作成します。

task-01-user-model.md
    ↓ (read by agent 2)
task-02-auth-middleware.md
    ↓ (read by agent 3)
task-03-login-endpoint.md
    ↓ (read by agent 4)
...

このチェーンにより、圧縮が発生してもコンテキストが維持されます。

エージェントオーケストレーションを使う場面

シナリオ	モード
簡単なタスクが1～3件	直接実装
タスクが4件以上	エージェントオーケストレーション
重要なコンテキストを維持する必要がある	エージェントオーケストレーション
簡単なバグ修正	直接実装
大規模な機能の実装	エージェントオーケストレーション
ユーザーが明示的に依頼した場合	ユーザーの希望を尊重

ヒント

• オーケストレーターは軽量に保つ： 自分で実装作業をしないでください。エージェントの管理だけを行います。
• 引き継ぎ情報を活用する： エージェントは詳細な引き継ぎ情報を作成します。コンテキストの把握に活用してください。
• タスクごとにエージェントを1つ使う： 複数のタスクを1つのエージェントにまとめないでください。
• 逐次実行する： まずは逐次実行から始めます。並列実行は複雑さを増します。
• 台帳を更新する： 各タスクの完了後に、継続性台帳のチェックボックスを更新します。