Claude Code配置实战：打造有分工、有边界的AI工程团队

如果你已经用 Claude Code 写过一阵子代码，大概率会有种感觉：刚装好的它像个聪明但没什么章法的实习生，你问一句它答一句，让它改个小文件还行，一旦涉及多模块改造、规范审查、部署检查，它就容易前后矛盾，甚至越改越乱。我刚开始也这样，直到我把 Claude Code 的配置系统彻底摸了一遍，才意识到问题不在于模型不够强，而在于我把它当成“一个助手”在用。这篇指南，就是要讲清楚怎么把 Claude Code 配置成一支有分工、有流程、有边界的 AI 工程团队。方案适合已经装过 CLI、试过基础对话、但觉得产出不稳定的人，也适合想在团队里推广 AI 编程工具、需要一套可复现配置的人。

1. 为什么我要把 Claude Code 配置成“一支团队”

1.1 默认模式的三个痛点

先聊聊默认状态下 Claude Code 的使用体验。你打开终端敲claude，进入一个对话式的 REPL 界面，工具可以读文件、写文件、跑命令。这个模式应付“给我解释一下这段代码”“帮我把这个函数改短”这类任务很顺手，但一旦任务复杂，三个问题就会暴露出来：

• 没有角色隔离。所有任务都交给同一个大脑处理。写业务代码、做代码审查、检查部署脚本，用的是同一套上下文和同一批权限。结果就是，让 AI 审查自己刚写的代码时，它很容易“护短”，抓不到真正的风险点。
• 上下文很容易失控。项目一复杂，对话里塞的东西一多，工具就开始忘事。它可能忘记你项目的目录规范，忘记某些目录不能动。CLAUDE.md 虽然能写项目说明，但大部分人没好好利用，配置文件长期处于缺失状态。
• 权限要么全给、要么全拒。默认情况下很多危险操作会弹确认框，点多了就麻木；或者为了省事直接--dangerously-skip-permissions一把梭，结果工具误删文件、乱装依赖，你根本反应不过来。

这三个痛点叠加起来，就是很多人觉得“AI 编程工具只能写玩具项目”的根本原因。它不是模型不行，是使用方式不对。

1.2 最终想达成的状态：目标与目录骨架

我想要的不是“一个助手”，而是一支能够自我管理的小团队。团队里每个人都只负责自己那摊事，都遵守同一套项目规范，都有明确的权限边界。具体到 Claude Code 的配置系统，就是用四个部件拼出这支队伍：

• CLAUDE.md是团队的“公司章程”，写清项目的一切硬性规定。
• Skills是团队的“操作手册”，把高频任务固化成标准流程。
• Subagents是“具体员工”，每个角色持有一份独立人格、独立工具集和独立模型配置。
• permissions是“门禁系统”，控制每个人的登录权限和危险动作审批。

最终配置的目录结构长这样：

~/.claude/ ├── settings.json # 全局配置（模型、权限、环境变量） ├── CLAUDE.md # 全局通用规范 ├── agents/ # 全局子代理定义 └── skills/ # 全局技能定义 项目目录/ └── .claude/ ├── settings.json # 项目级配置 ├── settings.local.json # 本地私有配置（不进 git） ├── CLAUDE.md # 项目专属规范 ├── agents/ # 项目团队角色 └── skills/ # 项目专属技能

这套结构的好处是“全局沉淀 + 项目定制”两层分离。通用的代码规范、审查标准放在~/.claude里，任何项目都能用；项目特有的技术栈、目录约定放在项目里的.claude下，跟着仓库走，新同事 clone 下来就能获得完全一致的工作环境。

2. 基础准备：安装、认证与配置文件分层

2.1 先把本机环境收拾利落

配置 Claude Code 前，需要先确认三样东西齐不齐：Node.js、Git、以及一个能正常访问 Anthropic 服务的网络环境。

Node.js 是 CLl 的运行底座，建议用 18 或更高的 LTS 版本。我见过很多安装失败案例，最后都是 Node 版本太老导致的；如果你机器上同时有多个项目、多个 Node 版本，建议用 nvm 做版本管理，避免全局环境互相污染。

Git 方面，Claude Code 的很多操作依赖 Git，比如查看当前变更、生成 diff、回退修改。Windows 用户建议直接装 Git for Windows，并且把终端切到 Git Bash 再跑 Claude Code，体验比 CMD 和 PowerShell 顺滑不少。

确认环境没问题后，安装命令就一条：

npm install -g @anthropic-ai/claude-code claude --version

如果能正常打印版本号，安装就完成了。升级也简单：claude update或者再用 npm 全局更新一次。

注意：如果你的终端提示claude命令找不到，多半是 npm 全局 bin 目录没进 PATH。用npm bin -g查一下目录，把它加进 PATH 即可。

2.2 认证方式选哪个

装完之后第一次运行claude，会进入登录流程。Claude Code 的认证方式主要有两种，适用场景完全不同：

*方式一：OAuth 交互式登录。*在终端直接运行claude，工具会弹出一个浏览器登录链接，登录你的 Anthropic 账号完成授权。这种方式适合个人笔记本，好处是省心，不需要手动管理密钥，坏处是换机器就要重新登录，不适合服务器和团队共享环境。

*方式二：API Key。*在环境变量里设置ANTHROPIC_API_KEY，工具启动时会自动读取。这种方式适合 CI、云服务器、或者团队需要集中计费的场景。把 Key 暴露在项目代码里是大忌，建议放在~/.claude/settings.json的env字段，或系统的环境变量文件里。

我个人在个人电脑上用 OAuth，在服务器和自动化脚本里用 API Key。两种方式互不冲突，看使用场景切换就行。

2.3 配置文件分层的底层逻辑

Claude Code 的配置分为三个层级，理解这个分层是后续所有配置的基础：

三个层级是叠加关系，相同键值按“越具体越优先”的原则覆盖。比如全局模型设为sonnet，项目里想用更强的opus，只在项目配置里改模型键就行，不影响其他项目。

下面是一份我自己在全局配置里常驻的基础模板：

{ "model": "sonnet", "env": { "CLAUDE_CODE_MAX_OUTPUT_TOKENS": 8000 }, "permissions": { "allow": [ "Bash(git status:*)", "Bash(git diff:*)", "Read(*)", "Glob(*)", "Grep(*)" ], "deny": [ "Bash(rm -rf:*)" ] } }

这里有几个细节值得解释：

• model填的是模型别名，不一定要写具体版本号，Claude Code 会自动解析成当前可用的最新版本。常见的别名就是opus、sonnet、haiku，分别对应能力从强到弱、成本从高到低的不同档位。
• allow和deny里的Read(*)、Glob(*)这类写法是权限通配规则。能精确限定到命令的绝不放开全局 Bash，这是我一直遵守的原则。
• CLAUDE_CODE_MAX_OUTPUT_TOKENS用来控制单次输出的 token 上限，遇到长文件生成时比较有用，防止工具输出到一半被截断。

3. 团队骨架配置：角色、技能、权限三位一体

3.1 CLAUDE.md：团队章程怎么写才有效

CLAUDE.md 是 Claude Code 的长期记忆文件，会在每次会话启动时自动加载，相当于给 AI 的“入职手册”。很多人只是随便往里面扔两句项目简介，这太浪费了。

一份好用的 CLAUDE.md 至少需要包含五类内容：

• 技术栈和目录结构。告诉 AI 这个项目用什么框架、代码放在哪里、哪些目录是生成产物不能动。
• 常用命令。开发、构建、测试、lint 分别是什么，AI 跑命令之前不用再猜。
• 代码规范。缩进风格、命名约定、组件拆分原则。这些内容写进去后，AI 生成的代码会明显更贴项目风格。
• 禁止事项。比如“不要修改数据库迁移文件”“不要动 lock 文件”“生产环境配置一律走环境变量”。
• 任务工作流。团队约定好的提交流程、分支策略，让 AI 按流程执行。

项目根目录如果没有 CLAUDE.md，可以用/init命令让工具自动扫描项目生成一份初稿，再人工补充修整。但注意一点：自动生成的版本通常只有技术栈和目录说明，团队真正的工作流和禁止事项还需要你自己补，这步偷懒的话，后面的配置效果会大打折扣。

举一个精简的例子：

# 项目规范 ## 技术栈 - Node.js 20 + TypeScript 5 - React 18 + Vite，后端 Express - 代码入口：src/ 目录，测试文件与源码同目录 ## 常用命令 - 本地开发：npm run dev - 测试：npm test - 构建：npm run build - 类型检查：npm run typecheck ## 代码规范 - 组件使用函数式写法，禁止 class 组件 - 样式使用 CSS Modules，不使用内联 style - 文件名采用 camelCase，组件文件用 PascalCase ## 禁止事项 - 不要修改 public/ 下的资源 - 不要直接改 package-lock.json - 数据库结构变更必须通过 migration 完成 ## 工作流 1. 开发前先看 docs/ 下的设计文档 2. 提交信息遵循 Conventional Commits 3. 提交前必须通过 typecheck 和 lint

3.2 Skills：把高频操作固化为标准作业程序

Skills 是 Claude Code 新版本里非常实用的能力，本质上是一组预先写好的“操作手册”，AI 遇到匹配任务时会自动加载对应手册来执行。它解决的是“每次都要重新解释一遍怎么做”的问题。

每个 Skill 是一个目录，目录里必须有SKILL.md文件：

.claude/skills/ └── mysql-debug/ └── SKILL.md

SKILL.md的格式是“YAML frontmatter + Markdown 正文”。frontmatter 里的name和description是索引的关键，AI 靠 description 来判断什么场景该用哪个 Skill，所以 description 一定要写得具体，包含触发条件和预期产出，不要写空话。

我拿自己常用的“MySQL 慢查询排查”技能举例。因为项目里经常有人来问“数据库怎么变慢了”，我把排查步骤沉淀成一个 Skill 之后，每次遇到类似问题，AI 会自动按步骤执行：

--- name: mysql-debug description: 当项目出现数据库连接超时、慢查询、死锁等问题时使用。 输入是数据库连接信息和问题描述，输出是排查结论和优化建议。 --- # MySQL 问题排查流程 1. 先确认数据库版本和隔离级别，执行 `SELECT VERSION()` 和 `SELECT @@tx_isolation;` 2. 开启慢查询日志，临时开启可以通过 `SET GLOBAL slow_query_log = 'ON';` 3. 查询当前运行中的长事务： `SELECT * FROM information_schema.innodb_trx WHERE TIME_TO_SEC(TIMEDIFF(NOW(), trx_started)) > 10;` 4. 针对慢查询使用 `EXPLAIN` 分析执行计划，重点关注： - type 是否为 ALL（全表扫描） - key 是否为空（未走索引） - rows 是否远超预期 5. 输出结论时给出具体 SQL 优化建议，不要泛泛说“加索引”，要指出加在哪个字段。 ## 注意事项 - 只读操作外不要在生产库上直接执行修改 - 慢日志打开后记得关闭，避免磁盘占用过高

这里面的核心经验是：Skill 的重点不是理论讲解，而是“可执行的操作步骤”。一篇好的 SKILL.md，要让 AI 照着走就能得到稳定结果。而且 Skill 对 description 的措辞很敏感，描述里带上项目里常用的说法（比如“数据库慢”“接口超时”），召回率会高很多。

3.3 Subagents：每个职能都有独立工位

如果说 Skills 是团队的操作手册，那 Subagents 就是团队的“具体员工”。你可以给每个角色定义一个独立的系统提示词、一组受限的工具列表，甚至指定不同的模型档位。这样“产品经理”“架构师”“代码审查员”“运维”就不共用一套大脑和权限了。

Subagents 的定义文件放在.claude/agents/目录下，格式是 Markdown，文件名最好和角色名一致。frontmatter 里核心字段有三个：

• name：角色名，会话里用@角色名呼出。
• description：角色能力的描述，AI 判断任务该交给谁的时候靠这个字段。
• tools：允许该角色使用的工具列表。不写就继承全部工具，写了就严格限制。
• model：可选，可以指定该角色使用不同档位的模型。

我拿“代码审查员”举例，这是我认为第一个值得配置的角色：

--- name: code-reviewer description: 负责对代码变更进行严格审查。当收到 git diff、PR 描述或 需要评估代码质量、找潜在缺陷时使用。输出结构化审查报告。 tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*), Bash(git status:*) model: sonnet --- # 角色定位 你是一名资深代码审查员，以严苛但建设性的态度审查代码。你的任务不是夸奖，而是发现风险。 # 审查流程 1. 运行 `git diff HEAD` 查看当前变更范围。 2. 从变更文件中识别高风险区域：涉及数据删除、权限校验、并发写入、外部输入拼接的代码优先看。 3. 逐文件检查，重点关注： - 错误处理是否完备（是否有空指针、异常吞噬） - 是否存在安全风险（SQL 注入、XSS、敏感信息硬编码） - 是否遵守项目 CLAUDE.md 中的代码规范 4. 输出报告，格式如下： - 严重级别（致命 / 建议） - 文件名与行号 - 问题描述 - 修改建议

这个文件建好后，在 Claude Code 会话里输入@code-reviewer就能把它拉进对话。更妙的是，你可以让主对话先完成开发，然后直接把变更内容简要交代给这个角色，让团队里“另一个人”来挑毛病，审查质量比同一个会话里自写自审高得多。

同样的思路，我还会配置一个tech-lead负责技术方案设计，一个release-ops负责发布检查，一个pm负责把需求拆成任务清单。每个角色的人格、工作流、工具边界各自独立，整支团队才像一个真正的团队。

3.4 Permissions：给每个角色划好边界

权限配置是整个体系的安全底座。Subagents 里的tools控制的是“能碰哪些工具”，settings 里的permissions控制的是“具体命令要不要审批”，两者配合使用。

权限规则的核心机制是三类动作：allow（允许）、deny（拒绝）、ask（询问）。匹配规则采用通配符，支持精细到具体命令：

{ "permissions": { "allow": [ "Bash(npm run dev:*)", "Bash(npm test:*)", "Bash(npm run build:*)", "Bash(git add:*)", "Bash(git commit:*)", "Bash(git push:*)", "Read(./src/**)" ], "deny": [ "Bash(rm -rf:*)", "Bash(sudo:*)", "Write(./node_modules/**)" ], "ask": [ "Bash(npm install:*)", "Bash(npx:*)" ] } }

我见过不少人把dangerously-skip-permissions当成常规手段，这个念头最好趁早打消。跳过权限意味着 AI 可以执行任何命令、改任何文件，一次误操作就能清空工作区。正确的打开方式是把常用安全命令写进 allow，把高风险命令写进 deny，剩下不能确定的交给 ask，运行时人工拍板。

4. 完整实操：5 分钟搭出五角色工程团队

4.1 场景与角色定义

理论讲了不少，我直接用一套真实可复现的配置，带你从零搭一个五角色的“AI 工程团队”。假设你有个 TypeScript + React + Express 的项目，团队里需要这么几个角色：

4.2 从空目录开始逐步配置

Step 1：创建目录结构。

mkdir -p .claude/agents .claude/skills

在项目根目录建好两个子目录，agents 放角色定义，skills 放操作手册。

Step 2：写项目章程 CLAUDE.md。

用上一节提到的五要素结构写一份精简版，至少包含技术栈、常用命令、禁止事项。如果嫌手写麻烦，可以先在 Claude Code 会话里敲/init，让工具扫描项目生成初稿，再人工补上“禁止事项”和“工作流”两节。

Step 3：定义子代理。

按 3.3 的例子，分别在.claude/agents/下写pm.md、tech-lead.md、frontend-dev.md、backend-dev.md、code-reviewer.md。每个文件重点是 description 和 tools，描述写得越具体，任务分派准确率越高。

Step 4：沉淀第一波 Skills。

先不要急着写很多技能，挑一个团队最痛的高频场景开始。比如前端团队经常要新页面，那就写一个react-page-generator技能；后端经常要新接口，那就写一个express-api-generator技能。一个能跑的技能比十个落灰的技能有价值得多。

Step 5：配置权限。

项目级 settings.json 里，把安全的常规命令加进 allow，把删除类命令放进 deny。配置完成后重启一次会话，让配置生效。

4.3 用一条任务串联整支队伍

配置完成后，实际使用的场景是这样的。你打开终端跑claude，输入：

@pm 需求来了：用户中心增加一个修改头像的功能。拆解一下任务和验收标准。

pm 角色会基于 CLAUDE.md 的项目背景输出任务清单，比如“前端：新增头像上传弹窗”“后端：新增图片上传接口”“数据库：新增用户头像字段”。然后你继续：

@tech-lead 根据 pm 的任务清单，给出技术方案，重点设计接口和文件结构。

tech-lead 输出方案后，你把方案精简一下派给前端开发：

@frontend-dev 按照 tech-lead 的方案实现头像上传组件，完成后运行 npm run typecheck 和 npm test。

开发角色干活的同时，主对话可以切去做别的事。等开发角色报告完成，你再拉最后一个角色进场：

@code-reviewer 请审查刚才的变更，输出审查报告。

整个流程共用一个终端会话，但每一步的“执行者”都是独立的角色、独立的上下文、独立的工具边界。这就是“AI 工程团队”和“单个助手”的核心区别。

4.4 让团队更聪明的三个进阶功能

基础团队搭好之后，有三个功能值得按需加上，它们能让团队的自动化程度再上一个台阶：

*第一个是 Hooks。*Hooks 可以在工具执行前后触发外部脚本，比如在每次 Edit 工具写文件之后自动跑一次 ESLint，或者每次会话结束后自动记录使用成本。配置写在 settings.json 的hooks字段里，适合做质量闸门。

*第二个是 MCP。*MCP 可以让 Claude Code 连接到外部工具，比如 GitHub、数据库、内部 API。用claude mcp add命令就能注册一个 MCP 服务器，配置会写入项目的.mcp.json。这相当于给团队成员接入了“外部专线”，能直接操作 GitHub PR 或者查询生产数据库状态。

第三个是非交互模式。claude -p "任务描述"可以在不进入交互界面的情况下直接执行任务，配合--output-format stream-json还能拿到结构化输出。我常用它做定时任务，比如每天早上自动检查代码库里有没有硬编码的敏感信息。

5. 常见问题与排查实录

5.1 安装与启动阶段

*Q：npm install时报 EACCES 权限错误。*这是 Node 全局目录没有写权限导致的。不要直接加 sudo 硬装，正确的解法是用 nvm 重装 Node，把全局目录挪到用户目录下，一劳永逸。

*Q：claude命令启动后卡在登录页，或者报网络连接错误。*先确认终端本身能正常访问外网，再确认 Anthropic 账号和订阅/API 额度正常。常见错误类似 ECONNRESET，多半是本机网络层面的问题，和工具配置无关。我遇到过几次是公司网络代理拦截了 WebSocket 连接，调整网络环境后就好了。

*Q：Windows 下输入中文或特殊字符时交互界面卡顿。*建议切换到 Git Bash 或 Windows Terminal 使用，并且把终端的编码切到 UTF-8，能减少大部分乱码和输入问题。

5.2 配置加载失效类问题

*Q：改了 settings.json 但行为没变化。*Claude Code 的配置在会话启动时加载，运行中修改不会热更新。改完配置要把当前会话/exit退出，重新进一次再测。如果是权限或者工具相关配置，还需要确保改的是正确层级的文件，项目行为和全局行为要分清。

*Q：Subagent 定义了但@角色名拉不出来。*先检查文件名和 frontmatter 里的 name 是否一致，再检查文件后缀是不是.md，位置是否在.claude/agents/下。另一个常见原因是 description 里的触发词太抽象，AI 不知道什么时候该用这个角色，可以尝试在任务描述里直接指名。

*Q：Skill 一直没被自动调用。*SKILL.md 放在技能目录后，不一定立即被索引，我遇到过需要等待系统扫描或重新启动会话的情况。另外 description 写得太笼统也会导致召回失败，比如只写“处理数据库问题”，不如写“当用户提到数据库连接超时、慢查询、死锁时使用”，召回率会明显提高。

5.3 权限与工具执行问题

*Q：AI 跑 npm install 一直被确认弹窗打断。*如果你确认这个项目里安装依赖是安全操作，把它加进项目 settings.json 的 allow 列表即可。但不要图省事把Bash(*)放进 allow，风险太大。

*Q：Subagent 提示没有权限执行某些命令。*看看 agents 文件的 frontmatter 里tools字段是不是写得过窄，比如只给了Read和Grep，它没法执行任何命令。tools 不是越宽越好，但你得给每个角色配齐完成核心工作所需的工具。

*Q：不小心放行了危险命令导致文件被删。*遇到这种情况先不要慌，如果有 Git，直接用git checkout -- .恢复；如果没有 Git，Claude Code 的/rewind功能可以回退 Checkpoint 记录。但更根本的预防方法是把rm -rf这类命令默认写进 deny 列表。

5.4 上下文与成本控制问题

*Q：会话太长之后 AI 开始“忘事”。*这是上下文接近上限的典型表现。规律性地用/compact把历史对话压缩成摘要继续，或者直接/clear开启新会话，让 AI 重新读取 CLAUDE.md 和关键文件。我的习惯是：完成一个小任务就 clear 一次，不贪恋长会话。

*Q：成本有点失控。*我的经验是：默认对话用 sonnet，量大且重复的整理类任务用 haiku，只有真正的架构设计、复杂审查才切 opus。通过 Subagents 的 model 字段做角色级成本控制后，整体账单能降不少。另外，/context命令可以随时查看当前上下文的占用占比，及时清理无用信息。

*Q：AI 输出经常被截断。*在 settings.json 里调整CLAUDE_CODE_MAX_OUTPUT_TOKENS，把它从默认值调高一些。不过这个参数不是越大越好，调太高可能影响工具的整体响应稳定性，建议从 8000 开始试。

6. 回到最开始：我的配置迭代路线

如果你看完这篇指南还是觉得信息量有点大，我给你一条不会出错的起步路线图：先装好环境，然后只做一件事——写一个 code-reviewer 子代理。让它成为你的第一道 AI 质量闸门，用两周时间观察审查质量，再逐步加第二个角色。等团队跑顺了，回头再看 CLAUDE.md、Skills、权限这些墙上的规矩，你自然会知道哪些要加、哪些要改。

我自己踩过最大的坑，就是把配置一步到位做得太复杂。文件堆得越多，维护成本越高，某个 skill 长期没人触发、某个子代理的工具列表和实际任务不匹配，都会让整个体系变得脆弱。想通这点之后，我把配置原则改成“每个文件都要回答一个问题”：CLAUDE.md 回答“项目有什么规矩”，Skill 回答“这件事怎么做”，Subagent 回答“这件事归谁管”。配置不是越多越好，而是越清晰越好。

最后分享一个小技巧：把整套.claude配置纳入 Git 管理，和代码一起提交。这样每次配置调整都有历史记录，团队成员之间可以直接互相借鉴配置。等用顺手了，你再打开一个新的空白项目，git clone一份，AI 团队就位，直接开工。这才是这套配置真正值回票价的地方。