<!-- title: Claude Code Rules模块化配置与路径作用域全实战 -->

# Claude Code Rules模块化配置与路径作用域全实战

## 概述

本教程深入讲解Claude Code的规则体系与模块化配置架构。你将学会如何从单一臃肿的CLAUDE.md迁移到`.claude/rules/`目录下的模块化规则文件，掌握路径作用域（path-scoped）规则让指令只在特定目录生效，理解五层配置作用域的优先级交互，并构建一套可扩展、可维护的项目配置体系。适合已使用Claude Code完成基本开发、希望提升AI协作精度的中高级开发者。

## 前置条件

- Claude Code已安装并能正常运行（版本≥2.0.64以支持rules目录）
- 熟悉Markdown语法和基本的JSON配置
- 有一个正在开发中的项目作为练习场地
- 理解基本的文件系统路径匹配模式（glob pattern）

---

## 第一章：理解配置全景——Claude Code如何读取你的指令

### 1.1 系统提示词的构建架构

Claude Code在每次会话启动时，会按特定顺序组装一个完整的系统提示词。理解这个架构是配置优化的基础。

整个系统提示词分为两大区域：

```
┌──────────────────────────────────────────────────────┐
│ 静态区域（全局缓存——全球所有Claude Code用户共享）    │
│                                                      │
│  1. Claude身份与自我介绍                              │
│  2. 系统行为规则                                     │
│  3. 任务执行指令                                     │
│  4. 工具使用说明                                     │
│  5. 输出风格与效率                                   │
│                                                      │
├────────══──────────────────────────────────────────────┤
│ === 动态边界 ===                                     │
├──────────────────────────────────────────────────────┤
│ 动态区域（会话级缓存——用户专属）                     │
│                                                      │
│  8. 会话引导                                         │
│  9. 指令：CLAUDE.md文件（按层级顺序加载）             │
│ 10. 环境信息（日期、OS、模型、会话ID）               │
│ 11. 语言偏好                                         │
│ 12. MCP服务器指令                                    │
│ 13. 输出样式                                         │
│                                                      │
│ + MEMORY.md（始终加载，前200行）                      │
│ + 最多5个记忆文件（由侧查询LLM选择）                  │
└──────────────────────────────────────────────────────┘
```

**关键认知**：静态区域对所有用户完全相同，Anthropic通过服务器端缓存复用，节省延迟和成本。动态区域因用户而异——你的CLAUDE.md、规则、设置都在这里注入。

### 1.2 CLAUDE.md的加载顺序

Claude Code按以下固定顺序加载所有CLAUDE.md文件：

| 顺序 | 文件位置 | 作用域 | 是否共享 |
|------|----------|--------|----------|
| 1 | 托管策略路径 | 组织全局 | 所有用户 |
| 2 | `~/.claude/CLAUDE.md` | 个人全局 | 仅自己 |
| 3 | 父目录中的CLAUDE.md | 继承链 | 视git而定 |
| 4 | `./CLAUDE.md` 或 `./.claude/CLAUDE.md` | 项目级 | 通过git共享 |
| 5 | `./CLAUDE.local.md` | 个人项目级 | 仅自己（gitignored） |

在monorepo中，子目录的CLAUDE.md按需加载——只有当Claude读取该目录下的文件时才会触发。

### 1.3 规则文件的两种加载模式

这是整个规则体系最核心的区分：

```mermaid
flowchart TB
    subgraph 规则文件加载机制
        A[.claude/rules/目录下的.md文件] --> B{是否有paths前置元数据?}
        B -->|无paths| C[始终加载到动态区域]
        B -->|有paths| D[按需加载：仅当访问匹配文件时注入]
        C --> E[与CLAUDE.md同等高优先级]
        D --> F[与CLAUDE.md同等高优先级<br>但仅作用于匹配上下文]
    end

    style C fill:#ff9800,color:#fff
    style D fill:#4caf50,color:#fff
```

- **无paths的规则**：每个会话始终加载，和CLAUDE.md一样占用上下文空间
- **有paths的规则**：只在Claude操作匹配文件时才加载，其他时候不占用token

---

## 第二章：从单文件到模块化——Rules目录实战

### 2.1 传统CLAUDE.md的困境

许多团队开始时把所有指令塞进一个CLAUDE.md：

```markdown
# 项目规范

## 技术栈
- 后端: FastAPI + Python 3.12
- 前端: Next.js 15
- 数据库: PostgreSQL

## API规范
- 所有端点必须用Zod验证输入
- 返回统一错误格式: { error: string, code: number }
- 所有请求记录correlation ID

## React规范
- 只用函数组件
- 逻辑抽取到自定义hooks
- 使用React.memo优化渲染

## 测试规范
- Mock外部服务
- 测试名格式: "should [action] when [condition]"
- 一个测试一个断言

## 数据库迁移规范
- 必须包含回滚指令
- 先添加可空列，填充数据后再加约束
- 列删除与代码删除分不同迁移

## 安全规范
- 禁止记录敏感数据
- 所有输入在函数边界验证
- 使用参数化查询
```

**问题**：当这个文件膨胀到400+行时，React规范在处理数据库迁移时也在争抢Claude的注意力。高优先级的内容太多等于没有优先级。

### 2.2 创建模块化规则体系

第一步：精简CLAUDE.md为核心运营规则

```markdown
# 项目核心

## 技术栈
- 后端: FastAPI + Python 3.12
- 前端: Next.js 15
- 数据库: PostgreSQL

## 构建命令
- 测试: `pytest`
- 代码检查: `ruff check .`
- 开发服务器: `uvicorn app.main:app --reload`

## 工作原则
- 正确性 > 可维护性 > 性能
- 简单任务直接执行，复杂任务先进入plan模式
```

第二步：创建规则目录并拆分

```bash
# 创建规则目录
mkdir -p .claude/rules
mkdir -p .claude/rules/frontend
```

### 2.3 带路径作用域的规则文件

这是最强大的特性。使用YAML前置元数据指定规则只在特定文件路径生效：

**API开发规则** `.claude/rules/api-guidelines.md`：

```markdown
---
paths:
  - "src/api/**/*.ts"
  - "src/routes/**/*.py"
---

# API开发规范

- 所有端点必须用Zod（TS）或Pydantic（Python）验证输入
- 返回统一错误格式: `{ error: string, code: number }`
- 所有请求记录correlation ID
- 分页接口必须支持cursor-based分页
- 错误响应包含request_id用于追踪
```

**React开发规则** `.claude/rules/frontend/react.md`：

```markdown
---
paths:
  - "src/components/**/*.tsx"
  - "src/hooks/**/*.ts"
---

# React开发规范

- 只用函数组件，禁止class组件
- 逻辑抽取到自定义hooks
- 使用React.memo优化列表渲染
- 状态管理优先使用Zustand
- 组件文件不超过200行，超过则拆分
```

**测试规则** `.claude/rules/testing.md`：

```markdown
---
paths:
  - "**/*.test.ts"
  - "**/*.test.py"
  - "**/*.spec.ts"
---

# 测试规范

- 测试名格式: "should [action] when [condition]"
- 一个测试一个断言（尽量）
- Mock外部服务，不调用真实API
- 覆盖边界情况: 空输入、null值、边界值
```

**安全关键路径规则** `.claude/rules/security.md`：

```markdown
---
paths:
  - "src/auth/**/*"
  - "src/payments/**/*"
  - "src/users/**/*"
---

# 安全关键代码规范

- 禁止记录密码、令牌、卡号等敏感数据
- 所有输入在函数边界验证
- 只使用参数化查询，禁止字符串拼接SQL
- 数据访问前必须检查授权
- 审计日志记录所有敏感操作
```

**数据库迁移规则** `.claude/rules/migrations.md`：

```markdown
---
paths:
  - "prisma/migrations/**/*"
  - "alembic/versions/**/*"
---

# 迁移安全规范

- 每次迁移必须包含回滚指令
- 先在生产数据副本上测试迁移
- 列删除与引用代码删除分不同迁移执行
- 先添加可空列 → 填充数据 → 再添加约束
```

### 2.4 目录结构总览

完成后的项目结构：

```
my-project/
├── CLAUDE.md                          # 核心运营规则（≤50行）
├── CLAUDE.local.md                    # 个人偏好（gitignored）
├── .claude/
│   ├── settings.json                  # 权限和配置
│   ├── settings.local.json            # 个人配置覆盖（gitignored）
│   └── rules/
│       ├── api-guidelines.md          # API规范 → src/api/**
│       ├── testing.md                 # 测试规范 → **/*.test.*
│       ├── security.md                # 安全规范 → auth/payments/**
│       ├── migrations.md              # 迁移规范 → migrations/**
│       └── frontend/
│           ├── react.md               # React规范 → components/**
│           └── styles.md              # CSS规范 → **/*.css
└── src/
    ├── api/                           # → 触发api-guidelines.md
    ├── components/                    # → 触发frontend/react.md
    ├── auth/                          # → 触发security.md
    └── ...
```

### 2.5 常见路径匹配模式速查

| 模式 | 匹配范围 | 典型用途 |
|------|----------|----------|
| `src/api/**/*.ts` | src/api及所有子目录中的.ts文件 | API层规范 |
| `**/*.test.ts` | 项目任意位置的测试文件 | 测试规范 |
| `src/components/*.tsx` | 仅components直接子文件 | 组件规范 |
| `**/*.css` | 所有CSS文件 | 样式规范 |
| `src/{auth,payments}/**/*` | auth或payments目录 | 安全敏感区 |
| `*.config.{js,ts}` | 根目录配置文件 | 配置管理规范 |

---

## 第三章：五层配置作用域深度解析

### 3.1 作用域层级与优先级

Claude Code的配置系统遵循严格的作用域优先级：

```mermaid
flowchart BT
    subgraph 配置作用域优先级
        direction BT
        U["⑤ 用户级<br/>~/.claude/settings.json<br/>个人全局偏好"] --> P
        P["④ 项目级<br/>.claude/settings.json<br/>团队共享配置"] --> L
        L["③ 本地级<br/>.claude/settings.local.json<br/>个人项目覆盖"] --> C
        C["② CLI参数<br/>命令行临时覆盖"] --> M
        M["① 托管级<br/>系统策略文件<br/>组织强制策略"]
    end

    style M fill:#f44336,color:#fff
    style C fill:#ff9800,color:#fff
    style P fill:#2196f3,color:#fff
    style U fill:#9e9e9e,color:#fff
```

**关键规则**：当同一设置出现在多个作用域时，高优先级的值覆盖低优先级的值。但权限规则（permissions）的行为不同——它们跨作用域合并而非覆盖。

### 3.2 settings.json配置详解

**项目级配置** `.claude/settings.json`（提交到git，团队共享）：

```json
{
  "permissions": {
    "allow": [
      "Bash(git log:*)",
      "Bash(git diff:*)",
      "Bash(git show:*)",
      "Bash(npm test:*)",
      "Bash(pytest:*)",
      "Bash(ruff check:*)",
      "Bash(docker compose:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl * | bash:*)",
      "Bash(* --force:*)"
    ]
  },
  "env": {
    "NODE_ENV": "development",
    "PYTHONPATH": "src"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write $FILE_PATH"
      }
    ]
  }
}
```

**个人项目覆盖** `.claude/settings.local.json`（gitignored）：

```json
{
  "permissions": {
    "allow": [
      "Bash(kubectl:*)",
      "Bash(terraform:*)"
    ]
  },
  "env": {
    "DATABASE_URL": "postgresql://localhost:5432/mydb_dev"
  }
}
```

**个人全局配置** `~/.claude/settings.json`：

```json
{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git branch:*)",
      "Bash(ls:*)",
      "Bash(cat:*)"
    ]
  },
  "env": {
    "EDITOR": "vim"
  }
}
```

### 3.3 权限规则的合并机制

权限的allow和deny列表跨作用域**合并**（而非覆盖）：

```
最终allow = 托管allow ∪ 项目allow ∪ 本地allow ∪ 用户allow
最终deny  = 托管deny  ∪ 项目deny  ∪ 本地deny  ∪ 用户deny
```

deny始终优先于allow——如果某个命令被任一层级拒绝，即使其他层级允许也无法执行。

### 3.4 各作用域适用场景

| 作用域 | 适用内容 | 示例 |
|--------|----------|------|
| 托管级 | 安全策略、合规要求 | 禁止所有危险命令 |
| CLI参数 | 临时会话覆盖 | 指定不同模型 |
| 本地级 | 机器特定配置 | 本地数据库URL |
| 项目级 | 团队共享标准 | 测试命令权限、代码格式化hook |
| 用户级 | 个人通用偏好 | 常用git命令权限 |

---

## 第四章：Monorepo中的层级化指令体系

### 4.1 多层CLAUDE.md架构

在monorepo中，Claude Code支持目录层级的CLAUDE.md发现机制：

```
my-monorepo/
├── CLAUDE.md                    # 顶层：全仓库通用规则
├── packages/
│   ├── api/
│   │   ├── CLAUDE.md            # API包专用规则
│   │   └── src/
│   │       ├── handlers/
│   │       │   └── CLAUDE.md    # 处理器专用规则（按需加载）
│   │       └── models/
│   ├── web/
│   │   ├── CLAUDE.md            # 前端包专用规则
│   │   └── src/
│   │       └── components/
│   └── shared/
│       └── CLAUDE.md            # 共享库规则
├── .claude/
│   └── rules/
│       ├── typescript.md        # 全仓库TS规范
│       └── testing.md           # 全仓库测试规范
└── CLAUDE.local.md              # 个人monorepo偏好
```

**顶层CLAUDE.md**——全仓库通用：

```markdown
# Monorepo全局规范

## 工作空间
- 使用pnpm workspaces管理包
- 构建: `pnpm -r build`
- 测试: `pnpm -r test`

## 通用原则
- 所有包使用TypeScript strict模式
- 共享类型定义在 @repo/types 包中
- 变更影响多个包时，逐个包提交
```

**packages/api/CLAUDE.md**——API专用：

```markdown
# API包规范

## 技术栈
- Fastify + TypeScript
- Drizzle ORM + PostgreSQL

## 命令
- 开发: `pnpm --filter api dev`
- 迁移: `pnpm --filter api db:generate`

## 约定
- 路由定义在routes/目录
- 每个路由文件导出Fastify插件
- 使用zod验证请求体和响应体
```

### 4.2 按需加载机制

子目录中的CLAUDE.md**不会**在会话启动时加载。它们只在Claude读取该目录下的文件时才被触发。这意味着：

- 在`packages/web/`中工作时，不会加载API的规则
- 在`packages/api/src/handlers/`中工作时，handler的CLAUDE.md才会被注入
- 这种机制天然实现了上下文隔离

### 4.3 与rules目录的协同

在monorepo中，推荐的使用策略：

| 指令类型 | 放置位置 | 原因 |
|----------|----------|------|
| 包级别的完整开发指南 | `packages/*/CLAUDE.md` | 按需加载，不浪费token |
| 跨包的特定领域规范 | `.claude/rules/` + paths | 路径匹配精确控制 |
| 全仓库通用原则 | 根目录`CLAUDE.md` | 始终需要，保持在30行内 |
| 个人偏好 | `CLAUDE.local.md` | 不影响团队 |

---

## 第五章：用户级规则——个人跨项目偏好

### 5.1 全局规则目录

在`~/.claude/rules/`下创建的规则文件会应用到你的所有项目：

```
~/.claude/
├── CLAUDE.md                      # 全局指令
├── settings.json                  # 全局设置
└── rules/
    ├── preferences.md             # 编码偏好
    ├── commit-style.md            # 提交风格
    └── workflow.md                # 工作流偏好
```

**个人编码偏好** `~/.claude/rules/preferences.md`：

```markdown
# 个人编码偏好

- 使用4空格缩进（Python）或2空格（TypeScript）
- 函数/方法必须有docstring
- 变量名使用snake_case（Python）或camelCase（TypeScript）
- 优先使用组合而非继承
- 错误处理使用Result模式而非异常（TypeScript）
```

**提交风格** `~/.claude/rules/commit-style.md`：

```markdown
# Git提交风格

- 使用conventional commits格式
- type(scope): description
- scope使用包名或模块名
- breaking changes必须标注!
- 正文解释why而非what
```

### 5.2 加载优先级

用户级规则在项目规则之前加载，这意味着项目规则拥有更高优先级：

```
加载顺序:
1. ~/.claude/rules/*.md          （用户级，较低优先级）
2. .claude/rules/*.md            （项目级，较高优先级）
```

如果用户级和项目级规则存在冲突，项目级规则胜出。这允许团队标准覆盖个人偏好。

---

## 第六章：完整实战案例——构建生产级配置体系

### 6.1 场景描述

假设我们有一个SaaS项目，包含以下结构：

```
saas-platform/
├── backend/          # Python FastAPI
├── frontend/         # Next.js React
├── infra/            # Terraform IaC
├── mobile/           # React Native
└── shared/           # 共享类型和工具
```

### 6.2 第一步：创建核心CLAUDE.md

`saas-platform/CLAUDE.md`：

```markdown
# SaaS Platform

## 项目概况
多端SaaS平台：FastAPI后端 + Next.js前端 + React Native移动端 + Terraform基础设施

## 全局命令
- 安装: `pnpm install` (前端/移动端), `uv sync` (后端)
- 检查: `pnpm lint` 和 `ruff check .`
- 测试: `pnpm test` 和 `pytest`

## 核心原则
- API契约优先：先定义OpenAPI spec，再实现
- 端到端类型安全：使用共享类型包
- 安全第一：所有API需要认证，敏感操作需要审计
- 变更必须向后兼容

## 架构约束
- 后端和前端通过API网关通信
- 共享类型定义在 shared/types/
- 绝不在客户端存储密钥
```

### 6.3 第二步：创建路径作用域规则

**后端规则** `.claude/rules/backend.md`：

```markdown
---
paths:
  - "backend/**/*.py"
---

# 后端开发规范

## 框架
- FastAPI + Pydantic v2 + SQLAlchemy 2.0
- 异步优先：所有IO操作使用async/await

## API设计
- 路由文件按领域分模块放在 backend/api/v1/
- 请求/响应模型使用Pydantic BaseModel
- 所有端点添加OpenAPI描述和响应示例

## 数据库
- 使用Alembic管理迁移
- 模型定义在 backend/models/
- Repository模式封装数据访问

## 测试
- 测试放在 tests/ 目录，镜像backend/结构
- 使用pytest-asyncio
- fixtures在conftest.py中定义
```

**前端规则** `.claude/rules/frontend.md`：

```markdown
---
paths:
  - "frontend/**/*.tsx"
  - "frontend/**/*.ts"
---

# 前端开发规范

## 框架
- Next.js 15 App Router + Tailwind CSS
- 状态管理: Zustand
- 数据获取: TanStack Query (React Query)

## 组件规范
- 组件放在对应的feature目录下
- 页面组件在 app/ 目录
- 可复用组件在 components/ui/
- 每个组件包含: 组件文件 + styles + types + index导出

## 性能
- 图片使用next/image
- 大列表使用虚拟滚动
- 代码分割使用dynamic import
```

**基础设施规则** `.claude/rules/infra.md`：

```markdown
---
paths:
  - "infra/**/*.tf"
  - "infra/**/*.tfvars"
---

# 基础设施规范

## Terraform
- 使用Terraform 1.7+，启用state encryption
- 模块化：每个环境一个workspace
- 变量通过terraform.tfvars传递，不硬编码
- 敏感值使用vault或AWS Secrets Manager

## 安全
- 所有S3 bucket启用versioning和encryption
- 安全组最小权限原则
- WAF规则保护公共端点
```

**移动端规则** `.claude/rules/mobile.md`：

```markdown
---
paths:
  - "mobile/**/*.tsx"
  - "mobile/**/*.ts"
---

# 移动端开发规范

## 框架
- React Native + Expo
- 导航: Expo Router
- 样式: NativeWind (Tailwind for RN)

## 平台适配
- 使用Platform.select处理平台差异
- 测试在iOS和Android双平台
- 无障碍支持: 所有交互元素添加accessibilityLabel
```

### 6.4 第三步：配置权限和hooks

`.claude/settings.json`：

```json
{
  "permissions": {
    "allow": [
      "Bash(git :*)",
      "Bash(pnpm :*)",
      "Bash(uv :*)",
      "Bash(pytest:*)",
      "Bash(ruff:*)",
      "Bash(terraform plan:*)",
      "Bash(terraform validate:*)",
      "Bash(docker compose:*)"
    ],
    "deny": [
      "Bash(rm -rf :*)",
      "Bash(terraform apply:*)",
      "Bash(* --force *)",
      "Bash(curl * | bash)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "matcher": ".*\\.py$",
            "command": "cd backend && ruff format $FILE_PATH && ruff check --fix $FILE_PATH"
          },
          {
            "matcher": ".*\\.(ts|tsx)$",
            "command": "npx prettier --write $FILE_PATH"
          }
        ]
      }
    ]
  }
}
```

### 6.5 第四步：配置层级可视化

```mermaid
flowchart TB
    subgraph 配置加载全流程
        A[会话启动] --> B[加载托管策略<br/>managed-settings.json]
        B --> C[加载用户全局<br/>~/.claude/settings.json<br/>~/.claude/CLAUDE.md<br/>~/.claude/rules/]
        C --> D[加载项目配置<br/>CLAUDE.md<br/>.claude/settings.json]
        D --> E[加载本地覆盖<br/>CLAUDE.local.md<br/>settings.local.json]
        E --> F[加载无paths的规则<br/>.claude/rules/*.md]
        F --> G[等待用户指令]
        G --> H{用户请求涉及什么文件?}
        H -->|backend/| I[注入backend.md规则]
        H -->|frontend/| J[注入frontend.md规则]
        H -->|infra/| K[注入infra.md规则]
        H -->|mobile/| L[注入mobile.md规则]
        I --> M[执行任务]
        J --> M
        K --> M
        L --> M
    end

    style B fill:#f44336,color:#fff
    style C fill:#9e9e9e,color:#fff
    style D fill:#2196f3,color:#fff
    style E fill:#ff9800,color:#fff
```

### 6.6 实测效果对比

在未配置规则时，Claude处理不同目录的代码使用相同的行为模式。配置路径作用域规则后：

| 操作 | 无规则 | 有路径规则 |
|------|--------|------------|
| 编辑API路由 | 使用通用编码风格 | 自动遵循API设计规范 |
| 编写React组件 | 不清楚项目组件约定 | 按feature目录组织，使用Zustand |
| 修改Terraform | 可能硬编码值 | 自动使用变量和加密 |
| 处理认证代码 | 可能遗漏安全检查 | 自动触发安全规范 |
| 上下文消耗 | 所有指令始终加载 | 仅加载相关指令，节省40-60% token |

---

## 第七章：高级技巧与最佳实践

### 7.1 规则文件的编写原则

**原则一：指令式而非描述式**

```markdown
❌ 不好的写法：
# 关于测试
这个项目比较重视测试，希望大家能多写测试。

✅ 好的写法：
# 测试规范
- 每个新函数必须编写单元测试
- 测试覆盖率不低于80%
- 使用pytest fixtures管理测试数据
```

**原则二：保持每个规则文件在50行以内**

过长的规则文件会降低Claude的遵循率。如果一个规则超过50行，考虑拆分为更细粒度的文件。

**原则三：使用正面指令而非禁令**

```markdown
❌ 过多禁令：
- 不要用class组件
- 不要用var
- 不要直接操作DOM
- 不要用any类型

✅ 以正面指令为主：
- 使用函数组件和hooks
- 使用const和let声明变量
- 使用React的状态管理API
- 使用具体的类型注解
```

### 7.2 规则与Skills的配合

规则（Rules）和技能（Skills）是互补的配置层：

| 特性 | Rules | Skills |
|------|-------|--------|
| 加载时机 | 自动（始终或按路径） | 按需（被调用时） |
| 优先级 | 高 | 中 |
| 最佳用途 | 编码规范、约束条件 | 可复用工作流、操作序列 |
| 跨项目复用 | 用户级rules目录 | 安装为插件 |

典型模式：Rules定义"做什么"，Skills定义"怎么做"。

例如，安全规则定义"所有API需要认证检查"，而一个安全审计Skill定义"按步骤审查所有端点的认证实现"。

### 7.3 CLAUDE.md中的文件导入

CLAUDE.md支持通过`@path/to/file`语法导入其他文件：

```markdown
# 项目规范

## 架构设计
@docs/architecture.md

## API契约
@docs/api-contract.md
```

导入是递归的（最多5层），允许你将详细文档从CLAUDE.md中分离出去。

### 7.4 定期清理和维护

规则体系需要定期维护：

```bash
# 检查当前项目所有规则文件
find .claude/rules -name "*.md" -exec echo "=== {} ===" \; -exec head -5 {} \;

# 统计CLAUDE.md行数
wc -l CLAUDE.md

# 检查是否有重复的规则
grep -r "禁止" .claude/rules/ CLAUDE.md | sort | uniq -d
```

**维护清单**：
- 每月检查CLAUDE.md是否超过50行，超出的内容迁移到rules
- 每季度审查paths模式是否仍然匹配项目结构
- 当项目结构变更时，同步更新对应的paths
- 删除过时的规则文件，避免指令退化

### 7.5 调试规则加载

当规则不生效时，可以排查：

```bash
# 检查规则文件是否存在YAML语法错误
head -5 .claude/rules/your-rule.md

# 确认paths格式正确（注意引号和缩进）
# 正确:
# ---
# paths:
#   - "src/api/**/*.ts"
# ---

# 错误（缺少引号、缩进不正确）:
# ---
# paths: src/api/**/*.ts
# ---

# 检查settings.json的JSON语法
python3 -c "import json; json.load(open('.claude/settings.json'))"
```

---

## 第八章：配置蓝图速查模板

### 8.1 新项目快速启动模板

新项目只需三步即可建立配置体系：

```bash
# 步骤1：创建核心CLAUDE.md
cat > CLAUDE.md << 'EOF'
# 项目名称

## 技术栈
- [填写你的技术栈]

## 命令
- 构建: [填写构建命令]
- 测试: [填写测试命令]
- 代码检查: [填写lint命令]

## 原则
- 正确性优先
- 先读后改
EOF

# 步骤2：创建规则目录
mkdir -p .claude/rules

# 步骤3：创建基本权限配置
cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(git :*)",
      "Bash([填写测试命令]:*)"
    ],
    "deny": [
      "Bash(rm -rf :*)"
    ]
  }
}
```

### 8.2 企业团队模板

企业团队需要更严格的管控：

```bash
# 托管级配置（由IT部署）
# /etc/claude-code/managed-settings.json
cat > /tmp/managed-settings.json << 'EOF'
{
  "permissions": {
    "deny": [
      "Bash(curl * | *)",
      "Bash(wget:*)",
      "Bash(* > /etc/*)",
      "Bash(chmod 777:*)",
      "Bash(*aws secret*:*)"
    ]
  },
  "hooks": {
    "Stop": [
      {
        "command": "/usr/local/bin/claude-audit-log.sh"
      }
    ]
  }
}
EOF

# 项目级配置（团队共享）
cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(git :*)",
      "Bash(npm :*)",
      "Bash(npx :*)",
      "Bash(docker compose:*)",
      "Bash(make:*)"
    ],
    "deny": [
      "Bash(docker compose *:*)",
      "Bash(npm publish:*)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write $FILE_PATH 2>/dev/null || true"
      }
    ]
  }
}
EOF
```

### 8.3 配置系统故障排查流程图

```mermaid
flowchart TD
    A[规则不生效] --> B{文件位置正确?}
    B -->|否| C[移到正确位置<br/>CLAUDE.md在根目录<br/>rules在.claude/rules/]
    B -->|是| D{YAML前置元数据正确?}
    D -->|否| E[检查paths格式<br/>使用YAML数组<br/>带引号的glob模式]
    D -->|是| F{文件路径匹配?}
    F -->|否| G[调整glob模式<br/>src/**匹配子目录<br/>src/*仅匹配直接子文件]
    F -->|是| H{settings.json权限冲突?}
    H -->|是| I[检查deny列表<br/>deny优先于allow]
    H -->|否| J{CLAUDE.md过长?}
    J -->|是| K[精简CLAUDE.md到50行内<br/>多余内容迁移到rules]
    J -->|否| L[重启Claude Code会话<br/>规则需要新会话加载]
```

---

## 延伸阅读

- [Claude Code官方文档：.claude目录](https://code.claude.com/docs/en/claude-directory) — Anthropic官方对.claude目录结构的完整说明
- [Claude Code官方文档：设置与权限](https://code.claude.com/docs/en/settings) — 五层作用域配置系统的权威参考
- [Claude Code官方文档：最佳实践](https://code.claude.com/docs/en/best-practices) — Anthropic团队总结的使用模式
- [Anthropic博客：使用CLAUDE.md文件](https://claude.com/blog/using-claude-md-files) — CLAUDE.md的设计理念和用法指南

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合训练营类型 | AI开发工具训练营、团队工程效能培训、企业AI规范化培训 |
| 学员基础要求 | 已使用Claude Code完成至少一个项目，理解基本git操作 |
| 预计教学时长 | 3-4小时（含动手练习） |
| 实操比例 | 70%实操 + 30%理论 |
| 分组建议 | 2-3人一组，每组一个真实项目作为练习对象 |
| 考核方式 | 每组提交完整的.claude/配置目录，通过Claude Code执行标准化任务验证规则是否生效 |

---

## 参考来源

1. [Explore the .claude directory - Claude Code Docs](https://code.claude.com/docs/en/claude-directory) — Anthropic官方.claude目录完整文档，涵盖所有配置文件的位置和加载机制
2. [Claude Code settings - Claude Code Docs](https://code.claude.com/docs/en/settings) — 五层配置作用域、settings.json字段参考、权限系统详解
3. [Best practices for Claude Code - Claude Code Docs](https://code.claude.com/docs/en/best-practices) — Anthropic官方最佳实践指南，CLAUDE.md编写和上下文管理建议
4. [Claude Code Rules Directory: Modular Instructions That Scale](https://claudefa.st/blog/guide/mechanics/rules-directory) — 规则目录的模块化指令详细教程，路径作用域机制深度解析
5. [The Definitive Guide to Every Claude Code Configuration File](https://wittmannf.github.io/blog/claude-code-config-guide/) — 所有配置文件类型的完整梳理，包含系统提示词架构的逆向工程分析

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)