01. Claude Code 底层技术全景导览

核心认知转变

Claude Code = 可编程、可扩展、可组合的 AI Agent 框架

• 不是"工具"，而是"平台"
• 不仅仅是被动使用（你问我答），而是主动驾驭（配置 Agent 自主工作）

对比：被动使用 vs 主动驾驭

被动使用（你问我答）	主动驾驭（配置 Agent 自主工作）
"帮我review这段代码"	配置 Hook，每次Edit自动审查
"跑一下测试"	配置 SubAgent，有PR自动跑测试
"检查安全问题"	配置 Skill，提到安全自动触发
"每天同步代码"	配置 Headless + CI/CD，定时执行

核心洞察：主动驾驭的本质是把重复性工作交给 Claude 配置完成，你只需设置一次，之后 Claude 自动化执行。

四层技术架构

层级	组件	职责
编程接口层	Agent SDK (编程调用)	完全编程控制
集成层	Headless (CI/CD集成) + MCP (外部工具)	连接外部世界
扩展层	Commands (手动) / Skills (自动) / SubAgents (手动/自动) / Hooks (事件触发)	核心能力中心
基础层	Memory 记忆系统	持久化上下文

层级关系：上层依赖下层，从下往上构建

• 基础层 → 扩展层 → 集成层 → 编程接口层

基础层：Memory 记忆系统

CLAUDE.md

~/.claude/CLAUDE.md           # 全局（所有项目共用）
./CLAUDE.md                   # 项目级（当前项目）
./.claude/rules/*.md         # 模块级（特定目录）

Claude 每次开始对话时，都会读 CLAUDE.md 文件， 全局、项目和项目的特定模块都可以拥有属于自己的记忆文件

作用

• 提供项目代码风格
• 定义 Git 提交规范
• 说明项目架构
• 标注禁区

全局示例

# 公司代码规范

## Git 提交规范
- feat: 新功能
- fix: Bug 修复
- docs: 文档更新
- style: 代码格式
- refactor: 重构
- test: 测试相关
- chore: 构建/工具

## 代码风格
- 缩进 2 空格
- 方法行数不超过 50 行
- 类注释必填，作者和日期

## 安全规范
- 禁止提交密钥/Token
- 敏感配置用环境变量

## 注释规范
- 公共方法必加 JavaDoc
- 复杂逻辑加行内注释

## 禁止操作
- 禁止 hardcode 敏感信息
- 禁止删除注释代码
- 禁止直接操作主分支

扩展层：四大核心组件

1. Commands（斜杠命令）

触发方式	适用场景
用户手动输入 /command	标准化操作、团队统一流程

# 示例
/review     # 代码审查
/commit     # 统一提交格式

2. Skills（技能）

触发方式	适用场景
自动判断（语义推理）	领域化能力、需要 LLM 判断
手动指定	明确调用特定 Skill

Java 开发示例：SQL 审查 Skill

# .claude/skills/sql-review/SKILL.md
---
name: sql-review
description: SQL 审查技能。检查 Java 项目中 Mapper.xml、@Query、JDBC 等 SQL 代码，识别性能和安全问题。触发条件：提到"检查 SQL"、"sql-review"、"检查 mapper"、"检查 MyBatis"等关键词。
allowed-tools: Grep, Read
---

# SQL 审查 Skill


...

```bash
# 自动触发：修改了 Mapper 文件
# 手动触发
使用 sql-review skill 帮我检查 UserMapper.xml

与 Commands 的区别：

• Commands：显式、固化、标准流程
• Skills：隐式、领域感、专家判断

3. SubAgents（子代理）

触发方式	适用场景
Claude 决定或用户指定	隔离执行、高噪声任务

# 主 Claude 创建子代理处理大量测试
# 子代理(test-runner) 执行测试，结果汇报给主 Claude

适用场景：

• 高噪声任务（日志分析、大量文档检索）
• 需要特定权限的任务
• 隔离执行避免污染主上下文

本质上解决的是单一 Agent 的上下文、权限和职责无法无限膨胀。

4. Hooks（钩子）

触发方式	适用场景
事件自动触发	自动化检查、格式化、安全审查

# 事件：Claude 即将执行 Edit 工具
# Hook：自动检查安全敏感内容
# 结果：发现问题则阻止执行并警告

集成层：连接外部世界

Headless（无头模式）

无头模式让 Claude Code 在没有人工交互的情况下运行，适合 CI/CD 集成——自动代码审查、自动修复、自动生成变更日志等。

• CI/CD 集成
• 自动代码审查
• 无人值守运行

真实例子：CI/CD 集成

# 定时任务：每日代码扫描
# crontab
0 8 * * * claude --headless "Scan src/ for security vulnerabilities, \
  generate report, send to security@company.com"

MCP（Model Context Protocol）

• 连接外部工具和服务
• 数据库、Jira、自定义 API

Claude → MCP → 数据库
Claude → MCP → Jira

编程接口层：Agent SDK

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

from claude_sdk import ClaudeSDKClient
client = ClaudeSDKClient()
result = client.query(prompt="Review code", tools=["Read", "Grep"])

技术选型指南

触发方式对比

组件	触发方式	确定性	适用场景
Commands	手动输入	100% 固定	标准化操作、团队统一流程
Skills	自动判断/手动	概率性	领域专家判断、代码审查
SubAgents	手动/自动	可控	隔离执行、并行处理
Hooks	事件触发	100% 固定	工具执行时自动检查

决策树

是"能力"还是"流程"？
├── 能力 → 需要手动触发？ → Commands
├── 能力 → 需要自动判断？ → Skills
├── 检查机制 → 工具执行时触发？ → Hooks
└── 隔离任务 → 需要特定权限？ → SubAgents

场景速查表

需求	方案
统一 commit 格式	Commands
自动检查代码安全	Hooks
查询内部知识库	MCP
执行大量测试	SubAgents
CI/CD 自动化	Headless
自定义工作流	Agent SDK

完整示例

假设你正在开发一个 Spring Boot 订单系统，Claude 帮你修复一个安全漏洞的完整流程：

┌─────────────────────────────────────────────────────────────────────┐
│ 1. Memory 层：加载 CLAUDE.md                                       │
│    → 了解到这是 Spring Boot 2.7 项目                               │
│    → 团队要求：所有安全修复必须附带单元测试                          │
│    → 禁止直接操作主分支                                            │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│ 2. 扩展层分发                                                       │
│    a. 用户没有输入 / 命令 → Commands 不参与                        │
│    b. 识别"安全漏洞"关键词 → 激活 sql-review Skill                │
│    c. Skill 指示创建子代理执行测试 → 激活 test-runner SubAgent    │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│ 3. Hooks 监控                                                      │
│    准备执行 Edit 工具时                                             │
│    → 自动检查：是否引入新的 SQL 注入风险                            │
│    → 自动检查：是否使用了硬编码密码                                  │
│    → 检查通过才允许修改                                            │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│ 4. 工具执行                                                        │
│    → Read 读取 OrderMapper.xml                                     │
│    → Edit 修复 SQL 注入                                            │
│    → Write 新增 OrderMapperTest 单元测试                           │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│ 5. MCP 连接（可选）                                                │
│    → 自动更新 Jira ticket 状态为 "Fixed"                           │
│    → 发送飞书通知给负责人                                           │
└─────────────────────────────────────────────────────────────────────┘

关键点：整个过程你只需说"修复订单查询的 SQL 注入漏洞"，其余全部自动化。

---

Plugins：打包机制

把 Commands、Skills、Hooks 组合打包成可分发插件：

my-plugin/
├── commands/     # 斜杠命令
├── skills/       # 技能
├── agents/       # 子代理
├── hooks/        # 钩子
└── plugin.json   # 插件配置

总结

层级	组件	职责
基础层	Memory	让 Claude 记住项目规范
扩展层	Commands/Skills/SubAgents/Hooks	核心能力中心，按需激活
集成层	Headless/MCP	融入 CI/CD，连接外部世界
编程层	Agent SDK	完全编程控制

核心洞察：

• Memory 是基础设施，始终存在
• 扩展层是能力中心，按需激活
• Hooks 是守门人，监控一切
• 组件可组合，形成完整自动化流程