CLAUDE.md 项目规范

CLAUDE.md 是放在项目根目录的一个 Markdown 文件，Claude Code 每次启动会自动把它读进上下文。它是把「模型不懂我的项目」变成「模型比新同事还熟」的最低成本手段。

生成

cd ~/your-project
claude

进入交互模式后执行：

/init

Claude 会扫描项目结构、依赖、脚本，生成一份初稿。不要直接用初稿——它只知道代码里写了什么，不知道你的团队约定。手动补上下面这些。

该写什么

一份好的 CLAUDE.md 回答四个问题：

1. 这是什么项目

## 概述

基于 Go 的订单结算服务，对接微信支付与支付宝。
上游是订单中心（gRPC），下游写入 MySQL + 发 Kafka 事件。

2. 怎么跑起来 / 怎么验证

这是回报率最高的一节。写清楚构建、测试、lint 命令，Claude 改完代码会自己验证，不用你手动跑。

## 常用命令

- 构建：`make build`
- 单测：`go test ./...`
- 单个包：`go test ./service/settle/...`
- Lint：`golangci-lint run`
- 本地起服务：`make dev`（需先 `docker compose up -d mysql redis`）

3. 架构与目录

## 架构

分层：Router → Controller → Service → Model

- `router/`   路由注册
- `service/`  业务逻辑，**所有跨表事务在这一层**
- `model/`    GORM 数据访问，不写业务判断
- `pkg/`      可复用工具，禁止反向依赖 service

4. 规矩（最重要）

模型不会自己猜出你的团队约定，必须明写：

## 规则

- 所有金额用 `decimal.Decimal`，禁止 float64
- 数据库必须同时兼容 MySQL 8 与 PostgreSQL 14，不用方言特性
- 新接口一律加 `//nolint:funlen` 之前先拆函数，不要靠注释绕过
- 错误一律 `fmt.Errorf("...: %w", err)` 包装，不要裸返回
- 不要自动 `git commit`，改完让我 review

有效的写法 vs 无效的写法

❌ 无效	✅ 有效
「代码要写得优雅」	「函数超过 60 行必须拆」
「注意性能」	「循环里禁止查数据库，先批量取再内存匹配」
「遵循最佳实践」	「HTTP handler 只做参数校验和调用 service，不写业务」
「小心处理错误」	「err != nil 必须处理或显式 _ =，禁止忽略」

规则要可判定。 一条规则如果没法机械地检查「有没有违反」，模型就执行不了。

分层文件

Claude Code 会按就近原则合并多个 CLAUDE.md：

位置	作用范围	用途
~/.claude/CLAUDE.md	所有项目	个人偏好：「回答用中文」「不要写多余注释」
<项目根>/CLAUDE.md	整个项目	团队约定，提交到 Git
<项目根>/CLAUDE.local.md	整个项目	个人本地设定，加进 .gitignore
<子目录>/CLAUDE.md	该子目录	子模块特有的规则

大型 monorepo 里，给 web/、server/ 各放一份子目录 CLAUDE.md，比在根目录堆一个巨型文件有效得多。

引用其它文件

用 @ 语法把别的文件也带进上下文：

# CLAUDE.md

@docs/api-conventions.md
@docs/database-schema.md

## 补充说明
...

别把整个文档库都 @ 进来

每次会话都会加载这些内容，直接推高每次请求的输入 token。只引用每次都需要的东西。 偶尔才用到的文档，写一行「数据库设计见 docs/db.md，需要时自己读」就够了——Claude 会自己去读。

控制长度

CLAUDE.md 每一轮对话都在上下文里，它的长度直接乘以你的会话轮数变成钱。

长度	评价
< 100 行	理想
100–300 行	可以接受，注意精简
> 500 行	太长了，拆到子目录或改成按需 @ 引用

配合 Prompt Cache：CLAUDE.md 内容稳定不变时会命中缓存，成本降到十分之一——所以更不要频繁改它，每改一次缓存就要重建。

迭代方式

最实用的习惯：当 Claude 犯了一个你不希望它再犯的错，立刻把对应规则写进 CLAUDE.md。

在交互模式里直接说：

把「service 层禁止直接拼 SQL」这条加到 CLAUDE.md

它会自己改文件。一两周下来，这份文件就沉淀成了团队真正的规范。

配套阅读

• Hooks 钩子 — 用代码强制执行规则，比文字约定更硬
• Skills 技能扩展 — 把可复用的流程封装成技能
• 成本优化策略