浅谈 AI 编程

过去两年，大家总喜欢问“模型能不能写代码”、“能不能替代程序员”、“是不是以后不用学编程了”。

这些问题当然重要，但它们都停留在表层。

真正的变化不是 AI 会写多少行代码，而是代码生产的边际成本正在快速趋近于零。当代码变得越来越便宜，软件工程的核心矛盾就会从“谁来写代码”转向“谁来定义正确性、谁来约束生成、谁来验证结果、谁来承担系统长期演化的责任”。

这也是 Codex Goal[1]、Claude Dynamic Workflows[2]、subagent、handoff、AGENTS.md、CLAUDE.md、hooks、evals、sandbox、worktree 等概念集中出现的深层原因。它们看起来像工具功能，实际上是在回答同一个问题：当 AI 可以持续生成、持续修改、持续调用工具、持续并行执行时，我们如何把这种机器产能纳入一个可控的软件工程系统？

这篇文章的核心观点不是 “AI 会让编程更快”这么简单，而是：AI 编程的下一阶段，不是代码生成工具之争，而是 AI 代码生产系统的治理能力之争。

Codex Goal 代表目标持续化，Claude Dynamic Workflows 代表编排外置化，subagent / handoff 代表协作结构分化，而真正决定成败的，是规格、约束、测试、架构文档、上下文工程与验证基础设施。

换句话说，未来软件组织最重要的资产不再是某一版代码本身，而是让任何一代模型都能安全重写、迁移、验证和接管系统的规格约束体系。

拓展阅读：

• 浅谈 AI 超级应用
• 深度解析：Harness Engineering
• 从 Prompt Engineering 到 Context Engineering
• ...

大背景

早期 AI 编程工具更像补全器。

Copilot[3] 时代，AI 的价值主要体现在局部编码效率：补全函数、生成样板、写测试、解释错误。它提升了“写代码”这件事的速度，但软件工程主流程并没有被根本改变。需求仍然由人拆，架构仍然由人定，测试仍然由人跑，错误仍然由人复制给模型，下一步仍然由人告诉模型。

这种模式有一个隐含问题：人类成了模型的“循环控制器”。

模型每做完一轮，人类要看输出、跑测试、粘错误、继续提示、再审查。表面上是 AI 帮人写代码，本质上还是人类在驱动整个工程循环。AI 提升的是局部动作速度，没有接管任务推进责任。

Agent 编程的出现，把问题推进了一层。

一个 agent 不只是“回答代码”，而是可以围绕目标调用工具：读文件、搜索代码、修改文件、运行测试、查看日志、调用浏览器、生成 PR、复盘失败结果，并基于反馈继续行动。Anthropic 对 agentic system 的区分很有启发（Building effective agents[4]）：workflow 是 LLM 和工具被预定义代码路径编排；agent 则是 LLM 动态决定自己的流程和工具使用。也就是说，agent 的关键不在于会不会生成文本，而在于它是否进入了“感知—行动—反馈—再行动”的循环。

一旦 AI 从“代码补全”进入“任务执行”，软件工程就会出现几个新瓶颈：

• 目标瓶颈：模型可以持续行动，但它必须知道什么叫完成。没有明确完成条件，AI 不是少做，而是会一直做、乱做、过度做。
• 上下文瓶颈：真实代码库不是算法题。它有历史包袱、隐性约定、兼容承诺、测试缺口、部署风险、团队风格。把更多文件塞进上下文，不等于模型更理解系统。Anthropic 在 context engineering[5] 文章里明确指出，context 是有限资源，随着上下文增长，模型会出现注意力稀释和信息相关性下降，长任务必须把 context 当作稀缺资源管理。
• 验证瓶颈：AI 生成代码很快，但正确性不是语言流畅度决定的。代码能编译，不等于业务正确；测试通过，不等于架构没被破坏；PR 看起来完整，不等于未来可维护。
• 组织吸收瓶颈：个人使用 AI 写 demo，是效率问题；企业让 agent 改核心仓库，是治理问题。权限、审查、回滚、合规、责任归属、知识沉淀，都会成为生产系统的一部分。

所以，AI 编程的真正主线不是“模型更会写代码”，而是：模型开始进入软件生产链路，工程组织必须为它设计目标、上下文、权限、验证和责任边界。

Codex Goal 与 Claude Dynamic Workflows，正是在这个背景下出现的两个关键原语。

概念校准：Goal & Workflow

讨论 Codex Goal、Claude Code /goal 和 Claude Dynamic Workflows 之前，必须先把层级分清。它们都和“长任务”有关，但解决的问题并不一样。

Codex Goal 是 OpenAI Codex 体系里的 /goal 能力，本质是把一个长期任务的完成条件固定在线程里。用户设置一个 persistent objective 后，Codex 会围绕这个目标持续推进，直到任务完成、暂停、遇到阻塞或需要更多输入。它解决的是：一个 agent 不该每轮都停下来等人说继续，而应该知道自己要持续工作到什么状态才算结束。

Claude Code/goal 与它更接近（网上评价不如 codex 好用），同样属于“完成条件”机制。区别在于 Anthropic 的实现语义不同：/goal 会设置一个 completion condition，每轮结束后由一个小模型判断目标是否满足；如果没有满足，就继续下一轮。所以，Claude Code /goal 和 Codex Goal 可以放在同一类讨论：它们都是“目标持续化 / 完成条件”原语。

Claude Dynamic Workflows 则是另一层东西。它不是 completion condition，而是多 agent 编排机制。Claude 会为任务生成一段 JavaScript workflow 脚本，在后台运行，并由这段脚本调度大量 subagents。它适合那些单个对话已经协调不过来的任务，比如大规模代码库审计、迁移、交叉验证研究，或者你希望把复杂编排沉淀成可读、可复跑的脚本。

一句话概括：Goal 定义什么时候算完成，Workflow 定义任务如何被组织和执行。前者解决完成条件，后者解决协作与调度。两者关注的是不同层级的问题。

Codex Goal

传统 prompt 更像口头指令。

你说“帮我优化结账接口性能”，模型确实可能去改代码，但它并不知道什么叫“优化完成”。是 p95 降到 120ms？还是只要比原来快一点？能不能改 API？能不能加缓存？能不能引入新依赖？测试挂了算不算失败？benchmark 不稳定时该继续试，还是停下来报告？

单轮任务里，这种模糊还可以靠人补救。模型输出后，人类看结果，再继续追问、修正、补充约束。但一旦任务变成长程 agent 任务，模糊目标就会被放大成系统性风险：agent 会持续行动，却不知道终点、边界和停止条件在哪里。

Codex Goal 的核心价值，就是把这种“口头指令”升级成“完成合同”。

OpenAI Goals[6] 文档把它定义为 Codex 线程中的 persistent objectives：Goal 会让线程跨 turn 朝一个明确 outcome 持续工作，并提供 completion condition，包括什么应该为真、如何检查成功，以及哪些约束必须保持不变。它不是无边界后台自治，而是 scoped、user-controlled completion contract。

它的心智模型可以简化成：

普通 prompt：ask -> work -> result -> wait
Goal：work -> check -> continue or complete

所以，Goal 不是更长的 prompt，而是一个围绕证据闭环运行的状态机。Codex 每轮工作后，都要根据证据判断目标是否完成；如果没有完成，就继续下一步；如果 benchmark 无法运行、预算耗尽、连续实验无效或遇到阻塞，就应该停止并报告证据，而不是假装成功。

一个强 Goal 通常要写清楚六件事：

Outcome：任务完成时什么应该为真
Verification surface：用什么测试、benchmark、报告或 artifact 证明
Constraints：哪些东西不能回归
Boundaries：允许使用哪些文件、工具、仓库、数据
Iteration policy：每轮失败后如何选择下一步
Blocked stop condition：什么时候必须停下来报告阻塞

弱 Goal 往往是这样的：

/goal 优化 checkout 性能，不要破坏功能

它的问题是没有终点、没有验证面、没有边界，也没有停止条件。更好的写法应该接近这样：

/goal 将 checkout benchmark 的 p95 延迟降到 120ms 以下，
通过 pnpm bench checkout 和 pnpm test checkout 验证，
同时保持 public API、数据库 schema、支付语义不变。

只允许修改 services/checkout、services/payment-adapter 及相关测试。
每次迭代只做一个假设驱动的最小改动，记录修改、benchmark 结果和下一步理由。

如果 benchmark 无法稳定运行，或连续三次实验没有改善，
停止并报告证据、阻塞原因和建议的人类决策点。

这背后是 AI 编程时代非常关键的变化：过去的高级工程师主要擅长写代码；未来的高级工程师必须擅长写可执行的任务合同。

但 Codex Goal 的边界也要讲清楚。它本身不是多 agent 编排系统。Codex 可以支持 subagent workflows，但文档语义上，Goal 解决的是“一个 agent 如何围绕目标持续推进并判断完成”，不是“如何组织一批 agent 并行协作”。换句话说，Codex Goal 最适合的任务不是“全仓十万文件并行迁移”，而是那些路径不确定、终点可验证、需要持续迭代的任务：复杂 bug 修复、flaky test 追踪、性能优化、依赖迁移、局部重构、测试补齐、审计报告生成。

它解决的不是“怎么组织一千个 agent”，而是：怎么让一个 agent 不需要我每轮说继续，也不在没有证据时宣告完成。

Claude Dynamic Workflows

如果 Codex Goal 解决的是“目标如何持续”，那么 Dynamic Workflows 解决的是另一个问题：单个对话已经协调不过来了。

大型代码库任务经常不是单点深挖，而是广域展开。比如扫描全仓 API endpoint 的鉴权缺口，迁移所有 deprecated API 调用，对几百个文件做相似结构改造，或者让多个 agent 从不同假设出发交叉验证架构方案。

这类任务交给一个 agent 顺序处理，很快会遇到两个问题：

• 主上下文会被中间材料淹没：grep 结果、日志、失败尝试、局部总结和临时判断不断堆进对话，真正的目标反而被稀释。
• 任务天然可以并行，却被单线程对话串行化：一个 agent 挨个看模块，时间成本线性上升，越往后上下文越脏，判断也越容易漂移。

Dynamic Workflows 的关键设计，是让 Claude 生成一段 JavaScript workflow 脚本，在后台运行，由脚本调度 subagents，而不是让主对话逐轮保存所有中间状态。Anthropic 文档里有一个关键边界：workflow 负责协调 agent，agent 负责读写文件和运行命令；workflow 脚本本身不直接访问文件系统或 shell。它还限制没有中途用户输入，除权限提示外不会暂停；默认最多 16 个并发 agents，单次运行最多 1000 agents，用来控制资源和失控循环。

这件事的本质不是“更多 agent 很酷”，而是：把计划、循环、分支、聚合和验证逻辑，从脆弱的自然语言上下文里抽出来，变成可读、可复跑、可观察的执行程序。

Dynamic Workflows 的关键词不是 autonomy，而是 orchestration。普通 subagent 模式里，主 agent 仍然要在对话中决定下一步；workflow 则把“怎么分阶段、怎么循环、什么时候聚合、如何交叉验证”写进脚本。它不是简单地增加 agent 数量，而是把多 agent 协作变成更稳定的运行时结构。

它最适合这几类任务：

• 可拆分：任务能切成相对独立的子问题，比如模块、接口、风险类型、迁移类别
• 可归并：中间结果能进入统一 schema，比如文件路径、风险等级、证据、建议、置信度
• 可验证：最终结果需要交叉核验，而不是每个 subagent 各说各话

所以，大型审计、批量迁移、多路研究、跨模块风险扫描，是 Dynamic Workflows 的典型场景。它的价值不在于“自动化程度更高”，而在于把并行探索、结构化归并和交叉验证固化下来。最成功案例：Bun 用 Claude Code 完成了 Zig → Rust 的重写。

但 Dynamic Workflows 也不能被神化。它更贵、更复杂，没有普通意义上的中途人工干预，也不适合需求还没想清楚的任务。尤其是多个 agent 同时修改同一批文件时，协调成本可能迅速超过收益。

更稳妥的策略不是一上来就多 agent，而是：先探索 -> 再规格化 -> 再设置 Goal -> 再小范围执行 -> 最后把可并行部分 workflow 化。

AI 编程不是越自动越好，而是越可控越好。Codex Goal 把“什么时候完成”变成合同，Dynamic Workflows 把“如何组织协作”变成程序。前者解决长程任务的持续推进，后者解决大规模任务的编排失控。它们共同指向一个趋势：agent 正在从会写代码的聊天框，变成有目标、有状态、有调度、有验证的执行系统。

一张原语地图

Subagent、Handoff、Workflow、Agent Teams 傻傻分不清楚，Agent 相关术语之所以容易混乱，是因为它们描述的是不同层级的控制权。

Agent：能围绕目标调用工具并持续行动的执行体

Agent 不是单纯的模型。它至少包含模型、工具、上下文、状态、权限、停止条件和外部反馈。

纯聊天模型回答问题；agent 在环境中行动。

Subagent：主 agent 派出去的子任务执行者

Claude Code 文档把 subagent 定义为处理特定任务的专门 AI assistant（Create custom subagents[7]）。它在自己的 context window 中工作，拥有自定义 system prompt、工具权限和独立 permission，并把摘要返回主对话。Anthropic 也特别强调：当某个 side task 会用搜索结果、日志或文件内容淹没主对话时，就适合交给 subagent。

Codex subagent[8] 概念类似：Codex 可以并行 spawning specialized agents，让它们探索、处理或分析工作，并把结果汇总回主线程；官方同时建议并行 agent 更适合 read-heavy 任务，比如探索、测试、triage、summarization，写-heavy 并行任务则要谨慎，因为会产生编辑冲突和协调成本。

所以，subagent 的本质是：

主 agent 仍负责最终判断；
子 agent 负责有界任务；
子 agent 返回摘要或工件；
控制权没有真正转移。

Handoff：把后续处理权转交给另一个 agent

OpenAI Agents SDK 中的 handoff[9]，是一个 agent 把任务委托给另一个专长 agent 的机制。文档举例说，客服场景可以由 triage agent 把订单、退款、FAQ 等问题转给不同专业 agent；handoff 对模型表现为一个工具调用，比如 transfer_to_refund_agent。

这和 subagent 不同：

subagent 是“你去查一块，回来汇报”。
handoff 是“这个问题之后归你处理”。

Workflow：把多个 agent 调用写成可执行流程

Workflow 不是 worker，而是编排器。

它决定什么时候启动哪个 agent、如何拆任务、如何等待、如何归并、如何校验、如何进入下一阶段。Dynamic Workflows 的价值正在于让 workflow 从自然语言计划变成 JavaScript 脚本。

Agent Teams：多个独立会话之间的协作

Claude Agent Teams 又是另一层能力。Orchestrate teams of Claude Code sessions[10] 文档说明，Agent Teams 允许多个 Claude Code instances 协作，一个 lead 负责协调，teammates 独立工作，拥有各自 context window，并能直接通信。它不同于 subagents：subagents 只能向主 agent 汇报，而 agent teams 的成员可以互相交流。

非对称性：AI 生成 & 人类审查

AI 编程真正危险的地方，不是它写不出代码，而是它写得太快。

代码生成正在变成低成本、可并行、可无限复制的动作；代码审查却仍然是高责任、强上下文、重认知负担的工作。于是软件工程出现了一个新的结构性非对称：机器可以在几分钟内生成几千行代码，人类却要花几小时甚至几天判断这些代码是否真的符合系统意图。

这不是普通的效率提升，而是瓶颈迁移：过去最贵的是写代码，未来最贵的是验证代码。

Stack Overflow 2025[11] 开发者调查给出了一个很典型的信号：84% 的受访者已经在使用或计划使用 AI 工具，但开发者对 AI 输出的信任并没有同步提升。只有 3.1% 表示高度信任 AI 输出，46% 表示不信任；在 deployment、monitoring、project planning 这类高责任任务上，开发者也明显更谨慎。

这说明，AI 的采纳率和可信度正在分叉。AI 可以快速生成“几乎对”的代码，而“几乎对”恰恰是软件工程里最危险的状态。语法错很容易发现，测试挂了也容易发现；真正麻烦的是那些局部合理、整体失稳的变更：

• 新增依赖打破部署约束；
• 复用工具函数破坏隐性语义；
• 为了过测试写出脆弱分支；
• 删除“看似无用”的兼容字段；
• 改善局部结构却破坏模块边界；
• 重构掉历史上为大客户保留的异常逻辑。

这些问题不是“代码写得慢”或“代码写得丑”，而是生成速度超过了验证系统的承载能力。AI 带来的新型技术债，不只是更多代码，而是更多表面完整、局部合理、缺乏系统意图约束的代码。它们看起来有测试、有类型、有错误处理，实际上可能没有真正对齐业务语义、架构边界和长期演进方向。

这就是比传统技术债更危险的“代码泥浆”：它不是一眼可见的混乱，而是披着工程完整性的外衣，把人类审查淹没在海量 diff 里。

AI 时代最重要的工程判断不是“如何让模型写得更多”，而是“如何让系统吸收得住”。不要试图用人类逐行审查去对抗机器批量生成，而要用规格、测试、静态规则、权限系统、审计日志、风险分层和可回滚机制，建立一套面向机器生成代码的吸收系统。

这正是 harness engineering 的意义：它不是让 agent 更自由，而是让 agent 的每一次行动都被目标、约束、证据和责任边界接住。

Engineering：Prompt → Harness

很多团队还停留在“怎么写好 prompt”。但 AI 编程越深入，prompt 的边际作用越有限。

Prompt 是一次性指令。
Harness 是可重复运行的工程系统。

Prompt 解决“这次怎么说”。
Harness 解决“每次怎么不失控”。

Anthropic 在 long-running agents[12] 的文章里总结了一个非常典型的失败模式：如果只给 agent 一个高层 prompt，比如“做一个完整应用”，即使有 compaction，agent 也容易一次做太多、上下文耗尽、留下半成品、下一轮又不知道前面发生了什么；或者看到一些进展后过早宣布完成。Anthropic 的应对方式不是写更神奇的提示词，而是建立 initializer agent、进度文件、feature list、init.sh、git commits 和结构化进度记录，让每一轮 agent 都能接力。

这就是 harness 思维：让 agent 在轨道上跑，而不是靠它自觉。

一个成熟的 AI 编程 harness 至少有六层。

1. 文档层：让 agent 读到正确上下文

Codex 支持 AGENTS.md，并且会在工作前读取这些文件。OpenAI 文档说明（Custom instructions with AGENTS.md[13]），Codex 会按全局、项目、目录层级构建 instruction chain，越靠近当前目录的文件越晚出现，因此可以覆盖更通用的指导。

Claude Code 对应的是 CLAUDE.md。Claude 文档明确说明（How Claude remembers your project[14]），每个 session 都从新 context window 开始，CLAUDE.md 文件用于提供 persistent context；但它也强调，CLAUDE.md 是 context，不是强制配置。要阻止某个动作，需要使用 PreToolUse hook 等机制。

这点极其关键：文档让 AI 知道应该怎么做。Harness 让 AI 不能越界。

因此，不要指望一句“不要破坏生产”就能约束 agent。真正的约束必须落在文件、测试、权限、hook、CI、review 和部署门禁上。

2. 目标层：把需求写成可执行合同

每个复杂任务都应该写成：

Goal：要达到什么终态
Context：相关背景、文件、历史约束
Constraints：不能破坏什么
Done when：如何证明完成
Stop when：何时必须停止并报告

这套结构适用于 Codex Goal，也适用于 Claude Code /goal，甚至适用于普通 agent 任务。

3. 测试层：把信任改造成验证

AI 生成代码越多，测试越不是“质量补充”，而是生产前提。

测试不只是单元测试，还包括：类型检查、lint、单元测试、集成测试、契约测试、端到端测试、性能 benchmark、安全扫描、golden master、snapshot、production log replay、shadow traffic comparison 等。

对 agent 来说，测试有一个额外意义：它给模型提供可重复、可解释的反馈信号。没有测试，agent 只能靠语言自我判断；有测试，agent 才能进入“改动—运行—失败—定位—修复”的闭环。

4. 隔离层：控制爆炸半径

不要让 agent 直接在主分支、生产配置或真实数据环境中自由行动。

默认应该使用：分支 / worktree、容器 / sandbox、只读探索模式、受限写权限、最小工具集、敏感命令审批、PR + CI、可回滚发布等。

AI 越强，权限越要细。因为能力越强的 agent，越可能通过你没想到的路径实现你没约束的副作用。

5. Hook / Guardrail 层：让错误在行动前被拦截

Claude hooks[15] 可以在生命周期特定点自动执行 shell command、HTTP endpoint 或 LLM prompt。文档示例中，PreToolUse hook 可以在 Claude 执行 Bash 之前检查命令，并阻止 rm -rf 等危险操作。

这代表一个重要思想：真正的安全不是“告诉模型别做”，而是“让系统在模型行动前检查”。

Claude 文档还提醒，command hooks 以用户系统权限运行，能修改、删除或访问用户可访问的文件，因此 hook 本身也需要审查和测试。

6. 审查层：从逐行 diff 审查转向风险审查

AI 时代 code review 不应继续幻想“人类看完每一行”。更现实的做法是风险分层：

• 低风险：文档、注释、测试补齐、局部样式，可更多依赖自动化和抽样。
• 中风险：业务逻辑、接口行为、数据处理，需要人类 reviewer + AI reviewer + CI。
• 高风险：支付、权限、认证、加密、数据迁移、生产基础设施，必须走设计评审、强测试、灰度、回滚方案和责任人批准。

未来 review 的核心问题不再是“这行代码写得怎么样”，而是：

• 这个变更是否符合规格？
• 是否破坏了领域不变量？
• 是否跨越了模块边界？
• 是否有测试证明？
• 是否可观测、可回滚？
• 是否改变了风险等级？
• 是否需要更新文档和 ADR？

这就是从写代码走向治理代码。

代码是负债，规格约束才是资产

这是本文最核心的转折，也是我 AI Coding 以来的观点！

在 AI 编程之前，代码通常被视为软件公司的核心资产。谁拥有代码，谁拥有产品实现、业务逻辑和竞争壁垒。

但在 AI 编程之后，这个判断要改写。

不是说代码没有价值，而是说代码的价值越来越不在“文本本身”，而在于它是否忠实实现了可验证规格。

因为代码有三个天然负债属性：

• 代码会腐烂：框架升级、依赖变化、安全规则变化、业务变化、运行环境变化，都会让代码持续过期。
• 代码会隐藏意图：代码告诉你“现在怎么做”，但不一定告诉你“为什么必须这么做”。AI 重构最需要的恰恰是“为什么”。
• 代码会制造审查负担：AI 可以快速生成大量代码，人类审查无法等比例扩展。

因此，未来更准确的表达是：代码是规格的一次编译产物。规格、约束、测试、架构决策和风险记录，才是跨模型周期延续的软件资产。

当 LLM 升级时，团队完全可能让新模型重写一部分实现代码。但它不能重写你的业务不变量、接口契约、合规要求、安全边界、兼容承诺、性能预算、历史架构决策和迁移策略。

没有这些约束，模型升级只会让混乱以更高速度发生。有了这些约束，模型升级才可能变成一次可控的再编译。这就是“代码是负债，规格才是资产”的真正含义。

AI 在老代码库中迷失

老代码库最难的地方，不是代码量大，而是关键知识不在代码里。

一个成熟系统里真正重要的信息，往往藏在这些地方：

• 某个字段为什么不能删
• 某个 API 为什么要返回奇怪格式
• 某个异常为什么必须吞掉
• 某个同步调用为什么不能异步化
• 某个表为什么不能强一致
• 某个“无用分支”为何承载了大客户历史逻辑
• 某个测试没覆盖但生产每天依赖

这些不是语法知识，而是系统意图。

AI 在老代码库中迷失，通常不是因为读不懂代码，而是因为它只能看到局部实现，却看不到全局约束。Anthropic 的 context engineering 文章也指出，长程任务需要 agent 在有限 context 下维持目标导向行为；等待更大上下文并不是根本解法，因为不同大小的 context window 仍会面对污染和信息相关性问题。

“把整个仓库塞给模型”不是答案，老代码库接管的真正问题是：AI 缺的不是更多文件，而是更高信号密度的系统地图。

如果没有系统地图，AI 会出现三类典型失败：

• 局部最优重构：它把某个函数写漂亮了，却破坏了模块间隐性契约。
• 测试迎合：它让现有测试通过，但只是学习了测试形状，没有恢复业务语义。
• 上下文腐败：任务越长，中间日志、失败尝试、临时假设越多，主上下文越容易被污染。前期资料也强调过，单体长会话会面临上下文腐败和记忆压缩失真，因此必须通过状态隔离、外部工件、subagent 或 workflow 来对抗熵增。

因此，AI 接管老代码库的第一原则不是“先改代码”，而是：先重建规格，再允许生成。

AI 接管老代码库

如果要让 AI 顺利接管一个庞大的老代码库，不应该从“改代码”开始，而应该从“测绘系统”开始。

Phase 0：只读接管

先让 AI 只读探索，禁止修改。

可以派多个 subagents 分别负责：模块地图、API 入口、数据库表、测试体系、构建部署、高风险逻辑、TODO / FIXME、权限与安全路径。

输出工件：

SYSTEM_MAP.md
MODULE_OWNERSHIP.md
DATA_FLOW.md
RISK_REGISTER.md
TESTING_BASELINE.md
UNKNOWN_QUESTIONS.md

目标不是修复，而是建立地图。

Phase 1：建立事实基线

每个结论都要标注证据等级：

CONFIRMED：代码 + 测试 + 文档共同支持
OBSERVED：由代码行为或日志观察支持
INFERRED：根据命名、调用链、注释推断
UNCERTAIN：无法确认，需要人类判断
CONFLICTED：代码、测试、文档之间存在冲突

这防止 AI 把推断写成事实。

Phase 2：冻结隐性行为

老代码库最大的问题是行为存在，但规格不存在。

这时要让 AI 做的不是重构，而是先把当前行为冻结下来：

golden master tests
snapshot tests
contract tests
API response fixtures
production log replay
shadow traffic comparison
database migration dry-run

没有行为锁定，就没有安全重构。

Phase 3：沉淀约束文件

为关键目录建立：

AGENTS.md / CLAUDE.md
ARCHITECTURE.md
DOMAIN_MODEL.md
TESTING.md
RISK_REGISTER.md

大型 monorepo 要就近放置约束。OpenAI 的 AGENTS.md 本身就支持从全局到项目再到当前目录的层级发现；Claude Code 也支持通过 CLAUDE.md、path-scoped rules、imports 等方式管理大项目上下文。

Phase 4：窄范围 Goal 执行

只有当规格、测试和约束到位后，才允许 AI 改代码。

每个任务都应该写成 contract：

目标：
将 payment timeout 处理逻辑迁移到新的 PaymentAttempt 状态机。

范围：
仅允许修改 services/payment、services/reconciliation 及相关测试。

保持：

- public API 响应结构不变
- timeout 不得直接标记 failed
- unknown 状态必须由 reconciliation job 关闭
- 旧版客户端兼容字段不得删除

验证：

- pnpm test payment-adapter
- pnpm test reconciliation
- pnpm test contract:payment-api
- 对比 fixtures/payment-timeout/\*.json

停止：
如果发现旧文档与当前测试冲突，停止并生成 CONFLICT_REPORT.md，不得自行选择一方。

Phase 5：每次变更反向更新规格

AI 修改完代码后，PR 不能只看 diff，还必须回答：

• 是否改变领域模型？
• 是否改变 API contract？
• 是否改变数据不变量？
• 是否新增风险？
• 是否需要更新测试说明？
• 是否需要新增 ADR？
• 是否改变 agent 操作规则？

未来成熟团队的 PR 模板应该长这样：

## 代码变更

...

## 规格变更

- [ ] ARCHITECTURE.md 已更新 / 不需要
- [ ] DOMAIN_MODEL.md 已更新 / 不需要
- [ ] API_CONTRACTS.md 已更新 / 不需要
- [ ] DATA_CONTRACTS.md 已更新 / 不需要
- [ ] TESTING.md 已更新 / 不需要
- [ ] RISK_REGISTER.md 已更新 / 不需要
- [ ] ADR 已新增 / 不需要

## 验证证据

...

## 风险与回滚

...

这一步最重要。否则规格会再次落后于代码，老系统会重新变成黑箱。

未来架构文档

传统架构文档经常有两个问题：写得太散，且不参与开发流程。

AI 时代，这种文档没有生命力。

未来的架构文档必须变成一种新的工程资产：可被 agent 读取、引用、检查、执行、更新的约束层。它不应该只是“系统采用微服务架构”这种介绍性文字，而应该清楚告诉 agent：

• 系统为什么存在
• 哪些事情不做
• 核心领域对象是什么
• 模块边界在哪里
• 依赖方向是什么
• 接口契约是什么
• 数据不变量是什么
• 哪些历史决策不能轻易推翻
• 哪些区域高风险
• 修改后必须运行哪些验证
• 不确定时必须停在哪里

个人建议，一个适合 AI 接管的成熟代码库，至少沉淀十类文档。

1. SYSTEM_CHARTER：系统使命与非目标

这类文档告诉 AI 系统的价值排序。没有价值排序，模型会为了“简洁”删掉历史兼容逻辑。

# SYSTEM_CHARTER.md

## 系统目标

本系统负责企业客户订阅计费、发票生成、支付状态同步和欠费处理。

## 非目标

- 不负责用户身份认证
- 不直接保存完整银行卡信息
- 不承担 CRM 客户生命周期管理
- 不在请求链路中直接调用第三方报表服务

## 优先级

1. 金额正确性高于性能
2. 审计可追溯性高于代码简洁性
3. 向后兼容高于接口美观

2. DOMAIN_MODEL：领域模型与不变量

这类文档比代码更重要，因为它定义了代码生成的语义空间。

# DOMAIN_MODEL.md

## 核心实体
- Account：计费主体，不等同于 User
- Subscription：订阅合同，决定周期与权益
- Invoice：账单，不代表已支付
- Payment：支付尝试，可能失败、重试或未知
- Credit：余额抵扣项，可正可负

## 不变量
- Invoice 一旦进入 issued 状态，金额不可变
- Payment 成功不等于 Invoice 已结清，必须检查 total_paid >= amount_due
- Subscription canceled 不代表立即停止服务，需要检查 grace_period

3. ARCHITECTURE.md：模块边界与依赖方向

AI 最常见的架构错误，是为了快速完成任务跨层调用。依赖方向必须写清楚，否则模型天然选择最短路径。

# ARCHITECTURE.md

## 模块边界
billing-core：计费规则与金额计算
payment-adapter：第三方支付网关适配
invoice-service：账单生命周期
entitlement-service：权益开通与关闭

## 依赖规则
- billing-core 不得依赖 payment-adapter
- payment-adapter 不得读取 invoice 数据库表
- entitlement-service 只能消费 billing events，不得同步调用 billing-core

4. API_CONTRACTS.md：接口契约

接口契约是 AI 重构时的生命线。字段一致不等于行为一致，模型必须知道语义承诺。

# API_CONTRACTS.md

## POST /v1/invoices/{id}/pay

### 保证

- 幂等键相同的重复请求必须返回同一 payment_id
- 4xx 错误不得触发支付网关调用
- 支付网关 timeout 必须记录 PaymentAttempt，状态为 unknown

### 禁止

- 不得在响应中暴露 gateway_raw_error
- 不得把 unknown 状态自动改为 failed

5. DATA_CONTRACTS.md：数据不变量

很多系统 bug 不是代码逻辑错，而是数据生命周期被破坏。

# DATA_CONTRACTS.md

## invoices

- amount_due 使用最小货币单位，禁止浮点数
- status 只能按 draft -> issued -> paid / voided 转移
- issued_at 一旦写入不得更新

## payment_attempts

- 每一次外部支付请求必须有一条记录
- unknown 状态必须由 reconciliation job 关闭

6. ADR：架构决策记录

ADR 的价值是告诉 AI：某些丑代码不是历史垃圾，而是经过权衡的结果。

# ADR/003-payment-reconciliation.md

## 背景

第三方支付网关 timeout 后可能实际扣款成功。

## 决策

同步支付接口遇到 timeout 时，将 payment_attempt 标记为 unknown，
由 reconciliation job 异步查询最终状态。

## 代价

用户短时间内可能看到“处理中”。

## 禁止

不得在同步链路中把 timeout 直接标记为 failed。

7. TESTING.md：验证命令与覆盖边界

注意，“测试没覆盖什么”同样要写。否则模型会把测试绿当成绝对正确。

# TESTING.md

## 修改 billing-core 后必须运行

pnpm test billing-core
pnpm test invoice-service
pnpm test contract:billing-events

## 修改 payment-adapter 后必须运行

pnpm test payment-adapter
pnpm test e2e:payment-timeout
pnpm test reconciliation

## 覆盖缺口

当前测试不覆盖老版 Android 客户端响应兼容，请勿删除 legacy_response 字段。

8. MIGRATION_PLAYBOOK.md：迁移策略

这决定 AI 是暴力重写，还是工程迁移。

# MIGRATION_PLAYBOOK.md

## 迁移原则

- 禁止一次性替换所有支付状态逻辑
- 必须先增加 shadow path，对比新旧输出
- 每个阶段必须保留 rollback flag

## 阶段

1. 增加新状态机，但不接入生产路径
2. 双写 payment_attempts_v2
3. 比对 7 天 reconciliation 结果
4. 只对内部租户开启
5. 按租户灰度

9. RISK_REGISTER.md：风险清单

AI 不知道哪些文件危险，除非你告诉它。

# RISK_REGISTER.md

## 高风险区域

- payment timeout handling
- invoice state transition
- subscription grace period
- tax calculation
- currency rounding

## 高风险变更规则

这些区域的任何修改必须：

1. 生成设计说明
2. 补充回归测试
3. 由人类 reviewer 审查
4. 提供 rollback 方案

10. AGENTS.md / CLAUDE.md：agent 操作手册

这就是 AI 时代的新 README。它不是给新人看的，而是给未来所有 agent 看的。

# AGENTS.md / CLAUDE.md

## 工作规则

- 修改前先阅读 ARCHITECTURE.md、DOMAIN_MODEL.md、TESTING.md
- 不确定业务语义时，不得猜测，必须标记为 UNCERTAIN
- 所有行为变化必须更新 API_CONTRACTS.md，或说明无需更新的理由
- 每次提交必须包含修改摘要、验证证据、风险、回滚方式

## 禁止事项

- 禁止引入新生产依赖，除非明确批准
- 禁止修改 public API，除非任务合同明确要求
- 禁止删除 legacy 字段，除非 compatibility matrix 已更新

AI 生成架构文档

AI 不只会乱写代码，也会乱写文档。更危险的是，AI 生成的架构文档往往非常像真的，却没有约束力。

所以，架构文档生成也需要 harness。

高质量 AI 架构文档必须遵守四条规则。

规则一：每个架构结论必须绑定证据

不要允许 AI 写：

系统采用事件驱动架构。

必须写成：

系统部分采用事件驱动架构。

证据：

- billing-service 在 invoice.issued 后发布 BillingEvent
- entitlement-service 订阅 BillingEvent 更新权益
- payment-service 仍通过同步 API 调用 billing-service，因此不是纯事件驱动

结论等级：OBSERVED

规则二：区分事实、推断和建议

架构文档必须分层：

## Facts

当前代码中可以直接确认的事实。

## Inferences

基于调用链、命名、测试推断出的设计意图。

## Risks

发现的风险。

## Recommendations

建议，但不是当前事实。

AI 最大的问题之一，是把建议写成事实。这个结构可以强制它隔离不确定性。

规则三：每个约束必须有违反检测方式

不要写：

模块之间应该低耦合。

要写：

约束：
billing-core 不得 import payment-adapter。

检测：
pnpm lint:boundaries
或
depcruise --config dependency-cruiser.config.js services/billing-core

没有检测方式的约束，通常只是口号。

规则四：必须输出不确定清单

## Unresolved Questions

1. legacy_response 字段是否仍被 Android 4.x 客户端使用？
   - 当前证据：API fixtures 中仍存在；无调用日志
   - 建议：查询最近 30 天客户端版本分布

2. invoice voided 后是否允许重新开票？
   - 当前证据：测试覆盖不足；代码路径存在 admin override
   - 建议：产品 / 财务确认

高质量 AI 文档的标志，不是什么都说得很肯定，而是能准确标注不确定性。

结语

讨论到这里，我们已经不只是在讨论 Codex Goal、Dynamic Workflows、subagent 或 handoff 这些工具概念。它们之所以重要，是因为它们共同指向一个更大的变化：软件工程正在从“人类手工生产代码”，转向“人类设计约束系统，AI 在系统内生产代码”。未来真正关键的问题，不再是“AI 能不能写代码”，而是“什么任务适合交给 AI、交给哪一层 agent、如何约束它、如何验证它、如何吸收它的产出，以及人类在其中承担什么不可替代的责任”。

这也是为什么我们不能迷信 agent。Goal、subagent、workflow、Agent Teams、handoff 并不是按照“高级程度”排列的工具，而是对应不同任务形状的工程原语。一个目标明确、需要持续修到测试通过的问题，适合 Goal；多个相对独立的探索任务，适合 subagent；大规模重复迁移、全仓审计、交叉验证，才适合 workflow；多个 agent 需要直接讨论、竞争假设、协作推进时，才需要 Agent Teams；而 handoff 的核心是责任和控制权转移，不是简单派工。成熟的团队不会问“哪个 agent 最强”，而会先问：这个任务是否可验证、是否可拆分、上下文是否可信、约束是否清楚、风险是否可控。任务不可验证，就不要自治；需求不清楚，就不要直接改代码；测试跑不起来，就先修 harness。

AI 带来的效率提升是真实的，组织重构也是真实的，裁员同样无法回避。但把趋势简单说成“程序员都会被替代”，并不准确。更准确的说法是：AI 会压缩低抽象、低上下文、低责任工作的价值，同时放大高抽象、高判断、高责任工作的价值。一个需求清晰、测试完善、文档健全、CI 稳定、权限严格、架构边界明确的团队，引入 agent 后会更快交付；一个需求混乱、测试缺失、文档过期、CI 不稳定、权限松散、架构腐烂的团队，引入 agent 后不会自动变强，只会更快地产生不可信变更。AI 不是组织解药，而是组织放大器。

因此，未来被替代的并不是“工程师”这个身份，而是那些缺乏系统判断、只承担低抽象实现工作的角色。只会按 ticket 写样板代码、不理解业务目标、不掌握系统设计、不会写测试、不会审查 AI 输出、不会拆任务、也不知道如何验证结果的人，会越来越危险。因为当 AI 能快速生成大量实现代码，这部分价值会被迅速压缩。相反，能够定义问题、设计系统、沉淀规格、构建验证闭环、识别风险、承担责任的人，会变得更稀缺。

工程师的比较优势会从“写代码速度”迁移到“定义正确系统”的能力上。未来强工程师更像问题定义者、系统架构师、规格工程师、验证工程师和 AI 编排者。他们不一定亲自写每一行代码，但必须能判断什么问题值得做，什么复杂度不该引入，哪些边界不能跨越，哪些测试必须补齐，什么时候应该用 Goal，什么时候应该拆 subagent，什么时候应该 workflow 化，什么时候必须人工介入。代码生成变快之后，错误抽象的代价会更高；agent 越强，约束和验证就越重要。

对普通人来说，真正该补的也不是几个 prompt 技巧，而是把想法转化为清晰任务的能力、真实领域的理解能力，以及最低限度的工程素养。AI 降低了生产门槛，但没有降低判断门槛。一个不懂代码的人，如果能清楚描述目标、用户、成功标准、边界条件、风险和验收方式，也可以借助 AI 做出有价值的东西；一个会写代码但不会定义目标的人，反而可能被 AI 的输出牵着走。未来竞争不是“会不会打开 AI”，而是你有没有一个足够深的领域，让 AI 放大你的判断。

从趋势看，软件工程会逐渐变成 AI 生产系统工程。IDE 会从编辑器演化为 agent 调度台，开发者面对的不只是文件树，而是任务队列、agent 状态、上下文地图、测试结果、风险报告、PR 队列、部署门禁和回滚记录。Workflow-as-Code 会变得重要，就像 Infrastructure-as-Code 把基础设施配置化一样，未来团队也会把安全审计、API 迁移、测试生成、依赖升级、事故排查、老代码库接管等复杂任务沉淀成可运行、可复用、可审计的 workflow。文档也会重新成为核心资产，因为 AI 需要清晰、最新、结构化、可检索的上下文。AGENTS.md、CLAUDE.md、ARCHITECTURE.md、TESTING.md、RISK_REGISTER.md、ADR 这些文件，不再只是给新人看的说明书，而会成为 agent 的操作系统配置。

更深一层看，代码本身的资产属性会下降，规格约束的资产属性会上升。代码会不断被生成、替换、压缩、迁移，甚至被下一代模型大规模重写；但真正不能丢的是领域模型、业务不变量、接口契约、数据契约、架构边界、安全策略、性能预算、合规要求、测试体系、风险登记、运行手册和历史决策记录。没有这些约束，模型升级只会让混乱以更高速度发生；有了这些约束，模型升级才可能变成一次可控的再编译。

Codex Goal 和 Claude Dynamic Workflows 表面上是两个工具能力，实质上代表的是同一场范式迁移：从补全代码到执行任务，从一次提示到持久目标，从单个 agent 到多 agent 编排，从人类写代码到人类治理代码生产系统，从代码作为资产到规格约束作为资产。AI 会让代码越来越便宜，但它不会自动让系统越来越好。当代码生成速度超过人类审查速度，真正稀缺的会变成清晰目标、正确抽象、有效约束、自动验证、架构判断、领域理解、风险治理和责任承担。

最终，AI 编程时代最值得记住的不是“以后不用写代码了”，而是：未来最强的人，不是写代码最快的人，而是最会定义目标、沉淀规格、设计约束、验证结果、治理 AI 生产系统的人。代码可以被下一代模型重写，但系统为什么存在、什么不能破坏、怎样才算正确、失败时如何回滚、风险由谁承担，这些问题仍然需要人类回答。这不是编程的终结，而是编程从手工业进入 AI 工业化生产之后，人类重新寻找控制点的开始。

References