一个残酷的现实

我见过太多团队这样用 Claude Code：

小王用得飞起，一天能干三天的活。小王请假，换小李接手，同样的提示词，输出质量断崖式下跌。小李折腾两天，终于摸出门道。小李离职，新人小张入职，循环重演。

问题出在哪？

不是 Claude Code 不稳定，是你的"用法"没有沉淀。每个人都在重新发明轮子，每次换人都是从零开始。

今天这篇，我想彻底讲透一件事：怎么把 Claude Code 从"个人技巧"升级成"团队资产"。

---

为什么"配置即代码"是唯一正确的路

很多人把 Claude Code 当成一个聊天工具——打开，输入，等结果。

这是最大的误区。

真正把 Claude Code 用好的团队，都在做一件事：把和 AI 协作的方式，当成代码来管理。

这意味着：

• 能被 Git 追踪，能看到谁改了什么
• 能被 Code Review，能讨论为什么这样改
• 能回滚到上一个稳定版本
• 能按项目独立演进
• 能让新人第一天就用上团队积累的所有经验

换句话说：你的 AI 协作经验，应该像代码一样有版本、有评审、有迭代。

---

七个构件：Claude Code 配置体系的完整拆解

我花了两个月时间，反复测试不同的配置方案，最终收敛出这套框架。

把它想象成七个抽屉，每个抽屉放不同的东西：

1. CLAUDE.md —— 项目的"身份证"

这是 Claude 读取的第一个文件，告诉它"这个项目是谁"。

应该写什么：

• 项目的技术栈（用什么语言、什么框架）
• 目录结构说明（哪些目录是什么用途）
• 构建和测试命令（怎么跑起来、怎么验证）
• 禁区（哪些文件绝对不能动）

不应该写什么：

• 长篇大论的编码规范（那是 rules 的事）
• 具体的操作流程（那是 commands 的事）
• 所有你能想到的注意事项（太长等于没写）

核心原则：只写 Claude 从代码里推不出来的信息。

2. rules/ —— 团队的"底线"

这是硬性约束，没有商量余地。

.claude/rules/
├── security.md      # 安全红线
├── testing.md       # 测试要求
├── coding-style.md  # 代码风格
└── git-workflow.md  # 提交规范

写 rules 的关键：短、硬、不解释。

比如 security.md：

- 禁止在代码中硬编码任何密钥、token、密码
- 禁止在日志中输出用户敏感信息
- 所有外部输入必须做校验

不需要解释为什么，就是必须遵守。

3. agents/ —— 专用的"分身"

当你发现某类任务需要"换一种思维方式"时，就该拆成独立的 agent。

.claude/agents/
├── planner.md           # 方案规划
├── code-reviewer.md     # 代码审查
├── security-auditor.md  # 安全审计
└── debugger.md          # 问题排查

为什么要拆？

主对话的上下文是有限的。你让 Claude 一边写代码一边审代码一边做安全检查，它会越来越糊涂。

把"审"和"查"拆出去，主对话只负责"做"，效率会高很多。

4. commands/ —— 高频操作的"一键化"

团队里总有一些反复出现的工作流程。把它们变成斜杠命令，是减少个人差异最有效的方式。

.claude/commands/
├── plan.md        # /plan - 先规划再动手
├── review.md      # /review - 代码审查
├── fix-build.md   # /fix-build - 解决构建错误
└── refactor.md    # /refactor - 重构指南

最值钱的命令：/plan

我强烈建议每个团队都落地这个命令。它的核心逻辑是：

1. 先复述需求，确认理解正确
2. 列出要改的文件
3. 评估风险点
4. 给出验收标准
5. 等你确认后，才开始写代码

这看起来"慢"，但它解决的是最贵的成本：返工。

一个判断标准：如果你没法用一句话说清楚这次改动的 diff，那就先 /plan。

5. skills/ —— 可复用的"方法论"

有些知识不是规则，而是"怎么做更好"的经验。

.claude/skills/
├── tdd.md              # 测试驱动开发
├── api-design.md       # API 设计原则
├── error-handling.md   # 错误处理模式
└── performance.md      # 性能优化思路

Skills 和 rules 的区别是：rules 是"必须这样做"，skills 是"这样做更好"。

6. hooks/ —— 自动化的"护栏"

这是整个体系里最容易被忽视、但价值最大的部分。

团队里最常见的幻觉：把规则写进 CLAUDE.md，就会自动被遵守。

现实是：越忙越容易忘，越急越容易破例。

Hooks 的作用是：把"应该发生的事"变成"必然发生的事"。

三种类型：

提醒型（不阻断，只提示）

{
  "event": "PreToolUse",
  "tool": "bash",
  "pattern": "npm test|pytest|cargo build",
  "action": "echo '⏱ 耗时命令，建议在 tmux 里运行'"
}

一致性型（自动执行某些动作）

{
  "event": "PostToolUse",
  "tool": "edit",
  "pattern": "\\.(ts|tsx)$",
  "action": "npx prettier --write $FILE && npx tsc --noEmit"
}

阻断型（不满足条件就停下来）

{
  "event": "PreToolUse",
  "tool": "bash",
  "pattern": "git push",
  "action": "echo ' 推送前请确认：测试通过了吗？' && exit 1"
}

落地建议：先提醒，再一致性，最后才是阻断。 一上来就到处拦截，团队体验会崩。

7. MCP —— 外部工具的"接入层"

当你希望 Claude 能直接查 issue、读 PR、拉日志时，MCP 就派上用场了。

但我不建议一上来就接一堆。原因很朴素：启用的工具越多，上下文越贵，权限面也越大。

稳妥的做法：

1. 先用 CLI 工具把流程跑通（比如直接跑 gh 命令）
2. 确认稳定后，再封装成 MCP
3. 密钥用环境变量，别进仓库

---

落地路线图：7 天从零到可用

如果你要在团队里推这套体系，按这个顺序来，阻力最小：

天数	动作	目标
Day 1	写 CLAUDE.md	让 Claude 认识项目
Day 2	加 rules/security.md + testing.md	把底线写硬
Day 3	落地 /plan 命令	改代码前先规划
Day 4	落地 /review 命令	审查维度标准化
Day 5	加一个提醒型 hook	让团队接受 hooks 的存在
Day 6	加一个一致性型 hook	质量变得可预期
Day 7	引入一个专用 agent	把"审"从主对话拆出去

到第七天，你会明显感觉到：Claude Code 不再是"靠个人发挥"，它开始像一套团队工具链。

---

五个翻车点，提前避开

1. CLAUDE.md 写太长

规则淹没规则，等于没有规则。狠删，把"必须发生"的动作迁到 hooks。

2. 把偏好写成底线

"我喜欢先写测试"是偏好，"必须有测试才能合并"是底线。前者放 CLAUDE.md，后者放 rules。混在一起，团队里一定有人不买账。

3. Hook 过度阻断

一上来就拦各种命令，团队体验直接崩。先提醒，再一致性，最后才是阻断。

4. 密钥进仓库

这是最危险也最常见的事故。用环境变量占位符，仓库里只放示例。

5. 照搬别人的配置

别人的语言栈、测试框架、Git 流程未必和你一致。先抄结构，再抄模式，最后才抄实现。

---

怎样"抄"一个开源配置仓库

我推荐看一下 everything-claude-code 这个仓库。不是让你照搬，而是学它的结构。

正确的"抄"法分三层：

第一层：抄结构 把七个构件的目录结构抄下来，让团队有一个共同的放置位置。

第二层：抄模式 挑 2-3 个可迁移的模式，比如：

• /plan 强制先计划再实现
• rules/security.md 约束密钥操作
• 一个提醒型 hook

第三层：抄实现 最后才是具体的提示词、脚本内容。这时候你已经有了边界，更知道该删什么。

---

写在最后

把 Claude Code 用到团队层面，本质是做一件很传统的事：

把隐性经验变成显性资产，把口头约定变成可执行系统。

你不需要一上来就把七个构件全部做满。

从 CLAUDE.md + rules + 一个 /plan 命令开始就够了。

当你发现团队里换人不再需要"传授心法"，新项目不再需要"重新摸索"，Claude Code 的输出质量开始稳定可预期——

你就知道，这套体系跑通了。

Claude Code 团队基建的完整方法论：配置写完之后，到底怎么用？