你是否也经历过这样的场景？周一早上，你打开Claude Code，准备重构一个组件。
你输入：“帮我重构 ArticleCard 组件。”
Claude 问：“这个项目用的是什么框架？”
你答：“Next.js 14，App Router。”
Claude 问：“用 TypeScript 还是 JavaScript？”
你答：“TypeScript，严格模式。”
Claude 问：“样式方案呢？Tailwind 还是 CSS Modules？”
你答：“Tailwind CSS。”
Claude 问：“组件导出方式有什么偏好吗？”
你答：……
短短两分钟，你就在重复上周甚至昨天说过的话。 周二如此，周三依然，周而复始。问题的根源在于，Claude Code 每次启动都像一张白纸，它不记得你昨天的任何对话，对你的项目一无所知。
但有一个文件可以彻底改变这一现状。写好它之后，Claude 每次启动都会自动读取，从而知晓项目的技术栈、编码规范和常用命令。这个文件就是 CLAUDE.md。
什么是 CLAUDE.md？一句话说清楚
CLAUDE.md 是你写给 Claude Code 的“项目入职文档”。
想象一下，团队来了一位能力超强但完全不了解项目的新同事。你会怎么做？你会准备一份文档，告诉他项目目标、技术栈、代码结构、常用命令和避坑指南。
CLAUDE.md 就是这份文档，只不过你的“新同事”是 Claude Code，而且它每天都会“失忆”，所以每天“上班”第一件事就是重读这份文档。
技术要点：
- 位置：项目根目录（或其它几个位置，后文详述）
- 格式：Markdown 文件
- 加载时机：每次会话开始时自动加载，无需手动指定
- 文件名：必须为
CLAUDE.md（全大写），而非 claude.md
- 优先级：
CLAUDE.md 中的指令优先级高于对话内容，冲突时以文件为准
记忆系统全景图：不只是一个文件
很多人误以为 CLAUDE.md 只是一个独立的配置文件。实际上，Claude Code 拥有一套分层的记忆系统，CLAUDE.md 是其中最核心的一层。
┌──────────────────────────────────────────────────────────┐
│ Claude Code 记忆系统全景图 │
├──────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────┐ │
│ │ 第 1 层：全局 CLAUDE.md │ │
│ │ ~/.claude/CLAUDE.md │ │
│ │ → 所有项目通用的个人偏好 │ │
│ │ → “我喜欢 2 空格缩进” │ │
│ └──────────┬─────────────────────────┘ │
│ ↓ 叠加 │
│ ┌────────────────────────────────────┐ │
│ │ 第 2 层：项目 CLAUDE.md │ │
│ │ 项目根目录/CLAUDE.md │ │
│ │ → 项目专属信息，提交到 Git │ │
│ │ → “本项目用 Next.js 14 + TS” │ │
│ └──────────┬─────────────────────────┘ │
│ ↓ 叠加 │
│ ┌────────────────────────────────────┐ │
│ │ 第 3 层：个人本地 CLAUDE.local.md │ │
│ │ 项目根目录/CLAUDE.local.md │ │
│ │ → 个人偏好，不提交到 Git │ │
│ │ → “用中文回答我” │ │
│ └──────────┬─────────────────────────┘ │
│ ↓ 叠加 │
│ ┌────────────────────────────────────┐ │
│ │ 第 4 层：子目录 CLAUDE.md │ │
│ │ src/components/CLAUDE.md │ │
│ │ → 按需加载，操作该目录时才读取 │ │
│ │ → “组件必须用函数式声明” │ │
│ └──────────┬─────────────────────────┘ │
│ ↓ 叠加 │
│ ┌────────────────────────────────────┐ │
│ │ 第 5 层：Auto Memory（自动记忆） │ │
│ │ ~/.claude/projects/<项目>/memory/ │ │
│ │ → Claude 自己记的笔记 │ │
│ │ → 自动记录，无需你维护 │ │
│ └────────────────────────────────────┘ │
│ │
│ 叠加规则：所有层级同时生效，不是覆盖关系 │
│ 冲突时：越具体的层级优先级越高 │
│ │
└──────────────────────────────────────────────────────────┘
核心概念是“叠加”，而非“覆盖”。 这类似于 CSS 的层叠逻辑——全局、项目、局部的样式同时生效，冲突时以更具体的为准。对于日常开发，你最需要关注的是前两层：全局 CLAUDE.md（个人偏好）和项目 CLAUDE.md（项目上下文）。
内容取舍：该写什么，不该写什么？
这个问题至关重要。写得太泛等于没说，写得太细则浪费 Token，可能导致 Claude 忽略关键指令。
业内共识如下：
┌──────────────────────────────────────────────────────────┐
│ CLAUDE.md 内容取舍原则 │
├──────────────────────────────────────────────────────────┤
│ │
│ ✅ 该写的（每次会话都需要知道的信息） │
│ ├── 项目是什么、用了什么技术栈 │
│ ├── 项目目录结构的关键说明 │
│ ├── 编码规范和命名约定 │
│ ├── 日常开发要跑的命令（dev/build/test/lint） │
│ ├── 重要的架构决策和约束 │
│ └── 常踩的坑和特殊注意事项 │
│ │
│ ❌ 不该写的 │
│ ├── “写出高质量代码” — 太模糊，等于没说 │
│ ├── “遵循最佳实践” — Claude 自己知道，不用你教 │
│ ├── 完整的 API 文档 — 太长，用 @docs/ 引用 │
│ ├── 频繁变动的信息 — 放到对话里说就行 │
│ ├── 所有可能用到的命令 — 只写高频的 │
│ └── SOLID 原则的定义 — Claude 比你还熟 │
│ │
│ 核心思路： │
│ 想象你给一个高级工程师写交接文档 │
│ 他什么都会，只是不了解“你这个项目的特殊情况” │
│ 你只需要写特殊情况，不需要教他基础知识 │
│ │
└──────────────────────────────────────────────────────────┘
经验法则：将内容控制在 100-150 行以内。 研究表明，前沿 AI 模型能稳定遵循大约 150-200 条指令。超出此范围，遵循率会下降。因此，一份精炼、每条指令都有分量的指南远胜于面面俱到的万字长文。
记住 “渐进式披露” 原则。不要把所有信息都塞进 CLAUDE.md。只写入“每次会话都必需的信息”，其他详细内容（如完整 API 文档）应放在 docs/ 目录下，通过 @docs/xxx.md 按需引用，这能有效节省 Token 并在需要时提供深度上下文。更多关于技术文档的组织方法，可以参考社区的最佳实践。
完整实战：为 Next.js 项目编写 CLAUDE.md
理论说再多不如动手实践。让我们为一个虚构的 “DevPulse” (基于 Next.js 14 的技术博客平台) 项目编写一份完整的 CLAUDE.md。
第一步：让 Claude 生成初稿
在项目目录下启动 Claude Code，你可以直接输入：
分析这个项目的完整结构，帮我生成一份 CLAUDE.md 初稿，
包括项目概述、技术栈、目录结构、编码规范和常用命令
或者使用内置的初始化命令：
/init
/init 命令会自动扫描项目并生成初稿。但请注意：这仅仅是起点，而非终点。 它能识别技术栈和基本命令，但编码规范、架构约束等“隐性知识”仍需你手动补充。
第二步：手动补充，形成终版
以下是为 DevPulse 项目编写的完整 CLAUDE.md 示例，可直接参考：
# DevPulse 项目说明
## 项目概述
DevPulse 是一个基于 Next.js 14 的技术博客平台，支持 Markdown 文章发布、
用户认证、评论互动和全文搜索。面向技术社区，部署在 Vercel 上。
## 技术栈
- 框架：Next.js 14.x（App Router，不使用 Pages Router）
- 语言：TypeScript 5.x（strict 模式，tsconfig 中 strict: true）
- 样式：Tailwind CSS 3.x（不使用 CSS Modules）
- ORM：Prisma 5.x + PostgreSQL 16
- 认证：NextAuth.js v5
- 部署：Vercel（自动部署 main 分支）
## 项目结构
src/
├── app/ # App Router 页面和布局
│ ├── (auth)/ # 认证路由组（登录、注册）
│ ├── (blog)/ # 博客路由组（文章列表、详情）
│ ├── api/ # API Routes
│ └── layout.tsx # 根布局
├── components/ # 可复用组件
│ ├── ui/ # 基础 UI（Button、Input、Modal 等）
│ └── features/ # 业务组件（ArticleCard、CommentBox 等）
├── lib/ # 工具函数、配置、第三方封装
├── types/ # TypeScript 类型定义（全局共享类型）
└── prisma/ # 数据库 schema 和迁移文件
## 编码规范
- 组件声明：使用 function 关键字，不用箭头函数导出
正确：export function ArticleCard() {}
错误：export const ArticleCard = () => {}
- Props 类型命名：ComponentNameProps（如 ArticleCardProps）
- 服务端组件是默认值，只在需要交互时添加 ‘use client’
- 禁止使用 any 类型，所有变量和参数必须有明确类型
- import 使用命名导入，避免 default export（组件除外）
- 提交信息格式：type(scope): description（英文）
示例：feat(blog): add article search functionality
## 常用命令
- 开发服务器：npm run dev
- 生产构建：npm run build
- 类型检查：npx tsc --noEmit
- 代码检查：npm run lint
- 运行测试：npm run test
- 测试覆盖率：npm run test -- --coverage
- 数据库迁移：npx prisma migrate dev
- 数据库客户端：npx prisma studio
- 生成 Prisma 类型：npx prisma generate
## 重要约束
- 所有页面组件默认是 Server Component，数据获取在服务端完成
- 客户端交互组件必须显式标注 ‘use client’
- 图片必须使用 next/image，链接必须使用 next/link
- API Routes 统一放在 src/app/api/，使用 Route Handlers（不是旧版 API Routes）
- 环境变量在 .env.local 中，不要提交到 Git
- Prisma schema 修改后必须运行 migrate dev 和 generate
第三步：测试效果
编写完成后，务必开启一个全新的会话进行测试：
# 退出当前会话
Ctrl+D
# 重新启动（不要用 -c 继续）
claude
然后输入：
帮我重构 ArticleCard 组件，拆分成更小的子组件
注意观察——这次你无需提供任何背景信息，但 Claude 已经知晓：
- 项目使用 Next.js 14 + TypeScript strict 模式
- 组件需用
function 声明
- 样式使用 Tailwind CSS
- Props 类型应命名为
ArticleCardProps
- 需要考虑 Server/Client 组件的划分
这就是 CLAUDE.md 的威力：一次编写，每次会话自动生效。
优劣对比：一组示例看明白
同样的项目，CLAUDE.md 的质量直接决定 Claude 的表现。
差的 CLAUDE.md 示例：
# My Project
This is a web project. Use React.
Write clean code and follow best practices.
问题何在？“web project”过于宽泛，“Use React”没有版本和风格，“clean code”和“best practices”过于模糊。结果就是 Claude 只能靠猜，频繁出错，浪费大量时间纠正。
好的 CLAUDE.md 就是上文 DevPulse 的版本——每条指令都具体、可执行、无歧义。
对比总结：
┌────────────┬──────────────────────┬──────────────────────┐
│ 维度 │ ❌ 差的 │ ✅ 好的 │
├────────────┼──────────────────────┼──────────────────────┤
│ 项目描述 │ “一个网站” │ “基于 Next.js 14 的 │
│ │ │ 技术博客平台” │
├────────────┼──────────────────────┼──────────────────────┤
│ 技术栈 │ “用了 React” │ “Next.js 14 + TS │
│ │ │ strict + Tailwind” │
├────────────┼──────────────────────┼──────────────────────┤
│ 编码规范 │ “写干净的代码” │ “function 声明组件， │
│ │ │ Props 命名 XxxProps” │
├────────────┼──────────────────────┼──────────────────────┤
│ 常用命令 │ 没有 │ 完整的 dev/build/ │
│ │ │ test/lint/migrate │
├────────────┼──────────────────────┼──────────────────────┤
│ 信息密度 │ 3 行 │ 80-100 行 │
├────────────┼──────────────────────┼──────────────────────┤
│ 效果 │ Claude 不断追问 │ Claude 上手就能干活 │
└────────────┴──────────────────────┴──────────────────────┘
进阶一：子目录 CLAUDE.md —— 分层上下文管理
项目通常包含不同类型的代码（组件、API、工具函数），它们规范各异。全部塞进根目录 CLAUDE.md 会导致文件臃肿。
更好的做法是使用子目录 CLAUDE.md：
DevPulse/
├── CLAUDE.md ← 项目全局上下文
├── src/
│ ├── components/
│ │ └── CLAUDE.md ← 组件开发规范
│ ├── app/api/
│ │ └── CLAUDE.md ← API 开发规范
│ └── lib/
│ └── CLAUDE.md ← 工具函数规范
└── tests/
└── CLAUDE.md ← 测试编写规范
加载时机：子目录的 CLAUDE.md 是按需加载的——仅当 Claude 读取或操作该目录下的文件时才会自动读取。这正是“渐进式披露”的实践：Claude 写组件时加载组件规范，写 API 时加载 API 规范，互不干扰，节省上下文空间。
例如，src/components/CLAUDE.md 可以这样写：
# 组件开发规范
## 文件组织
- 每个组件一个文件，文件名与组件名一致（PascalCase）
- 复杂组件可以建子目录：ComponentName/index.tsx + 子组件
- 基础 UI 组件放 ui/，业务组件放 features/
## 组件结构顺序
1. ‘use client’（如果需要）
2. import 语句
3. Props 接口定义
4. 组件函数
5. 辅助函数（组件外部）
## 样式规范
- 优先使用 Tailwind 工具类
- 超过 5 个类名时用 clsx/cn 函数合并
- 响应式断点：sm:640 md:768 lg:1024 xl:1280
- 暗色模式使用 dark: 前缀
## 性能注意事项
- 列表渲染必须有稳定的 key（不用 index）
- 大列表考虑虚拟滚动
- 图片使用 next/image 的 sizes 属性优化加载
而 src/app/api/CLAUDE.md 的内容则完全不同，专注于 API 设计、错误处理和数据校验等规范。
进阶二：.claude/rules/ —— 模块化规则文件
对于更复杂的团队规范，从2025年末开始，Claude Code 支持模块化的规则文件：
.claude/rules/
├── typescript.md ← TypeScript 规范
├── testing.md ← 测试规范
├── api-design.md ← API 设计规范
└── git-workflow.md ← Git 工作流规范
每个文件可以通过 frontmatter 指定作用范围：
---
globs: ["src/**/*.tsx", "src/**/*.ts"]
---
# TypeScript 代码规范
- 禁止使用 any，使用 unknown 替代
- 函数返回值必须有显式类型标注
- ...
此规则仅当 Claude 操作匹配 src/**/*.tsx 或 src/**/*.ts 的文件时才会加载。
何时使用 rules/ 而非子目录 CLAUDE.md？
- 按文件类型区分规则 → 用
rules/（例如所有 .tsx 文件遵循同一套 TypeScript 规范）
- 按目录/模块区分规则 → 用子目录
CLAUDE.md（例如 components/ 和 api/ 有不同规范）
两者可根据需要混合使用。如果你想深入了解大型项目中如何组织这类前端框架/工程化相关的配置和规范，可以探索更多案例。
维护策略：动态更新，而非一劳永逸
CLAUDE.md 不是写完后就可以束之高阁的。项目在演进，规范在变化，CLAUDE.md 也需要同步更新。
维护信号（出现以下情况就该更新了）：
- Claude 生成的代码经常不符合当前规范
- 你在会话中反复纠正同一件事
- 项目新增了重要依赖或发生了架构变更
- Code Review 中发现 Claude 遗漏了某项团队约定
一个实用技巧是让 Claude 自己检查 CLAUDE.md 的时效性：
读一下 @CLAUDE.md，对比当前项目实际的 package.json 和 tsconfig.json，
看看有没有过时或者不一致的信息，如果有就帮我更新
核心收获与检查清单
三个核心收获：
CLAUDE.md 是 Claude Code 的“项目入职文档”，一次编写，每次会话自动生效，极大减少重复沟通。- 记忆系统是分层叠加的，重点维护全局和项目级配置，其他按需使用。
- 内容贵在精炼具体，控制在 100-150 行，只写必需信息，模糊或冗长的内容通过引用方式提供。
通关检查清单：
- [ ] 理解五层记忆系统的层级关系和叠加规则
- [ ] 为你的项目创建了完整的
CLAUDE.md
- [ ]
CLAUDE.md 包含：项目概述、技术栈、目录结构、编码规范、常用命令
- [ ] 创建了全局
~/.claude/CLAUDE.md 定义个人偏好
- [ ] 已在新会话中测试 Claude 是否正确加载上下文
- [ ] 了解子目录
CLAUDE.md 和 .claude/rules/ 的用法
掌握 CLAUDE.md 的配置，就如同为你的 AI 编程助手装配了长期记忆。这不仅减少了日常开发中的摩擦，更能让 Claude 产出更符合项目规范、更高质量的代码，是提升开源实战与团队协作效率的利器。在 云栈社区 中，也有众多开发者分享他们利用类似工具提升工作流的经验，值得交流借鉴。如果这篇文章对你有所启发，不妨立即为你手头的项目创建或优化一份 CLAUDE.md，亲自体验效率的跃升。
发表于 16 小时前
|
查看: 4|
回复: 0
