CLAUDE.md 配置实践：全局约定与项目规则CLAUDE.md 配置实践：全局约定与项目规则

本文用一份实际使用的配置，说明 CLAUDE.md 适合记录哪些信息，以及如何控制文件长度。示例涉及具体项目，复用时需要核对命令和约定。工具参数可参照 Omnigate 的 Claude Code 进阶 文档。

语法和加载顺序见 CLAUDE.md 怎么写。这里重点说明配置内容及其对应的问题。

全局约定

~/.claude/CLAUDE.md 对所有项目生效，适合放通用的协作要求。下面是这份配置中的内容：

## 通用
 
- 用简体中文回复。
- 代码注释保持精简，且用英文。
- 改完 TypeScript 一定要跑类型检查，有错修到没错为止。
- 不确定的时候先问，不要猜着往下写。
 
## 文件写入
 
单个文件超过 200 行时，分多次 Edit 追加，不要一次 Write 写完——
一次写太大容易中途失败，留下半个文件。

全局文件保持简短，可以减少每个项目都要读取的重复说明。

“文件写入”这条来自具体的环境问题：我遇到过大文件一次写入失败，留下截断内容的情况。因此配置中采用分次写入；是否需要同样的限制，应根据实际环境判断。

项目规则入口

这份配置把项目根目录的 CLAUDE.md 用作规则入口：

@AGENTS.md

Codex 和 OpenCode 读取 AGENTS.md，Claude Code 读取 CLAUDE.md。将规则正文放在 AGENTS.md，再通过 CLAUDE.md 导入，可以让几个工具共用同一份规则。

四类项目规则

以 Omnigate 的 Go 后端和 React 前端代码库为例，配置内容可以按用途分成四类。

首先是项目命令，明确包管理器和检查方式：

- 前端包管理用 bun，不是 npm/yarn/pnpm
- 类型检查：`bun run typecheck`
- lint：`bun run lint`
- 改完 TS/TSX 必须跑 typecheck，不得遗留错误

如果没有明确包管理器，模型可能使用 npm，引入与项目 bun.lock 不一致的 package-lock.json。

第二类是项目特有的兼容性和正确性约定。这些要求不一定能从代码表面看出来：

- 所有 JSON 序列化必须走 common/json.go 的包装函数，
  禁止在业务代码里直接 import encoding/json
- 数据库代码必须同时兼容 SQLite / MySQL 5.7.8+ / PostgreSQL 9.6+
- 行锁统一用 lockForUpdate(tx)；GORM v2 会静默忽略旧版写法，
  写错了不报错但锁根本没加上

行锁这条针对的是代码没有报错、锁却未生效的情况。把相关约定写清楚，可以提醒实现和审查时核对具体调用。

第三类是修改范围和处理方式的限制：

- 不要修改已提交的 migration 文件，加新的
- 不要动任何 *.gen.ts（自动生成）
- 计费相关的数值转换只用 common/quota_math.go 里的辅助函数，
  禁止裸 int() 强转

第四类是实际问题留下的处理经验。这部分可以逐步补充；同一类错误再次出现时，检查是否缺少明确的约定。

例如，这份配置中的“布尔字段不要用 gorm default:true 标签”，来自一个 MySQL 和 PostgreSQL 布尔默认值处理不一致的问题。当时每次重启都会触发多余的 ALTER TABLE，因此将这一情况记入项目规则。

控制重复说明

可以逐项检查文件中是否存在以下内容：

• 模型能够直接查看的目录结构说明，只保留与执行有关的部分。
• “请写高质量代码”这类宽泛要求，改成具体检查或约定。
• 完整 API 文档，放入单独文件，在需要时读取或用 @ 导入。
• 通用语言基础，通常不必在项目规则中重复说明。

长度控制

记录这份配置时，项目 AGENTS.md 已有两百多行，可以考虑按用途拆分。行数是检查可维护性的提示，具体拆法取决于规则的适用范围。

稳定的强制约定留在主文件，领域知识挪到 .claude/rules/ 下按路径加载。比如渠道适配器的规则只在改 relay/channel/** 时才需要：

---
paths:
  - "relay/channel/**"
---
 
新增渠道时确认上游是否支持 StreamOptions，
支持的话要把渠道加进 streamSupportedChannels。

这样可以在处理相关文件时加载对应规则，减少无关任务需要读取的说明。

建立并维护配置

可以从现有项目开始，逐步整理：

1. 用 /init 生成初稿，检查自动生成的目录说明，删去对执行没有帮助的部分。
2. 补充项目命令和必须遵守的约定。
3. 同类错误再次出现时，补充或修正相关规则。

维护时保留能对应到具体需求、检查或已发生问题的内容，方便后续理解每条规则的用途。

本文原载于 Omnigate。