ClaudeCode 工程化学习 · 基础篇：四层架构全景与组件选型

如果你只会把 Claude Code 当成"会写代码的 ChatGPT"，那你每天都在浪费它 80% 的能力。这篇文章会带你建立 Claude Code 的全景认知，从"提问者"升级为"驾驭者"。

一、概述

本文要解决什么问题

很多开发者用 Claude Code（CC）的方式是这样的：打开终端、输入问题、复制答案、关闭。这种方式我们叫它被动使用——你和 CC 之间是"一问一答"的弱关系。

但 CC 真正的杀手锏是主动驾驭——通过记忆系统、命令、Skill、子代理、Hook、MCP 等扩展机制，让 CC 像一个有 SOP、有团队分工、有自动化质检的"虚拟工程师团队"。

本文要回答的核心问题：

• CC 的能力边界到底在哪里？
• 它的扩展机制是怎样分层的？
• 面对一个具体需求，应该选择 Commands、Skills、SubAgents 还是 Hooks？
• Memory、Skills、SubAgents 这些概念到底是什么关系？

适合谁看

• 已经用过 Claude Code，但觉得"也就那样"的开发者
• 想把 CC 接入团队工作流、CI/CD 的技术负责人
• 想理解 AI 编程工具底层架构的工程师

前置条件

• 已安装 Claude Code（>= 1.0）
• 会基本的命令行操作
• 了解 JSON、YAML 配置文件的写法

---

二、两种使用方式：被动使用 vs 主动驾驭

2.1 被动使用——一问一答

这是最基础的方式：用户 → 输入问题 → Claude 回答 → 完成。

适用场景：临时性的问题排查、代码片段生成、学习新概念。

局限：每次对话都是"从零开始"，没有记忆、没有规范、没有自动化。

2.2 主动驾驭——配置驱动

主动驾驭的链路是：用户 → 配置 agent → agent 自主工作 → 自动完成任务。

差异点对比：

维度	被动使用	主动驾驭
触发方式	手动输入	配置驱动 + 事件触发
记忆能力	无	跨会话记忆
流程规范	临时发挥	可固化、可审计
适用范围	单点问题	团队 SOP、CI/CD

我们这篇文章的核心，就是讲清楚"主动驾驭"背后的四层架构。

---

三、技术全景：CC 的四层架构

CC 的扩展能力可以抽象成四层结构，越往下越接近"基础设施"，越往上越接近"应用场景"：

各层职责速览：

层级	职责	典型组件
基础层	跨会话、跨项目的"共同记忆"	CLAUDE.md
扩展层	标准化、自动化、可复用的能力封装	Commands / Skills / SubAgents / Hooks
集成层	把 CC 接入外部世界	Headless（CI/CD）、MCP（外部工具）
编程接口层	完全用代码控制 CC	Agent SDK

接下来我们逐层展开。

---

四、基础层：Memory 记忆系统（CLAUDE.md）

4.1 是什么

CLAUDE.md 是 CC 的"长期记忆文件"，相当于给 CC 立的"团队规矩"。每次会话开始时，CC 都会自动读取这些文件，把里面的约束、偏好、规范当成"必须遵守的宪法"。

4.2 配置文件的三种粒度

CC 的记忆系统支持三个粒度，从全局到模块依次精确：

粒度	路径	作用范围	典型内容
全局	~/.claude/CLAUDE.md	所有项目共用	个人代码风格、IDE 偏好
项目级	<项目根目录>/CLAUDE.md	当前项目	架构说明、提交规范、禁区
模块级	<项目根目录>/.claude/rules/*.md	特定目录	单个模块的命名约定

💡 经验法则：通用的、个人偏好的放全局；项目相关的、团队约定的放项目级；某个目录独有的放模块级。

4.3 可能写入的内容

• 代码风格：缩进用 2 空格还是 4 空格、引号用单引还是双引
• GIT 提交信息：commit 格式（feat/fix/docs/refactor 等前缀）
• 项目架构：目录结构说明、核心模块职责
• 不能碰的禁区：禁止删除的目录、禁止改动的关键文件、敏感配置

4.4 一个最小可运行的示例

# ~/.claude/CLAUDE.md（全局示例）

## 代码风格
- 使用 2 空格缩进
- 字符串统一使用单引号
- 函数命名使用 camelCase

## Git 提交规范
- 提交信息使用中文
- 格式：`<type>: <description>`
- type 取值：feat / fix / docs / refactor / test

# 项目级 CLAUDE.md（示例）

## 项目架构
- src/components/ 放 UI 组件
- src/services/ 放业务逻辑
- src/utils/ 放工具函数

## 不能碰的禁区
- 不要修改 migrations/ 目录下的任何文件
- 不要删除 .env.example 里的字段

基础层是整个体系的"地基"——其他所有层都建立在 CC 已经"读过这些规矩"的前提之上。

---

五、扩展层：四大核心组件

扩展层是 CC 区别于普通 ChatGPT 的关键。这一层有四个组件：Commands、Skills、SubAgents、Hooks。它们看起来都像"扩展能力"，但触发方式、适用场景、确定性完全不同。

5.1 Commands（斜杠命令）——显式触发的标准流程

是什么：用户在输入框输入 /review，CC 就执行 .claude/commands/review.md 里定义好的流程。

触发方式：显式（用户输入斜杠命令）。

典型场景：

• 团队统一的 commit 格式
• 固定的部署流程
• 标准化的代码审查

特点：100% 确定性——只要用户输入命令，流程必走。

5.2 Skills（技能）——语义推理触发的能力组合

是什么：Skill 是"AI 的专项能力包"，由 CC 通过语义推理自动判断是否启用。

触发方式：语义推理（CC 自己判断）。

典型流程：

用户说："帮我看看这段代码有没有安全问题"
   ↓
CC 思考：这是代码安全审查任务 → 激活 security-review Skill
   ↓
CC 执行：按照 Skill 中定义的流程审查代码

Skills vs Tools 的本质区别——这是初学者最容易混淆的点：

维度	Tools（工具）	Skills（技能）
解决什么问题	我能不能做	我该不该做、怎么做、做到什么程度
本质	外部能力接口（函数调用）	模型内部的"行为模式 + 触发逻辑"
触发逻辑	由模型决定调用哪个	由模型语义推理判断是否激活
类比	像工具箱里的扳手、螺丝刀	像"安全审查专家"这个岗位本身

💡 怎么理解：Skill 就是把 if-else、prompt、策略、调用顺序全部折叠进一个文档的整体封装。当任务具备强烈的"领域感"（安全、架构、性能），执行路径可能因上下文变化时，应该用 Skill 而不是 Tool。

Skills 的适用信号：

• 任务有强烈的领域属性（安全、性能、架构）
• 判断依赖上下文而非关键词
• 执行路径会变化，需要"像专家一样行事"

5.3 SubAgents（子代理）——隔离执行的专项任务

是什么：让 CC 派一个"独立的小 CC"去干一个专项任务，干完只汇报结果。

触发方式：用户或主 CC 触发。

典型流程：

主 CC：这个任务需要跑大量测试，让我创建一个子代理来处理
   ↓
子代理（test-runner）：独立执行测试
   ↓
子代理：把结果汇报给主 CC

适用场景：

• 隔离执行
• 高噪声任务（在大日志中找错误、在大文档中检索资源）
• 需要特定权限的任务

5.4 Hooks（钩子）——事件驱动的自动化检查

是什么：在 CC 执行特定事件时自动触发的脚本。

触发方式：事件自动触发（不需要人输入）。

典型流程：

事件：CC 即将执行 Edit 工具
   ↓
Hook：自动检查是否有安全敏感内容
   ↓
结果：如果发现问题，阻止执行并警告

适用场景：

• 自动化检查（格式化、安全检查、日志记录）
• 不希望每次手动触发的"必须做的事"

5.5 四大组件对照表

组件	触发方式	确定性	适用场景
Commands	用户输入斜杠命令	100%（显式）	标准化操作、团队规范
Skills	CC 语义推理	概率性（隐式）	领域感强、路径变化的任务
SubAgents	用户或 CC 触发	100%（派发后必跑）	高噪声、需隔离的专项任务
Hooks	事件自动触发	100%（事件发生必跑）	自动化检查、日志、安全

---

六、集成层：链接外部世界

6.1 Headless（无头模式）

是什么：让 CC 在没有人工交互的情况下运行，适合 CI/CD 集成。

典型场景：

• 自动代码审查
• 自动修复
• 自动生成变更日志

GitHub Actions 示例：

name: Auto-fix code issues
on: [push]
jobs:
  fix:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: |
          claude --headless "Fix all linting errors in src/"

6.2 MCP（Model Context Protocol）

是什么：把任何外部系统变成 CC 可调用的工具的标准协议。

典型连接：

CC → MCP → 数据库
CC → MCP → Jira
CC → MCP → 自定义 API

MCP 解决了"工具孤岛"问题——只要外部系统实现了 MCP 协议，CC 就能像调用本地工具一样调用它。

---

七、编程接口层：Agent SDK

6.1 什么时候需要 SDK

当配置式的扩展（Commands/Skills/Hooks）不够用时，你可以用代码完全控制 CC。

典型场景：

• 构建自定义 Agent
• 完全控制执行流程
• 自定义工具、复杂工作流

7.2 最小可运行示例

from claude_sdk import ClaudeSDKClient

client = ClaudeSDKClient()

# 执行任务
result = client.query(
    prompt="Review this code for security issues",
    tools=["Read", "Grep"],
    max_turns=10
)
print(result)

📌 版本提示：claude-sdk 当前版本 0.4.x，API 可能在后续版本调整，请以 官方文档 为准。

---

八、选型指南：确定性、可控性、领域感决策三角

四层架构 + 四大组件看起来很多，但选型其实可以收敛到三个核心维度：

8.1 为什么"确定性"很重要

不同任务对"是否每次都执行"的容忍度完全不同：

任务类型	容忍度	推荐选择
代码格式化	必须 100% 执行	Commands / Hooks
安全审查	概率性可接受	Skills
跑测试套件	可手动触发也可自动派发	SubAgents

8.2 决策路线

8.3 选型速查表

你的需求	推荐组件	原因
团队统一的 commit 格式	Commands	标准化 + 必须执行
自动跑测试	Hooks	事件驱动 + 不打扰
让 CC 自动识别安全漏洞	Skills	领域感强 + 路径变化
在大量日志中找错	SubAgents	隔离执行 + 高噪声
CI/CD 自动修复 lint	Headless	无人工 + 集成 CI
接数据库 / Jira	MCP	外部系统标准化

---

九、避坑指南

常见错误	后果	正确做法
把所有规范都写在 CLAUDE.md	文件臃肿，CC 注意力稀释	按粒度拆分：全局 / 项目 / 模块
用 Skills 做"必须每次执行"的事	概率性触发导致偶发遗漏	改用 Commands 或 Hooks
让主 CC 直接跑大型测试	主上下文被测试日志淹没	用 SubAgents 隔离执行
在 Hooks 里写重业务逻辑	Hook 越来越慢	Hook 只做"检查 + 阻断"，业务逻辑交给 Commands
MCP 接一堆用不到的外部系统	上下文被工具描述占满	按需启用，用 disable 配置控制

---

十、总结与思考

核心要点回顾

• CC 的扩展能力分为四层：基础层（Memory）/ 扩展层（四大组件）/ 集成层（Headless + MCP）/ 编程接口层（Agent SDK）。
• 基础层靠 CLAUDE.md 立规矩，按全局 / 项目 / 模块三档粒度拆分。
• 扩展层的四大组件各有适用场景：Commands 重确定性、Skills 重领域感、SubAgents 重隔离、Hooks 重自动化。
• 选型决策收敛到确定性、可控性、领域感三个维度。

局限性声明

本文是"全景图"，每个组件的具体配置细节、调试技巧、最佳实践远不止一篇文章能讲完。比如：

• Skills 的 description 字段怎么写才能让 CC 准确激活？
• Hooks 的输入输出 JSON Schema 怎么自定义？
• MCP Server 怎么自己实现一个？

这些都会在后续章节展开。

下篇预告

进阶篇我们会深入：

• Skills 的 description 工程化调优
• MCP Server 自定义实现
• Agent SDK 构建多 Agent 协作系统

---

互动问题：你目前用 Claude Code 是"被动问答"还是"主动驾驭"？在评论区聊聊你的用法和踩过的坑。

延伸阅读

• Claude Code 官方文档
• Model Context Protocol 规范
• Claude Agent SDK 入门

---

本文是 ClaudeCode 工程化学习 系列的第一篇。系列目录：

• 基础篇：四层架构全景与组件选型（本文）
• 进阶篇：Skills 调优 + MCP 自定义 + Agent SDK 实战（待更新）