代码之外：为什么AI无法理解你的项目，以及我们如何应对

引言

在尝试用AI辅助分析代码时，我遇到了一个非常典型的场景：当我将一段包含复杂业务逻辑的补丁交给AI，它只能基于代码本身和通用的编程知识给出分析，却完全无法理解这段代码背后的真实故事——为什么要这样改？之前踩过哪些坑？团队内部有过什么样的争论？

这并非AI的能力缺陷，而是暴露了一个更深层次的问题：软件工程中真正重要的上下文，绝大部分并不存在于代码和公开文档中。 这一洞察与我们团队正在推行的知识沉淀实践紧密相关，本文将围绕这个核心矛盾展开。

一、AI所不知道的事：三个缺失的维度

如果把一个软件项目比作一座冰山，代码、文档、配置只是露出水面的部分。而水面之下，隐藏着决定工程成败的关键信息。

1. 业务背景的缺失

AI看到一行 if (user_type == 5)，只能判断这是一个类型判断。但它不知道：

• 这个5代表“企业高级版用户”，是某大客户去年签约时承诺的特殊逻辑；

• 产品经理当时说过“这个逻辑只保留半年，后面会合并”，但两年过去还没合并；

• 这种用户的数据量是普通用户的100倍，所以这段逻辑必须极度高性能。

2. 技术决策迭代史的缺失

当AI分析一个模块的当前代码时，它看到的只是最终方案C。但它不知道：

• 方案A因性能瓶颈被否决，相关压测报告在某个同事的本地目录里；

• 方案B依赖的一个第三方库有一个未文档化的Bug，导致线上事故后才被迫回退；

• 当前方案C实际上是一个“不完美但能跑”的妥协，团队原计划在Q3重构。

3. 隐形契约与口头约定的缺失

• “这段注释不要删，老李说他下周会重构这个模块”；

• “这个接口的参数虽然标记为可选，但支付模块实际上必须传，否则会触发风控”；

• “这条SQL虽然写法不优雅，但线上有这样建索引，改了反而慢”。

这些都是AI不可能从公开数据中学到的“部落知识”。

二、根源：信息媒介的碎片化与隐性化

为什么这些信息AI获取不到？因为它们根本没有被系统性地记录。

信息类型	典型存储位置	AI可达性
当前代码	代码仓库	高
正式文档	文档系统	中
设计决策讨论	邮件、Slack、钉钉	低
线上事故复盘	内部Wiki（可能未维护）	低
重构计划与权衡	开发者头脑	无
口头约定与承诺	开发者头脑	无

现代软件工程的信息分布是极度碎片化的。即使团队有文档文化，那些“不适合写进正式文档”的背景、那些“暂时记住就行”的小决策，最终都沉积在个人记忆中，随着人员流动而永久丢失。

三、这正是知识沉淀要解决的问题

在文章《Harness 不是目的，知识才是护城河 —— 一个AI工程交付团队的知识沉淀实践》中，核心观点直指这一痛点：工具（如Harness）只是流水线，真正的护城河是将项目经验、技术决策和业务理解转化为结构化、可复用的知识资产。

文中提出的五层知识存储架构和三级成熟度体系，本质上就是设计一套机制，将那些散落的信息“打捞”上来，成为团队的集体记忆：

• 五层存储：从临时的会话记录，到整理后的经验文档，再到可查询的领域知识图谱，层层提炼；

• 三级成熟度：从依赖个人英雄主义的“经验级”，到建立共享机制的“资产级”，最终达到能主动推荐决策的“智能级”。

这套体系的最终目标，是让新人、新AI工具、甚至是未来的自己，都能快速还原出项目的完整故事。

四、实践：如何让AI更好地理解你的项目

基于上述理念，我们可以采取一些具体措施，弥补AI的上下文鸿沟：

1. 建立“决策记录”习惯

对于每一次关键设计，不只记录“做了什么”，更要记录“当时为什么这么做”。一个简单的模板：

text

[决策] 选择方案C实现XX功能
- 背景：需要解决XX痛点
- 备选方案：A（...）、B（...）
- 否决原因：A性能不足（详见压测报告链接），B依赖库存在问题（详见Issue #123）
- 当前方案C的已知缺陷：...
- 未来计划：Q3重构（负责人：张三）

2. 将迭代历史作为一等公民

在代码注释或模块文档中，简要记录重大变更的时间线和原因。Git历史能告诉你“谁在什么时候改了哪行”，但无法告诉你“为什么这行代码不能删”。

3. 构建领域知识图谱

对于复杂业务，将核心实体、术语、流程环节及其关系显式化。这不仅能帮AI理解，也能极大降低新人的认知负载。

4. 将AI纳入知识沉淀流程

在Code Review或设计讨论中，有意识地将讨论结论整理成AI友好的格式（如结构化总结），让AI成为知识库的“消费方”，反向驱动团队沉淀习惯的养成。

五、结语：让AI成为知识的催化剂，而非替代品

AI不是全知全能的代码之神。它更像一个极度勤奋但缺乏项目背景的新同事：你需要给它足够的上下文，它才能产出有价值的分析。

而这恰恰提醒我们：软件工程的核心挑战从来不是“写出代码”，而是“管理复杂性”和“传递理解”。 当我们抱怨AI不够聪明时，或许更该反思：我们的知识沉淀是否足够好，能让任何协作者（无论是人还是AI）快速进入状态？

从这个角度看，AI不仅是辅助工具，更是一面镜子——它照出了团队在知识管理上的所有漏洞。而填补这些漏洞，正是建立真正“护城河”的起点。

---

本文的灵感来源于一次真实的AI辅助代码分析过程，以及AI工程交付团队的知识沉淀方法论。在对话中，AI的局限与知识沉淀的价值被同时照亮，这本身就是一个值得记录的知识片段。