# CLAUDE.md 怎么写？Claude Code 项目配置示例与维护方法

> 用一份简洁的 CLAUDE.md 记录项目命令、代码约定和验收要求。提供 Astro 文章站模板，说明如何检查规则效果，以及指引与权限控制的区别。

- 原文：https://token.help/articles/claude-md-project-guide
- 作者：词元有方编辑部
- 成稿时间：2026-09-29T07:46:10.000Z
- 发布时间：2026-09-29T07:58:52.000Z
- 最后更新：2026-09-29T07:58:52.000Z
- 分类：接入教程
- 核验方式：已核对官方文档
- 核验时间：2026-09-29T00:00:00.000Z
- 适用版本：Claude Code 官方在线文档（2026-09-29 核对）

引用本文请使用上方原文链接；配置与结论以文中版本和核验时间为准。来源内容的许可说明保留在正文中。

使用 Claude Code 时，你可能会反复提醒它：项目用哪个包管理器、修改后跑什么检查、哪些文件不能随便改。

这些长期适用的约定，可以放进项目的 `CLAUDE.md`。Claude Code 会把它作为工作上下文读取，让新会话也能了解项目规则。[官方说明](https://code.claude.com/docs/en/memory)

本文基于官方文档整理，并补充文章站示例；属于中文技术解读，不是原文逐句翻译。模板未做真实任务的效果对比测试。

## 1. 先写清三件事

一份实用的 `CLAUDE.md`，可以先回答三个问题：

- **怎么运行项目？** 写出准确的开发、检查和构建命令。
- **有哪些特殊约定？** 记录项目自己的规则。
- **怎样算完成？** 明确修改后需要验证什么。

官方最佳实践建议保持简洁，减少能从代码直接推断的信息。可以在 Claude Code 中用 `/init` 生成初稿，再人工删改。[官方最佳实践](https://code.claude.com/docs/en/best-practices)

## 2. 示例：给文章站写一份项目说明

在项目根目录创建 `CLAUDE.md`。下面是针对 Astro 文章站编写的示例，命令和路径需要按实际项目调整：

```markdown
# 项目

中文技术文章站，使用 Astro 构建静态页面。
文章源文件位于 src/data/post/。

# 开发命令

- npm run dev：启动开发服务
- npm run check：检查类型、格式和 SEO 字段
- npm run build：构建静态页面，输出至 dist/

# 文章维护

- 已发布文章保留原 slug。
- 修改 SEO 标题时，同时检查摘要与正文是否一致。
- 配置教程标注来源、核对日期和适用版本。
- 未执行真实 API 调用时，不写“实测成功”。

# 完成标准

- 修改后运行 check 和 build。
- 页面布局变化需检查桌面和手机显示。
- 交付时说明验证结果与尚未验证的部分。
```

这里的每条规则都对应具体动作。比如，“注意 SEO”很难执行；“修改标题时检查摘要与正文是否一致”就明确得多。

## 3. 把模糊要求改成可检查的动作

维护规则时，可以用下面的方式改写：

| 模糊要求     | 可执行的写法                       |
| -------- | ---------------------------- |
| 保证内容准确   | 接口参数标注官方来源和核对日期              |
| 不要破坏 SEO | 保留已有 slug，检查 canonical 和站内链接 |
| 做好测试     | 修改后运行项目约定的检查与构建命令            |
| 写高质量文章   | 提供前置条件、操作步骤和结果验证方式           |

这张表是一种编写方法：**把期待的结果，拆成能够检查的行为。**

对自己的项目，可以从最近一次返工开始梳理。例如，文章更新后链接失效，就补上地址维护要求；构建命令写错，就纠正命令。每条规则都要能说明它解决了什么实际问题。

## 4. 写完后，用真实任务检查它

选一个小任务，例如修改一篇文章的摘要，观察 Claude 是否：

1. 找到了正确文件。
2. 保留了原有文章地址。
3. 执行了要求的检查。
4. 如实说明验证结果。

建议记录“任务、预期动作、实际动作、需要调整的规则”，而不是只凭输出语气判断它是否理解了项目。

发现偏差后，再修改相关规则。不要因为一次遗漏，就不断追加重复指令。需要更新的是具体要求：哪个检查被漏掉了，在哪类修改后必须执行。

## 5. 项目说明不能替代权限控制

`CLAUDE.md` 是给模型的指引，不能保证某项操作绝不会发生。需要强制阻止的动作，应通过权限控制或相应的 Hook 实现。[规则与强制控制的区别](https://code.claude.com/docs/en/memory)

例如，“修改文章后提醒我预览”适合作为协作约定；禁止访问敏感目录，则需要在实际执行环境中限制访问。

**一份好的项目说明，应该能减少反复解释，也方便团队自己阅读和维护。**

## 继续阅读

- 尚未完成连接配置，可先看 [Claude Code 配置第三方 API](https://token.help/articles/claude-code-third-party-api)。
- 想把任务流程固定下来，可继续看 [AI 工作流如何复用](https://token.help/articles/reusable-ai-workflow)。

## 参考资料

- Anthropic / Claude Code：[Best practices](https://code.claude.com/docs/en/best-practices)。
- Anthropic / Claude Code：[How Claude remembers your project](https://code.claude.com/docs/en/memory)。

## 核验参考来源

- https://code.claude.com/docs/en/best-practices
- https://code.claude.com/docs/en/memory