1. 为什么你的 Claude Code 总在重复踩同一个坑如果你已经在项目里用了一段时间 Claude Code大概率遇到过这种场景昨天刚跟它说过这个仓库用 pnpm 不用 npm今天新开一个 session它又顺手敲了npm install上周调试时明确告诉它 API 集成测试要先起本地 Redis这周它跑测试失败第一反应还是去翻业务代码找 bug。问题不在于模型变笨了而在于这些信息从来没有真正沉淀成项目资产它们散落在一次次聊天记录里session 一关就没了。Claude Code 的长期记忆机制其实是一套分层系统核心入口就是/memory命令。它把CLAUDE.md、CLAUDE.local.md、.claude/rules/目录下的规则文件以及 Claude 自己写的 auto memory 放在同一个可审计的界面里。你可以把它理解成项目的上下文控制台哪些规则被加载了、auto memory 开了没有、Claude 自己记了些什么都能在这里看到。这套机制适合谁适合所有把 Claude Code 当日常开发工具、而不是偶尔玩一下的人。尤其是多人协作的仓库、前后端混合的 monorepo、有严格命名规范的企业项目。如果你只是拿它写个一次性脚本那确实用不上但只要项目会持续迭代记忆管理就是绕不开的一环。我试过在一个 Node.js 后端仓库里放任不管结果两周后 Claude 的 auto memory 里堆了一堆互相矛盾的调试笔记新 session 加载后反而更容易出错。后来把规则分层整理清楚稳定性提升非常明显。下面就把这套从会话到落盘的完整路径拆开讲。需要先明确一个边界CLAUDE.md和 auto memory 都是上下文不是强制执行层。它们影响 Claude 的判断但不能保证某个动作一定被拦截。真要强制阻止某条命令或某个路径访问得用settings.json里的 permissions 或 hooks。把/memory当工程协作入口别当权限系统这个定位很关键。2. /memory 命令与 CLAUDE.md 分层模板先搞清楚记忆从哪来在动手配置之前得先理解 Claude Code 记忆系统的两类来源。一类是我们主动写的包括项目级CLAUDE.md、本地私有的CLAUDE.local.md以及.claude/rules/下的规则文件另一类是 Claude 在工作中自动沉淀的 auto memory。两者都会在每次会话开始时进入上下文但职责完全不同。/memory的第一层价值是审计不是新增。很多人以为对 Claude 说一句以后都用 pnpm它就永久记住了实际上这句话很可能进了 auto memory而不是写进CLAUDE.md。打开/memory你能看到当前 session 到底加载了哪些文件。很多Claude 不听话的问题本质是规则没被加载、位置放错或者多个文件互相冲突。2.1 CLAUDE.md 的分层结构项目级CLAUDE.md可以放在./CLAUDE.md或./.claude/CLAUDE.md。它适合放每个 session 都该遵循的项目事实构建命令、测试命令、编码标准、架构决策、命名约定。下面是一个可以直接复制的分层模板我按稳定事实在前、易变信息在后的顺序组织# 项目上下文 ## 技术栈与包管理 - 包管理器统一使用 pnpm禁止使用 npm 或 yarn - Node 版本要求 20使用 .nvmrc 锁定 - 安装依赖pnpm install - 新增依赖pnpm add pkg禁止直接改 package.json ## 常用命令 - 开发pnpm dev - 构建pnpm build - 单元测试pnpm test:unit - 集成测试pnpm test:integration需先启动本地 Redis - 类型检查pnpm typecheck ## 目录约定 - src/api/**HTTP 接口层只做参数校验和转发 - src/service/**业务逻辑禁止直接操作数据库连接 - src/repo/**数据访问层SQL 只允许出现在这里 - db/migrations/**数据库迁移命名格式 YYYYMMDD_description.sql ## 编码规范 - 所有导出函数必须有显式返回类型 - 错误统一用 AppError 包装禁止裸 throw new Error - 日志使用 logger 实例禁止 console.log ## 测试前置条件 - 集成测试依赖本地 Redis默认端口 6379 - 启动命令docker compose up -d redis - 测试数据通过 fixtures 目录加载禁止硬编码这个模板的关键是具体。官方排障建议里提到当 Claude 没遵循CLAUDE.md时要检查指令是否具体、是否存在冲突。用 pnpm不如包管理器统一使用 pnpm禁止使用 npm 或 yarn来得明确。2.2 CLAUDE.local.md 放什么CLAUDE.local.md是本地私有偏好不进 Git。适合放你自己的沙箱地址、测试账号、临时调试习惯。比如# 本地私有配置 ## 我的开发环境 - 本地 API 网关http://localhost:8080 - 测试账号devexample.com / 从 1Password 取 - 我习惯先跑 pnpm typecheck 再跑测试 ## 临时备注 - 正在重构 order 模块相关代码先别动团队共享的规则放CLAUDE.md个人偏好放CLAUDE.local.md这个分层和 SAP 项目里 customizing 与本地开发偏好的区分是一个道理。2.3 rules 目录把大文件拆细项目一大根目录CLAUDE.md会膨胀。Claude Code 支持用.claude/rules/目录把规则拆成多个 Markdown 文件每个文件覆盖一个主题还能通过路径范围控制加载时机。目录结构可以这样组织.claude/ ├── CLAUDE.md # 主入口放全局约定 ├── rules/ │ ├── api.md # API 层规范 │ ├── database.md # 数据库与迁移规范 │ ├── frontend.md # 前端组件规范 │ └── testing.md # 测试规范 └── settings.json # permissions、hooks、env每个规则文件可以声明作用路径让规则只在处理匹配文件时加载减少上下文噪音。比如database.md只对db/**和src/repo/**生效处理一个纯前端改动时就不会被加载进来。3. 可复制配置auto memory 开关与 settings.json 片段搞清楚分层之后接下来是配置。auto memory 默认开启但它的行为可以通过项目 settings 精确控制。这一节给出可以直接复制的配置片段路径和字段名都按官方文档来。3.1 auto memory 的存储位置auto memory 每个项目一个目录路径形态是~/.claude/projects/project/memory/。project来自 Git repository所以同一个仓库的所有 worktree 和子目录共享一个 auto memory 目录不在 Git repo 内时用 project root。目录里有一个MEMORY.md入口文件也可能有debugging.md、api-conventions.md等主题文件。这里有个关键限制每次会话开始时只加载MEMORY.md的前 200 行或前 25KB取较小者。超出的内容不会在启动时加载。所以MEMORY.md要保持简洁详细笔记移到主题文件里Claude 需要时再按需读取。3.2 settings.json 配置片段在项目.claude/settings.json里可以控制 auto memory 的开关和目录{ autoMemoryEnabled: true, autoMemoryDirectory: ~/.claude/projects/my-repo/memory, permissions: { allow: [ Bash(pnpm install), Bash(pnpm test:unit), Bash(docker compose up -d redis) ], deny: [ Bash(npm install), Bash(rm -rf node_modules) ] }, env: { NODE_ENV: development } }几个要点。autoMemoryEnabled设为false时Claude 既不从 auto memory 目录读取也不写入。autoMemoryDirectory要求绝对路径或以~/开头配置自定义目录时需要通过 workspace trust 对话框后才生效。permissions里的deny才是真正的强制拦截层CLAUDE.md里的禁止使用 npm只是上下文提示两者要配合使用。如果要在环境变量层面彻底禁用 auto memory可以设置export CLAUDE_CODE_DISABLE_AUTO_MEMORY13.3 三件套Base URL Key Model ID如果你通过 API 方式接入 Claude Code配置里需要写全三件套。以项目 settings 为例{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥, ANTHROPIC_MODEL: claude-sonnet-4-5 } }Base URL 指向https://taotoken.net/apiKey 在控制台的 API Keys 页面生成Model ID 按你实际使用的模型填写。这三项缺一不可只填 Base URL 不填 Key 会直接 401。生成 Key 的入口在 API Keys 页面接入细节可以对照接入文档。3.4 版本要求auto memory 需要 Claude Code v2.1.59 或更高版本。先检查claude --version低于这个版本的话/memory里看不到 auto memory 相关选项先升级再继续。4. 验证请求从一次会话到落盘的完整动作配置写完不算完得验证它真的生效。这一节演示一次完整的会话 → 落盘 → 复查动作让你确认记忆确实被正确加载和写入。4.1 检查当前加载了哪些记忆在项目根目录启动 Claude Code输入/memory你会看到一个列表包含当前 session 加载的CLAUDE.md、CLAUDE.local.md和 rules 文件以及 auto memory 的开关状态和打开文件夹的入口。选中任意文件可以直接在编辑器里打开。如果某个你期望的规则文件没出现在列表里说明它没被加载检查路径和文件名是否正确。4.2 触发一次 auto memory 写入在会话里对 Claude 说一句项目事实比如记住这个仓库的集成测试必须先启动本地 Redis端口 6379用 docker compose up -d redisClaude 会判断这条信息对未来会话是否有用然后写入 auto memory。注意它默认写进 auto memory而不是CLAUDE.md。如果你希望它进项目规则要明确说把集成测试依赖本地 Redis端口 6379这条规则写入 CLAUDE.md 的测试前置条件章节4.3 复查落盘结果写入后再次打开/memory进入 auto memory 文件夹查看MEMORY.md的内容。你应该能看到类似这样的条目## 测试相关 - 集成测试依赖本地 Redis默认端口 6379 - 启动命令docker compose up -d redis - 详见 testing.md如果这条信息已经稳定把它从 auto memory 迁移到.claude/rules/testing.md让团队共享。auto memory 是机器本地的不会跟随 Git 分发也不会在多台机器间同步所以团队级事实必须落到CLAUDE.md或 rules 里。4.4 验证规则是否真的影响行为新开一个 session让 Claude 跑集成测试帮我跑一下集成测试如果规则生效它应该先检查 Redis 是否启动而不是直接跑测试然后报连接错误。如果它还是直接跑回到/memory检查规则文件是否被加载、指令是否足够具体。4.5 用模型对话快速验证配置如果你想先确认 API 配置本身没问题可以到模型对话页面发一条测试消息确认 Base URL 和 Key 能正常返回。这一步和 Claude Code 的记忆机制无关但能帮你排除接入层的干扰。5. 常见报错排查401、local proxy failed 与规则不生效配置过程中最容易卡在几个具体报错上。这一节按真实错误信息对照排查每个都给可操作的检查步骤。5.1 401 Unauthorized最常见的原因是 Key 没填、填错或者 Base URL 和 Key 不匹配。检查顺序# 确认环境变量是否生效 echo $ANTHROPIC_API_KEY echo $ANTHROPIC_BASE_URL如果环境变量为空说明 settings.json 里的env没被读取检查文件路径是否是.claude/settings.json以及 JSON 格式是否合法。Key 要在 API Keys 页面重新生成确认注意不要有多余空格或换行。5.2 local proxy failed这个报错通常出现在网络层。检查 Base URL 是否写成了https://taotoken.net/api注意结尾不要多加斜杠。如果你在 settings.json 里同时配了ANTHROPIC_BASE_URL和环境变量两者冲突时以哪个为准要看加载顺序建议只保留一处配置。5.3 reading choices 相关报错这类报错一般出现在响应解析阶段常见原因是 Model ID 写错或模型名不被支持。确认ANTHROPIC_MODEL的值和你在控制台看到的模型 ID 完全一致大小写敏感。如果用的是自定义模型名先在模型对话里验证一次。5.4 OAuth 相关报错如果你之前用 OAuth 方式登录过环境变量和 OAuth 凭证可能冲突。清理旧的凭证缓存或者显式用 API Key 方式覆盖。检查~/.claude/下是否有残留的凭证文件。5.5 规则不生效这是最隐蔽的一类。排查步骤第一打开/memory确认规则文件在加载列表里。不在列表里就是路径问题。第二检查指令是否具体。用 pnpm太模糊包管理器统一使用 pnpm禁止使用 npm 或 yarn才明确。第三检查是否有冲突。两个文件里对同一件事给了相反指令Claude 会困惑。第四确认你期望的是上下文提示还是强制拦截。如果是强制拦截得写进settings.json的permissions.deny或 hooks光靠CLAUDE.md不够。5.6 auto memory 不写入先确认版本claude --version低于 v2.1.59 不支持。再确认autoMemoryEnabled不是false环境变量CLAUDE_CODE_DISABLE_AUTO_MEMORY没被设为1。最后auto memory 不是每个 session 都写入Claude 会判断信息是否有长期价值偶尔不写是正常的。6. 把 /memory 变成每周巡检入口真正把 Claude Code 用进日常之后/memory不该只在出问题时才打开。比较稳的做法是把它当成项目上下文的巡检入口固定节奏检查。项目刚启动时用/init生成初始CLAUDE.md再把构建命令、测试命令、目录结构和团队约定补齐。开发几天后Claude 可能在 auto memory 里存了一些调试经验这时打开/memory把稳定事实整理进CLAUDE.md或 rules把偶发错误删掉把过时内容改掉。项目进入维护期后/memory能帮你排查 Claude 为什么突然用了旧命令或者某个 rule 为什么没生效。这套动作看着普通但对 agentic coding 的稳定性影响很大。Claude Code 不是靠单轮 prompt 工作它会读文件、跑命令、改代码、不断进入新 session。长期质量来自上下文资产的管理。/memory把上下文从隐式状态变成显式文件让你能像维护代码一样维护 Claude 的项目认知。如果你还在用零散的聊天记录管理这些信息建议从今天开始把项目规则写进CLAUDE.md把个人偏好放进CLAUDE.local.md把大项目拆进.claude/rules/然后每周花十分钟打开/memory巡检一次。长期编码和 Agent 场景下这套习惯配合 Coding Plan 使用会更顺接入细节对照接入文档即可。