CLAUDE.md 最佳实践

Ehtan_Zheng
0 阅读8分钟

CLAUDE.md 是为 Claude Code 提供项目特定上下文的关键文件。它充当了 AI 了解项目需求和代码库的“入职指南”。每当 Claude 的 AI 模型在你的项目中编写新代码或修改现有代码时，它做的第一件事就是检查 CLAUDE.md 文件。

在本文中，我将分享制作一份优秀的 CLAUDE.md 文件并优化编码流程所需了解的所有信息。

文件位置、文件格式以及 Claude AI 如何使用它

CLAUDE.md 文件通常放置在项目存储库的根目录中。例如，如果你正在开发一个 React Web 应用程序，你应该拥有如下的目录结构。

image.png

该文件本身采用 Markdown 格式编写（.md 代表 Markdown）。

## Project Overview  
Short explanation of what the project is.  
  
## Tech Stack  
- TypeScript  
- Next.js  
- Tailwind  
- ShadCN  
  
## Architecture  
Explain folders and patterns.  
  
## Coding Rules  
- Use functional React components  
- Prefer server components  
- Use Tailwind utilities instead of custom CSS  
  
## Design System  
- Follow ShadCN patterns  
- Use tokens from /styles/tokens.ts  
  
## Commands  
npm run dev  
npm run build

Anthropic 的官方文档指出，CLAUDE.md 是 Claude Code 项目记忆的一部分，会在每次对话开始时加载；此外，Claude 将其视为**上下文（context）**而非硬性强制要求。

常见部分

尽管每个项目都各不相同，且无法为 CLAUDE.md 文件提供一个通用的模板，但仍可以列出对大多数项目都适用的 10 个关键部分：

项目概览

这是对 Claude 价值最高的部分，用于建立上下文。在此部分，你应该用通俗易懂的语言解释：

  • 产品是什么
  • 它的受众是谁
  • 应用程序试图优化什么
  • 最重要的业务或用户体验（UX）约束

最佳实践

请保持在几个段落以内, 相比于冗长的品牌故事，Claude 在面对清晰简洁的心理模型时表现更好。

❌ 错误：

  • 包含大量公司历史背景的冗长起源故事
  • 像“我们重视创新”这样通用的陈述
  • 与实际执行无关的营销文案

✅ 正确：

  • “这是一个面向运营经理的 B2B 分析仪表盘。”
  • “主要目标：缩短获取洞察的时间。”
## 项目概览

本项目是一个供产品设计师使用的 Web 应用程序，旨在利用 AI 生成并优化落地页（Landing Pages）。

主要用户是希望快速获得高质量产出的初创公司创始人及营销人员。

产品针对以下方面进行优化：

-   视觉精致度
-   迭代速度
-   简洁的响应式代码
-   方便移交给工程团队

避免过度工程。相较于奇巧的代码，更偏好清晰的代码。

技术栈

这一部分可以防止许多错误的假设。如果没有它，Claude 可能会引入一些在技术上可行、但对你的项目来说是错误的选择。

请列出实际使用的技术：

  • 框架
  • 编程语言
  • 样式系统
  • 组件库
  • 状态管理
  • 测试框架
  • 构建工具
  • 后端/数据层（如果相关）

最佳实践

表述要明确。当你实际使用的是“Next.js App Router + TypeScript + Tailwind + shadcn/ui + Supabase”时，不要只写“React 技术栈”。

## Tech Stack  
- Next.js 15 with App Router  
- TypeScript  
- Tailwind CSS  
- shadcn/ui  
- React Hook Form + Zod for forms  
- Supabase for auth and data  
- Vitest for unit tests  
  
Do not introduce:  
- Redux  
- styled-components  
- Material UI  
unless explicitly requested.

架构

这是你教导 Claude 仓库是如何组织的地方。

你需要描述：

  • 主要目录
  • 各个区域的职责
  • 数据流向
  • 关注点分离
  • 新代码应该放在哪里

最佳实践

重点关注决策规则，而不仅仅是文件夹名称。

❌ 错误：

src/components contains components

✅ 正确：

Use `src/components/ui` for reusable presentational components.  
Use `src/features/*` for domain-specific UI and logic.  
Keep API calls out of presentational components.

完整示例

## Architecture  
- `app/` contains routes and server components  
- `components/ui/` contains reusable design-system components  
- `components/marketing/` contains landing-page sections  
- `lib/` contains utilities, API helpers, and shared config  
- `features/` contains feature-specific business logic  
- `types/` contains shared TypeScript types  
  
Rules:  
- Keep page-level composition in route files  
- Move repeated UI into reusable components  
- Keep side effects out of UI components when possible  
- Prefer server-side data fetching unless client interactivity is required

重要提示

如果你使用了第三方服务的 API 调用，并需要存储 API 密钥来访问这些工具，建议将这些密钥保存在项目根目录下的特定文件中 API keys are stored in '.env'

编码规范

与项目概览一样，我认为这是整个文件中第二重要的部分，因为它直接影响 Claude 输出的代码质量。它决定了代码对于任何阅读者来说是否易读且清晰。

你需要包含任何会影响日常代码生成的规范：

  • 命名约定
  • 组件模式
  • 类型定义标准
  • 文件大小偏好
  • 导入（import）约定
  • 错误处理
  • 注释规范
  • 异步模式

最佳实践

使用清晰的规则，而非模糊的偏好。

❌ 错误：

"Write clean code"

✅ 正确：

"Use named exports except for route files"  
  
"Avoid any; prefer inferred types or explicit interfaces"  
  
"Keep components under 200 lines unless justified"

完整示例

## Coding Conventions  
- Use TypeScript strictly; avoid `any`  
- Prefer functional components  
- Prefer named exports for shared modules  
- Use async/await instead of chained promises  
- Keep components focused and composable  
- Extract repeated logic into hooks or helpers  
- Prefer descriptive variable names over abbreviations  
- Add comments only when intent is non-obvious  
- Do not leave dead code or commented-out blocks

UI 与设计系统规则

对于前端项目，这一部分至关重要。

请定义：

  • 视觉风格
  • 间距理念
  • 字体排版方案
  • 交互模式
  • 响应式规范
  • 无障碍（Accessibility）预期
  • 组件使用规则
## UI 与设计规范

-   默认使用 shadcn/ui 组件作为基础
-   偏好宽敞的布局和强烈的视觉层级
-   颜色使用需克制；依赖字体排版、间距和对比度
-   优先采用 8px 间距
-   按钮应具有明确的主次层级
-   表单应简洁、易于扫描且对移动端友好
-   每个交互元素必须具备可见的悬停（hover）、聚焦（focus）和禁用（disabled）状态
-   满足对比度、标签和键盘导航的无障碍要求

如果你想在设计中实现某种特定的视觉风格，不要只说“让它看起来更现代”。这在操作层面没有任何意义。请务必将风格转化为具体的实现指南。

内容与文案指南

这一部分常被低估，特别是对于落地页和产品开发工作而言。

说明文案的风格：

  • 简洁还是详尽
  • 技术性语言还是通俗语言
  • 启发性还是务实性
  • 句子长度
  • 标题风格
  • 禁忌模式

最佳实践

包含适合你产品的优秀文案示例。提供指向现有品牌指南（包含语调和风格）的链接。

## 内容指南

-   使用简洁、自信的语言
-   避免夸大宣传和空洞的营销词汇
-   标题应优先保证清晰，而非追求奇巧
-   正文应侧重于用户产出结果
-   偏好短段落和易于扫描的结构
-   除非受众明确期望，否则避免使用专业术语

测试与质量标准

Claude 应该了解如何验证已完成的工作。

请定义：

  • 需要添加哪些测试
  • 何时需要进行测试
  • 代码检查（Lint）/类型检查的预期
  • “完成（Done）”的定义标准

以下操作设置将防止 Claude 出现测试不足或测试过度的情况：

## 测试与质量

在认为任务完成之前，请执行：

-   运行类型检查（typecheck）
-   运行代码检查（lint）
-   为修改后的逻辑运行相关的测试

测试规则：

-   为可复用的逻辑添加单元测试
-   不要为简单的展示性部分添加沉重的测试脚手架
-   确保 UI 更改后的响应式行为正常
-   在相关位置验证空状态、加载状态和错误状态

在 CLAUDE.md 中明确业务逻辑（Business Logic）的测试要求，能有效防止 AI 在修改代码时破坏核心业务规则。

文件与组件放置规则

这一部分值得独立成段，因为它能防止仓库架构“走样”。在成熟的仓库中，重复组件会迅速成为难题，而该部分规则能有效解决这一痛点。

你需要定义以下规则：

  • 在何处创建新文件
  • 何时该修改现有文件
  • 何时应该进行抽象（提取公共组件/逻辑）
  • 命名模式

最佳实践

明确划分“局部”与“全局”的界限。例如，规定只有在三个以上页面使用的代码才允许进入 src/lib 或 src/components/common。

## 文件放置规则

-   将新的落地页片段（Sections）添加到 `components/marketing/sections`
-   将可复用的基础组件（Primitives）添加到 `components/ui`
-   将共享的辅助函数（Helpers）存放在 `lib`
-   **不要**为仅使用一次的内容创建新的抽象
-   优先**修改现有组件**，而非创建高度重复的副本

安全变更规则 (Safe-change rules)

这在真实项目中极具价值。明确告诉 Claude 哪些内容不应随意更改，可以有效减少那些“技术上很聪明但操作上风险极大”的修改，避免后续产生高昂的重构成本。

## 安全变更规则

-   除非明确要求，否则**禁止重命名**公共 API 路由
-   **禁止在未明确说明的情况下**修改数据库模式（Schema）
-   除非任务有特定要求，否则**禁止修改**身份验证（Auth）流程
-   必须保持共享组件的**向后兼容性**
-   在实施重大架构调整前，必须**先行提醒并确认**

具体命令 (Specific Commands)

Anthropic 建议为 Claude 提供具体的项目上下文，而命令是这些操作上下文中不可或缺的一部分。

直接提供 Claude 应该使用的真实且当前的命令。这能让它在无需猜测的情况下执行安装、运行、测试或格式化操作。

## Commands  
- Install: `pnpm install`  
- Dev: `pnpm dev`  
- Build: `pnpm build`  
- Lint: `pnpm lint`  
- Typecheck: `pnpm typecheck`  
- Test: `pnpm test`
avatar
文章
阅读
粉丝