AI写代码总改错地方？Harness工程踩坑实录：90%团队都走偏了
企业做 AI Coding，从来不是工具问题，而是系统工程问题。
很多人试图把 AI 从写代码工具升级为系统协作角色，也通过度量与可观测让事情变得可管理。
但真正的分水岭，不在能不能用，而在：能不能长期稳定演进，而不是三个月后崩掉。
这一篇，我们只做一件事：👉 把企业在 Harness（工程驾驭层）建设中最容易踩的坑，讲透。
一、最常见的第一个误判：把问题当成检索问题
需求来了，让 AI 改代码，最怕什么？
不是 AI 漏改，而是 AI 多改了。比如：用户取消订单的场景，需求要求加一段逻辑，但同样的入口，订单超时关闭也在调用。AI 改了取消订单的流程，超时关闭的行为也跟着变了，但没人发现。
于是开始做：
- Code Graph：方法索引、调用关系、结构标签
- 向量检索：让 AI 能快速定位相关代码
动机是合理的：没有 Code Graph，AI Agent 只能一次次调用 bash 工具执行 grep，效率低还容易漏。有了 MCP + Code Graph，AI 可以直接判断出影响面和改动的爆炸半径，一次调用就知道哪些地方会受牵连。
但这个方向隐含了一个前提假设：Code is Document（代码即文档）
这个方向的问题是什么？
短期是有效的，但很快会遇到三个问题：
1. AI知道改哪里，但不知道该不该改
它可以回答：
- 哪些接口相关
- 哪些 service 会被影响
但回答不了：
- 为什么这个字段不能删？
- 为什么这个逻辑不能动？
- 为什么这个接口设计这么奇怪？
👉 因为这些信息不在代码里。
2. 在复杂系统中，影响范围判断会失真
当系统出现：
- 异步消息链路
- 跨服务调用
- 历史兼容逻辑
AI 会出现典型问题：路径找对了，结论错了。
3. 索引系统本身变成隐形技术债
- 标签需要维护
- 索引需要更新
- 一旦滞后 → 检索质量下降
最后变成：你在维护一个半成品知识库，但你自己没意识到。
二、第二个极端：过度建设知识库
另一类团队走向了反方向。
动机也很合理。
在企业的真实环境中，一个成熟的业务系统轻松十万行代码，从前台到管理端到数据分析端，涉及的角色和功能点特别多。一个需求过来，AI 首先要搞清楚：改哪些功能？涉及哪些模块？分析怎么改？
但问题是，从需求到代码，中间的转化是有误差的。代码注释不够、命名不够规范，AI 就无法精准定位到该改哪里。十万行代码里找一个逻辑入口，靠 AI 自己读代码，准确性没法保证。
所以团队的想法是：把业务知识补全，用知识库来弥补 AI 理解力的不足。
于是开始建设：
- 架构文档
- 业务文档
- 隐性约定
- 数据库清单
- 接口清单
这对应另一种思路：用知识补全来对冲 AI 的不确定性。
这个方向的问题更隐蔽
1. 文档维护成本极高，几乎必然失效
现实情况是：
- 三个月后，没人更新
- 六个月后，文档失真
- 九个月后，没人再信
2. 文档与代码脱节，反而误导 AI
最危险的情况不是没文档，而是：
- 文档说 A
- 代码是 B
- 实际行为是 C
AI 会优先相信文档 → **得出错误结论。**比没有文档更危险。
3. 不符合大模型的优势路径
当前大模型的能力特点很明确：
- 强于：代码理解、局部推理
- 弱于：文档真实性判断、长期一致性
👉 结果就是：文档越多，不一定越好，甚至可能更差。
三、核心误区：把 Harness 当工具，而不是系统
无论是代码派还是知识派，本质都有一个问题：把 Harness 当成一个能力点，而不是系统架构。
但 Harness 的精髓是：**用稳定可靠的技术手段，替代 AI 不够精确的部分。**不是让 AI 更聪明，而是让 AI 在不确定的地方被约束住。
它本质上是一个系统认知层。
它要解决的是：
- AI 怎么看系统
- AI 怎么理解影响
- AI 如何避免错误
- 系统如何自我进化
四、正确路径：三层结构，而不是两种流派
经过多轮实践，我们最终收敛出一个更稳定的结构：
第一层：Code Graph / 代码图谱（事实层）
解决问题：系统长什么样。
包含：
- 方法索引
- 调用关系（call graph / 调用图）
- 标签（自动生成）
👉 这是 AI 的感官系统。
举个例子：一个支付接口改了返回值，Code Graph 能立刻告诉你哪些方法在调用它，但不知道这个改动会不会引发业务问题。
第二层：Flow Graph / 流程图谱（路径层）
解决问题：请求是怎么跑的。
包含：
- API → service → DB → MQ 的完整链路
- 定时任务链路
- 外部依赖
👉 这是 AI 的血管系统。
接着上面的例子：Flow Graph 能告诉你这个支付接口的返回值，会被异步消息转发到对账系统，但不知道对账系统有兼容逻辑，删掉旧字段会导致对账失败。
第三层：Memory / 经验记忆（约束层）
解决问题：系统不能犯什么错。
只保留三类信息：
- 业务约束（必须遵守）
- 事故记录（踩过的坑）
- 架构决策（为什么这么设计）
👉 这是 AI 的经验系统。
同一例子：Memory 里有去年的一次事故记录：旧字段被删后对账失败，所以这个字段不能动。三层一起，AI 才能真正安全地改代码。
五、最大的分水岭：有没有自进化能力
前面三层解决的是：让 AI 能用。
但企业真正需要的是：让系统越来越好用。
这就进入下一阶段：👉 Self-evolving Harness / 自进化驾驭系统。
六、第三个坑：以为自动化 = 自进化
很多团队会尝试：
- 自动提取文档
- 自动生成规则
- 自动学习经验
但很快会翻车：垃圾进 → 垃圾出。
真正的自进化必须具备三个引擎
1️⃣ Risk Engine / 风险引擎
作用：在改代码前就告诉你：哪里可能炸。
核心逻辑：
- diff → 向量化
- 匹配历史事故
- 输出风险等级
没有它：每次上线都是在赌博，AI 改了一行代码，你不知道会不会引爆三个月前埋的雷。 有了它：AI 动代码之前，系统自动告诉你这片区域上个月出过 P0，建议加测试。
2️⃣ Constraint Engine / 约束引擎
作用：在生成代码时强制遵守规则。
例如：
- 状态不可逆（已支付不能回退为待支付）
- 操作必须幂等（同一请求不能重复扣款）
👉 防止 AI 看起来对，其实错。
没有它：AI 生成的代码语法没问题、逻辑也对，但违反了业务铁律，上线就是事故。 有了它：AI 想删一个字段，约束引擎直接拦截：这个字段在订单状态机里，不能动。
3️⃣ Learning Engine / 学习引擎
作用：每次改动都让系统更聪明。
从哪里学？
- diff（代码变更）
- session（操作会话）
- 错误记录
但关键点是：
- ❌ 不能全自动入库
- ✅ 必须有人审核
没有它：同一个坑，AI 今天踩、明天踩、后天还踩。 有了它：上次 AI 把异步消息当同步处理出了事故，审核入库后，下次遇到类似场景自动告警。
七、最关键的闭环（很多团队缺失）
真正的自进化，不是某个能力，而是一个闭环：
需求 → 分析 → 风险评估 → 约束注入 → 代码生成 → 执行 → 复盘 → 更新知识 → 下一轮
举个例子：缺了复盘环节会怎样？
团队上线了一个 AI 改动的接口，出了问题但没复盘。风险引擎不知道这片区域出过事，约束引擎也没学到新规则。下一次 AI 在同一片区域改代码，同样的坑再踩一遍，系统毫无长进。
如果缺任何一个环节：👉 都不叫自进化。
八、企业最容易踩的三个致命坑
坑一：只做 Code Graph（代码图谱）
结果：AI 会写代码，但经常改错地方。
坑二：过度建设文档
结果：AI 被误导，比没文档更危险。
坑三：没有风险体系
结果：每一次上线，都是一次赌博。
九、一个更现实的判断（给技术负责人）
如果你只能做一件事，优先级应该是：
- Code Graph / 代码图谱：让 AI 看懂代码
- Constraint / 约束：让 AI 不犯错
- Risk Engine / 风险引擎：让系统可控
- Learning / 学习：让系统进化
而不是一开始就：我们要做一个知识库。
十、这一阶段的本质变化
从个人提效到系统进化，其实是一次认知跃迁：
个人提效：AI 写代码
团队提效：AI 参与开发
系统进化：AI 参与决策
结尾
很多团队会问一个问题：Harness 到底值不值得做？
答案其实不复杂：
如果你只是想让开发快一点，不值得。
如果你想让系统越来越稳定、越来越可控，那这是唯一的路。