Claude Code 项目级深度配置解析

dctc_shouhuzhe

Claude Code 作为 Anthropic 官方的命令行 AI 编程助手，其真正的工程价值并不在终端里"聊几句"，而在于项目级配置体系。`.claude/` 目录、`CLAUDE.md` 记忆文件、`settings.json` 权限矩阵、Slash Commands、Subagents、Hooks、MCP 服务器——这七层机制共同构成了一个可被 Git 追踪、可被团队共享、可被 CI 集成的开发基础设施。本文从配置层级、文件语义、字段优先级三个维度做一次系统拆解。

## 一、配置文件的优先级体系

Claude Code 的配置按覆盖范围由窄到宽分为五层，高优先级覆盖低优先级：

| 层级 | 路径 | 适用场景 | 是否入 Git |
|------|------|---------|-----------|
| CLI 参数 | `--model`、`--permission-mode` | 临时调试 | 否 |
| 企业托管 | `managed-settings.json` | 公司统一管控 | 由 MDM 推送 |
| 项目本地 | `.claude/settings.local.json` | 个人覆盖团队设置 | 否（gitignore） |
| 项目共享 | `.claude/settings.json` | 团队约定 | 是 |
| 用户全局 | `~/.claude/settings.json` | 个人习惯 | 否 |

关键工程经验：所有团队成员应当遵守的规则放在 `settings.json`；个人临时实验放在 `settings.local.json`；CI 环境通过 CLI 参数或环境变量注入。这与 ESLint、Prettier 的 `.eslintrc` + `.eslintrc.local` 模式一脉相承。

合并规则的解析顺序遵循"窄作用域优先"：CLI 参数 → 企业托管 → 项目本地 → 项目共享 → 用户全局。也就是说，如果用户在 `settings.local.json` 中把 `model` 改成 `claude-haiku-4`，再去触发项目共享的 `settings.json` 里的 `claude-sonnet-4-5`，实际生效的是前者。这一机制既保障了个人灵活度，又防止了"绕过项目红线"的可能性——因为 deny 规则无论作用域都会阻断。

实操建议：把团队级 deny 规则（如禁止 `Bash(rm -rf:*)`、禁止 `Write(/etc/)`）从 `settings.json` 抽出到 `managed-settings.json`，由 IT 通过 MDM 强制下发。即使本地 `settings.local.json` 改写也无法绕过，这是企业级部署的关键护栏。

## 二、CLAUDE.md：项目记忆的承载体

`CLAUDE.md` 是 Claude Code 启动时自动加载的项目级上下文，类似于 Cursor 的 `.cursorrules` 或 Aider 的 `CONVENTIONS.md`。它的加载规则有三条必须掌握：

1. 多层级自动加载：从当前工作目录向上递归读取所有 `CLAUDE.md`，直至 Git 仓库根。这种设计借鉴了 Git 自身的 `.gitignore` 递归语义，但语义相反——`.gitignore` 是越近越优先，`CLAUDE.md` 是"全部加载然后聚合"。Monorepo 项目可以在 `apps/web/CLAUDE.md`、`packages/shared/CLAUDE.md` 各自写子项目规范。
2. 本地覆盖文件：`CLAUDE.local.md` 优先级高于 `CLAUDE.md`，且默认 gitignore，用于个人本地补充。
3. 外部文件导入：通过 `@path/to/file` 语法引入其他文档，避免 CLAUDE.md 单文件臃肿。

一个生产级的 `CLAUDE.md` 模板应包含以下结构化字段：

```markdown
## Build & Test
- 包管理器：pnpm 9.x（不要混用 npm/yarn）
- 测试命令：`pnpm test --run`，禁止 watch 模式
- Lint：`pnpm lint --fix` 自动修复

## Architecture
- Monorepo 结构：apps/、packages/、services/
- 状态管理：Zustand（禁止 Redux）
- 路由：React Router v6 file-based

## Conventions
- 提交前必须跑 `pnpm typecheck`
- 不允许直接修改 packages/shared/src/types/
- API 文档在 docs/api/，使用 OpenAPI 3.1

## @docs/architecture.md
## @docs/deployment.md
```

工程经验：CLAUDE.md 的字符数应控制在 2000 字以内，过长的文件会挤占上下文窗口。复杂内容用 `@` 拆分成多个文档，让模型按需 `Read`。

进阶技巧：CLAUDE.md 支持 `<!-- SUBAGENT-ONLY -->` 注释块，只在 Subagent 上下文加载；支持 `<!-- USER-ONLY -->` 块，仅主代理可见。这让"通用规范"和"子代理专属指令"可以共存于同一份文档。此外，CLAUDE.md 的更新应当与代码同步走 PR 流程——配置即代码（Configuration as Code）的核心是 Reviewable，PR 中能 diff 出"为什么改了规范"远比口头传达更可追溯。

## 三、settings.json：权限与行为的中央控制

`.claude/settings.json` 是项目行为的中央开关。核心字段如下：

```json
{
  "permissions": {
    "allow": [
      "Bash(pnpm test:*)",
      "Bash(git diff:*)",
      "Read(/docs/)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(curl * | bash)",
      "Write(/etc/)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(npm publish:*)"
    ]
  },
  "model": "claude-sonnet-4-5",
  "env": {
    "NODE_ENV": "development",
    "CLAUDE_CODE_MAX_THINKING_TOKENS": "10000"
  },
  "hooks": {
    &quotreToolUse": [...],
    &quotostToolUse": [...]
  },
  "enabledMcpjsonServers": ["github", "postgres"]
}
```

权限系统的三个动作语义：allow 自动放行；deny 硬性拒绝（即使 ask 也不行）；ask 每次人工确认。规则匹配是最长前缀优先——`Bash(git push:*)` 会被精确匹配，而 `Bash(git *)` 不会越权匹配前者。建议把危险操作（如 `git push --force`、`rm`、`chmod 777`）显式列入 deny 而非 ask，避免"误触确认"导致的破坏。

权限矩阵的设计原则可以归纳为"三明治模型"：
- 下层（最宽松）：只读工具（Read、Grep、Glob）一律 allow。
- 中层（团队约定）：包管理器命令、测试命令、`git diff` 列入 allow，体现"约定俗成"。
- 上层（最严格）：发布、删除、远程推送、修改系统目录列入 deny 或 ask，把决策权留给人类。

这种分层让 80% 的高频操作零摩擦，剩下 20% 的高危操作有显式拦截。同时建议在 CI 中加一个 `claude-validate` 脚本，扫描 `settings.json` 是否包含 `*` 通配符 allow、是否缺失 `rm` deny、是否声明了 `enabledMcpjsonServers` 白名单——把权限配置本身也变成可 Lint 的对象。

## 四、自定义 Slash Commands：把高频操作工程化

`.claude/commands/` 目录下的每个 `.md` 文件就是一条斜杠命令。文件结构是 YAML frontmatter + Markdown prompt：

```markdown
---
description: 创建符合团队规范的 React 组件
argument-hint: <ComponentName>
allowed-tools: Read, Write, Bash(pnpm test:*)
model: claude-sonnet-4-5
---

请基于以下规范创建组件：
- 路径：apps/web/src/components/$ARGUMENTS/
- 文件：index.tsx、Component.test.tsx、Component.stories.tsx
- 必须使用 forwardRef
- 必须包含 a11y 属性

组件名：$ARGUMENTS
```

调用 `/create-component Button` 时，`$ARGUMENTS` 会被替换为 `Button`。`allowed-tools` 字段是关键的安全护栏——它限定该命令能调用的工具集，避免 prompt 注入导致越权。`model` 字段允许单条命令使用不同于全局的模型，例如日常审查用 Haiku 4 节省成本。

实战案例库：
- `/pr-review <branch>`：自动拉取分支 diff 并按团队 checklist 审查
- `/release <version>`：跑测试 + bump 版本 + 生成 changelog
- `/db-migrate <name>`：生成迁移文件 + 跑 dry-run

进阶用法：Slash Command 支持 `!` 前缀执行 shell 命令并把输出注入 prompt。例如 `!git log --oneline -10` 会把最近 10 条 commit 直接拼到 prompt 里，这种"动态上下文注入"特别适合做 `/standup`（自动汇总昨日 commit 和今日 TODO）、`/incident <id>`（拉取 Grafana 日志和告警时间线）。同时建议用 `argument-hint` 显式声明参数形式（如 `[--type=feat] <message>`），IDE 风格的提示让命令可发现性大幅提升。

## 五、Subagents：专业化代理的注册中心

`.claude/agents/` 是 Subagent 注册表，每个 `.md` 定义一个专业化子代理：

```markdown
---
name: code-reviewer
description: 审查代码变更，发现安全和性能问题
tools: Read, Grep, Glob
model: claude-sonnet-4-5
isolation: worktree
---

你是一名资深 code reviewer。审查变更时请：
1. 优先检查认证、授权、输入校验路径
2. 标注 N+1 查询、内存泄漏、并发竞态
3. 输出 Markdown 格式：严重程度 + 文件 + 行号 + 修复建议
```

Subagent 与主代理的隔离体现在三方面：工具白名单（不能调 Write）、模型独立（可指定）、工作区隔离（`isolation: worktree` 在 git worktree 中运行，避免污染主分支）。复杂工作流可由一个 Subagent 调用其他 Subagent，形成层级化执行图。

Subagent 设计的三条经验法则：
1. 单一职责：每个 Subagent 只做一件事——reviewer 只读不写、test-runner 只跑测试、doc-writer 只动 docs。SRP 在 AI 代理中同样适用，因为工具集是 Subagent 的"肌肉记忆"，混用会导致越权。
2. 可观测性：在 Subagent 的 prompt 末尾强制要求输出"做了什么 + 没做什么 + 遗留问题"，便于主代理整合和人类审计。
3. 成本意识：高频 Subagent（如 test-runner）配 Haiku 4 节省成本；关键决策（如 security-reviewer）才上 Sonnet 4.5 或 Opus。模型分层比单一大模型便宜 70% 以上。

## 六、Hooks：事件驱动的自动化

Hooks 把 Claude Code 的生命周期事件暴露给外部脚本，配置在 `settings.json` 的 `hooks` 字段：

```json
{
  "hooks": {
    &quotostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATHS",
            "timeout": 30
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): $CLAUDE_USER_PROMPT\" >> .claude/prompts.log"
          }
        ]
      }
    ]
  }
```

可用事件：`PreToolUse`、`PostToolUse`、`UserPromptSubmit`、`Stop`、`SubagentStop`、`Notification`。环境变量 `$CLAUDE_TOOL_NAME`、`$CLAUDE_FILE_PATHS`、`$CLAUDE_USER_PROMPT` 是钩子与 Claude Code 通信的标准通道。退出码语义：0 = 成功；2 = 阻断操作并把 stderr 作为反馈喂给模型；其他非零 = 警告不阻断。这是实现"自动 lint"、"自动跑测试"、"敏感词拦截"的官方机制。

Hook 的高阶玩法：
- PreToolUse 阻断敏感词：matcher `Bash`，command `grep -E "(secret|token|password)" <<< "$CLAUDE_TOOL_INPUT"`，命中时 `exit 2` 并把"检测到敏感词，请改用环境变量"喂给模型——这是低成本防泄漏方案。
- PostToolUse 自动跑相关测试：matcher `Edit`，command `pnpm test --related`——只跑被影响到的测试，节省 CI 时间。

---

【标签】
Thinkpad, IBM, X1 Carbon, AI开发, Ollama部署, 本地大语言模型, VSCode配置, 华强北, 选购指南

【相关阅读】
- Thinkpad T14 深度评测：商务本的性能极限在哪里
- OpenClaw多模型集成配置指南
- 华强北Thinkpad港版购买防坑指南