用 CLAUDE.md 固化团队开发上下文

Claude Code 每次开启对话，都会重新建立上下文。怎样让它持续记住项目用 pnpm、接口放在哪、提交前跑什么检查？原文给出的办法，是把这些约定写进 CLAUDE.md，再用目录层级、文件导入和按路径加载的规则控制它何时读取。

但「记住」不等于「强制执行」。这篇最值得读的部分，是分清团队指令、自动笔记和客户端配置各自负责什么。分错了，规则写得再多，也可能只是增加上下文负担。

文件会一起读入，子目录规则不会自动覆盖父目录

原文把指令位置列成五项：机器级托管文件、用户文件 ~/.claude/CLAUDE.md、项目根目录的 ./CLAUDE.md、另一种项目位置 ./.claude/CLAUDE.md，以及个人项目文件 ./CLAUDE.local.md。严格说，两个项目位置是同一作用域的两种放法，不是五级优先级。

团队应把构建命令、测试入口和架构约定放进版本控制；个人跨项目偏好放用户文件；某个项目的私人备注放 CLAUDE.local.md，并加入 .gitignore。

加载机制比文件名更重要。按原文描述，从 foo/bar/ 启动时，Claude Code 会向上查找，再按祖先目录到当前目录的顺序拼接内容。同一目录里的 CLAUDE.local.md 排在 CLAUDE.md 后面。当前目录下面的嵌套文件，则等到读取对应子目录文件时才按需加载。

CLAUDE.md 的层级决定内容怎样进入上下文，不提供可靠的冲突覆盖机制。

父目录要求 npm，子目录要求 pnpm，模型会同时看到两条指令。原文称冲突时可能任意选取一条，因此不能照搬 CSS 层叠的理解，把「后读到」当成确定的覆盖规则。

Monorepo 可以用 claudeMdExcludes 按绝对路径或 glob 排除无关指令，各配置层的排除数组会合并；托管政策文件不能被排除。但不可排除只保证内容进入上下文，不代表模型一定遵守，其中的安全要求仍需执行层保障。

规则要少而明确，拆文件也要分清是否省上下文

原文建议每个 CLAUDE.md 控制在 200 行以内。这是写作建议，不是加载上限：文件再长仍会完整读入。作者没有给出不同长度下的遵循率测试，所以「超过 200 行效果下降」应理解为经验判断。

真正有帮助的是把模糊要求改成可检查的动作。「正确格式化」不如「使用 2 空格缩进」，「测试修改」不如「提交前运行 npm test」。目录约定也应写明 src/api/handlers/，让模型可以直接定位。

拆文件有两种用途，不能混为一谈。

第一种是 @ 导入，用来复用内容。已有 AGENTS.md 的仓库，可以采用原文这段写法，同时补充 Claude Code 专属要求：

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

注意第一行：这里的 @AGENTS.md 会导入文件；放进反引号或代码围栏就只是文本。相对路径以包含导入语句的文件为基准，递归导入最多四跳。导入的内容仍然进入启动上下文，所以拆成多个文件并不自动节省 token。

原文还给了 ln -s AGENTS.md CLAUDE.md 的替代办法，适合无需添加专属内容的情况；Windows 创建符号链接需要相应权限或 Developer Mode。对于多个 git worktree，未提交的 CLAUDE.local.md 不会自行同步，可以通过 @~/.claude/my-project-instructions.md 引用同一份个人文件。

第二种是 .claude/rules/ 下带路径条件的规则。下面这段只在读取匹配的 TypeScript API 文件时进入上下文：

---
paths:
  - "src/api/**/*.ts"
---

## API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

关键是 paths，不是文件放进了 rules/。没有路径条件的规则仍会在启动时加载。原文还支持 src/**/*.{ts,tsx}、lib/**/*.ts 和 tests/**/*.test.ts 这类匹配方式，多条模式满足任意一条即可。

因此，前端样式约定和 Node API 规范可以按实际目录分开；只在某类任务里需要的流程，则更适合做成 skills。

自动记忆负责积累线索，settings 负责执行边界

CLAUDE.md 是人维护的指令，auto memory 是 Claude 自己记录的工作笔记。原文称后者要求 Claude Code v2.1.59 或更高版本，默认开启，可通过 /memory、autoMemoryEnabled，或设置 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 关闭。

自动笔记保存在 ~/.claude/projects/<project>/memory/。同一 git 仓库的子目录和 worktree 共享该目录，也可以用 autoMemoryDirectory 改位置。这与每个 worktree 自己的本地指令文件不同。

入口 MEMORY.md 只在启动时加载前 200 行或前 25KB，以先达到的限制为准；debugging.md 等主题文件按需读取。这个限制只针对 MEMORY.md，不能套在 CLAUDE.md 上。

让 Claude「记住以后用 pnpm」，按原文会写进自动记忆；希望团队获得同一条约定，则应明确要求加入 CLAUDE.md，再走版本控制。个人笔记和团队规范不能互相替代。

另一条边界在 .claude/settings.json。权限、hooks 和配置由客户端执行；CLAUDE.md 则作为语言指令供模型参考。原文示例用 permissions.allow 配置 Bash(npm test *)、Bash(npm run *)，用 permissions.deny 配置 Bash(rm -rf *)，并在 PostToolUse 的 Edit|Write 后触发 Prettier。

这些示例展示的是配置入口，不能据此认为一个拒绝模式就覆盖了全部危险操作。

.claude/ 还容纳 skills/、commands/、agents/、output-styles/ 和 workflows/。按原文，skills 与 commands 已使用同一机制，新流程优先用包含 SKILL.md 的 skills；子代理可用 tools: 限制工具，并通过 memory: project 在 .claude/agent-memory/ 保存独立记忆。

我的判断

这篇最有价值的判断，是把「提示模型遵守」和「客户端实际限制」分开。代码风格、目录说明适合写进指令；必须执行的格式化动作、工具权限边界，则应放到对应配置和检查流程里。

相比把所有内容塞进一个大文件，按路径加载更适合多目录、多团队仓库。但维护成本也会上升：父级指令、个人偏好、导入文件和自动笔记都可能过时。文件拆得越细，越需要知道某条要求究竟从哪里来。

我会对原文的确定性语气打折。它是一篇配置指南，没有提供作者团队的对照实验、任务成功率或上下文消耗数据。「更简洁就更可靠」有合理解释，但还不是文中实测结论。

另外，原文除 auto memory 外，没有明确各项功能对应的版本。/workflows、增强 /init 等具体行为，应按实际安装版本确认。托管配置的 claudeMd 示例还把换行写成了 n，不能原样当成两条独立指令复制。所给原文结尾也有截断，不宜替作者补齐结论。

能拿来做什么

• 先用 /init 生成草稿，再核对仓库里的真实脚本，把包管理器、开发命令、测试入口和关键目录写进团队 CLAUDE.md。原文称已有文件时会建议改进，但生成内容仍需人工检查。
• 前端与 Node 服务共仓时，把各自规范放进带 paths 的规则文件。共享约定集中维护，避免根目录与子目录分别写出冲突的测试或提交要求。
• 已有 AGENTS.md 就用导入复用；需要跨 worktree 共享个人偏好时引用主目录文件。别把本机自动记忆当作已经同步给同事的项目知识。
• 遇到模型反复违反约定，先用 /memory 检查实际加载了哪些文件，再处理遗漏、冲突或过期内容。对于必须落实的动作，检查 settings、hooks 和项目校验流程，不要只在提示里反复强调。