agentic-workflow-guide

Agentic 工作流指南

基于经过验证的原则来设计、审查和改进 Agent 工作流。

这个 SKILL 的基本立场是：不是增加 agent，而是用必要的最小 primitive 来解决问题。 即使 context 膨胀时，也要首先考虑 split / compact / reference 化，不要一上来就用 multi-agent。

Primitive 优先

不要默认从 multi-agent 开始。

• 单一聚焦的 slash 任务 -> Prompt（仅限 Local harness；prompt 文件在 Agent Host 会话中已废弃，因此新的 slash 工作流请优先使用 Skill）
• 始终生效或限定文件的指导 -> Instruction
• 带捆绑资源的可复用工作流 -> Skill
• 角色设定、工具限制、委派或交接 -> Agent
• 确定性强制执行 -> Hook（Preview；事件和配置因 harness 而异）

如果需求不需要 Agent，就停下来使用更简单的 primitive。

选择详情：references/customization-decision.md

何时使用

操作	触发条件
创建	新建 .agent.md、.instructions.md、.prompt.md、AGENTS.md 或工作流架构
审查	编排器未进行委派、设计原则检查、context 溢出
更新	添加 Handoffs、改进委派、工具配置
调试	Agent 未找到、子 agent 不工作、选择器可见性、访问控制
决策	判断 multi-agent 是否合理，或者更简单的 primitive 是否足够

核心原则

• 简单优先：如果能用更简单的 primitive 解决，就不要 agent 化
• SSOT / SRP：遵守信息源与职责的划分
• 快速失败：让错误尽早停止
• 反馈循环：让每个阶段都能验证
• Context 纪律：当 context 膨胀时，考虑 compact / split / retrieve

原则详情：references/design-principles.md

模式选择

当复杂度上升时，使用 references/workflow-patterns/overview.md 中的选择器明确指定模式。每个循环都需要明确的停止条件。

设计工作流

1. 从对话中提取重复行为、工具偏好和工作流形态。
2. 选择 primitive + 作用域（workspace / profile）；只询问会改变行为的模糊之处。
3. 只有当 split / compact / reference 化无法解决时才升级，然后选择模式。
4. 实现最小版本，并收紧最薄弱的部分。

规则放置

• 通用的工作流设计原则以这个 SKILL 和 references/ 作为 SSOT。
• repo local 的 .instructions.md 中只保留 workspace 特有的差异。没有差异的 generic instruction 应 merge back 并作为删除候选。
• IR 原则上以 in-memory 方式处理。只有当需要 validator、script、deterministic handoff 时，才将中间 file materialize，并在不再需要时清理掉。
• scheduler / service / config 等确定性的 state mutation，不要通过 AI/UI loop，而是用 direct script / API 完成现状确认 -> 最小变更 -> live read-back。LLM 只限于判断 scope 和整合对象。
• 对于模型分配审查，使用 scheduled runtime bindings。

升级规则

优先使用能干净解决问题的最低层级（L0 prompt → L1 + instructions → L2 单一 agent → L3 multi-agent）。快速拆分信号：

• Prompt > 50 行
• 步骤 > 5
• "missed" / "overlooked" 错误持续出现
• 一个 agent 中承担多个职责
• Context > 70%

阈值详情：references/splitting-criteria.md

审查关卡

• 在可能的情况下，原语选择比 Agent 更简单
• 放置位置合适，且始终加载的入口文件保持精简（入口边界问题：review-checklist.md）
• 只有在检查过删除 / 合并 / 拆分 / 移动选项之后，才提出新增内容
• 保持每个 Agent 单一职责
• 错误可以被及早检测并停止
• 验证真实的从生产者到消费者的数据流，而不仅仅是注入到验证器中的 fixture；覆盖空结果和有意义的状​态转换。重复未变更的输入只能证明幂等性，不能证明完整生命周期。
• 确定性部分被下放到脚本 / IR / hooks，并且状态变更通过回读权威实时状态来确认（而不是 LLM/UI 循环）

完整清单：references/review-checklist.md

参考地图

核心参考：原语决策、设计原则、工作流模式、拆分标准、审查清单 和 上下文管理。

对于定时工作流，请使用定时运行时绑定。对于委派证据和仅追加的当前状态提取，请参阅 orchestrator-workers 和 IR 架构。

当 orchestrator 承诺委派却直接工作时，请让委派要求明确且可验证（agent-guide.md）。工具映射与 Agent 脚手架：agent-template.md。

完成标准

• 有意识地选择原语和范围
• 选择工作流模式并与用户确认
• 新增或更新的资产在适用处具有清晰的 Role/Workflow/Done Criteria
• 通过审查关卡
• 建议在适用处归类为删除 / 合并 / 拆分 / 移动 / 新增 / 保留
• 当 copilot-instructions.md 或 AGENTS.md 在范围内时，显式审查始终开启的指令边界以及 DRY / SSOT 风险
• 在需要时，将新的 Agent / 工作流资产注册到相应的目录或文档中
• 仅当共享护栏或入口行为需要变更时才更新 AGENTS.md
• 关闭工作流期间启动的长时间运行或临时终端/任务，或明确报告剩余终端并说明原因
• 区分配置已保存、代码已测试、实时读取已验证、操作已授权和周期性循环已完成。在声称完成或无人值守就绪之前，验证权威状态；待定防护措施和未观察到的循环仍保留其阻塞项和下一次检查条件。