Claude Code配置体系全实战：五层优先级到团队标准化

graph TD
    A["Enterprise<br/>企业级策略<br/>~/.claude/settings.json<br/>（最低优先级）"] --> B["Managed<br/>MDM/注册表托管<br/>managed-settings.json"]
    B --> C["User<br/>用户全局<br/>~/.claude/settings.json"]
    C --> D["Project<br/>项目共享<br/>.claude/settings.json"]
    D --> E["Local<br/>项目本地<br/>.claude/settings.local.json<br/>（最高优先级）"]

    style A fill:#e8f5e9
    style B fill:#fff3e0
    style C fill:#e3f2fd
    style D fill:#fce4ec
    style E fill:#f3e5f5

# 查看所有配置文件的位置
echo "=== 用户全局配置 ==="
cat ~/.claude/settings.json 2>/dev/null || echo "(不存在)"

echo ""
echo "=== 项目共享配置 ==="
cat .claude/settings.json 2>/dev/null || echo "(不存在)"

echo ""
echo "=== 项目本地配置 ==="
cat .claude/settings.local.json 2>/dev/null || echo "(不存在)"

echo ""
echo "=== 项目的CLAUDE.md ==="
cat CLAUDE.md 2>/dev/null || echo "(不存在)"

// .claude/settings.json — 项目级配置示例
{
  // ─── 权限系统 ───
  "permissions": {
    "allow": [
      "Bash(npm test*)",        // 允许运行测试
      "Bash(npm run lint*)",    // 允许运行lint
      "Bash(git status)",       // 允许查看git状态
      "Read",                   // 允许读取任何文件
      "Glob",                   // 允许文件搜索
      "Grep"                    // 允许内容搜索
    ],
    "deny": [
      "Bash(rm -rf*)",          // 禁止递归删除
      "Bash(sudo*)",            // 禁止sudo
      "Write(.env*)",           // 禁止写环境变量文件
      "Read(*.pem)",            // 禁止读取证书文件
      "Bash(git push --force*)" // 禁止强制推送
    ]
  },

  // ─── 环境变量 ───
  "env": {
    "NODE_ENV": "development",
    "API_BASE_URL": "http://localhost:3000",
    "MAX_RETRIES": "3"
  },

  // ─── MCP服务器 ───
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_PERSONAL_TOKEN}" }
    }
  },

  // ─── 模型选择 ───
  "model": "claude-sonnet-4-6",

  // ─── Hooks ───
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": ["npm run lint-staged"]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": ["npm run format:changed"]
      }
    ]
  }
}

格式: ToolName(pattern)
示例: Bash(npm test*)
      Read(*.ts)
      Write(src/**)

flowchart TD
    A["Claude请求执行工具"] --> B{"检查所有层的 deny"}
    B -->|"有匹配"| Z["❌ 拒绝执行"]
    B -->|"无匹配"| C{"检查所有层的 allow"}
    C -->|"有匹配"| D["✅ 自动执行"]
    C -->|"无匹配"| E{"检查所有层的 ask"}
    E -->|"有匹配"| F["🔔 弹窗询问用户"]
    E -->|"无匹配"| F

    style Z fill:#ffcdd2
    style D fill:#c8e6c9
    style F fill:#fff9c4

// frontend-project/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(node *)",
      "Read",
      "Write",
      "Edit",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(npm publish*)",
      "Write(*.env*)",
      "Write(*.key)",
      "Write(*.pem)"
    ]
  },
  "env": {
    "BROWSER": "none"
  }
}

// api-project/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(go *)",
      "Bash(docker *)",
      "Bash(make *)",
      "Bash(curl *)",
      "Read",
      "Write",
      "Edit"
    ],
    "deny": [
      "Bash(docker rm*)",
      "Bash(docker system prune*)",
      "Bash(sudo*)",
      "Write(*.env.production*)"
    ]
  }
}

~/.claude/CLAUDE.md           ← 全局个人指令（所有项目生效）
<project>/CLAUDE.md           ← 项目根目录（团队共享，提交Git）
<project>/.claude/CLAUDE.md   ← 项目.claude目录（同上，效果相同）
<project>/src/CLAUDE.md       ← 子目录级（进入该目录时生效）

# 项目名称

## 技术栈
- 语言: TypeScript 5.x (strict mode)
- 框架: Next.js 15 (App Router)
- 数据库: PostgreSQL 16 + Prisma ORM
- 测试: Vitest + Playwright

## 项目结构
- `src/app/` — 页面路由
- `src/components/` — UI组件
- `src/lib/` — 工具函数和共享逻辑
- `src/server/` — 服务端代码
- `prisma/` — 数据库Schema和迁移

## 编码规范
- 使用函数式组件和hooks，不用class组件
- 文件命名：组件用PascalCase，工具用camelCase
- 所有API响应使用zod schema验证
- 错误处理使用Result模式，不抛异常
- 导入使用 `@/` 路径别名

## 测试要求
- 新功能必须包含单元测试
- API端点必须有集成测试
- 使用 `npm test` 运行所有测试
- 测试覆盖率不低于80%

## 重要规则
- 不要修改 prisma/schema.prisma 除非明确要求
- 不要删除任何现有的API端点
- env变量通过 .env.local 管理，不要硬编码
- 提交前运行 `npm run lint && npm test`

project/
├── CLAUDE.md              ← 全项目通用规则
├── src/
│   ├── CLAUDE.md          ← 前端开发特定规则
│   └── components/
│       └── CLAUDE.md      ← 组件开发规范
└── api/
    └── CLAUDE.md          ← API开发特定规则

# API模块规范

## 数据库操作
- 所有查询通过Prisma Client执行
- 使用事务处理多表操作
- 分页查询统一使用 cursor-based pagination

## API设计
- RESTful风格，资源名用复数形式
- 响应格式: `{ data: T, meta?: { page, limit, total } }`
- 错误响应: `{ error: { code, message, details? } }`
- 认证通过Authorization Bearer token

## 安全
- 输入验证使用zod schema
- SQL查询通过Prisma参数化，禁止字符串拼接
- 敏感字段(密码等)永不出现在响应中

# [项目名]

## 一句话简介
[用一句话描述这个项目做什么]

## 技术栈
[列出主要技术]

## 项目结构
[用树状图说明目录含义]

## 开发命令
- 启动开发: `npm run dev`
- 运行测试: `npm test`
- 代码检查: `npm run lint`
- 构建: `npm run build`

## 编码规范
[3-5条最重要的规则]

## 禁止操作
[列出绝对不能做的事情]

## 提交规范
[Git commit消息格式]

git add CLAUDE.md
git commit -m "Add CLAUDE.md for project context"

flowchart LR
    A["方式1: settings.json<br/>env字段"] --> D["会话内生效"]
    B["方式2: .env文件<br/>项目根目录"] --> D
    C["方式3: Shell环境<br/>export/export命令"] --> D

    style A fill:#e3f2fd
    style B fill:#e8f5e9
    style C fill:#fff3e0

{
  "env": {
    "DATABASE_URL": "postgresql://localhost:5432/myapp_dev",
    "REDIS_URL": "redis://localhost:6379",
    "LOG_LEVEL": "debug"
  }
}

# 在 .bashrc 或 .zshrc 中设置
export ANTHROPIC_API_KEY="sk-ant-..."
export GITHUB_PERSONAL_TOKEN="ghp_..."

{
  "env": {
    "API_KEY": "${MY_API_KEY}"
  }
}

project/
├── .claude/
│   ├── settings.json              ← 基础配置（共享）
│   ├── settings.local.json        ← 个人覆盖（不提交）
│   └── env.sh                     ← 环境变量加载脚本
├── .env.example                   ← 环境变量模板（提交）
├── .env                           ← 实际环境变量（不提交）
└── .gitignore                     ← 忽略 .env 和 settings.local.json

# 复制此文件为 .env 并填入实际值
ANTHROPIC_API_KEY=sk-ant-your-key-here
DATABASE_URL=postgresql://localhost:5432/myapp_dev
REDIS_URL=redis://localhost:6379

.env
.claude/settings.local.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[$(date)] Tool: $CLAUDE_TOOL_NAME' >> ~/.claude/audit.log"
          }
        ]
      },
      {
        "matcher": "Bash(rm*)",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'BLOCKED: rm command detected' >&2 && exit 2"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Session ended. Files modified:' && git diff --name-only"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null" }]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "echo \"[$(date -Iseconds)] $CLAUDE_TOOL_INPUT\" >> .claude/bash-audit.log" }]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "cd $CLAUDE_PROJECT_DIR && npm test 2>&1 | tail -5" }]
      }
    ]
  }
}

graph TB
    subgraph "组织层"
        A["Enterprise Policy<br/>安全底线、合规要求<br/>不可被用户覆盖"]
    end

    subgraph "团队层"
        B["Project CLAUDE.md<br/>编码规范、项目结构<br/>提交到Git，全员共享"]
        C["Project settings.json<br/>共享权限、MCP服务器<br/>提交到Git，全员共享"]
    end

    subgraph "个人层"
        D["User CLAUDE.md<br/>个人偏好、工作习惯<br/>仅在个人机器"]
        E["Local settings<br/>调试开关、临时配置<br/>不提交Git"]
    end

    A --> B
    B --> C
    C --> D
    D --> E

    style A fill:#ffcdd2
    style B fill:#c8e6c9
    style C fill:#c8e6c9
    style D fill:#bbdefb
    style E fill:#e1bee7

team-project/
├── CLAUDE.md                       ← 项目背景和规范
├── .claude/
│   ├── settings.json               ← 团队共享配置
│   ├── settings.local.json         ← 个人覆盖（.gitignore）
│   └── skills/                     ← 团队自定义Skills
│       └── team-workflow.md
├── .claudeignore                   ← 排除敏感文件
├── .env.example                    ← 环境变量模板
└── .gitignore                      ← 忽略个人配置

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npm test*)",
      "Bash(npx *)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Read",
      "Write(src/**)",
      "Edit",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(sudo*)",
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Bash(npm publish*)",
      "Write(.env*)",
      "Write(*.key)",
      "Write(*.pem)",
      "Write(*.secret)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "cd \"$CLAUDE_PROJECT_DIR\" && npm run lint --quiet 2>&1 | tail -3 || true" }
        ]
      }
    ]
  }
}

# Team Project

## 技术栈
TypeScript + React + Node.js + PostgreSQL

## 编码规范
- ESLint + Prettier，配置见 .eslintrc.js 和 .prettierrc
- 组件文件用PascalCase，工具文件用camelCase
- 所有新代码必须有对应的测试文件
- API响应用zod验证

## 测试
- 单元测试: `npm test`
- E2E测试: `npm run test:e2e`
- 覆盖率: 不低于80%

## Git规范
- 分支名: feature/TICKET-ID-description
- Commit: conventional commits格式
- 提交前: `npm run lint && npm test`

## 禁止操作
- 不要直接修改 main 分支
- 不要删除或重命名现有的API端点
- 不要修改数据库迁移文件
- 不要在代码中硬编码密钥或密码

#!/bin/bash
# 团队新成员 Claude Code 环境一键配置

set -e

echo "=== Claude Code 团队环境配置 ==="

# 1. 检查 Claude Code 是否已安装
if ! command -v claude &> /dev/null; then
    echo "安装 Claude Code..."
    npm install -g @anthropic-ai/claude-code
fi

# 2. 创建个人全局配置（如果不存在）
mkdir -p ~/.claude
if [ ! -f ~/.claude/settings.json ]; then
    cat > ~/.claude/settings.json << 'EOF'
{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Bash(sudo*)"]
  }
}
EOF
    echo "✅ 已创建个人全局配置"
fi

# 3. 创建个人全局 CLAUDE.md
if [ ! -f ~/.claude/CLAUDE.md ]; then
    cat > ~/.claude/CLAUDE.md << 'EOF'
# 个人偏好

## 语言
- 默认使用中文回复
- 代码注释用英文

## 工作习惯
- 修改代码后主动运行测试
- 不要自动commit
- 优先编辑现有文件而非创建新文件
EOF
    echo "✅ 已创建个人全局 CLAUDE.md"
fi

# 4. 创建项目本地配置
mkdir -p .claude
cat > .claude/settings.local.json << 'EOF'
{
  "env": {
    "CLAUDE_USER": ""
  }
}
EOF

# 5. 复制环境变量模板
if [ -f .env.example ] && [ ! -f .env ]; then
    cp .env.example .env
    echo "⚠️  请编辑 .env 填入实际值"
fi

# 6. 确保 .gitignore 包含必要条目
if ! grep -q ".claude/settings.local.json" .gitignore 2>/dev/null; then
    echo -e "\n# Claude Code personal config\n.claude/settings.local.json\n.env" >> .gitignore
fi

echo ""
echo "=== 配置完成 ==="
echo "运行 'claude' 开始使用"

saas-platform/
├── CLAUDE.md
├── .claude/
│   ├── settings.json
│   ├── settings.local.json    (.gitignore)
│   └── skills/
│       ├── add-feature.md
│       └── fix-bug.md
├── .claudeignore
├── src/
│   ├── app/                   ← Next.js页面
│   ├── components/            ← UI组件
│   ├── server/                ← tRPC路由
│   │   ├── routers/
│   │   └── trpc.ts
│   ├── lib/                   ← 共享工具
│   └── CLAUDE.md              ← 前端模块规则
├── prisma/
│   ├── schema.prisma
│   └── migrations/
├── tests/
├── .env.example
└── .gitignore

# SaaS Platform

## 概述
B2B SaaS平台，支持多租户、RBAC权限、Stripe计费。

## 技术栈
- Next.js 15 (App Router, Server Components)
- tRPC v11 (类型安全API)
- Prisma (ORM)
- PostgreSQL 16
- Tailwind CSS + shadcn/ui
- Vitest + Playwright

## 项目结构
- `src/app/` — Next.js页面路由 (App Router)
- `src/components/` — React组件
- `src/server/routers/` — tRPC路由定义
- `src/lib/` — 共享工具函数
- `prisma/` — 数据库Schema和迁移

## 开发命令
- `npm run dev` — 启动开发服务器
- `npm test` — 运行单元测试
- `npm run test:e2e` — E2E测试
- `npm run lint` — ESLint检查
- `npx prisma studio` — 数据库可视化

## 编码规范
- Server Components优先，仅必要时用 "use client"
- tRPC路由按业务域拆分文件
- 组件使用shadcn/ui基础组件
- 类型定义放在 `src/lib/types/`
- 使用 `@/` 路径别名

## 禁止操作
- 不修改 prisma/schema.prisma（除非明确要求）
- 不删除现有tRPC路由
- 不直接操作数据库（用Prisma迁移）
- 不提交 .env 文件

## 提交规范
- 格式: type(scope): description
- 类型: feat/fix/refactor/test/docs/chore
- 示例: feat(auth): add OAuth2 login support

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npm test*)",
      "Bash(npx prisma *)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git add *)",
      "Read",
      "Write(src/**)",
      "Write(tests/**)",
      "Edit",
      "Glob",
      "Grep"
    ],
    "deny": [
      "Bash(sudo*)",
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Bash(npm publish*)",
      "Bash(npx prisma migrate reset*)",
      "Write(.env*)",
      "Write(prisma/schema.prisma)",
      "Write(*.key)",
      "Write(*.pem)"
    ]
  },
  "env": {
    "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/saas_dev"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cd \"$CLAUDE_PROJECT_DIR\" && npm run lint --quiet 2>&1 | tail -5 || true"
          }
        ]
      }
    ]
  }
}

# 前端模块规范

## 组件开发
- 使用 Server Components 为默认
- 客户端交互用 "use client" 标记
- UI组件基于 shadcn/ui，放在 components/ui/
- 业务组件放在 components/ 对应目录

## 样式
- Tailwind CSS utility-first
- 不写自定义CSS文件
- 响应式设计: mobile-first (sm → md → lg)

## 状态管理
- Server state: tRPC query hooks
- Client state: React useState/useReducer
- URL state: nuqs 库
- 不使用 Redux 或 Zustand

.env
.env.local
.env.production
*.pem
*.key
*.secret
node_modules/
.next/
coverage/

# 启动Claude Code
claude

# 在会话中验证
> 你能看到我的项目结构吗？CLAUDE.md加载了吗？

# 预期: Claude会引用CLAUDE.md中的信息，并了解项目结构

# 测试权限: 让Claude尝试执行被deny的操作
> 请运行 sudo apt update

# 预期: 被自动拒绝，不会弹出确认

# 测试环境变量
> 打印 DATABASE_URL 环境变量

# 预期: 显示配置中的值

# 1. 验证JSON语法
jq . ~/.claude/settings.json
jq . .claude/settings.json

# 2. 查看Claude Code版本
claude --version

# 3. 检查配置加载情况
claude config list

# 4. 查看当前生效的所有配置
claude config get

# 5. 清除缓存重新加载
rm -rf .claude/cache/

flowchart TB
    Start["团队成员克隆项目"] --> A["运行 setup-claude.sh"]
    A --> B["配置 .env 个人环境变量"]
    B --> C["启动 claude"]
    C --> D{"Claude Code<br/>加载配置"}

    D --> E["读取 Enterprise 策略"]
    D --> F["读取 Managed 配置"]
    D --> G["读取 User settings.json"]
    D --> H["读取 Project settings.json"]
    D --> I["读取 Local settings.json"]
    D --> J["读取 CLAUDE.md"]

    E & F & G & H & I & J --> K["合并配置<br/>（高优先级覆盖低优先级）"]
    K --> L["初始化会话"]

    L --> M["开发者与Claude协作"]
    M --> N{"Claude请求<br/>执行工具"}

    N --> O["PreToolUse Hook"]
    O --> P{"权限检查"}
    P -->|"Allow"| Q["执行工具"]
    P -->|"Deny"| R["拒绝并提示"]
    P -->|"Ask"| S["弹窗确认"]
    S -->|"批准"| Q
    S -->|"拒绝"| R

    Q --> T["PostToolUse Hook"]
    T --> U["继续协作"]

    M --> V{"任务完成?"}
    V -->|"是"| W["Stop Hook<br/>（自动测试+lint）"]
    V -->|"否"| M

    style Start fill:#e8f5e9
    style K fill:#fff9c4
    style Q fill:#c8e6c9
    style R fill:#ffcdd2
    style W fill:#e1bee7