AI 不记得昨天:让项目接得住下一次对话
你有没有过这样一个下午。
昨天花了两个小时才讲清楚的需求,今天新开一个会话,它一句都不记得。你从头再讲一遍,讲到第三句,发现它已经按自己的理解开始改代码了——改的还是另一个文件。
一开始我以为是提示词不够好。后来试着把话说得更长、更细、更"结构化",问题只是从「它不知道」变成了「它知道得不完全」。它会自动补上你没说的部分,补得很合理,然后一路做到底,中途不再回头问你。
所以真正的瓶颈不在模型能力,在状态:智能体每次只活在一次会话里,而项目活在会话之外。
这篇写的是我为这个裂缝长出来的一套东西。不是什么方法论,就是几个文件和几条习惯——它们让一个每次开机都失忆的执行者,也能接住别人的活。
先说清楚
文中的 Codex、Claude Code 只是举例,约定本身与具体产品无关。示例里的路径、接口、业务都是一个最普通的待办应用,不来自任何真实项目;贴出的规则和提示词可以直接拿去改。
上下文不是记忆
先把一个容易混的说法拆开。
上下文窗口是一次性的工作台。会话开始时它是空的,结束时它被清掉。你说「上次我们讨论过」,它没有「上次」——它只有你这一次打进去的字。
用程序员熟悉的类比:**一次会话是一个进程,文件系统是磁盘。**进程退出,内存回收;磁盘上的东西还在。智能体是一个近乎无状态的函数,输入是本次的上下文加上磁盘上的文件,输出是改过的文件和一段回复。
这个类比一旦立住,很多困惑就散了:
- 为什么它昨天明明答应过某个约定,今天又违反了——约定留在昨天的内存里,没落盘;
- 为什么同一个仓库、换一个工具就「变笨」了——不同工具认的入口文件不一样;
- 为什么「记忆功能」不能当保险——它是有损概括,还可能延迟,适合当助手,不适合当契约。
图 1 会话是会退出的进程,文件是留下来的磁盘。中间那条缝,就是所有「它怎么又忘了」的来源。
所以判断标准变得很简单:凡是你希望它下次还知道的事,就必须落在磁盘上,并且能被下一次的它读到。
这句话听起来像废话。但把这几个字当真的话,你会发现绝大多数「AI 不好用」的抱怨,都能归到两件事上:该写的没写,写了但没读。
三个文件,按变化的频率切开
落在磁盘上,落成什么形状?
我的答案是三个 Markdown 文件。不是因为三这个数字整齐,是因为它们变化的频率差了两个数量级。
长期规则一年改两三次;版本计划一周改一次;进度一天改好几次。把频率差这么远的东西塞进同一个文档,结果一定是:改进度要动整个文件,于是没人愿意改,于是文档开始过期,于是它失去被信任的资格——而一份没人信的文档,比没有文档更糟。
| 文件 | 装什么 | 什么时候改 |
|---|---|---|
| AGENTS.md | 长期规则、技术约定、验证要求、操作边界 | 工作方式变化时 |
| docs/PLAN.md | 当前版本的目标、范围、架构、步骤、验收标准 | 需求或验收要求变化时 |
| docs/PROGRESS.md | 完成情况、真实验证结果、已知问题、下一步 | 每个有价值的小任务结束后 |
三分还有个隐性好处:它把「我想做什么」「我们约定怎么做」「现在做到哪」拆成了三件事。这三件事混在一起的时候,最容易出现的失败是——AI 拿「现在做到哪」去反推「我想做什么」。
具体该写进哪个文件,一句话就能分辨:
- 希望它永远这样干(「改之前先说明方案」)→ 规则文件;
- 希望它这个版本这样干(「V1 只做新增和查询」)→ 计划文件;
- 刚刚发生的事实(「接口已实现,前端没联调」)→ 进度文件。
还有一个特别容易被忽略的差别:这三个文件里,通常只有规则文件是被工具主动加载的——Codex 认 AGENTS.md,Claude Code 认 CLAUDE.md,其他工具也各有各的约定名。计划和进度只是普通文档,不会自动进上下文。
所以规则文件里必须有一条:**开工前先读那两份。**这一步不做,前面全白搭:文件写得再好,它没读,等于没写。
图 2 三份文档的区别不在内容多少,而在改动它们的节奏。节奏不同的东西放在一起,先坏的一定是更新的意愿。
规则文件:写边界,不写鼓励
规则文件的正经身份是「开机自检」。它会被自动加载,所以最适合承担一件事:在它动手之前,把该知道的都灌进去。
我见过的大部分规则文件都太长。一屏半的愿景声明、技术选型表、代码风格偏好、目录结构说明……写得很认真,最后每一条都被「遵守」了——因为遵守的成本被摊薄成了忽略。
经验值
规则文件超过两屏,通常说明你把计划写进去了。规则应该是要求,不是背景;背景留在计划里就好。
真正起作用的是那些可以判定对错的条目。长期留在我清单里的是这几条:
AGENTS.md 节选
# 工作方式
开工前先读 docs/PLAN.md 和 docs/PROGRESS.md。
改代码之前,先用两三句话说明方案、涉及的文件、可能的影响。
如果我这次的描述和计划文件冲突,先指出来,不要自己选一个。
一次只推进一个能独立验证的小任务。
验证要真跑。没跑的检查,如实写「未执行」,
不要用「应该没问题」代替。
密钥只从环境变量读,不写进源码、文档、日志。
提交按任务切分,一个提交只做一件事;
不要顺手格式化无关文件。
其中「验证要真跑、没跑就写未执行」那条,是整份清单里最值钱的一条,第 05 节会专门讲它。
另一个反直觉的用法:写「边界」,别写「鼓励」。你可以自由发挥、尽量优雅、用你认为最合适的方式——这些话的实际效果不是提高质量,是允许它用一个漂亮的实现替换掉你真正要的东西。规则的价值在收窄,不在激励。
多工具怎么办
文件名跟着工具走,内容可以完全一样:AGENTS.md、CLAUDE.md、各家 IDE 的规则目录,本质都是「仓库根目录里的一份常驻约定」。
但真正的内容只放一处,其他地方用一句话指过去。两份并行的规则一定会分叉——它们只会在你最不希望的时候分叉,然后你就不知道该信哪一份。
计划文件:写验收,不写愿望
计划文件存的是意图。它防的不是写错代码,是完美地实现了你没要的东西。
这种失败最难受,因为对方没有犯任何错:需求模糊的地方,它选了最常见的解法;边界情况,它按行业惯例处理了;还顺手加了两个「你可能会需要」的参数。代码质量很好,测试也过了,方向错了。
所以计划的写法要反过来:不是描述要做什么,而是描述怎样算做完了。
「支持新增待办」不是验收标准,是标题。
「合法标题保存成功、空标题被拒绝」才是。
一条模糊的目标,通常能收缩成两三条可执行的断言。收缩的过程,往往就是你真正想清楚的过程——你会发现有些地方自己也没想明白,而以前那些地方是靠「写的时候再说」糊过去的。
图 3 同一句话,左边是愿望,右边是三条可判定的断言。中间那步「收缩」,是写计划唯一真正费脑的地方。
粒度上分两层就够:
| 层次 | 内容 | 放哪 |
|---|---|---|
| 版本总方案 | 目标、功能范围、架构、阶段、验收标准 | docs/PLAN.md |
| 单任务方案 | 改哪些文件、接口和数据怎么动、怎么验证 | 简单任务写在会话里;复杂的另起一份并引用 |
总方案写「这个版本做待办管理」;开工一个新功能时,再把它细到接口、数据和验证。复杂模块单独存一份文件,由总方案引用——同一段内容在三个地方各写一遍,是一定会不一致的,而且你永远不知道哪份最新。
还有一条纪律:**未定的事,就写「待定」。**你不写,它会替你定,而且不回来说。三个月后你盯着某段代码想「这设计怎么这么怪」,源头多半是当时一个没人回答的空白。
进度文件:唯一可信的事实来源
三个文件里,进度是最重要的一个。因为它是你判断「现在能不能交付」的唯一依据。
它最常见的退化形态,是变成一句「已完成」。已完成什么?跑过没有?谁验的?
所以我要求它按三个状态分开写,再加两节:
docs/PROGRESS.md 模板
## 已实现
- POST /api/tasks:Controller → Service → Mapper 写入。
## 已验证
- 合法标题提交成功,数据库存在对应记录。
- 空标题返回 400,未写库。
## 尚未验证
- 超长标题的行为(计划里写了,还没测)。
- 前后端联调。
## 已知问题
- 列表接口没有分页,超过 100 条会明显变慢。
## 下一步
- 补超长标题的验证,再做页面联调。
这个格式看着啰嗦,但它挡住了一种很隐蔽的错误:把「写完了」当成「做完了」。
代码已写好、编译通过、验收通过,是三件不同的事。
它们之间的距离,就是「我以为完成了」和「真的完成了」之间的距离。
为什么这件事要交给 AI 写,而不是你自己总结?因为它才是唯一知道刚才到底执行了哪些命令的一方——跑了哪个测试、跳过了哪一步、报错是不是被绕过去了。你要做的不是替它记,是核对它记得对不对。
看到「已验证」里有一条你从没见它跑过的检查,那就是该追问的地方。这种追问一天来一次,比一周后 debug 一轮便宜得多。
图 4 三个状态不是形容词的差别,是有没有独立证据的差别。大多数「明明说好了」的事故,都发生在第一格到第二格之间。
还有一条硬规矩:没有执行的检查,写「未执行」,不要省略。省略会让空缺看起来像通过。
这套流程最大的风险不是 AI 会撒谎,而是它会顺着你的期待做总结——你说「应该差不多了吧」,它就会写「基本完成」。这不是恶意,这是对齐。
Git:一个随时可以后悔的按钮
Git 在这一套里的角色,不是版本管理,是后悔药。
AI 改代码的速度远快于你 review 的速度。没有提交点,一次跑偏的改动会和你确认过的改动混在同一堆工作区里,想退回某个状态,只能靠记忆。有了按任务切开的提交,退回一步的成本是几秒钟——这个成本降下来,你才敢放手让它改。
所以提交的粒度按「可验证」切,不按「文件」切:
- 方案和规则定稿 → 一个提交;
- 工程骨架能跑起来 → 一个提交;
- 一个接口实现并通过验证 → 一个提交;
- 页面对接完成 → 一个提交。
同一个任务涉及的代码、必要测试、进度文档,一起提交;无关的格式化、顺手改的注释,不要混进来。理由不是洁癖:提交信息是你和 AI 未来共同的检索索引。「上次那个分页是怎么加的」,答案应该是一个提交,而不是翻三天聊天记录。
顺序也有讲究。先提交文档和规则,再提交骨架,再逐个功能——这样提交历史本身就是计划的执行轨迹。新会话顺着 git log 读一遍,比读任何总结都快,因为它是真的。
坑 01
.gitignore 不是保险箱
忽略规则只影响尚未被跟踪的文件。密钥一旦进过历史,补一行 .gitignore 没有任何作用——它还在提交里,git log -p 一眼就能翻出来。
发现之后只有两条路:改写历史(麻烦,且可能已经推过),或者换掉那把密钥(便宜)。真话是,后者通常更省事。
最后一点常被高估:远程仓库是备份,不是流程的一环。没配 GitHub 也能本地提交、看历史、回退。不要因为「还没建远程」就跳过提交——那是把唯一的后悔药也省了。
提示词是工单,不是咒语
工单要有四样东西:做什么、做到哪、怎么算做完、做完之后干什么。
日常任务模板
阅读 AGENTS.md、docs/PLAN.md、docs/PROGRESS.md,核对相关代码。
本次目标:【要实现或修复什么】
任务范围:【包含什么,以及明确不包含什么】
验收要求:【可验证的条目,或直接引用计划里的编号】
改之前先说明方案和影响;完成后执行相关验证,更新 PROGRESS.md,
明确写出未完成、未验证的部分。
最后检查本次差异,只提交与本任务相关的改动,写清提交说明。
本次只做本地提交。
比模板更重要的,是给指令分权限。同一个需求,至少有三种说法,后果完全不同:
| 说法 | 许可的动作 | 什么时候用 |
|---|---|---|
| 只讨论 | 说明影响、给建议,不动任何文件 | 还没想清楚,想先听判断 |
| 只改文档 | 更新计划和规则,不碰代码 | 方向定了,方案还没落地 |
| 改并实现 | 改代码 + 验证 + 更新进度 + 提交 | 想清楚了,一次做到底 |
这三档解决了一个很实际的问题:你经常在还没想清楚的时候,就想让它「先看看」。一旦它把「看看」理解成「动手」,你要么接受一个没想清楚的设计,要么回退十分钟的工作。
把「想」和「做」分开,是控制智能体最便宜的手段,比任何提示词技巧都有效。
反过来,当约定已经在文件里,提示词就可以很短:
按原计划完成下一项,验证后更新进度,只做本地提交。
这句能成立,是因为背景、规则、验收都在磁盘上,它读得到。这就是工程化的红利:你不需要每次都把上下文背一遍,只需要保证它读得到。
什么时候该换会话
不是按消息条数,也不是按 token 用完,是按阶段边界。
会话越长,里面堆积的废弃方案、临时决定、「先这样试试」就越多。这些东西不会被删掉,只会持续参与推理。到某个点,它会开始用一个你早就放弃的方案来解释现在的代码——不怪它,怪上下文里那段没标作废的历史。
| 情况 | 建议 |
|---|---|
| 同一个功能正在实现、验证、修 bug | 继续当前会话 |
| 完成一个阶段,准备进下一个模块 | 适合新开 |
| 需求分析转开发,或开发转部署 | 适合新开 |
| 只是隔了一天,仍在做同一件事 | 接着用原会话 |
| 无关话题和废弃方案太多,重点已变 | 整理交接后新开 |
| 中途问一个相关的小问题 | 继续当前会话 |
一句话原则:**能在一条消息里说清「现在做到哪、还差什么」的时候,就可以换了。**说不清楚,说明进度文件该更新了——那是文档的问题,不是会话的问题。
另外两个容易踩的点:功能和验证正在进行时别换,你会把验证现场丢掉;换了 worktree 或换了分支,记得在新会话开头核对一遍——这是「AI 记不住」之外的另一类事故:文件是对的,位置是错的。
交接:把上下文压成一段能复制的话
换会话本质上是一次上下文压缩。压缩必然丢信息,所以要规定丢什么、留什么。
交接分两半:旧会话的最后一条指令,和新会话的第一条指令。
旧会话临走前,让它做三件事:核对真实状态、更新进度、给出一段可以直接复制的话。
交接说明示例
已完成新增待办的后端接口。
已验证合法输入和空标题输入;前端尚未联调。
当前位于【目录】的【分支】,工作区没有未提交改动。
提交记录:3 个,仅本地,未推送。
下一步:接入新增待办页面,验证成功和失败提示。
详细状态见 docs/PROGRESS.md。
这段话的价值不在于全,在于准确。它必须包含六件事:做到哪、验过什么、没验什么、在哪、提交情况、下一步。少一项,新会话就得猜,而猜出来的东西通常比空白更危险。
新会话的第一条指令,只干一件事:只读核对,不许动手。
新会话开场
阅读 AGENTS.md、docs/PLAN.md、docs/PROGRESS.md,
检查当前目录、分支、最近提交、未提交改动和相关代码。
结合下面的交接说明,告诉我:现在做到哪、哪些没验过、
下一步是什么、文档和代码有没有对不上的地方。
本次只核对,不修改任何文件。
【粘贴交接说明】
这条指令看着啰嗦,但它挡掉的是最贵的一类错误:新会话理解错了,然后在错误的理解上干了半小时。让它先复述,你花三十秒确认,比事后回退便宜得多。
图 5 交接不是礼貌,是协议。中间那段话是压缩包,新会话先解压并复述,确认无误才放行。
坑 02
为了交接好看,把没验的写成验过了
这是这套流程里唯一会自我摧毁的错误。为了交出一个干净的状态,把「没跑通」写成「已实现」、把「应该可以」写成「已验证」——下一次你或者 AI 相信了这句话,就会在一个不存在的地基上继续盖。
宁可交接一个难看但真实的状态。可信度是这套东西唯一的资产,崩一次就再也修不回来。
熟练之后,可以把「核对」和「执行」合成一条指令。但「先只读核对」这个习惯建议保留到你完全信任这套文档为止。
fin
尾声:被管住的其实是你
这套东西表面上在管理 AI,实际收益全在自己身上。
你要写规则,就得先想清楚什么是不容商量的;你要写计划,就得先想清楚怎样算做完;你要写进度,就得诚实面对哪些只是「写完了」。这些事以前可以糊过去,因为执行的人是你,模糊的地方由直觉补上——而直觉不进文档。
智能体没有直觉。它只有你写下来的东西,和它对空白处的合理填充。你写得越含糊,它填得越自信。所以它其实是一面很诚实的镜子:你思路里所有没想清楚的地方,都会被它执行出来。
我现在不太在意「AI 能不能独立做完一个项目」这种问题了。更实际的判断是:这个仓库能不能让一个刚进来的人——或者一个刚开机的智能体——在半小时内搞清楚它在做什么、做到哪、接下来做什么。能做到,说明工程习惯是过关的,用不用 AI 都一样。
至于忘记这件事,它不是缺陷,是它的工作方式。一次会话就是一个干净的进程:进来、干活、退出,不留残余。你不需要让它记住,你只需要让项目记住。
然后你会发现,需要被记住的东西其实比想象中少得多。三个文件、一条提交线、一段每次都要说的话。
文中的工具名、路径、接口与业务场景均为通用示例,不对应任何真实项目或团队。
写于 一个反复重讲背景的周末
涉及 Codex · Claude Code · 通用工程约定
适用 个人项目,以及两三个人的小团队