核心概念

CLAUDE.md：让 AI 真正理解你的项目

一个文件，永久记忆你的项目规范、架构决策和团队约定——每次对话 Claude 都从这里开始

更新于 2026-10-08

#CLAUDE.md #ProjectMemory #BestPractices

什么是 CLAUDE.md？

CLAUDE.md 是放在项目根目录的特殊文件，Claude Code 每次启动时都会自动读取它。它相当于给 AI 的「项目简报」——包含技术栈、代码规范、目录结构、常用命令等关键信息，让 Claude 无需你反复说明就能理解项目上下文。截至 2026-10-07：仓库里只有 AGENTS.md、没有 CLAUDE.md 时，Claude Code 2.1.277 起会改读 AGENTS.md。

官方文档把它定位成「你本来要反复解释的东西」的记录处：只有每个会话都用得上的事实才该进来，单次任务的临时说明留给对话本身（核于 2026-09-21）。

一个纯文本文件

就是仓库里一份普通 markdown：你手写、提交进 Git、能读能 diff。官方口径是你写、Claude Code 在每个会话开始时读它（核于 2026-09-21）。

启动时自动加载

工作目录及其上层的每一级 CLAUDE.md 启动时一并读入；子目录里的要等 Claude 读到那里的文件才加载（核于 2026-09-21）。

是上下文不是配置

它每次会话都装进上下文窗口，和对话一起吃 token，而且不保证被严格执行——官方说它是上下文，不是强制配置（核于 2026-09-21）。

为什么需要 CLAUDE.md？

维护它的收益落在三件事上：省下每次会话开头那段背景介绍、让不同人问出的结果长得一样、让新人不用靠口头相传上手。

减少重复说明

不再需要每次会话都重新解释「我们用 TypeScript」「测试框架是 Jest」——CLAUDE.md 一次写好，永久生效

保持输出一致

定义代码风格、命名规范和架构约束，确保 Claude 生成的代码始终符合项目标准

团队知识共享

新成员加入时，CLAUDE.md 既是给 AI 的配置，也是给人的项目入门指南

CLAUDE.md 推荐模板

一个好的 CLAUDE.md 通常包含以下几个部分

CLAUDE.md

# 项目概述

- 订单中心后端，为 Web 端与小程序提供 REST API
- 新成员先读这份文件，再看入门指南
- 改接口前先确认客户端是否需要同步

## 技术栈

- 语言 TypeScript，运行时 Node.js，包管理用 pnpm
- 数据层 PostgreSQL，热点读走 Redis
- 测试 Vitest，覆盖率由 CI 卡住

## 目录结构

- src/api：HTTP 入口与参数校验，不放业务规则
- src/domain：业务规则，不 import 框架
- tests：与 src 同名镜像，定位失败更快

## 代码规范

- 两空格缩进、单引号、分号保留
- 命名写全称，不用缩写
- domain 层不出现框架类型，违反按缺陷处理

## 常用命令

- npm run dev：本地启动
- npm test：全量单测，交活前必须过
- npm run lint：提交前跑一次

## 注意事项

- 密钥和内部地址不写进本文件，走环境变量
- 数据库迁移先在影子库跑一遍
- 边界情况不确定就先问，别自己编默认值

高级技巧

这五条决定这份文件是被真正执行，还是变成没人再读的噪音；每条都给一条能直接拿去核对自家文件的判断标准。

只写反复用到的

判断标准很硬：这句话下次会话还用得上吗。构建命令、命名约定、踩过的坑算数；目录清单和依赖列表不算，那些 Claude 能从代码里自己读出来（核于 2026-09-21）。

控制在 200 行

官方给的参考线是每个文件 200 行以内，超过会更占上下文、遵循度也会掉（核于 2026-09-21）。装不下就拆成按路径作用域的规则，Claude 读到匹配文件时才加载。

写到能验证

「代码写得好」没有信息量，「两空格缩进、单引号、提交前跑 npm test」才能被照做。用小标题和列表分组，Claude 扫结构的方式和读者一样（核于 2026-09-21）。

先生成再修剪

别从空白页开始。/init 会分析代码库，把构建命令、测试方式和它发现的约定写成初稿；再按 /doctor 的思路删冗余、留下坑和理由；最后跑 /context 确认文件真被读到（核于 2026-09-21）。

不放敏感信息

这份文件会进 Git、被每个人每次会话读到。密钥、内部地址、测试账号走环境变量；个人偏好另放 CLAUDE.local.md 并加进 .gitignore，别污染团队那份（核于 2026-09-21）。

团队协作规范

多人项目中维护 CLAUDE.md 的最佳实践

改动走 PR

项目那份是团队资产，不是某个人的笔记：改它就走和代码同一个 PR，写清为什么改，并叫上负责那块目录的人评审。官方口径是项目级指令通过版本控制共享（核于 2026-09-21）。

加载顺序与冲突

上层的文件先装进上下文、子目录里的按需后读，内容是拼接叠加而不是互相覆盖。同一件事在两处写法不一致时，Claude 可能随机挑一条执行，所以要统一措辞或删掉一处（核于 2026-09-21）。

按模块拆文件

大仓别全塞根文件：模块专属内容放子目录的 CLAUDE.md 或按路径作用域的规则，它们在被读到时才进上下文，比一份巨型根文件更省也更准（核于 2026-09-21）。

让流水线盯着

把两件事变成固定动作：CI 检查根 CLAUDE.md 是否存在、是否超出约定规模；每次架构变更的 PR 顺手复查旧条目。官方也要求定期删掉过期与冲突指令（核于 2026-09-21）。

常见错误

这四条都会让文件从省事变成添乱，也都不需要重写就能改掉。

写成一次性任务

把某个 bug 的复现步骤、某次重构的中间结论整段贴进来——下次会话它还占着位置，而通用约定一条没写。这类内容放 issue 或 PR 描述里（核于 2026-09-21）。

文件只增不减

官方把参考线画在 200 行：超过就更占上下文、也更难被遵守（核于 2026-09-21）。别用「再加一条」治膨胀，把只在特定目录用得上的部分拆出去。

两处互相矛盾

根目录写用 pnpm、子目录写用 npm，Claude 可能任选一条执行（核于 2026-09-21）。同一主题只留一处权威写法，其余用导入引用，别复制第二份。

写完不再管

框架换了、目录重构了，文件里的命令还是旧的。官方要求定期复查各层文件、删掉过期与冲突条目（核于 2026-09-21）；挂在架构变更的 PR 检查里最省事。

常见问题

CLAUDE.md 每次都要手动给吗？

不用。放在工作目录或其上层目录的 CLAUDE.md 会在会话开始时自动加载，子目录里的文件等 Claude 读到那里再进上下文。想确认这次读了哪几份，跑 /context 看 Memory files 列表（核于 2026-09-21）。

文件多大算合适？

官方的参考是每个文件 200 行以内，超过会更占上下文、遵循度也会下降（核于 2026-09-21）。模块专属的内容拆成按路径作用域的规则文件，让它只在碰到对应文件时加载。

和 AGENTS.md 冲突吗？

官方默认二选一：工作目录或其上层有任一 CLAUDE.md 时就不读 AGENTS.md。想都生效，可在 /config 里改 Project instructions 为同时读取，或在 CLAUDE.md 用 @AGENTS.md 导入（核于 2026-09-21）。2026-10-07 补充：这一行为来自 Claude Code 2.1.277（2026-09-18 发布），变更日志原文「Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead」；2.1.281（2026-09-23）起在 LLM 网关会话里也生效。