本篇我们来简单梳理下 Claude Code 中 rules 的场景用法。

使用者痛点

• 同一功能不同同学提交的代码风格、日志、错误处理等不统一，导致 Code Review 工作量大增。
• AI 生成的代码只能靠人工逐个审查。容易遗漏关键问题，导致线上故障。其实，
• 项目组每天需要审阅十几个 PR，每个 PR 改动 dozens of files。人工检查 console.log、SELECT *、错误处理等细节非常耗时。
• 新人入职时文档繁杂。不清楚哪些是主要规范，导致上手慢、写出不符合团队要求的代码。
• AI 代码质量参差不齐，缺少统一约束后产量提高但维护成本增加。
• 规则更新后难以全员同步，旧上下文仍然使用过时规则。

至于场景概述。从团队协作角度看 Claude Code 的 Rules 用法

团队背景与现状

我目前是公司某项目组的小组长，负责四人后端团队的代码评审。公司已推行 AI 辅助开发，要求统一使用 Claude Code 编写代码。

实际碰到的问题示例

同一个「查询使用者」函数，两位开发者提交的代码截然不同：

function getUserById {
const user = await db.query
console.log
return user
}

async function get_user_by_id {
try {
const user = await db.findOne
logger.info
return user
} catch {
logger.error
throw new ServiceError
}
}

每次 Review 都要逐条指出并让作者修改；人工审查大量 PR 时常漏掉关键问题，甚至导致线上异常挂掉。

CLAUDE.md 的局限性：写得简洁还是写得详细？

写得太简单——AI 不知道怎么实现

示例约束这方面，

• 不要用 console.log。统一使用 logger
• 改接口要补测试

Ai 能看到约束，却不知道：

从结果来看，每个人对规则的理解不同，代码仍然不统一。

写得太详细——超出上下文限制

If CLAUDE.md exceeds recommended line count。it会：

• 占用大量，留给实际对话和代码的空间变少；老实说，
• Ai 注意力分散。后面的规则更容易被忽略，
• C​laude Code 启动变慢。

The official guidance suggests keeping CLAUDE.md concise—focus on project facts rar than exhaustive style rules.

C​LAUDE.md 更适合作为“项目事实”文件。包含：

The detailed coding standards belong in a separate .claude/rules/ directory.

C​LAUDE.md + rules/：建立完整团队规范程序的思路

• C​LAUDE.md： 提供项目基本信息，让 AI 知道“我们在做什么”。C​LAUDE.md 示例：

# 项目基本信息
## 技术栈
- Java / Spring Boot
- PostgreSQL / Redis
## 常用命令
- 启动：`mvn spring-boot:run`
- 测试：`mvn test`
## 目录结构
- src/main/java/com/xxx/controller // 接口层
- src/main/java/com/xxx/service // 业务层
## 基本约束
- 禁止 SELECT *，必须显式列出字段。话说回来，- 禁止提交明文 API_KEY。至于*Note，Keep within ~200 行.*
*C​LAUDE.md + rules/ 的好处：*


Ai 同时拥有项目上下文和团队编码约束；

`rules/` 可以细化到每个子目录或业务域，实现方法级别加载；

`git` 提交即同步，全员 pull 后立即生效；




`rules/` 的价值：职责分离 + 可执行细则 

`rules/` 的目录结构示例 


my-project/
├─ CLAUDE.md # 项目事实
└─ .claude/
└─ rules/
├─ coding-style.md # 全局代码风格
├─ api-design.md # 接口设计规范
├─ database.md # 数据库操作规范
└─ controller.md # Controller 专属

 


`rules/` 带来的三大优势 


”，`rules/` 只管“怎么写”。

.多人协作降低冲突：

.规则可细化到可执行层面：




.新人上手更快 

L1 onboarding 文档加入一句提醒：“拉完仓库后请先查看 .claude/rules/`”。随后在 Claude Code 对话里尝试生成代码，即可验证规则是否生效。

.规范更新全员同步 

# 更新流程
1️⃣ 在 `rules/` 中修改或新增规则并提交到 Git。
2️⃣ 团队在例会或群里提醒 “请 pull 最新代码并重启 Claude Code”。这样既利用 Git 做版本化，又避免旧会话继续使用旧规则。



`rules/` 的加载方式：全局、方法、个人级别 

全局规则 

- 函数命名使用 camelCase
- 错误处理必须使用 try‑catch
- 日志统一使用 logger。不要出现 console.log

 


Ai 启动时自动加载，对所有文件生效，非常适合通用的编码风格和安全底线。

方法范围规则 

You can limit a rule to specific directories or file types via a YAML header:




至于paths。- "src/api/*/.ts"

- "src/api/*/.tsx"


 

This prevents irrelevant规则占用上下文，也让 AI 在处理前端文件时只关注前端相关约束，在后端文件时只加载后端规则。

a) 方法匹配示例 


---paths:


- "/controller//*.java"


 

b) 多项目共享规则 




~/company-standards/
├── java-style.md
├── api-design.md
└── security.md 

cd my-project/.claude/rules/
ln -s ~/company-standards/java-style.md java-style.md
ln -s ~/company-standards/api-design.md api-design.md

 

*Windows 环境建议改用 Git submodule，以免权限问题。不过，

User‑level Rules 

User‑level rules reside in $HOME/.claude/rules/...。affecting所有项目。说到例如，


~/.claude/rules/
├── preferences.md # 个人日志时间戳、堆栈记录等偏好
└── workflows.md # 常用工作流脚本

 


Ai 会先加载项目级 `rules/` 再加载使用者级。所以冲突时项目级优先，怎么说呢，

`rules/` 与 Hook 的协同工作模式 


`rules/` → 引导 AI 在生成阶段遵循约定。按理说，

`hook` → 在提交前强制拦截绝对不能出现的问题。"


If only rely on hook。AI must repeatedly guess missing parts . By putting clear guidance in `rules/`,most code is generated correctly on first try;hook n acts as兜底，只检查关键违规项，提高整体效率。

至于持续演进，从制定到清理再到评估 

#1 项目启动阶段的硬性约定 

E.g.。响应统一 JSON 格式、函数命名 camelCase、日志采用 slf4j 等，这类在技术评审时就确定，并直接写入对应 `rules/*.md`。

#2 实践中沉淀的细化规则 

A/B 两次重复出现的问题会被抽象成新规则，例如 “所有入口参数必须校验” → 写进 `api-design.md` 并配上正反示例。

#3 定期清理与冲突解决 


"过时代码包装" 已被网关接管 → 删除对应 rule，否则会产生双层包装。

"函数命名 camelCase" 与 "数据库字段 snake_case" 冲突 → 使用 `paths:` 限定作用范围或在注释中明确适用层级。


Solve Conflict Process:



#4 衡量 Rule 生效性的方法 


Sprint 中统计 Review 提出的相同类型问题数量，如果下降说明 rule 有效。<\/ li>

CI 静态检查违规次数趋势图
<\/ li>

随机抽查 AI 提交的 PR，看是否符合 rules/
<\/ ul>







A Complete Example – 后端 Java 项目配置实例 
\
C​LAUDE .md :
\
\ n\
## 技术栈 \ n\
- Java \ n\
- Spring Boot \ n\
## 常用命令 \ n\
- 开启服务: `mvn spring‑boot:run`\ n\
- 测试: `mvn test`\ n\
## 目录结构 \ n\
src/main/java/com/... /controller // 接口层 \ n\
src/main/java/com/... /service // 业务层 \ n\
src/main/java/com/... /mapper // 数据层 \ n\
## 基本约束 \ n\
- 禁止 SELECT *，必须显式列字段 \ n\
- 禁止提交本地配置\ n\
\

`rules/coding-style .md :
\
\ n\
## 命名 \ n\
- 类名 PascalCase \ n\
- 方法 &变量 camelCase \ n\
- 常量 UPPER_SNAKE_CASE \ n\
## 日志 \ n\
- 使用 slf4j `,`log.error`)，禁止 System.out.println \ n\
## 错误处理 \ n\
- 必须使用 try‑catch 包裹对外方法 \ n\
- 捕获异常后记录上下文信息并抛出自定义 ServiceException \
\

`rules/api-design .md :
\
\

接口命名



RESTful 风格。用复数资源方法，如 /users,/orders

请求



必须校验入参 



分页参数为 page & pageSize 

响应



标准结构 { code,data,message }





`rules/database .md :
\
\ 



明确列出字段，禁用 SELECT *



批量操作使用 batch



使用 @Transactional 注解





`rules/controller .md （方法限定，仅在 controller 包生效) :
\
\ yaml
---paths:


不编写业务逻辑，只做参数校验 & 调用 service

入参使用 @Valid




The above configuration yields:


\

新人拉仓库即能看到完整规范，无需额外文档搜索。<\/ li>\

Code Review 大幅减少低级别问题，只聚焦业务逻辑与设计。<\/ li>\

AI 按照方法限定加载相应 rule，上下文更干净、更高效。<\/ li>\
<\/ ul>







个人开发 :
仅需要一个简洁的 CLAUDE . md c ode>。加几条关键底线，通过 Hook 强制敏感信息即可。 团队开发 :
采用 CLAUDE . md + . claude / rules / + Hook 三位一体：

\

CLAUde . md – 项目事实&红线
— 技术栈、启动指令、目录结构…<\/ li>\

Rules – 可模块化管理编码约定
— 全局+方法+个人偏好<\/ li>\

Hook – 最终兜底拦截不可容忍违规<\/ li>\
<\/ ul>










Pitfalls & Tips 


.
如果还有其他疑问，请随时提问！



 别把 “项目事实” 写进 rules/*。按理说，它们应当放在 CLAUD E . md 中！

 Rules 越多越易分散注意力，仅保留 AI 难以自行推断且经常出错的部分 

 定期 Review 清理失效或冲突规 则 

 区分引导性 Rules 与强制性底线 – 前者放 Rules。后者交给 Hook 实现