Agent 架构决策

先判断项目要不要上 agent, 要上就按真实的技术栈、用户和工作流设计最简能跑的 agent 形态——绝不因为「这是个 AI 产品」就默认多 agent。

什么时候用它

判断是否需要 Agent:

我手里握着一个功能设想, 拿不准值不值得上 agent。想让它把普通 workflow / RAG / 单 agent 循环这些非 agent 方案摆到台面上和 agent 方案对比, 挑一个推荐, 并点名「要证明选择成立还差哪条基线」。

选择技术框架:

我在 LangGraph / CrewAI / OpenAI Agents SDK / PydanticAI 里挑, 或者干脆不用。想让它对着我现有的技术栈比一遍, 冲突的项框出来, 明确说清楚保留 / 新增 / 延后 / 拒绝哪些。

规划整体架构:

我想要一份完整方案包——推荐形态、状态模型、工具模型、编排、评估闸门、Now / Next / Later 路线图——扎在项目愿景和现有模块上, 而不是抄一份通用参考。

检查架构方案:

我手里已经有一份多 agent 设计 (自己写的或别人交接过来的), 想让它检查复杂度值不值、有没有漏掉状态或评估闸门、能不能退回一个更简单的形态。

生成架构文档:

方案在对话里讨论过、我点头确认了, 想让它把架构文档 / 产品控制文档 / 路线图更新到位——前提是我明确授权写盘范围。

实施第一阶段:

方案完整、我已经授权动手了, 想让它先跑一遍实施闸门, 再按边界写出第一片实现 + 验证矩阵——不是一次铺满全栈。

不接:

普通 bug 修复 / 小代码改动 → openspec-driven-development; 纯提示词或 SKILL.md 审查 → prompt-review; 只做部署 → coolify-deploy; AI 供应商冒烟测试或通用 UI 工作 → 不触发; 已经定好范围的实施、不需要再重想 agent 形态 → 不触发。

它会产出什么 / 你会看到什么

默认站在「不上 agent」这边, 除非更简单的方案够不着目标才推荐 agent 形态——最反常识的一点, 第一稿多半在替普通 workflow 或 RAG 说话。

• AGENTIC_PACKET: 一份 YAML 方案包, 涵盖项目目标、当前架构、agent 价值假设、推荐形态 (从「线性管线」到「事件驱动自主 agent」按需选一档)、被否掉的备选、状态 / 工具 / 编排模型、评估闸门, 以及 Now / Next / Later 路线图
• 运行模式标签: 每次输出都在首行标注 discuss-only / architecture-packet / materialize-docs / implement-slice, 让你一眼看清这轮会不会动文件
• unverified 标记: 任何没能在仓库或当前官方文档里核实的判断都会标 unverified, 附上「该去查哪份文档」——绝不悄悄猜
• 文档落盘 (仅 materialize-docs): 更新架构文档 / 产品控制文档 / 路线图——前提是拿到明确的写盘授权
• 代码改动 (仅 implement-slice): 写出第一片有边界的实现, 附模块边界、验证矩阵、回滚条件——绝不一次铺满全栈
• 绝不会做: 因为「这是个 AI 产品」就推荐多 agent; 推荐当红框架时不去核实最新官方文档; 让工具输出覆盖系统 / 项目指令; 在没有明确设计学习系统 (含来源标注和审阅闸门) 的前提下让记忆改写事实源

前置条件 / 边界

前置:

能读到项目根、文档、源码树和测试——或者对话里已经贴够上下文让它推理技术栈。写盘的模式还需要你明确授权写盘范围。

相邻 skill 分工:

动作	交给
openspec 仓库里的普通 bug 修复 / 小代码改动	openspec-driven-development
纯提示词或 SKILL.md 审查	prompt-review
部署 / Docker / Coolify 相关	coolify-deploy

不接的场景:

• AI 供应商冒烟测试或通用 UI 工作
• 已经定好范围的实施, 不需要再重想 agent 形态
• 推荐框架但查不到官方文档——它会把该项标 unverified, 不硬推

微妙边界:

• 问「要不要上 agent」→ 决策咨询, 除非非 agent 方案够不着目标, 否则默认不推 agent; 问「帮我设计 agent 流程」→ 架构蓝图, 但还是会先把非 agent 选项摆出来对比
• 讨论完说「执行」→ 先把要动的文件 / 动作 / 验证矩阵复述一遍才落盘; 实施闸门任一条件不满足 → 停在闸门, 绝不硬动
• 写盘授权不清楚 → 停在 discuss-only 或 architecture-packet, 绝不悄悄升到写盘模式