Claude Code配置六层架构全解：从CLAUDE.md到权限模型

graph TB
    subgraph "Claude Code 六层配置架构"
        L1["第1层: 系统级<br/>/etc/claude-code/settings.json"]
        L2["第2层: 用户全局<br/>~/.claude/settings.json<br/>~/.claude/CLAUDE.md"]
        L3["第3层: 项目级<br/>.claude/settings.json<br/>CLAUDE.md"]
        L4["第4层: 本地覆盖<br/>.claude/settings.local.json<br/>CLAUDE.local.md"]
        L5["第5层: 模块规则<br/>.claude/rules/*.md"]
        L6["第6层: 会话级<br/>/compact, 环境变量"]
    end
    L1 --> L2 --> L3 --> L4 --> L5 --> L6
    style L1 fill:#ff6b6b,color:#fff
    style L2 fill:#ffa94d,color:#fff
    style L3 fill:#ffd43b,color:#333
    style L4 fill:#69db7c,color:#333
    style L5 fill:#4dabf7,color:#fff
    style L6 fill:#9775fa,color:#fff

claude --version
# 预期输出：Claude Code v1.x.x 或更高版本

# 查看当前配置目录结构
ls -la ~/.claude/

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
    "API_TIMEOUT_MS": "300000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  },
  "enabledPlugins": {
    "superpowers@claude-plugins-official": true,
    "context7@claude-plugins-official": true
  },
  "theme": "dark"
}

{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Bash(npx:*)",
      "Bash(node:*)",
      "Bash(python3:*)",
      "Bash(ls:*)",
      "Bash(cat:*)",
      "WebSearch",
      "mcp__context7__resolve-library-id",
      "mcp__context7__query-docs"
    ]
  }
}

# Global Preferences

## Language & Style
- 默认使用中文回复，代码注释可用英文
- 回复简洁明了，避免冗长解释

## General Rules
- 不要自动 commit，只在用户明确要求时执行 git commit
- 始终先读取文件再编辑，不要盲目修改
- 不要提交 secrets、credentials、.env 等敏感文件
- 修改代码后，如有测试命令，主动运行测试验证

# 步骤1：确认配置目录存在
mkdir -p ~/.claude

# 步骤2：创建全局CLAUDE.md
cat > ~/.claude/CLAUDE.md << 'EOF'
# Global Preferences

## Language
- 使用中文回复，代码保持原文

## Code Style
- 优先编辑现有文件而非创建新文件
- 先读取再修改，不要盲目操作
- 修改后自动运行测试验证

## Git Rules
- 不要自动commit或add
- 不要提交secrets和.env文件

## Summary Instructions
When summarizing, always preserve:
- The current task objective
- File paths that were read or modified
- Test results and error messages
- Pending tasks and next steps
EOF

# 步骤3：验证文件
cat ~/.claude/CLAUDE.md

graph LR
    subgraph "项目内 CLAUDE.md 三级层次"
        A["~/.claude/CLAUDE.md<br/>（全局指令）"]
        B["项目根/CLAUDE.md<br/>（团队共享）"]
        C["项目根/CLAUDE.local.md<br/>（个人覆盖）"]
        D["子目录/CLAUDE.md<br/>（模块级）"]
    end
    A --> B --> C --> D
    style A fill:#ffa94d,color:#fff
    style B fill:#ffd43b,color:#333
    style C fill:#69db7c,color:#333
    style D fill:#4dabf7,color:#fff

# 项目级配置目录
.claude/
├── settings.json          # 团队共享的项目配置（提交Git）
├── settings.local.json    # 个人权限覆盖（不提交Git）
├── commands/              # 自定义斜杠命令
├── rules/                 # 模块化规则文件
└── memory/                # 自动积累的学习记录

{
  "permissions": {
    "allow": [
      "Bash(go test:*)",
      "Bash(go build:*)",
      "Bash(go run:*)",
      "Bash(docker compose:*)",
      "Bash(make:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(dropdb:*)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash(go test:*)",
        "command": "echo 'Tests completed at $(date)'"
      }
    ]
  }
}

# 在项目根目录运行
cd your-project
claude
> /init

# Project Overview

This is a Go-based REST API service using the Gin framework.

# Commands
- Build: `go build -o bin/server ./cmd/server`
- Test: `go test ./...`
- Lint: `golangci-lint run`

# Architecture
- `cmd/server/main.go` — Entry point
- `internal/handler/` — HTTP handlers
- `internal/service/` — Business logic
- `internal/repository/` — Data access layer

# Code Style
- Follow Go standard formatting (gofmt)
- Error handling: always wrap errors with context
- Use table-driven tests

# Important Notes
- Database migrations in `migrations/`
- Config loaded from environment variables

# 步骤1：创建项目配置目录
mkdir -p .claude

# 步骤2：创建团队共享的项目CLAUDE.md
cat > CLAUDE.md << 'EOF'
# 项目：电商平台后端API

## 技术栈
- Node.js 20 + TypeScript 5
- Express.js + Prisma ORM
- PostgreSQL 16
- Redis 7（缓存/会话）

## 关键命令
- 开发：`npm run dev`
- 测试：`npm test`
- 构建：`npm run build`
- 数据库迁移：`npx prisma migrate dev`
- 生成Prisma客户端：`npx prisma generate`

## 项目结构
- `src/routes/` — 路由定义
- `src/controllers/` — 请求处理
- `src/services/` — 业务逻辑
- `src/middleware/` — 认证、日志、错误处理
- `prisma/schema.prisma` — 数据模型

## 编码规范
- 使用Zod进行输入验证
- 错误处理统一使用 AppError 类
- 控制器不直接访问数据库，通过Service层
- 测试使用 Jest + Supertest

## 禁止事项
- 不要修改 prisma/schema.prisma 除非明确要求
- 不要删除或重命名已有的 API 端点
- 不要在测试中使用真实数据库连接
EOF

# 步骤3：创建本地覆盖文件
cat > CLAUDE.local.md << 'EOF'
# 个人偏好
- 调试时使用 console.log 而非 debugger
- 偏好函数式写法而非 class
EOF

# 步骤4：确保本地文件不被提交
echo "CLAUDE.local.md" >> .gitignore
echo ".claude/settings.local.json" >> .gitignore

# 步骤5：创建项目级权限配置
cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Bash(npx:*)",
      "Bash(node:*)",
      "Bash(git:*)"
    ],
    "deny": [
      "Bash(npm publish:*)",
      "Bash(rm -rf node_modules:*)"
    ]
  }
}
EOF

.claude/rules/
├── typescript.md       # TypeScript编码规范
├── testing.md          # 测试策略
├── database.md         # 数据库操作规范
└── api-design.md       # API设计规范

# TypeScript Rules

## Type Safety
- 所有函数参数和返回值必须有类型注解
- 禁止使用 any，必须用 unknown + 类型守卫
- 使用 interface 定义对象类型，type 用于联合类型和工具类型

## Import Convention
- 使用 Node.js 子路径导入：import { User } from "#/types"
- 第三方库导入在前，项目导入在后，空行分隔
- 禁止使用 import * as

## Error Handling
- 异步操作必须使用 try/catch
- 错误类型使用自定义 AppError 及其子类
- 不要吞掉错误——至少 log 一条 warning

# Testing Rules

## Test Structure
- 文件名：`*.test.ts`，与源文件同目录
- 使用 describe/it 块，describe 名称用中文描述场景

## Coverage Requirements
- Service 层覆盖率 ≥ 90%
- Controller 层覆盖率 ≥ 80%
- 关键业务路径必须有集成测试

## Mocking
- 外部 API 调用必须 mock
- 数据库操作使用测试容器，不 mock Prisma
- 使用 `beforeEach` 重置 mock 状态

# 临时切换API端点
claude -e ANTHROPIC_BASE_URL=https://staging-api.example.com

# 设置调试模式
claude -e DEBUG=claude:* -e LOG_LEVEL=debug

graph LR
    subgraph "上下文窗口生命周期"
        A["新会话<br/>~0% 已用"] --> B["正常工作<br/>~40% 已用"]
        B --> C["接近阈值<br/>~70% 已用"]
        C --> D["自动压缩<br/>Compaction"]
        D --> E["继续工作<br/>~30% 已用"]
        C --> F["手动压缩<br/>/compact"]
        F --> E
    end
    style C fill:#ffd43b,color:#333
    style D fill:#ff6b6b,color:#fff
    style F fill:#69db7c,color:#333

graph TD
    subgraph "配置优先级（从低到高）"
        P1["1. 系统默认值<br/>内置的默认行为"]
        P2["2. 系统级配置<br/>/etc/claude-code/settings.json"]
        P3["3. 用户全局<br/>~/.claude/settings.json<br/>~/.claude/CLAUDE.md"]
        P4["4. 项目级<br/>.claude/settings.json<br/>项目根/CLAUDE.md"]
        P5["5. 本地覆盖<br/>.claude/settings.local.json<br/>CLAUDE.local.md"]
        P6["6. 规则文件<br/>.claude/rules/*.md"]
        P7["7. 会话级<br/>环境变量 / -e参数"]
    end
    P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7
    style P7 fill:#9775fa,color:#fff
    style P1 fill:#ff6b6b,color:#fff

有效权限 = 全局allow ∪ 项目allow ∪ 本地allow - (全局deny ∪ 项目deny ∪ 本地deny)

// ~/.claude/settings.local.json（个人开发机）
{
  "permissions": {
    "allow": [
      "Bash(git:*)",
      "Bash(npm:*)",
      "Bash(npx:*)",
      "Bash(node:*)",
      "Bash(docker:*)",
      "Bash(python3:*)",
      "Bash(go:*)",
      "Bash(make:*)",
      "Bash(cargo:*)"
    ]
  }
}

// .claude/settings.json（项目级，提交Git）
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Bash(npm run build:*)"
    ],
    "deny": [
      "Bash(npm publish:*)",
      "Bash(git push:*)",
      "Bash(rm:*)"
    ]
  }
}

// ~/.claude/settings.json（全局，团队统一分发）
{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm test:*)",
      "Bash(npm run lint:*)"
    ]
  }
}

// ~/.claude/settings.local.json（高级开发者，个人额外权限）
{
  "permissions": {
    "allow": [
      "Bash(docker compose:*)",
      "Bash(kubectl:*)",
      "Bash(npm run deploy:*)"
    ]
  }
}

my-saas-app/
├── .claude/
│   ├── settings.json
│   ├── settings.local.json
│   ├── rules/
│   │   ├── frontend.md
│   │   ├── backend.md
│   │   └── database.md
│   └── commands/
│       └── deploy.md
├── CLAUDE.md
├── CLAUDE.local.md
├── package.json
├── apps/
│   ├── web/          # Next.js前端
│   │   └── CLAUDE.md # 前端子目录指令
│   └── api/          # Express后端
│       └── CLAUDE.md # 后端子目录指令
├── packages/
│   └── shared/       # 共享类型和工具
└── prisma/
    └── schema.prisma

cat > CLAUDE.md << 'EOF'
# 项目：SaaS管理平台

## 技术栈
- Turborepo monorepo
- 前端：Next.js 15 + React 19 + Tailwind CSS
- 后端：Express 5 + TypeScript 5
- 数据库：PostgreSQL 16 + Prisma
- 认证：NextAuth.js v5

## 关键命令
- 安装依赖：`npm install`
- 开发模式：`npm run dev`
- 构建全部：`npm run build`
- 测试全部：`npm run test`
- Lint：`npm run lint`
- 数据库迁移：`npx prisma migrate dev`

## 项目结构
- `apps/web/` — Next.js前端应用
- `apps/api/` — Express API服务
- `packages/shared/` — 共享类型、常量、工具函数
- `prisma/` — 数据库schema和迁移

## 编码规范
- 严格TypeScript，零any
- 函数最大长度30行
- 组件最大长度200行
- API响应统一格式：{ success, data, error }

## 测试要求
- 新功能必须有单元测试
- API端点必须有集成测试
- PR合并前所有测试必须通过
EOF

mkdir -p .claude/rules

# 前端规则
cat > .claude/rules/frontend.md << 'EOF'
# Frontend Rules

## Component Convention
- 文件名：PascalCase.tsx
- 组件导出：默认导出
- Props类型：定义在同一文件的顶部

## State Management
- 服务端状态：React Query (TanStack Query)
- 客户端状态：zustand
- 表单状态：react-hook-form + zod

## Styling
- Tailwind CSS utility classes
- 复杂组件使用 cn() 合并类名
- 响应式优先：mobile-first
EOF

# 后端规则
cat > .claude/rules/backend.md << 'EOF'
# Backend Rules

## API Design
- RESTful 风格，资源名用复数
- 版本化路由：/api/v1/
- 请求验证使用 Zod schema
- 错误处理使用 AppError 类（含 statusCode）

## Database
- 所有数据库操作通过 Service 层
- 禁止在 Controller 中直接使用 Prisma
- 事务操作使用 prisma.$transaction
- 软删除：添加 deletedAt 字段

## Authentication
- JWT token 存在 httpOnly cookie
- 中间件验证：requireAuth, requireRole
- RBAC权限：admin, editor, viewer
EOF

# 数据库规则
cat > .claude/rules/database.md << 'EOF'
# Database Rules

## Schema Changes
- 不要修改已有字段的类型（需要迁移）
- 新增字段必须设置默认值或标记可选
- 枚举值变更需要手动迁移SQL

## Migration Rules
- 迁移文件一旦合并不可修改
- 新迁移：npx prisma migrate dev --name 描述
- 生产迁移：npx prisma migrate deploy

## Query Optimization
- 列表查询必须分页
- 避免N+1查询，使用 include 或 select
- 大批量操作使用 batch
EOF

cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Bash(npx:*)",
      "Bash(node:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(git add:*)",
      "Bash(git commit:*)"
    ],
    "deny": [
      "Bash(npm publish:*)",
      "Bash(git push --force:*)",
      "Bash(rm -rf /:*)"
    ]
  }
}
EOF

# 前端子目录
cat > apps/web/CLAUDE.md << 'EOF'
# Frontend App (Next.js)

## Routes
- App Router: src/app/
- 页面组件：page.tsx
- 布局组件：layout.tsx
- 加载状态：loading.tsx
- 错误处理：error.tsx

## Key Libraries
- UI: shadcn/ui (already configured)
- Icons: lucide-react
- Date: date-fns
- Charts: recharts
EOF

# 后端子目录
cat > apps/api/CLAUDE.md << 'EOF'
# Backend API (Express)

## Route Structure
- src/routes/v1/ — API v1路由
- 每个资源一个文件：users.ts, orders.ts, etc.

## Middleware Stack
- cors → helmet → rateLimit → auth → validate → controller

## Environment
- 需要 .env 文件（参考 .env.example）
- 必须变量：DATABASE_URL, JWT_SECRET, REDIS_URL
EOF

# 个人偏好（不提交Git）
cat > CLAUDE.local.md << 'EOF'
# Personal Preferences
- 使用 console.log 调试（开发环境）
- 偏好 early return 模式
EOF

cat > .claude/settings.local.json << 'EOF'
{
  "permissions": {
    "allow": [
      "Bash(docker compose:*)",
      "Bash(docker:*)"
    ]
  }
}
EOF

# 确保本地文件不提交
echo -e "CLAUDE.local.md\n.claude/settings.local.json" >> .gitignore

# 进入Claude Code会话
claude

# 在会话中验证
> 你能告诉我当前项目的技术栈和目录结构吗？

# Claude Code应该能准确读取CLAUDE.md中的信息
# 如果回答不准确，说明配置文件可能未正确加载

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null"
      },
      {
        "matcher": "Bash(npm test:*)",
        "command": "echo '[$(date)] Tests completed' >> .claude/test-history.log"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash(npx prisma migrate:*)",
        "command": "echo '⚠️ About to run database migration. Verify this is intentional.'"
      }
    ]
  }
}

# Claude Code会自动记录以下内容：
.claude/memory/
├── user-preferences.md    # 用户偏好
├── project-conventions.md # 项目约定
└── common-patterns.md     # 常见模式

# 创建团队模板仓库
git init claude-config-template
cd claude-config-template

# 模板结构
mkdir -p .claude/rules .claude/commands
touch CLAUDE.md
touch .claude/settings.json

# 编写通用规则...

# 新项目一键复制
# cp -r claude-config-template/. new-project/
# cd new-project && git init

# 方法1：退出并重新进入
> /exit
claude

# 方法2：使用/clear清除上下文
> /clear

# 检查全局权限
cat ~/.claude/settings.json
cat ~/.claude/settings.local.json

# 检查项目权限
cat .claude/settings.json
cat .claude/settings.local.json

# 确认没有语法错误
python3 -c "import json; json.load(open('.claude/settings.json'))"

团队共享（提交Git）        个人覆盖（不提交Git）
├── CLAUDE.md              ├── CLAUDE.local.md
├── .claude/settings.json  ├── .claude/settings.local.json
└── .claude/rules/         └── (个人额外规则)

graph TB
    subgraph "配置加载全流程"
        START["claude 命令启动"] --> SYS["加载系统级配置"]
        SYS --> GLOBAL["加载全局配置<br/>~/.claude/settings.json<br/>~/.claude/CLAUDE.md"]
        GLOBAL --> PROJ["加载项目配置<br/>.claude/settings.json<br/>项目/CLAUDE.md"]
        PROJ --> LOCAL["加载本地覆盖<br/>.claude/settings.local.json<br/>CLAUDE.local.md"]
        LOCAL --> RULES["加载规则文件<br/>.claude/rules/*.md"]
        RULES --> MEMORY["加载记忆文件<br/>.claude/memory/*.md"]
        MEMORY --> SUBDIR["加载子目录CLAUDE.md<br/>（按当前工作路径）"]
        SUBDIR --> READY["配置就绪<br/>开始对话"]
    end
    style START fill:#9775fa,color:#fff
    style READY fill:#69db7c,color:#333