三个Markdown文件给Claude Code装外置大脑，彻底解决会话失忆

同事路过我工位瞟了一眼终端里满屏滚动的代码突然问了一句“Claude Code这玩意儿不是经常失忆吗你真不怕它哪天把项目搞炸”我正盯着一个新报错头也没抬就回了一句“怕啊所以我给它装了个外置大脑三个Markdown文件。”他愣了一下然后拉了个椅子坐下了。其实他问到了点子上。Claude Code这类AI编程助手能力再强本质上还是一个“会话型”的工具。你每次关掉终端、开新会话它对你项目的了解基本归零。它不记得你昨天刚定下的接口命名规范不记得你为了一个编码问题折腾了两个小时更不记得项目经理反复强调“这个模块千万不能动”。这种失忆轻则让你重复解释重则让它把你好不容易调通的代码“优化”回坑里。我今天想聊的就是怎么用最朴素的办法——三个Markdown文件——给Claude Code装一个不会丢的外置大脑。这套方法我已经在几个项目上跑了几个月实测下来失忆带来的返工至少少了一半而且成本几乎为零。1. Claude Code为什么会“失忆”失忆到底有多危险1.1 上下文窗口不是硬盘关了终端就是天亮很多人对Claude Code有个误解觉得它跟你聊过的东西它就“记住”了。实际上它记住的内容全部存在于当前会话的上下文窗口里也就是那几十万token的临时空间。这个空间再大也是短时记忆不是硬盘。一旦你退出会话、重启终端或者用--continue续聊之前中间隔了太久那些对话细节就会全部清空。Claude Code本身不是完全没有记忆设计。它启动时会自动加载项目根目录下的CLAUDE.md文件你也可以通过/memory命令把一些要点写进去。这是官方给的“记忆机制”。但问题也出在这很多人的CLAUDE.md要么是空的要么是安装时自动生成的模板要么被塞成了一部百科全书。真正的项目状态、决策过程、踩坑记录压根没地方放。用大白话讲上下文窗口像是你办公桌上的一块白板。白板只能写这么多写满了就得擦。CLAUDE.md是贴在你显示器边上的一张便利贴上面写了“项目叫什么、用什么技术栈、怎么跑起来”。但便利贴上没写“昨天那个登录逻辑为什么要用token而不是session”也没写“这个接口的参数顺序千万不能改”。所以一旦对话上下文被压缩、被截断或者干脆开了新会话这些关键信息就从Claude Code的“脑子”里蒸发了。1.2 真正危险的几种“失忆”场景失忆最可怕的地方在于它不是“不知道”而是“不知道但以为自己知道”然后按照自己的理解乱来。我总结了几个真实踩过的场景每个都挺有代表性。第一种新会话复读已解决的Bug。比如你花了一晚上排查出一个诡异的时区问题并且改了代码、写了注释。第二天新开一个会话让Claude Code继续做另一个功能它扫到相关代码觉得“这个写法不够优雅”顺手就给你“优化”了时区问题原地复活。它不是坏它是真的不知道你昨天经历了什么。第二种违反你反复强调的约束。你可能在昨天的对话里明确说过“这个API的调用不能加重试逻辑因为接口幂等性没做好”。但这句话只存在于昨天的上下文里。今天它看到网络请求出于“稳健性”的惯性又给加上了重试直接把线上问题引爆。第三种反复横跳的架构决策。周一你让Claude Code把配置管理从环境变量迁到配置文件周二又让它接入一个配置中心周三你不在它看着代码里的两套方案自作主张都保留了。等你回来项目里多了一堆没人说得清为什么存在的兼容层。这些问题的共同根源都不是Claude Code能力不行而是它缺少一个跨会话的“长期记忆”。AI本身没有时间观念你上次会话里的所有约定对它来说都像是上辈子的事。所以问题的解法不应该是“祈祷它别忘”而应该是“把重要的事写到它每次启动都能看到的地方”。这就是我那个外置大脑的由来。2. 三个Markdown文件组成的“外置大脑”整体思路是什么2.1 为什么偏偏是Markdown而不是数据库或者别的工具你可能觉得给AI配记忆应该上什么向量数据库、知识库、Notion、飞书文档之类的专业工具。我一开始也这么想过后来发现全是过度设计。原因很简单。第一Markdown是纯文本Claude Code读起来几乎不消耗额外理解成本你把文件路径用符号一引用它就能直接读到内容。第二Markdown天然支持用Git做版本管理每次修改都能看到diff改坏了随时回滚这比任何“知识库”都更可靠。第三你作为人类也能轻松阅读和编辑不需要打开任何特殊软件终端里vim一下就能改。第四没有依赖不会因为某个平台的API变动导致整个记忆系统瘫痪。我之前见过有人给Claude Code专门搭了一套RAG检索系统把项目文档全部切片、向量化然后每次对话前先检索一遍。听着很酷但实际用起来检索质量不稳定有时候该召回的内容召不回来还白烧token。相比之下三个Markdown文件这种“确定性记忆”虽然看着土但它100%会被加载、100%不会被检索漏掉。对于编程助手这种场景确定性比智能重要得多。2.2 三张“记忆卡片”的职责划分我管这套系统叫“外置大脑”因为它模仿的正是人脑记忆的三种基本类型地图记忆、工作记忆、经验记忆。对应到文件上就是下面这三个第一张卡片CLAUDE.md放在项目根目录。它相当于大脑里的“地图”负责回答“这个项目是什么、代码怎么组织、有哪些硬性约定”。因为Claude Code每次启动都会自动读它所以它必须是所有记忆文件的总入口。第二张卡片docs/memory/progress.md我管它叫“进度快照”。它负责回答“项目现在走到哪一步了、上一次会话干到哪了、下一步该干什么”。这个文件是动态的每次会话结束都要更新。第三张卡片docs/memory/lessons.md我管它叫“教训清单”。它负责回答“这个项目里哪些坑踩过了、哪些决策是怎么定下来的、哪些事绝对禁止做”。这个文件是长期积累的越用越值钱。三张卡片各司其职互不越界。CLAUDE.md不写琐碎的进度progress.md不写长篇大论的经验lessons.md不写临时的待办事项。只有这样Claude Code在读取的时候才能各取所需不会在一个文件里迷失。2.3 为什么这一套能防住“搞炸项目”你可能会问光靠三个文件怎么就能防住项目被搞炸关键在于Claude Code搞炸项目的路径通常不是“恶意破坏”而是“不知情的破坏”。它不知道这个函数有历史包袱不知道那个配置项被外部系统依赖不知道某段代码为什么长得这么丑但千万不能动。外置大脑起的作用就是把这些“不知情”变成“知情”。每次会话启动Claude Code先读地图知道项目的全貌和规矩再看进度快照知道自己该从哪接着干最后翻教训清单确认哪些雷区绝对不能碰。这样一来它的每一次操作都是在完整记忆的约束下进行的而不是在一个空白的脑子里自由发挥。当然这套系统不能保证100%不犯错。它不能替代代码审查不能替代测试更不能替代你在关键操作前的确认。但它能把“随机犯错”的概率大幅降低为“被约束的小概率失误”。在AI编程这个场景里能把概率降下来就已经赚大了。3. 手把手搭好你的外置大脑模板与实操3.1 文件一项目地图CLAUDE.md的正确姿势很多人的CLAUDE.md是从官方模板抄的写满了使用说明唯独没有自己项目的信息。我的建议是把它彻底推翻重写成一份真正的“项目地图”。下面是我现在用的模板你可以直接抄# 项目概述 一句话说清楚这个项目是干什么的目标用户是谁。 # 技术栈 - 后端Python 3.11 / FastAPI - 数据库PostgreSQL 15 / SQLAlchemy 2.0 - 前端React 18 / TypeScript - 部署Docker / GitHub Actions # 目录结构 - app/后端主代码 - app/api/路由层只做参数校验和响应封装 - app/services/业务逻辑层核心代码都在这 - app/models/数据库模型 - frontend/前端代码 # 硬性约定 1. 禁止在 service 层直接操作数据库必须走 repository 2. 所有对外接口必须返回统一格式{code, message, data} 3. 错误处理一律使用全局异常处理器禁止到处 try-catch 4. 命名使用 snake_case数据库表名使用复数 # 常用命令 - 本地启动make dev - 跑测试make test - 代码检查make lint # 记忆文件索引 - 当前进度快照docs/memory/progress.md - 历史决策与踩坑记录docs/memory/lessons.md 每次任务开始前必须首先读取以上两个记忆文件再开始动手写代码。注意最后那个“记忆文件索引”段落这是整个外置大脑的神经中枢。没有这一段后面两个文件就算建了Claude Code也不知道要去读。我实测过只要在CLAUDE.md里明确写了“必须首先读取”它在新会话里的第一件事就是去读这两个文件非常听话。还有一个细节CLAUDE.md要尽量精简。它能容纳的内容有限如果写得太长Claude Code在长会话里可能会选择性地忽略后半部分。我的原则是CLAUDE.md只保留“稳定不变”的信息所有动态信息一律下放到另外两个文件里。3.2 文件二进度快照progress.md的更新节奏进度快照解决的是“接续”问题。这个文件的核心价值就是让一个完全失忆的Claude Code在读完这个文件之后能够无缝接上你上次的进度。它的结构应该是高度结构化的方便快速定位信息。# 项目进度快照 更新时间2025-06-14 18:30 ## 当前状态 正在开发用户中心的“登录审计”功能核心逻辑已完成前端页面还差一个导出按钮。 ## 最近完成 - 登录审计的 service 层 repository 层commit abc1234 - 审计日志的数据库迁移脚本migration 20250612 - 修复了审计列表分页时时间字段偏移的 Bug ## 当前阻塞 - 导出功能依赖的 CSV 库版本与项目冲突等待升级依赖后处理 - QA 反馈登录失败时的错误提示文案还没统一 ## 下一步计划 1. 完成导出按钮的前端实现 2. 统一登录失败的错误提示文案 3. 补充登录审计相关单元测试 ## 遗留问题 - 审计日志表的数据量增长很快后续要考虑归档策略 - refresh_token 的过期时间配置在环境变量里部署时别漏我一般是每完成一个阶段性任务就让Claude Code更新一次这个文件。每次会话结束前也会强制执行一次“收尾更新”确保最后的状态是新鲜的。这里有一个小技巧进度快照的时间戳一定要写准确因为Claude Code会以它为依据判断哪些信息是“最新的”。如果时间戳乱写它可能把一个月前的信息当成最新状态那就白搭了。还有一个容易忽略的点进度快照不是流水账。不要把每行代码的修改都记进去只记录“当前状态、最近里程碑、下一步行动、阻塞项”。这四类信息才是接续工作最需要的。写得太碎反而干扰Claude Code的注意力。3.3 文件三教训清单lessons.md的沉淀方法最值钱的就是这个文件。它积累的是你和这个项目的“共同记忆”是任何LLM通用知识库里都没有的“私有经验”。格式我推荐用条目式按主题分类每条尽量简短、可执行。# 历史决策与踩坑记录 ## 关键决策 - 2025-05-20用户状态存储弃用 session改用 JWT。原因微服务化后需要无状态鉴权。影响所有需要用户信息的接口改为从 token 解析。 - 2025-06-02审计日志写入采用异步队列不直接写库。原因高并发下同步写库会拖慢主流程。影响日志查询有秒级延迟可接受。 ## 踩坑清单 - 2025-05-25pandas.read_csv 读大文件时内存溢出。解决改用分块读取 类型压缩。后续注意数据量超过 500MB 时必须走分批方案。 - 2025-06-08Docker 容器内时区为 UTC导致任务调度错乱。解决Dockerfile 里增加时区配置。后续注意任何时间相关功能都要显式指定时区。 ## 禁止事项 - 禁止在事务块内调用外部 HTTP 服务会导致数据库连接长时间占用。 - 禁止直接修改 app/models/ 下的模型后不生成迁移脚本。 - 禁止为了过 lint 而加 # noqa 注释有问题的代码应该修根因。 ## 用户偏好 - 代码注释使用中文但变量名和函数名保持英文。 - 测试文件必须与被测模块保持相同目录结构。 - 提交信息使用 Conventional Commits 规范。这个文件有两种写法一种是让Claude Code在执行任务的过程中主动记录另一种是你自己汇总后让它整理。我的经验是高价值的教训比如“禁止事项”和“关键决策”最好由你自己确认后写入因为AI有时候分不清什么是“值得记的历史”和“随手带过的细节”。而那些琐碎的踩坑记录可以直接让AI在遇到问题时顺手记下来你再定期审查就行。教训清单是“越用越值钱”的典型。项目跑三个月后你再回头看这个文件会发现里面记录的那些“禁止事项”几乎每一行都对应过一次线上事故或者一次通宵排查。这些东西比任何代码注释都更能防止Claude Code以及你的同事重蹈覆辙。3.4 怎么让Claude Code每次都主动读这些文件文件建好了关键是怎么让Claude Code养成“开工先读记忆”的习惯。我总结了几种手段从最省事的到最兜底的你可以根据自己的情况组合使用。第一招也是最核心的一招在CLAUDE.md里写明“每次任务开始前必须读取记忆文件”。因为CLAUDE.md是自动加载的这条指令就等于在每次会话一开始就给它设定了一个“先读文件再干活”的前置步骤。实测下来大多数情况下它都会乖乖照做。第二招在会话开始时手动引用。你可以在第一句话里直接写“先读一下 docs/memory/progress.md 和 docs/memory/lessons.md然后告诉我项目的当前状态和我的下一步计划。”这种主动引用的方式比让AI自己发现文件要可靠得多因为引用是强制的它在对话里一定能看到文件内容。第三招利用/memory命令。Claude Code的/memory命令可以查看和编辑CLAUDE.md你可以用它把一些临时的重要信息固化进去。但我个人用得不多因为/memory编辑的是CLAUDE.md这个文件而我不希望它变得臃肿。更多时候我会直接用自然语言说“把这个决策记到lessons.md里”让它在文件末尾追加一条。第四招收工时的“交接仪式”。每次会话结束前强制让Claude Code更新progress.md把“当前状态、下一步计划、遗留问题”写清楚。这一步做到位了下次开新会话时哪怕你什么都不说它读了进度快照也知道从哪继续。4. 一次完整“防失忆”工作流是怎么跑下来的4.1 开工前先把大脑“接上”理论说完了我拿最近一个实际功能的开发过程来演示一遍完整流程你就知道这套系统在日常工作中到底怎么运转。假设今天是周五我下午要接着开发“订单导出”功能。早上的会话是我昨天开的已经关了所以现在的Claude Code是一个彻底的“失忆状态”。我在终端里敲下claude命令等它启动后没有直接说“帮我做订单导出”而是先发了一条指令“请先读取 docs/memory/progress.md 和 docs/memory/lessons.md然后告诉我项目当前状态是什么、订单导出功能进行到哪一步了、有没有相关的注意事项。”大概十几秒后Claude Code回复说“项目当前正在开发订单导出功能service层已完成前端页面缺少导出按钮。注意lessons.md里有一条提醒CSV库版本冲突尚未解决以及导出文件名中的时间戳要使用Asia/Shanghai时区。”这一步极其关键。我没有给它任何额外信息它仅仅通过两个Markdown文件就完整恢复了对项目的上下文。接下来我只需要说“继续把导出按钮做掉”它就直接开干完全不需要我复述需求、翻旧代码、找接口位置。4.2 干活中什么时候写入最关键在Claude Code干活的过程中我一般会保持比较高频率的“记忆写入”。你不要等整个功能做完再一次性记录那样中间产生的大量有价值的决策和坑点早就被上下文挤掉了。我的习惯是每当出现下面这几种情况就立刻让它写入第一种做了一个关键的方案选择。比如今天它告诉我实现导出功能有两种方案一种是直接用csv库手写流式输出另一种是引入pandas的to_csv。考虑到数据量不大而且项目里不想新增重型依赖我决定选第一种。这个决策虽然小但很重要因为几天后如果我来加“导出格式支持Excel”就得知道当初为什么没上pandas。我就说“把这个决策追加到lessons.md注明原因。”第二种发现了一个新的坑。比如它在写流式导出的时候发现文件编码如果用默认的utf-8用户在Windows上用Excel打开会乱码。这个问题是典型的“今天不记、明天必忘”。我让它把“导出CSV必须使用utf-8-sig编码”写进踩坑清单并且补进CLAUDE.md的约定里去。第三种需求发生了变更。比如我在它做导出的时候突然收到产品消息说要增加一个“仅导出最近30天”的筛选条件。这种变更如果不记录下次它可能会按照旧需求把整个功能重写一遍。我让它更新progress.md的“当前状态”把新需求写进去。简单说干活的整个过程就是“写代码”和“写记忆”交替进行的过程。每有一件值得让未来记住的事情发生它就落盘到Markdown文件里。这样做的好处是等到一个功能真正完成的时候你手里不只有代码还有一份完整的开发日志。4.3 收工后5分钟收尾下次直接续上功能做完之后我不会直接关终端而是会做一个五分钟的“收尾仪式”。这个仪式很简单就三句话的事。我通常会对Claude Code说“现在会话要结束了请做三件事更新progress.md的当前状态和下一步计划、检查lessons.md有没有需要补充的新教训、最后给我一个git提交建议。”Claude Code会依次执行把progress.md里“当前状态”改成“订单导出功能已完成”把“下一步计划”改成“联调导出权限控制”“补充导出功能的集成测试”把“遗留问题”里加上“导出的文件大小目前未做限制数据量大时要考虑异步生成”。然后给我几个提交信息建议我挑一个合适的git commit完事。整个收尾过程大概五分钟。这五分钟换来的是下周任何同事也好未来的你也好打开progress.md都能在三分钟内完全接手项目状态不需要重新翻代码、猜意图、问上一手开发者。对了还有一个习惯我强烈推荐收工后顺手把这三个Markdown文件一起提交到Git提交信息就写“docs: update project memory”。这样你的外置大脑就有了版本历史哪天发现记忆文件被改坏了直接git checkout就能找回之前的版本。这套外置大脑本身也需要“备份”而最现成的备份就是你的代码仓库。5. 常见问题与排查技巧实录5.1 Claude Code就是不理我的Markdown文件怎么办我刚开始用这套方案的时候也遇到过Claude Code“装瞎”的情况明明文件就在那里它偏不去读自顾自地开始了。排查下来原因基本都是这几个。最常见的原因是CLAUDE.md里的指令写得太模糊了。你写“项目信息见docs/memory”它可能觉得这不是强制要求就忽略了。解决办法是把指令写死比如“每次任务开始前必须先读取docs/memory/progress.md和docs/memory/lessons.md两个文件否则不要开始任何代码工作”。指令越明确它照做的概率越高。第二个原因是文件路径写错了。Claude Code的引用是相对当前工作目录的如果你的记忆文件放在docs/memory/但你在项目根目录启动的Claude Code却用了memory/progress.md这种路径它自然找不到。排查方法是直接在对话里问它“你能看到docs/memory/progress.md这个文件吗”如果看不到它会告诉你路径解析失败你调整一下就好。第三个原因比较隐蔽就是CLAUDE.md文件本身太长导致Claude Code在处理时把“记忆文件索引”段落给折叠或者截断了。解决办法是精简CLAUDE.md保持核心指令在最前面。我现在的CLAUDE.md全文大概就四五十行信息密度很高但很紧凑。5.2 文件被Claude Code写乱了怎么防止灾难外置大脑是由AI来写的那就存在写乱的风险。我遇到过的情况有它把lessons.md里的一条历史教训整个覆盖掉了它在progress.md里堆了一堆没用的中间过程把真正重要的状态淹没最夸张的一次它把CLAUDE.md的硬性约定列表给改写了差点导致整个项目的代码风格失控。针对这个问题我的做法有三个。第一所有记忆文件必须纳入Git版本控制这是底线。哪怕文件被写乱了也能轻松回滚到上一个可用版本。我甚至专门给记忆文件建了一个逻辑分组提交历史里一眼就能看出来“docs”的变更。第二在CLAUDE.md里明确写入一条规则“修改任何记忆文件时不得删除原有条目只允许追加或标注‘已过时’。如果需要重构文件结构必须提前询问我。”这就堵住了AI“自作主张重构”的路径。第三我会定期自己做一次“记忆文件体检”比如每周花十分钟翻一遍lessons.md把已经过时的条目标注出来把重复的教训合并把低价值的信息删掉。外置大脑也需要“整理”就像你的书桌一样不整理就会越堆越乱。5.3 文件越来越长反而变成新的负担记忆文件如果无限增长迟早会膨胀成一个谁也读不下去的“大部头”。我见过有人把lessons.md写了上千行Claude Code每次读文件都要浪费大量token而且真的读到有用信息的效率反而降低了。我的处理办法是分层归档。lessons.md只保留“最近三个月”的高价值教训超过三个月的我把它们转移到一个归档文件里比如docs/memory/lessons-archive-2025-q2.md并且在lessons.md顶部注明“历史归档见docs/memory/lessons-archive-2025-q2.md”。这样Claude Code日常只读活跃记录真需要查历史时再让它去翻归档文件。progress.md的处理方式更激进一些。因为进度快照追求的就是“最新状态”我每次收工更新时都要求Claude Code把上一轮的内容精简掉只保留最新的一版“当前状态”。简单说进度快照永远保持在“当前时间点”这一个版本不搞历史堆积。历史内容由Git负责保留progress.md只负责当下。还有一个技巧就是给记忆文件设置“篇幅上限”。我通常在CLAUDE.md里写一句“progress.md不得超过80行lessons.md不得超过200行超出部分需要精简或归档”。Claude Code在更新文件时就会主动控制篇幅不会越长越离谱。5.4 多人协作和多分支场景记忆文件怎么管如果你是一个人开发记忆文件的管理很简单。但如果团队里多个人都用Claude Code或者你经常开feature分支问题就来了A分支的进度会不会污染B分支的记忆我的建议是把“项目级记忆”和“分支级记忆”分开。CLAUDE.md和lessons.md是项目级的跟分支无关因为架构决策和踩坑经验是全项目通用的放在哪个分支都一样。但progress.md是状态级的跟当前工作上下文紧密相关我建议在多分支场景下给每个分支维护一个独立的进度文件比如docs/memory/progress-feature-login.md、docs/memory/progress-feature-export.md。切换分支干活时只需要把CLAUDE.md里的“记忆文件索引”对应改成当前分支的进度文件就行。这个改动很小但能避免“我在登录分支干的活在导出分支读到了错误状态”这种混乱。多人协作还有一个坑两个人同时在lessons.md里追加内容会产生合并冲突。我的处理办法是让每个人负责自己的“负责人前缀”区域。比如在lessons.md里按模块分目录每个人只追加到自己的模块下面。万一冲突了也没关系Git会标出来手工处理一下就好了。说到底团队协作时真正重要的是大家认可“这个文件是权威记忆”只要形成了这个共识技术上的冲突都是小事。6. 我对这套做法的真实感受和几个补充建议这套三个Markdown文件的外置大脑方案我大概用了有四个月。说几个比较主观但真实的感受。首先它带来的最大改变不是Claude Code变聪明了而是我对它的信任度变高了。以前它每改一个文件我都要提心吊胆生怕它“失忆”后胡来。现在有了这套记忆系统它的每一步操作都在“已知的上下文”里进行即便出了错也大概率是逻辑问题而不是“因为不知道所以乱改”的问题。这两者的排查成本完全不是一个量级。其次这套方案的隐性价值是它让你的项目变成了“可持续交接”的状态。以前团队里任何一个人休假项目进度就断档了。现在只要progress.md是新的任何人接手都能快速进入状态。甚至你离职了下一个开发者看这三个文件也能少走很多弯路。最后我想提醒一句的是这套外置大脑解决的是“长期记忆”问题解决不了“判断力”问题。有些坑哪怕Claude Code知道了它也可能因为能力边界而踩进去。所以重要的操作该Review还是要Review该跑测试还是要跑测试。这三个Markdown文件是守门员不是免罪金牌。如果你也想上手试我的建议是从最小成本开始先写一个CLAUDE.md把项目概述、硬性约定、目录结构写清楚再新建progress.md和lessons.md两个空的模板文件在CLAUDE.md里加上索引。不用追求一次到位用着用着你会自然找到适合自己的写法。等哪天你关掉终端第二天打开发现Claude Code居然还记得昨天的一切那种感觉真的会上瘾。