前言

用 AI 改代码，常常得先重复交代一遍：项目是做什么的、怎么运行、代码放在哪里、有哪些约定。说过几次之后，很容易漏掉细节；不说，AI 又可能按自己的习惯补全，改着改着就和项目原有风格不一致。

CLAUDE.md 可以把这类 稳定、反复适用的项目背景与规则 写下来，供 Claude Code 在项目里工作时参考。它不能代替每次具体的任务说明，也不能保证 AI 永远不会出错，但能减少重复说明和不必要的猜测。

这篇用一个 HTML5 小游戏合集做例子，走一遍从生成文件、整理内容，到用它完成修改并及时维护的过程。

一、CLAUDE.md 适合写什么？

可以把它理解成项目的协作说明：告诉 AI 项目是什么、怎样运行、修改时要遵循哪些长期约定。

内容	对话里的任务提示	`CLAUDE.md`
生效范围	当前任务	Claude Code 在对应范围内工作的会话
适合写什么	这次要实现或修改什么	项目背景、常用命令、长期规范
例子	把贪食蛇里的苹果换成香蕉	游戏使用 Canvas，保持单文件结构

一个简单的判断方法是：下周或下个月再做类似任务时，这条信息还重要吗？ 如果重要，可以考虑写进 CLAUDE.md；如果只对当前任务有效，就放在当次提示词里。

例如，技术栈、启动命令、目录用途、代码风格通常比较稳定；某个按钮临时换颜色、一次性活动页面的文案，则不适合变成长期规则。

二、从 `/init` 开始，再人工核对

在 Claude Code 中进入项目后，可以运行：

claude /init

它会检查当前项目并帮助建立或完善 CLAUDE.md。生成内容可能包括项目概况、常用命令、文件结构和开发约定。具体写入哪些信息，会取决于项目内容和 Claude Code 版本。

假设仓库里有 snake.html 和 tetris.html 两个独立小游戏，初稿可能会归纳出：

项目是浏览器运行的 HTML5 小游戏合集；
游戏以独立 HTML 文件组织，使用 Canvas 绘制；
可以直接用浏览器打开，也可以通过本地 HTTP 服务器运行；
使用原生 JavaScript，并通过 addEventListener 绑定事件。

自动生成的价值在于先从仓库里提取线索，减少凭记忆编写造成的遗漏。但它仍然只是待核对的初稿：命令是否正确、文件说明是否过时、约定是否真的是团队要求，都需要你确认。

三、把文件写成可执行的说明

一份短而有用的文件，通常只需要覆盖下面几类内容：

项目概况：项目解决什么问题，主要技术栈是什么。
运行与检查命令：怎样启动、构建或运行必要检查。
关键目录说明：常改的目录和文件分别负责什么。
开发约定：新增或修改代码时必须遵守的模式。
交付要求：任务完成后需要说明哪些结果。

例如，游戏合集项目的规则可以写成这样：

# 项目说明

这是一个基于浏览器的 HTML5 小游戏合集。每个游戏是独立的 HTML 文件，内含 CSS 和 JavaScript。

## 运行方式

直接在浏览器中打开游戏文件，或在项目目录运行：

```bash
python3 -m http.server 8080
```

然后访问 `http://localhost:8080/snake.html`。

## 开发约定

- 新增游戏时沿用独立 HTML 文件的组织方式；若需求需要共享模块，先说明拆分方案。
- 游戏画面使用 Canvas；状态更新和绘制逻辑分开组织。
- 使用 `const` 和 `let`，避免使用 `var`。
- 使用 `addEventListener` 绑定事件，不写内联事件处理器。
- 新增或修改游戏后，说明改动文件和实际检查过的功能。

规则尽量写成可以检查的动作。比如“使用 const 和 let”比“代码要优雅”清楚；“运行 python3 -m http.server 8080”比“按项目方式启动”更容易执行。

控制篇幅

CLAUDE.md 不是项目历史档案，也不适合复制大量源码。它及其引用的文件会占用会话上下文；内容太长、规则重复或彼此冲突，反而不容易找到重点。

可以优先留下三类信息：经常需要重复解释的、违反后会造成明显问题的、能通过具体行为验证的。临时任务、待办清单和已经失效的说明，及时移除或放回合适的文档。

四、让约定参与一次真实修改

文件写好之后，最好用一个范围小、结果容易检查的任务试一遍。比如：

请修改 snake.html：把食物从苹果改成香蕉，并将整体配色调整为粉色系。
请先检查现有结构，遵守项目中的单文件和 Canvas 约定。完成后检查界面文案、变量命名和食物绘制是否都已更新，并说明实际检查结果。

按项目说明，AI 应该先了解 snake.html 的结构，再完成相关修改，并检查食物图形、文字、变量命名和配色是否一致。你也可以对照文件里的规则，确认它有没有遵循单文件组织、事件绑定等约定。

这里要区分两件事：CLAUDE.md 提供项目长期背景；这段提示词说明本次要做什么、怎样检查。把两者分开，既能复用项目规则，也不会让长期文件被一次性需求塞满。

如果 AI 没有遵守规则，不要马上把文件越写越长。先确认规则是否清楚、是否适用于当前任务，再检查本次会话是否加载了相应文件。也可以用 Claude Code 提供的上下文或记忆相关命令查看当前会话的加载情况；具体命令和显示内容以当前版本为准。

五、修改项目后，同步更新说明

CLAUDE.md 需要随着项目变化维护。假如蛇的食物和主题已经改了，文件里仍然写着“绿色主题、红色小蛇吃苹果”，之后 AI 可能会继续把旧描述当作现状。

可以在任务结束时检查这几件事：

新增或删除了重要文件、目录吗？
启动、构建或检查命令变了吗？
原有约定是否已经不适用？
这次新增的规则是否长期有效，值得写进来？

若答案是肯定的，再让 AI 更新对应部分，并检查更新后的描述是否与仓库事实一致。小的功能变化不一定要改项目说明；目录、技术栈、运行方式或长期规范变化，通常值得同步。

六、文件放在哪里？

Claude Code 支持在不同范围使用说明和记忆文件。常见位置包括项目根目录的 CLAUDE.md、项目 .claude/ 目录里的说明文件，以及用户目录下的个人说明文件。团队共享的规则通常放在版本库内；只属于个人的偏好，应放在个人范围，避免意外提交。

不同位置的加载范围、优先级和文件名可能随配置或版本有所差异。实际使用时，优先参考 Claude Code 当前版本的文档，并检查会话里实际加载了哪些文件。不要只凭文件存在，就假设它一定按预期生效。

如果说明太长，可以把专门的规范拆到单独文档，并在 CLAUDE.md 中用文件引用引入。Claude Code 支持通过 @ 引用文件；使用前确认引用路径正确，并留意被引用内容也会增加上下文长度。

七、常见误区

误区	更好的做法
`/init` 生成后就不再检查	把它当初稿，逐条核实命令、目录和规范
把所有任务和想法都写进去	只保留长期适用、反复需要的信息
只写技术栈，不写运行命令	补上实际可执行的启动、构建和检查命令
使用“高质量”“优雅”等模糊要求	改成能观察或检查的具体行为
用户规则和项目规则互相冲突	划清适用范围，并删除过时或重复的规则
默认 AI 一定会遵守所有内容	结合当前上下文、工具权限和实际结果进行检查

八、总结

CLAUDE.md 的作用，是把项目里反复需要交代的背景和约定整理成一份可复用的说明。写的时候抓住几个要点：

用 /init 帮忙起草，再核对项目事实；
优先写具体、稳定、能检查的规则；
把长期约定和本次任务分开；
项目发生重要变化时，及时维护说明；
通过实际任务和检查结果确认它是否起作用。

它不是一份越长越好的“万能提示词”，也不能替你判断需求是否正确。把项目事实写清楚，再由人检查关键结果，才能让 AI 真正少猜一些、做得更贴近项目。

CLAUDE.md 怎么写才有用？让 AI 记住你的项目规则 🧠