本节目标完成本节后你将能够准确解释 CLAUDE.md 是什么以及它为什么是最重要的配置文件理解 CLAUDE.md 的三层加载优先级体系使用/init自动生成并手动精炼 CLAUDE.md编写一份包含 5 个核心模块的高质量 CLAUDE.md严格遵守 150 行预算规则写出精炼高效的项目规则核心知识点CLAUDE.md 到底是什么CLAUDE.md 是 Claude Code 的项目级配置文件。你可以把它理解为一份给 AI 工程师的员工手册就像一个新入职的工程师需要了解公司的代码规范、项目结构、构建命令和禁止操作一样Claude Code 在每次启动时都会自动读取 CLAUDE.md让它的行为符合你的预期。它使用 Markdown 格式放在项目的根目录或其他关键目录。Claude Code 会在每个会话开始时自动加载它。什么时候必须有 CLAUDE.mdCLAUDE.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 - 函数命名使用 camelCaseReact 组件使用 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 - 不要引入超过 50KBgzip的新依赖 - 不要修改 .github/workflows/ 下的 CI 配置模块 5语言和交互偏好## 交互偏好 - 使用中文回复所有消息 - 在修改文件前先解释将要做什么 - 遇到不确定的情况时先提问而不是猜测 - 修改超过 30 行时提供修改摘要150 行预算规则——最重要的纪律Claude Code 会把 CLAUDE.md 的全文加载到每个会话的上下文中。上下文窗口是有限且昂贵的资源。因此有一条黄金法则CLAUDE.md 的总长度不应超过 150 行约 2000-3000 字符为什么是 150 行上下文窗口约 200K tokenSonnet 4CLAUDE.md 消耗约 1000-2000 token这意味着 CLAUDE.md 只占约 1% 的上下文预算——合理如果 CLAUDE.md 长达 500 行约 5000 token它占了约 2.5%——开始不划算超过 1000 行约 10000 token它占 5%——严重浪费精简技巧写做什么和不做什么不要写为什么用列表和短句不要用段落体重复的内容合并到一处每季度审视一次删除过时内容实操步骤步骤 1在一个项目中生成你的第一份 CLAUDE.md找一个小项目目录或使用上一节创建的 playgroundcd ~/claude-playground claude在交互模式中输入/init观察 Claude Code 的行为它会扫描项目文件结构读取 package.json 等配置文件生成一份 CLAUDE.md 草稿展示给你预览你确认后写入文件步骤 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 Codeclaude现在提一个问题来验证规则是否被遵守帮我添加一个新的工具函数观察 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 只能猜测而猜测往往是错误的。坑 4CLAUDE.md 超过 200 行超过 200 行的 CLAUDE.md 说明你在把代码规范和项目文档混在了一起。代码规范放 CLAUDE.md项目文档放 README.md 或 Wiki。定期审查 CLAUDE.md每次会话后如果发现有不常用的规则删除它。坑 5团队成员各自修改 CLAUDE.md导致冲突如果你的团队都使用 Claude CodeCLAUDE.md 应该纳入版本控制通过 PR 流程来修改。每个人可以有自己的~/.claude/CLAUDE.md来设置个人偏好但项目级的 CLAUDE.md 必须经过团队共识。课后作业创建在你最常用的项目中使用/init生成 CLAUDE.md然后手动精炼到 150 行以内。测试精炼前后各让 Claude Code 完成一个同样的小任务如创建一个新的工具函数对比输出质量差异。记录你的观察。审查检查你的 CLAUDE.md确认每条规则都是可验证的。对于模糊的规则重写成具体可验证的形式。实验在子目录中创建一个 CLAUDE.md加入一条与根目录不同的规则。然后让 Claude Code 在该子目录下完成任务验证子目录规则是否覆盖了根目录规则。总结CLAUDE.md 是 Claude Code 系统中最重要的文件没有之一。它决定了 AI 在你项目中的行为边界和质量标准。记住三个核心原则精炼胜于全面150 行的好规则远胜 500 行的泛泛之谈可验证胜于抽象每一条规则都必须是可以明确判断遵守与否的层级治理全局偏好放~/.claude/CLAUDE.md项目规范放项目根目录目录特定规则放子目录把 CLAUDE.md 想象成你给 AI 工程师写的入职第一天该知道的所有事情——如果一件事不那么重要就不要写进去。每一条冗余的规则都在消耗宝贵的上下文窗口。