AI Coding 可靠落地软件工程，瓶颈从来不在模型

多数人的注意力还停在「哪个模型写代码更强、哪个 Agent 跑分更高」上。我更关心另一个问题：你的系统，是不是一个 AI 能看懂、能动手的环境。

给 AI 一个全新项目，它一般表现不差。没有历史包袱，技术栈是公开的，架构简单，规模也压得住。

可要是把它扔进一个跑了十几年的存量系统，情况就反过来了。它不知道这个页面算不算业务入口，不知道这个接口归哪个服务、能不能跨中心调用，不知道这个字段来自哪张表；更不知道这条规则是全国统一，还是只在某个省生效。

所以我习惯把 AI 软件工程拆成三层看。缺哪一层，AI 都只是「看起来会写代码」，还谈不上「像系统里的人」。

「注册的时候加一个手机号重复校验」。需求就这么一句话，微信群里发过来的，连附件都没有。

代码很快就出来了，编译通过，测试也是绿的。架构师扫了一眼，说：改错地方了。

这两年推 AI 研发工具链，被问得最多的一句是：模型都能写代码了，还折腾这么多规范和流程干嘛？

我的答案这几年没变过：先别急着换模型。它改错地方，多半是因为从来没人告诉过它，地方在哪。

就拿这条需求当例子，它是后面每一节的贯穿范例：

这三个坑，模型一个都答不上来。不是它笨，是它手上没有依据。

我一直不太喜欢把 AI 软件工程说成「一个更聪明的编程助手」。它更像三层环境叠在一起：

很多人把力气全砸在第一层，把 Prompt 写得更长更细，后两层却没怎么管。这大概就是企业 AI Coding 的分水岭。

有个反直觉的地方：Prompt 写得越细，反而越容易把问题盖住。因为多数时候，问题不是你说得不够多，是该它知道的事，它压根无从知道。

我更愿意把它理解成一次分工重切：把研发流程重新切一遍，每一段里人和 AI 各干什么，都得说清楚。

这张表里有一条线，我认为是整套方法能不能跑通的关键：

决策权和事实裁决权留在人手上，生成和执行的工作量交给 AI。这条守住了，团队就不会掉进「AI 写了一堆、没人敢签字」的窘境。守不住，就会听见那句话：「AI 检查全部通过」。

Checklist 全绿，不等于事实正确。 AI 自检全过，人再去抽查时序图和接口字段，照样能翻出语义丢失。这种事我见过不止一次。

这条需求落在五个阶段里，各自要交付什么、谁签字，也很清楚：

这一节是我最想让你看的。同一条需求，在五个阶段各留下什么真实产物，走完你会发现：「AI 软件工程」落下来，就是一堆能照着抄的文件。

第一步，落项目宪法。它是这个项目所有需求的共同约束，写一次、长期生效：

第二步，澄清（clarify）：AI 提问，人来裁决。全流程里我觉得最值钱的就是这段对话：

五轮问答下来，一句话变成了 5 条可验证的判定条件。这五条不是 AI 拍的，是人一句句确认过的。

最后两个问题尤其值钱。没有 Context，AI 根本不知道旁边还有个「开通子账号」的兄弟流程，也不知道规则有分渠道的口径。

第三步，Spec 定型，再谈怎么做。产物很朴素：业务规则 R1–R5（什么条件下触发、什么状态算「已注册」、命中返回什么错误码、在哪一层拦、是否分渠道），验收口径 A1–A5（命中 1 个账号怎么提示、超过 3 个怎么提示、只有已注销记录要放行、开通子账号不触发、接口超时要放行且告警），再配一份技术方案：影响哪几个服务、改哪几个文件、配置项叫什么。

最典型的一幕在这里。AI 没有新写一条查询 SQL，而是先去 Context 里翻，发现用户中心已经有现成接口，直接复用。复用而非新写，宪法里写着 C2 嘛，禁止直连对方库表。

有 Context 和没 Context，差别就是这么具体。

第四步，Coding。AI 生成的代码里带着注释，标着每条规则对应哪条约束，顺手把错误码登记、配置项、4 条单测一起出了。

AI 写代码和写测试是一步完成的，这点和人差别最大。不过测试到底有没有覆盖到该覆盖的地方，还是人说了算。

第五步，测试要过四层，最后一层最容易漏：

第四层是我们踩过的坑。功能全过，可 Context 已经悄悄过期了。这次不修，下次 AI 拿着旧事实卡做需求，还会再错一遍。

发布还有三个动作。灰度：先放 5% 流量，观察 24 小时。监控：盯错误码触发次数、接口 P99、放行告警计数。回滚：一个配置开关关掉就行，不用回滚代码。开关做进配置，是这类校验需求的标配。

最后一步是回流，这一步才是重点。这次确认了两条可复用的知识：跨域查用户账号一律走用户中心指定接口；账号状态口径要跟会员侧对齐。它们写回 Context，下一个需求就能直接用。

一条需求走完，系统里多了三样东西：一段受规范约束的代码、一份被校正过的 Context、两条能复用的知识。 我说的「知识跟着真实需求生长」，就是这个意思。

我们那套流程里，最基本的一条是：规范（Spec）是唯一事实来源。需求、设计、代码、测试、文档都对着它对齐，谁也别各说各话。

可 Spec 不会凭空长出来。它得有三类输入，缺哪一类都容易写偏：

① 用户的 Prompt：意图、边界、验收期望，决定「做什么」；

② 本体 / 行业知识：领域模型、术语体系、合规要求。它决定 AI 用的词和业务对不对得上，不至于把「订单取消」和「订单退款」混成一类流程；

③ 内部知识库：业务规则与系统现状。哪条规则全站统一、哪条只在某个渠道生效，这个接口归哪个域、允不允许跨中心调用。

同一个需求，只给 Prompt 和给三类输入，差别有多大？

差别不在 AI 聪明不聪明，在它有没有可能知道这些事。

这里有个误区得说清楚：把文档堆给 AI，不等于给了 AI 知识。

不少团队一上手就建目录、疯狂写 Markdown，业务规则一份、架构一份、接口一份、数据库一份，攒到几百份，跟 AI 说「你都看看」。这不过是把企业 Wiki 搬到了 AI 面前。

更靠谱的做法是让对的信息在对的时间、以对的粒度进模型：给 Agent 一张地图，别给它一本一千页的说明书。

我习惯把企业的 Context 分五层。前两层是指令和工具，管什么不能做、什么能做。第三层是技能，也就是开发的 SOP。第四层是项目知识，业务规则、架构边界、数据模型、API 契约、代码模式、私有技术栈都装在这一层。最后是运行时，装当前这条需求、对话历史，还有已经验证过的证据。

第四层是绝大多数企业最缺的，也是最值得投的。我一般按三档来组织：地图 → 目录 → 事实。

地图不解释知识，只说三件事：有哪些知识、在哪、什么时候该加载。AI 接到「注册加校验」这个需求，命中加载条件，就只去拿用户中心和注册服务这两小块，不用把整个系统吞下去。

事实是一张卡记一条知识。关键是它得带着几个字段：证据等级（这句话凭什么可信）、状态（说的是现状还是目标）、依据（源码位置、配置项、接口签名）、谁签的字、什么时候验的。缺一个都会出问题。

没有这几个字段，一条知识就只是「有人这么写过」。

证据分级最容易含糊，也最容易让 AI 钻空子：

AI 很容易把「我猜这个接口应该是这样」写成「系统就是这样」。这两句话，差得远。

还有一条边界容易忽略：现状（current）和目标（target）不能混。

举个我踩过的例子。文档里写着同步调用，代码里其实是异步。别急着说「那代码才是真的」，因为这次需求搞不好就是要把同步改成异步。所以现状卡和目标卡要分开放，别直接把旧的那张改掉。

最后一句提醒，是我见过最多的自伤：别为了「好读」，把 Context 压坏了。

很多人嫌文档长，压一压。压掉的往往是分支条件、接口字段、异步关系、异常路径这些最要命的地方。Context 工程要的是最小必要 Context，不是最短 Context。提炼和精简，是两回事。

前面几节讲的，说到底还是「怎么把一条新需求做对」。可企业里九成的活不是新需求，是存量系统上的改造。这种场景下，Knowledge 的分量还要再加一层。

绿地项目和存量项目，最大的差别不在难度，在你一开始根本不知道自己在改什么。

给 AI 一个全新项目，它的假设基本成立：目录干净、命名一致、没有历史包袱。把它放进一个跑了十几年的系统，假设全都不成立。

① 需求文档要么没有，要么停在好几年前。代码成了唯一还活着的事实，可代码只回答「现在怎么做」，答不了「为什么这么做」；

② 业务规则散在代码分支、配置表、历次工单和老人脑子里。同一个状态字段，在注册模块和在会员模块里，含义可能就不是一回事；

③ 你看到的每一行旧代码，背后都可能有你不知道的调用方在依赖。

所以存量改造的第一件事，不是「补文档」，是逆向理解：把已有的业务需求，从系统里重新读出来。

从哪读？按可信度排，四个来源：① 代码分支与校验逻辑，先分清哪些 if 是真业务规则、哪些只是防御性判断；② 数据表结构与状态枚举，业务对象的生命周期全写在这儿；③ 接口契约与调用方，谁在依赖它，改一下会波及谁；④ 测试用例和线上日志，记的是真实发生过的行为，不是「文档说应该发生」的行为。

读完要产出一张既有行为基线。措辞很重要：写的是「实际怎么跑」，不是「应该怎么跑」。

有了基线，第二步最值钱，也最容易被跳过：判断改动边界。

我自己的规矩是，动手前先把涉及的点标成三档：

这张表其实是给 AI 看的。AI 的默认行为是「既然看到这行代码，顺手把它改优雅点」，这在存量系统里就是灾难。你必须在 Spec 里明确告诉它：哪些是本次的非目标。

第三步，设计。存量改造的设计原则就一句：顺着现有结构走，别追求理想架构。 优先复用系统已有的扩展点，比如策略、钩子、配置项、已有的领域接口。新逻辑用开关包住，旧逻辑尽量原样留着，保证能一键退回去。

代码实践上也没什么玄学。改动面尽量小，不顺手重构，注释里标清楚「这条改动依据哪张事实卡」。顺手重构是存量改造里最常见的自伤，它会把一次范围可控、能回退的改动，变成一次没人说得清影响面的变更。

第四步，自动测试。这一环，存量改造和绿地项目差别最大。绿地写测试，第一目的是「证明我做对了」；存量改造写测试，第一目的是「证明我没碰坏别的」。

所以顺序也反过来：先给既有行为补特征测试（characterization test），把系统当前的行为固定下来当基线，哪怕这个行为本身是错的；再写本次需求的验收用例。因为「当前这个错」很可能已经被上游依赖着，你顺手纠正一下，就是一次计划外的破坏。

再往上还有一层：跨域调用加契约测试，守住服务边界。回归跑得动的存量系统，AI 才敢在里面做改动；跑不动的系统，给它再强的模型也只敢做加法。

不过这套「读懂旧系统」的动作，不能只做一次。

存量系统每天都在变。有人加字段，有人改状态枚举，有人开新接口，还有人悄悄下线一个服务。你今天刚建好的事实基线，下个月可能就对不上。

所以本体、WIKI、存量系统与数据库这三类知识来源，都得定期扫描，把「变了什么」重新扫回 Knowledge 层：

扫描这件事本身最适合交给 AI，它可以每天把全量代码和库表结构扫一遍，人没那个必要。但「这条差异要不要动事实卡、动哪一张」，还是得人签字。扫描的意义不是重写知识，是把系统和人的认知差，变成一张看得见、可裁决的差异清单。

在存量系统里，AI 最大的风险不是「改错地方」，而是「改对了地方，碰坏了别的地方」。Knowledge 的作用，就是把「哪里不能碰」变成 AI 看得见的约束。

知识不会因为「整理过一次」就永久可用。我的做法是让它跟着真实需求长，四个动作循环着做，每个动作都留下一份看得见的东西。

① 找缺口（Discover）。需求来了先别急着写代码。我一般让 AI 先交一份「缺口清单」：它已经知道什么，还缺哪几条，比如状态枚举有没有取全、有哪些合法的查询接口、这条规则分不分渠道；还有哪些得人去问，比如会员侧的口径是不是一致。

以前是人告诉 AI 该看什么，现在反过来，AI 自己说清它缺什么。这张清单丢给架构师，十分钟就回填完了。

② 补知识（Update）。AI 提出、人确认、再入库，最后产出一份变更报告：新增了哪张事实卡、修订了哪条规则、索引多了几条映射、谁确认的、依据是什么。

不是 AI 说什么就记什么，得走一遍「AI 提出 → 人确认 → 制定合并方案 → 写入 → 同步索引 → 变更报告」。因为错误的 Context，比没有 Context 更危险。

③ 做回流（Harvest）。合并完再问一句「这次有没有发现新知识」。本次发现 2 条，都涉及注册类需求的跨域查询，建议提为通用 Context。

④ 定期体检（Review）。每周做一次只读体检，只给建议、不动知识库：哪几条事实卡超过 90 天没复核、哪两处描述互相冲突、哪几段说明冗余、通用知识和临时知识有没有混放。外加一件必查项：本体、WIKI、存量系统与数据库的定期扫描有没有按时跑完，扫出来的差异清单处理了没有。

这跟代码治理是一套思路。

有一点要注意：整条回流线上，「人确认后回写」这个动作不能省。扫描代码、分析调用链、执行修改、跑测试、出报告，AI 都能干得又快又好。可业务事实到底是什么、两套架构描述哪个对、一条规则算不算全局规则、一个高风险改动能不能上，这些它不该独立拍板。

先说不要做的：

① 不要把模型当外包：只丢一个 Prompt，不给系统知识，然后抱怨它改错地方；

② 不要成立专项组，一次性把系统整理完：几个月后交出一套厚厚的「AI 知识库」，可真要写代码的时候，AI 还是找不到那段代码。脱离真实需求整理出来的知识，抽象层次对不上，放着放着就过期，还容易把一次性的需求当成通用规则；

③ 不要把 Prompt 写成小说：问题通常不在「说得不够多」，在「该知道的它不知道」；

④ 不要为了好读压坏 Context：上面说过了，不重复；

⑤ 不要把「AI 检查全部通过」当质量结论：AI 负责扩大检查覆盖面，最终裁决还是人的事；

⑥ 不要把人从关键节点上撤掉：需求和验收标准、方案取舍、上线与回滚，这三个节点的签字权必须在人手上。

再说怎么起步。这件事不用一上来就建「企业级 AI 知识中台」，也不用先拉十几个人成立专项组：

回头看，整条工具链其实只讲清四件事：把规则写清楚、从规范自动生成、渐进式改造、知识沉淀。收益也挺朴素：延期少一点，返工少一点，文档准一点，人不在了知识还在。

这两年吵得最凶的，是哪个模型写代码更强、哪个 Agent 跑分更高。这些当然重要。可真进了企业你会发现，有个变量几乎没人提：你的系统，到底是不是一个 AI 可以理解和工作的环境。

如果架构知识都装在某个架构师脑子里，业务规则散在微信群里，接口说明堆在各种文档里，代码边界不清，测试跑不起来，历史决策也查不到。那换上最强的模型，AI 也很难稳定干活。

反过来，如果业务知识、系统架构、数据模型、代码模式、工具、技能、规则、测试、历史决策，慢慢都变成 AI 能发现、能读取、能调用、能验证的工程资产，那模型每强一次，整个团队都跟着受益。

设计环境、明确意图、建立反馈回路，这三件事做扎实了，AI 才算真正成了系统里的工程师。