agentic-workflow

エージェント型ワークフローパターン

実装タスク向けの標準的なマルチエージェントパイプラインです。

アーキテクチャの原則

• メインコンテキストを最小限に保つため、すべてのエージェントで run_in_background: true を使用します
• エージェントの全トランスクリプトを受け取らないよう、Task ツールを使用します（TaskOutput は使用しないでください）
• 後続のエージェントに渡すため、エージェントは .claude/cache/agents/<stage>/ に出力を書き込みます
• メインの会話はオーケストレーションに専念し、重い作業は行わず、調整のみを行います

ワークフローの各段階

1. 調査エージェント

Task(subagent_type="oracle", run_in_background=true, prompt="""
Query NIA Oracle (via /nia-docs skill) to verify approach and gather best practices.

Output to: .claude/cache/agents/oracle/<task>-research.md
""")

• 調査レイヤーとして NIA を必ず使用します
• 出力：調査結果

2. 計画エージェント

Task(subagent_type="plan-agent", run_in_background=true, prompt="""
Read: .claude/cache/agents/oracle/<task>-research.md
Use RP-CLI to analyze the target codebase section.
Generate implementation plan informed by research.

Output to: .claude/cache/agents/plan-agent/<task>-plan.md
""")

• 受け取るもの：コンテキストとしての調査エージェントの出力
• 出力：実装計画

3. 検証エージェント

Task(subagent_type="validate-agent", run_in_background=true, prompt="""
Read: .claude/cache/agents/plan-agent/<task>-plan.md
Read: .claude/cache/agents/oracle/<task>-research.md
Review plan against research findings and best practices.

Output to: .claude/cache/agents/validate-agent/<task>-validated.md
""")

• 調査結果に照らして計画をレビューします
• 出力：修正を加えた検証済み計画

4. 実装エージェント

Task(subagent_type="agentica-agent", run_in_background=true, prompt="""
Read: .claude/cache/agents/validate-agent/<task>-validated.md
Read: .claude/cache/agents/oracle/<task>-research.md

TDD approach: Write failing tests FIRST, then implement.
Run tests to verify.

Output summary to: .claude/cache/agents/implement-agent/<task>-implementation.md
""")

• 受け取るもの：検証済み計画と調査コンテキスト
• TDD：まず失敗するテストを作成します
• 出力：実装とテスト

5. レビューエージェント

Task(subagent_type="review-agent", run_in_background=true, prompt="""
Read: .claude/cache/agents/implement-agent/<task>-implementation.md
Read: .claude/cache/agents/validate-agent/<task>-validated.md
Read: .claude/cache/agents/oracle/<task>-research.md

Cross-reference implementation against plan and research.
Run tests to confirm passing.

Output to: .claude/cache/agents/review-agent/<task>-review.md
""")

• すべての成果物を相互参照します
• テストが合格することを確認します
• 出力：レビューの概要

エージェントの進捗状況の監視

# Watch for system reminders:
# "Agent a42a16e progress: 6 new tools used, 88914 new tokens"

# Poll for output files:
find .claude/cache/agents -name "*.md" -mmin -5

# Check task file size growth:
wc -c /tmp/claude/.../tasks/<id>.output

停止状態の検知：

1. 進捗通知が届かなくなる
2. タスク出力ファイルのサイズが増えなくなる
3. 妥当な時間が経過しても、期待される出力ファイルが作成されない

ディレクトリ構造

.claude/cache/agents/
├── oracle/
│   └── <task>-research.md
├── plan-agent/
│   └── <task>-plan.md
├── validate-agent/
│   └── <task>-validated.md
├── implement-agent/
│   └── <task>-implementation.md
└── review-agent/
    └── <task>-review.md

主なルール

1. TaskOutput は絶対に使用しない - 70k 以上のトークンを含むトランスクリプトでコンテキストがあふれます
2. 常に run_in_background=true を使用する - エージェントのコンテキストを分離します
3. ファイルベースで受け渡す - 各エージェントは前のエージェントの出力ファイルを読み取ります
4. ブロックせず、ポーリングする - 出力を待つのではなく、ファイルシステムを確認します
5. 実装では TDD を行う - まず失敗するテストを作成し、その後で合格させます

出典

• セッション 2026-01-01：このパターンを使用した SDK Phase 3 の実装