你知道同事那句话把我问得多心虚吗他指着终端里正在自动改代码的 Claude Code 说“这家伙经常失忆你还敢让它碰项目核心模块不怕它把项目搞炸”我当时的真实反应是怕当然怕。任何用过 AI 编程工具的人都懂“失忆”的杀伤力——上上个会话还在跟它确认目录结构新开会话它又开始用老掉牙的旧代码思路乱改。后来我找到了应对方法不调教它的“临时记忆”而是给项目补一个外置大脑。思路简单到不值钱三个 Markdown 文件分别记录项目规矩、当前进度、历史决策提交到 Git 仓库里。Claude Code 每次开工先读一遍这三个文件边干活边更新干完再回写。这招用了一个月我没有再陪它“重新认识项目”超过三分钟。这篇文章就是把我的实战方案写透。我会拆解到底为什么 AI 会失忆为什么用 Markdown 而不是数据库或者 Notion三个文件的职责边界怎么划分具体怎么写才能在启动时被 Claude Code 自动加载以及怎么靠这套机制把“项目搞炸”的概率压到最低。适合正在用 Claude Code 但被上下文丢失搞到崩溃的开发者也适合准备把 Claude Code 引入真实项目但有点慌的团队。1. Claude Code 的“失忆”到底是怎么回事1.1 失忆的根源上下文窗口与会话隔离先说结论Claude Code 并不是真的得了阿尔茨海默它只是没有机会把上一轮对话里确认过的信息留到下一轮。每个会话开始时Claude Code 手里只有我这一条 Prompt加上它在项目目录里能看到的现有代码文件。它不是像人一样按一下“开始”就把整个项目历史都加载进脑海。我之前在这个项目里改过什么、踩过什么坑、淘汰了哪条技术路线它都不知道。它只知道现在这一轮对话、当前看到的代码、以及我刚刚塞给它的那些上下文。如果我的问题涉及的决策发生在上一次会话而这次会话没有把那段背景带进来它就会按照代码当前的样子反推逻辑然后自信地给你一个可能南辕北辙的方案。这个现象在工程上叫“上下文窗口有限 会话隔离”。Claude Code 每次能塞进思考的 token 数量有上限为了一个大型项目里几十个文件的背景都完整保留总要往前滚动压缩和遗忘。更现实的情况是很多开发者在同一个项目代码库里来回开多个会话每个会话就是一次短暂的分工合作。上一个会话里我告诉 Claude Code“我们这个项目权限校验在middleware目录里做别去 service 层重复写 token 解析”下一个会话我只说“把接口权限加上”它大概率会自己找一条“看起来更顺眼”的路径把逻辑写到我不希望它写的地方。用大白话讲Claude Code 像一位业务能力很强的临时工。这位临时工脑子聪明动作麻利但每天上班都八点整失忆一次。他今天帮你把柜子整理出逻辑明天到岗后看到柜子又觉得“这不符合他的审美”重新折腾一遍甚至把昨天固定好的螺丝都拧乱了。你说他不专业吗不是。问题是你没给他留一张“前一天交接表”。1.2 失忆不是 AI 的锅是我们没给它“办公室笔记本”很多同事遇到失忆的第一反应是“Claude Code 不行没法做真实项目。”我不太认同。当你只用一个会话跑完一个小工具从定义需求、写代码、修 bug 到收尾一气呵成它根本不会失忆因为所有信息都在对话里流动。但真实项目不是这样。真实项目动辄十几个模块、几百个文件、跨好几天的迭代。没有哪个会话可以保证从头到尾装着整个项目的全部上下文。想要它稳定就得像带新人一样给新一天的“Claude Code 临时工”递上一份完整的交接文档。这个交接文档就是外置记忆。一个人会失忆没关系只要他失忆后有明确的流程去翻看笔记、按笔记行动、工作完成后再更新笔记他就能长期稳定输出。同样Claude Code 允许我去定义读取哪些文件作为启动时的项目背景也允许在对话中指挥它读取和更新这些文件。既然模型自己有 token 上限我就把“记忆”放到磁盘上要多少容量有多少容量用的时候按需读取。这样每次会话不再是“从零开始理解项目”的笨重过程而是变成一次快速翻阅档案后的无缝续接。2. 为什么偏偏选三个 Markdown 文件当外置大脑2.1 Markdown 是“人、AI、Git”三方通吃的格式你可能想问搞外置记忆为什么不直接上数据库为什么不用 JSON为什么不丢到 Notion 或飞书文档里我的答案很直接因为 Markdown 文件是当前条件下人、AI、Git 三方都能高效读写的最小公约数。Claude Code 本身就是大语言模型驱动的它对纯文本和 Markdown 的理解能力非常强。你给它一份结构清晰的 Markdown它的解析成本低、遗漏概率小比让它去读 JSON 再推理“哪个字段代表已完成”直观得多。人也一样。我一个干了十年的工程师看.md文件时脑子里能直接渲染出层级和重点但让我打开一个 JSON 看记忆数据我脑细胞会死得快一点。Git 更是 Markdown 的天然朋友。文本文件可以做逐行 diff哪个会话改了项目规则、哪段进度记录发生了变化在 Git 历史里一眼就能看明白。我可以清楚地回到文件变化的源头判断 Claude Code 当时做了什么决策。反过来看一下其他方案Notion 文档确实排版漂亮可它没法让 Claude Code 自动读取目录内容接口调用、网络同步、权限策略都是风险点数据库则更适合记录结构化指标不适合记录“为什么这么做”这类可变长度叙事Word 文档不用说了二进制格式不但 Git diff 基本不可读Claude Code 也没法顺畅地做局部修改。Markdown 这种带一点结构、又不至于太重的纯文本格式正好能同时伺候好人类阅读习惯、AI 解析能力、版本控制需求这三方。2.2 三个文件的职责边界长期记忆、工作记忆、历史记忆我不建议把全部记忆写成一个大杂烩CLAUDE.md。一开始我就是这么干的把所有东西塞进去结果文件很快膨胀到几百行。每次 Claude Code 启动时都把这 500 行全读一遍尾巴上的规则早就被开头的大段背景稀释模型在前面的判断里根本没参考到后面的重要约束。真正的做法是拆成三个角色明确的文件。第一个是CLAUDE.md放在项目根目录。它承载“长期记忆”和“行为准则”。主要包括项目是什么、核心目录结构、技术栈、常用命令、代码规范、以及 Claude Code 在每个会话都必须遵守的规则。比如“启动会话时必须先读docs/progress.md和docs/decisions.md”“所有改动都必须先跑npm run lint”“权限逻辑集中在middleware目录不许在 service 层重复实现”等等。这个文件一旦写清楚就会成为 Claude Code 每次开工时看到的默认背景。它的修改频率应该很低隔几周才动一次。第二个是docs/PROGRESS.md承载“当前任务进行到哪里了”的工作记忆。我会在这个文件里写本轮迭代目标、已完成清单、进行中任务、待办事项、当前卡点、下一步计划。这个文件变化最频繁每个工作阶段结束我都要更新它。Claude Code 读它之后能快速知道上回我已经把登录接口的权限模型改完了这次只需要继续做 Redis 缓存部分不用重复修改登录逻辑。第三个是docs/DECISIONS.md承载“项目历史上做过的决策、以及为什么这么决策”的历史记忆。比如“2025 年 X 月 X 日决定缓存策略从本地内存改为 Redis原因是多实例部署内存缓存命中率低影响范围涉及登录态和商品列表接口。”这一个文件极其重要能够拦住 Claude Code 重蹈覆辙。它不会在眼前没有背景时重新想起“要不要去掉 Redis”因为文档里已经清楚写了 Redis 是上轮踩坑后的结论。三个文件的生命周期各不相同CLAUDE.md 是宪法稳定但需要偶尔修订PROGRESS.md 是工作便签每半天改一轮DECISIONS.md 是值班日志只能追加不许随便删除。把这三类信息混在一起是“外置大脑”方案最容易翻车的原因分开才能让每个文件保持短小、干净、高信噪比。3. 实操给 Claude Code 装上这套永不丢失的外置大脑3.1 先搭好 Claude Code 运行环境VSCode 下的安装与配置动手配三个 Markdown 文件之前得先把基础环境跑通。很多新人第一步就容易卡住其实流程不复杂。我自己的主力编辑器是 VSCode。安装 Claude Code 的方式通常是打开终端用 npm 全局安装命令行工具。安装完之后在项目终端里直接运行claude命令就能进入交互式会话。如果你更习惯图形界面在 VSCode 里搜索 Claude Code 相关的扩展安装后在侧边栏或聊天面板里也能调用同一个会话能力。我见过不少人踩一个典型的坑在某个全新环境下照抄网上的安装配置命令把模型名写错或把配置项写到不存在的区块。最直接的提示就是运行时报deepseek-v4-flash is not a model this version of claude code recognizes这类模型不匹配错误——这时候别怀疑人生先去检查环境变量或配置里指定的模型名是不是和当前 Claude Code 版本兼容再检查是不是大小写写错。问题多数出在这两处。基础环境就绪后还需要确认几件事在 VSCode 里建议顺手装一个 Markdown 预览增强插件这样你在写 CLAUDE.md、PROGRESS.md 时能用快捷键看到渲染效果不至于把表格语法写坏自己却看不出来另外确保文件统一用 UTF-8 编码保存避免中文注释或文档被工具读成乱码。3.2 创建三个 Markdown 文件样板与放置位置我推荐的项目结构如下my-project/ ├── CLAUDE.md # 根目录自动加载长期记忆 ├── docs/ │ ├── PROGRESS.md # 工作记忆高频更新 │ └── DECISIONS.md # 历史决策追加式更新把CLAUDE.md放在项目根目录是有讲究的。Claude Code 在启动会话时会把根目录的CLAUDE.md作为项目级记忆自动纳入上下文这是它能看到的默认信息不需要我每次手动提示。另外两个文件放在docs目录下防止它们混在源码根目录显得杂乱。下面是一份可以直接抄的 CLAUDE.md 示例。里面的内容要替你告诉 AI你是谁、你在做什么项目、你有哪些底线规则。# 项目记忆 ## 项目简介 这是一个面向企业客户的订单管理系统。前端基于 React TypeScript 后端基于 Node.js Fastify数据存储使用 PostgreSQL 和 Redis。 ## 关键目录 - src/middleware鉴权、权限校验、请求日志等中间件 - src/services核心业务逻辑按领域模块拆分 - src/routes路由定义禁止在路由中写过多业务逻辑 ## 每次会话开始时的默认动作 1. 先阅读 docs/PROGRESS.md了解目前任务进行到哪一步。 2. 再阅读 docs/DECISIONS.md查看是否有与本任务相关的历史决策。 3. 如果任务涉及核心流程重构先输出一份改动计划等待确认。 ## 编码规范 - 业务逻辑只写进 service 层路由层不承担业务判断。 - 鉴权逻辑统一在 middleware 中实现禁止在 service 层重复解析 token。 - 提交代码前必须运行 npm run lint通过后再结束会话。 - 数据库迁移必须写成独立 SQL 文件不要散落在业务代码里。这里要特别强调Claude Code 在启动时看到 CLAUDE.md 后理论上会遵守那些“默认动作”命令。但自然语言具备不确定性同一句话可能今天被当成强指令明天被当成温和建议。为了让它稳定地执行规则我会在交互开始时补一句“请严格遵守 CLAUDE.md 中定义的会话默认动作”。当这个习惯保持下来整个团队都会慢慢适应这种“先读记忆再干活”的模式。PROGRESS.md 的内容推荐长成下面这样。重点是把当前任务看成一个进展中的工作台不要让 AI 停留在“上次完成了那段代码”的模糊认知里。# 当前迭代订单状态机支持部分退款 ## 本轮目标 - [x] 梳理现有退款流程定位到 refundService.js 中的状态校验 - [x] 设计部分退款状态机PENDING - PARTIAL_REFUNDED - COMPLETED - [ ] 在 refundService.js 实现部分退款可用金额计算 - [ ] 为部分退款新增数据库迁移脚本 - [ ] 补充单元测试与集成测试 ## 当前进展 已完成状态机方案设计约定使用 refund_amount original_amount - refunded_amount。 进行中的实现位于 src/services/refundService.js目前尚未完成金额边界处理。 ## 卡点 当退款单已经存在部分退款记录时并发请求可能导致可退金额计算超卖。 计划先使用事务行级锁解决避免扩大改动范围。 ## 下一步 优先在 service 层实现金额边界校验再迁移数据库脚本。DECISIONS.md 则是一个慢慢变厚的日志我建议采用下方的条目格式把每个重要决策的“时间、决策、原因、影响范围”一并记下。# 技术决策记录 ## 2025-03-12退款金额校验从应用层下沉到数据库事务 - 状态已采纳 - 原因线上出现并发请求下可退金额重复计算的问题应用层分布式锁成本过高 - 影响refundService 中所有退款操作统一走事务脚本 - 备注未来如果引入消息队列可以重新评估异步退款方案 ## 2025-03-01缓存不再使用本地 Map - 状态已采纳 - 原因服务多实例部署后内存缓存无法共享订单查询数据不一致 - 影响缓存迁移到 Redis本地 Map 只用于极短时效的临时标记 - 备注无3.3 让“读文件-写文件-更新文件”成为固定工作流文件创建完并不代表这套系统会自动跑起来。最核心的关键是让 Claude Code 形成“先读记忆、按记忆执行、逐步更新记忆”的工作流。它不会像人一样天生养成这个习惯必须靠 CLAUDE.md 规则和要求反复强化。我实测下来最稳的做法是把规则写成一个“三段式指令”会话开始时读取外部记忆让 Claude Code 先去读三个 Markdown 文件然后在对话开头总结一遍它理解到的关键信息。这一步很关键因为它能逼着模型把读取结果回显出来让我确认它是否真正理解而不只是“读过就算”。分阶段执行任务并定期更新记忆每完成一个子任务让 Claude Code 修改 PROGRESS.md 中对应状态例如把“进行中”改成“已完成”把“下一步”推进一下。这样即使用户中途关掉编辑器下次打开也不会失去现场。任务收尾时沉淀决策如果本次会话做出过值得记录的技术决策要求 Claude Code 追加到 DECISIONS.md。不要只在口头沟通中说“你记得更新一下 PROGRESS”。建议在 CLAUDE.md 的规则里直接把更新机制写死例如“每完成一个 todo 项后将 PROGRESS.md 中对应复选框从[ ]改成[x]同时用一句话说明实现位置。若当前任务产生了影响后续开发的架构性决定在本会话结束前补充到 DECISIONS.md 中。”有人问为什么不用 Claude Code 的 Skill 功能做更复杂的自动化做是可以做我也见过有人写自定义 skill 把这些流程封装成/start、/finish这样的斜杠命令用完非常顺手。但对绝大多数项目来说用 CLAUDE.md 做驱动文件已经足够了。Skill 适合团队规范复杂、需要统一分发到所有成员项目的场景初期不需要把工程搞复杂。4. 怎么防止“外置大脑”本身出现陈旧和冲突既然已经决定把记忆外包给 Markdown 文件就要面对新的恐惧万一外置大脑记忆的内容本身已经过时了Claude Code 拿着旧地图找新大陆岂不是更危险4.1 给每个文件加上时间戳和状态标记这是我这几个月摸索出来的最有价值的小细节。文件如果从标题上看不出最后更新时间AI 就会默认里面所有内容都是“接近真实的全貌”。我习惯在每个文件顶部加入一个更新时间块 最后更新2025-06-14 18:20 当前状态部分退款功能开发中金额校验事务方案已冻结当 Claude Code 读到这部分信息时它能判断这条记忆是否已经快过期。我在 CLAUDE.md 中还加了一规则“若 最后更新”与实际任务时间相差超过一周先主动说明记忆可能过期再基于代码实际情况进行核对不要盲信文件内容。”这样外置大脑就不再是只进不出的杂物间而是一份会自我怀疑的活档案。4.2 先提交代码再提交记忆把三者放进同一个 Git 版本流我不建议每个会话改一套代码却把 Markdown 文件留着不动。正确习惯是让代码、PROGRESS.md、DECISIONS.md 保持在同一节奏提交。比如我做一个功能闭环本地先跑通测试然后 git diff 看一眼改动范围确认代码没有意外波及无关文件再把这三类变更一起提交到仓库。这套流程带来的最大好处是可回溯。哪天 Claude Code 忘了一件事我打开git show commit就能看到上次提交时它把某个功能标记为“已完成”还能从 diff 里找到对应实现文件。如果当时它做得不对我可以直接git revert那次提交而不需要被迫重放一整段漫长对话。这种安全感比单纯依赖 AI 记忆可靠太多。同事担心的“搞炸项目”绝大多数是靠这一条压下去的任何 AI 生成的大范围改动都会先通过 Git diff 审查不会让它在主干上瞎跑。4.3 三个常见错误记忆文件被覆盖、上下文暴增、规则被忽略第一类错误是 DECISIONS.md 被反复重写旧决策被悄悄删除。尤其当文件较短时Claude Code 为了省空间可能直接重写整份文档把之前某个“已采纳”记录弄丢。我在规则里明确要求DECISIONS.md 只允许追加新条目禁止删除或改写历史条目历史记录里如果需要更新状态只能追加一条“状态已废弃”的新记录。这个约束必须写清楚否则模型会认为“精简代码文件”的惯性同样适用于 Markdown。第二类错误是 CLAUDE.md 逐渐膨胀成巨型文件。有人觉得记忆越多越安全恨不得把半年内所有沟通记录都写进去。但文件越大模型实际读取时对每条规则的注意力权重越容易降低达到一定体量后甚至会挤占真正完成任务的上下文空间。所以控制每个文件的体量是我的铁律CLAUDE.md 控制在 100~150 行以内只放稳定且不应该被违反的信息PROGRESS.md 只保留当前迭代结束一轮迭代后把对应内容归档到docs/archive/让它始终保持轻量DECISIONS.md 允许慢慢变长毕竟它的价值在于积累。第三类错误是 Claude Code 没有真正读取这些文件。这种情况时常藏在用户以为“已经说了读文件”但实际上只说了“你看看 docs”这样模糊的句子里。我要求 Claude Code 在回复开头简要复述“根据 PROGRESS.md当前任务卡点是...”如果它复述不出准确内容就说明记忆没有被实际加载。我会立刻重读文件路径而不是继续带着错误的上下文对话。宁可让这一句复述多花一些 token也要确保它真的进了上下文。5. 同事最担心的问题让它做重大项目项目真的会炸吗5.1 “失忆”导致项目炸掉的几种典型现场同事的问题不是空穴来风。我见过不少没有外部记忆机制保护的项目发生过类似事故。比如前两天你和 Claude Code 商量好订单模块开始从单体架构向服务化迁移先只动订单创建链路保留订单查询旧逻辑。结果第二天你重新打开会话随口让它“优化一下订单查询”它不知道迁移边界在哪里非常贴心地按照“新架构标准”重写了查询链路。下游所有接口都还在跟旧数据库交互结果查询全部超时。这个事故不仅发生在菜鸟身上资深工程师也会经历。再比如另一个场景Claude Code 在修改完一个函数后自己把另一个旧文件当成“废弃代码”删掉了。你问它为什么删它說“因为我觉得这个文件已经不再被引用了”。真相是它只检查了局部几个 import漏掉了动态路由加载。这种对项目上下文的不完整记忆才是“搞炸”的真正元凶。有了三个 Markdown 文件之后这类事故的概率被显著降低但并不能归零。外置记忆让 Claude Code 有机会知道自己“不应该碰哪些地方”也让我们有办法在事故发生前看清它的意图。真正可靠的防线依然是人在关键节点把关AI 只是缩小了信息盲区而不是取代了你判断全局的能力。5.2 实操中的保命工作流小步提交、频繁记忆、及时复查把实际工作流程压缩一下大概长这样开工前读 CLAUDE.md、PROGRESS.md、DECISIONS.md让 Claude Code 明确本次会话要达成的目标边界。开发中让 Claude Code 每次执行完一个独立任务后先在本地跑测试不要攒一大堆代码再一次性执行检查和修复。提交前我审查 git diff 中涉及哪些文件和哪些逻辑如果改动跨了多个模块先暂停让 Claude Code 解释不同模块间的改动关系。收尾时更新 PROGRESS.md 的状态和下一步并把关键的技术决策追加到 DECISIONS.md。这套流程很像现实中的代码评审会议。区别是 Claude Code 只需要我提醒一句“把步骤走到”剩下的分析工作基本由它自己完成。例如我常直接告诉它“这个任务结束后请给出建议提交的 commit message并提醒我还需要更新 PROGRESS.md 里的哪些 item。”它的记忆力也许有限但有了这套外部规程大概率能保持有序。5.3 遇到事故怎么快速恢复如果真的出现改动大范围错误怎么靠记忆文件快速恢复我的恢复路径是三步。第一步先看git status和git diff确认当前代码树上哪些文件被这次会话改过不要把责任和困惑放在“AI哪一步错了”上先找回可运行的状态。第二步若代码改动过于混乱直接git checkout -- src/或者回滚最近一次未经确认的 commit把关键路径恢复到一个稳定点。第三步重新打开PROGRESS.md手动把状态改回事故发生前的节点再给 Claude Code 一条清晰指令“刚才那次改动因为改动范围超限而回滚了请基于docs/DECISIONS.md中的迁移边界重新出一个只动orders/create的实现方案。”这套恢复路径真正依赖的不是 AI 多聪明而是 Markdown 文件已经像航海日志一样替你把时间线记录下来。船偏航了没关系只要日志还在你总能找到此前正确的航向标。6. 这套外置大脑方案的进阶方向与实际使用心得6.1 从个人工具变成团队协作规范当团队里不止一个人用 Claude Code 改同一个仓库时三个 Markdown 文件的价值会被进一步放大。团队成员在决策里说“这个模块禁止把middleware改动直接发布需要先过评审”其他人在任何会话里启动 Claude Code 时都会看到同样的规则不需要在聊天里反复同步。它会成为一套活的项目守则。团队模式下我建议把 PROGRESS.md 里的“当前迭代”边界做得更窄。避免多人同时在一个文件里堆任务造成互相覆盖。比较好的做法是每个人都把任务写在同一份文件的不同 todo 区块或者改成给独立分支维护一个docs/PROGRESS_分支名.md合并完再统一收拢到主进度里。至于 DECISIONS.md我倾向把它当成只读共享知识任何人都能在新增决策处追加但不要修改历史块。6.2 和 Markdown 编辑工具搭配效率更佳写 Markdown 文件本身也有不少舒适技巧。我最常用的在 VSCode 中同时打开 CLAUDE.md、PROGRESS.md、DECISIONS.md 并用快捷键唤起 Markdown 预览让自己快速检查表格、checkbox、列表层级是否正常。偶尔会遇到 Markdown 表格复制到某些云端文档后格式炸掉的问题这类问题的根源通常是表格前后没有空行或者列没有对齐。虽然 Claude Code 对乱格式容忍度高但人阅读时那种乱糟糟的界面会极大消耗耐心。给文件留一份清爽的排版本质上也是在给未来的自己降低心智负担。Markdown 语法方面不用刻意追求炫技掌握几个足够好用的特性就行用- [x]表示已完成、- [ ]表示待办用二级标题划分不同任务分支用引用块放一条关键性结论用表格放少量对比型参数。别把它变成一份花哨 HTML越简单越不容易被搞乱。6.3 我个人的最后几条心得踩了无数坑之后我对外置大脑方案的真实评价是它不能让你家 Claude Code 变成神级编程搭档但可以让你再也用不着在每次会话开头重复三年前的背景故事。我过去最怕新开会话因为我知道 AI 也不知道自己在干嘛只想早点把活干完。现在的感觉变了每次新会话就像翻开一本写满批注的参考书Claude Code 自己知道自己是谁、为什么做、边界在哪。如果你正在用 Claude Code 做一个有真实用户的项目我的建议很简单现在就去创建这三个 Markdown 文件把 CLAUDE.md 放在项目根目录把 PROGRESS.md 和 DECISIONS.md 放到 docs/ 下推一次 commit。不需要先读完本文所有理论先跑起来从几行基础规则开始再慢慢补充细节。记忆系统的本质不是让 AI 记住所有而是帮它每次都从正确的起点出发。这句话是我在这个项目里最值钱的一段体会。