让AI真正读懂老项目：上下文工程实战指南

在AI能力飞速提升的今天，一个有趣的现象是：许多人依然认为AI更适合新项目的快速迭代，而对于背负历史包袱的老项目，AI能发挥的作用相当有限。这种认知的形成并非没有道理——AI在处理老项目时确实常常表现得差强人意。但问题的根源究竟在哪里？答案或许出乎意料：不是AI的能力不够，而是AI对项目的“理解”不够。

核心问题：被忽视的上下文鸿沟

AI与人类开发者的本质差异，往往不在于代码编写能力，而在于上下文知识的积累。当一位熟悉业务的开发者面对问题时，他能快速调取项目的历史背景、架构设计、技术债务等隐性知识，这些难以文档化的信息构成了协作的默契。AI却恰恰缺乏这种上下文，导致它在新旧代码边界模糊、业务逻辑复杂缠绕的老项目中频繁“失准”。

破局之道：构建AI上下文工程

老项目中阻碍AI发挥作用的上下文信息主要包括几个维度：业务的历史背景与演进脉络、项目模块间的协作关系、哪些代码仍在实际运行而哪些已是“死代码”、架构改造的完成度与遗留问题，以及散落在文档或个人记忆中的技术决策。这些信息对人类开发者尚需时间熟悉，对AI而言更是无从获取。正因如此，我们与AI的协作成本在很多时候并不亚于人与人之间的沟通成本。

让AI参与老项目重构

重构的目标不仅是解决技术债务，更是为AI创造可维护的条件。具体实践中，我建议从几个层面逐步推进。首先是静态上下文的建设——在代码仓库根目录建立AGENTS.md文件，作为AI理解项目的索引入口，包含业务背景、架构信息、技术方案、团队规范等关键指引。其次是代码治理，清理不再生效的遗留代码，简化过度设计的架构，让项目的实际结构与代码表象保持一致。再者是规范制定，为项目设置清晰的约束边界，包括页面布局、组件使用、代码风格等，使AI在迭代中有章可循。最后是自动化测试体系的建立，通过单测、E2E测试和视觉回归用例覆盖核心功能，配合MR流水线实现持续的质量保障。

将债务治理融入日常

技术债务的本质往往是重构的不彻底。每一次半途而废的改造，都可能成为未来的隐患。借助AI上下文工程，我们可以将周期性的专项债务治理，转化为日常开发中的持续收敛。通过规范约束和AI评审机制，在每次代码变更中顺手解决历史遗留问题，避免债务的进一步累积。

如有侵权，请联系删除。