1. 为什么长期项目里 Claude Code 总是“重新入职”维护同一个项目超过三个月的人大概都经历过这种循环今天在 session 里跟 Claude Code 交代“测试必须用pnpm test:unit -- --runInBand因为并行跑会抢同一个 mock 端口”明天开新会话它又默认跑npm test然后你重新解释一遍。问题不在于模型能力而在于每次会话开始时它对这个 repo 的认知是空的。Claude Code 的定位不是聊天窗口里的代码补全它会读代码库、改文件、跑命令接入终端和 IDE。正因为它会进入真实工程目录参与构建、测试、调试、提交它需要的不是一次性 prompt而是一套能随项目推进不断积累的上下文系统。这套系统里有两个角色CLAUDE.md是你手写的长期说明书Auto memory 是 Claude Code 自己在工作中记下的项目笔记。前者管“必须遵守的规则”后者管“这个 repo 里踩出来的经验”。这篇面向长期维护同一项目的开发者给出CLAUDE.md骨架、Auto memory 的触发与关闭配置、一次上下文注入后的验证动作以及常见报错排查。目标很直接让项目经验可复用、可传承而不是每次会话从零开始。如果你还没配好可用的模型接入可以先在 TaoToken 模型对话 里把对话链路跑通再回到本地做记忆配置。2. CLAUDE.md 与 Auto memory 的分工边界先把两者的边界讲清楚否则后面配置容易混。官方文档把二者放在同一套记忆体系里CLAUDE.md是你写的 instructionsAuto memory 是 Claude 根据修正和偏好写下的 notes。二者都会在每次 conversation 开始时进入上下文但它们都只是 context不是强制配置。这意味着一个关键结论不能把 Auto memory 当安全边界。如果某类操作无论 Claude 怎么判断都不能执行比如禁止提交密钥文件、禁止对生产库做破坏性操作那应该用 PreToolUse hook、permissions 或 managed settings而不是只靠记忆文件。记忆是软知识hook 才是硬拦截。Auto memory 默认开启要求 Claude Code v2.1.59 或更高版本。它记录的是项目局部经验比如构建命令、调试发现、架构说明、代码风格偏好、工作流习惯。它不是每次 session 都机械保存而是判断某条信息未来是否有复用价值再决定写入。存储位置通常在~/.claude/projects/project/memory/入口文件是MEMORY.md详细内容会被拆到 topic files比如debugging.md、api-conventions.md。这里有个容易忽略的细节每次 conversation 启动时只会加载MEMORY.md的前 200 行或前 25KB两者取更早达到的限制。所以MEMORY.md应该当索引用不是大杂烩。真正长的调试记录放 topic fileClaude 需要时再用文件工具读取。这是典型的上下文工程思路启动时加载核心摘要长尾资料按需读取。维度CLAUDE.mdAuto memory谁来写你/团队手写Claude 自动记录内容性质必须遵守的规则项目局部经验是否强制否是 context否是 context典型内容架构边界、测试命令、命名约定报错根因、模块特殊约定、workflow 习惯审计方式直接读文件/memory浏览、编辑、删除3. 可复制的 CLAUDE.md 骨架与 Auto memory 配置3.1 CLAUDE.md 骨架在项目根目录建CLAUDE.md结构建议按“命令—架构—约定—禁区”四段写。下面这份骨架可以直接改# 项目说明 ## 常用命令 - 安装依赖pnpm install --frozen-lockfile - 单元测试pnpm test:unit -- --runInBand - 端到端测试pnpm test:e2e需先启动 mock server - 构建pnpm build - 类型检查pnpm typecheck ## 架构分层 - src/features/* 按业务域拆分禁止跨域直接 import - src/api/client.ts 是唯一请求出口禁止在组件里裸写 fetch - 状态管理统一走 src/store禁止新增全局单例 ## 代码约定 - 组件文件用 PascalCase工具函数用 camelCase - 错误响应统一 { code, message, detail } 结构 - 提交前必须跑 pnpm typecheck 和 pnpm test:unit ## 禁区 - 禁止修改 .env.production - 禁止在 src/legacy 下新增文件只允许修 bug - 禁止执行 rm -rf 任何目录这份文件的价值在于把“口头交代”变成“每次会话自动加载”。注意最后一段禁区只是提示真正的强制拦截要放到 hook 或 permissions 里。3.2 Auto memory 开关配置默认开启需要关闭时有三种方式。在 session 里打开/memory通过界面切换在项目 settings 里设置autoMemoryEnabled为false或者用环境变量export CLAUDE_CODE_DISABLE_AUTO_MEMORY1检查版本是否满足要求claude --version如果低于 v2.1.59Auto memory 不会生效先升级。3.3 主动触发记忆写入Auto memory 会自动判断但关键经验最好当场指出。在会话里直接说记住这个 repo 的 CI 使用 Node 22依赖安装必须用 npm ci不要用 npm install。或者记住API 测试需要本地 Redis 实例端口 6379测试前先跑 docker compose up -d redis。这类显式提醒会显著提高记忆质量。把它当成一个会做笔记的同事平时它自己总结关键经验你当场点出来。4. 验证上下文注入是否生效配置完不能只看文件存在要验证它真的进了上下文。推荐三步验证。第一步查看当前 session 加载了哪些记忆文件。在 Claude Code 里运行/memory界面会列出当前加载的CLAUDE.md、CLAUDE.local.md、rules files以及 Auto memory 目录入口。确认你的CLAUDE.md在列表里。第二步直接检查 memory 目录内容ls -la ~/.claude/projects/project/memory/ cat ~/.claude/projects/project/memory/MEMORY.mdproject是 Claude Code 为项目生成的标识目录。你应该能看到MEMORY.md以及可能的 topic files。第三步做一次行为验证。开一个新会话不提任何背景直接问这个项目的单元测试命令是什么如果CLAUDE.md和 Auto memory 都正确注入它应该回答pnpm test:unit -- --runInBand而不是泛泛地说“通常用 npm test”。这一步是判断记忆是否真正生效的关键文件存在不等于上下文加载成功。如果你在验证过程中需要对比不同模型对同一段上下文的响应可以在 TaoToken 模型对话 里做交叉测试确认是记忆问题还是模型理解问题。5. 本篇常见错排查报错一Auto memory 完全不写入。先跑claude --version确认版本不低于 v2.1.59。再检查是否设置了CLAUDE_CODE_DISABLE_AUTO_MEMORY1或者项目 settings 里autoMemoryEnabled被设为false。两者任一命中都会静默关闭。报错二MEMORY.md越来越长但 Claude 好像没读到关键内容。大概率是超过了 200 行或 25KB 的加载上限。把详细调试记录挪到 topic fileMEMORY.md只留索引和核心摘要。检查行数wc -l ~/.claude/projects/project/memory/MEMORY.md报错三记忆里有过期命令Claude 一直沿用。Auto memory 是普通 markdown直接编辑或删除即可。比如旧记忆写着“临时用 yarn install 绕过依赖问题”但项目已统一回pnpm install --frozen-lockfile就手动清掉这条。建议每隔一段时间审计一次MEMORY.md。报错四把安全规则写进记忆结果没拦住危险操作。这是概念混淆。记忆是 context不是强制配置。禁止类规则必须落到 PreToolUse hook、permissions 或 managed settings。记忆只适合软知识。报错五/memory里看不到 Auto memory 目录。确认当前工作目录就是项目根目录Claude Code 按项目维度隔离记忆。如果换了目录启动会读到另一个项目的记忆。6. 把记忆变成可持续工程资产比较理想的分工是这样CLAUDE.md写必须遵守的项目规则Auto memory 记录 Claude 在实际工作中学到的项目经验hooks 和 managed settings 负责强制执行。三者各司其职Claude Code 才不会变成一个靠聊天记录维持状态的脆弱系统。高质量记忆满足三个条件稳定、可复用、能减少未来推理成本。构建命令稳定适合记临时分支上的实验参数不稳定不适合长期记复杂 bug 的根因和修复路径下次还可能遇到适合记一次性需求的页面文案不适合记。目标不是记得越多越好而是让未来 session 更少试错。如果你打算把 Claude Code 长期用在同一个项目上建议顺手把接入配置也固定下来。API Key 在 TaoToken API Keys 管理接入细节看 TaoToken 接入文档。长期编码和 Agent 场景可以走 Coding Plan把模型调用和记忆体系一起沉淀成团队可复用的工程资产。