前言
AI 编程的问题往往不在模型，而在工程：上下文召回不到/不全/不对，导致越改越乱、规则与接口漂移、正确性无法证明。我用“文档即代码”的顶层设计把真相结构化：System Manifest 做项目地图、 规则做唯一真理、契约固化边界、移交单让变更可追踪。本文主要讲 AI 编程的通病以及这套体系如何对症下药。
AI编程越来越强，为什么你的项目越做越烂
先说一个 暴论 ：市面上所有的ai编程工具技术路线都是存在缺陷的，都是在通过搜索的问题来解决上下文的问题，他这里有几个解决不了的问题
- 召回的数据不全
- 代码中存在噪音，如：废弃代码，同名不同含义的命名等
- 代码中信息不全，部分逻辑在配置、在运行时注入
AI编程工具通过搜索手段去构建上下文，但是这是在管中窥豹，效果其实是有上限的。
很多团队在引入AI编程之后，交付速度开始的确变快了，但是项目却越来越难维护。这里不是说工具不好用，模型不够强，而是缺乏顶层设计去约束AI，让AI编程可控、可持续迭代。
这篇文章我只讲两件事：
- 现在 AI 编程最常见、最致命的弊端是什么
- 文档即代码 为什么能系统性解决这些弊端
1. AI 编程的 4 个通病
通病 1：上下文召回不可靠
AI 写代码的前提是：它得先拿到“真相”。
但现实是：
- 关键规则在 PRD、飞书、会议纪要里，不在仓库里
- 同一个概念在不同模块叫不同名字（或反过来：不同概念叫同一个名字）
- 它搜到了接口，却没搜到业务规则；搜到了实现，却没搜到最新变更 于是它只能靠猜。
最可怕的是：它猜得往往还挺像那么回事。
通病 2：边界意识差
AI 很喜欢“顺便帮你优化一下”。
典型表现：
- 修个 bug，顺便重构目录结构
- 加个字段，顺便把接口语义也“优化”了
- 改个测试，顺便把规则改成“更好测”的版本，它觉得自己在做好事，你觉得它在“越级执法”。
通病 3：规则、契约、实现三者漂移
当系统里没有“唯一真理”时，就会出现三份互相背离的真相：
- 业务规则（人以为的）
- OpenAPI 契约（文档里写的）
- 代码实现（实际跑的） AI 加速了这个漂移：因为它能同时写这三样，而且每样都写得像真的。
通病 4：正确性不可证明
没有明确验收口径时，你对 AI 输出的评估方式只剩一种：
“看起来合理。”
工程里最贵的成本，就藏在“看起来”三个字里。
2. 根因：不是检索不够强，而是缺乏寻找真相的依据
很多人遇到上下文问题的第一反应是：上 RAG、上向量库、上更强模型。
这些当然有用，但它们解决的是“搜的工具”，不是“被搜的对象”。
如果你的系统里：
- 真相散落在仓库外
- 同一个概念多套说法
- 文档不版本化、不评审、不追踪
- 规则没有可验证表达 那再强的检索也只能把“碎片”捞得更快一点。
AI 依旧会在碎片之间补全它认为最合理的世界。
你依旧会在上线后发现：它补的是另一个世界。
3. 文档即代码：我怎么用顶层设计去约束AI
先澄清一句： 文档即代码不是让大家写更多文档。 它做的是一件更工程的事：把“真相”变成可寻址、可版本化、可验证的资产，让 AI 沿着正确路径加载上下文，而不是在全仓库盲搜。
我用四个顶层机制，对应解决四类通病。
3.1 System Manifest：给项目一张地图（治“召回不可靠”）
我把 system_manifest.json 当成项目的 DNA / 入口索引。
它明确：
- 模块在哪（backend / frontend / docs）
- 命令入口是什么（test / lint / typecheck / build）
- 契约在哪里（OpenAPI 来源目录）
- 生成到哪里（前端 client 输出目录）以及“禁止手改生成目录” 好处很直接： AI 不再“先搜再说”，而是“先定位再深入”。 上下文召回从“碰运气”变成“按地址取”。
3.2 L1-L4 分层：把真相分类型管理（治“越界”和“漂移”）
分层的关键不是形式，而是让不同真相各归其位：
- L1：系统边界与上下文（决定“去哪找”）
- L2：模型与不变式（决定“怎么理解”）
- L3：业务规则（决定“什么算对”）
- L4：接口契约（决定“怎么对齐前后端”） 这样 AI 在做事时，不会把“业务判断”写进接口文档，也不会把“接口妥协”写进业务规则里。
更重要的是： 分层天然带来权限边界 ——谁能改什么，一刀切清楚。
3.3 L3 作为唯一真理：把“正确性”做成可验证（治“无法证明”）
我强制规定：业务规则的唯一真理是 L3（场景/规则），而不是某段实现或某份口头对齐。
当规则写成可验收的形式时，AI 的工作从“写看起来对的代码”，变成“把规则跑通”。
你要的不是 AI 的灵感，是它的可验证。
3.4 结构化移交单：把协作从聊天升级为指令（治“变更不可控”）
每次变更必须输出结构化移交单，说明：
- 这次改动意图
- 影响范围（哪些模块/哪些接口能力）
- 具体变化（字段级、接口级）
- 下一步由谁做，怎么做 移交单的价值在于： AI 不用猜你要改什么，它拿到的是可执行的变更合约。
4. 一个你一定遇到过的翻车点：OpenAPI 到底谁来改？
如果让 AI 自由发挥，最容易发生的就是：
“我改了实现，为了对齐，我顺便把 OpenAPI 也改了。”
听起来很贴心，工程上却很危险：契约变更应当是可评审、可追踪、可讨论的决策，而不是实现过程中的副产品。
在我的体系里：
- 架构师只给“接口影响提示”（范围），不改 OpenAPI
- 领域专家负责把提示落到字段级契约变化（L4），并输出给程序员
- 程序员只按移交单实现；发现契约不够用，必须上抛，不准私改
5. 实践怎么开始
最小闭环就够：
- 先补一个 Manifest（让项目可寻址）
- 为一个需求写 L3（让正确性可验证）
- 再写 L4（让前后端对齐可复现）
- 实现按测试闭环推进（让漂移难以发生） 当这个闭环跑通，你会很明显地感觉到： AI 不再“随缘写”，而是“按规矩交付”。
结尾：AI 时代最值钱的能力，是让产能不变成风险
AI 能帮你写 10 倍代码，也能帮你制造 10 倍“看起来合理的隐患”。
你需要的不是更强的补全，而是更强的顶层设计：
- 真相可寻址（Manifest + 寻址协议）
- 变更可追踪（版本化 + 评审）
- 正确性可验证（L3 规则 + 测试闭环）
- 协作可执行（结构化移交单） 把这些做成系统能力后，AI 才会从“概率写手”变成“受控工程师”。
招人 Tips
我们团队正在招 AI-Native 工程师（初 / 中 / 高） 。如果你想在 AI 时代获得更快、更硬核的技术成长，这里有三个你会持续练到的能力：
- 顶层设计能力 ：从需求到边界、从模型到规则，学会把复杂问题拆成可交付系统
- 工程化能力 ：契约驱动（OpenAPI）、测试驱动（TDD/ATDD）、自动化与质量门禁，把“经验”沉淀成体系
- 驾驭 AI 的能力 ：上下文管理、约束与纠错，让 AI 放大你的判断力，而不是替你瞎猜
如果你愿意把自己从“写代码的人”成长为“能定义标准的人”，欢迎私信/评论我
