手写一个 CLAUDE.md——从空白到最佳实践

手写一个 CLAUDE.md——从空白到最佳实践

上篇我们聊了 CLAUDE.md 的概念——它是给 AI 看的项目手册，告诉 AI 你的项目怎么跑、有什么约定。

但概念归概念，真让你写，你可能还是不知道从哪里下笔。

这篇我们用一个真实的前端项目为例，从空白开始，一步步写出一份高质量的 CLAUDE.md。

2.1 先认识我们的"项目"

假设你有一个电商后台管理系统，技术栈是：

框架：React 18 + Next.js 14 (App Router) 语言：TypeScript (strict mode) 样式：Tailwind CSS 状态管理：Zustand API 请求：React Query + axios 测试：Vitest + Testing Library 包管理：pnpm 目录：src/ 下的标准 Next.js 结构

这是一个很常见的项目结构。没有 CLAUDE.md 的时候，你让 Claude “帮我加一个用户列表页面”，它生成的代码可能用的是 class component、CSS 文件放在 styles/ 下、API 请求直接写在组件里——完全不匹配你的项目风格。

每次你都得纠正它：“我们用函数组件”“API 放 services/ 下”“不要用 CSS 文件，用 Tailwind”。

有了 CLAUDE.md，这些只需要写一次。

2.2 第一步：项目概览

先把项目的基本信息告诉 AI。不用长篇大论，几句话说清楚就行。

# 电商后台管理系统 面向公司内部运营团队的后台系统，管理订单、商品、用户和数据报表。

为什么要写"面向公司内部"？因为 AI 可能会默认这是一个公开产品，考虑 SEO、SSR、性能优化——这些都是不必要的。让 AI 知道使用场景，它的建议会更对路。

2.3 第二步：技术栈

技术栈是 CLAUDE.md 最重要的部分之一。写清楚 AI 就不会推荐错误的技术方案。

## 技术栈 ### 核心 - React 18 + Next.js 14 (App Router) - TypeScript（strict mode，eslint 配置在项目根目录） - Tailwind CSS ### 状态与数据 - Zustand（全局状态） - React Query v5（服务端状态和缓存） - axios（HTTP 客户端） - zod（运行时类型校验） ### 测试 - Vitest + React Testing Library - Playwright（E2E 测试） ### 工具 - pnpm（包管理，禁止使用 npm 或 yarn） - ESLint + Prettier - husky + lint-staged

这里有一个细节：版本号。React Query v4 和 v5 的 API 差别很大，写清楚版本号，AI 生成的代码就不会用错 API。

还有一个更重要的细节：禁止事项。“禁止使用 npm 或 yarn”——如果你不写这一句，AI 可能哪天就给你跑了个npm install，把你的pnpm-lock.yaml搞乱。

2.4 第三步：开发命令

把日常命令都列出来，AI 就不用猜了。特别是那些不常用的命令——AI 记不住pnpm vitest --coverage，但你写在 CLAUDE.md 里它就知道了。

## 开发命令 # 安装 pnpm install # 安装依赖（新增依赖也要用 pnpm add） pnpm update # 更新依赖 # 开发 pnpm dev # 启动开发服务器 → http://localhost:3000 pnpm build # 生产构建 pnpm start # 启动生产服务器 # 代码质量 pnpm lint # ESLint 检查 pnpm lint:fix # ESLint 自动修复 pnpm type-check # TypeScript 类型检查 pnpm format # Prettier 格式化 # 测试 pnpm test # 运行单元测试 pnpm test:watch # 监听模式 pnpm test:coverage # 覆盖率报告 pnpm test:e2e # E2E 测试 # 数据库 pnpm db:migrate # 运行数据库迁移 pnpm db:seed # 填充测试数据

你可能会觉得"这些太基础了，AI 应该知道"。但真实情况是：AI 经常猜错命令。它可能猜npm start但实际上项目用的是pnpm dev。也可能会漏掉type-check这个重要步骤。

每一条命令都是给 AI 省一次猜测。

2.5 第四步：编码规范

这是最有价值的部分，也是拉开差距的地方。

## 编码规范 ### 组件 - 使用函数组件 + Hooks，禁止使用 class 组件 - 组件文件使用 PascalCase（UserProfile.tsx） - 非组件文件使用 kebab-case（user-api.ts） - 每个组件一个文件 - 页面组件放在 app/ 目录下，业务组件放在 components/ 下 ### TypeScript - 启用 strict mode - 禁止使用 any，优先使用 unknown - API 请求和响应的类型定义在 types/api.ts - 共享类型定义在 types/ 目录下 ### 样式 - 使用 Tailwind CSS 类名，禁止编写自定义 CSS 文件 - 复杂的样式使用 @apply 指令提取到组件同级文件中 - 颜色使用 Tailwind 的预设色板，不要使用十六进制颜色 ### API 请求 - 所有 API 请求放在 services/ 目录下 - 每个模块一个文件（services/user.ts、services/order.ts） - 使用 React Query 的 useQuery / useMutation - query key 统一管理在 lib/query-keys.ts ### 状态管理 - 全局状态用 Zustand（stores/ 目录） - 服务端状态用 React Query - 组件内状态用 useState / useReducer - URL 参数用 useSearchParams ### Git - 使用 Conventional Commits 格式 - 分支命名：feature/xxx、fix/xxx、chore/xxx - PR 标题格式：<type>(<scope>): <description>

看到区别了吗？这些不是通用的 JavaScript 规范，而是你的项目的专属规范。

有些是常识（“使用函数组件”），但更多的是只有你的团队才知道的约定（“query key 统一管理在 lib/query-keys.ts”“禁止使用十六进制颜色”）。

这些约定新人来了要学一两周，写在 CLAUDE.md 里，AI 一遍就学会了。

2.6 第五步：目录结构

告诉 AI 代码放在什么地方，它就不会把组件乱放了。

## 目录结构 src/ ├── app/ # Next.js App Router │ ├── layout.tsx # 根布局 │ ├── page.tsx # 首页/登录页 │ ├── dashboard/ # 仪表盘页面 │ ├── orders/ # 订单管理 │ ├── products/ # 商品管理 │ └── users/ # 用户管理 ├── components/ # 共享组件 │ ├── ui/ # 基础 UI 组件（Button、Modal、Table 等） │ ├── layout/ # 布局组件（Sidebar、Header 等） │ └── shared/ # 业务共享组件 ├── services/ # API 请求 │ ├── http.ts # axios 实例和拦截器 │ ├── user.ts # 用户相关 API │ ├── order.ts # 订单相关 API │ └── product.ts # 商品相关 API ├── stores/ # Zustand stores ├── types/ # TypeScript 类型定义 ├── lib/ # 工具函数和配置 │ ├── query-keys.ts # React Query key 管理 │ └── utils.ts # 通用工具函数 ├── hooks/ # 自定义 Hooks └── styles/ # 全局样式（Tailwind 配置）

目录结构写清楚之后，你让 Claude “在订单管理页面加一个搜索功能”，它会直接去src/app/orders/下找对应的文件，而不是在pages/或者containers/下面新建文件。

2.7 第六步：边界与约束

这一步很多人会忽略，但它往往是 CLAUDE.md 里最有价值的部分。

## 重要的约束 1. 不要修改 src/lib/ 下的文件，除非有明确说明 2. lib/utils.ts 中的工具函数必须有单元测试覆盖 3. 数据库 schema 的修改必须同时更新 types/ 下的类型定义 4. 不要引入新的 npm 包，除非经过技术评审 5. API 接口的字段命名使用 snake_case，前端代码使用 camelCase 6. 所有新增文件必须包含 TypeScript 类型定义

约束告诉 AI什么不能做，这比告诉它能做什么更能避免问题。

2.8 完整的 CLAUDE.md

把前面六步拼起来，就是一份高质量的 CLAUDE.md：

# 电商后台管理系统 面向公司内部运营团队的后台系统，管理订单、商品、用户和数据报表。 ## 技术栈 ### 核心 - React 18 + Next.js 14 (App Router) - TypeScript（strict mode） - Tailwind CSS ### 状态与数据 - Zustand（全局状态） - React Query v5（服务端状态） - axios（HTTP 客户端） - zod（运行时类型校验） ### 工具 - pnpm（包管理，禁止使用 npm 或 yarn） - Vitest + React Testing Library - Playwright（E2E 测试） - ESLint + Prettier + husky ## 开发命令 - pnpm dev — 启动开发（端口 3000） - pnpm build — 生产构建 - pnpm test — 运行单元测试 - pnpm test:e2e — E2E 测试 - pnpm lint — ESLint 检查 - pnpm type-check — 类型检查 ## 编码规范 - 函数组件 + Hooks，禁止 class 组件 - 文件命名：组件 PascalCase，其他 kebab-case - 禁止使用 any，优先 unknown - 使用 Tailwind，禁止自定义 CSS 文件 - API 请求放 services/，React Query key 管理在 lib/query-keys.ts - 全局状态用 Zustand，服务端状态用 React Query ## 目录结构 src/ ├── app/ # 页面（App Router） ├── components/ # 共享组件 ├── services/ # API 请求 ├── stores/ # Zustand stores ├── types/ # 类型定义 ├── lib/ # 工具函数 ├── hooks/ # 自定义 Hooks └── styles/ # 全局样式 ## 约束 - 不要直接修改 lib/ 下的文件 - 新增依赖需经评审 - API 字段 snake_case，前端代码 camelCase - 所有新增文件必须有类型定义

这份 CLAUDE.md 大概 500 字。占用上下文不多，但它能让 AI 生成的代码从一开始就符合你的项目标准。

2.9 这些内容分别放在哪个层级？

你可能注意到了，前面的六步都是在"项目级 CLAUDE.md"的视角下写的。但根据第 1 篇，CLAUDE.md 有三个层级。那六步的内容是不是都应该放项目级？

不是。区分清楚什么放哪，才能发挥分层管理的优势。

放用户级（~/.claude/CLAUDE.md）

跟个人习惯相关、跟项目无关的内容。

# 我的个人偏好 - 代码使用双引号 - 注释用中文写 - Git commit 使用英文写 - 默认用 pnpm，没有再用 npm

什么时候用：你有自己的一套写法习惯，但不想强迫整个团队。比如团队规范用单引号，但你个人偏好双引号——放用户级，你自己的项目生效，不影响团队。

放项目级（项目根目录/CLAUDE.md）

跟具体项目绑定的、所有团队成员都应该遵守的内容。

这些都应该放项目级。因为它们是项目本身的属性，不随人变。

放子目录级（子目录/CLAUDE.md）

项目内特定模块或子包专用的信息。

比如你的项目根目录的 CLAUDE.md 已经写了通用规范，但apps/admin/目录下的后台管理有额外的规范：

# apps/admin/CLAUDE.md 本目录是后台管理系统，跟前台应用不同： - 使用 Ant Design 组件库（前台用 Tailwind） - 所有页面都需要权限校验 - API 路径前缀是 /api/admin/ - 不需要考虑 SEO

什么时候用：monorepo 中的子包、大型项目中某个有特殊规范的模块。

一张表看懂

一个反例

有人把个人偏好写进项目级的 CLAUDE.md：

# 项目 CLAUDE.md ## 技术栈 - React 18 - TypeScript ## 编码规范 - 使用双引号（注：这是张三的个人偏好，其他人可以不遵守）

这就违背了 CLAUDE.md 的初衷——项目级应该写"项目规范"而不是"个人偏好"。如果张三离职了，这条注释要不要删？如果李四也用这个项目，她看到"可以不遵守"会不会困惑？

正确的做法：张三把"使用双引号"放自己的用户级 CLAUDE.md，项目级只写团队统一认可的规范。

2.10 写完怎么测试？

CLAUDE.md 写完了，怎么知道它有没有效果？

几个简单的测试方法：

测试 1：问项目信息

这个项目用什么技术栈？ 怎么启动？ 测试怎么跑？

AI 应该能直接从 CLAUDE.md 中找到答案，而不是猜测。

测试 2：让它生成代码

帮我新建一个用户管理页面，列出所有用户

生成的代码应该：

• 文件放在src/app/users/下
• 使用函数组件
• API 请求写在services/user.ts中
• 使用 React Query 管理请求状态
• 用 Tailwind 样式

如果生成的代码在这些方面有偏差，说明 CLAUDE.md 还需要补充或调整。

测试 3：检查约束

帮我安装 react-select

AI 应该提醒你"这个项目需要经过技术评审才能引入新依赖"——因为 CLAUDE.md 里写了约束。

2.10 小结

写一份好的 CLAUDE.md 只需要六步：

1. 项目概览：这个项目是干什么的
2. 技术栈：用什么技术、什么版本、什么禁止用
3. 开发命令：所有常用命令，包括不常用的
4. 编码规范：你们团队独有的约定（最有价值的部分）
5. 目录结构：代码放在哪
6. 约束：什么不能做

但写在哪同样重要：

• 项目规范（技术栈、命令、编码规范）→项目级
• 模块特有规范（子项目特殊规则）→子目录级
• 个人偏好（代码风格、语言习惯）→用户级 ~/.claude/CLAUDE.md

每部分放对层级，个人偏好不干扰项目规范，项目规范不被个人偏好覆盖。

CLAUDE.md 的价值在于——你写一次，AI 每次都用。不像你口头交代，说完了 AI 可能转头就忘。

上一篇：CLAUDE.md 是什么？——AI 协作的"项目手册"