Day 3 CLAUDE.md：给 AI 立规矩的艺术

guozi

Claude Code 从入门到脱发 · Day 3

用了两天 Claude Code，你大概已经发现：这东西确实能干活，但有时候像个刚入职的实习生——干劲十足，但完全不了解团队规矩。

你说"帮我加个接口"，它用了 axios，但你们团队统一用 fetch。你说"写个组件"，它加了一堆注释，但你们的风格是代码即文档，不写注释。你说"提交代码"，它写了个英文 commit message，但你们要求用中文。

每次都要纠正，累不累？

这就是 CLAUDE.md 要解决的问题——一次配置，永久生效。把你的规矩写进文件，Claude Code 每次启动都会读取，然后自动遵守。

本文你将学到：

CLAUDE.md 是什么，放在哪里

应该写什么、不应该写什么

多层级配置的妙用

从零写一个实用的 CLAUDE.md

阅读时间：8 分钟 | 实操时间：15 分钟 | 难度：入门

━━━━━━━━━━━━━━━━━━━━

CLAUDE.md 是什么

CLAUDE.md 就是一个 Markdown 文件，放在项目根目录下。Claude Code 每次启动时会自动读取它，把里面的内容当作"项目规范"来遵守。

你可以把它理解为给 AI 的"员工手册"。新员工入职第一天看公司制度，Claude Code 启动第一件事读 CLAUDE.md。

━━━━━━━━━━━━━━━━━━━━

放在哪里

Claude Code 会从多个位置加载规则文件，优先级从低到高：

1. ~/.claude/CLAUDE.md              # 全局配置（所有项目生效）
2. 项目根目录/CLAUDE.md              # 项目配置
3. 项目根目录/.claude/CLAUDE.md      # 项目配置（.claude 目录下）
4. 项目根目录/.claude/rules/*.md     # 分主题的规则文件
5. 子目录/CLAUDE.md                  # 子目录配置（进入该目录时生效）

复制代码

规则是：越靠近你当前工作目录的文件，优先级越高。子目录的配置会覆盖父目录的。

对于个人开发者，最常用的是在项目根目录放一个

1. CLAUDE.md

复制代码

。对于大项目或 monorepo，用

1. .claude/rules/

复制代码

目录按主题拆分更清晰。

━━━━━━━━━━━━━━━━━━━━

应该写什么

好的 CLAUDE.md 包含四类信息：

1. 项目基本信息

1. ## 项目概述
2. 这是一个基于 Next.js 14 的博客系统，使用 TypeScript + Tailwind CSS。
4. ## 常用命令
5. - 开发：npm run dev
6. - 构建：npm run build
7. - 测试：npm test
8. - Lint：npm run lint

复制代码

这些信息看起来简单，但对 Claude Code 很重要。它知道跑测试该用

1. npm test

复制代码

还是

1. pnpm test

复制代码

，知道项目用的是 Next.js 还是 Nuxt。

2. 代码风格规范

1. ## 代码风格
2. - 使用函数式组件，不使用 class 组件
3. - 状态管理使用 Zustand，不使用 Redux
4. - 接口请求使用 fetch，不使用 axios
5. - 文件命名使用 kebab-case（如 user-service.ts）
6. - 组件命名使用 PascalCase（如 UserProfile.tsx）
7. - commit message 使用中文，格式为：类型(范围): 描述

复制代码

3. 项目架构约定

1. ## 目录规范
2. - src/components/ 放可复用的 UI 组件
3. - src/features/ 放业务功能模块
4. - src/lib/ 放工具函数和第三方库封装
5. - src/types/ 放 TypeScript 类型定义
7. ## 数据库
8. - ORM 使用 Prisma
9. - 数据库是 PostgreSQL
10. - 迁移文件在 prisma/migrations/

复制代码

4. 禁止事项

1. ## 禁止
2. - 不要使用 any 类型
3. - 不要使用 console.log 做日志（用 logger 模块）
4. - 不要直接修改 node_modules
5. - 不要在组件里直接调用 API，通过 service 层
6. - 不要使用 var，用 const 或 let

复制代码

"禁止"清单往往比"要求"清单更有用。告诉 AI 不要做什么，比告诉它要做什么更容易执行。

━━━━━━━━━━━━━━━━━━━━

不应该写什么

CLAUDE.md 不是写小说的地方。官方建议控制在 200 行以内。写太长会怎样？两个问题：

Token 消耗增加：CLAUDE.md 的内容会注入到每次对话的上下文里，越长越费钱

注意力稀释：就像人看太长的文档会走神，AI 处理过长的指令也会"重点不突出"

不要写的东西：

教程式的长篇解释（Claude Code 不需要你教它什么是 React）

重复的信息（同一条规则写一遍就够了）

过于细节的实现指引（具体怎么实现某个功能不应该写在规范里）

项目历史和变更日志

核心原则：把 CLAUDE.md 当作给一个资深工程师的入职速查卡，不是新手教程。

━━━━━━━━━━━━━━━━━━━━

实战：从零写一个 CLAUDE.md

假设你有一个 Next.js + TypeScript 的项目，从头写一个 CLAUDE.md：

1. # 项目规范
3. ## 技术栈
4. - Next.js 14 + TypeScript + Tailwind CSS
5. - 状态管理：Zustand
6. - 数据库：PostgreSQL + Prisma
7. - 测试：Vitest + Testing Library
9. ## 命令
10. - 开发：pnpm dev
11. - 构建：pnpm build
12. - 测试：pnpm test
13. - Lint：pnpm lint
14. - 数据库迁移：pnpm prisma migrate dev
16. ## 代码风格
17. - 函数式组件 + hooks，不用 class 组件
18. - 使用 const 箭头函数定义组件
19. - 文件名 kebab-case，组件名 PascalCase
20. - 每个文件不超过 200 行，超过要拆分
21. - 函数不超过 30 行
23. ## Git 提交规范
24. - 中文 commit message
25. - 格式：类型(范围): 描述
26. - 类型：feat/fix/refactor/docs/test/chore
28. ## 禁止
29. - 禁止使用 any
30. - 禁止 console.log（使用 logger）
31. - 禁止在组件中直接请求 API
32. - 禁止硬编码密钥或密码

复制代码

简单、直接、高信息密度。这就够了。

━━━━━━━━━━━━━━━━━━━━

进阶：用 /init 自动生成

如果你懒得从头写，Claude Code 提供了自动生成功能：

1. > /init

复制代码

Claude Code 会扫描你的项目文件——package.json、tsconfig.json、.eslintrc、目录结构等——然后自动生成一份 CLAUDE.md。

生成的版本通常需要微调，但至少省去了 80% 的工作量。

━━━━━━━━━━━━━━━━━━━━

进阶：多文件规则

当 CLAUDE.md 超过 200 行时，把它拆分到

1. .claude/rules/

复制代码

目录：

1. .claude/
2.   rules/
3.     coding-style.md    # 代码风格
4.     git-workflow.md     # Git 工作流
5.     testing.md          # 测试规范
6.     security.md         # 安全规范

复制代码

每个文件聚焦一个主题，Claude Code 会全部加载。这样维护起来更清晰，不同主题的规则不会混在一起。

━━━━━━━━━━━━━━━━━━━━

常见问题 Q&A

Q1：CLAUDE.md 修改后需要重启吗？

不需要。Claude Code 每次新对话开始时都会重新读取。如果你在对话中改了 CLAUDE.md，用

1. /clear

复制代码

清一下上下文，它就会加载最新版本。

Q2：CLAUDE.md 应该提交到 Git 吗？

看情况。如果是团队协作项目，建议提交——让所有人的 AI 助手遵守同一套规范。如果包含个人偏好（比如你喜欢的编辑器配置），放到

1. ~/.claude/CLAUDE.md

复制代码

全局配置里，别提交。

Q3：写了规范它就一定遵守吗？

大部分时候会遵守，但 AI 不是程序——它不是硬编码的 if-else，偶尔会"忘记"或"创造性发挥"。Day 5 我们会讲 Hooks，那才是强制执行的手段。CLAUDE.md 是"指导方针"，Hooks 是"法律条文"。

━━━━━━━━━━━━━━━━━━━━

小结

今天学了 CLAUDE.md 的配置方法：

它是给 Claude Code 的"员工手册"，每次启动自动加载

写四类内容：项目信息、代码风格、架构约定、禁止事项

控制在 200 行以内，像速查卡而不是教程

大项目用

1. .claude/rules/

复制代码

目录拆分

有了 CLAUDE.md，Claude Code 从"聪明但不懂规矩的实习生"升级成了"了解团队规范的新同事"。

但你可能还有一个担心：它能读能写能执行命令，万一做了不该做的事呢？

明天 Day 4，我们聊权限管理——怎么让 AI 在安全线内干活，别把你家拆了。

━━━━━━━━━━━━━━━━━━━━

系列进度：3/10