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

多数人把 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 帮你写完一行代码就退场，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：

{
  "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 拉回工程纪律的关键约束。

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

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

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

# 六、常见反模式与修复

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

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

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

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

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

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