CLAUDE.md 最佳实践：Karpathy 四原则 + 6 套完整模板，看完直接复制

Claude Code 装好了，打开项目根目录，看到一个 CLAUDE.md。点进去——空的。或者更糟，是 /init 自动生成的一堆"请在此描述你的项目架构"。

问题从来不是该不该写这个文件，而是往里面写什么才真的管用。

我系统梳理了 GitHub 上各类项目的 CLAUDE.md——从 Karpathy 那个 22 万星的四原则，到 Anthropic 官方团队自己写的项目配置，到 React 核心开发者 Dan Abramov 对提交信息的强约束。看完之后有一个很清楚的判断：大多数人的 CLAUDE.md 要么规则过多导致 Claude 选择性忽略，要么写了大量 Claude 读代码就能推断出来的冗余信息。

这篇文章做两件事。先拆解这些真实案例里到底写了什么、为什么有效。然后给出 6 套完整的 CLAUDE.md——前端、后端、独立开发者、写作者、数据分析师、初学者——你找到自己的场景，整段复制过去，改几个名字就能用。

要点速览

• 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 可能会无视你写的规则

这是很多人不知道的：CLAUDE.md 并不是一道硬性命令，而是作为"用户消息"注入到对话里的。注入的时候，Claude Code 还会附带一句系统提醒，大意是：

"这些上下文不一定和你当前的任务相关，只在确实相关时才参考。"

换句话说，Claude 会自己判断哪些指令跟当前任务有关。文件越长、无关内容越多，有用的规则被忽略的概率就越高。

⚠️ 常见踩坑：你在 CLAUDE.md 里写了一整套数据库设计规范，结果 Claude 改前端代码的时候完全不看。这不是 bug——Claude 判断那些规则跟当前任务无关，就跳过了。解决办法：只和特定目录相关的规则，放到 .claude/rules/ 下面，用 paths: 字段限定生效范围。

官方说了：该写什么、不该写什么

Anthropic 的最佳实践文档列了一份很实用的清单：

该写的：

• Claude 看代码猜不到的构建命令（比如你的测试要加特殊参数 pnpm test:e2e --filter=@app/web）
• 偏离常规的代码风格（比如你们团队禁用 default export）
• 测试怎么跑、用哪个测试框架
• 分支命名规范、PR 提交习惯
• 为什么做了某个架构选择（不只写"用 X"，还写"因为 Y 所以用 X"）
• 开发环境的怪癖（比如必须先 source 某个 env 文件）
• 那些违反直觉、容易踩坑的地方

不该写的：

• Claude 一看代码就知道的事——你有 tsconfig.json，不用再写"本项目用 TypeScript"
• 编程语言的标准约定——Python 用 snake_case 是业界常识，写了等于没写
• 大段 API 文档——放个链接就行，别整段复制进来
• 经常变的信息——每次改完还要记得同步 CLAUDE.md，迟早会忘
• 一个文件一个文件地描述代码库——Claude 自己会看目录结构
• "请写出高质量的代码"——这种话约等于什么都没说

🔍 深入一步：如果某条规则特别重要，可以在前面加 IMPORTANT 或 YOU MUST 来加重语气。但别滥用——每条都加 IMPORTANT，等于没有 IMPORTANT。

5 个真实的 CLAUDE.md 完整拆解

原则讲完了，下面直接看原文。以下五份 CLAUDE.md 全部来自公开仓库，附完整内容和逐段分析。

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

Andrej Karpathy——前特斯拉 AI 总监、OpenAI 联合创始人。他的 CLAUDE.md 在 GitHub 上拿了超过 22 万个星，是目前传播最广的单个 CLAUDE.md 文件。没有任何项目信息，通篇只做一件事：约束 AI 的行为模式。

以下是完整内容（中文翻译，专业术语保留英文）：

# CLAUDE.md

减少大语言模型编程常见错误的行为准则。
可按需与项目专属指令合并使用。

取舍说明：这些准则偏向谨慎而非速度。简单任务可自行判断。

## 1. 先想再写

不要假设。不要隐藏困惑。把利弊权衡摆到台面上。

动手之前：
- 明确说出你的假设。不确定就问。
- 存在多种理解时全部列出来，不要默默选一种。
- 有更简单的方案就提出来。该反驳的时候要反驳。
- 遇到不清楚的地方，停下来，说明哪里不清楚，然后提问。

## 2. 简洁优先

用最少的代码解决问题。不做推测性的开发。

- 不做没被要求的功能。
- 不为只用一次的代码做抽象。
- 不添加没被要求的"灵活性"或"可配置性"。
- 不为不可能发生的场景做错误处理。
- 写了 200 行但 50 行就能解决——重写。

自问：一个资深工程师看了会觉得这太复杂了吗？如果会，就简化。

## 3. 精准修改

只动必须动的地方。只清理你自己造成的问题。

编辑现有代码时：
- 不要"顺手优化"旁边的代码、注释或格式。
- 不重构没出问题的部分。
- 匹配现有代码风格，即使你个人会用不同的写法。
- 发现无关的废弃代码，指出来即可，不要直接删除。

当你的改动产生了孤立引用：
- 删除因你的改动而变得多余的 import、变量和函数。
- 不要删除改动之前就已存在的废弃代码，除非被要求。

检验标准：每一行改动都应该能直接追溯到用户的请求。

## 4. 目标驱动执行

定义成功标准。循环执行直到验证通过。

把任务转化为可验证的目标：
- "加验证" → "写一组覆盖无效输入的测试，然后让它们通过"
- "修 bug" → "写一个能复现这个 bug 的测试，然后让它通过"
- "重构 X" → "确保重构前后测试都通过"

多步骤任务先列计划：
1. [步骤] → 验证方式：[检查项]
2. [步骤] → 验证方式：[检查项]
3. [步骤] → 验证方式：[检查项]

---

判断这些准则是否在起作用的三个信号：
diff 里多余的改动变少了，
因为过度设计而返工的情况变少了，
澄清性的提问出现在动手之前而不是犯错之后。

🔍 深入一步：这四条原则适合放在全局的 ~/.claude/CLAUDE.md 里，让所有项目自动生效。它和项目级 CLAUDE.md 是互补关系——全局管思维习惯，项目级管具体上下文。

案例二：Anthropic 官方 claude-code-action（42 行）

Anthropic 给 claude-code-action 写的 CLAUDE.md，是官方团队自用的真实配置。以下是完整内容翻译：

# CLAUDE.md

## 命令

bun test             # 运行测试
bun run typecheck    # TypeScript 类型检查
bun run format       # 用 Prettier 格式化
bun run format:check # 检查格式化

## 这个项目是什么

一个 GitHub Action，让 Claude 在 Issue 和 PR 中被 @claude 提及时
自动响应（标签模式），或通过 prompt 输入直接执行任务（代理模式）。
模式自动检测：提供了 prompt 就是代理模式，由评论或 Issue 事件中
的 @claude 触发就是标签模式。详见 src/modes/detector.ts。

## 怎么运行

单一入口：src/entrypoints/run.ts 统筹一切——准备阶段（认证、
权限、触发检查、分支和评论创建），安装 Claude Code CLI，
通过 base-action/ 的函数执行 Claude（直接导入，不是子进程），
然后清理（更新跟踪评论、写步骤摘要）。SSH 签名清理和令牌
撤销是 action.yml 中独立的 always() 步骤。

base-action/ 同时以 @anthropic-ai/claude-code-base-action
的名字独立发布。不要破坏它的公开 API。它从 INPUT_ 前缀的
环境变量（由 action.yml 设置）读取配置，不从 action input 直接读。

## 核心概念

认证优先级：github_token 输入（用户提供）> GitHub App OIDC 令牌（默认）。
claude_code_oauth_token 和 anthropic_api_key 是给 Claude API 用的，
不是给 GitHub 用的。令牌设置逻辑在 src/github/token.ts。

模式生命周期：src/modes/detector.ts 里的 detectMode() 选择模式名
（"tag" 或 "agent"）。触发检查和准备分发写在 run.ts 中：
标签模式调用 src/modes/tag/ 的 prepareTagMode()，
代理模式调用 src/modes/agent/ 的 prepareAgentMode()。

Prompt 构建：标签模式的 prepareTagMode() 通过获取 GitHub 数据
（src/github/data/fetcher.ts），格式化为 Markdown
（src/github/data/formatter.ts），再由 createPrompt() 写入临时文件
来构建 prompt。代理模式直接写入用户的 prompt。Prompt 包含
Issue/PR 正文、评论、diff 和 CI 状态。这是整个 Action 最重要的
部分——Claude 看到的就是这些。

## 会坑你的事

- 严格 TypeScript：启用了 noUnusedLocals 和 noUnusedParameters。
  有未使用的变量，类型检查直接报错。
- GitHub 上下文是判别联合类型：GitHubContext 是联合类型，
  访问 context.issue 或 context.pullRequest 之前必须先调用
  isEntityContext(context) 做类型收窄。
- 令牌生命周期很重要：GitHub App 令牌在早期获取，在 action.yml
  的独立 always() 步骤中撤销。如果把令牌撤销移到 run.ts 里，
  进程崩溃时它就不会执行。SSH 签名清理同理。
- 错误阶段归因：run.ts 的 catch 块用 prepareCompleted 来区分
  准备阶段失败和执行阶段失败。跟踪评论会显示不同的消息。
- action.yml 的输出引用了 Step ID：execution_file、branch_name、
  github_token 等输出引用的是 steps.run.outputs.*。
  如果改了 Step ID，必须同步更新 outputs 部分。
- 集成测试在另一个仓库（install-test），不在这里。
  本仓库的测试是单元测试。

## 代码约定

- 运行时是 Bun，不是 Node。用 bun test，不是 jest。
- moduleResolution 设为 bundler，import 不需要 .js 扩展名。
- GitHub API 调用应使用重试逻辑（src/utils/retry.ts）。
- MCP 服务器在运行时自动安装到 ~/.claude/mcp/github-{type}-server/。

这份 CLAUDE.md 最值得关注的是 "会坑你的事" 段落——六个踩坑点全部来自真实开发经验，不是预想出来的抽象规则。

案例三：Dan Abramov 的 overreacted.io（52 行）

React 核心开发者 Dan Abramov 给个人博客 overreacted.io 写的完整 CLAUDE.md，翻译如下：

# CLAUDE.md

本文件为 Claude Code 在本仓库中工作时提供指引。

## 开发命令

npm run dev        # 启动开发服务器
npm run build      # 构建生产版本静态站点
npm start          # 构建后启动生产服务器
npm run lint       # 代码检查
npm run postinstall # 依赖变更后应用补丁

## 架构概览

基于 Next.js App Router 的静态博客：这是 Dan Abramov 的个人博客，
使用 Next.js 15 和 App Router + React 19 构建为静态站点，
配置了 output: "export" 导出为静态文件。

文章结构：文章以 Markdown 文件形式存储在 /public/[slug]/index.md，
frontmatter 包含元数据（title、date、spoiler、youtube）。
每个文章目录可以包含：
- index.md — 文章正文
- components.js — 文章专属的 React 组件和可选的 Wrapper 组件
- 资源文件（图片等）

内容处理流水线：
1. app/posts.js 读取 /public/ 下的所有文章目录
2. 使用 gray-matter 解析 Markdown 的 frontmatter
3. 文章按日期排序（最新在前）
4. 单篇文章由 app/[slug]/page.js 使用 next-mdx-remote-client 渲染

MDX 处理：文章支持高级 MDX 特性：
- 带 eval 元标记的 JavaScript 代码块会执行并内联渲染
  （见 app/[slug]/mdx.js）
- 文章专属组件可从 components.js 文件导入
- 代码高亮使用 Shiki，主题为 Overnight Slumber
- 支持标题自动链接、GFM 语法、智能引号

路由结构：
- / — 首页，列出所有文章（app/page.js）
- /[slug]/ — 单篇文章页（app/[slug]/page.js）
- /atom.xml 和 /rss.xml — 生成的订阅源
  （app/atom.xml/route.js、app/rss.xml/route.js）

样式：使用 Tailwind CSS，通过自定义 CSS 变量控制主题
（--bg、--text、--title 等）。文章标题根据发布时间的远近
使用 colorjs.io 动态设置颜色。

静态生成：所有页面在构建时预生成。文章页使用
generateStaticParams() 为所有文章目录创建路由。

## 关键文件

- app/posts.js — 文章发现和订阅源生成的核心逻辑
- app/[slug]/page.js — 单篇文章渲染，含 MDX 处理
- app/[slug]/mdx.js — 可执行代码块的自定义 remark 插件
- next.config.js — 静态导出配置
- public/[slug]/index.md — 文章正文和 frontmatter
- public/[slug]/components.js — 可选的文章专属 React 组件

## 提交信息

写提交信息和 PR 描述时，像一个务实但有经验的工程师那样写。
保持简练，简要说明在做什么，点出不太直观的实现选择，但不要想太多。

不要用机器人腔调、营销术语或模糊的空话来写。你不是在写宣传册。
留下有意义的记录，让后来的人能看懂当时的决策就好。
默认读者完全有能力自己读代码。

反面示例："Refactor component for improved maintainability"
（重构组件以提升可维护性）
正确写法："Extract date formatting to lib/formatDate.ts"
（把日期格式化逻辑提取到 lib/formatDate.ts）

这份 CLAUDE.md 的独特之处在于对提交信息的强约束——不只管代码怎么写，还管 Claude 怎么表达。正反示例的对比非常具体，直接到文件名级别。

案例四：Vercel next-devtools-mcp（118 行）

Vercel 官方给 next-devtools-mcp 写的 CLAUDE.md 是大公司工程规范的代表。由于篇幅较长（118 行），这里展示最核心的段落——项目概述、架构和常见开发模式（完整文件见 GitHub 仓库）：

# CLAUDE.md

## 项目概述

这是一个 MCP 服务器，为 AI 编程助手提供 Next.js 开发工具。
服务器提供工具、提示词和资源，用于 Next.js 升级、
Cache Components 配置、文档搜索、浏览器测试和运行时诊断。
基于标准 @modelcontextprotocol/sdk 构建，使用 TypeScript 和 ES 模块。

## 命令

pnpm install                 # 安装依赖
pnpm build                   # 构建（测试前必须先构建）
pnpm dev                     # 开发模式
pnpm build && pnpm test      # 运行测试
pnpm typecheck               # 类型检查

## 架构

主入口 src/index.ts，使用标准 MCP SDK 的 stdio 传输。
服务器手动注册三类组件：
- 工具（src/tools/）：可调用的自动化函数
- 提示词（src/prompts/）：常见任务的预配置提示词
- 资源（src/resources/）：知识库文章和文档

核心工具：
- nextjs_docs：搜索 Next.js 文档和知识库
- browser_eval：Playwright 浏览器自动化
- nextjs_index：发现运行中的 Next.js 开发服务器
- nextjs_call：在 Next.js 开发服务器上执行 MCP 工具
- upgrade_nextjs_16：自动化 Next.js 16 升级引导
- enable_cache_components：Cache Components 配置 + 错误检测

遥测系统（src/telemetry/）：
通过 NEXT_TELEMETRY_DISABLED=1 禁用。
数据存储在 ~/.next-devtools-mcp/。

## 常见开发模式

新增 MCP 工具：
1. 在 src/tools/ 下创建工具文件（导出 inputSchema、metadata、handler）
2. 在 src/index.ts 的 tools 数组中导入并注册
3. 构建并测试

新增 MCP 资源：
1. 在 src/resources/ 下创建 Markdown 文件和处理器文件
2. 在 src/index.ts 的 resources 数组中导入并注册
3. 构建脚本自动复制 .md 文件到 dist/resources/

新增 MCP 提示词：
1. 在 src/prompts/ 下创建文件（导出 inputSchema、metadata、handler）
2. 在 src/index.ts 的 prompts 数组中导入并注册
3. 构建并测试

## 包发布

- 包名：next-devtools-mcp
- 包类型：ES 模块（"type": "module"）
- 包管理器：[email protected]
- prepublishOnly hook：发布前自动清理和重新构建

这份 CLAUDE.md 的核心做法是把最常执行的操作固化成标准步骤。新增工具、新增资源、新增提示词——每类操作都有确定的步骤，Claude 不需要自己推断该改哪些文件。

案例五：Karpathy llm-council（133 行）

Karpathy 自己的项目 llm-council 有一份详尽的项目级 CLAUDE.md，和四原则完全是两种写法。以下是完整翻译：

# CLAUDE.md — LLM Council 技术笔记

本文件包含技术细节、架构决策和重要的实现说明，供后续开发参考。

## 项目概述

LLM Council 是一个三阶段协商系统，多个大语言模型协同回答用户问题。
核心创新点是第二阶段的匿名同行评审——防止模型互相偏袒。

## 架构

### 后端（backend/）

config.py
- 包含 COUNCIL_MODELS（OpenRouter 模型标识符列表）
- 包含 CHAIRMAN_MODEL（负责综合最终答案的模型）
- 从 .env 读取 OPENROUTER_API_KEY
- 后端运行在 8001 端口（不是 8000，8000 被其他应用占了）

openrouter.py
- query_model()：单个模型异步查询
- query_models_parallel()：用 asyncio.gather() 并行查询
- 返回包含 content 和可选 reasoning_details 的字典
- 优雅降级：单个模型失败返回 None，继续处理成功的响应

council.py — 核心逻辑
- stage1_collect_responses()：并行查询所有参会模型
- stage2_collect_rankings()：
  - 把回答匿名化为 Response A、B、C
  - 创建 label_to_model 映射用于后续还原
  - 要求模型按严格格式评估和排名
  - 返回元组：(排名列表, 标签到模型的映射)
  - 每条排名包含原始文本和 parsed_ranking 列表
- stage3_synthesize_final()：主席模型根据所有回答和排名综合最终答案
- parse_ranking_from_text()：提取 FINAL RANKING 部分，
  兼容编号列表和纯文本格式
- calculate_aggregate_rankings()：计算所有同行评审的平均排名

storage.py
- 基于 JSON 的对话存储，保存在 data/conversations/
- 每个对话：{id, created_at, messages[]}
- 助手消息包含：{role, stage1, stage2, stage3}
- 注意：元数据（label_to_model、aggregate_rankings）不持久化，
  只通过 API 返回

main.py
- FastAPI 应用，启用 CORS 允许 localhost:5173 和 localhost:3000
- POST /api/conversations/{id}/message 额外返回元数据
- 元数据包含：标签到模型的映射和聚合排名

### 前端（frontend/src/）

App.jsx
- 主编排组件：管理对话列表和当前对话
- 处理消息发送和元数据存储
- 重要：元数据保存在界面状态中用于展示，不持久化到后端

components/ChatInterface.jsx
- 多行文本域（3 行，可调整大小）
- Enter 发送，Shift+Enter 换行

components/Stage1.jsx
- 各模型回答的标签页视图，用 ReactMarkdown 渲染

components/Stage2.jsx
- 关键功能：展示每个模型评审原始文本的标签页
- 匿名标签到模型名的还原在客户端完成
- 每条评审下方展示提取的排名，方便用户验证解析结果
- 聚合排名按平均位置和投票数展示

components/Stage3.jsx
- 主席模型综合后的最终回答
- 绿色调背景用于突出结论

样式
- 浅色主题，主色 #4a90e2
- 全局 Markdown 样式通过 .markdown-content 类定义
- 所有 Markdown 内容设 12px 内边距

## 关键设计决策

第二阶段的 Prompt 格式：
对输出格式有严格要求以确保可解析：
1. 先逐个评估每条回答
2. 提供 FINAL RANKING 标题
3. 用编号列表：1. Response C、2. Response A
4. 排名之后不要有额外文本

匿名还原策略：
- 模型看到 Response A、B、C
- 后端创建映射 {"Response A": "openai/gpt-5.1", ...}
- 前端加粗显示模型名方便阅读
- 既防止偏见又保持透明

错误处理理念：
- 部分模型失败时继续处理成功的响应
- 不因单个模型失败让整个请求失败
- 记录日志但不暴露给用户，除非全部失败

## 重要实现细节

相对导入：后端所有模块用相对导入（from .config import ...），
不用绝对导入。以 python -m backend.main 运行时必须如此。

端口配置：后端 8001，前端 5173。
改端口需同时更新 backend/main.py 和 frontend/src/api.js。

Markdown 渲染：所有 ReactMarkdown 组件必须包裹在
div.markdown-content 中，该类在 index.css 全局定义。

模型配置：模型在 backend/config.py 中硬编码。
当前默认主席模型为 Gemini。

## 常见陷阱

1. 始终在项目根目录以 python -m backend.main 运行，
   不要进入 backend 目录。
2. 前端地址必须在 main.py 的 CORS 允许来源中。
3. 模型不遵循格式时，回退正则提取所有 Response X 模式。
4. 元数据是临时的，只在 API 响应中存在，不持久化。

## 数据流概览

用户提问
    ↓
第一阶段：并行查询 → [各模型独立回答]
    ↓
第二阶段：匿名化 → 并行排名 → [评审 + 解析后排名]
    ↓
聚合排名计算 → [按平均位置排序]
    ↓
第三阶段：主席模型综合全部上下文
    ↓
返回 {stage1, stage2, stage3, metadata}
    ↓
前端标签页展示 + 验证界面

这份 CLAUDE.md 和四原则形成了清晰的分工——四原则管思维方式（放全局），llm-council 的 CLAUDE.md 管项目的具体面貌（放项目级）。两种 Karpathy 都在用。

两种流派

两种都有各自的价值，实践中建议两种结合使用。

中文开发者的真实 CLAUDE.md——GitHub 和 X 上的一手案例

前面拆解的五个案例以英文项目为主。中文开发者的 CLAUDE.md 写得怎么样？他们在实际项目里放了什么内容？以下是在 GitHub、X 和中文技术社区中检索到的最有参考价值的几份。

overtrue（安正超）的 CLAUDE.md——中文开发者的标杆

安正超是 EasyWeChat 的作者，PHP/Laravel 领域的知名开发者。他公开了一份纯中文的 CLAUDE.md，结构清晰，六个板块各解决一类问题。以下是完整内容（原文即为中文）：

# 开发指南

## 严格禁止的操作

### Git 操作限制
- 绝对禁止执行 git reset、git revert、git rebase、git restore 等回滚命令
- 只允许使用 git log、git status、git diff 等安全操作来对比文件变化以及恢复文件内容
- 禁止删除或修改 .git 目录
- 任何 git 操作前必须得到用户明确许可

### 文件系统操作限制
- 绝对禁止执行 rm -rf 命令
- 禁止删除目录，特别是项目根目录或重要目录
- 删除文件前必须明确告知用户并得到许可

## 沟通语言
重要：请使用与用户相同的语言进行所有沟通和交流。

## 理念

### 核心信念
- 渐进式进展优于大爆炸式改动 ——小改动，保证能编译通过并测试通过
- 从现有代码中学习 ——实施前先研究和规划
- 务实优于教条 ——适应项目实际情况
- 清晰的意图优于聪明的代码 ——保持朴素和直白

### 简单意味着
- 每个函数/类单一职责
- 避免过早抽象
- 不要耍小聪明 ——选择朴实的解决方案
- 如果需要解释，那就太复杂了

## 流程

### 1. 规划与分阶段
将复杂工作分解为 3-5 个阶段。记录在 IMPLEMENTATION_PLAN.md 中。

### 2. 实施流程
1. 理解 ——研究代码库中的现有模式
2. 测试 ——先写测试（红灯）
3. 实现 ——最少代码通过测试（绿灯）
4. 重构 ——在测试通过的情况下清理代码
5. 验证 ——确保编译通过且测试运行
6. 更新 TODO ——标记已完成的任务并总结成就
7. 提交 ——使用清晰的消息链接到计划

### 3. 遇到困难时（尝试 3 次后）
关键：每个问题最多尝试 3 次，然后停止。

## 编译错误处理
基本原则：永远不要删除代码来绕过编译错误。修复根本原因。

正确做法：错误发生 → 理解根本原因 → 研究正确解决方案 → 修复实际问题
错误做法：错误发生 → 删除有问题的代码 → 编译通过 ❌

## 决策框架
1. 可测试性 ——我能轻松测试这个吗？
2. 可读性 ——6 个月后有人能理解这个吗？
3. 一致性 ——这与项目模式匹配吗？
4. 简单性 ——这是最简单的可行解决方案吗？
5. 可逆性 ——以后改变有多难？

## 质量门槛

### 完成的定义
- 测试编写并通过
- 代码遵循项目约定
- 没有代码检查器/格式化器警告
- 提交消息清晰
- 实现与计划匹配
- 没有不带 issue 编号的 TODO

这份 CLAUDE.md 最值得注意的一点：每一条规则都对应一个具体的、已经发生过的问题。没有"本项目用 PHP"这类冗余声明，没有"请写高质量代码"这类不可验证的泛指令。"禁止删代码绕过编译错误"——这条规则的存在本身就说明 Claude 真的做过这件事。

claude-scholar——学术研究场景的 CLAUDE.md（172 行）

claude-scholar 是一个 4200 星的学术研究助手项目，提供了中英双语对照的 CLAUDE.md。以下是中文版完整内容（原文即为中文，部分段落保留英文术语）：

# Claude Scholar 核心指令

## 默认表达 Skill

在可用时，优先读取 ~/.claude/skills/expression-skill/SKILL.md，
将已安装的 expression-skill 作为默认表达层。

在回答非简单请求前，用它约束回答方式：
- 结论先行
- 以用户当前目标为中心
- 给出具体证据、路径、数量、命令和验证
- 尽早说明风险、不确定性和破坏性边界
- 对长任务给出可见 roadmarks
- 准确说明改了什么、没改什么
- 最后给最小有用下一步

## 身份定位

Claude Scholar 是一个用于学术研究和软件开发的半自动研究助手。
它的职责是帮助用户完成文献整理、代码开发、实验、分析、报告、
写作和长期项目知识维护。它不替代研究者的判断。
始终把人的决策放在中心。

## 沟通默认规则

- 默认使用英文回答。用户明确要求中文或偏好中文时使用中文。
- 技术术语准确，优先使用标准英文术语。
- 回答优先采用：1. 直接答案或可执行路径 → 2. 证据或验证方式 → 3. 限制、假设或下一步
- 保持简洁。除非背景信息会改变答案，否则不额外展开。
- 避免模糊表达和内部黑话。使用直接、清楚的语言。

## 写作纪律

- 每句话只表达一个具体信息点。
- 写之前先问自己：我具体想说什么？这是最清楚的说法吗？能不能说得更具体？
- 删除不能提供有用信息的句子。
- 不要使用 align、close the loop、optimize the workflow、make it robust 等模糊说法，除非同时说明具体动作。

## 澄清规则

- 如果用户请求有歧义，先问一个简短的澄清问题。
- 当存在多个合理解释时，不要默默选择其中一个。
- 如果可以基于低风险假设继续执行，应简短说明该假设。

## 执行优先级

- 先核对事实，再给结论。
- 修改文件、代码、文档或配置后，要做验证。
- 改动应小、可回滚、易审查。
- 在执行破坏性或高风险操作前先确认。
- 对长时间运行的命令，不要静默等待；要汇报当前步骤、已处理数量、输出路径和下一个检查点。

## 计划规则

- 对非简单任务，默认将 planning-with-files 作为 planning 和 progress tracking 的持久层。
- 默认文件模式：
  - task_plan.md：记录 phases、status、decisions 和 blockers
  - notes.md：记录 findings、evidence 和中间 research
- 只有当新证据改变任务时，才修改计划。
- 当范围较大时，用优先级排序：P0 现在必须处理 / P1 这一轮应该处理 / P2 可以稍后处理

## 最小路由规则

当任务明确匹配时，优先使用对应的本地 Skill：
- 多步骤任务、progress tracking → planning-with-files
- 研究启动、gap analysis、文献规划 → research-ideation
- 严格实验分析、统计、科研图表 → results-analysis
- 论文草稿、学术写作 → ml-paper-writing
- 审稿回复、rebuttal 写作 → review-response

## 工作方式

- 优先使用已有本地 Skills、Commands 和工作流，再考虑新路径。
- 对复杂任务，先列具体步骤，再执行。
- 实施后运行最小但有意义的验证。
- 如果被阻塞，说明具体阻塞点，以及下一步怎么解除。
- 给建议时，明确推荐哪条路径，并说明 tradeoff。

## 交付格式

对较完整的任务，默认用这个结构：

结论：
我做了：
我检查了：
风险/限制：
下一步建议：

这份 CLAUDE.md 的独特之处在于三点：一是明确的身份边界（"不替代研究者判断"），二是写作纪律中的模糊词黑名单（禁用 align / close the loop 等 AI 套话），三是固定的交付格式——每次交付都按统一结构输出，不用猜 Claude 做到了哪一步。

React.dev 官方——极简主义的代表（42 行）

React 官方文档站 的 CLAUDE.md 只有 42 行，是所有案例中最短的。以下是完整翻译：

# CLAUDE.md

本文件为 Claude Code 在本仓库中工作时提供指引。

## 项目概述

这是 React 文档网站（react.dev），使用 Next.js 15.1.11 和 React 19 构建。
文档以 MDX 格式编写。

## 开发命令

yarn build         # 生产环境构建
yarn lint          # 运行 ESLint
yarn lint:fix      # 自动修复 lint 问题
yarn tsc           # TypeScript 类型检查
yarn check-all     # 一次性运行 Prettier、lint:fix、tsc 和 rss

## 项目结构

    src/
    ├── content/           # 文档内容（MDX 文件）
    │   ├── learn/         # 教程/学习类内容
    │   ├── reference/     # API 参考文档
    │   ├── blog/          # 博客文章
    │   └── community/     # 社区页面
    ├── components/        # React 组件
    ├── pages/             # Next.js 页面
    ├── hooks/             # 自定义 hooks
    ├── utils/             # 工具函数
    └── styles/            # CSS/Tailwind 样式

## 代码约定

### TypeScript/React
- 只使用函数组件
- 样式用 Tailwind CSS

### 文档风格

编辑 src/content/ 下的文件时，对应的 Skill 会自动推荐：
- src/content/learn/ — 教程页的结构和语气
- src/content/reference/ — 参考文档页的结构和语气

需要使用 MDX 组件（DeepDive、Pitfall、Note 等）时，调用 /docs-components。
需要使用 Sandpack 代码示例时，调用 /docs-sandpack。

完整风格指南见 .claude/docs/react-docs-patterns.md。
代码格式化用 Prettier（配置在 .prettierrc）。

这份 CLAUDE.md 代表了一种极端策略：CLAUDE.md 本身只做最薄的一层索引，把详细规则交给 Skill 和 slash command 来承载。教程页和参考文档页的语气差异不写在 CLAUDE.md 里，而是由 Skill 根据编辑的文件路径自动切换。如果你的项目配置体系足够完善，这种极简写法反而最好维护。

X 上的共识：一句话顶一千行配置

在 X 上的讨论中，中英文社区对 CLAUDE.md 形成了几个高度一致的共识：

"从空文件开始。" 陈成（@chenchengpro，610 赞）的建议是：别从模板开始，从空白文件开始。每次你对 Claude 说了同一句话两遍以上，就把那句话写进 CLAUDE.md。这样积累出来的文件，每一行都是实打实有用的。

"400 行砍到 150 行，一切都好了。" Axel Bitblaze（@Axel_bitblaze69，1900 赞）连续使用 Claude Code 两个月后的经验总结：他的 CLAUDE.md 一度扩展到 400 行，结果 Claude 开始随机忽略部分指令。精简到 150 行之后，指令遵循率明显回升。

Claude Code 之父的做法出乎意料地简单。 宝玉（@dotey，1200 赞）分享了 Boris Cherny（Claude Code 核心作者）的做法：整个团队维护一个 CLAUDE.md，提交到 Git，每周有人往里加内容。规则只有一条——"每次看到 Claude 做错了什么，就把'别这样做'写进去"。宝玉管这叫 "复利工程"——CLAUDE.md 越养越好，Claude 犯的错越来越少。

Apple 都在用 CLAUDE.md。 2026 年最大的新闻之一是 Apple 在 Support App 的更新包里意外泄露了内部 CLAUDE.md 文件（@aaronp613，13500 赞），证明 Apple 内部团队在用 Claude Code 开发应用。Apple 紧急发了一个补丁移除这些文件。有人评论说："我们以前担心代码里泄露 API 密钥，现在还要担心泄露公司的 AI 工作方式。"

阶跃星辰总结的四条反模式

阶跃星辰（Step AI）在一份 2100 星的最佳实践文档里总结了四条 CLAUDE.md 反模式，每一条都很实际：

1. 别一上来就设限制。 正确的做法是从 Claude 实际犯的错误里一条条加——先用，发现问题，再写规则。
2. @ 引用不能无脑用。 盲目 @ 引用一个文件，每次会话都加载，浪费上下文。只写文件路径又没用，Claude 不会自己去看。正确做法是写清楚"什么时候该看这个文件、看了能得到什么"。
3. 不要只说"禁止"，要给替代方案。 光说"禁止用 Redux"，Claude 不知道用什么代替，只能在 Redux 和其他选项之间纠结。写成"禁止 Redux，用 Zustand"才有效。
4. CLAUDE.md 写太长了，说明你的工具该简化了。 如果你需要用半页纸解释一个 CLI 的用法，问题不在 CLAUDE.md，在那个 CLI。写个 bash 包装器把它简化掉，比在 CLAUDE.md 里写说明书强。

从这些案例里，能提炼出什么

看了这么多真实的 CLAUDE.md，有几件事变得很清楚：

好的 CLAUDE.md 都很短。 React.dev 52 行，Karpathy 65 行，Anthropic 官方 55 行，安正超那份也不到 100 行。没有一个超过 200 行的。

好的 CLAUDE.md 都是从实际遇到的问题中积累出来的。 Boris 的做法是每次 Claude 犯错就加一条规则。安正超的"禁止删代码绕过编译错误"明显对应一个真实发生过的场景。这些规则不是事先预想的，而是在使用中逐步沉淀的。

好的 CLAUDE.md 分两层写。 全局放思维方式（Karpathy 四原则），项目级放具体上下文（命令、架构、踩坑点）。两层各管各的，互不干扰。

好的 CLAUDE.md 不说废话。 不写 Claude 看代码就知道的事，不写标准编程约定，不写"请写高质量代码"。每一行的检验标准是：删掉这行，Claude 会不会犯错？不会就删。

如果你现在要开始写，最简单的路径是：

1. 先从空文件开始
2. 正常用 Claude Code 干活
3. 每次它犯错或者你重复说了同一句话，写进 CLAUDE.md
4. 一周后回头看，删掉已经不需要的
5. 如此反复

这种方式写出来的 CLAUDE.md，每一行都有来历，比任何模板都好用。

CLAUDE.md 的演变规律——从膨胀到精简

在给出我们自己的方案之前，有一件事值得先说。

调研中发现，几乎每个深度使用 Claude Code 的人都经历了同一条路径：先往 CLAUDE.md 里不断加东西，然后发现超过某个临界点之后效果反而变差，最终转向精简。

最典型的是 Pawel Jozefiak——用了 Claude Code 10 个月、跑了超过 1000 次会话之后，他的 CLAUDE.md 经历了四次重写：3 行 → 200 行（边缘情况清单）→ 471 行（把所有文档内联进来）→ 61 行（精简核心 + 外部参考文档按需加载）。

他总结的关键转折是：CLAUDE.md 不是百科全书，是路由层。它告诉 Claude"你是谁、怎么做决策、遇到具体问题去哪查"，具体的操作细节放在外部文档里按需读取。

这和我们实际运营知识库的经验完全一致——我们的 CLAUDE.md 就是一个路由表：身份定位写在最前面，行为准则按主题分块（语言→工具→编码→交付），工具和导航占最大篇幅。禁令不是单独的开头段落，而是融在每条规则里——"包管理 uv（禁止 pip/poetry/conda）"，做什么和不做什么写在同一句话里。

另一个被多个独立用户重复验证的规律叫复利效应——Pawel 叫它"指令设计"（instruction design），Matt Stockton 叫它"复合效应"（compounding effect），Boris（Claude Code 核心作者）的团队叫它"每次犯错就加一条"。核心是同一件事：CLAUDE.md 不是一次性写好的产品，而是一个持续积累的资产。它越养越好，Claude 犯的错越来越少。

理解了这两个规律——路由层思维和复利效应——下面的方案就容易理解了。

我们的方案：6 个场景的 CLAUDE.md

以下六份 CLAUDE.md 的结构都遵循同一个思路：先说你是谁和怎么做事，把禁令融进每条规则里，最后说交付标准。这不是随便排的——它反映了 CLAUDE.md 被读取时的实际优先级：Claude 先理解角色定位，再理解工作方式，最后才看具体约束。

内容创作者的 CLAUDE.md

内容创作最核心的问题不是"写不好"，而是"写得不像同一个人"。换一个对话窗口，品牌声音就丢了。这份 CLAUDE.md 管的是创作的工作方式和品牌一致性——平台的具体参数放在各自的参考文档里。

# 内容创作工作台

## 身份

- 定位：[一句话，如"用大白话讲清楚普通人怎么用 AI 工具"]
- 读者：[如"25-40 岁职场人，对 AI 感兴趣但没有技术背景"]
- 语气：专业但不学术，有态度但不抬杠
- 第一人称：我（禁用"笔者""小编""本文将为您"）
- 签名表达：[列出品牌反复出现的标志性短语]
- 禁用词：赋能、抓手、闭环、底层逻辑、降维打击、认知升级

## 创作流程

1. 选题评估——先回答三个问题再动手：
   读者为什么要看？我有什么独特角度？现在是不是最好的时机？
2. 素材研究——读完所有相关素材再写，中途发现不够就停下来补素材，
   不要边写边找（写到一半补料会打断文章的整体逻辑）
3. 大纲——先列 H2 大纲，每个 H2 回答读者一个具体问题。大纲没确认不动笔
4. 初稿——按大纲写，先求完整不求完美
5. 自检——每段问自己：删掉这段，读者会少知道一件事吗？不会就删。
   每个数据问自己：来源是什么？没有来源的统计数字直接删除
6. 终稿——精简、润色、补配图描述

## 写作方式

- 先说结论再展开，铺垫不超过 3 句话
- 数据和具体案例优先于观点和形容词
- 专业术语第一次出现时用括号解释，之后直接用
- 一段只讲一件事
- 能用一句话说清楚的不写成长段
- 连续三个以上排比句——删掉多余的，留最好的两个

## 平台适配

各平台的具体参数在参考文档中，创作时按需读取：
- 公众号 → @docs/wechat-rules.md
- 小红书 → @docs/xiaohongshu-rules.md
- 博客 SEO → @docs/blog-seo-rules.md
核心稿先写好，再按目标平台裁剪，不要一开始就针对某个平台写

## 质量标准

一篇内容"写完了"的定义：
- 读一遍不用回头重读任何一句
- 每个观点有支撑（数据 / 案例 / 逻辑推导）
- 开头三行能让不认识我的人想继续看
- 配图位置已标注
- 没有触碰禁用词

## 交付

每篇输出：标题（3 个备选）+ 正文（Markdown）+ 摘要（120 字）
+ 配图描述 + 适配平台标注

视频创作者的 CLAUDE.md

视频和文字是两套逻辑。写文章可以写长句、用括号注释、插脚注——视频不行，观众听一遍就过去了，听不懂不会倒回来。这份 CLAUDE.md 管的是"怎么用 Claude 管理视频项目"——从选题到脚本到发布的整个链条，不是某一个平台的参数。

# 视频创作工作台

## 频道身份

- 频道名：[你的频道名]
- 领域：[如"AI 工具实战教程"]
- 观众：[如"想用 AI 提升效率的职场人"]
- 风格：[如"真人出镜 + 屏幕录制，节奏紧凑"]
- 差异化：[你比别的频道强在哪——每条视频都要体现这一点]
- 口播人称：用"你"不用"您"
- 口播节奏：每句 15-20 字，断句处留换气空间

## 选题评估

做之前先回答五个问题：
1. 搜索验证——有人在搜这个话题吗
2. 竞品评估——现有视频我能超越吗
3. 差异化——我在这个话题上有独特经验吗
4. 时效性——现在做是不是最好的时机
5. 系列潜力——能延展成系列吗
至少三个是肯定的，才值得做

## 脚本工作流

1. 定核心信息——看完视频，观众记住的一句话是什么
2. 列大纲——每段围绕一个知识点，段间有逻辑过渡
3. 写 hook——开头 15 秒直接兑现核心承诺（禁止放铺垫、自我介绍、
   订阅提示。公式：反常识 / 预告高潮 / 数字承诺）
4. 写正文——每段 2-3 分钟，段尾设转折或小高潮
5. 写结尾——回扣核心信息 + 行动号召 + 下期预告
6. 标画面——每段口播配 [画面提示]
7. 默读——嘴上说不顺的地方改掉。文章能用的长句视频不能用

脚本语言：不用"接下来我将为大家介绍"等套话。
过渡用"那接下来""这里有个关键的点"，不用"首先、其次、最后"。
数据和案例不编造（播放量、订阅数、收入等）

## 平台元数据

各平台的标题/描述/标签参数在参考文档中：
- YouTube → @docs/youtube-metadata.md
- B 站 → @docs/bilibili-metadata.md
通用原则：标题含关键词 + 数字或疑问，描述前两行是核心概括

## 文章转脚本

文章逻辑和视频逻辑不一样——文章可以长句、括号注释、脚注，
视频不行。转化时必须重新组织，不能直接把文章段落当口播稿念

## 交付

每条视频输出：
1. 选题评估（五问）
2. 核心信息（一句话）
3. 完整脚本（含 [画面提示]）
4. 标题（3 备选）+ 缩略图文字（≤6 字）
5. 描述区（含时间戳）

独立开发者/一人公司的 CLAUDE.md

一个人管整盘生意和在团队里只负责一块代码，CLAUDE.md 的写法完全不同。团队项目的 CLAUDE.md 通常只管代码——技术栈、架构、命令。一人公司的 CLAUDE.md 要管的是整个业务的运转逻辑：哪些产品、怎么部署、怎么决策、钱花在哪。Claude 需要看到全局，才不会在 A 产品的上下文里做出 B 产品的决定。

# 一人公司工作台

## 业务全景

- 产品 A（主营）：[产品名 + 一句话定位 + 技术栈]
- 产品 B（副线）：[产品名 + 一句话定位 + 技术栈]
- 内容渠道：[如"公众号 + 小红书 + 个人博客"]
- 变现方式：[如"订阅制 + 一次性购买"]
- 各产品细节在各自的 CLAUDE.md 中，本文件只管全局决策

## 工作理念

- 渐进式改动优于大范围重构
- 能用现有工具解决的不造新轮子（认证/支付/邮件/存储用 SaaS API）
- 每次只改一个东西，确认没问题再改下一个
- 遇到问题尝试 3 次后停下来，说明卡在哪里
- 做之前先说打算怎么做，等我确认
- 先验证再建设——用最小成本验证想法，验证通过后再投入开发
- 功能优先级：获客 > 留存 > 变现（先有人来，再让人留下，最后收钱）

## 安全边界

- git reset / revert / rebase / rm -rf 等不可逆操作——禁止执行
- 密钥和令牌——走环境变量或凭据管理，不硬编码到代码和日志里
- 生产数据库——禁止命令行直连执行写操作
- 删除文件或目录——先告知我，得到确认后再执行
- 涉及付费的操作（发邮件、调 API、部署到生产）——先确认

## 决策框架

遇到多个方案时按这个顺序排：
1. 能不能在 1 小时内验证？能就先试
2. 是不是可逆的？可逆就大胆做
3. 影响面有多大？只影响我一个人就直接做
4. 有没有更简单的方案？有就换简单的

## 角色切换

一人公司需要在不同角色间切换，每个角色的规范不同：
- 写代码 → 对应产品的 CLAUDE.md
- 写内容 → 内容创作工作台的 CLAUDE.md
- 做分析 → 数据分析工作台的 CLAUDE.md
开始一个任务前告诉我当前角色，我切换到对应模式

## 部署和运维

- 标准流程：本地 → GitHub → CI 测试 → 合并 main 自动部署
- 数据库变更：开发环境先跑迁移，确认后再合并
- 出问题：先回滚到上一个正常版本，再排查原因
- 具体配置 → @docs/ops.md

翻译工作者的 CLAUDE.md

翻译项目的 CLAUDE.md 管的不是"某个词怎么翻"——那是术语表的事。它管的是翻译的工作原则、质量标准和协作流程：什么时候该问，什么时候不该猜，遇到不确定的术语怎么处理，翻完之后怎么自检。

# 翻译工作台

## 翻译原则

- 信达雅优先级：技术文档 信 > 达 > 雅（准确第一）；
  文学/营销内容 达 > 雅 > 信（可读第一）
- 不逐字翻译，按中文的思维方式重新组织句子
- 被动语态转主动："This can be achieved by..." → "可以通过...实现"
- 名词化表达还原为动词："the implementation of" → "实现"
- 三层以上从句的长句拆成 2-3 个中文短句
- 判断标准：读出来像不像中国人说的话。不像就重写
- 代码块、命令行、URL、文件路径中的内容不翻译

## 术语管理

- 术语表：glossary.md，格式 | 英文 | 中文 | 领域 | 备注 |
- 新术语查表，表里没有就给一个译法同时加入表中
- 同一术语全文只用一个译法（发现不一致的以术语表为准去改）
- 专有名词保留英文，首次出现括注中文
- 查询优先级：ISO/国标 → 行业通行译法 → 微软术语门户

## 工作流程

1. 通读——翻译前先通读整章，理解上下文再动手
2. 初译——按段落翻，一边翻一边更新术语表
3. 回读——翻完回读一遍，检查前后风格和术语一致性
4. 自检——对照上一章的译文风格，确认连贯

## 遇到不确定的怎么处理

- 术语拿不准 → 标注 [待确认]，给出倾向的译法和理由
- 原文含糊 → 标注 [原文含糊]，给出两种可能的理解
- 文化差异 → 标注 [文化适配]，说明背景和本地化建议
原则：不猜、不绕过、不默默选一个。把不确定的标出来比翻错更重要

## 格式

- Markdown 结构不动（标题、列表、代码块、链接）
- 中英文之间加空格，数字和中文之间加空格
- 表格和图表标注完整还原
- 不省略原文内容，不添加原文没有的信息

## 交付

每章输出：译文 + 本章新增术语 + 标注汇总（待确认/原文含糊/文化适配）
+ 风格一致性自检结果

数据分析师的 CLAUDE.md

数据分析的 CLAUDE.md 不应该是一份 matplotlib 参数手册——那些参数放在一个 Python 初始化脚本里就行了。它应该管的是分析的工作方法：先做什么后做什么、怎么选择统计方法、结果怎么呈现、怎么保证别人能复现你的分析。

# 数据分析工作台

## 分析方法论

1. 先看数据再选方法——拿到数据先做描述性统计和分布图，
   根据数据实际分布选择统计方法，不预设方法往数据上套
2. 正态性检验（Shapiro-Wilk）是分水岭——
   正态 → 参数检验；非正态 → 非参数检验
3. 多重比较必须校正（Bonferroni 或 FDR），不校正的结果不可信
4. 效应量和置信区间优先于 p 值——p 值说"有没有差异"，
   效应量说"差异有多大"，后者才是决策需要的信息
5. 一图一主题——每个图表只回答一个问题

## 数据管理

- 原始数据 data/raw/（只读，不动）
- 处理结果 data/processed/
- 每步处理记录在 data/processing_log.md（做了什么、影响多少行、
  缺失值策略和理由）
- 变量命名 snake_case，自解释（user_age 不是 ua）
- 参数不硬编码到脚本里，走 config/ 配置文件
- 路径全部用相对路径

## 可视化

- 图表类型由数据关系决定：
  趋势 → 折线图，对比 → 柱状图，分布 → 直方图/箱线图，
  关系 → 散点图，成分 → 堆叠柱状图（饼图仅 ≤5 类）
- 视觉参数（配色、字号、输出格式）统一放 config/plot_style.py，
  脚本开头引用，不在每个脚本里单独设
- 科研柱状图含误差线（标注 SD 或 SEM）
- 每张图必须有标题、坐标轴标签（含单位）、图例

## 报告标准

- APA 格式：*M* = 3.45, *SD* = 1.23, *t*(58) = 2.41, *p* = .019, *d* = 0.82
- 描述方向："A 组显著高于 B 组"，不是"差异显著"
- 小数全文统一 2 位，百分比 1 位
- 图标题在图下方，表标题在表上方

## 遇到数据问题

- 缺失值超 30%——先报告，让我决定是否继续
- 异常值——先可视化确认是真异常还是测量误差，不默默删
- 样本量不够——如实说明，给出需要多大样本量的估算
把问题如实摆出来，比给一个漂亮但不可靠的结论重要

## 可复现性

- 每个脚本顶部注释：输入、输出、用途
- 随机种子统一 42
- 依赖锁在 pyproject.toml，用 uv 管理
- 任何人在任何电脑上跑 uv run python scripts/{name}.py 得到相同结果
- 探索用 Jupyter Notebook，正式产出写 .py 脚本

## 交付

每次分析输出：结论（一段话）+ 方法说明 + 关键图表 + 统计报告（APA）
+ 数据质量说明 + 可复现性声明（脚本路径 + 运行方式）

这六份 CLAUDE.md 的共同结构

回过头看，这六份和前面拆解的 Karpathy、安正超、Anthropic 那些案例遵循同一套底层逻辑。结构都是这个顺序：

1. 你是谁 / 全景——先让 Claude 理解角色和上下文
2. 怎么做事——工作流程、方法论、决策框架
3. 边界和约束——融在每条规则里（"用 uv 管理依赖"比"禁止 pip"信息密度更高，同一句话既说了该做什么又说了不该做什么）
4. 遇到问题怎么处理——不确定时标注、卡住时停下来
5. 交付标准——做完了长什么样

关键在第三点——把约束融进规则里，而不是单独拎出来放最前面。如果 CLAUDE.md 一打开就是一长串"禁止 A、禁止 B、禁止 C"，Claude 看到的第一印象就是"这个用户很在意我不要犯错"，而不是"这个项目需要我做什么"。先理解角色和做事方式，约束自然跟在后面，更符合 Claude 处理上下文的方式。

另一个值得注意的点：平台的具体参数不放在 CLAUDE.md 里。公众号排版多少像素、小红书封面多大尺寸、YouTube 标签要几个——这些信息当然有用，但它们变化快、只在特定场景下用到。放在 docs/ 目录的参考文档里，CLAUDE.md 用 @docs/wechat-rules.md 按需引用就好。CLAUDE.md 本身只管不变的工作原则。

这套结构适用于任何场景——不管你写公众号还是做数据分析，CLAUDE.md 的职责都是同一个：把你脑子里的工作方式写成 Claude 能理解和执行的规则。

两种设计模式：规则内嵌式 vs 路由式

到目前为止看到的所有案例，其实分成了两种截然不同的设计模式。小项目和大项目的 CLAUDE.md 写法完全不同——搞清楚你该用哪种模式，比纠结具体写什么更重要。

模式一：规则内嵌式

把所有规则直接写在 CLAUDE.md 里，一个文件解决一切。

项目根目录/
└── CLAUDE.md     ← 身份 + 工作方式 + 约束 + 交付标准，全在这里

前面展示的 Karpathy 四原则、Dan Abramov 的 overreacted.io、React.dev 官方都是这种模式——一个文件，几十行，读完就知道怎么干活。

适合的场景：

• 个人项目或小团队项目
• 单一技术栈（不存在"前端规则和后端规则混在一起"的问题）
• 规则总量不超过 200 行
• 项目结构简单，不需要按模块区分规则

优点：简单、直观、维护成本低。打开一个文件就能看到全部。

缺点：项目复杂度上升之后，文件会越来越长。超过 200 行 Claude 的遵循率明显下降（前面 Pawel 和 Axel 的经验都验证了这一点）。

模式二：路由式

CLAUDE.md 本身只做索引和路由，真正的内容分散在各层级的子文件里，Claude 按需加载。

~/.claude/CLAUDE.md                    ← 全局层：身份 + 跨项目的思维方式
项目根目录/
├── CLAUDE.md                          ← 项目层：全景 + 行为准则 + 工具路由表
├── .claude/rules/
│   ├── frontend.md                    ← 按路径懒加载：只处理前端文件时生效
│   └── backend.md                     ← 按路径懒加载：只处理后端文件时生效
├── docs/
│   ├── architecture.md                ← 被 @import 引用的参考文档
│   └── platform-rules/
│       ├── wechat.md                  ← 公众号具体规则
│       └── youtube.md                 ← YouTube 具体规则
├── 子目录A/CLAUDE.md                   ← 子模块自己的规则（按需加载）
└── 子目录B/CLAUDE.md                   ← 子模块自己的规则（按需加载）

这是我们实际在用的方式。我们的知识库有 100 多个子目录，每个目录都有自己的 CLAUDE.md，根目录的 CLAUDE.md 是一张路由表——列出所有子目录的触发词和入口路径，Claude 根据当前任务自动找到该读哪个子目录的规则。

适合的场景：

• 大型项目、Monorepo、知识库
• 多模块/多技术栈混合
• 规则总量远超 200 行
• 需要多人协作维护
• 规则会随时间持续增长

优点：

• CLAUDE.md 保持精简（我们的根 CLAUDE.md 是路由表，Claude 只加载当前任务相关的规则，不浪费上下文）
• 各模块的规则独立维护，改一个模块不影响其他模块
• 可以利用 .claude/rules/ 的 paths: 机制做按路径懒加载——前端规则只在编辑前端文件时生效，后端规则同理

缺点：初始设计成本高，需要提前规划层级结构。小项目用这种模式是杀鸡用牛刀。

路由式 CLAUDE.md 的设计要点

如果你决定用路由式，有几个实际操作中的关键点：

第一，根 CLAUDE.md 只放三类信息：身份定位、行为准则、导航路由。 不放具体的技术细节。比如"用 TypeScript strict 模式"这种规则放在对应子目录的 CLAUDE.md 或 .claude/rules/ 里，根 CLAUDE.md 只负责告诉 Claude "你是谁、怎么做事、遇到 X 话题去哪个目录找详细规则"。

第二，用触发词做路由。 在根 CLAUDE.md 里列一张触发词表：

| 触发词 | 去哪读 |
|--------|--------|
| 前端、组件、页面 | src/frontend/CLAUDE.md |
| 后端、API、数据库 | src/backend/CLAUDE.md |
| 部署、运维、监控 | docs/ops.md |
| 写文章、内容创作 | docs/content-rules.md |

Claude 看到你说"帮我改一下前端组件"，就知道该去 src/frontend/CLAUDE.md 读具体规则。

第三，用 @import 引用而不是复制。

# 项目 CLAUDE.md

## 架构
@docs/architecture.md

## 编码标准
@docs/coding-standards.md

被引用的文件独立维护，CLAUDE.md 始终只是一个索引。最大支持 4 层嵌套。

第四，.claude/rules/ 做条件加载。 这是路由式最强的机制——规则文件加上 paths: 前置数据之后，只在 Claude 读到匹配路径的文件时才生效：

# .claude/rules/frontend-components.md
---
paths:
  - "src/components/**/*.tsx"
---

组件用 forwardRef 包裹。
Props 接口必须导出。
样式用 Tailwind，不用内联。

Claude 编辑后端代码时，这些前端规则根本不会出现在上下文里。

两种模式可以混合

实际上很多人是混合使用的。比如：

• 全局 ~/.claude/CLAUDE.md：内嵌式，放 Karpathy 四原则这种通用行为约束
• 项目 ./CLAUDE.md：路由式，做索引和导航
• 子目录 ./src/CLAUDE.md：内嵌式，该模块的具体规则直接写

Karpathy 本人就是这么做的——全局放四原则（内嵌式），llm-council 项目放详细架构和踩坑点（内嵌式，因为项目不大），两层各管各的。

选哪种模式取决于一件事：你的规则加起来超过 200 行了吗？ 没超过，内嵌式就够了。超过了，开始往路由式迁移——把不常用的、只对特定模块生效的规则拆出去。

CLAUDE.md 不是唯一的配置机制

Claude Code 还有 Skills 和 Hooks，三个各管一件事：

三者的关系是：CLAUDE.md 管"你应该怎么做"，Skill 管"具体按什么步骤做"，Hook 管"不管你怎么想，这件事一定会自动发生"。

🔍 深入一步：如果 Claude 反复忘记某件事（比如写完代码不跑格式化），在 CLAUDE.md 里加十遍强调也没用——换成 Hook。Hook 是脚本，写文件后自动执行，不存在"忽略"的可能。CLAUDE.md 是软约束，Hook 是硬约束。

从零开始：第一周怎么写出一份好用的 CLAUDE.md

如果你现在还没有 CLAUDE.md，或者只有 /init 生成的默认版本，按这个节奏来：

第一天：从空文件开始，只写三行

# [你的项目名]

交互语言：简体中文

就这些。然后正常用 Claude Code 干活。不要试图一次写完。

前三天：每次被 Claude 气到，就加一条

Claude 给你写了 class 组件？加一条"只用函数组件 + hooks"。Claude 用了 npm？加一条"包管理用 pnpm"。Claude 写了一个 500 行的大函数？加一条"函数不超过 30 行"。

每条规则的来历都很清楚——它不是你预想出来的，是 Claude 实际犯的错让你补上去的。

第一周结束：回头整理一遍

这时候你的 CLAUDE.md 大概有 20-40 行，全是实战中积累的规则。做一次整理：

• 把同类规则归到一起（命令归命令、代码规范归代码规范）
• 删掉 Claude 已经不会犯的错（有些问题加了一次规则之后就不再出现了，规则可以删）
• 检查有没有矛盾的规则

一个月后：判断需不需要升级到路由式

如果你的 CLAUDE.md 还在 100 行以内，保持内嵌式就好。如果已经超过 200 行，开始把不常用的规则拆到 .claude/rules/ 或 docs/ 里，CLAUDE.md 只留索引。

持续维护：复利积累

每次代码审查发现 Claude 本该知道的信息、每次你在新会话里重复说了同样的纠正——都是往 CLAUDE.md 里加一条的信号。反过来，每次你加了规则但 Claude 的行为没有改善——考虑这条规则是不是太模糊了，或者太长了被淹没了。

这就是前面提到的复利效应：CLAUDE.md 越养越好，Claude 犯的错越来越少。

一个改写对比：从"能用"到"好用"

来看一份真实的 before/after 对比，体会"差的 CLAUDE.md"和"好的 CLAUDE.md"之间的具体差距。

改写前（常见的初始版本）：

# CLAUDE.md

This is a Next.js project with TypeScript and Tailwind CSS.

Please write clean, maintainable code.
Follow best practices for React development.
Use functional components.
Make sure the code is well-tested.
Don't use any deprecated APIs.
Keep the code DRY.
Write meaningful commit messages.

这份 CLAUDE.md 有七个问题：

1. "This is a Next.js project" —— Claude 看到 next.config.js 就知道了，等于没写
2. "Please write clean, maintainable code" —— 不可验证，Claude 觉得自己写的都是 clean 的
3. "Follow best practices" —— 什么 best practices？Claude 的训练数据里有十种互相矛盾的 best practices
4. "Use functional components" —— 没说不能用什么，Claude 可能还是偶尔给 class 组件
5. "Make sure the code is well-tested" —— 用什么测试框架？跑什么命令？什么算"well-tested"？
6. "Don't use any deprecated APIs" —— 太模糊，Claude 不一定知道哪些是 deprecated 的
7. "Write meaningful commit messages" —— "meaningful" 是什么标准？

改写后：

# [项目名]

交互语言：简体中文

## 技术栈

- Next.js 15 App Router + React 19 + TypeScript strict（禁止 Pages Router / any / @ts-ignore）
- 样式 Tailwind CSS v4（禁止 CSS Modules / styled-components / 内联 style 对象）
- 状态管理 Zustand（禁止 Redux）
- 包管理 pnpm（禁止 npm / yarn）

## 命令

- 开发：pnpm dev
- 构建：pnpm build
- 测试：pnpm test
- 类型检查 + lint：pnpm typecheck && pnpm lint（提交前必跑）

## 代码约定

- 函数组件 + hooks，不超过 200 行/文件
- Props 用 interface，命名 {组件名}Props
- named export（page.tsx / layout.tsx 例外）
- 提交信息写改了什么文件和为什么，不写"refactor for better maintainability"

## 会坑你的事

- src/lib/auth.ts 里的 session 逻辑看起来像可以简化，但不要动——
  它处理了三种边界情况，去掉任何一个线上会出问题
- 数据库迁移文件一旦提交就不能修改，只能新建迁移

改写后每一条都是具体的、可验证的。"禁止 Redux"比"follow best practices"管用得多。"提交前必跑 pnpm typecheck && pnpm lint"比"make sure the code is well-tested"清楚得多。最后的"会坑你的事"段落是从 Anthropic 官方学来的——预判 Claude 会在哪里犯错，提前堵住。

六个常见写法错误

1. 太长了

写到 300 行以上，Claude 开始随机丢规则。不是它不想遵守，是上下文窗口被无关内容挤满了，有用的指令被埋掉了。定期回头删——每条规则先问自己：删了它，Claude 的输出真的会变差吗？拿不准就先删掉，观察一周。

2. 重复 Linter 的工作

缩进用几个空格、字符串用单引号还是双引号——这些事有 ESLint、Prettier、Ruff 负责，比 Claude 又快又准。你在 CLAUDE.md 里写一遍等于花高价请 AI 干 Linter 就能干的活。把格式化交给工具，用 Hook 自动运行就好。

3. 规则打架了

一处写"用 default export"，另一处写"禁止 default export"。两条规则矛盾，Claude 随机挑一条遵守。结果就是行为不可预测，你还以为是 Claude 的问题。一个规则只在一个地方声明，定期检查有没有自相矛盾的。

4. 内容过时了

CLAUDE.md 还写着"Next.js 13 的 app 目录"，项目早升到 15 了。Claude 按过时信息写代码，出的问题比没写还难排查。解决办法：CLAUDE.md 和代码一起签入 Git，升级依赖的时候顺手过一遍。

5. /init 生成后就没管过

/init 生成的 CLAUDE.md 是万金油——什么项目都能用的东西，约等于什么项目都用不好。可以拿它当起点，但生成完必须逐条过，删废话，补你项目特有的上下文。

6. 把它当文档写

在 CLAUDE.md 里写了三段话解释"为什么选 FastAPI 而不是 Flask"的历史渊源。Claude 不在乎你的故事，它只需要一句"用 FastAPI，禁止 Flask"。长段解释放 docs/ 目录里，CLAUDE.md 里给一个链接就够了。

快速检查表

写完 CLAUDE.md 后，对照这份清单检查一遍：

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

常见问题

和 Cursor 的 .cursorrules 什么关系？

各管各的。CLAUDE.md 是 Claude Code 的，.cursorrules 是 Cursor 的，两边互不认。如果你两个工具都用，得各写一份。

写了规则 Claude 还是不听怎么办？

三种可能：文件太长规则被淹没了（精简到 200 行以内）；规则太模糊 Claude 不知道怎么执行（"写好代码"→ 改成"函数不超过 30 行"）；规则跟当前任务无关 Claude 自动跳过了（拆到 .claude/rules/ 用 paths 限定作用范围）。如果是必须遵守的硬性要求，换成 Hook。

多人协作时 CLAUDE.md 怎么管？

项目级 CLAUDE.md 签入 Git，团队共同维护。个人偏好放 CLAUDE.local.md（在 .gitignore 里），不影响其他人。Boris（Claude Code 核心作者）的团队做法是：每周有人往里加内容，代码审查时通过 @.claude 让 Claude 自动把新规则写入 CLAUDE.md。

CLAUDE.md 和 AGENTS.md 什么关系？

CLAUDE.md 是 Claude Code 专用的。AGENTS.md 是 OpenAI Codex 用的，格式和作用类似。很多项目用 symlink 让两个文件指向同一份内容（CLAUDE.md → AGENTS.md），实现跨工具兼容。

支持中文吗？

完全支持。CLAUDE.md 是标准 Markdown 文件，语言不限。在开头写一句"交互语言：简体中文"即可。

这篇文章覆盖了从官方文档到真实案例到实操步骤的完整链路。但最重要的一件事只有你自己能做——打开你的项目，创建一个空的 CLAUDE.md，开始用 Claude Code 干活，每次被它做错了什么就加一条。一周之后回头看，你会发现这份文件比任何模板都管用，因为每一行都是你自己的实战经验。