百万行“祖传代码”AI读不懂？一个 context.md 让你彻底告别上下文灾难

在AI辅助编程已经成为日常开发标配的今天，许多开发者面临着一个隐秘而致命的痛点：面对动辄一两百万行的“祖传系统”，AI往往会表现出“智力降级”。

如果每次生成代码都让AI去扫描全部源文件，不仅技术上受限于上下文窗口，Token成本也会瞬间爆炸。这就好比让一个人在图书馆里找一句话，却要求他把所有书都通读一遍。

不要让AI去对百万行代码做“全表扫描”，你需要给程序的源代码建立专属索引。

这个索引，就是在工程化AI编程中至关重要的包内元数据（Package Metadata）——通常被命名为 context.md 或 readme.md。

一、为什么我们需要 context.md？

在传统业务开发中，一个模块下可能包含几百个控制器（Controller）、业务逻辑（Service）和响应实体（Response）。让AI依靠瞎猜或全量扫描去理解这些类，是不切实际的。

引入 context.md，本质上是为AI提供一个理解程序上下文的锚点。它以自然语言的形式，精确描述当前包的职责、业务边界以及依赖关系。

这与数据库查询的逻辑如出一辙：原本你需要面对成百上千万行数据，现在通过索引，极大强化了信息检索的速度与准确度。

具体而言，它解决了三大核心痛点：

突破 Token 上下文限制：将上百万行的代码逻辑压缩成极简的Markdown文件，极大地缩小了AI需要读取的上下文长度。
消除语义歧义：仅读取单个类文件往往会导致AI获取的信息碎片化。将一个包的完整语义聚合在MD文件中，能帮助AI纵观全局，做出正确的代码生成决策。
显性化隐式知识：老代码中充斥着只有老员工才懂的隐式业务逻辑（例如深埋在各种 if/else 中的出入口判断）。将其转化为显性的规则文档，可以直接作为系统级 Prompt 指导AI重构或生成新代码。

在实际的工程实践中，我们通常不需要拘泥于文件命名（context.md 只是约定俗成的叫法），核心在于其承载的信息架构。一套完善的元数据体系分为全局与包级别两层：

存在于项目根目录，是指导AI生成代码的总纲领。它需要包含：

针对具体业务包（如订单服务）的深度解析，通常包含以下五大要素：

通过这种“自然语言+Markdown”的结构化表达，既保证了人类开发者的可读性，又喂给了AI最纯粹、信息密度最高的系统特征。

理解了价值，接下来的问题是：上万个包的MD文件，难道要人工去写吗？
显然不是。我们可以通过以下三种方式的组合，实现元数据的自动化生成与流转：

对于历史遗留项目，第一次构建索引是必经之路。可以通过编写自动化脚本，或利用 IDE 将每个包的代码批量“喂”给AI，让其基于当前代码上下文，自动生成所有目录的 MD 文件。
注意：这会消耗大量 Token，初始成本较高，但作为打通系统经脉的“基建工程”，绝对物超所值。

在日常开发中，当对某个 Service 或 DAO 层进行了较大修改后，可以借助 Cursor、Trae（字节跳动）等带有内置 Chat/Builder 功能的 AI IDE，基于当前包的最新代码副本，手动触发重生成 context.md。

这是最高效的工程化手段。在每次提交代码时，利用 git diff 命令提取出产生变动的包（例如本次提交只影响了 3 个包）。
随后通过命令行脚本或 IDE 插件，仅针对这 3 个发生变化的包重新生成底层逻辑与依赖描述。

这样就能确保代码的变更与 context.md 的更新始终保持同步。提交到 Git 仓库的，不仅是能跑的代码，还有与代码血脉相连的“AI 索引”。