Claude Code | | 约 16 分钟 | 6,091 字

CLAUDE.md 最佳实践：打造项目记忆

如何编写高效的 CLAUDE.md 让 Claude Code 真正理解你的项目

claude-code CLAUDE.md 项目配置 记忆

什么是 CLAUDE.md

CLAUDE.md 是 Claude Code 的”项目记忆文件”。每次启动会话时，Claude Code 会自动读取它，用来理解项目的上下文、约定和规则。

可以把它想象成给 AI 写的一份”项目入职手册”——你希望一个新同事加入团队时知道什么，就写什么。

项目根目录/
├── CLAUDE.md          ← Claude Code 启动时自动读取
├── src/
│   ├── CLAUDE.md      ← 进入 src 目录时额外加载
│   └── ...
├── package.json
└── ...

文件层级

CLAUDE.md 支持多层级配置，从全局到局部逐级细化：

层级位置作用范围优先级
用户级~/.claude/CLAUDE.md所有项目最低
项目根级项目根/CLAUDE.md当前项目中
子目录级项目根/src/CLAUDE.md特定目录最高

用户级 CLAUDE.md

放在 ~/.claude/CLAUDE.md，适合写通用偏好：

# 个人偏好

- 我偏好 TypeScript，使用 strict 模式
- 代码注释用中文
- commit message 用英文，遵循 Conventional Commits
- 测试框架偏好 Vitest

项目根级 CLAUDE.md

这是最重要的一层，放在项目根目录：

# 项目：AI Learning Blog

## 技术栈
- Astro 5.x + TypeScript
- Tailwind CSS 4.x
- 部署在 Cloudflare Pages

## 常用命令
- `npm run dev` - 启动开发服务器
- `npm run build` - 构建生产版本
- `npm run preview` - 预览构建结果

## 项目结构
- `src/content/blog/` - 博客文章（Markdown）
- `src/components/` - Astro 组件
- `src/layouts/` - 页面布局
- `src/pages/` - 路由页面

## 约定
- 文章使用中文撰写
- 技术术语保留英文
- 组件使用 PascalCase 命名

子目录级 CLAUDE.md

针对特定目录的补充说明：

# src/components/

## 组件约定
- 每个组件一个 .astro 文件
- Props 使用 TypeScript interface 定义
- 样式使用 Tailwind CSS class
- 不使用 CSS Modules

应该写什么

一份好的 CLAUDE.md 应该包含以下内容：

1. 项目概述

让 Claude Code 快速理解”这是什么项目”：

## 项目概述

这是一个面向中文开发者的 AI 学习博客，使用 Astro 构建。
主要内容包括 Claude Code 教程、Prompt Engineering 技巧和 AI 工具评测。
目标读者是有 1-3 年经验的中级开发者。

2. 技术栈和版本

明确技术选型，避免 Claude Code 用错版本的 API：

## 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Astro | 5.x | 静态站点生成器 |
| TypeScript | 5.x | 类型系统 |
| Tailwind CSS | 4.x | 原子化 CSS |
| Node.js | 22.x | 运行时 |

3. 常用命令

Claude Code 经常需要执行命令，提前告诉它：

## 常用命令

```bash
npm run dev          # 开发服务器 (localhost:4321)
npm run build        # 生产构建
npm run check        # Astro 类型检查
npm run lint         # ESLint 检查
npm run lint:fix     # ESLint 自动修复
npm test             # 运行测试
npm run test:watch   # 测试监听模式

### 4. 项目结构

帮助 Claude Code 快速定位文件：

```markdown
## 项目结构

src/ ├── components/ # 可复用组件 │ ├── Header.astro │ ├── Footer.astro │ └── … ├── content/ │ └── blog/ # 博客文章 │ ├── claude-code/ # Claude Code 系列 │ └── prompt/ # Prompt 系列 ├── layouts/ # 页面布局 │ ├── BaseLayout.astro │ └── ArticleLayout.astro ├── pages/ # 路由 │ ├── index.astro │ └── category/[category].astro └── styles/ # 全局样式

5. 编码约定

这是最容易被忽略但最重要的部分：

## 编码约定

### 命名规范
- 组件：PascalCase（`ShareButtons.astro`）
- 工具函数：camelCase（`formatDate.ts`）
- 常量：UPPER_SNAKE_CASE（`MAX_POSTS_PER_PAGE`）
- CSS class：kebab-case（`article-card`）

### TypeScript
- 启用 strict 模式
- 优先使用 interface 而非 type
- 避免 any，使用 unknown 替代
- 函数参数和返回值必须有类型注解

### Git
- commit message 遵循 Conventional Commits
- 分支命名：feature/xxx, fix/xxx, docs/xxx
- PR 必须通过 CI 检查才能合并

6. 架构决策

记录重要的技术决策和原因：

## 架构决策

### 为什么选择 Astro
- 博客以静态内容为主，Astro 的 Islands 架构最合适
- 零 JS 默认策略，性能优秀
- 原生支持 Markdown/MDX

### 为什么不用数据库
- 内容通过 Markdown 文件管理，Git 即数据库
- 部署在 Cloudflare Pages，无需服务器

### 为什么用 Tailwind CSS 4.x
- 原子化 CSS 减少样式冲突
- 4.x 版本使用 CSS-first 配置，更简洁

不应该写什么

CLAUDE.md 不是万能的。以下内容应该避免：

1. 不要写太长

Claude Code 每次启动都会读取 CLAUDE.md，太长会浪费 Token：

<!-- 不好：把整个 API 文档复制进来 -->
## API 文档
### GET /api/users
### GET /api/users/:id
### POST /api/users
... (500 行)

<!-- 好：给出指引 -->
## API 文档
API 文档在 `docs/api.md`，需要时请查阅。

2. 不要写显而易见的内容

<!-- 不好 -->
- JavaScript 文件以 .js 结尾
- 使用 npm install 安装依赖

<!-- 好 -->
- 使用 pnpm 而非 npm（项目锁文件是 pnpm-lock.yaml）

3. 不要写频繁变化的内容

<!-- 不好 -->
- 当前版本：v2.3.1
- 最近修改了 Header 组件的样式

<!-- 好 -->
- 版本号在 package.json 中管理
- 组件变更记录在 CHANGELOG.md 中

4. 不要写敏感信息

<!-- 绝对不要 -->
- API Key: sk-xxxxx
- 数据库密码: password123

<!-- 应该 -->
- 环境变量在 .env 文件中配置（不要提交到 Git）
- 参考 .env.example 了解需要的环境变量

实战模板

这是一个经过实践验证的 CLAUDE.md 模板：

# 项目名称

## 概述
一句话描述项目是什么、做什么。

## 技术栈
- 框架：xxx
- 语言：xxx
- 包管理器：xxx

## 快速开始
```bash
npm install
npm run dev

项目结构

src/
├── ...

编码约定

  • 命名规范
  • 代码风格
  • 测试要求

常用命令

  • 开发：npm run dev
  • 构建：npm run build
  • 测试：npm test
  • Lint：npm run lint

重要注意事项

  • 不要修改 xxx 文件
  • xxx 功能有已知限制
  • 部署前必须运行 xxx

---

## 保持 CLAUDE.md 更新的技巧

CLAUDE.md 最大的问题是容易过时。这里有几个保持它新鲜的方法：

### 1. 用 Hook 自动提醒

```bash
#!/bin/bash
# .claude/hooks/check-claude-md.sh
# 如果 CLAUDE.md 超过 30 天没更新，提醒一下
CLAUDE_MD="CLAUDE.md"
if [ -f "$CLAUDE_MD" ]; then
  LAST_MODIFIED=$(stat -f %m "$CLAUDE_MD" 2>/dev/null || stat -c %Y "$CLAUDE_MD" 2>/dev/null)
  NOW=$(date +%s)
  DAYS_AGO=$(( (NOW - LAST_MODIFIED) / 86400 ))
  if [ "$DAYS_AGO" -gt 30 ]; then
    echo "提醒：CLAUDE.md 已经 ${DAYS_AGO} 天没有更新了，考虑检查一下是否需要更新。"
  fi
fi

2. 在 PR 模板中加入检查项

## PR Checklist
- [ ] 代码通过 lint 检查
- [ ] 添加了必要的测试
- [ ] 如果修改了项目结构或约定，更新了 CLAUDE.md

3. 让 Claude Code 帮你更新

当你做了重大变更后，直接告诉 Claude Code：

我刚把测试框架从 Jest 迁移到 Vitest，请帮我更新 CLAUDE.md 中的相关内容。

4. 定期审查

每个 Sprint 结束时花 5 分钟检查 CLAUDE.md：

  • 技术栈版本是否正确？
  • 项目结构是否有变化？
  • 有没有新的约定需要记录？

多人协作中的 CLAUDE.md

在团队项目中，CLAUDE.md 是共享的。这意味着：

统一团队认知

## 团队约定

### Code Review 标准
- 每个 PR 至少需要 1 个 Approve
- 不允许直接 push 到 main 分支
- CI 必须全部通过

### 分支策略
- main：生产分支
- develop：开发分支
- feature/*：功能分支
- hotfix/*：紧急修复

个人偏好放在用户级

团队共享的 CLAUDE.md 不应该包含个人偏好。个人偏好放在 ~/.claude/CLAUDE.md：

# 我的偏好
- 我习惯用 Vim 键位
- 代码注释用中文
- 喜欢函数式编程风格

常见误区

误区 1：“写得越详细越好”

CLAUDE.md 不是文档，是”记忆”。记忆应该是精炼的、关键的信息。一份 50 行的 CLAUDE.md 比 500 行的更有效。

误区 2：“写一次就不管了”

项目在演进，CLAUDE.md 也需要跟着演进。过时的信息比没有信息更糟糕——它会误导 Claude Code。

误区 3：“只写技术信息”

业务上下文同样重要。告诉 Claude Code “这是一个面向初学者的教育平台”，它生成的代码会更注重可读性和注释。

误区 4：“把所有文档都放进去”

CLAUDE.md 应该是索引，不是百科全书。指向详细文档的路径比复制内容更好：

## 参考文档
- API 设计规范：`docs/api-design.md`
- 数据库 Schema：`docs/database.md`
- 部署流程：`docs/deployment.md`

CLAUDE.md 是你和 AI 之间的契约。写好它，Claude Code 就不再是一个”什么都不知道的新人”，而是一个”读过项目文档的老手”。花 10 分钟写好 CLAUDE.md，能为你节省数小时的重复解释。

评论

加载中...

相关文章

🤖Claude Code

Claude Code Agent 完全指南

深入掌握 Claude Code 的 Agent 模式，从基础操作到子 Agent 调用的全面教程

🤖Claude Code

Claude Code SDK 入门：Agent SDK 详解

从安装到调用，系统学习 Claude Code Agent SDK 的核心能力

🤖Claude Code

Agent Teams 自定义角色配置：让每个队友都成为专家

深入讲解如何通过 .claude/agents/ 自定义 Agent 定义文件，为 Agent Teams 中的每个角色配置专属工具、模型、权限和系统提示，解决团队协作中的常见问题

分享：

评论

加载中...