新对话不必从零开始：用 CLAUDE.md 保留项目上下文

Claude Code 新建会话时不必从零了解项目。只要在仓库根目录维护一份准确、精简的 CLAUDE.md，Claude 会在该目录启动会话时自动读取它，把构建命令、架构约定、硬性限制和常见陷阱带入上下文。它更像给新队友的项目简报，而不是保存所有聊天记录的长期记忆。

CLAUDE.md 解决什么问题

代码仓库本身能说明系统“现在是什么样”，却不一定解释团队为何采用某种结构、该运行哪条命令、哪些目录不能修改。每次新会话都重新猜测这些信息，会浪费时间并增加错误。

CLAUDE.md 用一个版本化文件保存高价值项目约束。官方说明中，Claude Code 会自动读取适用范围内的文件，不需要用户每次在提示词中手动附加。只要新会话位于同一项目，它就能得到一致的基础简报。

三个常用放置位置

用户目录下的 ~/.claude/CLAUDE.md 适用于本机所有项目，可保存个人偏好，例如统一使用某个包管理器、修改后运行测试或输出风格。这里不适合写某个仓库的架构细节。

仓库根目录的 CLAUDE.md 是团队最常用的位置，适合保存项目架构、常用命令、代码约定和安全边界。它应提交到 Git，让所有成员和自动化环境获得相同规则。

子目录也可以有自己的 CLAUDE.md，用于前端、后端或基础设施模块的局部规则。官方说明指出，这类文件会在 Claude 读取该子目录内容时按需加载，而不是会话一开始全部塞入上下文。

加载顺序与作用域

Claude Code 会从较宽的范围到较具体的范围合并适用说明。个人规则提供通用偏好，仓库根规则定义项目标准，子目录规则补充模块差异。越具体的文件应只写本目录特有内容，避免复制根目录全文。

这种分层让大型单体仓库可以保持根文件简洁。例如根目录规定统一测试策略，前端目录补充组件命名和浏览器测试命令，API 目录补充数据库迁移限制。进入不同模块时，Claude 才读取对应规则。

它在什么时候被读取

位于当前工作目录及其上级路径的 CLAUDE.md 会在会话开始时加载。官方文档说明，它作为用户消息的一部分进入上下文，而不是被嵌入系统提示。子目录文件则在读取对应目录时加载。

文件不会在每一轮都从磁盘重新读取。会话中途修改后，通常要等下一次压缩上下文、通过记忆入口重新打开，或开启新会话才会生效。因此修改规则后应明确刷新，不要假设当前会话已经看到新内容。

最值得写入的五类内容

第一类是可执行命令：如何安装依赖、启动开发环境、运行单测、执行静态检查和构建发布。命令必须在当前仓库真实可用，因为 Claude 可能直接执行。

第二类是团队约定：命名、错误处理、目录布局、依赖选择和“使用 A 而不是 B”的明确决定。只记录无法从格式化工具或代码轻易推断的规则。

第三类是三句话以内的架构说明，解释主要组件及其通信方式，并指向更详细文档。第四类是硬性限制，例如测试不得连接生产数据库、所有 API 必须经过认证中间件、生成目录禁止手工编辑。

第五类是已知陷阱，例如某测试必须在特定目录运行、迁移前需要生成代码、某环境变量只在本地有效。这些是新成员最容易踩到、又难以仅靠阅读代码发现的信息。

哪些内容不该放进去

完整 API 文档、长篇变更日志、文件树中显而易见的信息和一次性任务进度不适合放进根文件。它们会占用上下文并降低重要规则的可见度。更详细的材料应留在专门文档中，再由 CLAUDE.md 提供短链接式路径说明。

不要写密钥、访问令牌、客户数据或生产凭据。可以说明凭据从哪个秘密管理系统获取、需要什么权限，但不能把秘密值提交到 Git。也不要把未经验证的聊天结论当作项目规则。

控制在约 200 行以内

官方建议保持文件简短、信息密度高，大致控制在 200 行以内。这个数字不是强制限制，重点是每一行都值得在每个相关请求中占据上下文。规则越多，真正重要的限制越容易被淹没。

当文件变长时，先删除过期和重复内容，再把模块规则下沉到子目录，把详细教程迁移到 docs。根文件只保留入口、共同约束和最常用命令。

一个实用的最小模板

# Project overview
- Web API and background worker share the domain package.
- Database migrations live in db/migrations.

# Commands
- Install: pnpm install
- Test: pnpm test
- Lint: pnpm lint

# Conventions
- Add tests for behavior changes.
- Use existing repository helpers before adding dependencies.

# Hard constraints
- Never edit generated/ manually.
- Tests must not access production services.

# Gotchas
- Integration tests require the local test database.

模板中的命令只是结构示例，必须替换为项目实际命令。不存在的命令比没有说明更危险，因为 Agent 可能据此产生错误诊断。

用 init 生成初稿后必须人工审查

官方建议可以在项目中运行 /init，让 Claude 探索代码库并生成初始 CLAUDE.md。初稿通常包含构建与测试命令、目录概览和检测到的约定，适合快速起步。

自动生成不等于可以直接提交。开发者必须删除推测内容，实际运行命令，确认架构描述和安全边界，并补上代码无法推断的组织约束。错误的规则会在每个新会话中持续放大。

如何验证 CLAUDE.md 有效

在干净的新会话中，让 Claude 简要列出项目构建、测试命令和不可修改目录，再与文件核对。随后给一个小任务，观察它是否选择正确工具并遵守限制。只有实际行为符合规则，才说明简报有效。

可在 CI 中验证文档列出的命令仍存在，例如检查 package script 或 Make target。对于关键禁令，还应通过权限、测试隔离和代码审查实现技术控制，不能只依赖自然语言提醒。

CLAUDE.md 与任务交接的区别

CLAUDE.md 保存跨任务稳定的项目规则，不应频繁记录“今天做到哪里”。某项功能的进展、失败尝试、未解决问题和下一步，应写入任务文档、工单或临时交接文件。

新会话先通过 CLAUDE.md 获取工作方式，再读取任务交接了解当前目标，最后检查 Git 和测试确认真实状态。这三层各司其职，既能恢复上下文，也能避免根规则文件变成流水账。

不要用它代替代码和测试

如果文档说所有路由必须认证，但代码允许绕过，那么真实风险仍在。关键规则应落实为中间件、类型约束、静态检查或测试。CLAUDE.md 用来指导工作，不是运行时控制系统。

同样，架构变更后必须同步更新文档。可在相关 Pull Request 模板中加入检查项，要求评估根文件和子目录规则是否需要调整。过期说明会让新会话比没有说明更容易走错方向。

缓存与上下文成本

官方文档说明，企业环境中的 Claude Code 会对 CLAUDE.md 应用提示缓存。会话首次请求需要处理完整文件，短时间内后续请求通常可以使用成本更低的缓存读取；文件内容变化会使缓存失效。

即使有缓存，也应保持精简，因为上下文窗口和注意力仍是有限资源。减少无关内容的主要收益是提高执行质量，而不只是降低 Token 费用。

团队维护流程

把根文件视为代码资产：通过 Pull Request 修改，由熟悉相关模块的人审查，并与代码变更一起发布。重大规则写明理由或链接到架构决策记录，但不要在文件中展开长篇历史。

定期检查命令、版本和目录是否仍有效。删除已经由工具强制执行的冗余提醒，合并重复规则，将局部约束移动到对应子目录。一个维护良好的短文件，比多年只增不减的规则集合更有价值。

结论

CLAUDE.md 让 Claude Code 在新会话开始时自动获得项目简报，因此新对话不必从零猜测团队习惯。个人、仓库和子目录三级文件分别承载不同作用域，最重要的是根目录文件应准确、精简并纳入版本控制。

把构建测试命令、架构摘要、硬性限制和常见陷阱写进去，把一次性进度留给任务交接，把行为要求落实到测试和工具中。这样新会话获得的不是旧聊天的模糊回忆，而是一份可审查、可更新、能被项目事实验证的工作说明。