CLAUDE.md：AI 编程效率的秘密武器

简介

CLAUDE.md 是放置在项目根目录的一个简单 Markdown 文件，它相当于 Claude 的"备忘录"。通过记录常用命令、编码规范和架构决策，你可以让 Claude：

• 执行正确的命令（构建、测试、lint）无需猜测
• 一致地遵循你的编码风格
• 即时理解你的项目结构
• 减少对不存在的库或脚本的幻觉

什么是 CLAUDE.md？

在 AI 辅助编程时代，上下文就是王道。虽然 Cursor 和 Claude Code 等工具功能强大，但它们往往缺乏关于你的特定项目设置的具体知识。它们可能在你使用 pnpm test 时尝试 npm test，或者在你严格使用函数式 hooks 时建议使用 React 类组件。

CLAUDE.md 帮助弥合这个差距。它是一种约定——一个专门为 AI 助手阅读而编写的文档文件。它不是代码，但它指导代码生成过程。

为什么需要它

1. 零样本准确性

不再需要在每次会话开始时解释"我们使用 Tailwind，组件通常放在 src/ui"，Claude 读取 CLAUDE.md 后就能立即"理解"。

2. 命令可靠性

AI 经常猜测如何启动服务器或运行特定测试套件。通过明确列出这些命令，你可以确保 Claude 每次都执行正确的操作。

3. 风格一致性

你可以通过配置文件强制执行 lint 规则，但高级架构决策（例如"数据访问始终使用 Repository 模式"）最好通过 CLAUDE.md 中的自然语言来传达。

完美的 CLAUDE.md 模板

这是一个你可以复制并适应你项目的稳健结构：

# CLAUDE.md

## 构建和运行命令
- **运行开发服务器**: `npm run dev`（在 localhost:3000 运行）
- **构建**: `npm run build`
- **Lint**: `npm run lint`
- **类型检查**: `npm run type-check`
- **测试**: `npm test`（监视模式：`npm test -- --watch`）

## 技术栈
- **框架**: Next.js 14（App Router）
- **样式**: Tailwind CSS
- **状态管理**: Zustand
- **认证**: Clerk
- **数据库**: PostgreSQL 配合 Prisma ORM

## 编码规范
- **组件**: 仅使用函数式组件，使用箭头函数
- **样式**: 使用工具类（Tailwind），除非必要否则避免 CSS 模块
- **导入**: 使用绝对导入 `@/components/...` 而非相对路径 `../../`
- **错误处理**: 在 server actions 中使用 `try/catch`；UI 错误使用 toast 显示
- **命名**: 变量/函数使用 camelCase，组件使用 PascalCase

## 项目结构
- `src/app`: App Router 页面和布局
- `src/components/ui`: 可复用的 UI 基础组件（按钮、输入框）
- `src/lib`: 工具函数和数据库客户端
- `src/actions`: 用于数据变更的 Server actions

如何有效使用

1. 保持简洁

Claude 有很大的上下文窗口，但简洁有助于聚焦。要点式比长段落更好。

2. 经常更新

如果你将包管理器从 npm 换成 bun，更新 CLAUDE.md。如果你引入了新的架构模式，添加它。将其视为一个活文档。

3. 引用它

在开始复杂任务时，你可以明确提示：

"读取 CLAUDE.md，然后实现用户登录功能。"

大多数具有文件感知能力的高级 AI 编程工具会自动索引根目录中的这个文件，但明确提及可确保它在优先级列表中排名靠前。

CLAUDE.md vs .cursorrules

如果你使用 Cursor，你可能熟悉 .cursorrules。

• .cursorrules: 最适合特定的提示指令（例如"始终用法语回复"、"保持简洁"）。它是系统提示覆盖。
• CLAUDE.md: 最适合项目事实知识（命令、技术栈、结构）。

它们可以完美配合使用。.cursorrules 用于行为，CLAUDE.md 用于知识。

结论

创建一个 CLAUDE.md 文件大约需要 5 分钟，但在项目的整个生命周期中可以节省数小时的纠正和澄清时间。它将一个通用的 AI 助手变成了你的代码库的专业专家。

今天就开始：创建这个文件，列出你最常用的 3 个命令，然后看着你的 AI 编程效率飙升。