当 AI 开始参与复杂软件工程,我在思考什么?

最近，我整理并开放了一个自己一直在思考的 Codex Skill：coordinate-software-work。

它关注的不是怎样让 AI 更快地写出一段代码，而是另一个更难回答的问题：

当 AI 开始参与一项真正复杂的软件工作时，人和 AI 应该怎样协作，才能把事情可靠地做完？

这里说的“复杂”，不一定意味着代码量很大。一个改动只涉及几个文件，但如果它改变了公开接口、要求保持兼容、需要跨越多个会话，或者必须用运行结果证明安全性，它就已经不再是一次孤立的代码编辑。

相反，有些改动虽然涉及不少代码，但目标明确、风险可控、验证直接，也未必需要复杂的协调方式。

我越来越觉得，AI Coding 下一阶段值得讨论的重点，可能不只是模型一次能写多少代码，而是它能否理解一项工作的边界，保护不应该变化的东西，识别自己还没有完成的部分，并留下足够可信的证据。

coordinate-software-work 就是围绕这些问题形成的一次方法整理。

GitHub RepositoryXinChenyang1214/doc-driven-development

从“生成代码”到“协调工作”

给 AI 一个清晰的小任务，它通常已经能完成得很好：增加一个字段、修改一处判断、补一条测试，或者解释一段代码。

但真实的软件工程很少永远停留在这种理想状态。

我们经常面对的是另一种场景：需求还带着不确定性；代码、文档和测试对系统行为的描述并不一致；一个功能同时影响多个模块；修改必须保持兼容；上线还涉及迁移、回滚和状态核对；工作中途可能交给另一个人或另一个 Agent。

这时，问题不再只是“下一段代码怎么写”，而是：

• 我们现在是在调查问题，还是已经承诺交付？
• 目标行为究竟由什么决定？
• 哪些东西要改变，哪些东西必须保持不变？
• 需要什么证据，才能说明工作真的完成了？
• 调研笔记、临时脚本、外部资料和实验结果，最后该怎样处理？

这些决定以前通常散落在聊天、工单、文档、代码和人的记忆里。每次换一个任务、换一次会话，甚至只是换一个 Agent，都可能重新做一遍。

我希望这个 Skill 能减少这种重复的协调成本。

我尝试用四类 Claim 描述一项工作

在整理这套方法时，我首先做的一件事，是不再把复杂任务简单理解成一串待办事项，而是把它拆成几类可以被验证的 Claim。

• Change
  
  ：什么必须变成新的状态。
• Invariant
  
  ：在工作过程中，什么必须始终保持成立。
• Knowledge
  
  ：有哪些事实需要通过调查、测量或实验得到。
• Operational
  
  ：哪些迁移、发布、回填、回滚或停用动作必须安全完成。

例如，“完善批量导入”听起来像一个任务，但它包含的真实要求可能是：支持中断恢复，重复执行不会产生重复数据，原有单条导入保持兼容，在代表性数据上达到预期性能，并在上线后完成数据核对。

这些要求不是同一种性质。实现新能力是一类工作，保护旧行为是另一类工作，性能结论需要测量，生产状态转换则需要操作证据。

当它们全部挤在一句自然语言里时，AI 很容易完成最显眼的那部分，然后宣布任务结束。把它们拆开，并不是为了制造表格，而是为了让“完成”变得可以判断。

对于简单任务，这个模型完全可以只存在于当前思考中；只有当工作需要跨会话、跨人员或长期保留时，才有必要把它外化成正式产物。

探索和交付，应该拥有不同的自由度

另一个让我反复思考的问题，是 AI 在什么时候应该大胆探索，什么时候应该严格守约。

一项工作的早期往往充满不确定性。我们需要阅读代码、核对现状、比较方案、做实验，有时还需要写一个最终会被丢弃的原型。在这个阶段，如果给 AI 过多限制，反而不利于发现真正的问题。

我把这个阶段称为 Discovery。

Discovery 允许较高的自由度，但需要分清事实、假设、提案、决策和开放问题。一个实验可以帮助我们学习，却不能因为“看起来能跑”，就被直接当成正式交付。

当目标、范围、Claim、不变量、验收方式、证据要求以及必要权限已经足够清楚，工作才通过 Ready Gate，进入 Delivery。

进入 Delivery 后，自由度应该收紧。此时需要一份明确的 Work Contract：这次承诺做什么、不做什么，哪些行为不能破坏，以及用什么方式判断完成。

如果实现过程中出现了会改变范围、行为或风险的新情况，更合适的做法是暂时回到一个受控的探索分支，重新确认契约，而不是让 AI 自己悄悄简化目标。

这条主线可以概括为：

Discovery → Ready Gate → Work Contract → Delivery → Verification → Settle & Close

它不是要求每次都创建六份文档，而是在提醒我们：探索可以试错，交付需要守约，两者不应该混在一起。

“有测试”和“有证据”并不是一回事

在与 AI 协作时，“已经完成”是一句需要谨慎对待的话。

编译通过，不等于行为正确；仓库里有测试文件，不等于测试已经执行；本地单元测试通过，不等于一次生产迁移已经完成；一份计划写得很完整，也不能证明对应功能已经落地。

因此，这个 Skill 会区分两件事：

• 测试、基准脚本、核对查询等属于 Verification Asset，描述“准备怎样验证”。
• 某次测试结果、性能数据、运行观察和迁移核对结果属于 Evidence，描述“实际观察到了什么”。

证据还需要有适用范围。它对应哪个代码版本、什么环境、哪组数据和配置？相关条件变化以后，这份证据是否仍然有效？

我希望最终的完成判断可以沿着这样一条链路发生：

Claim → 实现或操作 → 验证证据 → 一致性结论

这并不意味着每个小改动都要生成一份证据报告。它只是要求完成声明与任务风险相匹配：低风险改动可以用局部测试证明，涉及真实状态转换的工作则需要运行或操作层面的证据。

我尤其想避免“看起来完成了”

AI 很擅长填补空白。当真正的实现遇到困难时，这种能力有时会产生一种非常隐蔽的问题：结果在形式上完整，在语义上却已经缩水。

例如：

• 用占位符、空实现或固定返回值代替真实行为；
• 只完成正常路径，遗漏已经确认的错误和边界场景；
• 新系统尚未实现某项能力，却继续借用旧系统并声称迁移完成；
• 代码已经存在，但配置、开关或部署链路没有接通；
• 为了让结果变绿，降低测试断言或反过来修改验收标准。

我把这些情况统称为“静默降级”。

coordinate-software-work 的一个重要原则，是不允许把这类替代方案包装成完整交付。如果某个已确认的 Claim 暂时无法完成，就应该明确标记阻塞、说明影响，并在确实需要改变范围时重新协商。

当然，现实工作完全可以分阶段进行。区别只是：阶段需要被明确划分，每一阶段都应当对自己的 Claim 负责，而不是用“第一阶段”来掩盖一个实际不可用的结果。

文档不是越多越好，重要的是权威和生命周期

仓库地址使用了 doc-driven-development 这个名字，但我并不希望这套方法被理解为“所有事情都要先写一堆文档”。

文档的价值不来自数量，而来自它是否承担了必要的协调责任。

当一项信息需要跨越当前会话、约束未来实现、保存一项代价很高的决策、支撑可重复操作，或者为完成结论提供证据时，它才值得被外化和保留。

同时，文件出现在仓库里，并不代表它自动具有权威性。外部资料可能只是输入，调研笔记可能只是工作记忆，实验输出可能可以重新生成，运行记录也可能只在特定环境和时间内有效。

我更倾向于从角色和生命周期理解这些产物：

• 当前契约保存有效的目标、边界和不变量；
• 决策记录长期有价值的选择与理由；
• Runbook 保存可以重复执行的操作；
• 测试和脚本提供验证方法；
• 结果记录提供有范围的证据；
• 调研笔记、临时计划和实验日志服务于当前工作；
• 外部材料在被明确采纳前，只是参考输入。

工作结束时，真正值得长期保留的内容应当被提炼到合适的位置。临时材料在不再被依赖、且符合项目规则的情况下，可以删除或重新生成。归档只是其中一种选择，不应该成为所有过程文件默认的终点。

这不是一套覆盖所有任务的重流程

我很在意这个 Skill 的适用边界。

它更适合需要跨会话或交接、包含多个 Claim 和不变量、涉及权威冲突、迁移发布、复杂实验、审计或长期维护的工作。

如果只是一个目标清楚、影响局部、风险较低的修改，那么代码、回归测试和必要的现有文档更新可能已经足够。此时创建正式契约、台账和工作目录，反而会增加噪音。

所以，这套方法的关键词不是“完整流程”，而是按比例使用和最小充分产物。复杂度应该来自问题本身，而不是来自 Skill。

它也不试图替代专业技术能力。框架怎么使用、数据库如何迁移、云平台怎样部署，仍然应该优先遵循项目规则、已有 Runbook、领域 Skill 和当前官方文档。coordinate-software-work 负责协调“要交付、保护、证明和沉淀什么”，具体技术流程则交给更专业的来源。

欢迎交流

这是 coordinate-software-work 第一次公开分享。

目前仓库中包含核心 Skill、工作模型、权威与证据、产物治理、交付完整性、测试与实验、执行内核以及不同工作场景的参考流程。

如果你想尝试，不需要手动研究安装命令。把下面的仓库地址发给你使用的 AI 编程工具，请它安装这个 Skill 即可：

请帮我安装这个 Skill：
https://github.com/XinChenyang1214/doc-driven-development

View on GitHubgithub.com/XinChenyang1214/doc-driven-development

我也很希望听到不同的实践经验：你在使用 AI 参与复杂软件工作时，最常遇到的是上下文丢失、需求漂移、验证不足，还是任务“看起来完成了”、实际上却仍有关键缺口？

如果这套方法对你有启发，欢迎试用、讨论，也欢迎提出改进建议。