agent-design

Agent 设计涵盖构建高性能 AI Agent 背后的架构决策：工作流与 Agent 的区别（代码编排与 LLM 指挥控制）、Agent 的最小结构（身份、能力、工具、约束、工作流），以及“全新视角”原则——每个子 Agent 只获取所需的上下文，绝不获取编排器的完整历史记录。

根据任务，它会指向四份参考文档：patterns.md 用于选择架构（单 Agent、编排器、流水线、网络、监督者、分层、元提示）；workflows.md 用于在 Agent 中实现 APEX/TDD/Explore-Plan-Code/Review/Debug 模式；templates.md 提供完整的生产级 frontmatter 和 Claude Code Agent 模板；anti-patterns.md 用于根据常见错误审查设计。

Agent 设计

用于按照 2025 年模式设计高性能 AI Agent 的技能。

参考文档

• patterns.md - 在选择 Agent 架构（单 Agent、Agent+工具、编排器、流水线、网络、监督者、分层、元提示）或比较其权衡时加载
• workflows.md - 在为 Agent 实现 APEX、TDD、Explore-Plan-Code、代码审查或调试工作流时加载
• templates.md - 在编写完整的 Agent 定义（生产级 frontmatter + 各章节）或 Claude Code Agent 模板时加载
• anti-patterns.md - 在审查 Agent 设计中的常见错误（全知 Agent、隐式指令、缺少错误处理）时加载

基本区别

工作流与 Agent

类型	控制方式	适用场景
工作流	代码编排 LLM	可预测的任务，需要控制
Agent	LLM 指挥其行动	需要灵活性和适应性决策

黄金法则： 从简单开始，必要时再增加复杂性。

Agent 的最小结构

Agent:
  identity: Who am I?
  capabilities: What can I do?
  tools: What tools do I have?
  constraints: What are my limits?
  workflow: How should I proceed?

完整的生产级结构和 Claude Code Agent 模板，请参阅 templates.md。

全新视角原则

2025 年关键概念： 每个子 Agent 都必须拥有“全新”的上下文。

❌ Bad: Pass entire history to each sub-agent
✅ Good: Give only necessary information

Orchestrator:
  - Keeps complete history
  - Extracts relevant context for each sub-agent
  - Synthesizes results

设计检查清单

创建 Agent 之前

• 目标是否明确？
• 简单的工作流是否足够？
• 需要哪些工具？
• 需要哪些防护措施？

设计期间

• 身份是否定义清晰？
• 工作流是否明确？
• 是否处理了错误情况？
• 示例是否相关？

创建之后

• 是否测试了标准情况？
• 是否测试了边缘情况？
• 是否进行了安全测试（越狱）？
• 性能是否可接受？

设计时应避免的反模式，请参阅 anti-patterns.md。

禁止事项

• 绝不创建没有明确工作流的 Agent
• 绝不在没有必要时授予对所有工具的访问权限
• 绝不忽视最小权限原则
• 绝不忘记安全防护措施