让 AI Coding 进入一个 20+ 模块的老项目

2025 年下半年，朋友跟我说 AI Coding 已经很好用了，Sonnet 4 甚至能写生产代码，让我赶紧试试。

我那时连 Claude Code 怎么装都不知道，还在网上找终端安装命令。第一次跑起来，我让它修一个小 Bug。按照以前的经验，这个问题我自己处理大概要两个小时，Claude Code 二十分钟左右就改完了。

我看了一遍代码 Diff，它改的几个地方正好就是我原来设想的方案。那次以后，我开始认真关注 AI Coding，也很快用得一发不可收拾。

小任务很顺，任务一长就开始出问题

最开始我的用法比较简单。先开 Plan 模式，只讨论方案，不让它修改文件；我确认方案没问题，再切到 Build 去实现。

修 Bug、增加小接口，这种任务完成得一直不错。偶尔也会出现幻觉，把原本正确的代码改错，但人看一遍 Diff 通常能够发现。

真正让我改变用法的，是一次比较长的方案讨论。

当时已经聊了很多轮，方案也快确认了，我突然发现 AI 对前面讨论过的一个细节理解偏了。继续往下看，才意识到整个对话已经很长，这是上下文开始丢失的前兆。

麻烦在于，前面花了很多时间确认方案。现在不但要重新解释那个细节，还要担心它后面是不是又忘了别的内容。

从那以后，复杂方案只要讨论到一定程度，我就先让它写进文档。下一次对话不再依赖模型“记得我们刚才说过什么”，而是从已经落盘的方案继续。效果马上稳定了很多。

ISMP 是一个 Java 8、Spring Cloud 的存量项目，有 20 多个模块。AI 第一次进入这个项目时，不知道模块之间的关系，也不知道项目使用的技术版本、编码习惯和编译方式。

这些问题我都真实遇到过。项目明明是 Java 8，AI 写出了 Java 17 才有的方法，最后编译报错。还有一次，它没有按项目原来的 Maven 方式验证，跑去找一个 Eclipse 相关的编译插件，因为我的环境里根本没有，最后一直卡在那里。

每遇到一次，我就要在提示词里补充一次。用久了以后，我开始觉得这样很笨：同一个项目、同一套技术栈和规范，为什么每次开新会话都要从头讲？

最开始，各个 AI CLI 会通过自己的初始化命令生成说明文件。不同工具关注的内容不一样，最后很容易得到一个大而全的 AGENTS.md。但一次简单的文档修改，并不需要先读完项目的 Java 编码规范；一个后端开发任务，也未必需要把所有部署资料都塞进上下文。

我后来把各个 CLI 的入口统一起来，让 AGENTS.md、CLAUDE.md 只负责告诉 AI：这个项目的上下文放在哪里，当前任务应该继续读什么。真正的内容按用途放进 .ai/，包括项目架构、编码规范、验证方式和复杂任务的任务包。

入口尽量薄，不是为了追求目录漂亮，而是为了少占上下文。具体任务只读自己需要的材料，把更多窗口留给代码和当前问题。

架构文档先告诉 AI 这是一个什么项目：使用哪些技术、模块怎样划分、常见调用链在哪里。至少不会再用 Java 17 的写法修改 Java 8 项目。

编码规范记录公司和项目原来的习惯，包括分层、命名、注释、事务和日志等要求。AI 写代码时不能只按它认为“更现代”的方式改，而要先服从这个项目已经形成的风格。

验证文档则把编译和检查命令写清楚。该在哪个目录执行 Maven、哪些模块可以单独编译、哪些环境依赖本地没有，都提前说明，避免 AI 自己到处找工具。

这些内容没有什么神秘的，大部分都是我在多次对话中重复说过、或者因为出过问题才补进去的。后来看到 Harness Engineering 的概念时，我很认同这种思路：与其不断要求模型“更聪明一点”，不如先把它工作的环境整理好。

说得直接一点，这些工作都是为了以后偷懒。项目知识只整理一次，后面就不用在每个提示词里写一大段背景。

小 Bug 和单接口修改可以直接做。只要任务跨模块、步骤多、一次很难完成，我就会建立任务包。

日志写出任务就是一个例子。它不是给一个接口加一行日志，而是要处理一组结构复杂的字段，其中还有 JSON 内容，并且多个接口、多个模块都要补齐同一套日志能力。

这种任务如果全部塞进一次对话，做到后面很容易忘记前面的字段约定，也很难判断哪些接口已经修改、哪些还没有验证。

任务包先记录基线和方案，再拆成子任务。每完成一段就复查一段，把当前进度、发现的问题和评审结果继续写回去。下一个会话或者另一个 AI CLI 接手时，不需要重新翻完整聊天记录，直接看任务包就知道现在做到哪里。

确认范围 -> 记录基线 -> 拆分子任务 -> 分段实现
                                |
                                v
更新进度 <- 复查结果 <- 编译验证 <- 完成一段

Claude Code、Codex 和 OpenCode 没有固定成“一个只写代码、一个只做 Review”。它们都能做 Plan、Coding 和 Review。我会根据当时的任务和模型能力，让更合适的工具挑大梁，其他工具做补充分析或交叉复核。

任务包在这里还有一个作用：交接不再只发生在人和人之间，也可以发生在不同 AI、不同会话之间。

做完这层改造后，最直接的变化是提示词变短了。以前要先写一大段项目背景，现在很多任务只要说明要做什么，AI 会自己按入口找到架构、规范和验证方式。复杂任务也不必强行挤在一个长对话里，切换会话时不容易把已经确认的方案弄丢。

当然，这套方式也有成本。文档需要维护，代码和架构变了，说明不更新反而会误导 AI。人工 Review 也没有消失，AI 改完的代码仍然要看 Diff、做编译和回归。

目前的文档分类还比较粗。不同类型的任务有时仍然会读同一套材料，后面还可以继续细分，让数据库修改、接口开发、文档编辑和部署排查各自读取真正需要的上下文。

我现在对 Harness Engineering 的理解很实际：它不是再加一个 AI 工具，也不是写一份特别长的项目说明。它只是把原来散落在人脑里、聊天里和踩坑记录里的信息，整理成 AI 随时能够读取的工作环境。

AI 写代码已经很快了。大型老项目真正缺的，往往不是更快地生成代码，而是让它先知道这里原来是怎么工作的，改完以后又该怎样证明自己没有把东西弄坏。