# 重新认识 Claude Code 架构治理与团队工程化实战全景

> 深度解构 Claude Code 的核心架构与治理机制，覆盖 SubAgent、Skills、Hooks、Permission、MCP、 CLAUDE.md 等模块，给出从个人到团队的工程化落地路线图。

- 原文：https://feinterview.poetries.top/blog/claude-code-engineering-architecture-governance
- 来源：前端进阶之旅（feinterview.poetries.top）
- 更新：2026-05-18
- 可见范围：免费部分

---

> 多数人把 `Claude Code` 当成「命令行版 `Cursor`」，写代码顺手用一下，关掉终端就忘了。但真正长期用下来你会发现：它不是一把瑞士军刀，而是一个完整的 **AI 工程化操作系统**。本文系统拆解 `Claude Code` 的架构、治理和团队落地实践。

在本篇文章中，我们将从浅入深，和大家一起学习以下知识：

- 为什么 `Claude Code` 不只是 AI 编程工具
- 六个一等公民模块：`Slash Commands`、`SubAgent`、`Skills`、`Hooks`、`MCP`、`Permission`
- `CLAUDE.md` 的三层优先级模型怎么生效
- 个人 / 小团队 / 大团队的三档落地路线图
- 常见反模式与可执行的修复建议
- 一份完整的 SOP 模板，照搬就能用

## 痛点与解决方案

很多人第一次用 `Claude Code` 的体验是：跑个 `claude` 命令，让它写段代码，跑通了关掉终端，工作结束。这种用法没有错，但只发挥了 5% 的能力。当你想把 AI 接到真实业务里，会立刻撞上几堵墙：

- **上下文漂移**：每次开新会话都要重新解释项目背景、技术栈、命名约定，重复劳动
- **行为不一致**：今天让它写 React 组件用 antd，明天它给你混进 shadcn，没人管它
- **没有审计**：它擅自跑了 `rm -rf`、`git push --force`，等你发现已经晚了
- **协作失控**：团队两个人各用各的 Claude Code，对同一份代码的判断完全不一样

这些问题不靠「再 prompt 一遍」解决，而是要把 `Claude Code` 当成一个**有架构、有治理、有 SOP 的系统**去配置。`Claude Code` 现在已经长成了一个高度结构化的平台，本文我们就把它的全貌拆开看。

## 一、Claude Code 不只是 AI 编程

把 `Claude Code` 类比成命令行版的 `Cursor` / `Copilot` 是常见误解。`Cursor` 是 IDE 增强，本质是把 AI 嵌进编辑器；`Claude Code` 是 **AI Agent runtime**，本质是给你一个会用工具的同事。

具体差别在哪？看下面这张职责对比：

| 维度 | Cursor / Copilot | Claude Code |
| --- | --- | --- |
| 形态 | IDE 插件 / 编辑器 | 终端 + 跨 IDE Agent runtime |
| 主战场 | 写代码补全、问答 | 多步任务执行、跨工具协作 |
| 上下文承载 | 单文件 / Cursor Rules | `CLAUDE.md` + Skills + Hooks + MCP |
| 工具调用 | 内置少量 | 任意 Bash / 文件 / Web / MCP server |
| 多代理 | 无 | `SubAgent` 派发、并行隔离 |
| 行为治理 | 较弱 | `Permission` + `Hooks` 强约束 |

简单说：`Cursor` 帮你写完一行代码就退场，`Claude Code` 会陪你跑完一个完整任务（写代码、跑测试、查日志、提 PR、看 CI），中间任何一步都能被你的约定接管。

## 二、六个一等公民模块

理解 `Claude Code` 先理解它的「构件」。这六个模块是平台级一等公民，缺一不可。

### Slash Commands 不只是快捷命令

`/<command>` 形式的斜杠命令是用户和系统交互的入口。常见的内置命令有 `/help`、`/clear`、`/config` 等。但更关键的是：**你可以把任意一段标准操作变成一个自定义 slash command**，让团队所有人用同样的姿势调用。

举两个例子：

- `/review` —— 自定义为「读 git diff、按团队 review checklist 检查、给出修改建议」
- `/ship` —— 自定义为「跑测试、写 commit、push、开 PR」

斜杠命令本质是**可执行 prompt 模板** + 可选脚本，它把「人脑里的 SOP」变成了「键盘上的快捷键」。

### SubAgent 分形 AI 团队

`SubAgent` 是 `Claude Code` 最反直觉但威力最大的能力之一。主 Agent 可以派发独立的子 Agent 去完成边界清晰的子任务，子 Agent 有自己的上下文窗口，跑完只把结果回传一句话。

适合派子代理的场景：

- 3 个独立 spec 文档的并行 review
- 5 个不同文件的并行 lint 修复
- 多目录的并行代码搜索 / 关键字定位
- `frontend` / `backend` / `docs` 三个独立模块的并行研究

不适合派的场景：

- 任务有顺序依赖（B 必须等 A 完成）
- 多个子任务改同一个文件、`schema`、`package.json`、`lockfile`
- 单一目标的 bug 修复（根因未明时）

`SubAgent` 的核心价值不只是「并行加速」，更是**保护主 Agent 的上下文**：让它不必把 50 个文件的搜索结果塞进自己的窗口。

### Skills 渐进披露的能力封装

`Skills` 是 `Claude` 体系里相对新的设计，它把「让 Claude 做某类专业任务」从「每次重写一遍 prompt」升级为「一次定义、按需加载」。

`Skills` 用渐进披露（Progressive Disclosure）架构：

1. **元数据扫描**：~100 tokens，判断当前任务和哪些 Skill 相关
2. **完整加载**：`SKILL.md` 内容（约 5k tokens），含具体步骤、注意事项
3. **资源按需**：脚本、模板、参考文件，只在真要执行时才入栈

这个设计让你能挂几十个 `Skills` 而不撑爆上下文。`frontend-design`、`figma-use`、`ship`、`code-review`、`investigate`、`dev-guide` —— 每一个都是封装好的「领域专家」。

### Hooks 事件总线

`Hooks` 是 `Claude Code` 的事件钩子系统。它在固定时刻（`SessionStart`、`UserPromptSubmit`、`PreToolUse`、`PostToolUse`、`Stop`）执行你定义的 shell 命令，命令的输出会被注入到 Agent 的对话上下文里。

`Hooks` 解决一个核心问题：**那些「每次都要做」的事情，不能靠 Claude 记住，要靠系统强制执行**。比如：

- `SessionStart`：注入项目最新 git 状态、当前分支、未提交文件
- `PreToolUse`：拦截危险命令（如 `rm -rf` 路径校验、`git push --force` 二次确认）
- `PostToolUse`：测试跑完自动追加结果到上下文
- `Stop`：要求 Claude 跑完任务必须输出验证证据

记住一个判定：**「从现在起 / 每次 / 在 X 之前都要 Y」这种自动化诉求只能用 Hooks 实现**，不能写进 memory 或 CLAUDE.md（那只是文字提醒，没有强制力）。

### MCP Servers 外挂能力

`MCP`（Model Context Protocol）是把外部系统接入 AI Agent 的标准协议。你可以接 `Figma`、`GitHub`、禅道、`Linear`、自建数据库 —— 接好后 Agent 就拥有了「操作这些系统」的能力。

接 MCP 时要注意三条护栏：

- **只暴露最小工具集**：禅道 MCP 没必要把所有 REST API 都开，只开「读 bug、读详情、加评论」就够了
- **Token 缓存与 HTTPS 强约束**：避免每次调用都重新登录、避免明文传输
- **路径白名单**：上传 / 写文件类工具必须限制相对路径

### Permission 信任边界

`Permission` 系统决定了 Claude 在没有人类确认的情况下能跑哪些命令。默认大量动作（`Bash`、`Edit`、`Write`、MCP 工具）会触发确认弹窗。

聪明的做法不是「全部 allow」，而是**精细化 allowlist**：

```json
{
  "permissions": {
    "allow": [
      "Bash(yarn tsc)",
      "Bash(yarn lint)",
      "Bash(yarn build:*)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)",
      "Bash(curl:* | sh)"
    ]
  }
}
```

只读、可逆、低风险的命令放 allow；破坏性命令放 deny 兜底。这样既减少打断，又给关键动作留确认环节。

## 三、CLAUDE.md 的三层优先级模型

`CLAUDE.md` 是 `Claude Code` 的「项目宪法」。它不是一次性 prompt，而是每次会话都会被加载的**持久化指令集**。

优先级是这样设计的：

1. **用户当下指令**（最高）
2. **项目级 `CLAUDE.md`**（当前工作目录）
3. **全局 `~/.claude/CLAUDE.md`**
4. **系统默认 prompt**（最低）

这套优先级让你能做出**分层治理**：

- 全局层写「我所有项目都遵守的原则」（比如：禁止 AI 主动 push、危险命令必须二次确认）
- 项目层写「这个仓库特有的事实」（技术栈、命令清单、UI 双栈规则、部署方式）
- 任务层（用户消息）覆盖前两层做临时调整

一份好的项目级 `CLAUDE.md` 通常包含：项目身份、技术栈速查、命令清单、路径别名、UI 选用规则、提交规则、护栏、Change Delivery Gate（完成 / commit / push 之前必须满足什么）。

## 四、治理：把 AI 接进团队 SOP

光有架构不够，要把它变成团队能跑的流程。下面是一个真实落地过的三层分工：

- **规范层（`OpenSpec`）**：影响对外行为 / API / SEO / 部署形态的变更，走 `/opsx:propose`，产出 `proposal.md` + `design.md` + `tasks.md`
- **流程层（`superpowers`）**：plan / brainstorm / debug / TDD / verify / code review
- **执行层（`gstack`）**：浏览器 / QA / ship / deploy / canary / 危险命令护栏

类比一下：`OpenSpec` 是蓝图，`superpowers` 是大脑，`gstack` 是手脚。

配套的 Change Delivery Gate（声明完成、准备 commit 之前必须满足）：

1. 已完成相关验证，并如实报告结果
2. 已过对应质量门禁（review / verification）
3. 关键验证无法执行时必须明确说明原因
4. 禁止虚构命令输出
5. 没有验证证据，不得声称「通过」/「完成」

可接受的证据形式：测试输出真实日志、`/qa` 报告、`/browse` 截图、`/canary` 部署后比对、type checker 与 linter 的真实输出。**「证据优先」是把 AI 拉回工程纪律的关键约束**。

## 五、轻 / 中 / 大任务分流

不是所有任务都要走完整流程，那是过度工程。按任务规模分流：

| 任务规模 | 典型场景 | 推荐流程 |
| --- | --- | --- |
| 只读 | 解释代码、架构问题 | 直接答 |
| 轻量 | 单文件 bug、文案、配置 | 直接改 + 定向验证 |
| 中等 | 多文件新功能、明确重构 | `/opsx:propose` + 短 brainstorm + 实现 + `/browse` 或 `/qa` |
| 重量 | 跨模块、共享逻辑、新架构、公共 API | 完整闭环：spec → plan → executing-plans + worktree + TDD → `/qa` → review → `/ship` → `/canary` |

判定方法：**变更是否影响对外可观察行为 / 接口契约 / 数据形状 / 公共 API？** 是 → 中或重；否 → 轻量。这是一条很实用的快速判断线。

## 六、常见反模式与修复

下面这些坑大多数人都踩过，逐条对照能省很多返工。

### 反模式 1：CLAUDE.md 当一次性 prompt

写一长串「这次任务请注意 X、Y、Z」，结果下次会话全忘了。

**修复**：把通用规则沉淀进项目 `CLAUDE.md`，把项目独有 SOP 拆成 `skill`，把强制行为升级为 `hooks`。

### 反模式 2：滥用 SubAgent 改同一文件

「并行才快」于是开 5 个子代理同时改 `package.json`，结果互相覆盖。

**修复**：`package.json` / `yarn.lock` / `tsconfig` / 根配置 / `schema` 默认串行。子任务必须独立、无共享状态、可独立验证。

### 反模式 3：跳过 verification 直接声明完成

最常见的「AI 说通过了」其实根本没跑过测试。

**修复**：Change Delivery Gate 强制要求证据。配 `Stop` hook 拦截无证据的「完成」表述。

### 反模式 4：MCP 全开导致权限滥发

接一个新 MCP server，把它所有工具都加进 allowlist。

---

> 以上是免费部分。完整内容需要「前端进阶之旅」会员，原文：https://feinterview.poetries.top/blog/claude-code-engineering-architecture-governance