说真的，2026 年这一波 AI 编程工具混战，已经从"谁聊天更溜"卷到"谁能进 CI、谁能管权限、谁能被 PR Review"。Cursor 2.x 把 Composer 模式摆上桌，Cline 把开源 Agent 做到 VS Code 里，Aider 死守终端党的 git-aware 阵地，而 Anthropic 官方的 Claude Code 则走了一条"配置即代码"的路子——把 .claude/ 目录、CLAUDE.md 记忆文件、settings.json 权限矩阵、Slash Commands、Subagents、Hooks、MCP 服务器这七层机制全部做成了可被 Git 追踪、可被团队共享、可被 CI 集成的工程基础设施。
截至 2026 年 8 月，本文所引用的 Claude Code 版本以官方稳定版为准，涉及的模型包括 Claude Sonnet 4.5、Claude Haiku 4 以及 Claude Opus 系列。如果你在用的是更早的版本，文中部分字段名可能略有差异，建议升级后再按本文操作。下面我从配置层级、文件语义、字段优先级三个维度做一次系统拆解，并补齐原版遗漏的 MCP 一层与几个常见踩坑点。
一、配置文件的优先级体系
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。它的加载规则有三条必须掌握：
多层级自动加载： 从当前工作目录向上递归读取所有 CLAUDE.md，直至 Git 仓库根。这种设计借鉴了 Git 自身的 .gitignore 递归语义，但语义相反——.gitignore 是越近越优先，CLAUDE.md 是"全部加载然后聚合"。Monorepo 项目可以在 apps/web/CLAUDE.md、packages/shared/CLAUDE.md 各自写子项目规范。本地覆盖文件： CLAUDE.local.md 优先级高于 CLAUDE.md，且默认 gitignore，用于个人本地补充。外部文件导入： 通过 @path/to/file 语法引入其他文档，避免 CLAUDE.md 单文件臃肿。
一个生产级的 CLAUDE.md 模板应包含以下结构化字段（这份模板在多个团队验证过，可直接复用）：
## 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 支持
三、settings.json：权限与行为的中央控制
.claude/settings.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": {
"PreToolUse": [...],
"PostToolUse": [...]
},
"enabledMcpjsonServers": ["github", "postgres"]
}
权限系统的三个动作语义：allow 自动放行；deny 硬性拒绝（即使 ask 也不行）；ask 每次人工确认。规则匹配是最长前缀优先——Bash(git push:*) 会被精确匹配，而 Bash(git *) 不会越权匹配前者。建议把危险操作（如 git push --force、rm、chmod 777）显式列入 deny 而非 ask，避免"误触确认"导致的破坏。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：
---
description: 创建符合团队规范的 React 组件
argument-hint:
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 节省成本，关键决策才上 Sonnet 4.5。
实战案例库：
/pr-review ：自动拉取分支 diff 并按团队 checklist 审查/release ：跑测试 + bump 版本 + 生成 changelog/db-migrate ：生成迁移文件 + 跑 dry-run
进阶用法：Slash Command 支持 ! 前缀执行 shell 命令并把输出注入 prompt。例如 !git log --oneline -10 会把最近 10 条 commit 直接拼到 prompt 里，这种"动态上下文注入"特别适合做 /standup（自动汇总昨日 commit 和今日 TODO）、/incident （拉取 Grafana 日志和告警时间线）。同时建议用 argument-hint 显式声明参数形式（如 [--type=feat] ），IDE 风格的提示让命令可发现性大幅提升。! 前缀本身是个有安全边界的特性——shell 输出是"数据"而非"指令"，Claude Code 不会把它的内容当 prompt 执行，这一点比裸的 RAG 注入稳得多。
五、Subagents：专业化代理的注册中心
.claude/agents/ 是 Subagent 注册表，每个 .md 定义一个专业化子代理：
---
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 设计的三条经验法则（我自己踩过坑后总结的，实操可落地）：
单一职责： 每个 Subagent 只做一件事——reviewer 只读不写、test-runner 只跑测试、doc-writer 只动 docs。SRP 在 AI 代理中同样适用，因为工具集是 Subagent 的"肌肉记忆"，混用会导致越权。可观测性： 在 Subagent 的 prompt 末尾强制要求输出"做了什么 + 没做什么 + 遗留问题"，便于主代理整合和人类审计。成本意识： 高频 Subagent（如 test-runner）配 Haiku 4 节省成本；关键决策（如 security-reviewer）才上 Sonnet 4.5 或 Opus。模型分层比单一大模型便宜非常多，但具体比例取决于调用量和上下文长度，建议团队跑一周做账单回归。
六、Hooks：事件驱动的自动化
Hooks 把 Claude Code 的生命周期事件暴露给外部脚本，配置在 settings.json 的 hooks 字段：
{
"hooks": {
"PostToolUse": [
{
"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 时间。
七、MCP 服务器：模型与外部世界的连接层
这一层在很多教程里被一笔带过，但它正是 Claude Code 能调 GitHub、能查 Postgres、能读 Notion 的关键。.mcp.json（项目级）或 ~/.claude/mcp.json（用户级）声明所有可用的 MCP 服务器：
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
},
"filesystem-remote": {
"url": "https://mcp.example.com/sse",
"transport": "sse"
}
传输协议选型：
stdio： 本地进程，延迟最低，适合本机工具（filesystem、git、postgres）。SSE（Server-Sent Events）： HTTP 长连接，适合远程服务、内网共享、企业统一治理。streamable HTTP： 2026 年逐步成为默认远程传输，兼容老 SSE 客户端。
白名单治理：在 settings.json 中用 enabledMcpjsonServers 显式声明哪些 MCP 服务器可用，例如：
{
"enabledMcpjsonServers": ["github", "postgres"],
"disableMcpjsonServers": ["*"]
}
这一对字段组合的语义是"白名单优先、其余默认禁"，避免新装 MCP 被自动启用造成越权。配合第一层提到的 deny 规则，企业可以把 MCP 治理也纳入 MDM 管控范围。
实操经验：MCP 配置最容易出问题的点不是协议，而是凭据管理。建议所有 token 走环境变量注入，不要直接写在 mcp.json 里——前者入 .gitignore，后者必泄漏。
八、横向对比：Claude Code vs Cursor 2.x / Cline / Aider
截至 2026 年 8 月，这四款工具的定位差异已经相当清晰：
维度 Claude Code Cursor 2.x Cline Aider
形态 CLI / IDE 插件 VS Code 衍生 IDE VS Code 插件 纯终端 主模型 Claude 系列 多模型（含 Claude、GPT 等） 多模型 多模型 项目配置 .claude/ 七层体系.cursorrules + Composer单 JSON CONVENTIONS.md权限矩阵 内置 allow/deny/ask 弱 弱 弱 Subagent 原生 有限 插件扩展 不支持 MCP 支持 一类公民 部分 插件 不支持 Git 集成 Hooks + Worktree 基础 基础 一类公民 团队共享 settings.json 入仓 规则文件入仓 插件配置导出 git 仓库即配置 适用场景 大型团队、企业合规 个人/小团队高效 IDE 开源派、VS Code 用户 终端党、Git-heavy 项目
怎么选（个人观点，仅供参考）：
大团队 + 企业合规 → Claude Code，权限矩阵 + MDM + Hooks 这套天花板级别的工程化能力是独有优势。
个人开发者 + 想要 IDE 体验 → Cursor 2.x，Composer 模式流畅，配置门槛低。
开源 + VS Code 习惯 → Cline，生态丰富，扩展性强。
纯终端 + git 工作流重度用户 → Aider，diff 体验极致，配置简单。
九、2026 年 Claude Code 演进方向速览
以下信息基于官方公开 Roadmap 与开发者社区观察，仅供参考，具体上线以官方公告为准：
Agent SDK 化： 把 Subagent 与 Hooks 抽象为可独立部署的 SDK，第三方工具可以调用 Claude Code 的代理能力而不仅限于本地 CLI。远程会话（Remote Sessions）： 在云端维护长会话状态，开发者切换设备时无缝衔接，适合分布式团队。多模态输入： 除文本外，截图、Figma 文件、PDF 表格可直接作为上下文喂入，进一步压缩"描述 UI 改需求"的成本。企业级 Audit Log： 所有 allow/deny/ask 事件、MCP 调用、Hook 触发统一上报至 SIEM 系统，满足金融、医疗等强合规场景。MCP Registry： 官方推动的 MCP 服务器注册中心，类似 npm registry，未来 npx claude-mcp add 一键安装可信源服务器。
十、常见踩坑清单（QA 团队整理）
CLAUDE.md 字符超限触发截断： 超过约 2 万字符时模型可能只读前部，建议用 @ 拆分子文档，不要把架构图、API 列表全塞进主文件。Hook 超时设置过短： PostToolUse 跑 pnpm test --related 时如果项目大、30 秒不够，会被 SIGTERM，导致 lint 没跑完代码已经提交。建议 CI 环境放宽到 120s，本地保持 30s。* 通配符 allow 被误用：Bash(*:*) 等同于放行所有 Bash 命令，权限矩阵直接破防。务必把通配符收敛到具体前缀。deny 写错字段名： 早期版本字段是 reject，现在是 deny，混用会被静默忽略——升级后建议跑一次 claude-validate 校验。MCP token 写死在 mcp.json： 所有凭据必须走环境变量，否则一次 commit 永久泄漏。Subagent 之间循环调用： A 调用 B，B 又调用 A，会导致上下文无限膨胀。设计上要在主代理层做深度限制。settings.local.json 误入 Git： .claude/settings.local.json 是个人文件，务必加入 .gitignore，否则个人偏好会污染团队。Hook 在 Windows 下路径问题： $CLAUDE_FILE_PATHS 在 Windows 上是分号分隔而非冒号，Hook 脚本要用对应的 split 方式，否则会一次性格式化所有改动文件。
十一、FAQ：读者最常问的 6 个问题
Q1：CLAUDE.md 最佳实践里，团队规范和个人偏好怎么分？ CLAUDE.md 并入 Git；个人偏好进 CLAUDE.local.md，.gitignore 兜底。两份文件同名加载顺序不同，local 后加载、优先级更高。
Q2：Claude Code 权限配置能做到"零确认"吗？
Q3：Subagent 和主代理调同一个模型时，token 怎么算？
Q4：MCP 服务器和直接调 API 有什么区别？
Q5：Slash Command 能调用 Subagent 吗？
Q6：团队里有人用 Cursor、有人用 Claude Code，规范怎么统一？
来源华强北商行 · 数码科技资讯
|手机版|华强北商行
( 粤ICP备17062346号 )
发表于 2026-6-25 06:04
加好友78950405
