AI渐进编程之七：让 AI 先读项目地图再动手

前面几篇我们已经把几件事说清楚了：

• 先从小任务开始，用prompt就能做的先做
• 任务变复杂后，再加Harness
• 任务继续推进后，引入状态
• 状态机负责描述转移
• SIADOS负责把一轮任务推进串起来
• 控制层要能按风险逐步加深，也要能在任务稳定后适当降级

这一篇开始进入本书的第三部分：文件系统与记忆。

这里要回答的是一个很现实的问题：

如果 AI 不能只靠当前对话记住项目，那它到底应该先看什么？

答案是：先看项目地图。

1. 为什么不能只靠对话上下文？

对话窗口很适合承载当前一轮输入，
但它不适合保存长期可复用的项目事实。

因为对话上下文有几个天然问题：

• 它会不断增长
• 它会混入很多临时讨论
• 它会被新的任务覆盖
• 它不适合长期维护稳定认知

也就是说，对话更像“当前工作台”，
不是“项目记忆库”。

如果一个 AI 编程系统总是靠当前对话去猜项目状态，它就会越来越容易：

• 忘记之前的边界
• 误读当前目标
• 重复处理已经解决过的问题
• 在无关信息里浪费上下文

所以，本书的思路不是把所有内容都塞进上下文，
而是把长期应该记住的东西，放到文件里。

2. 什么是项目地图？

project_map.md的作用，可以先理解成一张“导航图”。

它不是完整文档，
也不是详细日志，
而是一份经过维护的、足够短的项目认知摘要。

它负责告诉 AI：

• 这个项目的目标是什么
• 关键文件有哪些
• 哪些约束不能破坏
• 现在大概处于哪个阶段
• 下一轮应该先读什么

换句话说，project_map.md不是用来记录所有细节的，
而是用来让 AI先知道往哪走，再决定怎么走。

3. 项目地图和对话历史有什么区别？

这两者的职责不一样。

对话历史

对话历史按照时间保存消息。
它的特点是：

• 量会越来越大
• 内容会越来越杂
• 容易混入旧计划
• 适合回看过程，不适合做长期认知

项目地图

项目地图按照决策价值保存事实。
它的特点是：

• 短
• 稳
• 可维护
• 优先读取
• 适合决定下一步动作

所以它们不是替代关系，
而是分工关系：

• 对话历史负责“发生过什么”
• 项目地图负责“现在该怎么继续”

4. 项目地图应该保留什么？

项目地图不是越多越好。
它只保留会影响下一轮决策的内容。

4.1 项目目标

目标要明确，不然 AI 不知道局部修改和整体方向是不是一致。

例如：

• 这本书是在讲 AI 渐进编程
• 不是在讲纯 prompt 技巧
• 也不是在讲单点工具炫技

4.2 关键文件与入口

AI 不应该每轮都重新扫描整个项目。
它应该知道先看哪些文件。

例如：

• 哪个是主文档
• 哪个是当前任务
• 哪个记录问题
• 哪个记录修改原因

4.3 稳定不变量

有些规则不能随便改。
这些规则就应该出现在项目地图里。

例如：

• 某些术语不能乱换
• 某些范围不能越界
• 某些结构要保持一致

4.4 当前阶段

项目现在处于哪个阶段，也要写清楚。
因为阶段不同，允许动作不同。

例如：

• 现在是在概念讲解阶段
• 还是在论文修改阶段
• 还是在代码项目阶段

5. 项目地图为什么能减少上下文膨胀？

因为它让 AI 不用每轮都从头猜。

如果没有项目地图，AI 往往要：

• 重新读很多历史对话
• 重新猜项目目标
• 重新判断边界
• 重新找相关文件

这就会把上下文越拖越大。
而项目地图的作用，就是把这些稳定事实压缩成一份短文本。

所以本书把它看成一种：

• 索引
• 压缩
• 导航
• 入口控制

它位于“易失上下文”和“完整历史”之间，
承担的是中间层记忆的作用。

6. 一个论文项目地图长什么样？

以论文修改场景为例，paper_map.md可以很短，但要足够清楚。

它至少要告诉 AI：

• 论文的核心目标是什么
• 主文档是哪一个
• 哪些 claim 是边界内的
• 哪些表述不能越界
• 下一轮应该先读什么

比如：

# Paper Map ## Goal 提出一种基于 NFT 的 WiFi 访问控制机制： 网关验证钱包签名与访问 NFT 的当前持有状态， 据此决定网络会话的建立。 ## Main file - paper.md ## Claim boundary - 可以描述为条件性的访问控制机制 - 不能把 NFT ownership 写成现实身份的证明 - 不能声称它单独防止共享、私钥泄露或终端入侵 ## Read order 1. current_task.md 2. terms_and_symbols.md 3. 任务涉及的论文段落 ## Current stage 引言主张强度校准

这个地图很短，
但它已经足够让下一轮知道：

• 目标是什么
• 主文件是什么
• 边界在哪里
• 先读什么
• 当前处在什么阶段

7. 为什么读顺序也要写进地图？

因为 AI 并不总知道应该先看什么。

如果没有读顺序，它可能：

• 先读错文件
• 先看无关章节
• 先进入细节而忽略总目标
• 在缺少前提的情况下就开始动作

所以读顺序不是形式要求，
而是为了让 AI 先建立正确的上下文层级。

本书里推荐的顺序通常是：

1. current_task.md
2. project_map.md
3. 任务相关的正文或代码片段
4. 再进入修改、验证和记录

这样，AI 先知道这轮做什么，
再知道为什么这么做，
最后才进入具体动作。

8. 项目地图和其他状态文件的关系

这一点也很重要。

project_map.md

放长期稳定的项目认知。

current_task.md

放本轮具体任务。

revision_log.md

放为什么这么改、改了什么、验证如何。

open_issues.md

放暂时不能解决，但不能忘掉的问题。

它们不是重复，而是分层：

• project_map.md管“项目认知”
• current_task.md管“当前任务”
• revision_log.md管“修改原因”
• open_issues.md管“未决问题”

项目地图是入口，
其他文件是围绕入口展开的具体状态。

9. 什么时候项目地图会变得太重？

如果项目地图写得太长，它就会失去“地图”的作用。

常见问题有三个：

9.1 目标写得太多

项目目标如果变成了长篇讨论，它就不再是目标，而是文档堆积。

9.2 细节写得太满

地图里不该塞完整历史。
历史应该进日志和 Git。

9.3 长期不更新

如果项目已经变了，地图还停留在旧版本，那它会误导下一轮。

所以项目地图要控制长度，
只保留会改变下一轮动作的内容。

10. 本章小结

这一章想讲清楚的核心是：

AI 编程不能只靠对话窗口记忆，必须有一份稳定的项目地图，让 AI 先读认知，再决定动作。

它的作用不是记录所有事，
而是压缩出一份短、稳、可维护的项目导航模型。
有了项目地图，AI 才能在每一轮任务里先知道：

• 目标是什么
• 关键文件有哪些
• 边界在哪里
• 现在处于哪个阶段
• 下一步应该先读什么

下一章，我会继续讲：当前任务current_task.md怎么把自然语言要求编译成一份可执行、可验收的任务契约。