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

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

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

# 项目规范

## 技术栈
- 后端: 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]"
- 一个测试一个断言

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

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

# 项目核心

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

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

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

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

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

# API开发规范

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

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

# React开发规范

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

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

# 测试规范

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

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

# 安全关键代码规范

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

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

# 迁移安全规范

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

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
    └── ...

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": {
    "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"
      }
    ]
  }
}

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

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

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

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偏好

# Monorepo全局规范

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

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

# API包规范

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

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

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

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

# 个人编码偏好

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

# Git提交风格

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

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

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

# 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/
- 绝不在客户端存储密钥

---
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中定义

---
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

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

# 基础设施规范

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

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

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

# 移动端开发规范

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

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

{
  "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"
          }
        ]
      }
    ]
  }
}

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

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

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

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

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

# 项目规范

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

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

# 检查当前项目所有规则文件
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

# 检查规则文件是否存在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'))"

# 步骤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 :*)"
    ]
  }
}

# 托管级配置（由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

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/>规则需要新会话加载]