Back to Details

agentic-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agentic Workflow Pattern

Agentic工作流模式

Standard multi-agent pipeline for implementation tasks.
适用于实施任务的标准多智能体流水线。

Architecture Principles

架构原则

  • Use 
    run_in_background: true
    for all agents to keep main context minimal
  • Use 
    Task
    tool (never 
    TaskOutput
    ) to avoid receiving full agent transcripts
  • Agents write outputs to 
    .claude/cache/agents/<stage>/
    for injection into subsequent agents
  • Main conversation is pure orchestration — no heavy lifting, only coordination
  • 所有Agent均使用
    run_in_background: true
    ，以保持主上下文简洁
  • 使用
    Task
    工具（绝不要用
    TaskOutput
    ），避免接收完整的智能体对话记录
  • 智能体将输出写入
    .claude/cache/agents/<stage>/
    ，以便注入到后续智能体中
  • 主对话仅负责编排——不处理繁重任务，仅进行协调

Workflow Stages

工作流阶段

1. Research Agent

1. 调研Agent

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
""")
  • Enforce NIA as the research layer
  • Output: Research findings
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. Planning Agent

2. 规划Agent

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
""")
  • Receives: Research agent output as context
  • Output: Implementation plan
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
""")
  • 接收：调研Agent的输出作为上下文
  • 输出：实施计划

3. Validation Agent

3. 验证Agent

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
""")
  • Reviews plan against research
  • Output: Validated plan with amendments
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. Implementation Agent

4. 实施Agent

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
""")
  • Receives: Validated plan + research context
  • TDD: Failing tests first
  • Output: Implementation + tests
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. Review Agent

5. 审核Agent

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
""")
  • Cross-references all artifacts
  • Confirms tests pass
  • Output: Review summary
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
""")
  • 交叉引用所有工件
  • 确认测试通过
  • 输出：审核总结

Agent Progress Monitoring

Agent进度监控

bash
undefined
bash
undefined

Watch for system reminders:

Watch for system reminders:

"Agent a42a16e progress: 6 new tools used, 88914 new tokens"

"Agent a42a16e progress: 6 new tools used, 88914 new tokens"

Poll for output files:

Poll for output files:

find .claude/cache/agents -name "*.md" -mmin -5
find .claude/cache/agents -name "*.md" -mmin -5

Check task file size growth:

Check task file size growth:

wc -c /tmp/claude/.../tasks/<id>.output

**Stuck detection:**
1. Progress reminders stop arriving
2. Task output file size stops growing
3. Expected output file not created after reasonable time
wc -c /tmp/claude/.../tasks/<id>.output

**停滞检测:**
1. 进度提醒停止推送
2. 任务输出文件大小停止增长
3. 在合理时间内未生成预期的输出文件

Directory Structure

目录结构

.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
.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

Key Rules

核心规则

  1. Never use TaskOutput - floods context with 70k+ token transcripts
  2. Always run_in_background=true - isolates agent context
  3. File-based handoff - each agent reads previous agent's output file
  4. Poll, don't block - check file system for outputs, don't wait
  5. TDD in implementation - failing tests first, then make them pass
  1. 绝不要使用TaskOutput - 会使上下文充斥70k+的token对话记录
  2. 始终设置run_in_background=true - 隔离智能体上下文
  3. 基于文件的交接 - 每个智能体读取前一个智能体的输出文件
  4. 轮询，不要阻塞 - 检查文件系统获取输出，不要等待
  5. 实施阶段采用TDD - 先编写失败的测试用例，再使其通过

Source

来源

  • Session 2026-01-01: SDK Phase 3 implementation using this pattern
  • 2026-01-01会话：使用该模式的SDK第三阶段实施