为你的项目编写第一份 CLAUDE.md

本节把前两节知识落到一份真实文件：用 /init 生成草稿，按推荐结构补全项目记忆，再通过"可运行、精简、可验证"三条标准打磨出第一份可用的 CLAUDE.md。下面的结构是建议模板，可按项目大小裁剪，不必逐条填满。

一、推荐工作流（五步）

1. 生成草稿：在项目根目录启动会话，运行 /init，让代理先产出初稿。
2. 审阅删冗：通读初稿，删除空泛描述、重复说明和与本项目无关的内容。
3. 补齐关键命令：把安装、启动、测试、构建、检查等真实命令补全，并先在终端跑通。
4. 补约定与禁区：写入技术栈、目录职责、命名风格、必过检查项和不要改动的范围。
5. 小步迭代：先写一版精炼可用的，随项目演进定期更新，不追求一次写满。

二、推荐结构模板（建议，可裁剪）

# 项目名称
一句话说明：这个项目做什么、服务谁。

## 技术栈
- 语言与运行时：<填写>
- 主要框架/库：<填写>
- 版本与兼容性要求：<填写>

## 目录速览
- src/：主要源码，职责是 <填写>
- tests/：测试代码，组织方式为 <填写>
- config/：配置文件，注意 <填写>
- docs/：说明文档位置

## 常用命令（先在终端验证可运行）
- 安装依赖：<真实命令>
- 本地启动：<真实命令>
- 运行测试：<真实命令>
- 构建打包：<真实命令>
- 代码检查：<真实命令>

## 编码与命名约定
- 命名风格：<具体规则>
- 错误处理：<具体要求>
- 注释与文档：<具体要求>

## 测试与提交约定
- 测试覆盖重点：<填写>
- 提交信息风格：<填写>
- 合并前必过检查：<填写>

## 注意事项与禁区
- 不要改动：<明确排除目录/模块>
- 兼容性约束：<填写>
- 易踩坑点：<填写>

## 参考资料
- 关键文档：<稳定链接或本地路径>

三、四条写作原则

原则	含义	反例
具体可执行	写清命令、规则与边界，代理可直接遵循	"代码要规范""多写测试"这类无判据表述
稳定优先	只沉淀长期不变的背景，临时状态留在对话	把当天调试步骤写进长期记忆
精简克制	控制篇幅，细节让代理按需读文件	粘贴整份 README 或源码片段
可验证	命令能跑通、约定与现状一致	写入已失效的构建命令或过时结构

四、常见反例（应避免）

• 全文照搬 README：冗余且易过期，应提炼约定与命令。
• 写入密钥与内部敏感值：违反安全要求，必须删除并改用环境变量。
• 只有口号没有规则：代理无法据此稳定产出一致风格。
• 写完从不更新：项目重构后记忆失真，反而误导代理。

五、如何验证记忆生效

1. 保存文件后新开一个会话（或用 /clear 清掉当前对话），在项目根目录启动。
2. 让代理复述技术栈、常用测试命令和一条明确约定，检查是否与 CLAUDE.md 一致。
3. 下达一个受约定约束的小任务，观察它是否按记忆中的命令与风格执行。
4. 发现遗漏或过时内容，用 /memory 或直接编辑文件修正，形成持续维护习惯。