# Claude Code配置体系全实战：五层优先级到团队标准化
## 概述
本教程系统讲解Claude Code的五层配置体系（Enterprise → Managed → User → Project → Local），手把手带你从零构建一套适合个人和团队的完整配置方案。涵盖settings.json全字段解析、CLAUDE.md编写范式、权限模型设计、环境变量管理、Hooks生命周期，以及团队级标准化策略。适合已在日常使用Claude Code但希望从"能用"进化到"好用"的开发者和团队负责人。
## 前置条件
- 已安装 Claude Code CLI（`npm install -g @anthropic-ai/claude-code`）
- Node.js ≥ 18.0
- 基本熟悉终端操作和JSON配置文件
- 至少有一个正在开发的项目目录
---
## 第一章：理解五层配置优先级
### 1.1 为什么配置体系如此重要
Claude Code不是一个"装上就能用"的简单工具。它的行为——从模型选择到文件访问权限，从输出风格到安全边界——全部由配置系统驱动。如果你不理解这套五层优先级体系，就会遇到这些典型问题：
- "为什么我改了settings.json但不生效？"
- "团队里每个人都在重复配置同样的规则"
- "Claude总想执行危险命令，每次都要手动批准"
- "不同项目的编码规范不同，怎么自动切换？"
Claude Code的配置系统采用**分层覆盖（Layer Override）**模型，类似于CSS的层叠规则：高优先级层覆盖低优先级层的同名配置。
### 1.2 五层优先级详解
```mermaid
graph TD
A["Enterprise
企业级策略
~/.claude/settings.json
（最低优先级）"] --> B["Managed
MDM/注册表托管
managed-settings.json"]
B --> C["User
用户全局
~/.claude/settings.json"]
C --> D["Project
项目共享
.claude/settings.json"]
D --> E["Local
项目本地
.claude/settings.local.json
（最高优先级）"]
style A fill:#e8f5e9
style B fill:#fff3e0
style C fill:#e3f2fd
style D fill:#fce4ec
style E fill:#f3e5f5
```
**优先级从低到高：**
| 层级 | 文件路径 | 作用域 | 是否提交Git | 典型用途 |
|------|---------|--------|------------|---------|
| Enterprise | `~/.claude/settings.json` | 全局 | 否 | 组织安全策略、合规要求 |
| Managed | MDM配置文件/注册表 | 全局 | 否 | IT部门强制策略，不可用户修改 |
| User | `~/.claude/settings.json` | 个人全局 | 否 | 个人偏好、常用MCP服务器 |
| Project | `/.claude/settings.json` | 项目级 | **是** | 团队共享规则、项目特定配置 |
| Local | `/.claude/settings.local.json` | 项目本地 | 否（加入.gitignore） | 个人临时配置、调试开关 |
**关键规则：**
- 同名字段，高优先级**覆盖**低优先级
- 数组类型字段（如`permissions`），各层**合并**
- `deny`规则具有**绝对否决权**——即使更高层Allow了，任何层的Deny都会生效
### 1.3 实操：定位你的配置文件
```bash
# 查看所有配置文件的位置
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 Code会话（`/clear`或退出重新进入）
> - 检查JSON语法是否合法（用`jq . < settings.json`验证）
---
## 第二章：settings.json全字段解析
### 2.1 核心字段一览
```jsonc
// .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"]
}
]
}
}
```
### 2.2 权限规则语法详解
权限规则使用**glob模式匹配**，语法简洁但功能强大：
```
格式: ToolName(pattern)
示例: Bash(npm test*)
Read(*.ts)
Write(src/**)
```
**三大匹配规则：**
| 规则 | 含义 | 示例 |
|------|------|------|
| `*` | 匹配任意非路径分隔符字符 | `Bash(npm *)` → 匹配 `npm test`、`npm run build` |
| `**` | 匹配任意层级路径 | `Read(src/**)` → 匹配 src 下所有文件 |
| `无pattern` | 匹配该工具的所有用法 | `Read` → 允许/禁止读取任何文件 |
**权限决策流程：**
```mermaid
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
```
### 2.3 实战：为不同项目类型配置权限
**前端项目配置：**
```json
// 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项目配置：**
```json
// 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.md编写范式
### 3.1 CLAUDE.md的四层定位
CLAUDE.md是Claude Code的"持久化指令文件"——它在每次会话开始时自动加载，告诉Claude Code关于项目的一切背景信息。它可以存在于四个位置：
```
~/.claude/CLAUDE.md ← 全局个人指令（所有项目生效）
/CLAUDE.md ← 项目根目录（团队共享，提交Git）
/.claude/CLAUDE.md ← 项目.claude目录（同上，效果相同）
/src/CLAUDE.md ← 子目录级（进入该目录时生效）
```
### 3.2 CLAUDE.md的最佳结构
```markdown
# 项目名称
## 技术栈
- 语言: 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`
```
### 3.3 子目录级CLAUDE.md示例
```
project/
├── CLAUDE.md ← 全项目通用规则
├── src/
│ ├── CLAUDE.md ← 前端开发特定规则
│ └── components/
│ └── CLAUDE.md ← 组件开发规范
└── api/
└── CLAUDE.md ← API开发特定规则
```
**`api/CLAUDE.md` 内容示例：**
```markdown
# 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参数化，禁止字符串拼接
- 敏感字段(密码等)永不出现在响应中
```
### 3.4 实战：为团队项目编写CLAUDE.md
**步骤1：** 在项目根目录创建 `CLAUDE.md`
**步骤2：** 按以下模板填充内容：
```markdown
# [项目名]
## 一句话简介
[用一句话描述这个项目做什么]
## 技术栈
[列出主要技术]
## 项目结构
[用树状图说明目录含义]
## 开发命令
- 启动开发: `npm run dev`
- 运行测试: `npm test`
- 代码检查: `npm run lint`
- 构建: `npm run build`
## 编码规范
[3-5条最重要的规则]
## 禁止操作
[列出绝对不能做的事情]
## 提交规范
[Git commit消息格式]
```
**步骤3：** 提交到Git
```bash
git add CLAUDE.md
git commit -m "Add CLAUDE.md for project context"
```
> **常见问题：** CLAUDE.md太长会不会浪费Token？
> 会的。建议控制在50行以内，只写Claude Code无法从代码推断的信息。技术栈、项目结构这些"可以通过代码发现的"尽量精简，重点放在"约定和禁止事项"上。
---
## 第四章：环境变量管理
### 4.1 三种环境变量注入方式
```mermaid
flowchart LR
A["方式1: settings.json
env字段"] --> D["会话内生效"]
B["方式2: .env文件
项目根目录"] --> D
C["方式3: Shell环境
export/export命令"] --> D
style A fill:#e3f2fd
style B fill:#e8f5e9
style C fill:#fff3e0
```
**方式1：settings.json的env字段（推荐用于项目共享变量）**
```json
{
"env": {
"DATABASE_URL": "postgresql://localhost:5432/myapp_dev",
"REDIS_URL": "redis://localhost:6379",
"LOG_LEVEL": "debug"
}
}
```
**方式2：Shell环境变量（适合敏感信息）**
```bash
# 在 .bashrc 或 .zshrc 中设置
export ANTHROPIC_API_KEY="sk-ant-..."
export GITHUB_PERSONAL_TOKEN="ghp_..."
```
**方式3：在settings.json中引用环境变量（安全写法）**
```json
{
"env": {
"API_KEY": "${MY_API_KEY}"
}
}
```
这样settings.json可以安全提交Git，而实际值从Shell环境中读取。
### 4.2 实战：多环境配置方案
```
project/
├── .claude/
│ ├── settings.json ← 基础配置（共享）
│ ├── settings.local.json ← 个人覆盖（不提交）
│ └── env.sh ← 环境变量加载脚本
├── .env.example ← 环境变量模板（提交）
├── .env ← 实际环境变量（不提交）
└── .gitignore ← 忽略 .env 和 settings.local.json
```
**`.env.example` 模板：**
```bash
# 复制此文件为 .env 并填入实际值
ANTHROPIC_API_KEY=sk-ant-your-key-here
DATABASE_URL=postgresql://localhost:5432/myapp_dev
REDIS_URL=redis://localhost:6379
```
**`.gitignore` 追加：**
```
.env
.claude/settings.local.json
```
---
## 第五章：Hooks生命周期自动化
### 5.1 Hooks是什么
Hooks是Claude Code的事件钩子系统——它在特定生命周期事件触发时执行你预定义的Shell命令。可以理解为"AI编码的CI/CD管道"。
**五大生命周期事件：**
| 事件 | 触发时机 | 典型用途 |
|------|---------|---------|
| `PreToolUse` | 工具执行前 | 代码格式化、安全检查、阻止危险操作 |
| `PostToolUse` | 工具执行后 | 自动lint、触发通知、日志记录 |
| `Notification` | Claude发送通知时 | 集成Slack/Teams通知 |
| `Stop` | Claude完成任务时 | 自动运行测试、生成变更摘要 |
| `SubagentStop` | 子Agent完成时 | 聚合子任务结果 |
### 5.2 实战Hooks配置
```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环境变量：**
| 变量 | 说明 |
|------|------|
| `$CLAUDE_TOOL_NAME` | 正在使用的工具名 |
| `$CLAUDE_TOOL_INPUT` | 工具输入（JSON格式） |
| `$CLAUDE_FILE_PATH` | 文件路径（仅Write/Edit/Read） |
| `$CLAUDE_SESSION_ID` | 当前会话ID |
**退出码语义：**
| 退出码 | 含义 | PreToolUse效果 |
|--------|------|---------------|
| 0 | 成功 | 继续执行工具 |
| 2 | 阻止 | 取消工具执行 |
| 其他 | 错误 | 记录警告，继续执行 |
### 5.3 常见Hooks场景
**场景1：自动格式化（写入文件后）**
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null" }]
}
]
}
}
```
**场景2：安全审计（记录所有Bash命令）**
```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "echo \"[$(date -Iseconds)] $CLAUDE_TOOL_INPUT\" >> .claude/bash-audit.log" }]
}
]
}
}
```
**场景3：任务完成时自动测试**
```json
{
"hooks": {
"Stop": [
{
"hooks": [{ "type": "command", "command": "cd $CLAUDE_PROJECT_DIR && npm test 2>&1 | tail -5" }]
}
]
}
}
```
---
## 第六章：团队标准化策略
### 6.1 配置分层原则
```mermaid
graph TB
subgraph "组织层"
A["Enterprise Policy
安全底线、合规要求
不可被用户覆盖"]
end
subgraph "团队层"
B["Project CLAUDE.md
编码规范、项目结构
提交到Git，全员共享"]
C["Project settings.json
共享权限、MCP服务器
提交到Git，全员共享"]
end
subgraph "个人层"
D["User CLAUDE.md
个人偏好、工作习惯
仅在个人机器"]
E["Local settings
调试开关、临时配置
不提交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
```
**核心原则：**
1. **团队共享的写Project层**（提交Git）
2. **个人偏好的写User/Local层**（不提交）
3. **安全策略写Enterprise层**（IT管理）
4. **Deny规则可以写在任何层**（绝对否决权）
### 6.2 团队配置模板
**模板项目结构：**
```
team-project/
├── CLAUDE.md ← 项目背景和规范
├── .claude/
│ ├── settings.json ← 团队共享配置
│ ├── settings.local.json ← 个人覆盖（.gitignore）
│ └── skills/ ← 团队自定义Skills
│ └── team-workflow.md
├── .claudeignore ← 排除敏感文件
├── .env.example ← 环境变量模板
└── .gitignore ← 忽略个人配置
```
**团队共享的 `.claude/settings.json`：**
```json
{
"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" }
]
}
]
}
}
```
**团队共享的 `CLAUDE.md`：**
```markdown
# 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端点
- 不要修改数据库迁移文件
- 不要在代码中硬编码密钥或密码
```
### 6.3 新成员入职自动化
**一键入职脚本 `setup-claude.sh`：**
```bash
#!/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' 开始使用"
```
---
## 第七章：实战案例——全栈项目的完整配置
### 7.1 项目背景
假设我们要为一个全栈SaaS项目配置Claude Code环境。技术栈：Next.js 15 + tRPC + Prisma + PostgreSQL。
### 7.2 目录结构
```
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
```
### 7.3 各配置文件完整内容
**`CLAUDE.md`（项目根）：**
```markdown
# 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
```
**`.claude/settings.json`（团队共享）：**
```json
{
"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"
}
]
}
]
}
}
```
**`src/CLAUDE.md`（前端模块级）：**
```markdown
# 前端模块规范
## 组件开发
- 使用 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
```
**`.claudeignore`：**
```
.env
.env.local
.env.production
*.pem
*.key
*.secret
node_modules/
.next/
coverage/
```
### 7.4 验证配置是否生效
```bash
# 启动Claude Code
claude
# 在会话中验证
> 你能看到我的项目结构吗？CLAUDE.md加载了吗？
# 预期: Claude会引用CLAUDE.md中的信息，并了解项目结构
# 测试权限: 让Claude尝试执行被deny的操作
> 请运行 sudo apt update
# 预期: 被自动拒绝，不会弹出确认
# 测试环境变量
> 打印 DATABASE_URL 环境变量
# 预期: 显示配置中的值
```
---
## 第八章：配置排错指南
### 8.1 常见问题速查表
| 症状 | 可能原因 | 解决方案 |
|------|---------|---------|
| 配置修改不生效 | 编辑了错误层级 | 检查五层优先级，确认编辑了正确的文件 |
| 权限规则不生效 | JSON语法错误 | `jq . < settings.json` 验证语法 |
| CLAUDE.md没加载 | 文件位置错误 | 确保在项目根目录启动Claude Code |
| MCP服务器连接失败 | command路径问题 | 使用 `npx -y` 确保自动安装依赖 |
| Hook不触发 | matcher语法错误 | matcher支持正则，检查转义 |
| 环境变量为空 | 未引用Shell环境 | 使用 `${VAR}` 语法引用而非直接写值 |
### 8.2 调试技巧
```bash
# 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/
```
---
## 完整工作流程图
```mermaid
flowchart TB
Start["团队成员克隆项目"] --> A["运行 setup-claude.sh"]
A --> B["配置 .env 个人环境变量"]
B --> C["启动 claude"]
C --> D{"Claude Code
加载配置"}
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["合并配置
（高优先级覆盖低优先级）"]
K --> L["初始化会话"]
L --> M["开发者与Claude协作"]
M --> N{"Claude请求
执行工具"}
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
（自动测试+lint）"]
V -->|"否"| M
style Start fill:#e8f5e9
style K fill:#fff9c4
style Q fill:#c8e6c9
style R fill:#ffcdd2
style W fill:#e1bee7
```
---
## 延伸阅读
1. **Anthropic官方文档 - Settings**: [code.claude.com/docs/en/settings](https://code.claude.com/docs/en/settings) — Claude Code配置系统的官方参考
2. **Anthropic官方博客 - Using CLAUDE.md files**: [claude.com/blog/using-claude-md-files](https://claude.com/blog/using-claude-md-files) — CLAUDE.md文件的最佳实践
3. **Claude Code权限配置文档**: [code.claude.com/docs/en/permissions](https://code.claude.com/docs/en/permissions) — 权限系统详细说明
4. **Claude Code Hooks参考**: [code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks) — Hooks事件的完整规范
5. **shanraisshan/claude-code-best-practice**: [github.com/shanraisshan/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice) — 社区最佳实践合集
## 参考来源
1. [Claude Code Settings - 官方文档](https://code.claude.com/docs/en/settings) — 五层配置体系的权威说明，包含所有字段定义和优先级规则
2. [Claude Code settings.json 配置详解：5 层优先级](https://blog.vincentqiao.com/claude-code-settings-intro/) — 中文社区对五层优先级的深度解析，包含大量示例
3. [Using CLAUDE.md files - Anthropic官方博客](https://claude.com/blog/using-claude-md-files) — CLAUDE.md编写的官方指南和推荐范式
4. [Claude Code 配置工程实战 - AI编程实战笔记](https://lukaxiya.github.io/coding-agent-blog/posts/claude-md-configuration-guide/) — CLAUDE.md、settings.json、Skills、MCP的分层策略
5. [Claude Code Session Management & 1M Context - Anthropic](https://claude.com/blog/using-claude-code-session-management-and-1m-context) — 会话管理和上下文窗口策略的官方博客
## 训练营适用性评估
| 维度 | 说明 |
|------|------|
| **适合训练营类型** | AI编码工具入门营、团队效率提升营、DevOps工程化营 |
| **预计教学时长** | 3小时（讲解1.5h + 动手实践1.5h） |
| **难度等级** | ⭐⭐☆☆☆（初级到中级） |
| **前置要求** | 已安装Claude Code，有至少一个开发项目 |
| **实操占比** | 60%（大量配置文件编写和验证） |
| **最佳分组方式** | 2-3人小组，每组一个模拟项目 |
> [!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 等场景全覆盖。
