如何编写完美的 CLAUDE.md 文件 (2026)

如何在 2026 年编写完美的 CLAUDE.md 文件

CLAUDE.md 文件是你在使用 Claude Code 的项目中可以添加的最具影响力的单体文件。它充当了一个持久的系统提示词，Claude 每次在你的代码库中启动会话时都会读取它。一个编写良好的 CLAUDE.md 可以极大减少错误、强制执行编码标准，并帮助 Claude 理解你的项目架构，而无需你每次都重新解释。

本指南涵盖了编写高效 CLAUDE.md 文件所需的所有知识，并提供了模板和真实案例。

什么是 CLAUDE.md？

CLAUDE.md 是放置在项目根目录（或全局设置位于 ~/.claude/CLAUDE.md）的一个 Markdown 文件。当 Claude Code 在目录中启动时，它会自动读取该文件并将其作为所有交互的上下文。

你可以把它看作：

为 AI 助手准备的 README，而不是为人类开发者准备的
一个跨会话持久存在的 系统提示词 (System Prompt)
一份 Claude 能够真正遵守的 编码规范文档

CLAUDE.md 放置位置

Claude Code 按以下顺序搜索 CLAUDE.md 文件：

位置	作用域	使用场景
`~/.claude/CLAUDE.md`	全局（所有项目）	个人偏好、默认配置
`./CLAUDE.md`	项目根目录	特定项目的上下文和规则
`./src/CLAUDE.md`	子目录	特定模块的指令

所有找到的文件都会被拼接在一起，较具体的文件优先级更高。

核心组成板块

一个优秀的 CLAUDE.md 文件应包含以下板块：

1. 项目概览 (Project Overview)

用 2-3 句话告诉 Claude 项目是什么。这可以防止 Claude 进行盲目猜测。

# Project Overview
这是一个基于 Next.js 14 (App Router)、TypeScript 和 Tailwind CSS 构建的 AI 媒体生成 SaaS 平台。
后端使用 Supabase 处理认证和数据库，Stripe 处理支付，并包含一个用于 AI 模型推理的自定义 API 层。

2. 技术栈 (Tech Stack)

列出所有主要的技术、框架和库。请明确版本号。

# Tech Stack
- Framework: Next.js 14.2 (App Router, NOT Pages Router)
- Language: TypeScript 5.4 (strict mode)
- Styling: Tailwind CSS 3.4 + shadcn/ui components
- Database: PostgreSQL via Supabase
- ORM: Prisma 5.x
- Auth: NextAuth.js v5 (Auth.js)
- Payments: Stripe (subscriptions + one-time)
- State: Zustand for client state
- Forms: React Hook Form + Zod validation
- Testing: Vitest + React Testing Library
- Package manager: pnpm (NOT npm or yarn)

3. 项目结构 (Project Structure)

映射出关键目录，以便 Claude 知道在哪里查找和放置文件。

# Project Structure
- src/app/ - Next.js App Router 页面和布局
- src/app/api/ - API 路由处理程序
- src/app/[locale]/ - 国际化路由
- src/components/ - 可复用的 React 组件
- src/components/ui/ - shadcn/ui 基础组件 (请勿修改)
- src/lib/ - 工具函数、API 客户端、助手函数
- src/hooks/ - 自定义 React hooks
- src/types/ - TypeScript 类型定义
- src/config/ - 应用配置文件
- prisma/ - 数据库 Schema 和迁移文件
- content/ - MDX 博客文章
- messages/ - i18n 翻译 JSON 文件
- public/ - 静态资源

4. 编码规范 (Coding Conventions)

这是最重要的部分。请明确你的编码标准。

# Coding Conventions

## General
- 使用带有 hooks 的函数式组件 (不要使用类组件)
- 优先使用具名导出 (named exports)，而非默认导出 (default exports)
- 使用以 @/ 为前缀的绝对导入 (例如：@/components/Button)
- 所有文件使用 TypeScript (.ts/.tsx)，严禁使用纯 JavaScript

## Naming
- Components: PascalCase (如 UserProfile.tsx)
- Hooks: camelCase 并加 "use" 前缀 (如 useAuth.ts)
- Utilities: camelCase (如 formatDate.ts)
- Types: PascalCase 且名称具有描述性 (如 UserProfile, ApiResponse)
- Constants: UPPER_SNAKE_CASE
- CSS classes: 使用 Tailwind 工具类，避免自定义 CSS

## Components
- 每个文件一个组件
- 在组件上方定义 Props 接口
- 谨慎使用 React.FC；优先使用明确的返回类型
- 在函数签名中解构 props
- 仅在必要时使用 "use client" 指令

## Error Handling
- 在 API 路由和 Server Actions 中使用 try/catch
- 返回结构化的错误响应：{ error: string, code: number }
- 严禁向客户端泄露内部错误细节
- 使用 console.error 在服务端记录错误

## Imports Order
1. React/Next.js 导入
2. 第三方库导入
3. 内部导入 (@/)
4. 类型导入
5. 相对路径导入

5. 重要规则与约束 (Important Rules and Constraints)

这里放置 Claude 绝对不能违反的硬性规则。

# Important Rules
- 永远不要修改 src/components/ui/ 中的文件 (这些是 shadcn/ui 生成的)
- 严禁提交 .env 文件或硬编码密钥
- 始终使用 Server Actions 进行数据变更，而不是 API 路由
- 使用 hooks 或事件处理程序时，始终添加 "use client"
- 在认为任务完成前，必须运行 `pnpm lint`
- 数据库迁移必须通过 `pnpm prisma migrate dev` 创建
- 严禁删除或修改现有的迁移文件
- 所有面向用户的文本必须使用 i18n 系统 (useTranslations)
- 严禁使用 `any` 类型；如果类型确实未知，请使用 `unknown`

6. 常用命令 (Common Commands)

列出 Claude 构建、测试和校验项目所需的命令。

# Common Commands
- `pnpm dev` - 启动开发服务器
- `pnpm build` - 生产环境构建
- `pnpm lint` - 运行 ESLint
- `pnpm typecheck` - 运行 TypeScript 类型检查
- `pnpm test` - 运行测试套件
- `pnpm test:watch` - 以监听模式运行测试
- `pnpm prisma generate` - 重新生成 Prisma 客户端
- `pnpm prisma migrate dev` - 创建并运行迁移
- `pnpm prisma studio` - 打开数据库浏览器

7. API 与数据模式 (API and Data Patterns)

记录应用程序中的数据流向。

# Data Patterns

## API Routes
API 路由位于 src/app/api/。使用 Next.js Route Handler 格式：
export async function POST(request: Request) { ... }

## Server Actions
数据变更优先使用 Server Actions 而非 API 路由。
Server Actions 位于 src/lib/actions/ 并使用 "use server" 指令。

## Database Queries
所有数据库查询均通过 Prisma。客户端位于 src/lib/db.ts。
严禁直接在组件中查询数据库。

## Authentication
使用 src/lib/auth.ts 中的 auth() 助手获取当前会话。
受保护的 API 路由应在处理程序顶部检查认证。

完整模板

你可以直接适配以下完整的 CLAUDE.md 模板：

# Project Overview
[用 2-3 句话描述你的项目]

# Tech Stack
- Framework: [框架及其版本]
- Language: [语言及其版本]
- Styling: [样式方案]
- Database: [数据库]
- Auth: [认证方案]
- Testing: [测试框架]
- Package manager: [pnpm/npm/yarn]

# Project Structure
- src/app/ - [描述]
- src/components/ - [描述]
- src/lib/ - [描述]
[根据需要添加更多]

# Coding Conventions
[你的编码标准]

# Important Rules
- 严禁 [关键约束]
- 始终 [必须执行的实践]
[根据需要添加更多]

# Common Commands
- `[命令]` - [描述]
[根据需要添加更多]

# Data Patterns
[应用中的数据流向]

# Known Issues
[Claude 应该注意的任何坑或已知问题]

高级技巧

为子目录使用 CLAUDE.md

如果你使用的是 Monorepo（单仓多包）或复杂项目，可以在子目录中添加 CLAUDE.md：

project/
  CLAUDE.md           # 根目录级别的项目上下文
  packages/
    api/
      CLAUDE.md       # API 特有的规范
    web/
      CLAUDE.md       # 前端特有的规范

包含优秀模式的代码示例

与其只是描述规范，不如展示它们：

# Example: Creating a New API Route

这是一个新 API 路由的标准模式：

\`\`\`typescript
import { auth } from "@/lib/auth";
import { db } from "@/lib/db";
import { NextResponse } from "next/server";

export async function GET(request: Request) {
  const session = await auth();
  if (!session?.user) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  try {
    const data = await db.item.findMany({
      where: { userId: session.user.id },
    });
    return NextResponse.json(data);
  } catch (error) {
    console.error("Failed to fetch items:", error);
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 }
    );
  }
}
\`\`\`

引用关键文件

指引 Claude 阅读重要文件：

# Key Files
- src/lib/auth.ts - 认证配置和助手函数
- src/lib/db.ts - 数据库客户端和连接
- src/types/index.ts - 共享类型定义
- .env.example - 必要的环境变量模板

保持更新

将 CLAUDE.md 视为一份动态文档。当你变更规范时，更新该文件。当 Claude 犯错时，添加一条规则以防再次发生。

应避免的常见错误

过于笼统：“使用良好的编码实践”对 Claude 毫无用处。请具体化。
篇幅过长：Claude 有上下文窗口限制。保持在 500 行以内。
自相矛盾：不要在一处说“使用具名导出”，却在示例中使用默认导出。
忽略反向约束：不仅要告诉 Claude 该做什么，还要告诉它不该做什么。
遗漏技术栈：Claude 可能会误判框架版本。

衡量效果

添加 CLAUDE.md 后，观察 Claude 是否：

无需提醒即可遵循你的命名规范
将文件放置在正确的目录中
使用正确的导入路径和模式
避开了你在“重要规则”中列出的错误
运行了正确的 build/lint 命令

如果 Claude 持续犯同样的错误，请在你的 CLAUDE.md 中添加更明确的规则。

结语

一个编写精良的 CLAUDE.md 文件，决定了 Claude Code 是一个通用的 AI 助手，还是一个理解你项目的上下文感知型团队成员。投入 30 分钟写一个好的文件，将为你节省数小时的纠错和重复解释时间。

如果你正在构建需要 AI 媒体生成能力的应用（图像、视频、音频或会话化身），Hypereal AI 通过单一 API 提供所有这些功能。凭借按需付费、快速生成且对创意作品无内容限制等特点，它是为产品添加 AI 媒体最简便的方式。

如何在 2026 年编写完美的 CLAUDE.md 文件

本指南涵盖了编写高效 CLAUDE.md 文件所需的所有知识，并提供了模板和真实案例。

什么是 CLAUDE.md？

你可以把它看作：

为 AI 助手准备的 README，而不是为人类开发者准备的
一个跨会话持久存在的 系统提示词 (System Prompt)
一份 Claude 能够真正遵守的 编码规范文档

CLAUDE.md 放置位置

Claude Code 按以下顺序搜索 CLAUDE.md 文件：

位置	作用域	使用场景
`~/.claude/CLAUDE.md`	全局（所有项目）	个人偏好、默认配置
`./CLAUDE.md`	项目根目录	特定项目的上下文和规则
`./src/CLAUDE.md`	子目录	特定模块的指令

所有找到的文件都会被拼接在一起，较具体的文件优先级更高。

核心组成板块

一个优秀的 CLAUDE.md 文件应包含以下板块：

1. 项目概览 (Project Overview)

用 2-3 句话告诉 Claude 项目是什么。这可以防止 Claude 进行盲目猜测。

# Project Overview
这是一个基于 Next.js 14 (App Router)、TypeScript 和 Tailwind CSS 构建的 AI 媒体生成 SaaS 平台。
后端使用 Supabase 处理认证和数据库，Stripe 处理支付，并包含一个用于 AI 模型推理的自定义 API 层。

2. 技术栈 (Tech Stack)

列出所有主要的技术、框架和库。请明确版本号。

# Tech Stack
- Framework: Next.js 14.2 (App Router, NOT Pages Router)
- Language: TypeScript 5.4 (strict mode)
- Styling: Tailwind CSS 3.4 + shadcn/ui components
- Database: PostgreSQL via Supabase
- ORM: Prisma 5.x
- Auth: NextAuth.js v5 (Auth.js)
- Payments: Stripe (subscriptions + one-time)
- State: Zustand for client state
- Forms: React Hook Form + Zod validation
- Testing: Vitest + React Testing Library
- Package manager: pnpm (NOT npm or yarn)

3. 项目结构 (Project Structure)

映射出关键目录，以便 Claude 知道在哪里查找和放置文件。

# Project Structure
- src/app/ - Next.js App Router 页面和布局
- src/app/api/ - API 路由处理程序
- src/app/[locale]/ - 国际化路由
- src/components/ - 可复用的 React 组件
- src/components/ui/ - shadcn/ui 基础组件 (请勿修改)
- src/lib/ - 工具函数、API 客户端、助手函数
- src/hooks/ - 自定义 React hooks
- src/types/ - TypeScript 类型定义
- src/config/ - 应用配置文件
- prisma/ - 数据库 Schema 和迁移文件
- content/ - MDX 博客文章
- messages/ - i18n 翻译 JSON 文件
- public/ - 静态资源

4. 编码规范 (Coding Conventions)

这是最重要的部分。请明确你的编码标准。

# Coding Conventions

## General
- 使用带有 hooks 的函数式组件 (不要使用类组件)
- 优先使用具名导出 (named exports)，而非默认导出 (default exports)
- 使用以 @/ 为前缀的绝对导入 (例如：@/components/Button)
- 所有文件使用 TypeScript (.ts/.tsx)，严禁使用纯 JavaScript

## Naming
- Components: PascalCase (如 UserProfile.tsx)
- Hooks: camelCase 并加 "use" 前缀 (如 useAuth.ts)
- Utilities: camelCase (如 formatDate.ts)
- Types: PascalCase 且名称具有描述性 (如 UserProfile, ApiResponse)
- Constants: UPPER_SNAKE_CASE
- CSS classes: 使用 Tailwind 工具类，避免自定义 CSS

## Components
- 每个文件一个组件
- 在组件上方定义 Props 接口
- 谨慎使用 React.FC；优先使用明确的返回类型
- 在函数签名中解构 props
- 仅在必要时使用 "use client" 指令

## Error Handling
- 在 API 路由和 Server Actions 中使用 try/catch
- 返回结构化的错误响应：{ error: string, code: number }
- 严禁向客户端泄露内部错误细节
- 使用 console.error 在服务端记录错误

## Imports Order
1. React/Next.js 导入
2. 第三方库导入
3. 内部导入 (@/)
4. 类型导入
5. 相对路径导入

5. 重要规则与约束 (Important Rules and Constraints)

这里放置 Claude 绝对不能违反的硬性规则。

# Important Rules
- 永远不要修改 src/components/ui/ 中的文件 (这些是 shadcn/ui 生成的)
- 严禁提交 .env 文件或硬编码密钥
- 始终使用 Server Actions 进行数据变更，而不是 API 路由
- 使用 hooks 或事件处理程序时，始终添加 "use client"
- 在认为任务完成前，必须运行 `pnpm lint`
- 数据库迁移必须通过 `pnpm prisma migrate dev` 创建
- 严禁删除或修改现有的迁移文件
- 所有面向用户的文本必须使用 i18n 系统 (useTranslations)
- 严禁使用 `any` 类型；如果类型确实未知，请使用 `unknown`

6. 常用命令 (Common Commands)

列出 Claude 构建、测试和校验项目所需的命令。

# Common Commands
- `pnpm dev` - 启动开发服务器
- `pnpm build` - 生产环境构建
- `pnpm lint` - 运行 ESLint
- `pnpm typecheck` - 运行 TypeScript 类型检查
- `pnpm test` - 运行测试套件
- `pnpm test:watch` - 以监听模式运行测试
- `pnpm prisma generate` - 重新生成 Prisma 客户端
- `pnpm prisma migrate dev` - 创建并运行迁移
- `pnpm prisma studio` - 打开数据库浏览器

7. API 与数据模式 (API and Data Patterns)

记录应用程序中的数据流向。

# Data Patterns

## API Routes
API 路由位于 src/app/api/。使用 Next.js Route Handler 格式：
export async function POST(request: Request) { ... }

## Server Actions
数据变更优先使用 Server Actions 而非 API 路由。
Server Actions 位于 src/lib/actions/ 并使用 "use server" 指令。

## Database Queries
所有数据库查询均通过 Prisma。客户端位于 src/lib/db.ts。
严禁直接在组件中查询数据库。

## Authentication
使用 src/lib/auth.ts 中的 auth() 助手获取当前会话。
受保护的 API 路由应在处理程序顶部检查认证。

完整模板

你可以直接适配以下完整的 CLAUDE.md 模板：

# Project Overview
[用 2-3 句话描述你的项目]

# Tech Stack
- Framework: [框架及其版本]
- Language: [语言及其版本]
- Styling: [样式方案]
- Database: [数据库]
- Auth: [认证方案]
- Testing: [测试框架]
- Package manager: [pnpm/npm/yarn]

# Project Structure
- src/app/ - [描述]
- src/components/ - [描述]
- src/lib/ - [描述]
[根据需要添加更多]

# Coding Conventions
[你的编码标准]

# Important Rules
- 严禁 [关键约束]
- 始终 [必须执行的实践]
[根据需要添加更多]

# Common Commands
- `[命令]` - [描述]
[根据需要添加更多]

# Data Patterns
[应用中的数据流向]

# Known Issues
[Claude 应该注意的任何坑或已知问题]

高级技巧

为子目录使用 CLAUDE.md

如果你使用的是 Monorepo（单仓多包）或复杂项目，可以在子目录中添加 CLAUDE.md：

project/
  CLAUDE.md           # 根目录级别的项目上下文
  packages/
    api/
      CLAUDE.md       # API 特有的规范
    web/
      CLAUDE.md       # 前端特有的规范

包含优秀模式的代码示例

与其只是描述规范，不如展示它们：

# Example: Creating a New API Route

这是一个新 API 路由的标准模式：

\`\`\`typescript
import { auth } from "@/lib/auth";
import { db } from "@/lib/db";
import { NextResponse } from "next/server";

export async function GET(request: Request) {
  const session = await auth();
  if (!session?.user) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  try {
    const data = await db.item.findMany({
      where: { userId: session.user.id },
    });
    return NextResponse.json(data);
  } catch (error) {
    console.error("Failed to fetch items:", error);
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 }
    );
  }
}
\`\`\`

引用关键文件

指引 Claude 阅读重要文件：

# Key Files
- src/lib/auth.ts - 认证配置和助手函数
- src/lib/db.ts - 数据库客户端和连接
- src/types/index.ts - 共享类型定义
- .env.example - 必要的环境变量模板

保持更新

将 CLAUDE.md 视为一份动态文档。当你变更规范时，更新该文件。当 Claude 犯错时，添加一条规则以防再次发生。

应避免的常见错误

过于笼统：“使用良好的编码实践”对 Claude 毫无用处。请具体化。
篇幅过长：Claude 有上下文窗口限制。保持在 500 行以内。
自相矛盾：不要在一处说“使用具名导出”，却在示例中使用默认导出。
忽略反向约束：不仅要告诉 Claude 该做什么，还要告诉它不该做什么。
遗漏技术栈：Claude 可能会误判框架版本。

衡量效果

添加 CLAUDE.md 后，观察 Claude 是否：

无需提醒即可遵循你的命名规范
将文件放置在正确的目录中
使用正确的导入路径和模式
避开了你在“重要规则”中列出的错误
运行了正确的 build/lint 命令

如果 Claude 持续犯同样的错误，请在你的 CLAUDE.md 中添加更明确的规则。

开始使用 Hypereal 构建

如何在 2026 年编写完美的 CLAUDE.md 文件

什么是 CLAUDE.md？

CLAUDE.md 放置位置

核心组成板块

1. 项目概览 (Project Overview)

2. 技术栈 (Tech Stack)

3. 项目结构 (Project Structure)

4. 编码规范 (Coding Conventions)

5. 重要规则与约束 (Important Rules and Constraints)

6. 常用命令 (Common Commands)

7. API 与数据模式 (API and Data Patterns)

完整模板

高级技巧

为子目录使用 CLAUDE.md

包含优秀模式的代码示例

引用关键文件

保持更新

应避免的常见错误

衡量效果

结语

相关文章

Claude Code 入门指南与最佳实践 (2026)

如何使用 Claude Code 编写更好的代码 (2026)

Claude Code IDE 集成：VS Code、JetBrains 等 (2026)

立即开始构建

开始使用 Hypereal 构建

如何在 2026 年编写完美的 CLAUDE.md 文件

什么是 CLAUDE.md？

CLAUDE.md 放置位置

核心组成板块

1. 项目概览 (Project Overview)

2. 技术栈 (Tech Stack)

3. 项目结构 (Project Structure)

4. 编码规范 (Coding Conventions)

5. 重要规则与约束 (Important Rules and Constraints)

6. 常用命令 (Common Commands)

7. API 与数据模式 (API and Data Patterns)

完整模板

高级技巧

为子目录使用 CLAUDE.md

包含优秀模式的代码示例

引用关键文件

保持更新

应避免的常见错误

衡量效果

结语

相关文章

Claude Code 入门指南与最佳实践 (2026)

如何使用 Claude Code 编写更好的代码 (2026)

Claude Code IDE 集成：VS Code、JetBrains 等 (2026)

立即开始构建