AI Coding中方案变更后文档修改最佳实践,既省Token,又准确识别最终需求

你有没有遇到过这种情况:一个功能做到一半,方案改了。1. 不修改文档直接改代码，多次修改后发现文档也没记，自己也忘记了。 2. 修改原文档后忘记了修改的历史原因。3.增加一个新版本，浪费大量Token也没让AI搞清楚以哪个为准。此时AI的代码与文档对不上，与你的实际需求也有差异，AI Coding陷入泥潭。

这不是个例,是 AI Coding 里一个非常典型的坑:AI Agent文档 versioning 的方式,直接决定了 Agent 能不能"读懂"你的项目。

这个问题最初被提出时的真实对话记录

01多文档副本,问题比想象中大

大部分AI Agent做方案变更时的本能反应是"另存一份",这背后其实藏着三个问题:

1. 多文档歧义 —— 同一个功能有两份甚至三份设计文档摆在那,Agent 不知道哪个是"当前生效"的方案,只能靠猜或者全读2. 上下文浪费 —— Agent 要把新旧文档都读一遍去做对比,才能搞清楚"到底哪里变了",这个过程消耗的是实打实的 token 和推理成本3. 历史丢失 —— 反过来,如果你图省事直接覆盖原文档,"当初为什么这么设计、后来为什么改了"这条线索也一起被抹掉了。等你自己三个月后回头看代码,也会一脸问号

说白了,这是一个"单一事实来源"(single source of truth)被破坏的问题——只不过在 AI Coding 场景下,后果被放大了:人类还能凭记忆大概判断哪个文档是新的,Agent 没有这个直觉,它只能靠文件结构和文本内容做判断。

· · ·

02核心原则:一个功能一份权威文档

推荐的做法其实很简单,就一句话:

💡 一个功能只有一份权威设计文档,永远不改文件名,永远不建 v2/v3 副本。

方案怎么变,就在原文档里原地更新。变更的过程,靠"文内修订记录"去追踪,而不是靠"另开一个文件"去追踪。

03具体怎么做

落地成四个动作:

1. 原地更新方案变了,就直接把新内容写进原文档,比如截图中我的项目里的 body-discomfort-interactive-diagram-design.md,它永远是这个功能唯一的当前方案,文件名不变。

2. 顶部加修订记录表在标题下方放一张简短的表格,记录"什么时候、改了什么版本、为什么改":

日期	版本	变更说明
2026-07-09	v2	交互模式从"图纸点击+Chip导航双模式"改为"统一chip选择+图纸仅查看"
2026-07-08	v1	初版,引入 SVG 人体图纸 + 双模式交互

3. 旧方案归档,不占主视线原方案内容不删,挪到文末的折叠区(用 <details> 标签,或者一个"## 附录:历史方案"的二级标题),读者/Agent 默认不需要看,但需要溯源时随时能查。

4. Git commit 做变更摘要文档记录"改了什么、为什么改"这种结论性信息,而具体的"每一次改动细节"交给 git log --oneline 去追——这本来就是它的强项,不用文档重复劳动。

· · ·

04为什么这套方法特别适合 AI Coding

场景	效果
Agent 找方案	搜文件名 → 只有一份,无歧义
Agent 读方案	从顶部读起,前200行就是当前有效方案
Agent 理解背景	修订记录表 + git log 快速建立时间线
上下文不够	可以跳过附录历史方案,不影响理解当前逻辑
人类 review	单一文件,diff 清晰,一眼看出这次改了哪一段

💡 一句话总结:Agent 不需要"更多信息",需要的是"更少歧义"。减少文档数量,比增加文档细节更重要。

· · ·

05可以直接抄的Rule模板(建议收藏)

如果你想把这套习惯直接用到自己的项目里,下面这份规范可以整段复制,粘贴进你的项目文档或者 AI Coding Agent 的规则文件里:

设计方案文档管理规范

设计方案变更是常态。为避免 AI Agent 在多版本文档间产生歧义、浪费上下文、无法定位权威方案,统一遵循以下规则。

核心原则:一功能一文档一个功能模块只有一份权威设计方案文档,永远不改文件名,永远不建 v2/v3 副本。

文档存储位置docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md

变更操作流程

1. 原地更新将当前方案内容更新到原文档中,它始终是唯一的权威方案

2. 文档顶部加修订记录标题下方维护一个简短表格,记录每次变更的日期、版本、变更说明:

> 状态:已实施 | 最后更新:YYYY-MM-DD(版本说明)

日期	版本	变更说明
YYYY-MM-DD	v2	变更说明
YYYY-MM-DD	v1	初版

3. 旧方案归档文末被替换的旧方案放在文档底部的"附录:历史方案"折叠区(<details> 标签)中,不占主要阅读视线,仅供了解历史沿革备查

4. Git commit 做变更摘要commit message 清晰描述变更原因和内容,git log --oneline 即可快速浏览功能演进脉络

设计考量(针对 AI Coding 场景)

场景	效果
Agent 找方案	搜文件名 → 只有一份,无歧义,无需判断哪个是"最新版"
Agent 读方案	从顶部读起,前 200 行即当前有效方案,无需对比多文档
Agent 理解背景	修订记录表 + git log 快速建立时间线,知道"为什么改"
上下文受限	可跳过附录历史方案,不影响对当前方案的理解
人类 review	单一文件,diff 清晰,变更范围一目了然

不做什么

✗ 不建 xxx-design-v2.md、xxx-design-revised.md 等副本✗ 不在旧文档中仅添加"指向新文档"的链接然后弃用✗ 不覆盖旧文档而不留修订记录✗ 不对同一功能维护两份并存的设计文档

发布/更新一份 Spec 文档之前,一定要人工对照检查一下，AI Agent不可信:

☑ 是否复用了原文档,而不是新建了 v2/v3?☑ 状态行是否更新到了最新日期和版本号?☑ 修订记录表是否新增了一行,说明改了什么、为什么改?☑ 旧方案内容是否完整挪进了附录折叠区,而不是被直接删除?☑ 是否用规范的 commit message 提交了这次文档变更?

这套方法不复杂,但它背后其实是个更值得琢磨的问题:AI Coding 时代,我们给 Agent 准备的"知识载体",到底该怎么设计才既省 token 又不丢历史?文档结构本身,可能比我们以为的更值得花心思。

👍 你在用 AI Coding 时,是怎么处理方案变更和文档更新的?是也踩过"v2文档"的坑,还是有自己的一套方法?欢迎留言聊聊。