第 12 章：CLAUDE.md —— 项目的大脑

如果说 Agent Loop 是 Claude Code 的"神经系统"，工具系统是它的"双手"，那么 CLAUDE.md 就是它的"大脑皮层"——它为 Claude 建立了对项目的初始认知模型。没有 CLAUDE.md，Claude 像一个被临时拉来的外包开发者，每次都要从零开始理解项目；有了一份好的 CLAUDE.md，Claude 就像一个入职两周、已经读过所有文档的新同事。

本章是进阶篇中最重要的一章。你将学到 CLAUDE.md 的完整编写方法论：从基本结构到编写原则，从模板到真实案例，从单项目策略到大型 monorepo 的分层方案，以及与之配合的 Memory 系统。

学习完本章后，你将能够：

理解 CLAUDE.md 在 Claude Code 体系中的核心地位
按照社区最佳实践编写一份高质量的 CLAUDE.md
为大型项目设计 CLAUDE.md 的分层策略
利用 Memory 系统实现跨会话的持久化记忆
建立 CLAUDE.md 的持续维护机制

12.1 CLAUDE.md 是什么

定义

CLAUDE.md 是放在项目根目录下的一个 Markdown 文件，它是 Claude Code 的项目上下文文件。每当你在该项目中启动 Claude Code，它会自动读取这个文件来理解项目。

my-project/
├── CLAUDE.md          ← Claude Code 自动发现并读取
├── src/
├── package.json
└── ...

它不是什么

一个常见的误解是把 CLAUDE.md 当作 README 来写。两者的区别至关重要：

	CLAUDE.md	README.md
读者	Claude（AI）	人类开发者
目的	让 AI 理解项目，高效工作	让开发者了解项目，快速上手
内容侧重	命令、架构、规范、约定、易错点	项目介绍、安装步骤、使用示例
语言风格	指令性、结构化、精简	叙述性、展示性、可加入品牌元素
长度建议	300 行以内	无严格限制

一句话总结：README 是写给人的项目介绍，CLAUDE.md 是写给 AI 的"新人入职文档"。

没有 CLAUDE.md 会怎样

如果项目中不存在 CLAUDE.md，Claude Code 仍然可以工作——它会通过读取文件、分析代码来逐步理解项目。但这个过程存在几个问题：

效率低：每次新会话，Claude 都需要花时间重新探索项目结构
易出错：没有明确规范指导，Claude 可能写出风格不一致的代码
遗漏约定：项目特有的隐式约定（如"不要用某个库"、"配置文件必须手动更新"）不会被感知
消耗上下文：Claude 需要自己用 Glob/Read 工具去探索项目，这些操作占用宝贵的上下文窗口

有了一份好的 CLAUDE.md，Claude 在会话开始的第一秒就能理解项目的核心信息，像一个已经上手的同事一样开始工作。

有 CLAUDE.md 的效果

一份优秀的 CLAUDE.md 带来的改变是实质性的：

启动零成本：Claude 在对话开始时就了解项目架构、常用命令、编码规范
输出一致性：生成的代码自动符合项目规范，不需要你反复纠正
减少错误：易错点和注意事项被提前告知，Claude 会主动规避
上下文节省：不需要在每次对话中重复解释项目背景，节省宝贵的上下文窗口

12.2 CLAUDE.md 的作用与加载时机

什么时候加载

CLAUDE.md 的加载遵循一个明确的规则——在每个新会话开始时自动加载：

场景	CLAUDE.md 是否加载	说明
启动 Claude Code	✅ 自动加载	新会话的第一步就是读取 CLAUDE.md
执行 `/clear`	✅ 自动加载	`/clear` 相当于重置会话，CLAUDE.md 会重新读取
对话进行中修改 CLAUDE.md	❌ 不会自动加载	修改不会在当前会话中生效
Git 分支切换导致 CLAUDE.md 变化	❌ 不会自动加载	CLAUDE.md 在会话启动时读入，后续不跟踪变化

如何强制重新加载 CLAUDE.md

由于 CLAUDE.md 不会在会话进行中自动重新读取，如果你在对话过程中修改了它，有两种方式让更新生效：

执行 /clear：清空当前对话，CLAUDE.md 会被重新读取
开启新会话：结束当前会话，启动一个新的对话

最佳实践：如果你需要频繁修改 CLAUDE.md 并测试效果，建议在一个独立会话中完成修改，然后用新会话验证。

多文件策略的限制

一个重要的限制：Claude Code 只自动读取项目根目录下的单个 CLAUDE.md 文件。它不会自动递归查找子目录中的 CLAUDE.md。

my-project/
├── CLAUDE.md              ← ✅ 自动读取
├── packages/
│   ├── web/
│   │   └── CLAUDE.md      ← ❌ 不会自动读取
│   └── api/
│       └── CLAUDE.md      ← ❌ 不会自动读取

对于 monorepo 项目，我们会在 12.5 节中讨论如何应对这个限制。

上下文注入的时机

从技术角度看，CLAUDE.md 的内容会在以下时机被注入到系统提示词中：

启动 Claude Code
  → 检测项目根目录的 CLAUDE.md
  → 读取完整内容
  → 注入到 System Prompt 的"项目上下文"部分
  → 后续对话中，Claude 始终拥有这些上下文

这解释了为什么 CLAUDE.md 的内容如此重要——它成为了 Claude "认知基础"的一部分，在整个会话期间持续发挥作用。

12.3 CLAUDE.md 编写规范

基本结构

一份标准的 CLAUDE.md 通常包含以下四个核心模块：

markdown

# CLAUDE.md

## Commands
# 常用的构建、测试、开发命令
```bash
pnpm dev          # 启动开发服务器
pnpm build        # 生产构建
pnpm test         # 运行测试
pnpm lint         # 代码检查

Architecture

项目的高层架构描述

src/ — 前端源码（React + TypeScript）
server/ — 后端 API（Express + Prisma）
数据流：Client → API → Service → Database

Code Style

编码规范和约定

使用 TypeScript 严格模式
组件文件使用 PascalCase
工具函数文件使用 camelCase
所有 API 返回值使用统一的 { data, error } 格式

Conventions

项目特有的约定

测试使用 vitest，不要用 jest
Git commit 使用 conventional commits 格式
新功能需要 feature flag，使用 useFeatureFlag hook


这四个模块各司其职：

| 模块 | 回答的问题 | 关键内容 |
|------|-----------|---------|
| **Commands** | 怎么运行这个项目？ | 开发、构建、测试、部署命令 |
| **Architecture** | 项目是怎么组织的？ | 目录结构、数据流、技术栈 |
| **Code Style** | 代码应该怎么写？ | 语言、格式化、命名、错误处理 |
| **Conventions** | 项目有什么特殊约定？ | 工作流、Git 规范、特有的限制 |

### 编写原则

#### 原则一：当新人入职文档写

**把 CLAUDE.md 当作你给新同事第一天准备的入职文档来写。** 你希望新人第一天知道什么，就写进 CLAUDE.md：

- 项目是做什么的（一句话）
- 怎么启动开发环境
- 代码在哪里、怎么组织的
- 有哪些容易踩的坑
- 团队的特殊约定是什么

不需要写：
- 业务逻辑的完整描述（Claude 可以读代码理解）
- 每个文件的详细说明（Claude 可以自己 Glob/Grep）
- 可以在 README 中找到的安装步骤（写给人看的放 README）

#### 原则二：宁短勿长

**只写关键的、反直觉的、易错的内容。300 行以内是最佳范围。**

- ✅ 写："配置文件 `.vitepress/config.ts` 是导航和侧边栏的唯一真实来源，添加新章节时必须手动更新"
- ❌ 不写：每个文件的逐行解释、完整 API 文档、可以自动发现的信息

Claude Code 自带 Glob、Grep、Read 工具，它能自己探索的东西不需要写在 CLAUDE.md 中。你应该聚焦在：
- 它无法自己发现的信息（历史背景、设计决策）
- 容易出错的地方（陷阱、限制、反模式）
- 项目特有的非标准约定

#### 原则三：保持更新

CLAUDE.md 不是写完就扔的一次性文档。项目架构变化时，同步更新 CLAUDE.md：

- 技术栈升级 → 更新 Commands 和 Architecture
- 新增或删除目录 → 更新 Architecture
- 发现新的易错点 → 补充到 Conventions
- 编码规范变化 → 更新 Code Style

一个过时的 CLAUDE.md 比没有更糟糕——Claude 会基于错误的信息做出错误的判断。

#### 原则四：用 `/init` 生成初稿，然后手动精炼

Claude Code 内置的 `/init` 命令可以自动分析项目并生成 CLAUDE.md 初稿：

/init


生成的初稿通常包含基本的架构描述和命令，但它不能替代人工精炼。`/init` 适合作为起点，之后你需要：

1. 删除冗余信息（CLAUDE.md 不是文件清单）
2. 补充项目特有的约定和易错点
3. 用更精确的语言重写关键段落
4. 控制总长度在 300 行以内

#### 原则五：放在项目根目录

CLAUDE.md 必须放在项目根目录下，Claude Code 才能自动发现。不需要任何额外配置。

### 各模块编写指南

#### Commands 模块

只列出**最常用的命令**，每条命令附带一行注释说明其作用：

```bash
pnpm dev          # Start dev server (hot-reloads .md; restart for config.ts changes)
pnpm build        # Build static site to .vitepress/dist/
pnpm test         # Run test suite (vitest)
pnpm lint         # Run ESLint + Prettier

关键点：

每条命令一行，不要写完整的使用文档
注释用英文或中文皆可，保持一致性
不包括罕见/特殊用途的命令
如果项目没有测试套件，明确注明 "No test suite exists"

Architecture 模块

描述项目的高层架构——目录结构和它们之间的关系，而非罗列每个文件：

markdown

- **`src/`** — Content root (`srcDir: 'src'`). All `.md` files become pages.
- **`src/posts/YYYY/MM_DD_title.md`** — Blog posts by year. `posts.data.ts` reads frontmatter.
- **`.vitepress/config.ts`** — Single source of truth for nav, sidebar, and all site settings.
- **`.vitepress/dist/`** — Build output. **Do not delete this directory.**

关键点：

用箭头或文字描述数据流
标记易错点（用加粗强调）
只写到目录级别，不深入文件
说明"为什么"（这个目录的设计意图），而非仅仅"是什么"

Code Style 模块

列出非标准的、项目特有的编码规范：

markdown

- 使用 TypeScript 严格模式
- 组件文件使用 PascalCase（`UserProfile.tsx`）
- API 返回值使用统一的 `{ data, error }` 格式
- 禁止使用 `any` 类型

关键点：

不重复通用的最佳实践（如"使用 const 而非 let"）
聚焦在项目特有的约定
如果使用了 ESLint/Prettier，指出配置文件位置即可，不重复规则

Conventions 模块

记录工作流、Git、部署等方面的约定和注意事项：

markdown

- 测试使用 vitest，不要用 jest
- Git commit 使用 conventional commits 格式
- 新功能必须通过 feature flag 发布
- `/dist/` 目录有自己的 git 仓库用于部署，**不要删除**

关键点：

强调"不要做什么"（反模式）和"必须做什么"（硬性约束）
记录已发现的陷阱和解决方案
如果项目有特殊的文件结构约定（如博文命名格式），在此说明

12.4 CLAUDE.md 模板与示例

社区推荐模板

以下是社区中广泛使用且经过验证的 CLAUDE.md 模板：

markdown

# CLAUDE.md

## Tech Stack
- Frontend: React 18 + TypeScript + Tailwind CSS
- Backend: Node.js + Express + Prisma + PostgreSQL
- Testing: Vitest + Testing Library

## Commands
```bash
pnpm dev          # Start dev server (localhost:3000)
pnpm build        # Production build
pnpm test         # Run tests
pnpm test:watch   # Watch mode
pnpm lint         # ESLint + Prettier
pnpm db:migrate   # Run Prisma migrations

Project Structure

src/
  components/  # Shared UI components
  features/    # Feature modules (each has its own hooks, types, tests)
  lib/         # Utilities and helpers
  pages/       # Route pages
server/
  routes/      # API route handlers
  services/    # Business logic
  db/          # Prisma schema and migrations

Rules

Always use TypeScript strict mode
API responses use { data, error } envelope
Feature flags are required for new features
Commit messages follow conventional commits
Never import from ../../ — use path aliases
Tests go next to the file they test, with .test.ts suffix


### 真实案例：本书项目的 CLAUDE.md

以下是本项目（一个基于 VitePress 的个人 Wiki/Blog）实际使用的 CLAUDE.md，配合逐段注解，帮助你理解为什么每个部分要这样写：

```markdown
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working
with code in this repository.

注解：第一段说明文件的用途和受众。简洁直接，不废话。

markdown

## Commands

```bash
pnpm dev          # Start dev server (hot-reloads .md; restart for config.ts changes)
pnpm build        # Build static site to .vitepress/dist/
pnpm preview      # Preview built site

make post 'title' # Scaffold new post at src/posts/YYYY/MM_DD_title.md
make image        # Resize images to 1400px, convert png/jpg → webp (requires fd, cwebp)
make deploy       # Clean, build, force-push dist/ to GitHub Pages repo
make clean        # Remove .vitepress/cache and .vitepress/dist/assets

No test suite exists.


> **注解**：每条命令一行加注释。特别注明 `pnpm dev` 对 `.md` 文件热更新但对 `config.ts` 修改需重启——这是一个**反直觉的知识点**，如果不写，Claude 修改配置后可能困惑为什么没生效。最后明确声明"没有测试套件"，避免 Claude 反复尝试运行测试。

```markdown
## Architecture

Personal wiki/blog built with VitePress. Content in Markdown under `src/`,
deployed as a static site to GitHub Pages (`https://wshibin.github.io`).

- **`src/`** — Content root (`srcDir: 'src'`). All `.md` files become pages.
- **`src/posts/YYYY/MM_DD_title.md`** — Blog posts by year. `posts.data.ts`
  reads frontmatter and exposes a sorted `Post[]` for the Archives page.
- **`src/drafts/`** — Draft posts, excluded from build via `srcExclude` in config.
- **`.vitepress/config.ts`** — Single source of truth for nav (`themeNav`),
  sidebar (`themeSidebar`), and all site settings. Must be updated manually
  when adding new doc sections.
- **`.vitepress/theme/`** — Custom theme: `NewLayout.vue` wraps default layout
  with a `Date` component; `Archives.vue` renders the post list; `style.css`
  overrides brand colors and content width (1440px max).
- **`.vitepress/dist/`** — Build output with its own `.git` repo for deployment.
  **Do not delete this directory.**

Content areas under `src/`: `csprimer/`, `linux/`, `windows/`, `lang/`,
`misc/`, `backend/`, `multimedia/`.

注解：每个目录都说明了为什么存在和怎么使用。两个关键点被加粗强调：config.ts 是"单一真实来源"且必须手动更新（如果 Claude 不知道这点，可能只创建 .md 文件而忘记更新配置）；dist/ 有独立的 git 仓库，绝对不能删除（这是最致命的陷阱）。

markdown

## Content Conventions

### Two page types

**Post** (blog entries appearing in archives):
```yaml
---
title: 'Post Title'
categories: CategoryName
tags:
  - tag1
outline: deep
layout: doc
prev: false
next: false
sidebar: false
comments: true
date: 2025-01-15 10:00:00
---

# {{ $frontmatter.title }}

Doc (reference/wiki pages with sidebar navigation):

yaml

---
title: 'Doc Title'
outline: deep
layout: doc
prev: true
next: true
sidebar: true
date: 2025-01-15 10:00:00
---

# {{ $frontmatter.title }}

Key differences: posts have sidebar: false, prev: false, next: false, comments: true, and categories/tags. All pages use # 第 12 章：CLAUDE.md —— 项目的大脑 as the first heading, not a hardcoded string.


> **注解**：这是项目特有的约定——两种页面类型的 frontmatter 模板。通过直接嵌入完整的 YAML 模板，Claude 在创建新页面时能直接复制正确的格式。底部特别说明了两种类型的差异和"必须用 `{{ $frontmatter.title }}`"这一规则——这是一个极易被忽略的细节。

```markdown
### Adding new doc sections

1. Add nav items to `themeNav` in `.vitepress/config.ts`
2. Add sidebar entries to `themeSidebar` keyed by URL prefix (e.g., `'/newSection/'`)

### Images

Store as `.webp` alongside the referencing `.md` file or under
`src/public/img/`. Use `make image` to bulk-convert.

注解：操作步骤清晰、按顺序排列。这些是非标准的流程，Claude 无法通过读代码推断出来。

markdown

## Other

- git commit 信息使用中文

注解：项目中最重要的特殊约定之一，一句话说清楚。Claude 看到这条后，所有 commit message 都会自动用中文。

这份 CLAUDE.md 总共约 60 行（不含代码块）。它做到了：精准（每条信息都有明确的目的）、简洁（300 行以内）、可执行（Claude 可以据此直接行动）。

12.5 大型项目的 CLAUDE.md 分层策略

单一文件的困境

前文提到，Claude Code 只自动读取根目录下的单个 CLAUDE.md。对于 monorepo 或多模块的大型项目，把所有信息塞进一个文件会导致文件臃肿，违反"宁短勿长"原则。

本节提供三种经过实践验证的策略。

策略一：CLAUDE.md 作为总索引

根目录的 CLAUDE.md 只写全局信息，将子项目的详细说明引用到各自的文档文件：

markdown

# CLAUDE.md

## Project Overview
Monorepo with 3 packages, managed by pnpm workspaces.

## Commands
```bash
pnpm dev          # Start all packages in dev mode
pnpm build        # Build all packages
pnpm test         # Run all tests

Package Structure

packages/web/ — React frontend. See packages/web/README.md for detailed architecture and component conventions.
packages/api/ — Express backend. See packages/api/README.md for API design conventions and middleware usage.
packages/shared/ — Shared TypeScript types and utility functions. Changes here affect all packages.

Global Rules

Use pnpm, not npm or yarn
All packages use TypeScript strict mode
Commit messages follow conventional commits
See packages/*/README.md for package-specific conventions


**关键原则**：根 CLAUDE.md 做"目录"，子项目的 `README.md`（或 `DEVELOPER.md`）做"正文"。Claude 会用 Read 工具自行查阅引用的文件。

这种策略的优势：
- 根 CLAUDE.md 保持精简（通常 50-80 行）
- 子项目文档可以写得更详细，因为它们按需加载
- 职责清晰：全局约定在根，局部约定在子项目

### 策略二：子项目 CLAUDE.md + 手动加载

**在子项目中也放置 CLAUDE.md，但在提示中手动要求 Claude 阅读：**

请先阅读 packages/web/CLAUDE.md，然后开始处理前端任务


这种方式适合：
- 你不总是在根目录启动 Claude Code
- 不同团队负责不同子项目，各自维护自己的 CLAUDE.md
- 子项目差异很大（如一个是 Rust 后端、一个是 React 前端）

> **注意**：这不是自动的——你需要在提示中明确指导 Claude 去读子项目的 CLAUDE.md。不过一旦读过，该会话中 Claude 就会记住这些信息。

### 策略三：按场景的 CLAUDE.md 变体

对于非常庞大的项目，可以为不同场景维护多个版本的 CLAUDE.md，通过脚本在需要时切换：

```bash
# 日常开发使用标准版
cp CLAUDE-dev.md CLAUDE.md

# 部署相关任务使用运维版
cp CLAUDE-ops.md CLAUDE.md

这种策略适合 CI/CD 集成场景，日常开发较少使用。不推荐在常规开发中使用，因为增加了维护负担。

分层决策指南

项目规模	推荐策略	根 CLAUDE.md 长度
单项目	单一 CLAUDE.md	50-150 行
小型 monorepo（2-3 包）	策略一：总索引	50-80 行
中型 monorepo（4-10 包）	策略一或策略二混合	40-60 行
大型 monorepo（10+ 包）	策略二：子项目 CLAUDE.md	30-50 行（仅全局约定）

各层内容分配指南

当使用分层策略时，按以下原则分配内容：

放在根 CLAUDE.md 中的内容：

全局命令（如 pnpm dev 启动所有包）
跨包共享的编码规范
Git commit 约定
Monorepo 工具链信息（如 pnpm workspaces）
各子项目的简要描述和文档引用路径

放在子项目 README.md 或 CLAUDE.md 中的内容：

子项目的架构细节
子项目特有的命令
子项目特有的编码规范
子项目的测试策略
子项目的已知陷阱

12.6 Memory 系统

Memory 是什么

Memory 是 Claude Code 的持久化记忆系统。与 CLAUDE.md（手写的、静态的）不同，Memory 是 Claude Code 自动生成和维护的，它记录你在使用过程中的偏好、反馈和项目上下文。

Memory 的存储位置

Memory 文件存储在项目目录下的 .claude/projects/<path>/memory/ 中：

my-project/
├── .claude/
│   └── projects/
│       └── -Users-shibin-my-project/
│           └── memory/
│               ├── user-role.md      # 用户角色和偏好
│               ├── project-context.md # 项目上下文和当前目标
│               └── feedback.md       # 反馈记录

Memory 存储的内容

文件	内容	示例
用户角色	你的技术背景、偏好、常用技术栈	"你是一名全栈开发者，偏好 TypeScript，使用 fish shell"
项目上下文	当前目标、已知问题、正在进行的工作	"正在重构用户认证模块，目标是从 JWT 迁移到 OAuth 2.0"
反馈记录	你之前的纠正和确认	"上次你建议用 Redis，但团队决定用 PostgreSQL 做缓存"

Memory 的跨会话持久化

Memory 最重要特性是跨会话持久化——它会在会话结束后保留，在新会话开始时被加载。这意味着：

会话 1:
  你："这个项目用 pnpm，不要用 npm"
  → Memory 记录了这个偏好

会话 2（第二天，新窗口）:
  你："安装 express"
  → Claude 自动使用 pnpm add express（不需要你再次提醒）

这种机制让 Claude Code 具备了"学习能力"——随着使用次数的增加，它越来越了解你和你的项目。

Memory vs CLAUDE.md

两者的定位有本质区别：

维度	CLAUDE.md	Memory
创建方式	人工编写	自动生成
内容性质	项目通用信息	个人偏好和会话历史
更新频率	偶尔（项目变化时）	持续（每次对话都可能更新）
是否提交 Git	✅ 是	❌ 否（在 `.claude/` 中）
作用范围	所有使用该项目的开发者	仅当前用户
可控性	完全可控	部分可控

简单记忆：CLAUDE.md = 项目的公共知识，Memory = 你的私人笔记。

何时手动更新 Memory

虽然 Memory 是自动维护的，但在某些场景下，手动更新会更高效：

项目目标变更：告诉 Claude "我们现在的目标是 X"
纠正错误认知：Claude 从之前的对话中得出错误结论时
重新设定偏好：比如"我以后用 yarn 而不是 pnpm"

你可以直接告诉 Claude：

请记住：这个项目使用 Biome 而不是 ESLint + Prettier

Claude Code 会自动更新对应的 Memory 文件。

Memory 文件格式

Memory 文件是普通的 Markdown 文件，内容由 Claude 维护。你可以直接查看和编辑它们：

markdown

# User Role

- Full-stack developer with 8 years of experience
- Primary languages: TypeScript, Rust, Python
- Uses fish shell on macOS
- Prefers functional programming patterns
- Uses VSCode with Vim keybindings

注意：虽然可以直接编辑，但不推荐——Memory 文件由 Claude 维护，手动编辑可能导致格式不一致。

12.7 CLAUDE.md 维护与更新

更新触发条件

以下情况应该触发 CLAUDE.md 的更新：

触发条件	需要更新的部分	示例
架构变化	Architecture	从单体拆分为微服务
技术栈升级	Commands, Architecture	Next.js 12 → 14
新增约定	Conventions	团队决定所有 API 加版本号
发现陷阱	各相关模块	发现某个库的特定版本有兼容性问题
新命令	Commands	添加了新的 Makefile 目标
编码规范变化	Code Style	从 ESLint 迁移到 Biome
目录重组	Architecture	移动或重命名重要目录

使用 `/init` 重新生成

当项目发生较大变化时，可以用 /init 命令重新分析项目并生成新的 CLAUDE.md 草稿：

/init

对比新旧版本，合并有价值的新信息，同时保留你手动添加的精炼内容和特殊约定。

使用 claude-md-management 审计

Claude Code 社区提供了 claude-md-management 系列 Skill，用于对 CLAUDE.md 进行质量审计：

claude-md-management:claude-md-improver：扫描项目中所有 CLAUDE.md 文件，评估质量，给出改进建议并自动优化
claude-md-management:revise-claude-md：基于当前会话的学习内容更新 CLAUDE.md

使用示例：

帮我审计一下这个项目的 CLAUDE.md

这些 Skill 会按照社区质量标准检查你的 CLAUDE.md，并给出具体的优化建议。

版本控制

CLAUDE.md 应该提交到 Git，作为项目源码的一部分。带来的好处：

历史追踪：可以看到规范的演变过程
团队共享：所有团队成员使用相同的 AI 行为引导
PR 审查：CLAUDE.md 的变更可以像代码一样被审查和讨论
回退能力：如果某次更新导致 Claude 行为异常，可以回退到之前的版本

bash

git add CLAUDE.md
git commit -m "docs: 更新 CLAUDE.md，补充新的编码规范"

团队协作

对于多人协作的 CLAUDE.md：

PR 流程：CLAUDE.md 的变更走正常的 PR 审查流程
保持共识：团队定期讨论是否需要更新 CLAUDE.md（如 Sprint 回顾时）
避免冲突：CLAUDE.md 通常较短，结构清晰，合并冲突较少
新成员参与：新同事入职时，鼓励他们根据切身体验更新 CLAUDE.md——"新手视角"往往能发现老成员忽略的痛点

12.8 常见错误

1. 写得太多（把 CLAUDE.md 当百科全书）

这是最常见的错误。一份 500+ 行的 CLAUDE.md 不仅消耗上下文窗口，还会稀释关键信息——真正重要的内容被淹没在细节中。

错误示例：列出每个文件的用途、每行配置的解释、完整的 API 文档

正确做法：只写高层架构 + 关键约定 + 易错点。Claude 可以自己读文件了解细节。

2. 复制 README 内容

README 和 CLAUDE.md 的读者不同、目的不同。在 CLAUDE.md 中写"安装步骤"、"功能列表"、"使用示例"毫无意义——Claude 不需要"安装"这个项目。

正确做法：CLAUDE.md 聚焦在 Claude 需要知道的信息——如何运行、如何组织、什么能做、什么不能做。

3. 罗列所有文件

Claude Code 有 Glob 和 Grep 工具，可以自己探索文件结构。在 CLAUDE.md 中列出每个文件是浪费上下文。

错误示例：

- src/index.ts — 入口文件
- src/config.ts — 配置文件
- src/utils.ts — 工具函数
...（共 50 行）

正确做法：

- src/ — 源代码目录，按功能模块组织

4. 不更新

项目经过几个月的迭代，CLAUDE.md 还停留在最初的版本。新的陷阱没有被记录，过时的约定仍在生效。

正确做法：每次重大变更后检查 CLAUDE.md 是否需要更新。把"检查 CLAUDE.md"加入 PR checklist。

5. 语言模糊

使用含糊不清的表达，Claude 无法从中提取可执行的指导。

错误示例：

我们通常用 TypeScript 写代码，最好用严格模式

正确示例：

- 所有新代码使用 TypeScript 严格模式（tsconfig.json 中 strict: true）
- 禁止使用 any 类型

6. 遗漏已知陷阱和变通方案

项目中最有价值的信息往往是那些"不能用常规方式解决"的部分——已知的坑和对应的变通方案。这些信息是 Claude 无法通过阅读代码推断出来的，正是 CLAUDE.md 应该承载的核心内容。

错误示例：CLAUDE.md 只写了标准的架构描述，没有提到"这个库的 3.x 版本有内存泄漏，不能升级"

正确做法：把所有已知的坑、不兼容性、变通方案都写进去。

12.9 本章小结

CLAUDE.md 是 Claude Code 体系中最重要的项目级配置。它不是一份可有可无的文档，而是直接决定了 Claude Code 在你项目中的工作效率和输出质量。

本章的核心要点：

CLAUDE.md 是给 AI 看的"新人入职文档"，不是 README，也不是文件清单
基本结构四大模块：Commands（怎么运行）、Architecture（怎么组织）、Code Style（怎么写）、Conventions（有什么特殊约定）
编写五原则：当入职文档写、宁短勿长、保持更新、用 /init 起手、放在根目录
精确保守：每行内容都要有明确的目的，300 行以内为佳。只写 Claude 无法自己发现的信息
大型项目用分层策略：根 CLAUDE.md 做索引，子项目 README.md 做正文，或使用多个 CLAUDE.md 配合手动加载
Memory 是自动生成的持久化记忆：它记录你的偏好和反馈，跨会话保存，但不需要手动维护
CLAUDE.md 需要持续维护：架构变化时同步更新，使用 /init 重生，用 claude-md-management 审计，提交到 Git 做版本控制
避免常见错误：不要写太长、不要复制 README、不要罗列文件、不要忘记更新

CLAUDE.md 是你和 Claude Code 之间的"API 契约"。投入时间写好它，你在每一次对话中都会收到回报。

在下一章，我们将深入 Claude Code 的配置体系——从四层配置优先级到每个配置项的详细说明，帮助你构建最适合自己的开发环境。

第 12 章：CLAUDE.md —— 项目的大脑 ​

12.1 CLAUDE.md 是什么 ​

定义 ​

它不是什么 ​

没有 CLAUDE.md 会怎样 ​

有 CLAUDE.md 的效果 ​

12.2 CLAUDE.md 的作用与加载时机 ​

什么时候加载 ​

如何强制重新加载 CLAUDE.md ​

多文件策略的限制 ​

上下文注入的时机 ​

12.3 CLAUDE.md 编写规范 ​

基本结构 ​

Architecture ​

项目的高层架构描述 ​

Code Style ​

编码规范和约定 ​

Conventions ​

项目特有的约定 ​

Architecture 模块 ​

Code Style 模块 ​

Conventions 模块 ​

12.4 CLAUDE.md 模板与示例 ​

社区推荐模板 ​

Project Structure ​

Rules ​

12.5 大型项目的 CLAUDE.md 分层策略 ​

单一文件的困境 ​

策略一：CLAUDE.md 作为总索引 ​

Package Structure ​

Global Rules ​

分层决策指南 ​

各层内容分配指南 ​

12.6 Memory 系统 ​

Memory 是什么 ​

Memory 的存储位置 ​

Memory 存储的内容 ​

Memory 的跨会话持久化 ​

Memory vs CLAUDE.md ​

何时手动更新 Memory ​

Memory 文件格式 ​

12.7 CLAUDE.md 维护与更新 ​

更新触发条件 ​

使用 /init 重新生成 ​

使用 claude-md-management 审计 ​

版本控制 ​

团队协作 ​

12.8 常见错误 ​

1. 写得太多（把 CLAUDE.md 当百科全书） ​

2. 复制 README 内容 ​

3. 罗列所有文件 ​

4. 不更新 ​

5. 语言模糊 ​

6. 遗漏已知陷阱和变通方案 ​

12.9 本章小结 ​

第 12 章：CLAUDE.md —— 项目的大脑

12.1 CLAUDE.md 是什么

定义

它不是什么

没有 CLAUDE.md 会怎样

有 CLAUDE.md 的效果

12.2 CLAUDE.md 的作用与加载时机

什么时候加载

如何强制重新加载 CLAUDE.md

多文件策略的限制

上下文注入的时机

12.3 CLAUDE.md 编写规范

基本结构

Architecture

项目的高层架构描述

Code Style

编码规范和约定

Conventions

项目特有的约定

Architecture 模块

Code Style 模块

Conventions 模块

12.4 CLAUDE.md 模板与示例

社区推荐模板

Project Structure

Rules

12.5 大型项目的 CLAUDE.md 分层策略

单一文件的困境

策略一：CLAUDE.md 作为总索引

Package Structure

Global Rules

分层决策指南

各层内容分配指南

12.6 Memory 系统

Memory 是什么

Memory 的存储位置

Memory 存储的内容

Memory 的跨会话持久化

Memory vs CLAUDE.md

何时手动更新 Memory

Memory 文件格式

12.7 CLAUDE.md 维护与更新

更新触发条件

使用 `/init` 重新生成

使用 claude-md-management 审计

版本控制

团队协作

12.8 常见错误

1. 写得太多（把 CLAUDE.md 当百科全书）

2. 复制 README 内容

3. 罗列所有文件

4. 不更新

5. 语言模糊

6. 遗漏已知陷阱和变通方案

12.9 本章小结