CLAUDE.md最佳实践排行榜：Karpathy四原则+6套完整模板

你费了好大劲装好了 Claude Code，准备大干一场。你也知道项目根目录下那个叫 `CLAUDE.md` 的文件能“指挥”AI 的行为。可当你满怀期待地打开一看——要么是空空如也，要么是 `/init` 命令随手甩出来的一堆不痛不痒的废话。

别急着删文件。真正的问题从来不是“要不要写”，而是“怎么写才能让它物超所值”。

这篇文章没什么高深的理论。我直接把圈内几位顶流高手的真实配置扒了个底朝天：从 Andrej Karpathy 那个 22 万星的“四原则”，到 Anthropic 官方团队自己饭碗里的 CLAUDE.md，再到 React 核心开发者 Dan Abramov 的私房配置。看完这些，我又给你打包好了 6 套可以直接复制到项目里的完整模板——从前端后端到独立开发、写作、数据分析，再到刚入门的学生。找到你的角色，把模板整段粘过去，改几个占位符，马上就能用起来。

先快速扫一眼核心思路：

• CLAUDE.md 的“四层”作用域和加载机制（官方文档原话，没添油加醋）
• 5 个全球知名项目的真实 CLAUDE.md 是怎么写的
• 6 套分场景、可直接复制的完整模板
• 从单文件到多级配置体系的进阶玩法
• 一份帮你避坑的“反模式”检查清单

为什么说 CLAUDE.md 是你最该花时间打磨的单个文件？

Claude Code 每次启动，都像是一个有“失忆症”的外援。它不记得你上次聊到哪了，不记得你偏爱什么技术栈，更不知道你项目里的那些架构默契。而 CLAUDE.md，是唯一一个能默认塞进每次对话里的“备忘录”。

HumanLayer 的创始人 Kyle 专门分析过这个事情，他画过一个很有名的杠杆层级图。大意是说：

CLAUDE.md 里写错一行指令 → 影响所有研究 → 影响所有规划 → 影响所有代码

你看，这份文件是整个工具链里“杠杆率”最高的地方。一行没写对，后面所有的产出都会跑偏。反过来，一行写对了，它就能在每一次会话、每一个任务里，持续地、自动地帮你拉高下限。

官方怎么说？CLAUDE.md 的底层逻辑

在动手写之前，最好先摸清 CLAUDE.md 的门道。下面的内容都来自 Anthropic 官方文档。

四层作用域，层层叠加

CLAUDE.md 不是单独一个文件，而是一个分层体系。Claude Code 启动时，会严格按这个顺序加载：

关键点在于：所有层级的内容是**拼接**起来注入上下文的，不是覆盖，是叠加。而且，子目录里的 CLAUDE.md 并不会在启动时就加载，只有 Claude 读到那个目录里的文件时，才会按需加载。

一个必须知道的事实：它只是“建议”，不是“命令”

很多人有个误解，以为 CLAUDE.md 里写了啥，Claude 就必须遵守。实际上，CLAUDE.md 是作为一条“用户消息”注入的，并且注入时 Claude Code 会附带一句系统提醒——大概意思是“这些信息不一定与当前任务相关，你可以判断使用”。

这意味着，Claude 有权利选择性地忽略它认为不重要的指令。文件越长，指令被忽略的概率就越高。

官方给出的“写什么”和“不写什么”清单

Anthropic 官方有一套明确的最佳实践来指导你：

应该写进去的：

• Claude 靠读代码猜不出来的构建命令（比如 pnpm test:e2e --filter=@app/web）
• 偏离默认规范的代码风格（比如，“本项目中禁止使用 default export”）
• 测试指令和指定的测试框架
• 仓库协作的礼仪（分支命名规范、PR 约定）
• 项目特有的架构决策，以及为什么要这么做的理由
• 开发环境的特殊前置条件（比如“必须先设置环境变量 OPENAI_API_KEY”）
• 那些容易掉进去的坑，或者反直觉的行为

千万不要写进去的：

• Claude 看一眼代码就能知道的东西（比如“这个项目用了 TypeScript”——它自己会去看 tsconfig.json）
• 语言层面的通用约定（比如“Python 用 snake_case”——这是它默认会做的事情）
• 冗长的 API 文档（放个链接就够了，别把整篇文档复制进去）
• 频繁变动的信息（每次改完还要来同步 CLAUDE.md，不出几周就过时了）
• 对代码库的逐文件描述（Claude 自己会去看目录结构）
• 像“写干净的代码”这种说了等于没说的废话

5 个知名项目的 CLAUDE.md 拆解，看看高手怎么玩

理论听得差不多了。直接来看看行业里那些顶级开发者和公司，他们实际在用的 CLAUDE.md 长什么样。

案例一：Karpathy 的“四原则”（22 万 Star）

Andrej Karpathy 的这份 CLAUDE.md 被很多人称为“改变 AI 编程的四行”，它的仓库在 GitHub 上收藏量极高。这份文件里没有任何项目信息，纯粹是一份行为准则：

原则一：先想再写
别急着动手，也别藏着疑虑。开始实施前先把你的假设亮出来。如果存在多种解读方式，把它们全列出来，不要自己偷偷选一个。如果想到了更简单的方案，直接说出来。

原则二：简洁优先
用最少的代码解决问题，没要求的功能坚决不做。不为只用一次的代码做抽象，不加毫不必要的“灵活性”或“可配置性”。如果你写了 200 行，但 50 行就能搞定——那就重写。

原则三：外科手术式修改
只动那些必须动的部分。不要“顺手”优化旁边的代码、注释或者格式。没坏的东西就不要去“重构”。尽量匹配现有的风格，哪怕你自己习惯另一种写法。检验标准只有一个：你的每一行改动，都应该能直接追溯到用户提出的请求。

原则四：目标驱动执行
把任务转化为可验证的目标。“加个验证” → “写一个无效输入的测试，然后让它通过”。“修个 bug” → “写一个能复现 bug 的测试，然后让它通过”。

在文件末尾，他加了一行自检标准，简短有力。

案例二：Anthropic 官方团队的 “claude-code-action”

Anthropic 自己给 claude-code-action 这个项目写的 CLAUDE.md，大约 55 行。它的结构非常值得借鉴：

Commands (构建/测试/lint 的具体命令) → What This Is (一句话定位) → How It Runs (运行机制简述) → Key Concepts (核心概念解释) → Things That Will Bite You (六个会坑到你的地方) → Code Conventions (代码约定)

最有价值的部分是 Things That Will Bite You。它直接列出了六个开发过程中最容易被绊倒的坑：比如严格的 TypeScript 配置、判别联合类型的使用、Token 的生命周期管理、错误的阶段归因、step ID 的引用方式，以及集成测试实际在另一个仓库里。

这种“预判你会在哪里翻车”的写法，比罗列一堆干巴巴的规则要有效得多。

案例三：Dan Abramov 的 “overreacted.io”

React 核心开发者 Dan Abramov 给他的个人博客写的 CLAUDE.md，也是 55 行左右。整体结构很标准，但有一个独特的段落：Commit Messages（提交信息）。

他直接告诉 Claude：别用机器人腔调、营销黑话或者模糊的废话来写提交信息。这是把个人风格变成强约束条件的典范——不只约束代码质量，还约束了 Claude 的“说话方式”。

案例四：Vercel 的 “next-devtools-mcp”

Vercel 官方给 next-devtools-mcp 写的 CLAUDE.md，大约 120 行，体现了大公司的工程化水准。它新增了一个 Common Development Patterns（常见开发模式） 段落，里面给出了“添加新 Tool”、“添加新 Resource”、“添加新 Prompt”的标准步骤模板。相当于把项目里最常做的几件事，都写成了操作规程，Claude 照着做就不会跑偏。

案例五：Karpathy 的 “llm-council”

除了上面那个通用的“四原则”，Karpathy 自己项目 llm-council 的 CLAUDE.md 有 130 行，内容非常详尽。它包含了完整的架构描述（按目录结构逐文件介绍后端和前端）、关键设计决策、实现细节、4 个常见的坑，甚至还有一个用 ASCII 字符画的数据流图。

这和他的“四原则”形成了有趣的对比。“四原则”是通用的行为约束（放在全局），而 llm-council 的 CLAUDE.md 是具体的项目上下文（放在项目根目录）。两种他都在用。

两种流派，做个对比

最理想的做法是两者结合。全局文件放通用行为准则，项目文件放具体项目上下文。

基础配置：一份所有人都适用的 CLAUDE.md 底座

不管你是做什么的，下面这四个段落，都建议写进你的 CLAUDE.md 作为起点：

# 基础设定
- 交互语言：简体中文
- 思考过程可以用英文，最终输出用中文
- 代码注释用英文

# 代码风格
- 变量命名：自解释的完整单词，不用缩写
- 函数：只做一件事，不超过 30 行
- 缩进：2 空格（前端）/ 4 空格（Python）

# 输出格式
- 默认输出 Markdown
- 代码块标注语言（```python / ```tsx）
- 文件路径用反引号包裹

# 安全底线
- 密钥、令牌、密码走环境变量，禁止硬编码到源代码
- 禁止在日志中打印敏感信息
- 不删除不可恢复的数据前先确认

这就是个万能底座，复制到你任何项目的 CLAUDE.md 开头都不会错。下面是根据不同场景定制的完整模板。

场景一：前端开发者的完整 CLAUDE.md

这是 Claude Code 用户中人数最多的群体。最让人头疼的问题就是 Claude 猜错技术栈——你想要 hooks，它给你 class 组件；你要 CSS Modules，它给你 Tailwind；你要 App Router，它给你 Pages Router。

下面这份模板锁定了 Next.js + TypeScript + Tailwind 技术栈，可以直接复制：

# 项目配置

## 技术栈（不可协商）
- 框架：Next.js 15，App Router（禁止 Pages Router）
- 语言：TypeScript strict 模式，禁止 any 和 @ts-ignore
- 样式：Tailwind CSS v4（禁止内联 style 对象，禁止 CSS Modules，禁止 styled-components）
- 状态管理：Zustand（禁止 Redux、MobX、Recoil）
- 数据请求：Server Components 直接 fetch + React Query（客户端）
- 包管理：pnpm（禁止 npm 和 yarn）
- 运行时：Node.js 22

## 命令
- 开发：`pnpm dev`
- 构建：`pnpm build`
- 类型检查：`pnpm typecheck`
- 代码检查：`pnpm lint`
- 测试：`pnpm test`
- 提交前必跑：`pnpm typecheck && pnpm lint`

## 项目结构
app/ 路由和页面（每个 page.tsx 只做布局编排，不放业务逻辑）
components/ 可复用组件（按功能域分子目录：components/auth/、components/dashboard/）
components/ui/ 基础 UI 组件（Button、Input、Modal 等，来自 shadcn/ui）
lib/ 工具函数、第三方 SDK 封装、常量定义
lib/api/ API 调用封装（每个端点一个文件）
types/ 全局类型定义（不放在组件文件里）
hooks/ 自定义 hooks

## 组件规范
- 只用函数组件 + hooks，禁止 class 组件
- Props 用 interface 定义，命名格式 `{组件名}Props`
- 单文件不超过 200 行，超过就拆成子组件
- 导出用 named export（`page.tsx` 和 `layout.tsx` 除外，这两个用 default export）
- 事件处理函数命名 `handle{Event}`（如 handleClick、handleSubmit）
- 组件文件命名 PascalCase（UserProfile.tsx），工具文件命名 camelCase（formatDate.ts）

## 样式规则
- Tailwind 优先，自定义值走 tailwind.config 的 theme.extend
- 响应式用 mobile-first：无前缀 → sm → md → lg → xl
- 暗色模式用 dark: 前缀
- 间距用 Tailwind 的间距比例（p-4、gap-6），不用任意值（p-[13px]）

## Server Components vs Client Components
- 默认 Server Component（不加 'use client'）
- 只在需要 useState、useEffect、事件监听器、浏览器 API 时才加 'use client'
- 'use client' 加在最小必要的组件上，不要加在页面级

## 错误处理
- Server 端错误用 error.tsx 边界捕获
- 客户端异步操作用 try-catch + 用户友好的错误提示
- 不要用 console.log 做错误处理，用 console.error 或接入错误追踪服务

场景二：后端开发者的完整 CLAUDE.md

后端开发的核心问题是安全和架构。Claude 默认不太会主动考虑 SQL 注入、密钥硬编码和权限校验。下面是一份 Python + FastAPI 的完整模板：

# 项目配置

## 运行时
- Python 3.12 + FastAPI 0.115+
- 包管理：uv（禁止 pip、poetry、conda）
- 类型标注：全量（参数 + 返回值 + 类属性）
- 代码格式化：Ruff（禁止 black、isort、flake8）

## 命令
- 安装依赖：`uv sync`
- 开发运行：`uv run uvicorn app.main:app --reload --port 8000`
- 测试：`uv run pytest -v`
- 类型检查：`uv run mypy .`
- 格式化：`uv run ruff format . && uv run ruff check --fix .`

## 架构约定
- 分层：router → service → repository → model
- router 层只做参数校验和响应封装，禁止业务逻辑
- service 层承载业务逻辑，一个 service 对应一个业务域
- repository 层封装数据访问，禁止在 service 里直接写 SQL
- 依赖注入用 FastAPI 的 Depends，禁止全局实例化

## 目录结构
app/
├── main.py FastAPI 应用入口
├── config.py 配置管理（Pydantic Settings）
├── routers/ 路由层（每个资源一个文件）
├── services/ 业务逻辑层
├── repositories/ 数据访问层
├── models/ SQLAlchemy 模型
├── schemas/ Pydantic 请求/响应 Schema
├── middleware/ 中间件（认证、日志、CORS）
├── exceptions/ 自定义异常
└── utils/ 工具函数
tests/
├── conftest.py 测试 fixtures
├── test_routers/ 路由层测试（集成测试）
└── test_services/ 业务逻辑测试（单元测试）

## API 设计
- RESTful 命名，资源名用复数（/users、/orders）
- 统一响应格式：`{"code": 0, "data": {}, "message": ""}`
- 分页用 cursor-based（禁止 offset-based，数据量大时性能差）
- 版本号放 URL 路径：/api/v1/
- 请求体和响应体都用 Pydantic model 定义

## 数据库
- ORM：SQLAlchemy 2.0（异步模式，用 AsyncSession）
- 迁移：Alembic。每次改模型必须生成迁移文件
- 禁止原始 SQL 字符串拼接，全部用参数化查询或 ORM
- 索引：查询条件中的字段加索引，外键加索引
- 命名：表名用 snake_case 复数（users、order_items）

## 安全铁律
- 密钥通过环境变量注入（Pydantic Settings 的 .env 读取），禁止硬编码
- 所有外部输入必须经过 Pydantic model 校验
- 认证用 JWT，令牌有效期不超过 24 小时，刷新令牌不超过 7 天
- 密码存储用 bcrypt，禁止 MD5 和 SHA256
- 日志禁止打印密钥、密码、令牌、用户隐私数据
- CORS 不要设置 allow_origins=["*"]，列出具体域名

## 测试
- 改完代码必跑 pytest
- 新增 API 端点必须有对应的集成测试
- 测试数据库用独立实例或 SQLite 内存模式，禁止连接生产库
- mock 只用于外部服务调用（第三方 API、邮件发送），数据库层不 mock

## 错误处理
- 自定义异常层级：AppError → BusinessError / AuthError / NotFoundError
- 全局异常处理器统一捕获，返回标准错误响应
- 禁止裸 try-except（必须指定具体异常类型）
- 所有异常记录日志，包含请求 ID 便于追踪

场景三：独立开发者 / 一人公司的完整 CLAUDE.md

对于一人公司来说，CLAUDE.md 的价值是最大的——它相当于一份“写给 AI 队友的团队手册”。你一个人要管前后端、部署、运维和运营，所有约定都在你脑子里，但 Claude 不知道。

# 一人公司项目配置

## 项目全景
- 产品 A（主营）：SaaS 应用，Next.js 15 + Supabase + Stripe
- 产品 B（副业）：API 服务，FastAPI + PostgreSQL，为产品 A 提供后端
- 产品 C（营销）：营销站 + 博客，Astro + Tailwind + Ghost CMS
- 共用基础设施：Cloudflare（DNS / CDN / R2 存储）+ Vercel（前端部署）+ Railway（后端部署）

## 全局约定
- 前端项目统一 TypeScript + pnpm
- 后端项目统一 Python 3.12 + uv
- 代码风格：前端 Prettier + ESLint，后端 Ruff
- Git：main 分支保护，功能分支开发，squash merge，提交信息用英文

## 部署流程
- 标准流程：本地开发 → 推到 GitHub → CI 自动测试 → 合并 main 自动部署
- 前端：Vercel 自动部署，Preview Deployment 用于测试
- 后端：Railway 自动部署，每次 push 到 main 触发
- 数据库变更：先在 staging 环境跑 Alembic 迁移，确认无误后合并到 main

## 安全边界（不可违反）
- 密钥管理：本地用 .env.local，线上用平台环境变量面板，禁止硬编码
- 生产数据库：禁止在命令行直连执行写操作（DELETE / UPDATE / DROP）
- 第三方 API：所有调用必须设置超时（30 秒）和重试（最多 3 次）
- 回滚方案：Vercel 一键回滚到上一版 / Railway 回滚到上一 commit

## 运维
- 监控：Sentry 用于错误追踪，UptimeRobot 用于可用性监控
- 日志：结构化 JSON 格式，级别分 info / warn / error
- 告警：Sentry 新 issue → Telegram 通知（通过 webhook）
- 备份：数据库每日自动备份（Railway 自带），R2 存储无需备份（Cloudflare 托管）

## 成本控制
- Vercel：Pro 计划 $20/月，留意 bandwidth 和 serverless function 调用量
- Railway：用量计费，每月 $5 封顶（低流量阶段）
- Supabase：Free 计划（500MB 数据库 + 1GB 存储），超了再升
- 域名：在 Cloudflare 统一管理，自动续费已开

## 脚本索引
- `scripts/deploy-staging.sh` — 手动部署到 staging 环境
- `scripts/db-backup.sh` — 手动触发数据库备份
- `scripts/seed-dev.sh` — 开发环境填充测试数据
- `scripts/check-env.sh` — 检查必需环境变量是否配齐

场景四：写作 / 自媒体从业者的完整 CLAUDE.md

这是非程序员群体里，使用 Claude Code 增长最快的一个方向。最大的痛点是风格漂移——每次对话都跟 Claude 重新介绍一遍你的品牌人设和语气偏好，太累人了。

# 写作工作台配置

## 关于我
- 我是一名自媒体从业者，主要在公众号、小红书和个人博客发布内容
- 主题领域：[你的领域，如"AI 工具使用""个人成长""职场效率"]
- 读者画像：25-40 岁职场人，对效率工具感兴趣但技术基础有限

## 品牌人设
- 定位：[一句话定位，如"用大白话讲清楚 AI 工具怎么用"]
- 语气：专业但不学术，亲切但不油腻，有态度但不抬杠
- 第一人称：我（不用"笔者""小编""本人"）
- 禁用词：赋能、抓手、闭环、底层逻辑、降维打击、认知升级、深度赋能
- 禁用句式：禁止三个以上排比句连用，禁止反问句开头

## 写作风格铁律
- 一段不超过 4 行（手机阅读友好）
- 一句话能说清的不拆成两句
- 先说结论再展开，不铺垫太久
- 数据和案例优先于观点和形容词
- 专业术语第一次出现时用括号注释

## 平台规则

### 公众号
- 正文 1500-3000 字
- 标题不超过 32 字，必须包含核心关键词
- 需要提供：标题 + 正文 + 摘要（120 字以内）
- 封面图描述（用于 AI 配图或找图）

### 小红书
- 正文 300-800 字
- 标题必须包含数字或问句
- 正文用段落+要点混排，适当使用符号分隔
- 需要提供：标题 + 正文 + 标签建议（5-8 个）

### 博客（Ghost / WordPress）
- 正文 2000-5000 字
- SEO 标题不超过 60 字符
- 需要提供：标题 + 正文 + meta description（80 字以内）+ 摘要

## 内容结构模板

### 标题公式（每次给 3 个备选）
- 数字型：{数字} + {方法/工具} + {结果/好处}
- 问题型：{痛点问题}？{暗示有答案}
- 对比型：{旧方法} vs {新方法}：{差异点}

### 开头范式（前 3 行决定读者走不走）
- 场景切入：描述一个读者正在经历的具体场景
- 数据冲击：用一个让人意外的数字开场
- 反常识：提出一个和读者直觉相反的观点

### 结尾要求
- 行动号召：告诉读者看完可以做什么
- 互动引导：提一个能引发评论的问题

## 输出格式
- 每篇文章输出：标题（3 个备选）+ 正文 + 摘要 + 标签建议
- 文章用 Markdown 格式
- 图片位置用 `[图片：描述]` 占位

场景五：数据分析师的完整 CLAUDE.md

数据分析最核心的要求是可复现性和可视化的一致性。下面这份模板主要解决“每张图配色都不一样”、“统计方法选错”、“换个环境就跑不通”这三个老大难问题。

# 数据分析工作台配置

## 计算环境
- Python 3.12
- 核心库：pandas 2.x、numpy、scipy、matplotlib、seaborn、scikit-learn
- 交互探索用 Jupyter Notebook，正式分析出 .py 脚本
- 随机种子统一设为 42（涉及随机操作必须 set_seed(42)）

## 命令
- 安装依赖：`uv sync`
- 运行分析脚本：`uv run python scripts/{script_name}.py`
- 启动 Jupyter：`uv run jupyter lab`
- 运行测试：`uv run pytest tests/`

## 数据处理规范
- 原始数据只读（放 data/raw/），处理结果写到 data/processed/
- 每个处理步骤记录到 data/processing_log.md
- 缺失值处理必须记录策略（删除 / 填充 / 插值）和影响的行数
- 变量命名用 snake_case，含义自解释（user_age 而不是 ua）
- 日期格式统一 ISO 8601（2026-06-06）

## 可视化风格（所有图表统一）
- 配色方案：seaborn 的 "colorblind" 色板（色盲友好）
- 字号：标题 14pt，坐标轴标签 12pt，刻度标签 10pt，图例 10pt
- 所有图表必须有：标题、坐标轴标签（含单位）、图例（多系列时）
- 输出格式：论文用 PDF 300dpi，汇报用 PNG 150dpi
- 中文字体 SimHei（黑体），英文字体 Arial
- 图表尺寸默认 (10, 6)，保存时 bbox_inches='tight'

```python
# 标准图表模板（每个脚本开头引入）
import matplotlib.pyplot as plt
import seaborn as sns
sns.set_theme(style="whitegrid", palette="colorblind")
plt.rcParams.update({
    'font.sans-serif': ['SimHei', 'Arial'],
    'axes.unicode_minus': False,
    'figure.figsize': (10, 6),
    'font.size': 12,
    'axes.titlesize': 14,
    'axes.labelsize': 12,
    'xtick.labelsize': 10,
    'ytick.labelsize': 10,
})
```

## 统计分析约定
- 描述性统计先行：均值、中位数、标准差、分布图
- 推断统计前先做正态性检验（Shapiro-Wilk）
- 正态 → 参数检验（t 检验、ANOVA）；非正态 → 非参数检验（Mann-Whitney、Kruskal-Wallis）
- 报告效应量（Cohen's d），不只报 p 值
- 多重比较必须做校正（Bonferroni 或 Benjamini-Hochberg FDR）
- 置信区间优先于假设检验

## 报告格式
- 数值报告：M = 3.45, SD = 1.23, p < .001, d = 0.82
- 表格用三线表，小数统一保留 2 位
- 引用格式：APA 第 7 版
- 百分比保留 1 位小数（35.7%）

## 可复现性要求
- 依赖锁定：pyproject.toml 含精确版本号
- 数据路径用相对路径（data/raw/），不用绝对路径
- 每个分析脚本顶部注释：输入文件、输出文件、用途
- 结果可以通过 `uv run python scripts/{name}.py` 完整复现

场景六：学生 / AI 编程初学者的完整 CLAUDE.md

初学者最头疼的问题是，Claude 默认输出的代码往往太“高级”了——解构赋值、泛型、装饰器满天飞，看得云里雾里，根本学不到东西。

# 学习配置

## 关于我
- 我是编程初学者，正在学 Python
- 当前阶段：掌握了变量、条件语句、循环、列表，正在学函数和面向对象
- 学习目标：能独立写一个完整的命令行工具项目
- 我不熟悉的概念：装饰器、生成器、异步编程、元类、设计模式

## 交互方式
- 交互语言：简体中文
- 每段代码都加逐行中文注释，解释这行在做什么
- 新概念第一次出现时，先用一句话解释"它是什么"，再解释"为什么需要它"
- 用生活类比解释抽象概念（比如用"快递地址"类比变量）
- 如果有多种实现方式，先给最简单的那种

## 代码风格约束
- 变量名用完整英文单词（user_name 而不是 un 或 u_n）
- 一个函数只做一件事，不超过 15 行
- 禁止使用以下高级特性（除非我主动问）：
  - 列表推导式嵌套（[x for y in z for x in y]）
  - 三元表达式嵌套
  - lambda 表达式
  - 装饰器（@something）
  - 元类（metaclass）
  - 生成器（yield）
  - async/await
  - *args, **kwargs（除非正在学这个概念）
- 用 for 循环代替 map/filter/reduce

## 错误处理引导
- 我遇到报错时，按这个顺序帮我：
  1. 先翻译这个错误信息是什么意思（用大白话）
  2. 告诉我应该看报错信息的哪一行、哪个关键词
  3. 解释为什么会出这个错
  4. 给出修复方案，并解释为什么这样改能解决

## 学习节奏
- 每次改完代码后提醒我运行并观察结果
- 在教我新概念时，先给一个最小的可运行示例
- 不要一次改太多东西，每次只改一个地方
- 如果我问的问题超出了当前学习阶段，告诉我"这个概念在 {X} 阶段会学到，现在先理解 {Y} 就够了"

进阶玩法：从单文件到多级配置体系

如果只有一个项目，一个 CLAUDE.md 就够用了。但当项目越来越大，或者你同时管理好几个项目时，单文件就会变成一锅粥，什么规则都往里面塞。

多层级继承

利用 CLAUDE.md 的四层作用域，可以搭建一个层级分明的配置体系：

~/.claude/CLAUDE.md ← 全局：行为约束（Karpathy 四原则） └── 项目根目录/CLAUDE.md ← 项目级：技术栈、架构、命令 ├── src/CLAUDE.md ← 子目录级：该模块的特殊约定 └── tests/CLAUDE.md ← 子目录级：测试相关约定

全局文件放通用的行为规则（所有项目都生效），项目文件放技术上下文（只对当前项目生效），子目录文件放局部规则（只在 Claude 读取该目录时加载）。

Import 语法

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

# CLAUDE.md
@docs/architecture.md
@docs/coding-standards.md

这样一来，你可以把架构文档和编码标准拆成独立的文件去维护，CLAUDE.md 本身只做个索引。导入功能最大支持 4 层递归。

按路径懒加载（.claude/rules/）

大型项目还可以用 .claude/rules/ 目录实现条件加载——只有在 Claude 读取匹配路径的文件时，才加载对应的规则：

# .claude/rules/frontend-components.md
---
paths:
  - "src/components/**/*.tsx"
  - "src/components/**/*.ts"
---
组件必须用 forwardRef 包裹。
Props 接口必须导出。
样式用 Tailwind，不用内联。

这条规则只在 Claude 处理 src/components/ 下的 TypeScript 文件时才会生效，处理后端文件时不会浪费宝贵的上下文窗口。

CLAUDE.md、Skills 和 Hooks 的分工

CLAUDE.md 只是配置体系的一部分，它和另外两个工具各有侧重：

反模式检查清单

以下是在实践中，最常见的几种写坏 CLAUDE.md 的方式：

1. 太长了

症状： CLAUDE.md 超过 300 行，恨不得把你能想到的所有规则都塞进去。
后果： Claude 开始随机忽略你的指令，因为上下文窗口被大量无关内容挤占，它根本看不过来。
修复： 无情地精简内容。每条规则都问自己一句：删掉这条，Claude 的输出会变差吗？如果不确定，就先删了，观察一周再说。

2. 和 Linter 功能重复

症状： CLAUDE.md 里写了非常详细的代码风格指南，比如缩进几个空格、用不用分号、单引号还是双引号。
后果： 让一个 AI 去干 Linter 的活，既贵、又慢、还不可靠。
修复： 代码风格交给 ESLint、Prettier、Ruff 这些确定性工具去管。利用 Hooks 功能，让 Claude 写完文件后自动帮你格式化代码。

3. 规则自相矛盾

症状： 前面写了“推荐使用 default export”，后面又写“禁止使用 default export”。
后果： Claude 只能随机选一条来遵守，行为完全不可预测。
修复： 定期审查你的 CLAUDE.md，搜索一下有没有逻辑矛盾。每个规则只在一个地方声明。

4. 信息过时

症状： CLAUDE.md 里还写着“用 Next.js 13 的 app 目录架构”，但你的项目早就升级到 Next.js 15 了。
后果： Claude 按照过时的信息来生成代码，生成的东西和现有项目完全不兼容，全是坑。
修复： 把 CLAUDE.md 签入 Git，当成代码一样去维护。每次升级依赖的时候，顺手检查一下 CLAUDE.md 里有没有需要同步更新的内容。

5. 用 /init 生成了就不管了

症状： 直接用 /init 命令生成了 CLAUDE.md，然后就一个字不改地开始用。
后果： /init 生成的东西都是最通用的泛泛之谈，根本反映不出你项目的特色和你个人的偏好。
修复： /init 可以作为起点，但你必须逐条审查、精简、删除废话、补充你项目特有的信息。

6. 把 CLAUDE.md 当 wiki 写

症状： 在 CLAUDE.md 里写了大段大段的解释、教程和背景故事。
后果： 这些内容虽然占用了上下文，却不能提供任何可执行的指令，反而会拉低所有指令的整体遵循率。
修复： CLAUDE.md 只放可执行的指令和不可改变的事实。复杂的背景文档，应该放到 docs/ 目录下，然后在 CLAUDE.md 里用一句话指向那个地方就行。

快速检查表

写完你的 CLAUDE.md 后，对照这份清单过一遍：

• [ ] 不超过 200 行（官方推荐的上限）
• [ ] 只包含了 Claude 从代码里推不出来的信息
• [ ] 没有和 Linter / Formatter 重复的规则
• [ ] 没有互相矛盾的规则
• [ ] 构建、测试、lint 的命令完整且准确
• [ ] 架构决策写明了原因（不只说“用 X”，还说“为什么用 X”）
• [ ] 把常见的陷阱列出来了（Things That Will Bite You）
• [ ] 项目级的文件已经签入了 Git
• [ ] 个人偏好放在了 CLAUDE.local.md 里（不签入 Git）
• [ ] 频繁变更的信息没有写进来（用文档链接代替）

常见问题

CLAUDE.md 应该写多长？

官方建议每个 CLAUDE.md 不超过 200 行。HumanLayer 那个项目的根本 CLAUDE.md 都没超过 60 行。文件太长，指挥占用过多的上下文窗口，导致指令被遵循的概率下降。

CLAUDE.md 和 .cursorrules 有什么区别？

CLAUDE.md 是 Claude Code 的项目记忆文件，作为一条用户消息注入到每次会话里。.cursorrules 是 Cursor 编辑器的项目规则文件。两者功能类似，但互不通用，各自只对自己的工具生效。

为什么 Claude Code 经常不遵守 CLAUDE.md 里的规则？

因为 CLAUDE.md 在注入时，会附带一条系统提示，大意是“这些上下文可能与你的任务有关，也可能无关”。Claude 会判断某些指令和当前任务关系不大而选择忽略。解决办法是保持文件简短、指令具体可验证、避免自相矛盾的规则。

应该用 /init 自动生成 CLAUDE.md 吗？

可以作为起点，但绝不能当成终稿。CLAUDE.md 是整个工具链里杠杆率最高的配置点，一行坏指令会影响后续所有的输出。建议先用 /init 生成一个初版，然后逐条审查和精简，补充项目特有的信息。

全局 CLAUDE.md 和项目 CLAUDE.md 应该分别放什么？

全局（~/.claude/CLAUDE.md）放跨项目通用的行为约束，比如 Karpathy 四原则里关于思考习惯和简洁的要求。项目级（./CLAUDE.md）放具体的技术栈、架构决策、构建命令和那些容易踩的坑。

CLAUDE.md 需要签入 Git 吗？

官方推荐签入 Git，让团队里的所有成员都能共享同一套项目指令。个人的偏好设置可以放在 CLAUDE.local.md 里，这个文件不会被签入版本控制。

CLAUDE.md 和 Skills、Hooks 是什么关系？

CLAUDE.md 用来放事实性规则（总是做 X），Skills 用来放多步骤流程（触发时执行 Y），Hooks 用来放确定性门控（每次执行 Z 前自动检查）。三者配合使用，效果最好。

CLAUDE.md 支持中文吗？

完全支持。CLAUDE.md 就是标准的 Markdown 文件，内容用什么语言写都行。你只需要在文件开头声明一下交互语言就行，比如写上“交互语言：简体中文”。

写好一份 CLAUDE.md，就像是在为你项目里的这个“AI 实习生”准备一份入职手册。它不会让一个初级工程师一夜之间变成高级工程师，但一定能让他少走很多弯路，更快地上手。Claude Code 也是一样。工具的上限由你来设定，而 CLAUDE.md，就是你用来设定这个上限的那个工具。

从今天展示的这 6 套模板里，挑一个最接近你场景的，复制到你的项目里，改掉里面的占位符，然后开始用。用不了几天你就会发现，Claude 的输出风格和水平，就像是换了个人似的。