从胡言乱语到精准改代码:我是如何让 AI 读懂老项目的
AI 时代赋予 AI 的新角色:AI 铲屎官。
在 AI 很强的现在,依然很多人会认为,AI 更适用于新项目快速迭代,但很难在一个背负着沉重的历史包袱的项目中起到很大的用处。
最近大半年都在重构项目,从前期使用 AI 依然困难重重,到如今 AI 能高效定位问题、给到十分贴合项目需要的解决方案,中间特别明显的一个转折点,在于开始给项目搭建 AI 上下文工程。
当然,这一年来 AI 的能力本身也在不断加强,我们项目的质量和架构的合理性在我的努力重构下也在稳步提升,但 AI 上下文的搭建依然起到了十分关键的作用。
今天给大家分享的,主要是如何在重构过程中,将 AI 总是胡言乱语,变成了 AI 也可高效助力的一个项目。
思考:AI 提效到底是在提效什么?
在过去的一年里,AI 的能力有大幅度的提升,从最初只能做点明确的小任务,到如今能协助排查问题、提出可落地的解决方案、自执行落地和自测等等,在我们工作中参与的幅度越来越大。
如今很多新业务直接是 AI 原生项目,意味着从立项到上线,开发未亲自写过一行代码,基本上都是 AI 自行完成的。
但即使在 AI 能力很强的今天,大家还是有些共识,比如一个历史债务很重的项目中,AI 能发挥的作用很少,还是需要开发的介入更多。
这很大一部分原因是:AI 的上下文知识不够。
业务瓶颈常在上下文
其实 AI 和开发并没有太大的区别,很多时候区别只是在于,我们比 AI 拥有更多的上下文,这些上下文包括:
业务的历史背景,项目的整体协作方式(与其他模块的关系等)。 过去的需求文档、技术文档,可能存在其他地方或者是开发和产品的脑袋中。 项目真实运行情况,哪些分支代码上的功能还在跑的、哪些只是历史兼容但不会运行到的。 架构设计和技术债务情况,哪些技术改造只做了一半,未改造彻底等。
这些问题,不管是 AI 还是新加入业务的开发来说,都会遇到,而我们过往经常做的定规范、写文档、做通用化/平台化方案等很多工作内容,都是为了降低对接和沟通成本。
现在我们很多人都会让 AI 写代码,开发成本大大降低了,如今困扰我们的往往是沟通协作成本。人和人之间如此,人和 AI 之间也是如此。
重构成为 AI 可维护项目
回到话题,我们常说的 AI 提效,到底是指什么?
在过去这一年中 AI 已经逐渐参与到很多业务中,十分肯定的是它能提效我们的开发过程,但 AI 还能做更多,包括排查问题、系统现状分析、技术方案设计和落地、代码 Review 等等。如今很多人也已经在尝试让 AI 参与更多,但大多数依然仅限于 AI 原生的新业务。
旧业务和新业务,其实区别便在于 AI 的上下文是否充分。对于历史债务多、维护成本高的项目来说,其实正适合带着 AI 进行重构,重构的过程中给 AI 逐渐补充足量的上下文信息,这样重构后我们就能得到一个 AI 可维护的项目。
过去我们重构,原因无非是架构设计已无法支持业务迭代、技术债务过重需要专项治理、来新人了大家都按自己的想法重做一遍。
如今我们重构,除了治理项目中的既有问题,更是给 AI 添加足够的上下文信息,使得 AI 能参与到日常排障、功能迭代、架构优化中,让开发从日常的高成本维护和反复沟通协作中减负,达到真正的项目提效。
AI 上下文内容建设
我从去年年底就开始治理我们项目的技术债务,今年刚开始的时候,AI 能力已经很强了,但依然经常会判断出错。
判断不准确的原因除了架构过度设计、同时设计的方案落地过程变了形之外,还有很多并没有真实在运行的代码。这些代码是否真的运行,不管是开发还是 AI 都无法通过相关引用判断,因为代码有真实的引用,但在真实运行时可能某个链路却彻底不会运行到。
这些上下文除了 AI 无非获取,很多时候开发自己也无法获取。
过去很长的工程项目中,上下文信息的维护也常常是业务痛点。团队知识的建设很重要,但是无法体现价值,因此往往因为性价比等各种原因,几乎没有团队能将团队知识建设得很好,甚至很多技术强的团队反而崇拜“自己看代码解决”的协助方式。
开发都不爱写文档,也不爱看文档,每个细节和协作内容都存在各自的脑袋中。信息的不对齐、遗漏导致协作过程中的变形,架构设计、技术方案也常常很难坚定不移地完整落地。
我们过去推崇的功能组件化、平台化、通用化,目标都是为了减少开发和维护成本,因为约束了大家认可的规范和协议,这些规范和协议便是我们协作中的上下文信息。
和 AI 协作也是如此,并且在开发成本已被 AI 大大降低的今天,业务开发的效率往往卡在人与人、人与 AI 的协作中。建设团队文档和知识,是为了减少人与人之间的协作,那么建设 AI 上下文工程,便是为了:同样的事情,应该只需要跟 AI 强调一遍即可。
从 AGENTS.md 开始
AI 的上下文知识沉淀,最简单的方式便是从静态上下文开始,这便是跟着代码仓库走的AGENTS.md。
当然,AI 上下文也是有限的,因此我们需要将项目的信息拆分领域放在对应的位置,只保留最重要的内容放置在项目根目录的AGENTS.md中,比如:
# 知识索引
此处描述各个领域的知识需要去哪里找,比如
- 业务背景知识
- 架构信息&技术方案沉淀
- 通用组件&规范
- 三方的对接系统信息
- 其他业务规范等
## 要求
- AI 代提交代码时,commit message 必须以 `| pub` 结尾(这条为我们项目仓库规范)
### 知识落盘规范
- 根目录 AGENTS.md 和 CLAUDE.md 只保留索引概要(路径 + 1~2 句摘要),不在此堆细节。
- 当对话中出现可复用的规则/兼容性/排障结论/项目知识时,必须就近落盘到对应模块 `AGENTS.md`,并同步更新根目录 AGENTS.md 和 CLAUDE.md 中的知识索引(以模块内容为准)。
- 当发现知识索引出现内容过期或不准确时,主动修改
新建一个根目录的AGENTS.md,是一个简单的开始(此处感谢 yuankai 同学的积极分享)。
带着 AI 一起重构业务
即使在 AI 能力超强的现在,依然有无数的业务不会选择进行重构。“代码还能跑就不要动”,这样的历史教训还在深刻影响着不少人。
这对一个停止迭代需求的业务来说,或许问题不大。但如果项目还在快速迭代,将项目重构成一个 AI 项目,在不远的未来可以逐步放手交由 AI 去做更多的事情。
先简单介绍下我们的小程序教育平台,该平台可以理解为一个面向教育场景的“项目创作 + 课程教学 + 小程序体验/发布”平台。它是围绕教育内容生产、学习过程、项目开发、作品体验和发布管理串起来的一整套系统,核心功能包括:
自由创作/AI Coding:小程序编程/编译/预览/发布、AI 编程 课程学习/课程制作:项目式课程的学习、制作、能力配置,包括小程序预览、富文本编辑知识面板、代码编辑器、AI 对话、答题等各种内容板块 资源管理:学校/班级/学生账号、小程序管理、云开发/混元资源等
自由创作(代码编辑+小程序预览+AI对话+代码版本管理+素材库资源管理)
系统的复杂度拆分为两部份:
前端 WEB 本身的复杂度。除了业务需求上的复杂交互设计(比如课程学习/自由创作/课程制作等复杂板块需要支持宽窄屏+拖拽调整+动画效…