04 — CLAUDE.md 入门：给 AI 写一份“员工手册“

本节目标

完成本节后，你将能够：

1. 准确解释 CLAUDE.md 是什么以及它为什么是最重要的配置文件

2. 理解 CLAUDE.md 的三层加载优先级体系

3. 使用/init自动生成并手动精炼 CLAUDE.md

4. 编写一份包含 5 个核心模块的高质量 CLAUDE.md

5. 严格遵守 150 行预算规则，写出精炼高效的项目规则

核心知识点

CLAUDE.md 到底是什么

CLAUDE.md 是 Claude Code 的项目级配置文件。你可以把它理解为：

一份给 AI 工程师的"员工手册"

就像一个新入职的工程师需要了解公司的代码规范、项目结构、构建命令和禁止操作一样，Claude Code 在每次启动时都会自动读取 CLAUDE.md，让它的行为符合你的预期。

它使用 Markdown 格式，放在项目的根目录（或其他关键目录）。Claude Code 会在每个会话开始时自动加载它。

什么时候必须有 CLAUDE.md？

CLAUDE.md 不是必须的——没有它 Claude Code 也能工作。但在以下场景中，它会从"可有可无"变成"必不可少"：

• 你的项目使用了特定的代码风格（比如所有函数必须加 JSDoc 注释）

• 你的项目有非标准的构建或测试命令

• 你希望 Claude Code 遵循特定的命名规范

• 你有一些绝对不能被修改的文件或目录

• 你的项目使用 monorepo 结构，不同子目录有不同规则

• 你希望团队中所有成员的 Claude Code 行为一致

三层加载优先级体系

Claude Code 按以下顺序加载 CLAUDE.md 文件，后面的会覆盖前面的：

1. 全局配置： ~/.claude/CLAUDE.md （你个人的全局偏好） 2. 项目根目录： ./CLAUDE.md （项目级通用规则） 3. 子目录配置： ./subdir/CLAUDE.md （目录级特定规则）

实际例子：

~/.claude/CLAUDE.md → "总是使用中文回复"（个人全局偏好） ​ ~/project/CLAUDE.md → "这个项目使用 ESLint + Prettier，禁止用 var"（项目规则） ​ ~/project/src/api/CLAUDE.md → "API 层所有函数必须添加 try-catch，返回统一格式 {success, data, error}"（目录特定规则）

当你让 Claude Code 修改~/project/src/api/user.ts时，它会同时遵守三层规则：用中文回复、不用 var、加上 try-catch 和统一返回格式。

什么是/init自动生成

Claude Code 提供了/init命令，它会自动分析你的项目结构，然后生成一份 CLAUDE.md 草稿。

自动生成的内容通常包括：

• 项目的技术栈（识别的语言、框架、构建工具）

• 目录结构概览

• 常见的构建和测试命令

• 基本的代码风格建议

但这只是起点。自动生成的内容往往是"通用的"而不是"你的项目的"。真正的价值在于你对这份草稿的精炼。

一份高质量 CLAUDE.md 的五个核心模块

经过大量实践验证，一份有效的 CLAUDE.md 应该包含以下内容：

模块 1：构建与运行命令

## 构建与命令 - 开发服务器: `npm run dev` - 构建生产版本: `npm run build` - 运行所有测试: `npm test` - 运行单个测试: `npm test -- -t "test name"` - 类型检查: `npm run typecheck`

模块 2：代码风格约定

## 代码风格 - 使用 TypeScript 严格模式，禁止使用 `any` - 函数命名使用 camelCase，React 组件使用 PascalCase - 所有公共 API 函数必须包含 JSDoc 注释 - 优先使用 const 和箭头函数 - 文件最长 400 行，超出则拆分

模块 3：项目架构约定

## 架构约定 - src/components/ — UI 组件，每个组件一个目录 - src/hooks/ — 自定义 React Hooks - src/utils/ — 纯函数工具，无副作用 - src/api/ — API 调用层，统一错误处理格式 - 组件不直接调用 API，必须通过 hooks 层

模块 4：禁止操作清单

## 禁止操作 - 不要修改 package-lock.json 或 yarn.lock - 不要删除任何 .test.ts 文件 - 不要在没有讨论的情况下修改数据库 schema - 不要引入超过 50KB（gzip）的新依赖 - 不要修改 .github/workflows/ 下的 CI 配置

模块 5：语言和交互偏好

## 交互偏好 - 使用中文回复所有消息 - 在修改文件前先解释将要做什么 - 遇到不确定的情况时，先提问而不是猜测 - 修改超过 30 行时，提供修改摘要

150 行预算规则——最重要的纪律

Claude Code 会把 CLAUDE.md 的全文加载到每个会话的上下文中。上下文窗口是有限且昂贵的资源。因此有一条黄金法则：

CLAUDE.md 的总长度不应超过 150 行（约 2000-3000 字符）

为什么是 150 行？

• 上下文窗口约 200K token（Sonnet 4），CLAUDE.md 消耗约 1000-2000 token

• 这意味着 CLAUDE.md 只占约 1% 的上下文预算——合理

• 如果 CLAUDE.md 长达 500 行（约 5000 token），它占了约 2.5%——开始不划算

• 超过 1000 行（约 10000 token），它占 5%——严重浪费

精简技巧：

• 写"做什么"和"不做什么"，不要写"为什么"

• 用列表和短句，不要用段落体

• 重复的内容合并到一处

• 每季度审视一次，删除过时内容

实操步骤

步骤 1：在一个项目中生成你的第一份 CLAUDE.md

找一个小项目目录，或使用上一节创建的 playground：

cd ~/claude-playground claude

在交互模式中输入：

/init

观察 Claude Code 的行为：

1. 它会扫描项目文件结构

2. 读取 package.json 等配置文件

3. 生成一份 CLAUDE.md 草稿

4. 展示给你预览

5. 你确认后写入文件

步骤 2：阅读并评审自动生成的内容

cat CLAUDE.md

用批判的眼光审视每一条内容：

• 哪些描述是准确的？留用。

• 哪些是自动生成的不相关内容？删除。

• 哪些是你的项目特有的规则但没被生成出来？补充。

步骤 3：手动精炼 CLAUDE.md

以下是一个实战示例。假设你的项目是一个 React + TypeScript 的前端应用，使用 Vite 构建：

# MyApp 项目规范 ​ ## 命令 - 开发: `npm run dev` (端口 3000) - 构建: `npm run build` (输出到 dist/) - 测试: `npm test` (Vitest) - 类型检查: `npm run typecheck` ​ ## 技术栈 - React 19 + TypeScript 5.x 严格模式 - Vite 6.x 构建 - Tailwind CSS 4.x 样式 - Vitest 测试 - React Router 7 路由 ​ ## 代码风格 - 文件名: 组件用 PascalCase, 工具用 camelCase - 禁止 any 类型, 禁止 console.log (debug 用 debug 包) - 所有组件导出必须有 displayName - 组件 props 用 interface 而非 type - CSS 只用 Tailwind 类名, 不写自定义 CSS ​ ## 架构 - src/components/ — 通用 UI 组件 - src/features/ — 按功能组织的页面和业务逻辑 - src/hooks/ — 自定义 hooks - src/api/ — API 调用, 统一用 fetcher.ts 封装 - 组件不和 API 直连, 通过 hooks 层 ​ ## 禁止 - 不要引入新的状态管理库 (已选用 Zustand) - 不要修改 vite.config.ts 的核心配置 - 不要删除任何 .test.ts 文件 - 不要添加超过 30KB 的新依赖 ​ ## 交互 - 用中文回复 - 修改前先说明意图

步骤 4：验证 CLAUDE.md 是否生效

清空会话后重新启动 Claude Code：

claude

现在提一个问题来验证规则是否被遵守：

帮我添加一个新的工具函数

观察 Claude Code 是否：

• 用中文回复 ✓

• 把文件放在 src/utils/ 下 ✓

• 使用了 camelCase 命名 ✓

• 没有用any类型 ✓

步骤 5：创建多层 CLAUDE.md（进阶）

# 创建子目录的 CLAUDE.md mkdir -p src/api

在src/api/CLAUDE.md中写入：

# API 层规则 ​ ## 强制要求 - 所有 API 函数必须返回 {success: boolean, data?: T, error?: string} 格式 - 每个 API 函数必须有 try-catch - 使用 src/api/fetcher.ts 发起请求, 不要直接调用 fetch - API 函数命名: getXxx, createXxx, updateXxx, deleteXxx

然后在交互模式中测试：

在 src/api/ 下创建一个获取用户列表的函数

验证它是否遵循了子目录的特定规则。

避坑指南

坑 1：把 CLAUDE.md 写成了项目文档

错误：在 CLAUDE.md 里长篇大论地解释项目背景、业务逻辑、历史决策。

CLAUDE.md 是"操作手册"，不是"百科全书"。你不需要告诉 AI 为什么当初选了 React 而不是 Vue——你只需要告诉它在使用 React 时需要遵守什么规范。

坑 2：规则太模糊，无法验证

错误示例："写出高质量的代码"正确示例："每个函数不超过 40 行，圈复杂度不超过 5，嵌套不超过 3 层"

模糊的规则等于没有规则。每一条规则都应该是可验证的——你能明确判断"这条遵守了"还是"这条被违反了"。

坑 3：禁止清单没有具体文件路径

错误示例："不要修改配置文件"正确示例："不要修改 vite.config.ts、tsconfig.json、.eslintrc.js"

不给具体文件路径，AI 只能猜测，而猜测往往是错误的。

坑 4：CLAUDE.md 超过 200 行

超过 200 行的 CLAUDE.md 说明你在把"代码规范"和"项目文档"混在了一起。代码规范放 CLAUDE.md，项目文档放 README.md 或 Wiki。定期审查 CLAUDE.md，每次会话后如果发现有不常用的规则，删除它。

坑 5：团队成员各自修改 CLAUDE.md，导致冲突

如果你的团队都使用 Claude Code，CLAUDE.md 应该纳入版本控制，通过 PR 流程来修改。每个人可以有自己的~/.claude/CLAUDE.md来设置个人偏好，但项目级的 CLAUDE.md 必须经过团队共识。

课后作业

1. 创建：在你最常用的项目中使用/init生成 CLAUDE.md，然后手动精炼到 150 行以内。

2. 测试：精炼前后各让 Claude Code 完成一个同样的小任务（如"创建一个新的工具函数"），对比输出质量差异。记录你的观察。

3. 审查：检查你的 CLAUDE.md，确认每条规则都是"可验证的"。对于模糊的规则，重写成具体可验证的形式。

4. 实验：在子目录中创建一个 CLAUDE.md，加入一条与根目录不同的规则。然后让 Claude Code 在该子目录下完成任务，验证子目录规则是否覆盖了根目录规则。

总结

CLAUDE.md 是 Claude Code 系统中最重要的文件，没有之一。它决定了 AI 在你项目中的行为边界和质量标准。记住三个核心原则：

1. 精炼胜于全面：150 行的好规则远胜 500 行的泛泛之谈

2. 可验证胜于抽象：每一条规则都必须是可以明确判断遵守与否的

3. 层级治理：全局偏好放~/.claude/CLAUDE.md，项目规范放项目根目录，目录特定规则放子目录

把 CLAUDE.md 想象成你给 AI 工程师写的"入职第一天该知道的所有事情"——如果一件事不那么重要，就不要写进去。每一条冗余的规则都在消耗宝贵的上下文窗口。