Rules + @include + 级联 CLAUDE.md 配合使用指南

my-project/
├── CLAUDE.md                          ← 精简入口（<200行）
├── CLAUDE.local.md                    ← 个人覆盖（gitignore）
├── .claude/
│   ├── settings.json
│   └── rules/
│       ├── code-style.md              ← 无 paths，全局生效
│       ├── testing.md                 ← 无 paths，全局生效
│       ├── security.md                ← 无 paths，全局生效
│       ├── api.md                     ← 有 paths: src/api/**
│       ├── components.md              ← 有 paths: src/components/**
│       └── database.md               ← 有 paths: src/db/**
├── docs/
│   ├── architecture.md                ← 被 @include 引用
│   └── api-spec.md                    ← 被 @include 引用
└── src/
    ├── api/
    │   └── CLAUDE.md                  ← 子目录级联（按需加载）
    └── components/
        └── CLAUDE.md                  ← 子目录级联（按需加载）

# My Project

## 构建 & 测试
- `pnpm install` 安装依赖
- `pnpm test` 运行测试
- `pnpm build` 构建项目

## 架构概览
这是一个 Next.js + tRPC + Prisma 的全栈项目。
详细架构见 @docs/architecture.md

## 关键约定
- 使用 TypeScript strict mode
- 所有 PR 必须通过 CI
- commit message 遵循 conventional commits

## 容易踩的坑
- 数据库迁移前必须先 `pnpm db:generate`
- 环境变量在 `.env.example` 中有模板

# 代码风格
- 使用 2 空格缩进
- 字符串用单引号
- 文件末尾留空行
- 函数不超过 50 行

# 测试约定
- 测试文件与源文件同目录，命名 `*.test.ts`
- 使用 describe/it 结构
- mock 外部依赖，不 mock 内部模块

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

# API 开发规范
- 所有端点必须有输入校验（使用 zod）
- 统一错误响应格式 `{ error: string, code: number }`
- 必须写 OpenAPI 注释
- 使用 try-catch 包裹所有 handler

---
paths:
  - "src/components/**/*.tsx"
  - "src/ui/**/*.tsx"
---

# React 组件规范
- 使用函数组件 + hooks
- Props 用 interface 定义，命名 XxxProps
- 导出命名组件，不用 default export
- 样式使用 Tailwind，不写内联 style

---
paths:
  - "src/db/**/*.ts"
  - "prisma/**/*"
---

# 数据库规范
- 表名用 snake_case 复数形式
- 所有表必须有 created_at / updated_at
- 查询必须用参数化，禁止字符串拼接
- 迁移文件不可修改，只能新增

---
paths:
  - "**/*.{ts,tsx}"         # 所有 TypeScript 文件
  - "!**/*.test.ts"         # 但排除测试文件（ignore 库支持取反）
---

---
paths:
  - "src/**/*"              # src 下所有文件
  - "lib/**/*"              # lib 下所有文件
---

# My Project

项目架构详见 @docs/architecture.md
API 规范详见 @docs/api-spec.md
Git 工作流 @docs/git-workflow.md

# 团队共享指令
...

# 个人偏好（不入 Git）
@~/.claude/my-preferences.md

@AGENTS.md

## Claude 专属补充
- 使用 plan mode 处理 src/billing/ 下的修改

# API 模块
这个目录是 Express + TypeORM 后端。
- 路由在 routes/ 下，每个文件对应一个资源
- 中间件在 middleware/ 下
- 本目录测试用 supertest

# 前端模块
这个目录是 React + Vite 前端。
- 组件在 components/ 下
- 页面在 pages/ 下
- 本目录测试用 @testing-library/react

/project/CLAUDE.md            → "使用 Jest 测试"
/project/src/legacy/CLAUDE.md → "使用 Mocha 测试"（覆盖父级）

要写全局上下文？                          → CLAUDE.md
  └─ 内容超 200 行？                      → 拆到 @include 或 rules

要写通用规范？                            → .claude/rules/xxx.md（无 paths）
  └─ 只对特定文件类型生效？               → 加 paths frontmatter

子目录有独立技术栈/上下文？               → 子目录/CLAUDE.md
  └─ 有对该子目录的精细规则？             → 子目录/.claude/rules/

要引用已有文档（README、API spec）？      → @include
要跨项目共享规则？                        → symlink 或 @~ 引用
要覆盖团队配置做个人调整？                → CLAUDE.local.md

CLAUDE.md（入口，<200 行）
  ├── @docs/architecture.md          # include 引入架构文档
  └── @docs/conventions.md           # include 引入约定文档

.claude/rules/
  ├── code-style.md                  # 无 paths → 全局代码风格
  ├── git.md                         # 无 paths → 全局 Git 规范
  ├── api.md                         # paths: src/api/** → API 专属
  ├── frontend.md                    # paths: src/ui/** → 前端专属
  └── testing.md                     # paths: **/*.test.ts → 测试专属

src/api/CLAUDE.md                    # 子目录上下文（按需加载）
src/frontend/CLAUDE.md               # 子目录上下文（按需加载）

CLAUDE.local.md                      # 个人覆盖（gitignore）