从Claude Code的架构设计浅析Agent

AI编程工具的发展正在重新定义编程工作范式，从“执行者”到“指挥者”，并且AI编程工具如Claude Code代表了一种新的人机协作范式

关于Claude Code

什么是Claude Code？

Claude Code不仅仅是一个编程工具，它代表了一种范式，人们在使用它时不再只是把自然语言翻译成代码，而是在做设计、拆解问题、分配任务和组织多个智能体协作完成目标。
Claude Code更是一个可编程、可扩展、可组合的AI Agent框架。

Claude Code的常用命令

claude: 启动交互模式
cluade "任务描述"：执行单次任务
claude -p "问题"：快速查询后退出
claude -c: 继续最近的对话

Usage: claude [options] [command] [prompt]

Claude Code - starts an interactive session by default, use -p/--print for non-interactive output

Arguments:
  prompt                                            Your prompt

.........

Commands:
  doctor                                            Check the health of your Claude Code auto-updater
  install [options] [target]                        Install Claude Code native build. Use [target] to specify version (stable, latest, or specific version)
  mcp                                               Configure and manage MCP servers
  plugin                                            Manage Claude Code plugins
  setup-token                                       Set up a long-lived authentication token (requires Claude subscription)
  update                                            Check for updates and install if available

Claude Code 技术架构

基础层： Memory

Memory是一个记忆系统，它的核心文件是CLAUDE.md, 工作原理则是每次开启对话时，都会读取这个文件。（PS: 这样它就记住了你的项目规范，不需要每次重复说明）

不同级别下的CLAUDE.md文件

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

示例

# Project: E-commerce Platform

## Tech Stack
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL

## Code Style
- Use functional components
- Prefer async/await over .then()
- Maximum line length: 100 characters

## Important Rules
- NEVER commit to main directly
- Always run tests before pushing

扩展层：四大核心组件

Commands(斜杠命令)

是Claude Code内置或用户自定义的一系列核心能力，其触发方式是用户手动输入 /command

是显式、可复用、可审计、通过斜杠命令固定触发的操作指令集，是相对固化的标准流程。

Commands 适合标准化操作：团队统一的commit格式、固定的部署流程等。

Skills(技能)

代表着AI的一系列专属能力组合，其触发方式是Claude自动判断（语义推理）是否激活相应技能。Skills可以是CC内置的，也可以是用户自己设定。

与Tools的区别：

Tools是外部能力接口， Skills是模型内部的“行为模式+触发逻辑”。

如果Tools是函数调用，Skill就是把if-else、prompt、策略和调用顺序，全部折叠进一个文档的整体封装，是对一个专有能力集的全面定义

Tools解决的是：我能不能做；Skill解决的是：我该不该做、怎么做、做到什么程度。

Skills的理念：是专家判断，而非流程执行。

SubAgents(子代理)

用于独立完成专项任务。其触发方式可以由Claude决定或用户指定。

原理是：主Claude发送任务，SubAgents执行任务，只把结果汇报给Claude.

适合隔离执行，比如高噪声任务，需求特定权限的任务、从大量日志心中寻找错误信息。

与Skills的关系：

和Skills类似，它本质上解决的是一个在Agent系统模块化必然出现的问题：单一Agent的上下文、权限与职责无法无限膨胀。

Hooks(钩子)

是在特定事件触发自动执行的脚本，其触发方式是事件自动触发。

适合自动化检查类的任务：如格式化、安全检查、日志记录等

集成层：连接外部信息

Headless(无头模式)

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

1
2
3

# GitHub Actions 中
- name: Auto-fix code issues
  run: claude --headless "Fix all linting errors in src/"

MCP(Model Context Protocol)

MCP让Claude连接外部工具和服务，适合工具连接，可以把任何外部系统变成Claude可调用的工具。

编程接口层

Agent SDK

当配置式的扩展不够用时，可以用代码来驱动Claude.这种方式适合构建自定义Agent，完全控制执行流程、自定义工具、复杂工作流。

from claude_sdk import ClaudeSDKClient

client = ClaudeSDKClient()

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

Plugins:打包

当开发了一套好用的Command、Skills、Hooks组合，想要分享给团队或社区时，就需要用Plugins打包。

Plugins不是一种新能力，而是打包机制，类似npm打包js文件。Plugins把一组相关的Claude Code扩展打包在一起。

Plugins的价值在于可复用、可版本化、可分发。

my-team-plugin/
├── commands/           # 斜杠命令
│   └── review.md
├── skills/             # 技能
│   └── security-check/
│       └── SKILL.md
├── agents/             # 子代理
│   └── test-runner.md
├── hooks/              # 钩子
│   └── pre-edit.sh
└── plugin.json         # 插件配置

四大核心组件场景与选型对照表

组件	本质定位	谁触发	决策权在谁	适合解决的问题	不适合做什么	典型一句话总结
Commands (斜杠命令)	人工触发的标准操作流程（SOP）	用户 / command	人	固定流程、可复现操作、团队统一规范	依赖语义判断、需要灵活决策的任务	“按我写好的步骤，严格执行”
Skills (技能)	模型内部的专家行为模式	Claude自动（语义推理）	模型	领域能力、上下文判断、策略可变的问题	纯机械、无判断空间的操作	“我判断这是我的专业领域，让我像专家一样来”
SubAgents (子代理)	独立上下文与权限的执行单元	Claude或用户	架构设计	高噪声任务、权限隔离、并行处理	简单一步就能完成的任务	“这件事我不亲自干，交给专人处理”
Hooks (钩子)	事件触发的强制规则	系统事件	系统事件	安全、合规、自动化校验	需要权衡、讨论、模糊判断的事情	“不管你想不想，这条规则必须执行”

Agent协作的常见的痛点与解决方案

Memory

解决Agent每次对话都“从零开始”、不理解项目背景的问题，让AI真正记住你的代码结构、约束和上下文。

Sub-Agents

解决单一Agent角色混乱、上下文污染、又写代码又审查的问题，通过职责拆分实现关注点分离。

Skills

解决Prompt不可复用、经验无法沉淀、团队能力难以传承的问题，把个人技巧变成可组合的工程资产。

Hooks

解决Agent执行过程不可控、缺乏检查点、容易“越权操作”的问题，在关键点引入自动校验和人工兜底。

Headless

解决Agent只能在IDE里交互、无法自动化流程的问题，让AI能在CI/CD中无人值守地运行。

Agent SDK

解决只会用对话的方式使用Agent,难以嵌入现有系统和工作流的问题，用代码驱动Agent，构建可编排的工程流程。