面临的问题

我之前在用 AI 写代码的时候，如果说我直接给 AI 说，我想实现什么什么样的功能，有些时候，它往往接到需求就开始写代码，这个时候写出来的代码，往往是不可靠的，也无法直接用的。比如说，有时候在写代码时 AI 会忽略已存在的方法或函数而重新创建新的。因为它没有探索项目中的相关代码，因此它对于当前项目中的代码情况是不清楚的。
如果我在前面的指令中，进一步说：“我想实现 xxx 功能，请先探索一下项目中的相关代码”。就因为加了这么一句话，它的代码质量就好了很多。
如果我进一步说：“我想实现 xxx 功能，请先阅读 @src/xxx 和 @src/xxxx 中的相关代码”。这个时候的代码质量又会高很多，甚至很多时候就非常精准。
所以，即使现在 AI 能够一次性处理的上下文窗口很大，但并不是说你给到它的信息越多越好。如果你给到它很多无关的信息，这只会影响到它的输出质量。如果说要让 AI 做到指哪儿打哪儿的程度，精准的 Prompt 还是非常必要的。

如果围绕 AI 构建一套精准的上下文呢？

我觉得最好的方式，就是为它构建一张关于项目代码的实时地图。让它可以通过地图，指引它找到适合的上下文。

解决的思路

将文档进行分层隔离和分层披露。在 AI 的每一次会话时，只让 AI 读取目标模块的文档，无需消化全量信息，从而提升上下文质量与 AI 的代码输出质量。

达到目的

  1. 给 AI 提供一份实时更新的项目代码地图指引和每个模块的具体说明，让 AI 通过阅读这些地图，能够快速指导 AI 基于用户的需求从什么地方去寻找相关的代码。
  2. 功能开发完成之后，自动更新地图信息。

具体方法

结构设计

AI Map 系统由两个层次的文档构成：

  • ai-map/AIMAP.md (总地图)：项目的“宪法”和核心索引。它定义了全局架构规范、编码准则，并通过自动化脚本实时同步各子模块的职责摘要。它是 AI 进入项目后的首要参考点。
  • 各模块目录下的 CONTEXT.md (微观路标)：分布在各个业务或功能模块中的详细文档。它定义了该模块的单一职责、内部架构、对外接口以及模块特有的开发规范。

执行策略

建立一套上下文的加载协议。

  1. 显示引用。
    在与 AI 对话时，遵循一套加载顺序。不要上来就写代码，而是先让 AI 读取“地图”。
    指引路线：比如说，我需要修改 User 模块的登录逻辑。
    1. 请先阅读 AIMAP.md，确认项目的架构规范、开发准则以及相关模块索引。
    2. 然后阅读 /src/UserModule/CONTEXT.md，获取该模块的详细约束。
    3. 最后基于以上上下文，修改 login.ts。
  2. 更新机制
    在功能实现完成后，通过 Git 的 pre-commit hook 工具监测代码变动，从而识别可能受影响的模块，最后通过 AI 自动更新相关文档。具体来说：
    • 架构层面的变更 → 更新 AIMAP.md
    • 模块内部的变更 → 更新对应目录的 CONTEXT.md
      目前这个项目已经上传到 GitHub 上ai_map_core。有需要的朋友可以自行下载使用，也欢迎大家提供使用反馈。

项目地址：[1] ai_map_core: https://github.com/maxweber36/ai_map_core