团队 Claude Code 配置从一个命令搭起

团队用 Claude Code 久了，配置会散落在好几个地方：斜杠命令、Hook 脚本、CLAUDE.md，各有各的写法。平时相安无事，一到换工具就出问题。

比如 /commit 命令里写着“用 npm lint 检查”，Hook 里写着 eslint --fix，CLAUDE.md 里又交代“统一使用 Biome 格式化”。团队全面换成 Biome 时，你改了记忆和命令，偏偏漏了 Hook。从此每次提交，代码先被 Biome 格式化一遍，再被 Hook 用旧版 ESLint 改回去。

刚开始搭这套配置时，还有一种常见的翻车方式：第一天就想把提交命令、PR 审查、子代理、自动化 Hook、外部 MCP、打包插件全部端上来，结果一整天都在跟配置文件的路径和权限较劲，报错时连哪个零件卡住都定位不到。

这两类问题有同一个解法：

• 先跑通一条最小的业务流程，再按实际缺口一层层加组件，每加一层都能定位它的故障；
• 每项能力只管一段职责，同一件事只保留一个事实来源，其他入口都去调用它；
• 出了漏洞，修共享的源头组件，而不是在单个入口上补一句。

01 从一次最朴素的代码审查起步

最终蓝图再宏大，第一天也只盯住一个最小的具体场景：比如只做一次最朴素的代码审查，让它读入当前分支的 diff，按照项目约定挑出两处逻辑漏洞，并在代码里准确复现出来。

先验证这条基础流程，再按实际需要加入自动化组件。下面从这条小流程出发，按实际缺口扩展：

1. 在 CLAUDE.md 写测试命令和目录边界，验证 /review-change。
2. 提交准备、格式化或独立审查反复出现，再加 /commit、Hook 或审查代理。
3. 要查线上 PR，再接代码托管 MCP；跨模块重构用规划；跨团队共享再打包插件。

走到哪一步缺能力，就补哪一项。下面的目录是扩展后的参考，你需要能解释每个已加入组件解决什么，也能说明哪些暂时用不上：

.claude/
├── commands/
│   ├── commit.md
│   ├── prepare-pr.md
│   └── review-change.md
├── agents/
│   ├── code-reviewer.md
│   └── security-reviewer.md
├── hooks/
│   ├── pre-tool-check.sh
│   ├── format-code.sh
│   └── security-scan.py
├── settings.json
└── skills/
    ├── review-report/
    │   └── SKILL.md
    └── technical-writing/
        └── SKILL.md

CLAUDE.md
.mcp.json

先保留少量能说清用途的配置。用不上的组件即使闲着，也需要维护和排错。

02 每项能力只管一段职责

先画能力分工，再写配置。这样能提前发现职责重叠，也能避免为了完整而启用多余组件：

先找需求，再选能力；一项不够时才组合。维护时也沿同样的分工查。

03 同一件事只留一个事实来源

回到开头 Biome 和 ESLint 打架的例子。要解决这种配置冲突，办法是“单一事实来源”：

• 把具体执行的命令统一放在项目的 package.json 脚本里。
• CLAUDE.md 只需要说明“提交前要跑校验”。
• 各个 Hook 或快捷命令入口，都只负责调用 npm run lint 这个项目脚本。

底层无论怎么更换工具链，只需要修改一处项目脚本，所有的入口和门禁就会一起对齐。Claude Code 的最佳实践文档也有类似的建议：仓库里已有测试、构建或 lint 命令时，CLAUDE.md 里最有用的一行，就是运行它的那条命令。

同一份文档还区分了两类指令：CLAUDE.md、提示词和 Skill 由模型读了再决定怎么做，模型可以判断某条准则不适用；Hook、deny 规则和受管设置则由 Claude Code 每次强制执行。每次都必须发生的事，比如编辑后格式化，放进 Hook 或权限规则；可以随情境判断的准则，留在 CLAUDE.md。

先写 CLAUDE.md，为后续所有入口提供同一份稳定项目规则：

# Project Instructions

## Project Shape

- This is a TypeScript web application.
- Use the existing architecture and helper APIs before adding new abstractions.
- Keep changes scoped to the requested feature or fix.

## Commands

- Install dependencies: `npm install`
- Run tests: `npm test`
- Run lint: `npm run lint`
- Run typecheck: `npm run typecheck`

## Git Workflow

- Review `git status` before committing.
- Do not include secrets, build artifacts or local files.
- Use conventional commit style.

## Testing

- Add focused tests for behavior changes.
- Run the smallest relevant test first.
- For shared logic, run broader tests before finishing.

如果项目较大，可以在 src/api/、src/ui/、docs/ 等子目录放更具体的记忆文件。Memory 只保存跨会话稳定的信息；当前任务细节、临时计划和一次性结论留在本次对话，避免影响后续工作。

04 入口负责编排，方法放进共用组件

接着为每天反复执行的工作建立清楚入口，让用户知道从哪里启动流程：

这五个是候选入口，先选择当前确实重复发生的一项。入口负责取上下文、启动方法和汇总结果，审查、写作与检查交给对应组件。例如 /prepare-pr 可以这样写：

---
allowed-tools: Bash(git status *) Bash(git diff *) Bash(npm test *) Bash(npm run lint *) Bash(npm run typecheck *)
description: 准备 PR 摘要和合并前检查
---

## Workflow

1. 查看当前变更范围。
2. 运行相关测试、lint 和 typecheck。
3. 生成 PR 摘要：
   - 变更了什么
   - 为什么变更
   - 做了哪些验证
   - 有哪些风险
4. 按改动需要委派审查，要求只读报告；test-engineer 在本次流程中只分析测试缺口，不自动修改测试。
5. 汇总必须修复项和可选改进项。

假设 review-change 加入了安全清单、测试标准和报告模板，接着 prepare-pr 也要用。此时可以复制过去，但下次改标准就得找两份。真正值得拆出来的是这份重复方法：保存为 Skill，让两条入口共用，相关材料按条件读取。

是否拆分，要看复用与加载需要。一个入口长一点、却只处理自己的完整流程，并不因此需要再加一层。

05 其余组件按缺口逐个加入

规划与恢复。跨模块功能、数据模型、权限认证、共享逻辑重构和迁移部署，先用 /plan 把方案想清。计划至少交代当前结构、要改哪里、风险、分段步骤、测试与回滚。动手前查看当前 diff，认清已有用户修改与可用恢复点。恢复办法按来源准备：跟踪到的编辑用 Rewind；Bash 和子代理的文件变化另备 Git 或补丁；数据库与外部服务在对应系统恢复。

想象第一阶段改了文件，第二阶段又跑命令更新了数据库。后续测试失败时，回退文件只恢复了前一部分，数据库还在新状态。所以每个阶段做了什么、怎样验证、失败怎样恢复，都要分别记清。阶段可以这样定义：只读分析和计划、最小实现、测试补充、文档和清理、最终验证。阶段检查通过后再继续，才能知道哪一段引入了变化。

Hooks。把短小、确定的自动检查放到事件边界上执行：危险命令在 PreToolUse 拦截，写入后的格式化和安全扫描放在 PostToolUse。看到配置数组里先格式化、再扫描，容易以为执行顺序也如此；它们匹配同一事件，实际上可能同时运行。若扫描必须看格式化后的文件，就把两步写进同一脚本串行调用。

MCP。先看当前流程真正缺哪项外部信息。只查 PR，就先接代码托管；需要业务状态，再加入只读数据库。本地文件可直接读取时，省去文件系统 MCP。把服务职责分开，才能分别收紧权限、核对日志，并在故障时单独停用。

Subagents。先把最需要独立审查的一项职责拆出去，比如只读的 code-reviewer 或 security-reviewer。委派前，主代理先交代 diff 范围和已有测试结果；收到报告后，回到代码核对证据。若交出去的是写任务，再指定谁负责哪些文件，数据库、端口和外部服务另外分配。

CLI。输入、输出和失败处理都能预先定义时，再用 claude -p 接入脚本，比如 CI 中生成审查摘要、批量整理文档。明确输出格式、限制最大成本、设置工具权限、保留日志，避免把敏感内容输出到公共 CI 日志。

06 高级能力按问题选，并把取舍原因留下

高级能力也按问题选：

例如复杂功能实现可以这样推进：plan 模式生成方案，确认代码基线与恢复办法，实现代理在 worktree 中实现，test-engineer 补测试，code-reviewer 和 security-reviewer 审查，Hook 自动格式化和扫描，CLI 生成 JSON 验证报告，主代理汇总结果。

试着从这条链路里抽掉一个零件，看看手头的任务是不是照样能跑顺：

• 需要跨设备切换会话时，再考虑 Remote Control。
• 一两分钟的任务可以留在前台执行。
• 串行执行本来就稳妥、文件归属也没理清，那就保持串行。

高级特性会增加权限、状态管理和协作成本，按实际需求选择。把原因留给新成员看：以后出现了跨设备接续，或真正独立的并行任务，再回到原来的取舍重新判断。

配置在一个项目里实际跑通几次之后，若方法还在变化，继续在这里调整即可；等工作流稳定、另一个项目也要使用时，再把它打包成插件。

07 出了漏洞，修共享的源头

系统投入使用后，给各组件指定维护者和清理周期。规则、命令、权限和工具链都可能过期，成员也应知道怎样禁用和排错。按负责的层次检查和更新：

维护中最常见的一个下意识动作是：有同学反馈某次 /review-change 漏审了一个关键的 SQL 注入隐患，负责维护的同学顺手就在这个命令的提示词里加了一句“一定要检查 SQL 注入”。

停下来多想一步：团队里另一个高频的 /prepare-pr 命令，以及 CI 脚本里调用的自动化审查，是不是同样存在这个漏洞？只在单个入口上补一句，只是临时补救。下次有人换了个入口，或者在流水线里调 CLI，同样的漏洞依然会进入主分支。

这时要抓住真正的共享源头：既然所有审查入口底层用的都是同一个 security-reviewer 子代理或安全检查 Skill，就把规则更新到这个共享组件里。修好这一处，所有调用它的命令、脚本和自动化流程会同时受益。维护时沿职责找到共享组件，分工和配置才不会逐渐混乱。

工作系统搭好后，真正的考验是中途有环节失败时，它能不能如实交付结果，这部分见 如实汇总 Claude Code 多代理的审查结果。各项能力最初怎样按问题挑选，可以回看 Claude Code 功能这么多，先学哪几个。

维护一套工作系统，最常问的一句话是：这件事的源头在哪？格式化找项目脚本，安全规则找共享的审查组件，项目约定找 CLAUDE.md。源头只有一个，改一处就全对齐。