CLAUDE.md 和 rules 如何配合使用：Claude Code 项目指令设计指南

在 Claude Code 里，CLAUDE.md 和 .claude/rules/ 不是相互替代的两套东西，而是一套“总则 + 分流”的指令组织方式。最实用的理解是：把所有人都要长期遵守、几乎每次会话都相关的内容放进 CLAUDE.md；把只对某些目录、文件类型或专项主题生效的规则拆到 .claude/rules/ 中。

如果只记一句话，可以记成这句：CLAUDE.md 负责全局上下文，rules 负责按主题和路径精细化加载。

先理解官方定义

根据 Claude Code 官方文档，Claude Code 每次会话都会从一个新的上下文窗口开始。为了让 Claude 跨会话保留项目知识，官方提供了两种机制：一是由用户编写的 CLAUDE.md，二是由 Claude 自己积累的自动记忆。本文讨论的重点是前者，以及它在大型项目里延伸出来的 .claude/rules/ 组织方式。

官方对 CLAUDE.md 的定位很明确：它是一个持久指令文件，适合承载项目架构、编码标准、构建和测试命令、命名约定以及常见工作流。官方在最佳实践中还特别提到，可以把 Bash commands、code style 和 workflow rules 放进 CLAUDE.md。这也说明，很多团队口中的“rules”，本质上首先就是写给 Claude 的项目指令。

什么内容应该写进 CLAUDE.md

CLAUDE.md 适合放“广泛适用”的规则，也就是那些无论 Claude 正在改哪个模块、读哪个文件，几乎都应该知道的内容。

常见适合写进 CLAUDE.md 的内容包括：

• 项目的构建、测试和启动命令
• 团队统一的代码风格约定
• 关键目录的职责说明
• 常见工作流要求，例如改动后先跑哪类测试
• 架构层面的硬性约定，例如 API 统一放在哪个目录

例如，下面这些内容就很适合作为 CLAUDE.md 的主干：

# Build And Test
- 安装依赖使用 `pnpm install`
- 提交前运行 `pnpm test`
- 前端改动后运行 `pnpm lint`

# Code Style
- TypeScript 使用 ES modules
- 新组件放在 `src/components/`
- 接口类型定义统一放在 `src/types/`

# Workflow
- 修改 API 前先查看 `src/api/` 下现有模式
- 涉及数据库 schema 的改动必须补 migration

官方同时强调，CLAUDE.md 最好保持简洁、具体、可验证，并尽量控制在 200 行以内。因为它会在每次会话开始时加载，写得太长不仅消耗上下文，还会降低 Claude 遵守指令的一致性。

什么内容应该拆到 .claude/rules/

当项目变大后，你很快会遇到一个问题：并不是所有规则都应该一直常驻在上下文里。比如前端组件规范对后端任务不重要，数据库 migration 规则对文档改写任务也未必相关。这时就应该把专项规则拆进 .claude/rules/。

官方给出的定位是：.claude/rules/ 用于把指令组织成多个 markdown 文件，让规则模块化、便于团队维护，而且还能通过路径范围限制，只在 Claude 处理匹配文件时才加载。

这意味着 .claude/rules/ 特别适合承载下面几类内容：

• 仅针对某一技术栈的规则，例如 React、TypeScript、Python
• 仅针对某一目录的规则，例如 src/api/、apps/admin/
• 主题明确的专项规范，例如测试、安全、数据库、发布流程
• 不适合放在主 CLAUDE.md 中长期常驻的大段说明

一个典型目录结构可以是这样：

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md
    ├── testing.md
    ├── security.md
    ├── frontend/
    │   └── react-components.md
    └── backend/
        └── api-design.md

rules 最大的价值：可以按路径生效

.claude/rules/ 和 CLAUDE.md 的最大区别，不只是“文件拆分”，而是“加载条件”。

如果某个 rule 文件没有写 paths，它会像 .claude/CLAUDE.md 一样，在会话开始时就加载。这适合那些虽然不想塞进主文件，但仍然希望始终生效的主题规则，比如全局测试约定。

如果某个 rule 文件带有 paths frontmatter，它就会变成条件规则。只有当 Claude 读取了匹配这些路径的文件时，这条规则才会进入上下文。官方示例如下：

---
paths:
  - "src/api/**/*.ts"
---

# API 开发规则

- 所有 API 端点必须包括输入验证
- 使用标准错误响应格式
- 包括 OpenAPI 文档注释

这种写法特别适合大型仓库。它让 Claude 在处理 src/api/**/*.ts 时才关注 API 规则，而不是在修 CSS 或写文档时也背着这一整套要求。结果就是上下文更干净，规则噪音更低，也更不容易相互打架。

二者应该怎么分工

一个实用的落地原则是：先写一份短小、稳定的 CLAUDE.md，再把复杂内容逐步拆到 .claude/rules/。

可以按下面这个思路分工：

• CLAUDE.md 写全局总则
• .claude/rules/testing.md 写测试约定
• .claude/rules/security.md 写安全要求
• .claude/rules/frontend/*.md 写前端专项规范
• .claude/rules/backend/*.md 写后端专项规范
• 带 paths 的 rule 处理目录级和文件类型级约束

换句话说，CLAUDE.md 更像项目宪法，.claude/rules/ 更像分部门执行细则。

推荐的写法：总则写原则，rules 写触发条件和细节

如果你把所有细节都堆进 CLAUDE.md，很容易变成一份几百行的大说明书，Claude 每次都得完整加载，效果反而会变差。更好的做法是：

在 CLAUDE.md 中写清楚：

• 项目是什么
• 最重要的通用约束是什么
• 团队默认工作流是什么
• 哪些专项规则已经拆到 .claude/rules/

在 rules 中写清楚：

• 这份规则针对什么主题
• 它适用于哪些路径
• 具体要遵守哪些检查项
• 是否有示例、例外和配套命令

比如主文件可以很短：

# Project Overview
- 这是一个 pnpm monorepo
- 前端在 `apps/web`
- 后端在 `services/api`

# Team Workflow
- 所有改动完成后先运行最小相关测试
- 不要顺手修无关问题

# Rule Modules
- 前端规则见 `.claude/rules/frontend/`
- API 规则见 `.claude/rules/backend/api-design.md`
- 测试规则见 `.claude/rules/testing.md`

而专项规则则独立维护。这样一来，主文件稳定，细则也便于按模块演进。

还要注意一件事：它们都不是“强制执行器”

这是很多团队最容易误解的地方。官方明确说明，CLAUDE.md 和 rules 在本质上都属于上下文指导，而不是客户端强制层。它们会影响 Claude 的行为，但不是硬约束。

如果你的诉求是下面这类能力：

• 禁止访问某些路径
• 禁止执行某些命令
• 强制开启 sandbox
• 固定登录方式、组织限制、环境变量

这些应该交给 settings 或 managed settings，而不是寄希望于在 CLAUDE.md 里写一句“不要这样做”。前者是系统层强制，后者是行为层引导，二者边界要分清。

如何从现有 AGENTS.md 迁移

如果你的仓库已经有 AGENTS.md，官方建议不要重复维护两份内容，而是在 CLAUDE.md 中直接导入它：

@AGENTS.md

## Claude Code
- 对 `src/billing/` 下的更改使用 plan mode

这种方式的好处是，其他代理继续读 AGENTS.md，Claude Code 则通过 CLAUDE.md 间接读取同一套共享规则。你只需要在下面追加少量 Claude Code 专用说明即可。

一套适合团队的实践模板

如果你正准备落地，我更推荐从下面这套结构开始：

your-project/
├── CLAUDE.md
└── .claude/
    └── rules/
        ├── testing.md
        ├── security.md
        ├── frontend/
        │   └── react.md
        └── backend/
            └── api.md

其中：

• CLAUDE.md 只写所有人都长期适用的总则
• testing.md 和 security.md 写全局专项规范
• frontend/、backend/ 里的规则按技术域拆分
• 对强依赖路径的规则使用 paths，减少无关上下文加载

常见误区

第一个误区是把 CLAUDE.md 写成百科全书。官方已经明确建议把它控制在较短范围内，因为它会在每次会话完整加载。你越想把所有东西都塞进去，实际效果往往越差。

第二个误区是把 .claude/rules/ 当成“另一个 CLAUDE.md 备份目录”。rules 的价值不是单纯拆文件，而是让规则主题化、模块化，并在需要时按路径触发。

第三个误区是把规则当成系统权限。实际上，真正要“硬拦截”的能力应该放到 settings、permissions 和 managed settings，不应混进项目指令。

第四个误区是规则冲突。官方提到，如果多条规则互相矛盾，Claude 可能会任意选择。团队在维护 CLAUDE.md 和 rules 时，应该定期清理过期、重复和冲突内容。

结语

如果你希望 Claude Code 在项目里既“听话”又“不臃肿”，最稳妥的方式不是不断把提示词写长，而是把指令分层。

CLAUDE.md 用来定义长期有效的全局协作规则，.claude/rules/ 用来承载主题化、路径化的专项细则；需要硬性执行的部分，再交给 settings。三者分工清楚后，Claude Code 的表现通常会更稳定，团队维护成本也会更低。