第 5 章 配置体系

用户4018993342284
3 阅读5分钟

第 5 章 配置体系

← 上一章 | 下一章 →

本章目标

  • 理解 Claude Code 的三级配置架构（全局 / 用户 / 项目）
  • 掌握 settings.json 的常用参数及其作用
  • 学会编写高质量的 CLAUDE.md
  • 理解 .claude 目录的完整结构和各文件用途
  • 能根据项目需求定制 Claude Code 行为

5.1 三级配置架构

Claude Code 的配置分为三个层级，逐级合并，形成最终生效的配置。

flowchart TD
    subgraph 优先级：低 → 高
        A[全局级配置<br/>~/.claude/settings.json] --> B[用户级配置<br/>~/.claude/settings.local.json]
        B --> C[项目级配置<br/>.claude/settings.json]
    end

    C --> D[最终生效配置]
层级路径作用范围典型用途
全局级~/.claude/settings.json所有项目通用模型选择、全局权限规则、个人偏好
用户级~/.claude/settings.local.json所有项目个人密钥、本地调试开关（不提交到版本控制）
项目级.claude/settings.json当前项目项目特定的权限、工具配置、团队约定

合并规则：

  • 数组类型的配置项（如权限规则）是叠加的
  • 标量类型的配置项（如模型选择）是覆盖的 —— 项目级覆盖用户级覆盖全局级
  • 设置某个值为 null 表示"清除"该配置，回退到下一级

⚠️ settings.local.json 默认不应加入版本控制。它用于存放个人敏感信息（API Key、本地路径等）。

5.2 settings.json 参数详解

以下是 settings.json 中主要的配置项分类说明。

模型相关

{
  "model": "claude-sonnet-4-6",
  "modelOverrides": {
    "fast": "claude-opus-4-7"
  }
}
参数类型说明
modelstring默认使用的模型 ID
modelOverridesobject针对特定场景的模型覆盖，如 fast 模式使用的模型

权限相关

{
  "permissions": {
    "allow": ["Read(./src/**)"],
    "deny": ["Read(./.env)", "Read(./secrets/**)"],
    "defaultMode": "default"
  }
}
参数类型说明
permissions.allowstring[]自动允许的规则列表
permissions.denystring[]始终拒绝的规则列表
permissions.defaultModestring默认权限模式，可选 default / acceptEdits / plan / bypassPermissions

⚠️ bypassPermissions 模式会跳过所有审批环节，仅应在完全受控的环境（如 CI/CD）中使用。

Hook 相关

{
  "hooks": {
    "SessionStart": [
      { "matcher": "*", "command": "echo 'Claude Code started at $(date)'" }
    ]
  }
}

详见第 8 章 Hook 系统。

MCP 相关

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-filesystem"]
    }
  }
}

详见第 11 章 MCP 协议与集成。

外观与行为

{
  "theme": "dark",
  "showTokensCounter": true,
  "autoCompactEnabled": true,
  "continueOnSameLine": true
}
参数类型说明
themestring主题：dark、light、system
showTokensCounterboolean是否显示 Token 用量统计
autoCompactEnabledboolean是否启用上下文自动压缩
continueOnSameLineboolean是否允许回复与消息同行显示

环境变量

{
  "env": {
    "NODE_ENV": "development",
    "HTTP_PROXY": "http://proxy:8080"
  }
}

通过 env 字段为 Claude Code 的执行环境注入环境变量。项目级配置中的 env 会与系统环境合并。

5.3 CLAUDE.md 深入

在第 3 章我们介绍了 CLAUDE.md 的基本概念，这里进一步深入编写技巧。

CLAUDE.md 应该包含什么

# CLAUDE.md

## 项目简介
一行描述项目做什么、为谁做。

## 技术栈
- 运行时：Node.js 20
- 语言：TypeScript 5.x (strict mode)
- 框架：Express 4.x
- 数据库：PostgreSQL 15 + Drizzle ORM
- 缓存：Redis 7

## 项目约定

### 代码风格
- 使用 Prettier + ESLint，配置在项目根目录
- 函数参数超过 3 个时使用对象参数
- 异步函数统一返回 Result<T, Error> 类型

### 文件组织
- 新 API 路由添加到 src/routes/
- Service 层放在 src/services/，一个 service 一个文件
- 类型定义放在 src/types/，按领域分文件

### 测试要求
- Service 层函数必须有单元测试
- API 路由需要有集成测试
- 测试文件与源文件同目录，命名 xxx.test.ts

## 禁止事项
- 不要修改 src/migrations/ 目录
- 不要提交 .env 文件
- 不要使用 any 类型
- 不要安装未经审批的 npm 包

什么不该写进 CLAUDE.md

不该写理由
完整的 API 文档太冗长，用单独的 docs/ 文件
业务逻辑详解Claude 能通过读代码理解
个人偏好（如"我不喜欢 for 循环"）这是你的偏好，不是项目约定
TODO 列表用 Git Issues 管理
安装步骤这些属于 README.md

💡 判断标准：如果一段话描述的是"项目规则"（每个人都应当遵守），放进 CLAUDE.md；如果描述的是"你应该做什么"（任务），不要放 —— 在对话中说。

CLAUDE.md 的位置

Claude Code 会按以下顺序查找 CLAUDE.md：

  1. 项目根目录 ./CLAUDE.md
  2. 项目 .claude/CLAUDE.md
  3. 用户目录 ~/.claude/CLAUDE.md

多个存在的 CLAUDE.md 内容会合并。通常建议放在项目根目录，便于团队成员发现和维护。

CLAUDE.md 的维护

  • 代码审查时：如果团队采纳了新约定，同步更新 CLAUDE.md
  • 新人入职时：让新人读 CLAUDE.md 了解项目规范，也让他们补充遗漏
  • 迭代时：删除过时的规则，保持精简

5.4 .claude 目录结构全览

项目根目录/
├── CLAUDE.md              # 项目上下文描述（可选，也可放在此处）
└── .claude/
    ├── settings.json       # 项目级配置
    ├── settings.local.json # 本地配置（不提交到版本控制）
    ├── CLAUDE.md           # 项目上下文描述（可选）
    ├── scheduled_tasks.json # 持久化定时任务（由 CronCreate 自动管理）
    └── memory/             # Memory 系统持久化目录（详见第 15 章）
        ├── MEMORY.md       # 记忆索引
        └── *.md            # 各类型记忆文件
文件 / 目录作用是否提交 Git
CLAUDE.md (根目录)项目上下文描述是
.claude/settings.json项目级配置是（团队共享）
.claude/settings.local.json本地个人配置否
.claude/CLAUDE.md项目上下文（备选位置）是
.claude/scheduled_tasks.json定时任务持久化视团队策略
.claude/memory/Memory 系统数据否（个人知识库）

⚠️ .claude/settings.local.json 和 .claude/memory/ 应加入 .gitignore。

5.5 配置实战：定制你的 Claude Code

场景一：前端项目

{
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": [
      "Read(./src/**)",
      "Edit(./src/**)",
      "Bash(npm test)",
      "Bash(npm run dev)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Read(./.env*)",
      "Read(./node_modules/**)"
    ]
  }
}

CLAUDE.md 要点：

  • 使用 React 18 + TypeScript + Tailwind CSS
  • 组件命名使用 PascalCase，文件使用 kebab-case
  • 状态管理使用 Zustand

场景二：后端 API 项目

{
  "model": "claude-opus-4-7",
  "permissions": {
    "allow": [
      "Read(./src/**)",
      "Edit(./src/**)",
      "Bash(npm test)",
      "Bash(npx jest -- --testPathPattern=)"
    ],
    "deny": [
      "Read(./src/migrations/**)",
      "Bash(*production*)"
    ]
  }
}

CLAUDE.md 要点：

  • NestJS + PostgreSQL + Prisma
  • 所有 API 返回统一的 { code, data, message } 格式
  • 数据库迁移文件不可修改，只能读取

💡 配置是活的。不要一次写死所有规则 —— 先在对话中手动审批几次，观察哪些操作反复出现，再把它们加入 allow。配置是使用中"长出来的"，不是一次性设计出来的。

本章要点回顾

  • Claude Code 配置分三级：全局（~/.claude/）→ 用户（settings.local.json）→ 项目（.claude/），优先级逐级升高
  • settings.json 控制模型、权限、Hook、MCP、外观行为等各个方面
  • CLAUDE.md 写的是项目规则和约定，不是教程、不是 TODO、不是个人偏好
  • .claude 目录中，settings.json 和 CLAUDE.md 应提交版本控制，settings.local.json 和 memory/ 不应提交
  • 好的配置是"长出来的"：先用 ask 模式观察高频操作，再逐步加入 allow

← 上一章 | 下一章 →

avatar
文章
阅读
粉丝