夜雨聆风系列第 1 篇：认知框架。后续每篇深入一个扩展点。
网上大多数 AI Coding 的分享都是小项目、从零开始的场景。
这个系列专门写大型存量代码库——50 万行、十几个人、有历史包袱的那种。
我经历的三个阶段
刚开始用的时候确实兴奋。让 AI 写个 CRUD，几秒出来，感觉生产力翻倍了。
然后慢慢发现不对劲。AI 开始犯一些说不清楚的错误——不知道我们公司平台的封装方式，不知道跨模块调用的约定，同一个问题昨天能答对今天又答错了。项目越大，这种感觉越明显。
后来才意识到，问题不在模型，在于我根本没有认真对待这个工具本身。
开始把它当成一个需要配置和调教的系统来对待，而不只是一个"聪明的搜索框"——事情才开始变得不一样。
一个让我想清楚的类比
模型是发动机；Harness 是让车跑起来的其他一切。
光有发动机，车跑不起来。你需要底盘、变速箱、方向盘、油路——这些东西的质量，决定了同一台发动机能发挥出多少性能。
AI Coding 也是一样。Claude Opus、GPT-5.4、Gemini——这些是发动机，毫无疑问越强越好。但围绕模型建造的系统，也就是 Harness，越来越决定一个 Coding Agent 的实际表现。
Harness 是什么？就是 Claude Code、Cursor、Codex、Trae 这些工具本身构建的框架。我们无法插手它们的内核，但它们给我们留下了扩展点。
大型代码库的核心矛盾
我们的项目是 Java Monorepo，50 万行代码，18 个 Spring Cloud 微服务模块，团队十几个人。
这种规模的代码库，直接用 AI 工具体验很差。根本原因是一个结构性矛盾：
AI 的上下文窗口是有限的，代码库是无限的。
50 万行代码，AI 每次只能看到其中很小的一部分。它不知道模块间的调用约定，不知道公司平台封装了哪些东西，不知道哪些坑已经踩过、哪些写法是被禁止的。生成的代码看起来对，但放到项目里要改很多地方才能真正用。
这个系列要解决的，就是这个矛盾。
五个扩展点
经过三个月的摸索，我把解法归纳为五类扩展点：
① AI 上下文文件让 AI 在每次会话开始前，就已经"懂这个项目"。在不同工具里叫法不同——CLAUDE.md、.cursor/rules、AGENTS.md——本质是同一件事：把 AI 猜不到的项目知识，提前告诉它。
② Hooks在 AI 的生命周期节点插入自定义逻辑。写完代码自动编译验证、会话结束自动生成 PR 摘要——让 AI 的输出直接达到可提 PR 的质量，减少你在中间的手工打磨。
③ Skills可复用的工作流。把"新增一套 API"、"生成单元测试"这类高频任务封装成一条命令，而不是每次都重新描述一遍需求。AI 按照你定义的规范生成，不用每次纠偏。
④ MCP连接外部系统的标准协议。让 AI 直接读数据库 Schema、Nacos 配置、Jira 工单，而不是靠你复制粘贴上下文。上下文窗口有限，就让 AI 自己去拿它需要的信息。
⑤ Plugins把前四样打包成一个可安装、可分发的单元。新同事入职第一天装上去，立刻拥有和老同事一样的配置，不需要任何额外说明。
配置前后的对比
系统化配置之后，变化体现在具体的工作流上：
新增一套 API：从"描述需求 → AI 生成 → 人工修正平台用法 → 编译报错 → 再修"，变成"一条命令，编译通过"。
PR 描述：从手写，变成会话结束自动生成草稿，直接复制进去改两行。
Bug 排查：从"复制粘贴堆栈给 AI"，变成 AI 直接查 Git 历史和 Nacos 配置，给出定位结论。
不是说 AI 变得无所不能了。而是它终于开始真正理解这个项目了。
本系列的计划
这是系列的第一篇，建立认知框架。后续每篇深入一个扩展点，都有来自真实项目（50 万行、Java Monorepo）的代码和案例：
第 2 篇：AI 上下文文件——怎么写才有效，写进去的每一行都要能回答"如果没有这行，AI 会犯什么错" 第 3 篇：Hooks——两个真实脚本，AI 每次写完代码自动编译，失败了自己修 第 4 篇：Skills——自制 PR 冲突解决 Skill，把团队 Git 工作流标准化成一条命令 第 5 篇：MCP——Nacos 没有官方 MCP，我自己写了一个，100 行，AI 现在直接读配置中心
如果你也在大型存量代码库里用 AI 工具、也遇到过"生成的代码看起来对但用不了"的问题，后续应该会有用。
下篇：AI 上下文文件怎么写——不是什么都往里塞，而是只写 AI 会犯错的地方。
