CLAUDE.md 配置指南：把团队规则写好，让每次会话直接开工

这样做的价值，是减少反复交代背景的时间。假设一个团队有四名开发者，每人每周开启五次会话，每次花三分钟重复说明工作要求，合计就是每周 60 分钟。共享指令文件能让这些要求集中在一处维护。评估效果时，要把省下的重复说明时间与维护文件的时间放在一起比较；节省多少时间并没有保证。

CLAUDE.md 是什么？

CLAUDE.md 是一个 Markdown 文件，存放 Claude Code 需要读取的项目、个人工作流程或组织级指令。可以把它理解成团队长期有效的工作说明，而自动记忆则是 Claude 在旁边维护的工作笔记。说明由你负责，笔记由 Claude 记录，两者都会成为它做决定时的上下文。参见 Anthropic 记忆指南。

区分两者的关键，是看哪些要求应该跨会话持续生效。必须执行的测试命令应写进工作说明；你反馈某次解释过于冗长，可以沉淀为它学到的偏好；当前任务则留在对话里。

这一划分依据官方目录指南。不必一开始就搭建庞大的 .claude 目录。先写好工作说明，等其他文件有了明确用途再添加。

CLAUDE.md 配置放在哪里？项目、用户与组织级作用域

小团队可以先在仓库根目录提交一份项目指令文件。个人偏好放进用户级文件，避免同事无意中也受这些偏好影响。

以上是文档列出的作用域和位置。受管理的组织级文件无法通过个人设置排除，但其中的文字仍然只起指导作用。

Claude 启动时会加载工作目录及其上级目录中的指令文件。处理子目录里的文件时，才会加载相应子目录中的指令。这些文件会合并使用，因此，新增一份作用域更具体的文件，并不会消除其他位置的冲突指令。用户级与项目级指引应保持一致。参见加载行为说明。

小型产品团队可以从这份 CLAUDE.md 模板开始

把能防止重复犯错的团队决定写下来。下面的示例假设项目使用 TypeScript 和 pnpm，且已经定义了 lint、typecheck 和 test 脚本。提交前，请把示例中的命令和路径替换成已在自己仓库里验证过的内容。

每节都用一行说明解释其用途。这些是建议采用的团队约定，并非 Anthropic 的默认规则。

# Product Team Instructions

## Product Intent
Why: Keep implementation tied to the customer problem.
- Read the task's acceptance criteria before changing code.
- Ask when missing product behavior would change the solution.

## Working Commands
Why: Make verification repeatable across teammates and sessions.
- Use pnpm for this repository; keep pnpm-lock.yaml consistent.
- Run pnpm lint and pnpm typecheck for application changes.
- Run pnpm test for behavior changes; report any checks not run.

## Change Boundaries
Why: Keep reviews small and dependencies deliberate.
- Follow nearby patterns before adding a new abstraction.
- Ask before adding a runtime dependency or changing public APIs.
- Keep unrelated cleanup out of the change.

## Data and Migrations
Why: Make data changes reviewable and reversible where possible.
- Add schema changes through the existing migration workflow.
- Describe compatibility and rollback concerns in the handoff.
- Use synthetic data in examples and tests.

## Quality
Why: Catch user-visible regressions before review.
- Add a focused regression test when fixing a behavior bug.
- Check loading, empty and error states when changing UI flows.
- State remaining uncertainty instead of calling unchecked work done.

## Project References
Why: Point to maintained decisions without copying the whole wiki.
- Read docs/product-decisions.md when product behavior is unclear.
- Read docs/release-checklist.md before preparing a release.

示例中的文档引用，只是要求在相关情境下查阅文档的普通指令。请创建这些文档，或替换为已有路径。这里特意没有使用自动导入。

保存文件后，从仓库中启动会话，运行 /context 检查启动时加载的记忆列表。用 /memory 打开并编辑指令文件。接着交给 Claude 一个真实的小任务，观察这些命令和边界是否有帮助。参见记忆检查方法。

只适用于特定文件的规则，移出主指令文件

如果多数任务用不到某条规则，就把它移到 .claude/rules/。例如，处理前端改动时，没有必要带上 API 处理代码的全部约定。

创建 .claude/rules/api.md，并添加 paths 头部。glob 是一种文件名匹配模式；src/api/**/*.ts 会匹配该目录及其子目录中的 TypeScript 文件。

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

# API Rules
- Validate external input before passing it to application logic.
- Use the existing error response format.
- Add a focused test when changing an endpoint's behavior.

匹配模式决定这条指令何时进入上下文。如果没有 paths，规则就会在启动时无条件加载。仅仅把长篇工作说明拆成多个规则文件，并不能节省上下文；还需要限制加载范围。参见按路径限定规则。

导入可以复用内容，但不会减少上下文占用

在 CLAUDE.md 中写入 @docs/team-conventions.md 这样的导入语句，会在启动时把对应文件读入上下文。相对路径以包含导入语句的文件为基准解析。真正要执行的导入必须放在 Markdown 反引号或代码围栏之外，否则只会被当作字面文本。项目导入若指向工作目录之外的文件，会提示请求批准。参见导入语法。

如果另一支团队已经维护了一份简短约定，而且每次会话都需要它，可以直接导入。对于较长的发布检查清单，更适合像上面的模板一样，留下普通文档引用。导入只是重新组织工作说明，并不会减少 Claude 启动时读取的内容。

已经有 AGENTS.md？让团队指令只维护一份

从 2.1.277 版本开始，在相关支持可用时，Claude Code 可以直接使用 AGENTS.md，代替 CLAUDE.md。默认行为有一个重要前提：工作目录及其上级目录中，都不能存在 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md。用户级和组织级指令文件不会阻止这一回退机制。参见 AGENTS.md 加载说明。

因此，CLAUDE.local.md 很容易引发困惑。只是添加了个人项目笔记，就可能改变你加载的是哪一份共享指令文件。

如果需要同时使用两种文件，打开 /config，将 Project instructions 设为 claude-md-and-agents-md。也可以在同目录的 CLAUDE.md 中写入 @AGENTS.md；即使无法直接加载 AGENTS.md，这种导入方式也能使用。尽量不要维护两份内容相同的团队规则。我们的 AGENTS.md 配置指南详细介绍了如何选择。

Claude Code 记忆怎么用？把有用的经验交给自动记忆

自动记忆让 Claude 能在不同对话之间保留有用的偏好、纠正和项目背景。哪些内容值得记录，由它自行判断；一次会话也可能什么都不保存。本地会话默认启用这一功能。参见自动记忆说明。

默认情况下，这些文件存放在 ~/.claude/projects/<project>/memory/。在同一台机器上，同一仓库的各个 worktree 和子目录共用这个记忆目录。worktree 是仓库的另一个检出工作区，因此，在其中切换到某个分支开始工作，并不会获得一本独立的笔记。这些文件不会自动共享给同事、其他机器或云端环境。参见存储位置说明。

MEMORY.md 是索引。会话启动时，Claude 会加载它的前 200 行或 25KB，以先达到的上限为准。详细的主题文件则在需要时读取。这一阈值限制的是启动时加载的索引内容，并非可存储记忆的总量。参见自动记忆的加载方式。

把 /memory 当作管理入口：它会列出记忆位置，让你在编辑器中打开文件、进入自动记忆文件夹，并开关自动记忆。需要核实启动时加载了哪些 CLAUDE.md 和规则文件时，再用 /context。参见记忆管理入口。

交代要求时，要说清楚保存到哪里。“记住，我希望交付说明更简短”是在要求保存一条学到的偏好；“把团队必须执行的测试命令加入 CLAUDE.md”则是在要求更新持续维护的指令。整个团队都需要的规则，不应依赖某位开发者主目录里的一条笔记。

不要默认普通子代理也能拿到这本笔记。主对话的自动记忆不会加载到普通子代理中；继承父对话的分叉是例外，子代理也可以单独配置自己的记忆。需要把工作分给多个代理时，可以参考我们的 Claude Code 子代理指南。另见子代理的记忆行为。

如何关闭自动记忆？

根据希望影响的范围选择设置方式：

• **用户级设置：**打开 /memory，关闭自动记忆。这个开关会把 autoMemoryEnabled 保存到 ~/.claude/settings.json。
• **单个项目：**在项目设置中写入 "autoMemoryEnabled": false。团队共享的项目设置放在 .claude/settings.json，个人的本地覆盖设置放在 .claude/settings.local.json。
• **通过环境变量控制启动：**设置 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。

以上方式见文档中的关闭选项和设置文件位置。关闭自动记忆后，独立的 CLAUDE.md 指令机制仍然可用。如果还想移除旧笔记，需要检查并明确删除相应的 Markdown 文件。

每月整理一次自动记忆

把这项工作当作一次简短的内容审阅，检查 Claude 会把哪些信息带入后续任务。每月一次是建议的团队习惯，并非产品要求。

1. **打开 /memory，浏览自动记忆文件夹。**先读 MEMORY.md，再沿着其中的引用查看具体笔记。
2. **删除过期背景。**移除已过去的截止日期、放弃的计划，以及不再适用的特例。对拿不准的笔记，结合项目现状核实。
3. **合并重复的纠正。**保留一条准确表述，避免留下多个略有不同的版本。
4. **把长期有效的团队决策移入共享指令。**将所有人都需要的约定写入已提交的 CLAUDE.md 或限定作用域的规则文件，再删除多余的个人笔记。
5. **精简索引。**在 MEMORY.md 中只保留简短指引，把细节放入主题文件。对照启动加载上限，同时检查行数和字节数。
6. **开启新会话试用。**用 /context 核实指令列表，并在下一个真实任务中检查是否仍有过时建议。

自动记忆文件是可编辑的 Markdown 文件，对话记录的保留策略不会自动清理它们。过时笔记仍然需要有人负责删除。参见编辑与保留机制。

五个值得这样配置的场景

先从那些已经因反复纠正而拖慢代码审查的环节入手。以下是建议采用的工作流程，按对小型产品团队可能带来的帮助排序。

围绕这套流程，可以做哪两种小产品？

**最值得考虑的是仓库指令审查服务。小团队可能愿意付费，请人核实命令、找出冲突指引，并给出简短的工作说明和限定作用域的规则。最小的实用交付物，是一份经过审查的拉取请求，以及可重复使用的审查清单。DataForSEO 估算，“claude project instructions”在美国的月搜索量为 260。**这个宽泛的查询还包含 Claude Code 之外的需求，只能说明有人在搜索相关主题，不能等同于买家数量。通用模板很容易复制，付费价值必须来自对具体仓库的判断。

**本地记忆整理报告，可能对同时维护多个活跃仓库的团队有用。初版可以标记过大的索引、缺失的主题引用，以及可能过时的笔记，再由开发者审核修改。DataForSEO 估算，“claude code memory”在美国的月搜索量为 1,300。**这说明有人关注这个问题，并不代表他们需要这款特定工具。这里有个很大的难点：仅凭文件的存在时间，无法判断其中的决策是否已经过时。内容含义是否仍然成立，应由了解项目的人判断。

这两项估算均来自美国英语关键词概览数据，于 2026 年 10 月 11 日通过本站的 DataForSEO 研究集成获取。它们对应的是产品构想，并非 Claude Code 内置功能。如果只有一个小仓库，先用好指令文件和每月审阅，再考虑购买或开发这些产品。

记忆提供上下文，强制约束要靠控制机制

在 CLAUDE.md 中写下“绝对不要这样做”，并不会让某项操作变得无法执行。自动记忆和组织级文字指引也是如此。Claude 可能误解含糊的指令，也可能遇到相互矛盾的要求。参见 Anthropic 的提醒。

如果某项操作无论 Claude 如何判断都必须拦截，就使用 PreToolUse 钩子：它是在工具操作执行前运行的控制机制。关于受保护文件的提醒，可以解释团队的意图；真正阻止操作，需要落实相应的控制。我们的 Claude Code hooks 配置指南介绍了钩子的配置方式。

控制上下文大小时，目标应是一份真正有人能维护的工作说明。Anthropic 建议每个 CLAUDE.md 文件少于 200 行，但这项建议与 MEMORY.md 的启动加载上限是两回事。不要为了凑一个想象中的配额而扩充模板，也不要把所有内容移到导入文件后，就以为上下文成本降低了。参见如何编写有效指令。

小团队常见问题

下周一就可以动手：回顾最近几次会话中的纠正，把反复出现的团队决策整理成一份经过审阅的 CLAUDE.md，再用一个小任务试用。把每月记忆审阅加入团队日历。

如果你需要帮助，将这些约定落地为可靠的开发流程，可以了解我们的 AI 生产系统服务。