Skip to Content

05b - CLAUDE.md 编写指南

本文是《AI Agent 实战手册》第 5 章第 2 节。 上一节：Claude Code 快速入门 | 下一节：Agentic Loop 与 Subagent

概述

CLAUDE.md 是 Claude Code 的”项目记忆”文件——每次启动会话时自动加载，为 AI 提供项目的技术栈、编码规范、工作流程和领域知识等持久化上下文。一份精心编写的 CLAUDE.md 能显著减少重复解释、提升代码生成质量、确保团队一致性。本节提供完整的结构模板、逐节编写最佳实践，以及 Web App、CLI 工具、Library 三种项目类型的实战注释示例。

1. CLAUDE.md 是什么，为什么重要

核心问题

LLM 是无状态的——每次新会话都是一张白纸。没有 CLAUDE.md，你需要在每次对话中重复解释项目背景、技术栈、编码规范。这不仅浪费 token，还容易导致 AI 生成不符合项目规范的代码。

CLAUDE.md 解决了这个问题：写一次，每次会话自动加载。

CLAUDE.md 的三个维度

编写 CLAUDE.md 时，围绕三个核心维度组织内容：

维度回答的问题包含内容
WHAT（是什么）这个项目用了什么技术？技术栈、项目结构、关键依赖、代码库地图
WHY（为什么）这个项目的目的是什么？项目目标、各模块职责、业务领域术语
HOW（怎么做）开发时应该怎么操作？构建命令、测试流程、编码规范、工作流程

工具推荐

工具用途价格适用场景
Claude Code /init自动生成初始 CLAUDE.md包含在 Claude Code 订阅中快速起步（需手动优化）
Claude Code /memory编辑和管理记忆文件包含在 Claude Code 订阅中日常维护 CLAUDE.md
Biome 代码格式化和 lint免费（开源）替代在 CLAUDE.md 中写样式规则
ESLint  + PrettierJS/TS 代码规范免费（开源）自动化代码风格检查
markdownlint Markdown 格式检查免费（开源）验证 CLAUDE.md 格式

2. 记忆层级体系

Claude Code 的记忆系统是分层的，理解这个层级对编写有效的 CLAUDE.md 至关重要。

记忆类型与优先级

从高到低排列（更具体的指令优先级更高）：

层级位置用途共享范围是否提交 Git
企业策略/Library/Application Support/ClaudeCode/CLAUDE.md（macOS）组织级强制规则组织内所有用户N/A（系统部署）
项目记忆./CLAUDE.md 或 ./.claude/CLAUDE.md团队共享的项目指令团队成员✅
项目规则./.claude/rules/*.md模块化、主题化的项目规则团队成员✅
用户记忆~/.claude/CLAUDE.md个人全局偏好仅自己❌
项目本地记忆./CLAUDE.local.md个人项目偏好仅自己❌（自动 gitignore）
自动记忆~/.claude/projects/<project>/memory/Claude 自动记录的学习笔记仅自己❌

加载机制

  • 启动时加载：Claude Code 从当前工作目录向上递归查找所有 CLAUDE.md 和 CLAUDE.local.md 文件
  • 按需加载：子目录中的 CLAUDE.md 在 Claude 读取该目录文件时才加载
  • 自动记忆：仅加载 MEMORY.md 的前 200 行，详细内容存放在主题文件中按需读取

文件导入语法

CLAUDE.md 支持用 @path/to/file 语法导入其他文件：

参考 @README.md 了解项目概况，查看 @package.json 获取可用命令。
 
# 额外指令
- Git 工作流参见 @docs/git-instructions.md

导入规则：

  • 支持相对路径和绝对路径，相对路径基于当前文件所在目录
  • 代码块和行内代码中的 @ 不会被解析为导入
  • 支持递归导入，最大深度 5 层

3. 完整结构模板

以下是经过实战验证的 CLAUDE.md 结构模板，涵盖所有关键节：

# 项目名称
 
## 项目概述
[1-2 句话说明项目目的和核心功能]
 
## 技术栈
- **语言**：[主要语言和版本]
- **框架**：[核心框架]
- **数据库**：[数据库类型]
- **关键依赖**：[重要的第三方库]
 
## 项目结构

src/ ├── [目录说明] ├── [目录说明] └── [目录说明]


## 常用命令
```bash
[包管理器] dev          # 启动开发服务器
[包管理器] build        # 生产构建
[包管理器] test         # 运行全部测试
[包管理器] test [文件]  # 运行单个测试文件
[包管理器] lint         # 代码检查

编码规范

  • [关键规范 1]
  • [关键规范 2]
  • [关键规范 3]

工作流程

[工作流名称]

  1. [步骤 1]
  2. [步骤 2]
  3. [步骤 3]

领域术语

  • [术语]：[定义]

提交前检查

  • 运行测试：[命令]
  • 类型检查：[命令]
  • 代码格式化：[命令]

文档索引

  • 相关工作参见 docs/x.md
  • [Y] 相关工作参见 docs/y.md

---

## 4. 逐节最佳实践

### 4.1 项目概述

**目标**：让 Claude 在 2-3 句话内理解项目的 WHY。

```markdown
## 项目概述
RunCover 是一个全栈 Web 应用，用户上传 GPX 运动轨迹文件后，
系统自动生成 Wrapped 风格的短视频摘要。

✅ 好的做法：

  • 说明项目类型（Web 应用、CLI 工具、库）
  • 说明核心功能和目标用户
  • 如果是 monorepo，说明各子项目的职责

❌ 避免：

  • 冗长的项目历史
  • 市场分析或商业计划

4.2 技术栈

目标：让 Claude 知道 WHAT——用了什么技术。

## 技术栈
- **后端**：.NET 10.0, ASP.NET Core Web API, EF Core 10.0, PostgreSQL 17
- **前端**：React 19, TypeScript 5.9, TanStack Router & Query, Tailwind CSS 4.1
- **构建**：Vite 7.2
- **测试**：Vitest, Playwright

✅ 好的做法：

  • 标注具体版本号（避免 Claude 使用过时 API）
  • 区分前端/后端/基础设施
  • 列出关键依赖，不需要列出所有依赖

❌ 避免：

  • 列出 package.json 中的每一个依赖
  • 不标版本号（Claude 可能使用旧版 API）

4.3 项目结构

目标：给 Claude 一张代码库地图，尤其对 monorepo 至关重要。

## 项目结构

api/src/ ├── RunCover.API/ # 控制器、中间件、入口点 ├── RunCover.Application/ # 服务接口、DTO、业务逻辑 ├── RunCover.Domain/ # 实体、值对象 └── RunCover.Infrastructure/ # EF Core、仓储、外部服务

✅ 好的做法：

  • 用树形结构展示关键目录
  • 每个目录加简短注释说明职责
  • 标注自动生成的文件（如 routeTree.gen.ts — 自动生成，勿手动编辑）

❌ 避免：

  • 列出每一个文件
  • 不加注释的纯目录树

4.4 常用命令

目标：告诉 Claude HOW——怎么构建、测试、运行项目。

## 常用命令
 
### 后端（在 api/ 目录下运行）
```bash
dotnet build src/RunCover.API --configuration Release  # 生产构建
dotnet test tests/RunCover.Domain.Tests                # 运行领域测试
dotnet run --project src/RunCover.API                  # 启动 API 服务

前端（在 web/ 目录下运行）

bun install        # 安装依赖（使用 bun，不要用 npm）
bun run dev        # 开发服务器 (localhost:5173)
bun run test       # 运行全部测试
bun run test file  # 运行单个测试文件

✅ 好的做法：
- 明确指定命令应在哪个目录下运行
- 标注特殊参数和标志（如 EF Core 迁移的项目路径参数）
- 说明包管理器偏好（"使用 bun，不要用 npm"）

❌ 避免：
- 只写 `npm test` 而不说明如何运行单个测试
- 遗漏需要特殊参数的命令

### 4.5 编码规范

**目标**：只写 Claude 容易犯错的关键规范，不要写 linter 能处理的规则。

```markdown
## 编码规范
- 优先写清晰的代码，少用行内注释
- C#：使用 primary constructor；XML 注释覆盖所有公开 API
- TypeScript：永远使用 async/await，不用 .then()
- 测试方法命名：`<方法名>_<条件>_<预期结果>`
- 提交信息：Conventional Commit 格式（feat:, fix:, docs:, refactor:）

✅ 好的做法：

  • 只写 2-5 条最关键的规范
  • 写 Claude 经常违反的规则
  • 代码风格交给 linter 和 formatter 处理

❌ 避免：

  • 把整个 style guide 复制进来
  • 写缩进、分号等 linter 能自动修复的规则
  • 超过 10 条编码规范（指令过多会降低遵循率）

4.6 工作流程

目标：定义 Claude 执行特定任务时应遵循的步骤。

## 工作流程
 
### 创建/修改 API 端点
1. 先规划变更方案（新增/修改的方法、路径、请求体）
2. 向用户确认方案后再实现
3. 实现端点代码
4. 更新 .http 文件中的端点文档
5. 运行 .http 文件测试端点

✅ 好的做法：

  • 针对 Claude 经常跳过步骤的场景编写工作流
  • 包含”确认后再实现”这类人工审查节点
  • 保持步骤简洁明确

4.7 领域术语

目标：消除业务领域的歧义。

## 领域术语
- **Wraps**：年度视频摘要的别称
- **Athlete**：系统中也称为 User
- **Pace**：跑步速度，始终使用 min/km 或 min/mile
- **Track**：GPX 文件中构成路线的 segment 集合

✅ 好的做法：

  • 定义 Claude 可能误解的业务术语
  • 说明术语与代码实体的映射关系
  • 如果你发现自己在 prompt 中反复解释某个词，就把它加到这里

4.8 文档索引（渐进式披露）

目标：避免把所有信息塞进 CLAUDE.md，用引用指向详细文档。

## 文档索引
- 构建/部署相关：参见 `agent_docs/building_the_project.md`
- 数据库相关：参见 `agent_docs/database_schema.md`
- 服务架构相关：参见 `agent_docs/service_architecture.md`
- API 安全规范：参见 `docs/api-security.md`

这种”渐进式披露”策略的好处：

  • Claude 只在需要时才加载详细文档，节省上下文窗口
  • 引用文件始终与代码同步更新，不会过时
  • CLAUDE.md 保持精简

5. 模块化规则：.claude/rules/

对于大型项目，可以将指令拆分到 .claude/rules/ 目录下的多个文件中：

.claude/rules/
├── code-style.md        # 代码风格
├── testing.md           # 测试规范
├── security.md          # 安全要求
├── frontend/
│   └── components.md    # 前端组件规范
└── backend/
│   └── api.md           # API 开发规范

路径限定规则

通过 YAML frontmatter 的 paths 字段，可以让规则只在处理特定文件时生效：

---
paths:
  - "src/api/**/*.ts"
---
 
# API 开发规则
 
- 所有 API 端点必须包含输入验证
- 使用标准错误响应格式
- 包含 OpenAPI 文档注释

支持的 glob 模式：

模式匹配
**/*.ts任意目录下的 TypeScript 文件
src/**/*src 目录下的所有文件
src/**/*.{ts,tsx}src 下的 .ts 和 .tsx 文件
{src,lib}/**/*.tssrc 和 lib 下的 .ts 文件

6. 编写原则与长度控制

核心原则

  1. 精简至上：Claude Code 的系统 prompt 已包含约 50 条指令，研究表明前沿 LLM 可靠遵循约 150-200 条指令。CLAUDE.md 越长，指令遵循率越低
  2. 普遍适用：每条指令都应在所有工作场景中适用。Claude 会忽略它认为不相关的指令
  3. 不做昂贵的 linter：代码风格交给 Biome/ESLint/Prettier 等工具，不要让 LLM 做模式匹配
  4. 用文件引用代替内联代码：内联代码片段会过时，文件引用始终是最新的
  5. 手动编写，不要自动生成：/init 生成的内容只是起点，必须手动审查和优化

长度指南

指标建议
最佳长度< 300 行
理想目标< 100 行
根级 CLAUDE.md尽可能精简，详细内容放到 rules/ 或外部文档

自检清单

  • 少于 300 行（理想情况下少于 100 行）
  • 每条指令都普遍适用于所有工作场景
  • 没有代码风格/lint 规则（交给工具处理）
  • 没有内联代码片段（使用文件引用）
  • 任务特定的文档放在单独文件中
  • 手动编写，不是自动生成的
  • 覆盖了 WHAT、WHY、HOW 三个维度

7. 提示词模板

从零创建 CLAUDE.md

请帮我为当前项目创建一个 CLAUDE.md 文件。要求：
1. 分析项目结构和技术栈
2. 按照 WHAT/WHY/HOW 三个维度组织
3. 包含：项目概述、技术栈、项目结构、常用命令、编码规范
4. 控制在 100 行以内
5. 不要包含 linter 能处理的代码风格规则

优化现有 CLAUDE.md

审查当前的 CLAUDE.md 文件，帮我优化：
1. 删除冗余和重复的指令
2. 将过长的内容拆分到 .claude/rules/ 下的独立文件
3. 确保每条指令都是普遍适用的
4. 用文件引用替代内联代码片段
5. 目标：精简到 100 行以内

为 monorepo 创建分层 CLAUDE.md

这是一个 monorepo 项目，请帮我设计 CLAUDE.md 的分层结构：
1. 根目录 CLAUDE.md：项目总览、共享规范
2. 各子项目目录的 CLAUDE.md：子项目特定的技术栈和命令
3. .claude/rules/ 下的模块化规则文件
4. 确保不同层级之间没有重复内容

实战案例 1：Web App 项目的 CLAUDE.md

以下是一个 Next.js 全栈 SaaS 应用的完整 CLAUDE.md 示例，附逐节注释：

# TaskFlow — 团队任务管理 SaaS
 
<!-- ✅ 项目概述：2 句话说清 WHY -->
## 项目概述
TaskFlow 是一个面向中小团队的任务管理 SaaS 应用，支持看板视图、
时间追踪和团队协作。前后端一体化部署在 Vercel 上。
 
<!-- ✅ 技术栈：标注具体版本，区分前后端 -->
## 技术栈
- **框架**：Next.js 15 (App Router), React 19, TypeScript 5.8
- **样式**：Tailwind CSS 4.0 + shadcn/ui
- **数据库**：PostgreSQL 16 + Prisma 6.2 ORM
- **认证**：NextAuth.js v5 (GitHub + Google OAuth)
- **部署**：Vercel (前端 + API Routes), Neon (Serverless PostgreSQL)
- **测试**：Vitest (单元), Playwright (E2E)
 
<!-- ✅ 项目结构：树形图 + 注释，标注自动生成文件 -->
## 项目结构

src/ ├── app/ # Next.js App Router 页面和 API Routes │ ├── (auth)/ # 认证相关页面（登录、注册） │ ├── (dashboard)/ # 登录后的仪表板页面 │ ├── api/ # API Routes（REST 端点） │ └── layout.tsx # 根布局 ├── components/ │ ├── ui/ # shadcn/ui 基础组件（勿手动修改） │ └── features/ # 业务功能组件 ├── lib/ │ ├── db.ts # Prisma 客户端实例 │ ├── auth.ts # NextAuth 配置 │ └── validations/ # Zod schema 定义 ├── hooks/ # 自定义 React Hooks └── types/ # 共享 TypeScript 类型定义

prisma/ ├── schema.prisma # 数据库 schema（单一来源） └── migrations/ # 自动生成的迁移文件（勿手动编辑）


<!-- ✅ 常用命令：标注运行目录和特殊参数 -->
## 常用命令
```bash
pnpm dev                          # 启动开发服务器 (localhost:3000)
pnpm build                        # 生产构建
pnpm test                         # 运行 Vitest 单元测试
pnpm test -- src/lib/utils.test.ts  # 运行单个测试文件
pnpm e2e                          # 运行 Playwright E2E 测试
pnpm lint                         # ESLint 检查
pnpm db:push                      # 推送 schema 变更到开发数据库
pnpm db:migrate -- --name <名称>  # 创建迁移文件
pnpm db:studio                    # 打开 Prisma Studio

编码规范

  • 使用 Server Components 作为默认，只在需要交互时使用 “use client”
  • 数据获取使用 Server Actions，不要在客户端组件中直接调用 Prisma
  • 所有表单输入必须用 Zod schema 验证（定义在 lib/validations/）
  • 错误处理使用自定义 AppError 类（定义在 lib/errors.ts）
  • 永远使用 async/await，不用 .then() 链

工作流

添加新功能

  1. 先规划方案：涉及哪些文件、需要哪些数据库变更
  2. 向用户确认方案
  3. 如需数据库变更，先更新 prisma/schema.prisma
  4. 实现功能代码
  5. 添加 Vitest 单元测试
  6. 运行 pnpm test 确认通过

领域术语

  • Workspace：团队的顶级容器，一个用户可属于多个 Workspace
  • Board：看板，属于某个 Workspace
  • Card：任务卡片，属于某个 Board 的某个 Column
  • Member：Workspace 成员，角色分为 owner / admin / member

提交前检查

  • 运行测试：pnpm test
  • 类型检查：pnpm tsc --noEmit
  • Lint：pnpm lint

### 案例分析

这个 CLAUDE.md 的关键设计决策：

1. **约 80 行**，控制在理想长度范围内
2. **Server Components 优先**的规范避免了 Claude 默认生成客户端组件的倾向
3. **Zod 验证**的强调确保 Claude 不会跳过输入验证
4. **工作流中的确认节点**防止 Claude 直接修改数据库 schema 而不经过审查
5. **领域术语**中 Workspace/Board/Card 的层级关系帮助 Claude 理解数据模型

---

## 实战案例 2：CLI 工具项目的 CLAUDE.md

以下是一个 Rust CLI 文件同步工具的 CLAUDE.md 示例：

```markdown
# rsync-ai — 智能文件同步 CLI 工具

## 项目概述
rsync-ai 是一个用 Rust 编写的跨平台文件同步 CLI 工具，
支持增量同步、冲突检测和 .gitignore 风格的排除规则。

## 技术栈
- **语言**：Rust 1.82 (edition 2024)
- **CLI 框架**：clap 4.5 (derive API)
- **异步运行时**：tokio 1.x
- **序列化**：serde + serde_json
- **文件监听**：notify 7.x
- **测试**：内置 #[test] + proptest (属性测试)

## 项目结构

src/ ├── main.rs # 入口点，CLI 参数解析 ├── lib.rs # 公开 API，模块声明 ├── sync_engine.rs # 核心同步逻辑 ├── diff.rs # 文件差异计算 ├── ignore_engine.rs # .gitignore 风格排除规则引擎 ├── transfer.rs # 文件传输调度 ├── config.rs # 配置文件解析 (TOML) └── types.rs # 共享类型定义

tests/ ├── integration/ # 集成测试（需要临时目录） └── fixtures/ # 测试用的示例文件和目录结构


## 常用命令
```bash
cargo build                        # 调试构建
cargo build --release              # 发布构建
cargo test                         # 运行全部测试
cargo test sync_engine             # 运行特定模块的测试
cargo test -- --nocapture          # 运行测试并显示 println 输出
cargo clippy -- -D warnings        # Lint 检查（视警告为错误）
cargo fmt --check                  # 检查格式化
cargo run -- --source ./a --dest ./b  # 本地运行

编码规范

  • 所有公开函数和类型必须有 /// 文档注释
  • 错误处理使用 thiserror 定义自定义错误类型，不要用 unwrap()
  • 优先使用 &str 和 &Path 作为函数参数（而非 String 和 PathBuf）
  • 集成测试使用 tempdir 创建临时目录，测试结束后自动清理

工作流

添加新 CLI 子命令

  1. 在 main.rs 的 Cli struct 中添加子命令定义（clap derive）
  2. 在对应模块中实现业务逻辑
  3. 添加单元测试和集成测试
  4. 更新 README.md 的命令文档
  5. 运行 cargo test 和 cargo clippy 确认通过

领域术语

  • Source：同步源目录
  • Dest：同步目标目录
  • Manifest：记录文件元数据（大小、修改时间、哈希）的 JSON 文件
  • Conflict：源和目标都有修改时的冲突状态

提交前检查

  • 测试：cargo test
  • Lint：cargo clippy -- -D warnings
  • 格式化：cargo fmt --check

### 案例分析

CLI 工具的 CLAUDE.md 特点：

1. **Rust 特有规范**：`unwrap()` 禁令、借用优先（`&str` 而非 `String`）是 Claude 在 Rust 项目中最常犯的错误
2. **测试命令详细**：Rust 的测试命令有多种变体（模块过滤、`--nocapture`），需要明确列出
3. **子命令工作流**：CLI 工具的核心扩展模式是添加子命令，定义清晰的步骤避免遗漏
4. **Manifest 术语**：这是项目特有的概念，不定义的话 Claude 可能误解

---

## 实战案例 3：Library 项目的 CLAUDE.md

以下是一个 TypeScript 工具库的 CLAUDE.md 示例：

```markdown
# @acme/validation — 通用数据验证库

## 项目概述
@acme/validation 是一个零依赖的 TypeScript 数据验证库，
提供类型安全的 schema 定义和运行时验证，支持 Tree-shaking。

## 技术栈
- **语言**：TypeScript 5.8 (严格模式)
- **构建**：tsup 8.x (ESM + CJS 双格式输出)
- **测试**：Vitest 3.x
- **文档**：TypeDoc 0.27
- **发布**：changesets

## 项目结构

src/ ├── index.ts # 公开 API 导出（所有公开 API 必须从这里导出） ├── schemas/ # 内置 schema 类型（string, number, object, array…） ├── validators/ # 验证逻辑实现 ├── errors/ # 自定义错误类型 ├── types.ts # 核心类型定义 └── utils/ # 内部工具函数（不导出）

常用命令

pnpm dev          # 监听模式构建
pnpm build        # 生产构建（ESM + CJS + 类型声明）
pnpm test         # 运行测试
pnpm test:cov     # 运行测试并生成覆盖率报告
pnpm typecheck    # 类型检查
pnpm docs         # 生成 API 文档
pnpm changeset    # 创建变更集（发布前必须）

编码规范

  • 零依赖原则：不引入任何运行时依赖，所有功能自行实现
  • 所有公开 API 必须从 src/index.ts 导出
  • 所有公开函数和类型必须有 TSDoc 注释，包含 @example
  • 泛型参数使用描述性名称（Schema, Input, Output），不用单字母（T, U）
  • 保持向后兼容：不删除或修改已发布的公开 API 签名

工作流

添加新 Schema 类型

  1. 在 src/schemas/ 下创建新文件
  2. 实现 schema 类和验证逻辑
  3. 在 src/index.ts 中导出
  4. 添加完整的单元测试（覆盖正常值、边界值、错误值）
  5. 添加 TSDoc 文档和 @example
  6. 运行 pnpm test 和 pnpm typecheck
  7. 运行 pnpm changeset 记录变更

发布新版本

  1. 确认所有 changeset 已创建
  2. 运行 pnpm changeset version 更新版本号
  3. 审查 CHANGELOG.md
  4. 提交并推送，CI 自动发布到 npm

提交前检查

  • 测试：pnpm test
  • 类型检查：pnpm typecheck
  • 构建：pnpm build（确保 ESM 和 CJS 都能正常构建）

### 案例分析

Library 项目的 CLAUDE.md 特点：

1. **零依赖原则**是最重要的约束——不写明的话，Claude 很可能引入 lodash 等依赖
2. **公开 API 管理**：所有导出必须经过 index.ts，这是库项目的核心架构约束
3. **向后兼容**：库项目不能随意修改已发布的 API，这条规则防止 Claude 做破坏性变更
4. **changeset 工作流**：库的发布流程比应用复杂，需要明确步骤
5. **TSDoc 要求**：库的文档质量直接影响用户体验，要求 `@example` 确保文档实用

---

## 避坑指南

### ❌ 常见错误

1. **把 CLAUDE.md 当成完整文档来写**
   - 问题：超过 300 行的 CLAUDE.md 会显著降低指令遵循率，浪费上下文窗口
   - 正确做法：根级 CLAUDE.md 控制在 100 行以内，详细内容放到 `.claude/rules/` 或外部文档

2. **用 `/init` 生成后不做修改**
   - 问题：自动生成的内容往往过于泛化，缺少团队特有的规范和工作流
   - 正确做法：`/init` 只是起点，必须手动审查、删减冗余、补充关键规范

3. **在 CLAUDE.md 中写代码风格规则**
   - 问题：缩进、分号、引号等规则让 LLM 做昂贵的模式匹配，且效果不如 linter
   - 正确做法：使用 Biome/ESLint/Prettier 等工具自动处理，配合 Claude Code Hooks 在编辑后自动运行

4. **内联大段代码示例**
   - 问题：代码示例会过时，且占用大量上下文空间
   - 正确做法：使用 `@path/to/file` 引用实际代码文件，或用 `file:line` 格式指向具体位置

5. **不区分共享和个人配置**
   - 问题：把个人偏好（如本地数据库 URL、IDE 设置）写进提交到 Git 的 CLAUDE.md
   - 正确做法：个人配置放在 `CLAUDE.local.md`（自动 gitignore），团队规范放在 `CLAUDE.md`

6. **忽略 monorepo 的分层需求**
   - 问题：在 monorepo 根目录写一个巨大的 CLAUDE.md，包含所有子项目的信息
   - 正确做法：根目录放共享规范，每个子项目目录放各自的 CLAUDE.md，利用层级加载机制

### ✅ 最佳实践

1. 把 CLAUDE.md 当作"活文档"——每次发现 Claude 犯错，就更新对应的指令
2. 提交到 Git 版本控制，让团队成员共同维护和审查
3. 使用渐进式披露：CLAUDE.md 只放索引，详细内容放在独立文档中
4. 定期审查和精简：删除不再适用的指令，合并重复内容
5. 不要在 CLAUDE.md 中包含密钥、连接字符串等敏感信息
6. 利用 `.claude/rules/` 的路径限定功能，让规则只在相关文件上生效

---

## 相关资源与延伸阅读

### 模板与示例

- [Awesome CLAUDE.md — GitHub](https://github.com/hesreallyhim/awesome-claude-code) — 社区收集的 CLAUDE.md 文件示例和最佳实践
- [The CLAUDE.md Workflow Guide — ChronoInnovation](https://www.chronoinnovation.com/resources/claude-md-workflow-guide) — CLAUDE.md 工作流的详细指南
- [CLAUDE.md for .NET Developers — CodeWithMukesh](https://codewithmukesh.com/blog/claude-md-mastery-dotnet/) — .NET 项目的 CLAUDE.md 编写实战

### 工具

- [Claude Code Rules — paddo.dev](https://paddo.dev/blog/claude-rules-path-specific-native/) — 路径特定规则的使用技巧，按文件类型加载不同规则
- [Repomix](https://github.com/yamadashy/repomix) — 将代码仓库打包为 AI 友好格式，辅助编写 CLAUDE.md 中的项目描述

### 学习资源

- [The Claude Developer Playbook — ywian](https://www.ywian.com/blog/the-claude-developer-playbook) — 以 CLAUDE.md 为核心的 Claude 开发者实战手册
- [AI-Ready Codebase Guide — LLMX](https://llmx.de/blog/ai-ready-codebase-claude-cursor-integration-guide/) — 让代码库对 AI Agent 友好的完整指南

### 社区

- [r/ClaudeAI](https://www.reddit.com/r/ClaudeAI/) — Claude 用户社区，经常有 CLAUDE.md 编写经验和模板分享
- [Book of Kiro — Steering](https://kiro-community.github.io/book-of-kiro/en/features/steering/) — Kiro 社区的 Steering 文件指南，与 CLAUDE.md 理念相通

---

## 参考来源

- [Manage Claude's Memory — Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/memory)（持续更新）
- [Creating the Perfect CLAUDE.md for Claude Code — Dometrain](https://dometrain.com/blog/creating-the-perfect-claudemd-for-claude-code/)（2026-01）
- [Writing a Good CLAUDE.md — Understanding Data](https://understandingdata.com/posts/writing-a-good-claude-md/)（2026-01）
- [Writing a Good CLAUDE.md — HumanLayer](https://www.humanlayer.dev/blog/writing-a-good-claude-md)（2025-11）
- [The Ultimate Guide to CLAUDE.md in 2026 — BuildCamp](https://www.buildcamp.io/guides/the-ultimate-guide-to-claudemd)（2026-06）
- [Claude Code Best Practices — Anthropic](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/best-practices)（持续更新）
- [CLAUDE.md, Subagents, MCP & Skills: The AI Coding Stack — Saurav.io](https://blog.saurav.io/ai-coding-stack-explained/)（2026-01）
- [Claude Code for Legacy Codebases — Richard Porter](https://richardporter.dev/blog/claude-code-legacy-codebase-practitioners-guide)（2026-01）

---

> 📖 返回 [总览与导航](../00-总览与导航.md) | 上一节：[Claude Code 快速入门](./05a-Claude-Code快速入门.md) | 下一节：[Agentic Loop 与 Subagent](./05c-Agentic-Loop与Subagent.md)
Last updated on
从 Copilot 到 Agent