导语

最近 GitHub 上有个现象挺有意思——

前几天的 Trending 榜，前 10 的项目里有 7 个都跟 Claude Code 有关。最离奇的是，最火的项目不是什么新模型、不是什么新框架，而是一个配置文件。

就是这个：CLAUDE.md

有人把自己项目的这个配置文件开源出来，几天内涨了好几百 Star，Andrej Karpathy（前 OpenAI 研究科学家）类似的配置文件甚至有 10 万+ Star。

大家都在研究的东西，咱们今天也来搞懂它。

一、CLAUDE.md 是什么？一句话解释 🤔

你有没有遇到过这种场景：

每次让 AI 改代码，它都自作主张引入了你不要的依赖；或者你说用 pnpm，它给你生成了 npm 的命令；再或者你有个文件说好不能动，结果它给你动了……

根源在哪？AI 不了解你的项目背景，每次对话都是”失忆状态”重新开始。

CLAUDE.md 就是解决这个问题的：它是放在项目根目录的一个 Markdown 文件，每次 Claude Code 启动时会自动把它读进去，作为持久上下文。

可以把它理解成给 AI 写的”入职说明书”——你不用每次都重复交代，它自己会记住。

二、放什么进去？有讲究 📝

CLAUDE.md 不是越长越好，社区普遍反馈 300~800 字、1~5KB 是最佳区间，超过 10KB 反而会导致关键规则被稀释。

根据开发者分享的实践经验，一份高质量的配置文件通常包含这几块：

1. 项目概述（最重要）

## Project Overview
这是一个给独立开发者用的定时任务管理 SaaS。
核心用户是自由职业者和远程工作者。
优先保证：任务可靠性 > UI 美观 > 功能数量。

为什么重要：放在文件最上方，是最先被读取的内容，直接定调整体风格。

2. 技术栈白名单 + 黑名单

## Tech Stack
- Next.js 15（App Router）
- TypeScript（strict mode）
- Tailwind CSS
- pnpm（包管理器）

❌ 禁止引入：
- Redux（没必要）
- styled-components（已用 Tailwind）
- any 类型

关键点：禁止的东西要写清楚，”允许”列表 AI 可能绕过，”禁止”列表它会严格遵守。

3. 架构目录约定

## Architecture
- src/app/ — 路由和页面（RSC 优先）
- src/components/ — 可复用 UI 组件
- src/features/ — 业务逻辑模块
- src/lib/ — 工具函数

新功能必须先在 features/ 下创建模块，不得直接写在页面文件里。

4. 编码规范（越具体越好）

❌ 抽象原则（没用）：

写可维护的代码
使用现代 JavaScript

✅ 可执行规则（有用）：

## Coding Conventions
- 函数不超过 50 行
- 禁止使用 var，禁止 any 类型
- 使用 async/await，不用链式 Promise
- 每次提交前不遗留 console.log
- 每个文件不超过 300 行

5. 安全红线

## Safety Rules
除非明确被要求，否则不要：
- 修改数据库 schema
- 重命名已发布的 API 路由
- 重构超过 3 个文件
- 引入新的第三方依赖

这部分是防止 AI “好心办坏事”的关键。

三、加载机制，你得知道这一点 ⚙️

CLAUDE.md 有两个层级：

~/.claude/CLAUDE.md         ← 全局配置（所有项目通用）
./CLAUDE.md                  ← 项目配置（当前项目专属）

两个配置叠加生效，项目级配置优先于全局配置中的同名章节。

所以推荐这么分工：

• 全局配置：放通用规则，比如”始终用 TypeScript strict”、”用 pnpm”、”提交前跑类型检查”
• 项目配置：放项目特有的技术栈、目录结构、安全约束

还有一点需要注意：CLAUDE.md 只在对话开始时加载一次，不热重载。 改了文件之后需要重新开启会话才能生效。

四、一个完整的真实配置模板 📋

## Project Overview
一个面向设计师的 AI 落地页生成工具。
用户上传设计稿，AI 生成可直接部署的页面。
核心指标：从设计稿到上线 < 5 分钟。

## TechStack
-Next.js15（AppRouter）
-TypeScript（strict）
-TailwindCSS + shadcn/ui
-Supabase
-pnpm

❌ 禁止：Redux、styled-components、MaterialUI

## Architecture
-app/ — 路由和页面（RSC 优先）
-components/ui/ — 设计系统组件
-lib/ — 共享工具函数
-features/ — 业务模块

## CodingConventions
- 函数式组件，不用类组件
- 具名导出（路由文件除外）
- 组件不超过 200 行
- 所有用户输入必须经过 Zod 验证
- 不遗留 console.log 和注释掉的代码

## Commands
- 开发：pnpmdev
- 构建：pnpmbuild
- 类型检查：pnpmtypecheck
- 测试：pnpmtest

## SafetyRules
- 不修改认证逻辑
- 不修改数据库 schema
- 不重命名已发布的 API 路由

五、什么时候需要更新它？ 🔄

有个简单的判断标准——发现 AI 重复犯同类错误，就往里加规则。

开发者社区总结了几个常见信号：

• AI 总是引入你不要的某个包 → 加到禁止列表
• AI 把文件写在了错误的目录 → 补充架构说明
• AI 总是遗漏某个测试步骤 → 加到 Commands 章节

反过来，不再适用的规则要及时删掉——上下文噪音会稀释有效规则。

总结

CLAUDE.md 这个配置文件的核心逻辑很朴素：你愿意花 30 分钟把项目背景说清楚，AI 就能在之后每次对话里更聪明地帮你干活。

根据开发者社区的反馈，配置得好的 CLAUDE.md 可以显著减少”AI 自作主张”的情况，减少返工，也不用每次对话都重复交代背景。

现在去你的项目根目录，touch CLAUDE.md，开始写吧。