自 2025 年初以来，我每天都在使用 Claude Code，我可以告诉您，获得有用输出的最大因素不是提示工程或巧妙的技巧。而是上下文。具体来说，是位于项目根目录的编写良好的 CLAUDE.md 文件。这一个文件决定了 AI 助手是与您的代码库搏斗，还是像在您团队工作数月的资深开发人员那样工作。

如果您一直在向 Claude Code 输入提示，却得到通用、错误或令人沮丧的结果，本指南适合您。我将详细说明如何构建 CLAUDE.md、包括什么、省略什么，并分享 Social Animal 已发布的生产项目中的真实示例。

目录

CLAUDE.md 是什么及其为何重要

CLAUDE.md 是您放在存储库根目录中的 Markdown 文件，Claude Code 会在每次开始会话时自动读取。将其视为您的 AI 对编程助手的入职文档。当新开发人员加入您的团队时，您不会只是递给他们一台笔记本电脑说「自己搞清楚」。您会向他们讲解架构、解释奇怪的部分、指出陷阱。CLAUDE.md 对 Claude 做同样的事情。

没有它，Claude Code 必须从您的文件结构、package.json 和它碰巧读取的任何文件中推断一切。这就像要求新员工通过阅读随机源文件来理解您的整个系统。他们会得到一些正确的东西，但他们也会做出浪费每个人时间的假设。

有了扎实的 CLAUDE.md，我看到首次任务完成精度从大约 60% 跳升到超过 90%。这不是个小改进——这是 AI 辅助开发成为生产力倍增器和令人沮丧的时间消耗之间的区别。

Claude Code 如何读取项目上下文

Claude Code 有一个特定的加载上下文的层级。理解这一点很重要，因为它影响您如何组织项目记忆。

上下文加载顺序

  1. ~/.claude/CLAUDE.md — 您的全局偏好（应用于每个项目）
  2. ./CLAUDE.md — 您的 repo 根目录下的项目级文件
  3. ./subdirectory/CLAUDE.md — 目录特定的覆盖
  4. .claude/settings.json — 项目特定的工具权限和设置
  5. 会话上下文 — 您在当前对话中告诉 Claude 的内容

项目级 CLAUDE.md 是您将花费大部分时间的地方。全局文件适合个人偏好（「我倾向于函数式组件」或「始终使用 TypeScript 严格模式」），但真正的价值在于每个项目的上下文。

关键是：Claude Code 在每次会话开始时读取 CLAUDE.md，但它的上下文窗口空间有限。如果您的 CLAUDE.md 是 5,000 字的冗长文档，您就在消耗本来可以用于实际代码推理的令牌。简洁。具体。每一行都应该赚到它的位置。

优秀 CLAUDE.md 文件的解析

在多个项目中编写和改进 CLAUDE.md 文件后——Next.js 应用、Astro 网站、无头 CMS 集成、API 服务——我找到了一个有效的一致结构。

理想结构

# 项目名称

## 概述
解释这个项目做什么和为谁服务的一段话。

## 技术栈
确切的版本和框架。

## 架构
这些部分如何组合在一起。

## 关键约定
编码标准、命名模式、文件组织规则。

## 常见命令
构建、测试、部署和开发命令。

## 重要上下文
从代码中不明显的东西。

## 已知问题 / 陷阱
要避免的地雷。

## 不要
 AI 永远不应该做的明确事情。

让我们深入了解每个部分。

分章节详细说明

概述

最多保持 2-3 句。Claude 不需要您的产品路线图——它需要理解域名，以便它可以做出上下文相关的决定。

## 概述
这是 Acme Corp 的营销网站，一个用于供应链管理的 B2B SaaS 平台。该网站使用动态 API 路由进行表单处理和潜在客户捕获的静态生成。内容由营销团队通过 Sanity CMS 管理。

技术栈

精确。不要只说「React」——指定版本、框架、渲染策略。这可以防止 Claude 建议在 React 18 中有效但在 React 19 中中断的模式，或在您使用 App Router 时推荐 Pages Router。

## 技术栈
- **框架**: Next.js 15.1（App Router、默认 RSC）
- **语言**: TypeScript 5.7（严格模式）
- **样式**: Tailwind CSS v4 和 CSS 优先配置
- **CMS**: Sanity v3 和实时预览
- **部署**: Vercel（生产 + 预览环境）
- **包管理器**: pnpm 9.x
- **Node**: v22 LTS
- **测试**: Vitest + Playwright
- **状态管理**: Zustand（最小化，仅用于客户端 UI 状态）

架构

这是大多数人要么写得太少，要么写得太多的地方。您不是在写系统设计文档。您正在给 Claude 一个心智模型。

## 架构
- `app/` — Next.js App Router 页面和布局
- `app/api/` — API 路由（表单提交、webhooks）
- `components/` — 共享 UI 组件（原子设计：atoms/、molecules/、organisms/）
- `lib/` — 实用函数、API 客户端、类型定义
- `lib/sanity/` — Sanity 客户端、查询（GROQ）和类型生成
- `content/` — MDX 文件用于博客文章（与前缀共同定位）
- `public/` — 静态资源（对所有图像首选 next/image）

数据流：Sanity CMS → lib/sanity/queries.ts 中的 GROQ 查询 → 服务器组件 → 客户端组件（仅在需要交互性时）

除了 /blog/[slug]/preview 使用草稿模式外，所有页面都在构建时静态生成。

关键约定

本部分节省最多时间。没有它，Claude 将遵循可能与您团队选择相冲突的通用最佳实践。

## 关键约定
- 组件为 PascalCase 命名，每个文件一个组件
- 使用命名导出，从不默认导出（除了 pages/layouts）
- 所有数据获取发生在服务器组件中——从不使用 useEffect 进行数据获取
- API 响应类型位于 lib/types/ 中，从 Sanity 架构自动生成
- 使用 `cn()` 实用程序（lib/utils.ts）进行条件类合并，而不是模板文字
- 错误边界包装每个主要页面部分，而不是整个页面
- 所有表单处理使用 react-hook-form + zod 验证架构
- 提交消息遵循常规提交（feat:、fix:、chore:）

常见命令

这看起来很基础，但 Claude Code 实际上运行这些命令。如果它不知道正确的命令，它会猜测，而且它经常会猜测错误。

## 常见命令
- `pnpm dev` — 启动开发服务器（端口 3000）
- `pnpm build` — 生产构建
- `pnpm lint` — ESLint + Prettier 检查
- `pnpm test` — 运行 Vitest 单元测试
- `pnpm test:e2e` — 运行 Playwright E2E 测试
- `pnpm sanity:typegen` — 架构更改后重新生成 Sanity 类型
- `pnpm db:migrate` — 运行 Drizzle ORM 迁移

重要上下文

这是用于 Claude 无法通过阅读您的代码推断出的东西。业务逻辑、外部约束、人工审查者需要 30 分钟来解释的事情。

## 重要上下文
- 我们为所有 CMS 页面使用 ISR（revalidate: 3600）。除非绝对必要，否则不要使用 `force-dynamic`。
- /api/revalidate 的 Sanity webhook 处理按需重新验证——不要添加手动重新验证逻辑。
- 图像优化通过 Sanity 的 CDN（cdn.sanity.io）进行，而不是对 CMS 内容使用 next/image。
- 身份验证由 Clerk 处理——从不构建自定义身份验证流程。
- /api/leads 端点通过 Upstash Redis 进行速率限制。不要删除速率限制中间件。

已知陷阱

每个项目都有奇怪的东西。把它放在这里，这样 Claude 就不会被绊倒。

## 已知陷阱
- Sanity 的便携式文本渲染器在 v3.2 中对嵌套列表有一个错误。我们在 components/portable-text/list-fix.tsx 中使用自定义序列化程序
- Tailwind v4 在模块 CSS 文件中不支持 `@apply` 指令——改用内联类
- vercel.json 为 /docs/* 的重写代理到我们的 Mintlify 文档网站。不要在没有与团队确认的情况下修改这些。
- 以 NEXT_PUBLIC_ 为前缀的环境变量是仅在客户端可用的。绝不以这种方式暴露 API 机密。

「不要」部分

这可能是最重要的部分。负指令对 AI 模型非常有效。

## 不要
- 不要在没有询问的情况下安装新的依赖项
- 不要使用 `any` 类型——找到或创建适当的类型
- 不要为服务器组件可以做的事情创建新的 API 路由
- 不要在没有确认迁移计划的情况下修改 Sanity 架构文件
- 不要使用 `"use client"`，除非组件确实需要浏览器 API 或事件处理程序
- 不要编写 CSS 文件——所有内容都是 Tailwind 实用类
- 不要硬编码应该来自 CMS 的字符串

真实 CLAUDE.md 示例

示例：Next.js 营销网站

这是我们在客户项目上使用的 CLAUDE.md 的精简版本，特别是在使用无头 CMS 后端构建 Next.js 网站时。

# Acme 营销网站

## 概述
Acme 的营销网站（acme.com）。使用 Next.js 15 构建，用 Tailwind v4 样式化，内容来自 Sanity CMS。目标：所有页面上的 LCP < 2 秒。

## 技术栈
Next.js 15.1 | TypeScript 5.7 严格 | Tailwind v4 | Sanity v3 | Vercel | pnpm

## 架构
App Router 和 RSC。通过 lib/sanity/queries.ts 中的 GROQ 查询在服务器组件中进行所有数据获取。客户端组件仅用于交互式元素（模态、表单、轮播）。

页面：/ (首页)、/about、/pricing、/blog、/blog/[slug]、/contact

## 约定
- 仅命名导出（除了 page.tsx/layout.tsx）
- 组件：PascalCase，每个文件一个
- cn() 用于类合并
- Zod 架构用于所有表单验证
- 不使用 useEffect 进行数据获取。绝不。

## 命令
pnpm dev | pnpm build | pnpm lint | pnpm test

## 不要
- 在没有正当理由的情况下添加「use client」
- 在没有询问的情况下安装包
- 为组件使用默认导出
- 修改 sanity/schema/ 文件，除非先确认迁移
- 使用 any 类型

示例：Astro 内容网站

对于 Astro 项目，CLAUDE.md 看起来有点不同，因为架构范式不同。

# 技术博客 — Astro

## 概述
有 500+ 篇文章的开发人员博客。静态优先，默认零 JS。MDX 用于内容和自定义组件。

## 技术栈
Astro 5.x | MDX | Tailwind v4 | 部署到 Cloudflare Pages | 内容集合 v2

## 架构
src/content/ — MDX 文章和 Zod 验证的前缀
src/components/ — Astro 组件（零 JS）和 React 岛屿（交互式）
src/layouts/ — 基础布局
src/pages/ — 基于文件的路由

## 关键规则
- 默认使用 Astro 组件（.astro）。仅对需要交互性的岛屿使用 React。
- client:visible 用于折叠下方的交互式组件
- client:idle 用于非关键的交互式组件
- 除非绝对必要，否则不要使用 client:load
- 所有图像使用 Astro 的图像组件和适当的宽度/高度
- RSS 源从内容集合自动生成——不要构建手动源逻辑

## 不要
- 当 Astro 组件有效时，不要添加 React 组件
- 不要使用 client:load 指令
- 不要跳过图像尺寸（导致 CLS）
- 在没有更新现有前缀的情况下不要修改内容集合架构

破坏 AI 上下文的常见错误

在这一点上，我已经审查了许多 CLAUDE.md 文件。以下是一致导致不良结果的模式。

错误 为什么伤害 修复
太长（2000+ 字） 消耗上下文窗口令牌，关键信息丢失 保持在 800 字以下。链接到外部文档以进行深入研究。
太模糊（「我们使用 React」） Claude 用假设填补空白 具体说明：版本、模式、确切的工具
没有负指令 Claude 做「合理的」事情会破坏您的约定 始终包括「不要」部分
复制粘贴 README.md README 是为人类，而不是 AI 上下文 从头开始编写 CLAUDE.md 和 AI 特定框架
包含敏感数据 上下文文件中的 API 密钥、机密 不要在 CLAUDE.md 中放置机密。改为参考 .env.example
从不更新它 项目演变，上下文文件不演变 在每个 sprint 或主要重构时审查 CLAUDE.md
相互矛盾的指令 「使用服务器组件」+ 带有 useEffect 获取的示例 让一个人拥有该文件，检查一致性

CLAUDE.md 与其他 AI 上下文文件

Claude Code 不是唯一读取项目上下文文件的 AI 工具。以下是 2025 年的形势：

文件 工具 自动读取 范围
CLAUDE.md Claude Code 是，在会话开始时 项目范围
.cursorrules Cursor 是，在文件打开时 项目范围
.github/copilot-instructions.md GitHub Copilot 是，在 Copilot Chat 中 Repo 范围
.windsurfrules Windsurf (Codeium) 是 项目范围
AGENTS.md OpenAI Codex CLI 是 项目范围
.ai/context.md 自定义约定 否（手动参考） 变化

好消息：大部分内容是可转移的。如果您编写了扎实的 CLAUDE.md，将其转换为 .cursorrules 或 copilot-instructions.md 大约需要 5 分钟。结构和信息相同——仅文件名和次要格式不同。

如果您的团队使用多个 AI 工具（2025 年很多都这样做），请考虑维护单一事实来源并从中生成特定工具的文件。一个简单的构建脚本可以将您的主上下文文件复制到所有正确的位置。

大型项目的高级模式

嵌套 CLAUDE.md 文件

对于 monorepos 或大型代码库，您可以在子目录中放置 CLAUDE.md 文件。Claude Code 将为您正在工作的目录读取最具体的文件。

project/
├── CLAUDE.md              # 全球项目上下文
├── apps/
│   ├── web/
│   │   └── CLAUDE.md      # Web 应用特定上下文
│   └── api/
│       └── CLAUDE.md      # API 特定上下文
├── packages/
│   └── ui/
│       └── CLAUDE.md      # 设计系统上下文

根 CLAUDE.md 涵盖共享架构和约定。每个嵌套文件为该包添加具体内容。

使用 /compact 的动态上下文

Claude Code 的 /compact 命令总结当前对话并释放上下文空间。对于长时间的会话，我发现了一个有效的模式：

  1. 从自动加载的 CLAUDE.md 开始
  2. 在一项功能上工作
  3. 当上下文变得沉重时运行 /compact
  4. 继续——Claude 保留 CLAUDE.md 上下文加上压缩的摘要

团队共享与个人上下文

我们在版本控制中保留 CLAUDE.md（应该提交）。但个人开发人员也使用 ~/.claude/CLAUDE.md 获取个人偏好：

# 个人偏好
- 我偏向冗长的变量名而不是缩写
- 在编写代码前显示推理
- 建议更改时，显示完整文件差异
- 我将 VS Code 与 Vim 按键绑定一起使用（不要建议 IDE 特定的快捷方式）

这种分离使团队文件保持整洁和集中在项目事实上，同时允许个人自定义他们的体验。

衡量影响

您如何知道您的 CLAUDE.md 有效？以下是我们在内部跟踪的指标：

  • 首次尝试精度：Claude 的第一个响应需要零更正的频率有多高？一个好的 CLAUDE.md 会将其提升到 80% 以上。
  • 约定违规：计算 Claude 打破编码标准的次数。应该趋向于零。
  • 上下文问题：如果 Claude 不断询问「这是什么框架？」或「我应该使用 App Router 吗？」，您的 CLAUDE.md 缺少信息。
  • 撤销频率：您必须拒绝或还原 Claude 更改的频率。越低越好。

一家中型创业公司的一个团队报告说，在花费一小时改进他们的 CLAUDE.md 后，他们的平均 AI 辅助任务时间从 12 分钟减少到 4 分钟。那是仅来自一个文件的 3 倍改进。

如果您正通过我们的服务与我们合作，我们会在每个项目交付中包含定制的 CLAUDE.md。这对持续开发速度来说是多么重要。

常见问题

CLAUDE.md 是什么以及它放在哪里？ CLAUDE.md 是放在项目存储库根目录中的 Markdown 文件。Claude Code 在每次会话开始时自动读取它，以了解您项目的架构、约定、技术栈和约束。将其视为专门为您的 AI 编程助手编写的入职文档。

CLAUDE.md 文件应该多长？ 目标是 300-800 字。更短的文件错过了关键上下文，但超过 1,000 字的任何东西都开始消耗上下文窗口——更好地用于实际代码推理的空间。简洁具体。每句话都应该赚到它的位置。如果您需要更深的深度，请链接到外部文档而不是嵌入它。

我应该将 CLAUDE.md 提交到版本控制吗？ 绝对地。CLAUDE.md 应该像任何其他项目文档一样对待——版本化、审查和保持最新。您的整个团队都会受益于一致的 AI 行为。个人偏好改为放在 ~/.claude/CLAUDE.md 中，这保持在每个开发人员机器的本地。

CLAUDE.md 与 .cursorrules 有何不同？ 内容几乎相同——两者都为 AI 编码工具提供项目上下文。区别在于哪种工具读取它们。CLAUDE.md 适用于 Claude Code（Anthropic 的 CLI 工具），而 .cursorrules 适用于 Cursor IDE。如果您使用两种工具，请维护一个事实来源并将其复制到两个文件，根据任何特定于工具的格式进行调整。

CLAUDE.md 的最重要部分是什么？ 「不要」部分。负指令对 AI 模型的效果不成比例。告诉 Claude 要避免什么——不要使用 any 类型、不要不必要地添加 "use client"、不要在没有询问的情况下安装新包——可以防止最常见和最令人沮丧的错误。一个好的禁止列表节省的时间比数页积极指令还多。

我可以为非代码项目使用 CLAUDE.md 吗？ 是的。CLAUDE.md 适用于任何您与 Claude Code 交互的项目。我已经为文档 repos、基础设施即代码项目甚至数据分析管道看到了有效的。原理是相同的：给 Claude 它需要对您的特定项目做出良好决定的上下文。

我应该多频繁更新 CLAUDE.md？ 在每次重大重构时审查它，至少每个 sprint 一次。如果您升级框架版本、更改关键依赖项或采用新约定，请立即更新文件。陈旧的上下文比没有上下文更糟糕，因为它会主动误导 AI。一些团队将 CLAUDE.md 审查添加到他们的 PR 清单中以进行基础设施更改。

CLAUDE.md 适用于 Web 上的 Claude（claude.ai）吗？ 不。CLAUDE.md 专门由 Claude Code 读取，这是基于 CLI 的编码工具。如果您通过 Web 界面或 API 使用 Claude，您需要手动粘贴上下文或使用项目功能将其附加为知识文件。Claude Code 的自动加载是使文件如此强大的原因——零摩擦，每个会话。