关于 design-agentic-architecture
将具体需求整理为 Agent 架构设计文档的技能。它从单 Agent 基线出发，仅在证据支持时增加复杂度，并涵盖持久状态、人工监督、评估和实时工具调研。
主要功能
- 01评估用例与风险
- 02依据证据逐级选择架构
- 03规划持久状态与记忆
- 04按操作设置人工审核关卡
- 05跟踪并评估各步骤表现
- 06实时调研工具并生成设计文档
适用场景
- 01为新 Agent 选择架构
- 02规划状态持久化、记忆与恢复
- 03为高风险或不可逆操作制定监督机制
- 04记录 Agent 评估与可观测性方案
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/design-agentic-architecture确认已加载。
附带文件DESIGN-DOC-TEMPLATE.mdPRINCIPLES.md
详细介绍
设计 Agentic 架构
Agentic 复杂性是一项需要逐步削减的成本，而不是一开始就默认采用的方案。这项技能会基于持久状态，将用例转化为一份设计文档：根据证据逐级攀登阶梯，只有在需求迫使你增加结构时才添加，并且仅在确有必要时接入记忆、人在回路和可观测性。
架构规则有研究依据，截至 2026 年年中，收录于 PRINCIPLES.md——设计时请查阅。工具会进行实时检查（第 7 步），因为它们很快就会过时；切勿凭记忆推荐工具。输出遵循 DESIGN-DOC-TEMPLATE.md。
请按顺序完成各步骤。每一步都有完成标准——达标之前不要进入下一步。
1. 明确用例
记录目标（一句话）、Agent 可以执行的每一项操作（读取或写入／不可逆）、风险概况（不可逆性、影响范围、合规性）、预期规模、对延迟／成本的敏感度，以及定价模式（按量计费的 API 或固定订阅——它决定成本因素的影响有多大，也决定在攀登阶梯前优化的力度）。如果目标含糊不清，请先访谈用户再进行设计——模糊的用例会导致设计空泛无用。
**完成标准：**能够用一句话陈述目标，列出每项操作并标记为读取或写入，同时记录风险概况、预期规模、对延迟／成本的敏感度和定价模式。
2. 根据证据攀登阶梯
从第 1 阶（单 Agent + 类型化、经过验证的工具）开始。只有存在未满足的需求时才增加阶层：正确性 → 反思（使用独立的审查者），结构 → 有界规划，适应性 → ReAct，严格的组织边界 → 多 Agent。选择满足需求的最低阶层。攀登之前，先穷尽单 Agent 优化手段——提示词、检索、缓存、上下文工程（筛选／压缩／卸载）、升级模型；上下文窗口溢出或内容陈旧，意味着应当先修复上下文，而不是增加阶层。多 Agent 是最后手段（Token 用量增加 4–220 倍、交接延迟、调试困难），且只用于满足边界需求——不能仅为并行而采用。如果使用多 Agent，请执行单写入者规则：一个协调者负责整个计划和所有写入；子 Agent 只返回信息和完整轨迹，不执行操作。
**完成标准：**明确选定的阶层及其具体理由（或说明第 1 阶已足够），并且在攀登之前已穷尽包括上下文工程在内的单 Agent 优化手段。
3. 奠定持久状态基础
首先确定检查点／持久化执行方案——记忆、HITL、长时间运行和可回放轨迹都建立在这个共用基础之上。事后补上会很麻烦。通过检查点或交接传递的内容，通常是上下文的压缩版（摘要、笔记文件或交接简报），而非原始对话记录——持久化上下文并将其控制在预算范围内（第 4 步），是同一个问题的两个方面。
**完成标准：**设计说明运行状态如何持久化和恢复。
4. 安排记忆
从上下文内开始，但要把窗口视为一项预算，并把握合适的使用范围——在考虑扩大窗口或使用外部记忆之前，先对持久事实进行筛选、压缩（删减／总结）和卸载。只有在 Token 成本或窗口限制确实造成影响时，才添加外部记忆。默认选择 RAG／向量方案；只有在关系或随时间变化的情况很重要时，才考虑知识图谱。更大的上下文并不是记忆策略（长上下文模型在对抗性回忆任务中会退化并产生幻觉）。如有需要，可以购买写入路径——但不要轻信供应商的基准测试。
**完成标准：**为 Agent 需要的每类知识分配一个层级（上下文内或外部），并说明理由，同时写明上下文预算计划（筛选／压缩／卸载）。
5. 在适当位置引入人工参与
仅当预期错误成本 > 审核延迟成本时，才对操作设置关卡。根据不可逆性、影响范围、合规性和置信度为每项操作评分——但绝不能依据模型的原始置信度升级处理（LLM 往往过度自信）；应结合信任度与风险。在链路边界设置少量异步关卡，绝不要在每个步骤都设关卡，否则会导致橡皮图章式审批。监督应按操作调整（在回路内／在回路上／在回路外），而非采用全局模式。
**完成标准：**每项写入／高风险操作都有明确的关卡决策，常规操作则留在回路外。
6. 衡量中间过程
Agentic 系统会在中间过程中出错。采用 OpenTelemetry GenAI 约定进行埋点；在步骤级评估执行轨迹（工具调用准确性、检索依据充分性、交接质量），而不只是最终答案；形成闭环（生产追踪 → 评估数据集 → CI）。对于多 Agent 系统，使用 MAST 归因故障。
**完成标准：**设计中明确说明要追踪和评估哪些步骤级指标，以及端到端检查。
7. 推荐工具——实时搜索
工具迭代很快，因此应针对各项能力（编排、持久化执行／HITL、记忆、可观测性／评估）实时搜索当前选项——不要凭记忆列出工具。提供全景介绍，而非排名：研究中没有找到经过验证的正面比较赢家，而且各框架提供的基础能力相同。指出两个有证据支持的基准方案（OpenTelemetry、MAST）。始终提供自建还是购买的选项（组合各领域最佳方案，或采用互联的一体化生态）。自建与购买的判断方法见 PRINCIPLES.md。
**完成标准：**每项能力至少列出一个当前工具，注明每次搜索的日期，并说明不排名的原因。
8. 撰写文档并执行虚假信心检查
填写 DESIGN-DOC-TEMPLATE.md 并保存（默认路径为 ./agentic-architecture-design.md，除非用户指定路径）。注明**“截至 2026 年年中提供的架构指导；工具搜索日期：。”然后执行虚假信心检查**：依据 PRINCIPLES.md 中的三个陷阱审查设计——那些看似没有问题、实则掩盖故障的事项——并在交付前修复发现的问题。
**完成标准：**文档已保存到指定路径并注明日期，且已确认不包含这三种虚假信心陷阱。