# 通用 CLAUDE.md 骨架

> 一份适用于任何项目的 CLAUDE.md 起步骨架，涵盖命令、目录、约定、禁区和已知坑，复制后替换占位符即可，建议控制在 200 行以内。

## 适用场景

新项目第一次接入 Claude Code，或者老项目里的 CLAUDE.md 越写越长、越来越没人看。这份骨架只保留「智能体读代码读不出来」的信息：怎么跑、哪里不能碰、哪些坑踩过。

你也可以先在项目里运行 `/init`，让 Claude 扫描代码库生成一份初稿，再用下面的结构去裁剪。自动生成的内容往往偏长，里面的目录清单和依赖列表大多可以删掉。

## 模板

保存为项目根目录的 `CLAUDE.md`（或 `.claude/CLAUDE.md`）：

```markdown
# 【项目名】：一句话说明它是做什么的

<!-- 维护提示：HTML 注释不会进入 Claude 的上下文，可以给人类同事留言 -->

## 常用命令
- 安装依赖：`【命令】`
- 本地开发：`【命令】`
- 全部测试：`【命令】`
- 单个测试：`【命令】`（改动期间优先跑单个，不要每次跑全量）
- Lint / 类型检查：`【命令】`
- 构建：`【命令】`（提交前必须通过）

## 目录结构（只写不一目了然的部分）
- `【路径】`：【用途】
- `【路径】`：【用途】

## 代码约定（只写和默认习惯不同的规则）
- 【可验证的规则，例如：错误一律抛出 AppError，不返回 null】
- 【例如：日期统一用 UTC 存储，只在展示层转换】

## 工作方式
- 动手前先读相关文件，再改；改动保持最小，不顺手重构无关代码。
- 完成后运行【验证命令】，并在汇报里贴出实际输出。
- 需求有关键歧义时先问，不要猜。

## 禁区
- 不要修改：`【生成文件 / 第三方代码目录】`
- 不要提交：`.env`、密钥、本地数据库文件
- 新增依赖前先说明理由

## 已知坑
- 【例如：集成测试需要本地 Redis，先执行 docker compose up -d redis】
- 【例如：某个脚本只能在项目根目录执行】
```

## 怎么用 / 怎么改

1. 把所有【】换成真实内容。写不出来的小节直接删掉，不要留空壳。
2. 每条规则都要能被验证。「保持代码整洁」没有信息量；「函数超过 60 行必须拆分」可以检查。
3. 在会话里运行 `/context`，确认 CLAUDE.md 出现在 Memory files 列表里，说明它确实被加载了。
4. 只对局部目录有效的规则，不要塞进根目录文件。可以放进子目录自己的 CLAUDE.md，它们会在 Claude 读写该目录文件时按需加载；也可以放进 `.claude/rules/`，用 `paths` 限定适用的文件。
5. 个人偏好（比如你本机的沙箱地址）写进 `CLAUDE.local.md`，并加入 `.gitignore`，不要污染团队文件。
6. 想引用已有文档，可以在文件里写 `@docs/架构说明.md`，被引用的文件会一并加载。引用最多可以嵌套四层。

## 常见问题或注意事项

- **文件越长，遵守率越低。** 官方建议单个文件控制在 200 行以内。导入文件并不会省上下文，因为被导入的内容会和主文件一起加载。
- **CLAUDE.md 是上下文，不是强制规则。** 它以用户消息的形式交给模型，模型会尽量遵守但没有保证。必须每次都发生的事（比如改完文件自动格式化）应该做成 hook，必须禁止的事应该写成权限规则。
- **规则互相矛盾时，模型可能随机选一条。** 定期检查根目录、子目录和 `.claude/rules/` 里有没有冲突。运行 `/doctor prompt-audit` 可以让 Claude 帮你找出过时或冲突的指令，它只出报告，不会擅自改文件。
- **Claude 同一个错误犯了第二次，就是该补一条规则的信号。** 反过来，某条规则 Claude 本来就做得对，删掉它。
- 把 Claude 的提交、PR 规则写进 CLAUDE.md 时，如果和内置行为冲突，可以用 `includeGitInstructions` 关掉内置说明，并用 `attribution` 自定义署名。具体字段以官方设置文档为准。