同事问我的时候我正在改一个命名不太友好的函数。他说Claude Code 经常失忆你不怕它哪天把项目搞炸我说怕所以我现在给它配了一个永不丢失的外置大脑——三个 Markdown 文件。这不是夸张是实打实踩了很多次坑之后总结出来的方案。如果你也在用 Claude Code 写项目或者已经被它的“失忆”坑过这篇文章应该能帮到你。先交代背景Claude Code 这类 AI 编码工具核心痛点从来不是代码能力而是记忆。它的上下文窗口是有限的每轮对话都会消耗 token会话一长早期的约定、偏好、进度就会从它的“注意力”里滑出去。于是你会看到它把明明统一的命名规范写乱、把已经废弃的接口当主力调用、甚至在你明确说过“不要动这个文件”之后依然自信地改出 bug。这其实不是它故意也不是能力不行这是架构层面的限制——上下文就是个短时记忆撑不住多文件、多轮次、跨会话的复杂项目。我的解决方案说穿了很简单既然它记不住那就让它的记忆落到外置的、持久化的、每次开始都能主动加载的文件里。Markdown 是天然的选择结构清晰、LLM 解析友好、人类也能直接阅读维护。我用三个文件分别覆盖“项目状态”“领域知识”“操作规则”三个维度相当于给它装了一个随身携带的笔记本每次开工先翻一遍。这篇文章我会从三个层面展开一是为什么 Claude Code 会“失忆”、为什么 Markdown 是适合做外置记忆的载体二是三个 Markdown 文件分别怎么写、写什么、边界在哪三是具体落地时怎么配合项目流程和常见坑位。每个部分我都会给可直接抄作业的模板和说明你在自己的项目里基本可以照搬。1. 为什么 Claude Code 会“失忆”本质是上下文管理出了问题1.1 上下文窗口是 AI 编码助手的先天限制很多人第一次用 Claude Code 的时候会高估它的记忆力它能理解整个仓库能一口气改十几处代码看起来“什么都记得”。但用过一个星期就会发现问题——它记的是当前上下文中可见的信息而不是整个项目的历史全貌。你在对话中告诉过它的约定只要不处在前面的窗口内就会逐渐被丢弃或弱化。这个“窗口”是什么概念你可以把它理解成一张只够铺开几张纸的桌面代码文件、对话记录、中间结果都在有限的桌面上争抢位置。窗口越大能放的越多但总有一个上限。当新内容不断进入旧内容就会被从桌面上清理掉。Claude Code 根据 token 数来管理这个窗口超出的内容会被截断、压缩或遗忘。它不会主动去翻磁盘上那些文件除非你告诉它去加载或者它在有限的上下文里本能地选择了忽略。所以“失忆”并不是说它“忘了你说过的话”而是它的记忆机制天然只保存“当前看得见的东西”。你上一个会话里定下的规则下一个会话默认继承不了。Claude Code 确实有一些全局配置和 CLAUDE.md 的机制能让我自定义指令和规则但如果项目复杂、规则一多单一文件很容易变成大杂烩什么都写最后变成什么都没写。这个限制是所有会话式 AI 编码工具的共性不是某一个产品的问题。1.2 为什么说 Markdown 是最适合做“外置大脑”的载体明白了上下文有限思路就清晰了我们要做的不是让 AI“记住所有东西”而是让它每次工作时能快速、准确地把最关键的信息加载回上下文里。这里选 Markdown 有三个原因第一Markdown 是人类和 LLM 都易于理解的格式。你不需要额外的工具就能随手打开修改AI 也能用很低的 token 成本提取标题、列表、表格中的语义。相比 JSON、YAML、数据库Markdown 在“人机共同维护”这个场景下是平衡点最好的一个普通的项目备注可以无缝变成 AI 的提示词源。第二Markdown 的长度可控、结构清晰。你可以用二三级标题把不同主题切分开AI 按需读取不用一次性吞大量内容。配合简洁的列表和表格信息密度高噪音低对上下文来说很友好。我见过有人用 PDF 或 DOCX 做知识库但那些格式的解析成本高、容易引入格式噪音远不如 Markdown 干净。第三Markdown 天然适合放在版本控制里。用 Git 管理三个记忆文件每次修改都有历史记录AI 就算将来出错你也可以 diff 出它干了什么、改了什么。这一点非常重要因为“外置大脑”本身也需要被审计、被回滚不能只指望它不出错。1.3 不同记忆类型要分开放不能塞进同一个文件我在早期踩过一个很典型的坑把所有规则写进一个 CLAUDE.md结果越写越长。业务规则、编码规范、当前进度、待办清单混在一起每次 Claude Code 加载的时候要么截断要么被不重要的内容稀释重要优先级。后来我复盘发现一个文件里塞三种记忆本质上是混淆了“状态记忆”和“知识记忆”——状态是每时每刻变化的知识是长期稳定的把它们放一起任何一方的更新都会污染另一方。所以我的做法是把记忆拆成三个不同职责的文件一个记录“现在在哪里”项目状态一个记录“项目的地图与规则”领域知识与编码规范一个记录“干活时的红线”操作边界与禁止事项。每次开工Claude Code 只会按需读取对应文件而不是一口吃掉所有内容。这个拆分看似简单但对实际使用效果提升非常明显后面我会逐个文件详细说明。2. 给 Claude Code 装“外置大脑”三个核心文件如何规划2.1 文件一项目状态文件PROJECT_STATE.md解决“它不知道现在进行到哪”这个文件的核心使命是让 AI 在每次会话开始时快速了解项目的“当前坐标”。它不需要写历史长篇而是记录四个板块当前里程碑及完成度最近一次修改的模块和文件已知问题 / 阻塞项下一步计划按优先级排序模板我放在下面基本可以直接参考# 项目状态 ## 当前里程碑 - v0.3认证模块重构完成度 90%剩余单元测试补充 ## 最近变更 - 2024-XX-XX重构 login 流程新增 /api/v2/auth/session - 2024-XX-XX修复首页加载 WhiteScreen 问题根因是 provider 顺序错误 ## 已知问题 / 阻塞 - 刷新 token 偶发 401疑似 clock skew 问题待验证 ## 下一步 1. 完成 auth 单测覆盖优先级高 2. 审计 logger 输出防止敏感信息泄漏 3. 整理 API 文档供前端联调写这个文件的时候务必克制。只保留 AI 完成任务真正需要的“事务性信息”就够了不要把什么都往里面倒。项目状态是高频变化的每次会话结束后顺手更新它是这套机制能不能有效的关键。你不更新AI 再强也猜不到你昨天在改什么。2.2 文件二领域知识文件KNOWLEDGE.md解决“它不懂业务规则和通用规范”项目状态解决“进度”领域知识解决“共识”。这个文件面向的是项目中那些长期有效的背景知识和约定比如技术栈和目录结构说明核心业务概念和领域术语已经确定的架构决策ADR关键接口和数据结构示例编码规范和命名约定这里有一个核心原则不要写教科书只写这个项目特有的、AI 不看就会犯错的信息。比如“本项目用 Vue3 TypeScript”是一种约定而“本项目所有组件的 props 必须用 defineProps 声明并导出类型”是更具体、更能防止它写错的东西。后者才值得写进 KNOWLEDGE.md。我通常会这样组织# 领域知识 ## 技术栈 - 前端Vue 3 Pinia Vite组件库使用 Arco Design Vue - 后端Node.js 18 Express PostgreSQL ## 架构约定 - API 统一走 /api/v1 前缀 - 所有写操作必须通过 service 层禁止直接在路由中操作数据库 ## 核心概念 - 订单状态机CREATED - PAID - SHIPPED - COMPLETEDCANCELLED 仅允许从 CREATED 转移 ## 编码规范 - 组件文件名使用 PascalCase - 所有 API 错误返回格式{ code, message, details? } ## 已确定的技术决策 - 2024-XX-XX选用 PostgreSQL 而非 MySQL原因是 JSONB 查询需求较多领域知识文件更新频率低但价值密度高。你会发现有了它之后Claude Code 在几个容易“自由发挥”的点上明显收敛比如接口风格、目录位置、命名习惯。2.3 文件三操作规则文件CLAUDE.md 或 RULES.md解决“它乱动不该动的地方”第三个文件专门用来写优先级最高、绝不能违背的硬约束。在我的架构里这个文件会让 Claude Code 在会话开始时主动读取并当作“最高指令”遵守。它跟 KNOWLEDGE.md 的区别是知识是“应该知道”规则是“必须遵守”。这里面的内容包括但不限于禁止事项不能动哪些文件、不能依赖哪个包必须遵守的流程比如每次提交前先跑 lint 和测试敏感操作警告比如不能直接改数据库 schema命令缩写和工具调用约定为了让 AI 认真对待我通常会把规则写得非常明确避免模糊表述。比如不要写“尽量别修改配置文件”而要写“禁止修改 .env 文件所有环境变量变化需先与项目负责人确认”。# 操作规则最高优先级 ## 绝对禁止 - 禁止修改 .env / .env.* 文件如有需要请联系仓库管理员 - 禁止在未运行 npm run lint 的情况下提交代码 - 禁止删除 migration 目录下任何历史文件 ## 强制流程 - 修改数据模型前先给出 migration 草案 - 涉及第三方支付接口时必须先在沙箱环境验证 ## 命令约定 - 开发服务器npm run dev - 测试npm run test:unit - 构建npm run build ## 重要提醒 - 项目使用 pnpm不使用 npm/yarn 安装依赖 - package.json scripts 中的自定义命令禁止自行覆盖在实际项目中CLAUDE.md 是 Claude Code 的原生配置文件通常位于项目根目录它天然会被自动读取。所以我的建议是把第三个文件做成 CLAUDE.md 的名字或想办法让 Claude Code 在会话开始时自动加载它这样规则优先级最高、最不容易被遗漏。3. 实操过程建立三个文件并让 Claude Code 每次开工先读取3.1 第一步初始化文件目录与模板不要把这几个文件散落在项目各处。我推荐在仓库根目录建立docs/或.ai/目录统一管理 AI 相关记忆文件让它们与代码结构分离。以.ai/为例your-project/ ├── .ai/ │ ├── PROJECT_STATE.md │ ├── KNOWLEDGE.md │ └── CLAUDE.md ├── src/ ├── tests/ └── package.json目录的命名没有绝对标准但建议一进仓库就能看到不要让 AI 去猜这些文件在哪。初始化就是创建三个空模板先把结构搭好。3.2 第二步根据项目现状填充三个文件接下来要做的是一次性“知识迁移”。如果你有一个已经存在很久的项目不可能一下子就写全所有内容我的建议是分优先级高优先级CLAUDE.md 的禁止规则和命令约定必须在第一天就写好因为任何一次 AI 的乱操作都可能造成不可逆后果PROJECT_STATE.md 的当前状态和下一步任务也需要尽快填上否则 AI 不知道从哪里开始。中优先级KNOWLEDGE.md 的技术栈、目录结构、核心概念。这部分可以边做边补不用强求一次写完美但凡是 AI 容易搞错的架构决策建议尽早写进去。低优先级历史故意的技术决策、复杂业务背景、模块间的依赖关系。这些可能你平时也不太讲给 AI但一旦遇到相关任务就是关键信息。建议随用随记不要等到需要时再临时补。3.3 第三步在会话开始时显式加载记忆虽然 CLAUDE.md 有自动加载机制但另外两个文件 Claude Code 不会默认读取。所以我每次开会话第一句就会让它加载记忆类似这样请先读取 .ai/PROJECT_STATE.md 和 .ai/KNOWLEDGE.md然后基于项目状态继续工作。如果你觉得每次手输麻烦也可以在 CLAUDE.md 里嵌一条启动指令或者用 Claude Code 支持的 hooks / 自定义 commands 简化操作。具体支持方式可能随版本变化但核心原则不变把“读记忆”变成开工前的第一动作而不是等任务开始之后才想起来补。我在实践中还发现一个技巧就是让 AI 在回复开头先用“状态确认”的方式复述它读到的核心信息比如“当前里程碑是…已知阻塞是…”这样你可以快速判断它是否真的读进去了而不是假装读了一段。不过不要让它长篇复述浪费 token两三行就够。3.4 第四步每次会话结束同步更新 PROJECT_STATE更新状态文件是整套机制里最容易偷懒、也最影响效果的一步。我自己会把它当成“下班前的五件事”之一要么手动改要么在会话接近尾声时让 Claude Code 自己先总结变更我再人工确认。一个可落地的方法是在会话结束前给 AI 下一条指令请根据本次对话整理变更内容以 PR 描述的形式更新 .ai/PROJECT_STATE.md包括当前里程碑完成度、下一步计划、已知问题。不要改代码。这里有一个注意点千万不要让 AI 在更新状态文件的同时去改业务代码因为状态文件的准确性直接影响下一次开工而自动更新的内容必须经过你的确认不然它可能把工作成果写错。3.5 第五步把知识沉淀变成例行公事KNOWLEDGE.md 和 CLAUDE.md 不应该是一成不变的。每当项目里出现一个“新约定”“踩过一次的坑”“一个容易忘记的架构事实”就把它记进合适的文件。记录的时机越及时成本越低。我自己有一个很简单的习惯当 Claude Code 在某个任务里做对了某件事且它提到过某个规则或约束是我不曾显式告诉它的我会检查它是否真的理解了项目上下文并考虑把这条规则固化到 KNOWLEDGE.md。当它犯了一个违背约束的错我也会立刻补一条规则到 CLAUDE.md防止下次再犯。时间久了这三个文件就成了项目和 AI 之间的“共同记忆库”越来越准。4. 常见问题与排查技巧实录4.1 问题一配置了 CLAUDE.md但 AI 根本不遵守里面的规则这是最常见也最让人崩溃的问题之一。很多人的第一反应是“Claude Code 没用”但检查之后发现其实是 CLAUDE.md 写入的信息跟对话里的冲突或者规则写得不够具体被 AI 在生成长回复时忽略了。排查思路首先确认 CLAUDE.md 是否在项目根目录且命名正确其次看看文件里有没有过长的段落——超过 1000 行的话AI 有可能抓取不到重点最后再确认规则是不是足够 “可执行”。如果某条规则你写成“代码质量要高”AI 依然会自由发挥因为它没有可判定的标准。但如果你写“所有组件必须用 TypeScript 写并且 props 必须显式定义类型”它就很难无视。4.2 问题二PROJECT_STATE 更新不及时下一步指令全是错的这基本属于“人没做好不能怪 AI”。状态文件一旦过期AI 拿着过时的信息开工自然会把精力浪费在已经完成的事情上或者误以为某块逻辑还是旧结构。解决办法是“定义更新触发点”每完成一个小里程碑或每次提交 PR 前必须更新状态文件。可以把这一步做成 Git 提交模板的一部分比如在git commit模板里加一个 “是否更新 .ai/PROJECT_STATE.md” 的勾选也可以用 Claude Code 的 hooks 自动在提交前提醒。我在实践中用的是最笨也最有效的方法在每日站会时让 AI 帮我把当天代码改动汇总成状态更新草稿我审阅后提交。这样既省事又不容易漏。4.3 问题三三个文件内容越写越重叠不知道该放哪个拆分多了也容易踩坑状态文件里写了领域知识知识文件里混了操作规则CLAUDE.md 里又出现进度信息。结果 AI 读到的是三个“半对半错”的信息源反而比没有文件更混乱。我给这套机制定了一条判断标准一条信息如果“会随会话变化”放 PROJECT_STATE.md一条信息如果“长期稳定且描述项目背景”放 KNOWLEDGE.md一条信息如果“是禁止动作或强制流程”放 CLAUDE.md如果拿不准就写进 KNOWLEDGE.md因为它的语义最宽。但你也可以定期做一次“文件审阅”例如每两周花 15 分钟看看三个文件有没有过时或重复的内容删掉无用的、合并相似的保持简洁。4.4 问题四加上这些文件之后响应变慢了 / token 消耗变多了这是很多人对“记忆文件”的另一个顾虑。实际上Markdown 文件的 token 开销很小几百行的知识库也就相当于几千 token相比动辄上万行代码的上下文占比不高。但如果你每次会话都强制 AI 一次性读取全部三个文件确实会浪费一部分窗口。优化方法很简单不是所有任务都需要所有文件。改 UI 的时候不需要读数据库 migration 规则调 API 的时候不需要知道组件命名规范。我的做法是让 AI 根据任务类型按需加载比如在指令里写明“只需要读取 KNOWLEDGE.md 中的技术栈和接口规范”。4.5 问题五多分支并行开发时状态文件会冲突如果你同时开了 feature-A 和 feature-B 两个分支用同一个 PROJECT_STATE.md就会出现相互覆盖的问题。这个痛点是真实存在的因为状态文件本质上反映的是某个工作线的前进情况不等同于仓库主干。我尝试过两种解法第一种把状态文件按分支或工作线拆开比如PROJECT_STATE.feature-A.md在不同会话里指定不同文件第二种在状态文件里加一个“当前分支/工作线”字段每次切换上下文时明确告知 AI 当前服务于哪个分支。如果你是主力用 trunk-based 开发或者单分支工作流这个问题没那么严重可以直接用第二种。4.6 问题六Claude Code 把状态文件改坏了怎么办“外置大脑被 AI 自己改坏了”是很多人不放心把状态文件交给 AI 维护的原因之一。这里我的经验是不要阻止 AI 修改状态文件但一定要用 Git 守住底线。把.ai/目录纳入版本控制每次 AI 更新状态文件后你可以通过git diff .ai/PROJECT_STATE.md快速看到改动如果它写坏或者胡编内容直接 checkout 还原。我甚至会在项目里加一条规则AI 每次修改状态文件后必须输出一句“已更新状态文件”方便我在终端看到它的动作痕迹。用 Git 兜底比任何权限控制都省心。5. 边界与演进外置大脑的局限以及后续还能怎么扩展5.1 别指望外置大脑解决所有问题三个 Markdown 文件这套方案核心价值是把项目的“变数”和“常量”分隔开降低 AI 因上下文丢失带来的风险和返工成本。但它不是银弹解决不了所有 AI 编码问题。比如你在会话里临时交代一个很细的微调要求如果这个要求不会在之后的会话中反复出现那确实没有必要写进任何文件强行写进去反而增加噪音。外置大脑应该记那些“稳定且高价值”的信息而不是事无巨细的流水账。另外只有你主动更新和维护这套文件它的价值才会持续增长。如果连续几周不更新 PROJECT_STATE那么这套机制基本等于失效。AI 工具本身不会替你维护记忆它只是提供了一个可以被“喂记忆”的接口。5.2 后续可以扩展成团队级 AI 协作规范如果你一个人用这套方法跑顺了下一步完全可以把它推广到团队。我这里说的团队级不是简单地把三个文件放到共享仓库里而是让每个团队成员都领会这套分类思路状态、知识、规则分开维护。团队可以在docs/ai/目录下增加一个 INDEX.md 说明让所有人都知道这些文件是干嘛用的、什么时候应该更新。更进一步你可以在 CI 阶段加一个检查比如提交时校验.ai/CLAUDE.md是否包含某些必要的禁止项或者在代码评审模板里增加一项如果这次改动影响了业务约定记得同步更新.ai/KNOWLEDGE.md。当 AI 编码助手从个人玩具升级成团队基础设施时这套“外置记忆”的约束机制会变得越来越重要。5.3 把外置大脑和自动化工作流结合另一个可以探索的方向是把 Markdown 记忆文件接入你的自动化工作流。比如你可以在每天早晨用脚本汇总 Git 日志和 issue 进展自动生成一份当天的 PROJECT_STATE 草稿供你确认后覆盖旧文件或者在上线前用脚本检查 KNOWLEDGE.md 中记录的前端命名规范是否真的被代码库中的所有新文件遵守。我自己目前在实验的方向是把外置记忆文件当作 prompt template 的来源——在 Claude Code 里写一个 command让它根据当前分支、当前 diff 和状态文件生成一份“本次改动目标 潜在风险 应守规则”的启动提示词。这样每次开工AI 不仅能读到记忆还能收到一份针对当前任务的上下文摘要效率比单纯读文件更高。这个方向值得关注因为它的本质是把“外置大脑”从被动读取变成主动工作流的一部分。从我目前的实操体会来说给 Claude Code 配三个 Markdown 文件看起来只是最简单的“写文档”动作但它带来的转变是结构性的你不再依赖 AI 的临时记忆力而是把“约定”和“事实”沉淀成项目的一部分。这让 AI 写代码时不再像无头苍蝇一样乱撞也让团队里的每个人都有一条可以参考的、与 AI 协作的共同路径。工具总在快速迭代但“把重要的东西写到不会丢的地方”这个思路我觉得无论用哪款工具都值得保留。
Claude Code外置记忆方案：用三个Markdown文件打造永不丢失的AI协作大脑
同事问我的时候我正在改一个命名不太友好的函数。他说Claude Code 经常失忆你不怕它哪天把项目搞炸我说怕所以我现在给它配了一个永不丢失的外置大脑——三个 Markdown 文件。这不是夸张是实打实踩了很多次坑之后总结出来的方案。如果你也在用 Claude Code 写项目或者已经被它的“失忆”坑过这篇文章应该能帮到你。先交代背景Claude Code 这类 AI 编码工具核心痛点从来不是代码能力而是记忆。它的上下文窗口是有限的每轮对话都会消耗 token会话一长早期的约定、偏好、进度就会从它的“注意力”里滑出去。于是你会看到它把明明统一的命名规范写乱、把已经废弃的接口当主力调用、甚至在你明确说过“不要动这个文件”之后依然自信地改出 bug。这其实不是它故意也不是能力不行这是架构层面的限制——上下文就是个短时记忆撑不住多文件、多轮次、跨会话的复杂项目。我的解决方案说穿了很简单既然它记不住那就让它的记忆落到外置的、持久化的、每次开始都能主动加载的文件里。Markdown 是天然的选择结构清晰、LLM 解析友好、人类也能直接阅读维护。我用三个文件分别覆盖“项目状态”“领域知识”“操作规则”三个维度相当于给它装了一个随身携带的笔记本每次开工先翻一遍。这篇文章我会从三个层面展开一是为什么 Claude Code 会“失忆”、为什么 Markdown 是适合做外置记忆的载体二是三个 Markdown 文件分别怎么写、写什么、边界在哪三是具体落地时怎么配合项目流程和常见坑位。每个部分我都会给可直接抄作业的模板和说明你在自己的项目里基本可以照搬。1. 为什么 Claude Code 会“失忆”本质是上下文管理出了问题1.1 上下文窗口是 AI 编码助手的先天限制很多人第一次用 Claude Code 的时候会高估它的记忆力它能理解整个仓库能一口气改十几处代码看起来“什么都记得”。但用过一个星期就会发现问题——它记的是当前上下文中可见的信息而不是整个项目的历史全貌。你在对话中告诉过它的约定只要不处在前面的窗口内就会逐渐被丢弃或弱化。这个“窗口”是什么概念你可以把它理解成一张只够铺开几张纸的桌面代码文件、对话记录、中间结果都在有限的桌面上争抢位置。窗口越大能放的越多但总有一个上限。当新内容不断进入旧内容就会被从桌面上清理掉。Claude Code 根据 token 数来管理这个窗口超出的内容会被截断、压缩或遗忘。它不会主动去翻磁盘上那些文件除非你告诉它去加载或者它在有限的上下文里本能地选择了忽略。所以“失忆”并不是说它“忘了你说过的话”而是它的记忆机制天然只保存“当前看得见的东西”。你上一个会话里定下的规则下一个会话默认继承不了。Claude Code 确实有一些全局配置和 CLAUDE.md 的机制能让我自定义指令和规则但如果项目复杂、规则一多单一文件很容易变成大杂烩什么都写最后变成什么都没写。这个限制是所有会话式 AI 编码工具的共性不是某一个产品的问题。1.2 为什么说 Markdown 是最适合做“外置大脑”的载体明白了上下文有限思路就清晰了我们要做的不是让 AI“记住所有东西”而是让它每次工作时能快速、准确地把最关键的信息加载回上下文里。这里选 Markdown 有三个原因第一Markdown 是人类和 LLM 都易于理解的格式。你不需要额外的工具就能随手打开修改AI 也能用很低的 token 成本提取标题、列表、表格中的语义。相比 JSON、YAML、数据库Markdown 在“人机共同维护”这个场景下是平衡点最好的一个普通的项目备注可以无缝变成 AI 的提示词源。第二Markdown 的长度可控、结构清晰。你可以用二三级标题把不同主题切分开AI 按需读取不用一次性吞大量内容。配合简洁的列表和表格信息密度高噪音低对上下文来说很友好。我见过有人用 PDF 或 DOCX 做知识库但那些格式的解析成本高、容易引入格式噪音远不如 Markdown 干净。第三Markdown 天然适合放在版本控制里。用 Git 管理三个记忆文件每次修改都有历史记录AI 就算将来出错你也可以 diff 出它干了什么、改了什么。这一点非常重要因为“外置大脑”本身也需要被审计、被回滚不能只指望它不出错。1.3 不同记忆类型要分开放不能塞进同一个文件我在早期踩过一个很典型的坑把所有规则写进一个 CLAUDE.md结果越写越长。业务规则、编码规范、当前进度、待办清单混在一起每次 Claude Code 加载的时候要么截断要么被不重要的内容稀释重要优先级。后来我复盘发现一个文件里塞三种记忆本质上是混淆了“状态记忆”和“知识记忆”——状态是每时每刻变化的知识是长期稳定的把它们放一起任何一方的更新都会污染另一方。所以我的做法是把记忆拆成三个不同职责的文件一个记录“现在在哪里”项目状态一个记录“项目的地图与规则”领域知识与编码规范一个记录“干活时的红线”操作边界与禁止事项。每次开工Claude Code 只会按需读取对应文件而不是一口吃掉所有内容。这个拆分看似简单但对实际使用效果提升非常明显后面我会逐个文件详细说明。2. 给 Claude Code 装“外置大脑”三个核心文件如何规划2.1 文件一项目状态文件PROJECT_STATE.md解决“它不知道现在进行到哪”这个文件的核心使命是让 AI 在每次会话开始时快速了解项目的“当前坐标”。它不需要写历史长篇而是记录四个板块当前里程碑及完成度最近一次修改的模块和文件已知问题 / 阻塞项下一步计划按优先级排序模板我放在下面基本可以直接参考# 项目状态 ## 当前里程碑 - v0.3认证模块重构完成度 90%剩余单元测试补充 ## 最近变更 - 2024-XX-XX重构 login 流程新增 /api/v2/auth/session - 2024-XX-XX修复首页加载 WhiteScreen 问题根因是 provider 顺序错误 ## 已知问题 / 阻塞 - 刷新 token 偶发 401疑似 clock skew 问题待验证 ## 下一步 1. 完成 auth 单测覆盖优先级高 2. 审计 logger 输出防止敏感信息泄漏 3. 整理 API 文档供前端联调写这个文件的时候务必克制。只保留 AI 完成任务真正需要的“事务性信息”就够了不要把什么都往里面倒。项目状态是高频变化的每次会话结束后顺手更新它是这套机制能不能有效的关键。你不更新AI 再强也猜不到你昨天在改什么。2.2 文件二领域知识文件KNOWLEDGE.md解决“它不懂业务规则和通用规范”项目状态解决“进度”领域知识解决“共识”。这个文件面向的是项目中那些长期有效的背景知识和约定比如技术栈和目录结构说明核心业务概念和领域术语已经确定的架构决策ADR关键接口和数据结构示例编码规范和命名约定这里有一个核心原则不要写教科书只写这个项目特有的、AI 不看就会犯错的信息。比如“本项目用 Vue3 TypeScript”是一种约定而“本项目所有组件的 props 必须用 defineProps 声明并导出类型”是更具体、更能防止它写错的东西。后者才值得写进 KNOWLEDGE.md。我通常会这样组织# 领域知识 ## 技术栈 - 前端Vue 3 Pinia Vite组件库使用 Arco Design Vue - 后端Node.js 18 Express PostgreSQL ## 架构约定 - API 统一走 /api/v1 前缀 - 所有写操作必须通过 service 层禁止直接在路由中操作数据库 ## 核心概念 - 订单状态机CREATED - PAID - SHIPPED - COMPLETEDCANCELLED 仅允许从 CREATED 转移 ## 编码规范 - 组件文件名使用 PascalCase - 所有 API 错误返回格式{ code, message, details? } ## 已确定的技术决策 - 2024-XX-XX选用 PostgreSQL 而非 MySQL原因是 JSONB 查询需求较多领域知识文件更新频率低但价值密度高。你会发现有了它之后Claude Code 在几个容易“自由发挥”的点上明显收敛比如接口风格、目录位置、命名习惯。2.3 文件三操作规则文件CLAUDE.md 或 RULES.md解决“它乱动不该动的地方”第三个文件专门用来写优先级最高、绝不能违背的硬约束。在我的架构里这个文件会让 Claude Code 在会话开始时主动读取并当作“最高指令”遵守。它跟 KNOWLEDGE.md 的区别是知识是“应该知道”规则是“必须遵守”。这里面的内容包括但不限于禁止事项不能动哪些文件、不能依赖哪个包必须遵守的流程比如每次提交前先跑 lint 和测试敏感操作警告比如不能直接改数据库 schema命令缩写和工具调用约定为了让 AI 认真对待我通常会把规则写得非常明确避免模糊表述。比如不要写“尽量别修改配置文件”而要写“禁止修改 .env 文件所有环境变量变化需先与项目负责人确认”。# 操作规则最高优先级 ## 绝对禁止 - 禁止修改 .env / .env.* 文件如有需要请联系仓库管理员 - 禁止在未运行 npm run lint 的情况下提交代码 - 禁止删除 migration 目录下任何历史文件 ## 强制流程 - 修改数据模型前先给出 migration 草案 - 涉及第三方支付接口时必须先在沙箱环境验证 ## 命令约定 - 开发服务器npm run dev - 测试npm run test:unit - 构建npm run build ## 重要提醒 - 项目使用 pnpm不使用 npm/yarn 安装依赖 - package.json scripts 中的自定义命令禁止自行覆盖在实际项目中CLAUDE.md 是 Claude Code 的原生配置文件通常位于项目根目录它天然会被自动读取。所以我的建议是把第三个文件做成 CLAUDE.md 的名字或想办法让 Claude Code 在会话开始时自动加载它这样规则优先级最高、最不容易被遗漏。3. 实操过程建立三个文件并让 Claude Code 每次开工先读取3.1 第一步初始化文件目录与模板不要把这几个文件散落在项目各处。我推荐在仓库根目录建立docs/或.ai/目录统一管理 AI 相关记忆文件让它们与代码结构分离。以.ai/为例your-project/ ├── .ai/ │ ├── PROJECT_STATE.md │ ├── KNOWLEDGE.md │ └── CLAUDE.md ├── src/ ├── tests/ └── package.json目录的命名没有绝对标准但建议一进仓库就能看到不要让 AI 去猜这些文件在哪。初始化就是创建三个空模板先把结构搭好。3.2 第二步根据项目现状填充三个文件接下来要做的是一次性“知识迁移”。如果你有一个已经存在很久的项目不可能一下子就写全所有内容我的建议是分优先级高优先级CLAUDE.md 的禁止规则和命令约定必须在第一天就写好因为任何一次 AI 的乱操作都可能造成不可逆后果PROJECT_STATE.md 的当前状态和下一步任务也需要尽快填上否则 AI 不知道从哪里开始。中优先级KNOWLEDGE.md 的技术栈、目录结构、核心概念。这部分可以边做边补不用强求一次写完美但凡是 AI 容易搞错的架构决策建议尽早写进去。低优先级历史故意的技术决策、复杂业务背景、模块间的依赖关系。这些可能你平时也不太讲给 AI但一旦遇到相关任务就是关键信息。建议随用随记不要等到需要时再临时补。3.3 第三步在会话开始时显式加载记忆虽然 CLAUDE.md 有自动加载机制但另外两个文件 Claude Code 不会默认读取。所以我每次开会话第一句就会让它加载记忆类似这样请先读取 .ai/PROJECT_STATE.md 和 .ai/KNOWLEDGE.md然后基于项目状态继续工作。如果你觉得每次手输麻烦也可以在 CLAUDE.md 里嵌一条启动指令或者用 Claude Code 支持的 hooks / 自定义 commands 简化操作。具体支持方式可能随版本变化但核心原则不变把“读记忆”变成开工前的第一动作而不是等任务开始之后才想起来补。我在实践中还发现一个技巧就是让 AI 在回复开头先用“状态确认”的方式复述它读到的核心信息比如“当前里程碑是…已知阻塞是…”这样你可以快速判断它是否真的读进去了而不是假装读了一段。不过不要让它长篇复述浪费 token两三行就够。3.4 第四步每次会话结束同步更新 PROJECT_STATE更新状态文件是整套机制里最容易偷懒、也最影响效果的一步。我自己会把它当成“下班前的五件事”之一要么手动改要么在会话接近尾声时让 Claude Code 自己先总结变更我再人工确认。一个可落地的方法是在会话结束前给 AI 下一条指令请根据本次对话整理变更内容以 PR 描述的形式更新 .ai/PROJECT_STATE.md包括当前里程碑完成度、下一步计划、已知问题。不要改代码。这里有一个注意点千万不要让 AI 在更新状态文件的同时去改业务代码因为状态文件的准确性直接影响下一次开工而自动更新的内容必须经过你的确认不然它可能把工作成果写错。3.5 第五步把知识沉淀变成例行公事KNOWLEDGE.md 和 CLAUDE.md 不应该是一成不变的。每当项目里出现一个“新约定”“踩过一次的坑”“一个容易忘记的架构事实”就把它记进合适的文件。记录的时机越及时成本越低。我自己有一个很简单的习惯当 Claude Code 在某个任务里做对了某件事且它提到过某个规则或约束是我不曾显式告诉它的我会检查它是否真的理解了项目上下文并考虑把这条规则固化到 KNOWLEDGE.md。当它犯了一个违背约束的错我也会立刻补一条规则到 CLAUDE.md防止下次再犯。时间久了这三个文件就成了项目和 AI 之间的“共同记忆库”越来越准。4. 常见问题与排查技巧实录4.1 问题一配置了 CLAUDE.md但 AI 根本不遵守里面的规则这是最常见也最让人崩溃的问题之一。很多人的第一反应是“Claude Code 没用”但检查之后发现其实是 CLAUDE.md 写入的信息跟对话里的冲突或者规则写得不够具体被 AI 在生成长回复时忽略了。排查思路首先确认 CLAUDE.md 是否在项目根目录且命名正确其次看看文件里有没有过长的段落——超过 1000 行的话AI 有可能抓取不到重点最后再确认规则是不是足够 “可执行”。如果某条规则你写成“代码质量要高”AI 依然会自由发挥因为它没有可判定的标准。但如果你写“所有组件必须用 TypeScript 写并且 props 必须显式定义类型”它就很难无视。4.2 问题二PROJECT_STATE 更新不及时下一步指令全是错的这基本属于“人没做好不能怪 AI”。状态文件一旦过期AI 拿着过时的信息开工自然会把精力浪费在已经完成的事情上或者误以为某块逻辑还是旧结构。解决办法是“定义更新触发点”每完成一个小里程碑或每次提交 PR 前必须更新状态文件。可以把这一步做成 Git 提交模板的一部分比如在git commit模板里加一个 “是否更新 .ai/PROJECT_STATE.md” 的勾选也可以用 Claude Code 的 hooks 自动在提交前提醒。我在实践中用的是最笨也最有效的方法在每日站会时让 AI 帮我把当天代码改动汇总成状态更新草稿我审阅后提交。这样既省事又不容易漏。4.3 问题三三个文件内容越写越重叠不知道该放哪个拆分多了也容易踩坑状态文件里写了领域知识知识文件里混了操作规则CLAUDE.md 里又出现进度信息。结果 AI 读到的是三个“半对半错”的信息源反而比没有文件更混乱。我给这套机制定了一条判断标准一条信息如果“会随会话变化”放 PROJECT_STATE.md一条信息如果“长期稳定且描述项目背景”放 KNOWLEDGE.md一条信息如果“是禁止动作或强制流程”放 CLAUDE.md如果拿不准就写进 KNOWLEDGE.md因为它的语义最宽。但你也可以定期做一次“文件审阅”例如每两周花 15 分钟看看三个文件有没有过时或重复的内容删掉无用的、合并相似的保持简洁。4.4 问题四加上这些文件之后响应变慢了 / token 消耗变多了这是很多人对“记忆文件”的另一个顾虑。实际上Markdown 文件的 token 开销很小几百行的知识库也就相当于几千 token相比动辄上万行代码的上下文占比不高。但如果你每次会话都强制 AI 一次性读取全部三个文件确实会浪费一部分窗口。优化方法很简单不是所有任务都需要所有文件。改 UI 的时候不需要读数据库 migration 规则调 API 的时候不需要知道组件命名规范。我的做法是让 AI 根据任务类型按需加载比如在指令里写明“只需要读取 KNOWLEDGE.md 中的技术栈和接口规范”。4.5 问题五多分支并行开发时状态文件会冲突如果你同时开了 feature-A 和 feature-B 两个分支用同一个 PROJECT_STATE.md就会出现相互覆盖的问题。这个痛点是真实存在的因为状态文件本质上反映的是某个工作线的前进情况不等同于仓库主干。我尝试过两种解法第一种把状态文件按分支或工作线拆开比如PROJECT_STATE.feature-A.md在不同会话里指定不同文件第二种在状态文件里加一个“当前分支/工作线”字段每次切换上下文时明确告知 AI 当前服务于哪个分支。如果你是主力用 trunk-based 开发或者单分支工作流这个问题没那么严重可以直接用第二种。4.6 问题六Claude Code 把状态文件改坏了怎么办“外置大脑被 AI 自己改坏了”是很多人不放心把状态文件交给 AI 维护的原因之一。这里我的经验是不要阻止 AI 修改状态文件但一定要用 Git 守住底线。把.ai/目录纳入版本控制每次 AI 更新状态文件后你可以通过git diff .ai/PROJECT_STATE.md快速看到改动如果它写坏或者胡编内容直接 checkout 还原。我甚至会在项目里加一条规则AI 每次修改状态文件后必须输出一句“已更新状态文件”方便我在终端看到它的动作痕迹。用 Git 兜底比任何权限控制都省心。5. 边界与演进外置大脑的局限以及后续还能怎么扩展5.1 别指望外置大脑解决所有问题三个 Markdown 文件这套方案核心价值是把项目的“变数”和“常量”分隔开降低 AI 因上下文丢失带来的风险和返工成本。但它不是银弹解决不了所有 AI 编码问题。比如你在会话里临时交代一个很细的微调要求如果这个要求不会在之后的会话中反复出现那确实没有必要写进任何文件强行写进去反而增加噪音。外置大脑应该记那些“稳定且高价值”的信息而不是事无巨细的流水账。另外只有你主动更新和维护这套文件它的价值才会持续增长。如果连续几周不更新 PROJECT_STATE那么这套机制基本等于失效。AI 工具本身不会替你维护记忆它只是提供了一个可以被“喂记忆”的接口。5.2 后续可以扩展成团队级 AI 协作规范如果你一个人用这套方法跑顺了下一步完全可以把它推广到团队。我这里说的团队级不是简单地把三个文件放到共享仓库里而是让每个团队成员都领会这套分类思路状态、知识、规则分开维护。团队可以在docs/ai/目录下增加一个 INDEX.md 说明让所有人都知道这些文件是干嘛用的、什么时候应该更新。更进一步你可以在 CI 阶段加一个检查比如提交时校验.ai/CLAUDE.md是否包含某些必要的禁止项或者在代码评审模板里增加一项如果这次改动影响了业务约定记得同步更新.ai/KNOWLEDGE.md。当 AI 编码助手从个人玩具升级成团队基础设施时这套“外置记忆”的约束机制会变得越来越重要。5.3 把外置大脑和自动化工作流结合另一个可以探索的方向是把 Markdown 记忆文件接入你的自动化工作流。比如你可以在每天早晨用脚本汇总 Git 日志和 issue 进展自动生成一份当天的 PROJECT_STATE 草稿供你确认后覆盖旧文件或者在上线前用脚本检查 KNOWLEDGE.md 中记录的前端命名规范是否真的被代码库中的所有新文件遵守。我自己目前在实验的方向是把外置记忆文件当作 prompt template 的来源——在 Claude Code 里写一个 command让它根据当前分支、当前 diff 和状态文件生成一份“本次改动目标 潜在风险 应守规则”的启动提示词。这样每次开工AI 不仅能读到记忆还能收到一份针对当前任务的上下文摘要效率比单纯读文件更高。这个方向值得关注因为它的本质是把“外置大脑”从被动读取变成主动工作流的一部分。从我目前的实操体会来说给 Claude Code 配三个 Markdown 文件看起来只是最简单的“写文档”动作但它带来的转变是结构性的你不再依赖 AI 的临时记忆力而是把“约定”和“事实”沉淀成项目的一部分。这让 AI 写代码时不再像无头苍蝇一样乱撞也让团队里的每个人都有一条可以参考的、与 AI 协作的共同路径。工具总在快速迭代但“把重要的东西写到不会丢的地方”这个思路我觉得无论用哪款工具都值得保留。
