我的 AI 开发流程：从模糊需求到可验证的交付

我目前参与 mooth.ai 的开发，此前主要做 SG 源安全网关。随着 AI 参与的工作越来越多，我发现最需要优化的，往往不是让它再快一点写代码。

真正浪费时间的是：需求没说清就开始实现；已有的项目背景需要反复解释；接口测通了，实际调用链却没有跑通；改完以后，又要重新整理一遍“到底做了什么”。

这些问题有一个共同点：每一步看起来都在推进，但信息在阶段之间丢失了。编码速度越快，错误方向也可能推进得越快。

所以，我给这套流程定的第一性原理是：

降低从需求到结果之间的不确定性，并控制错误被快速放大的风险。

这篇文章记录的是我目前在用、也还在调整的协作方法。它不是一套已经证明适用于所有团队的标准，更不是让每个小修改都填一遍表。判断流程有没有用，最终要看返工是否减少、问题是否更早暴露，以及它是否值得我们投入的时间。

更新于 2026 年 9 月 11 日。

一、先看全貌：每一步要消除什么不确定性

我的日常分工是：我提出目标、处理关键取舍、批准执行并确认业务结果；主 Agent 调查事实、形成方案、实现和验证。只有我明确要求时，才加入外部审查者。

阶段	最容易出的问题	我们具体做什么	留下什么
需求澄清	双方以为理解一致，其实想的是不同结果	回显目标、范围和成功示例，追问关键取舍	明确的需求意图
可行性验证	方案建立在不存在的能力或错误环境上	检查最新代码、契约、依赖和运行条件	可执行、被阻断，或需要小实验
方案审查	开发开始后才发现影响其他模块	写清修改范围、消费者、失败路径和验收方式	获批的明确版本
实现	顺手扩大范围，或增加没有收益的复杂度	按模块职责落到现有目录，保持修改聚焦	实现与定向验证
审查与验收	“有人看过”“测试通过”被当成全部正确	核实问题，区分技术证据和业务确认	结论及证据边界
交付与复盘	结果说不清，相同卡点反复出现	汇总结果，按需分析重复摩擦	交付记录和小步改进

表格里的“留下什么”不一定意味着创建文件。小任务在对话里说清楚就够了，复杂任务才需要阶段文档。

下面用一个贯穿全文的假设需求说明：

“让 Agent 支持查询企业资产。”

这个例子用于解释流程，不代表某个线上功能的实际交付记录。

二、需求刚提出，就开始澄清

过去我容易把“需求澄清”理解成：Agent 不懂的时候，再来问我。但很多偏移恰恰发生在它以为自己懂了的时候。

“查询企业资产”至少可能有几种解释：查询某一家已确定的企业、按名称匹配多家企业、直接返回全部结果，或者先让我选择企业。它们对应的交互、接口和验收都不同。

因此，我现在要求新需求刚提出，或者需求发生实质变化时，就触发项目里的 grill-me。它的作用是把目标问清，不是增加一轮形式化问答。

先回显三件事：

目标：我理解你希望最终观察到什么变化。
范围：本次涉及什么，哪些内容不在本次范围内。
成功示例：给定一个具体输入，什么输出或行为算完成。

然后只追问当前最影响结果的一项取舍。例如：

如果名称匹配到多家企业，你希望先选择一家，还是直接汇总所有匹配企业的资产？

这比一次列出十几个技术问题更容易作出决定。一个关键答案确定后，再判断有没有下一个必须解决的问题。

这里还有一条分工：代码能回答的问题，由 Agent 先查；产品取舍，才交给我决定。 不能让我凭记忆回答接口在哪里，也不能让 Agent 替我决定多企业匹配的业务行为。

需求已经明确时，快速通过即可。续做任务、查询状态、单纯批准，也不重新启动澄清。

它解决的是“带着不同理解进入开发”的问题。预期收益是更早发现分歧，而不是追求更多对话轮次。

三、明确想做什么之后，还要证明现在能做

需求清楚，不等于具备实现条件。

对上面的例子，Agent 需要继续查：

当前代码提供的是企业名称查询，还是只支持内部标识？
数据源是否覆盖需求中的资产类型？
实际消费者是直接调用接口，还是经由工具、Worker 或其他适配层？
目标环境里，依赖服务、权限和对应版本是否就绪？

这些结论必须来自当前代码、接口契约或环境证据。历史文档只能作为入口，不能代替现状。

可行性验证的出口只有三种：

状态	含义	下一步
可以执行	核心依赖和实现路径已有依据	形成执行提案
暂时阻断	缺少权限、数据、能力或必要决策	明确阻断项及解除条件
需要实验	存在影响方案的技术未知	先批准一个范围小、可停止的验证实验

例如，不确定数据源能否支持名称匹配，就先验证查询能力，不直接把完整接口和交互都写完。

这一阶段的价值，是把“我们假设它能做到”变成可核实的事实。最贵的失败，通常不是小实验没成功，而是大量实现完成后，才发现前提不成立。

四、上下文要能找到，也要知道什么时候不读

我希望 Agent 不再反复问：负责哪个项目、哪些模块归它、开发规则在哪里、怎样进入测试环境。

但解决办法也不是每次把所有文档、日志和历史对话一起塞进去。资料越多，过时结论和无关规则也越多。

我现在把上下文分成几个职责明确的入口：

入口	放什么	什么时候读
`AGENTS.md`	少量必须遵守的边界与路由	开始工作时
开发 Skill	执行顺序和触发条件	进入对应任务时
Runbook	验证、部署、工具链等具体操作细节	命中相关环节时
项目导航	仓库位置、模块职责、权威资料入口	确定目标项目时
当前任务文档	本次需求、约束、获批方案和结果	推进或恢复当前任务时

同一条规则尽量只在一个地方维护，其他地方指向它。这样修改流程时，不必同步三份近似但不完全相同的表述。

本次任务采用的事实，还要能回答：来源在哪里、对应哪个版本、现在是否仍成立。例如“接口支持批量查询”应能定位到当前契约或实现，而不是一句无法追溯的旧结论。

历史约束也不能只读一次就结束。假设需求明确“多家匹配时直接汇总”，这个约束就要出现在方案判断和最终验收里，避免实现阶段又加回选择步骤。

账号密码、Token 不放进这些文档。入口只记录登录方式和凭据引用，使用时通过对应机制获取。

我们要建设的是“当前决策需要的最小充分上下文”。它既减少重复说明，也减少错误背景对判断的干扰。

五、执行前批准的是一份具体方案

需求、可行性和上下文对齐之后，才进入执行提案。

这里我区分三种深度：

Lite：范围小、影响明确、容易回退。对话里的短提案即可。
Standard：跨文件或模块，需要稳定保存需求、方案和验收。
High Risk：涉及重要数据、权限、外部副作用或复杂发布，需要展开对应风险。

复杂任务的提案大致如下：

执行提案 v1｜待批准

目标：最终希望观察到的行为
当前事实：代码、接口、环境及证据
关键约束：必须保持什么，来源是什么
影响范围：主责模块 → 现有目录 → 修改文件
关联影响：接口、消费者、数据、权限和环境
修改方案：具体改什么，本次不做什么
失败处理：什么情况阻断，什么情况允许兜底
稳定性：如何灰度、监控和回滚
验收：自动验证什么，哪些需要人工确认
停止点：出现什么新情况必须重新讨论

“稳定性”不是要求每个改动都实现一套发布平台，而是逐项判断是否适用。

例如，一个弱依赖查询服务不可用时，需要明确超时、熔断或降级路径；如果允许返回部分结果，就必须让调用方知道结果不完整，不能把失败伪装成“没有资产”。对于没有运行时影响的文字修正，则可以直接说明灰度不适用。

灰度关注如何限制影响范围；监控关注通过什么信号发现异常；回滚关注撤回后能否恢复，包括数据变更是否可逆。代码回退，并不天然意味着数据也恢复。

我批准的是当前版本的目标、范围、环境、风险和验收条件。批准后，Agent 可以自行处理范围内的普通实现选择；如果要改变公共接口、扩大权限、调整目标环境或降低验证标准，就必须提交新版本。

这样可以避免两个极端：一句“可以”被解释成无限授权，或者每改一行代码都要再确认一次。

六、文档是阶段之间的接口，不是开发流水账

对于需要跨会话推进的任务，我使用这几个文件：

文件	要回答的问题	进入下一阶段的条件
`intent.md`	用户到底要解决什么问题？	目标、边界和关键取舍明确
`spec.md`	应该表现出什么行为？	规则、异常和验收可判断
`plan.md`	基于当前代码准备怎样做？	对应版本获得批准
`review.md`	有哪些审查问题，如何处理？	影响当前推进的问题已处理或明确决策
`result.md`	实际完成什么，有什么证据？	交付状态和剩余事项说清楚

review.md 按需使用，不为了凑齐文件而创建。只有确实需要独立交付、跨上下文协作的任务，才进一步拆成 tickets。

这些文件只保存结论、来源和下一阶段条件，不复制完整对话、模型思考、终端流水和 Trace。

中断之后，Agent 先核对当前任务、获批版本、代码基线、已完成项、验证状态和阻断点，再继续。环境或代码变了，就补查变化部分，而不是重新理解整个项目，也不是照着旧计划盲目执行。

文档的收益是减少阶段交接和恢复时的信息损失。小任务不需要这种成本，所以保留在对话中。

七、实现既要正确，也要控制维护负担

进入实现后，我最在意两件事：代码落在正确的位置，修改没有偷偷长大。

在模块职责已经划分的项目里，先找到主责模块和现有目录。新增目录、抽象或公共接口，应该有当前需求上的理由，不能因为“以后可能有用”就顺手搭一套。

实现完成后，使用 Ponytail 做一次无收益复杂度检查：

这段逻辑是否确实需要？
项目里是否已有同等能力？
标准库或已有依赖能否完成？
是否为了一个实现增加了没有实际作用的接口或包装？
注释是在解释必要原因，还是只复述代码和修改过程？

这里追求的是更容易理解、验证和维护，不是机械减少行数。信任边界校验、数据保护、无障碍要求和已确认的稳定性行为，不能为了短 diff 删除。

Ponytail 也不替代正确性、安全和性能审查。它负责的是一个更窄的问题：实现中有没有不值得长期维护的东西。

验证遵循目标仓库的规则。有的项目要求 TDD，有的修改只需要一次定向检查。相关代码没有变化时，不在提交前后反复跑同一套检查；修改共享契约或高风险逻辑时，再增加必要的消费者或边界测试。

检查应该证明本次改动，而不是靠检查数量制造完成感。

八、外部 Agent 是审查者，不是另一个自动实施者

目前我使用 ZCode 作为可选外部审查者。它默认不参与；只有我明确要求审查方案或实现时，主 Agent 才调用。

一次明确的审查请求就进入审查，不再叠加多轮材料确认。审查者可以使用工具、Skill 和项目上下文调查；但职责是审查，不是修改实现或决定扩大需求。每次审查都会新建独立会话，避免旧方案和旧结论污染本轮判断。

我比较认可的审查顺序是：

先搞清楚要解决的问题；再独立判断自己会怎样解决；最后阅读待审方案或实现，对照给出结论。

对代码审查来说，目标可以是一个提交、一段 diff 或当前工作区，不要求一定有 PR。先理解问题和原有实现，再看本次修改，有助于减少被现有方案带着走。

对设计文档，则先理解目标、约束和现状，形成自己的实现判断，再检查文档的可行性、遗漏和取舍。不能只看章节是否齐全。

我使用的提示词思路可以概括为：

你是审查者。本次审查对象是指定文档或代码变更。

先理解它解决的问题、成功条件和现有约束。
在详细阅读待审方案或 diff 前，基于需求和现状形成自己的解决思路。
随后检查待审内容，比较两者，必要时调查调用方、测试和相关实现。

差异本身不是问题。若现有方案更合适，应修正自己的判断。
报告有证据支持的问题：位置、触发条件、影响和修改建议。
证据不足的地方单独说明，不凑问题。

即使每次新建会话，也不能声称这是一次完全独立的“盲审”：同一个模型、相同项目资料和提示方式仍可能产生相似偏差。独立思考是一种减少偏差的方法，不是一项可以凭提示词保证的能力。

审查结果回到主 Agent 后，还需要核实：哪些有效、哪些误报、哪些缺少证据。不会自动循环修改直到审查者说通过，也不会把两个模型意见一致当成正确证明。

每次审查保留一份独立的简短记录，包括失败调用。详细过程留在对应会话中，记录只保留结论、处理和必要引用。这既方便跟进，也能观察审查本身是否带来收益。

后来我又沿用同一条 ACP 链路增加了独立测试执行者。它不参与审查，而是根据明确任务书在指定环境串行执行可复用用例，具体设计见《我把 ZCode 变成了测试执行者》。

九、验收要沿着实际使用路径，不能只看“测试通过”

这是我特别希望守住的边界。

一个工具可能已经注册，却没有出现在主 Agent 的可用工具列表里；接口可以直接调用，却不代表 Worker 路径正常；自然语言任务执行成功，也可能仍未满足业务要求。

因此，交付时需要区分不同层次的证据：

已有证据	能说明什么	还不能说明什么
能力已注册	系统知道存在这个能力	实际消费者能够发现和使用
消费者可发现	工具或接口对调用方可见	调用参数和运行链路正确
直接调用成功	该入口在本次条件下工作	Agent 会选择并正确调用它
Agent 任务成功	实际任务链路完成了本次执行	所有业务边界都已覆盖
业务验收通过	符合明确的成功条件	在未经验证的环境中同样成立

回到企业资产查询例子：接口返回了一个非空数组，不足以证明需求完成。还需要检查是否覆盖所有匹配企业、是否包含应有资产类型、失败是否被正确表达，以及实际 Agent 是否走了这条调用链。

自动化适合证明接口契约、边界行为、失败路径和回归；人工确认适合产品取舍、真实使用体验，以及需要业务判断的结果。

验证结论必须带着版本和环境边界。代码已提交、CI 通过、测试环境已部署、生产已发布、业务已验收，是不同状态，不能混写成“已完成”。

发布涉及多个依赖服务时，也要核对完整链路是否更新，不能只部署一个接口服务，就假定所有消费者已经采用新契约。

十、交付说明要能回答“这次工作为什么值得做”

开发结束后的说明，不能只有修改文件清单，也不能直接写“显著提升效率”。

我希望结果能被用于下一步决策，也能作为向老板汇报的事实输入：

本次结果：完成了什么行为变化
验证状态：哪些证据已经取得，哪些尚未确认
目标影响：对应哪个核心目标，改善通过什么机制发生
剩余事项：人工验收、环境限制或后续工作
文档建议：哪些权威文档可能需要更新，具体建议是什么

例如，可以说：

本次实现允许按企业名称查询并汇总匹配结果，减少用户先获取内部标识再发起查询的步骤。接口验证已通过，实际 Agent 链路与业务验收仍待确认。减少操作步骤是本次设计的预期收益，暂未统计实际节省的时间。

这比“完成查询接口，效率提升 50%”更有信息价值，也更诚实。

权威能力文档不在交付时自动改写。Agent 先报告具体文件和拟修改内容，由我确认后再改，避免实现中的临时行为反过来悄悄改写产品约定。

当前任务的结果及时保存；长期汇总、功能台账和知识整理，则在我明确开放记录窗口后处理。开发过程中不自动扩展成一次知识库大扫除。

十一、持续改进，也要有复杂度预算

这套流程本身也可能出问题。

我已经注意到两种风险：规则写了，但触发时没有执行；同一件事在多个文件里重复维护，越补充越难遵守。需求澄清和最小化检查都不能只靠“文档里有这一条”。

所以，复盘时我不只问 Agent 有没有遵守流程，还会问：入口是否明确？规则有没有冲突？工具输出是否太长？是否让人做了本来可以由代码调查回答的事？

每次复盘优先看少量事实：

哪些稳定上下文被重复解释？
哪些范围变化在批准后才暴露？
自动测试和人工验收分别发现了什么问题？
哪些检查跑在错误环境或错误链路上？
审查发现了多少有效问题，又产生了多少误报？
恢复任务和维护流程本身花了多少额外精力？

这些是后续评估的维度，不代表我已经有完整、连续的统计数据。

一个卡点不一定需要新增规则。更有效的动作可能是修正上下文路由、缩短脚本输出、补一个真正覆盖失败路径的测试，或者删除一个没有收益的确认步骤。

我希望每次改进都遵循：

找到反复发生的问题 → 选择最小调整 → 放进真实任务验证 → 保留有效部分。

没有证据，就不继续增加文档、状态文件和自动化。

十二、这套流程的收益与边界

目前我能明确说的收益，是协作结构更清楚了：需求有澄清入口，执行有批准对象，审查有职责边界，交付能够区分不同层次的证据，复杂任务也有恢复入口。

这些机制有望减少错误方向上的实现、重复解释和交接损失。但我还不能给出可信的整体提效百分比，也不能保证 Agent 每次都完整遵守。它仍需要真实任务的反馈和人的关键判断。

代价同样存在：澄清、方案和文档需要时间；审查可能误报；上下文会过时；小改动如果套上全流程，反而更慢。

因此，我不建议别人先复制所有文件和工具。更合适的起点是选一个真实需求，先把三件事做扎实：

开始前，说清楚目标和成功条件。
执行前，确认修改方案与影响范围。
结束后，说明实际结果和验证边界。

遇到反复的上下文问题，再补路由；遇到跨会话恢复困难，再补阶段文档；遇到确实值得第二视角检查的改动，再引入审查者。

对我来说，好的 AI 开发流程应该让关键判断更容易、结果更可核实，而不是让每个任务看起来都很正式。