Claude Code 深度解析：功能介绍与实现原理

一、概述

Claude Code 是 Anthropic 推出的终端原生 AI 编程智能体。它不是一个 IDE 插件或代码补全工具，而是一个运行在终端中的完整智能体——能够自主读取代码库、编辑文件、执行命令、管理 Git 工作流，并以最少的人工干预完成复杂的软件工程任务。

首次发布：2025 年 2 月 24 日（研究预览版，随 Claude 3.7 Sonnet 发布）
正式 GA：2025 年 5 月 22 日（Anthropic "Code with Claude" 开发者大会）
技术栈：Node.js CLI（TypeScript 实现）
底层模型：Claude Opus 4.6 / Sonnet 4.6 / Haiku 4.5
上下文窗口：200K tokens
SDK：@anthropic-ai/claude-agent-sdk（开源，Apache 2.0）

二、核心架构与实现原理

2.1 双系统架构（Two-System Architecture）

Claude Code 的架构由两个独立系统组成：

┌─────────────────────────┐          HTTPS           ┌──────────────────────┐
│   Claude Code CLI       │ ◄──────────────────────► │   Claude Model       │
│   (本地 Node.js 进程)    │    Anthropic Messages    │   (Anthropic 服务器)  │
│                         │         API              │                      │
│  • 工具执行器            │                          │  • 推理引擎           │
│  • 权限管理器            │                          │  • 工具调用决策        │
│  • 上下文管理器          │                          │  • 代码生成           │
│  • Hooks 引擎           │                          │  • 扩展思考           │
│  • 文件系统操作          │                          │                      │
└─────────────────────────┘                          └──────────────────────┘

关键设计理念：Claude Code CLI 本身不包含任何 AI 能力。它是一个纯粹的协调器和执行器——所有推理、决策和代码生成都发生在 Anthropic 服务器上的 Claude 模型中。CLI 负责的是：收集上下文、执行工具调用、管理权限、维护对话状态。

2.2 智能体循环（Agent Loop）

Agent Loop 是 Claude Code 的核心执行引擎，遵循一个简洁的四步循环：

                    ┌──────────────────────────────────────┐
                    │                                      │
                    ▼                                      │
        ┌───────────────────┐                              │
   ①    │  接收提示          │                              │
        │  (Prompt + 系统提  │                              │
        │   示 + 工具定义 +  │                              │
        │   对话历史)        │                              │
        └────────┬──────────┘                              │
                 │                                         │
                 ▼                                         │
        ┌───────────────────┐                              │
   ②    │  模型评估与响应     │     有工具调用？             │
        │  (Claude 决定下    │────── 是 ──────┐            │
        │   一步动作)        │                │            │
        └────────┬──────────┘                │            │
                 │ 否（纯文本响应）             │            │
                 │                           ▼            │
                 ▼                  ┌─────────────────┐   │
        ┌───────────────────┐  ③   │  执行工具调用     │   │
        │  返回最终结果       │      │  (Bash/Read/     │   │
        │  (结束循环)        │      │   Write/Edit...) │   │
        └───────────────────┘      └────────┬────────┘   │
                                            │            │
                                            │  ④ 将工具  │
                                            │  结果追加   │
                                            │  到对话历史  │
                                            └────────────┘

步骤详解：

接收提示（Receive Prompt）：将用户输入、系统提示（System Prompt）、工具定义（JSON Schema 格式）和完整对话历史打包发送给 Claude 模型
评估与响应（Evaluate & Respond）：Claude 分析当前状态，决定下一步——返回纯文本、发起一个或多个工具调用、或两者兼有。支持并行工具调用
执行工具（Execute Tools）：SDK/CLI 在本地执行工具调用（文件读取、Shell 命令等），将结果作为 tool_result 消息追加到对话中
循环（Repeat）：步骤 2-3 不断循环，直到 Claude 产生一个不包含工具调用的响应

设计哲学：

无独立规划模型：没有单独的 planner 或 orchestrator——一个上下文窗口、一个模型、逐轮累积状态
单线程可调试：当出错时，可以追踪一个线性的工具调用序列，而不是调试分布式消息传递
简单可组合：Anthropic 的研究表明，最可靠的智能体实现使用的是简单、可组合的模式，重点在工具设计而非复杂的多智能体协调

2.3 工具调用协议（Tool Use Protocol）

工具调用是连接模型与执行环境的核心协议。模型从不直接执行工具，而是返回结构化的请求：

json

{
  "type": "tool_use",
  "id": "toolu_01ABC123",
  "name": "Edit",
  "input": {
    "file_path": "src/utils.ts",
    "old_string": "function add(a, b) {",
    "new_string": "function add(a: number, b: number): number {"
  }
}

CLI 收到请求后：

检查权限（是否需要用户确认）
触发 PreToolUse Hook（可拦截/修改/阻止）
执行工具操作
触发 PostToolUse Hook
将结果返回给模型，让模型基于实际结果决定下一步

这种"请求-执行-反馈"模式意味着模型是反应式的——它根据每次工具执行的真实结果调整策略，而不是预先规划一个固定的执行序列。

三、内建工具体系

Claude Code 的工具体系是其核心能力的基础。每个工具都以 JSON Schema 形式定义，注入到系统提示中。

3.1 工具总览

工具名	功能	需要权限	分类
Read	读取文件内容（支持图片/PDF/Jupyter）	否	文件操作
Write	创建或覆写文件	是	文件操作
Edit	对文件进行精准的局部编辑	是	文件操作
Glob	按模式匹配查找文件（基于文件系统索引）	否	搜索
Grep	按正则搜索文件内容（基于 ripgrep）	否	搜索
Bash	执行 Shell 命令	是	系统交互
WebFetch	获取 URL 内容	是	网络
Task	创建和管理子智能体任务	是	智能体编排
TodoWrite	管理会话任务清单	否	任务管理

3.2 各工具详解

Read — 文件读取

参数：
  - path (必选): 文件绝对路径
  - offset (可选): 起始行号（支持负数，从末尾计算）
  - limit (可选): 读取行数

特性：
  - 支持文本文件、图片（jpeg/png/gif/webp）、PDF、Jupyter Notebook
  - 输出带行号：LINE_NUMBER|LINE_CONTENT
  - 文件为空时返回 "File is empty."

Write — 文件写入

参数：
  - path (必选): 文件绝对路径
  - contents (必选): 写入内容

特性：
  - 覆写模式（如文件已存在则替换）
  - 会自动创建不存在的父目录

Edit — 精准编辑

参数：
  - file_path (必选): 文件路径
  - old_string (必选): 要替换的原文本（必须唯一匹配）
  - new_string (必选): 替换后的文本
  - replace_all (可选): 是否替换所有匹配项

特性：
  - 基于精确字符串匹配的替换，非正则
  - 保留原始缩进
  - old_string 必须在文件中唯一，否则失败

Bash — Shell 命令执行

参数：
  - command (必选): 要执行的命令
  - description (可选): 5-10 词描述
  - timeout (可选): 超时时间（默认 120s，最大 600s）
  - run_in_background (可选): 是否后台运行

特性：
  - 有状态的 Shell 会话（工作目录和环境变量在调用间持久化）
  - 支持后台运行长时间命令
  - 内建命令黑名单（默认阻止 curl、wget 等）

Glob — 文件模式匹配

参数：
  - glob_pattern (必选): 匹配模式（如 "**/*.ts"）
  - target_directory (可选): 搜索目录

特性：
  - 基于文件系统索引，极快
  - 结果按修改时间排序
  - 自动添加 "**/" 前缀以支持递归搜索

Grep — 内容搜索

参数：
  - pattern (必选): 正则表达式模式
  - path (可选): 搜索路径
  - glob (可选): 文件过滤模式
  - output_mode (可选): content / files_with_matches / count

特性：
  - 基于 ripgrep 构建，支持并行处理
  - 支持上下文行显示（-A/-B/-C 参数）
  - 支持多行匹配（multiline 参数）
  - 结果上限为数千行，防止输出过大

Task — 子智能体任务

参数：
  - prompt (必选): 任务描述
  - description (必选): 3-5 词简述
  - model (可选): 使用的模型（fast 等）
  - subagent_type (可选): explore / generalPurpose / shell / browser-use
  - readonly (可选): 是否只读模式

特性：
  - 每个子智能体拥有独立的上下文窗口
  - 深度限制为 1（子智能体不可再生成子智能体）
  - 仅摘要结果返回给父对话

四、系统提示工程（System Prompt Engineering）

4.1 动态组装架构

Claude Code 的系统提示不是一个静态文本，而是动态组装的模块化体系。据公开分析，Claude Code 包含 110+ 个专用指令片段，根据当前模式、工具集、子智能体类型和会话状态动态拼接。

系统提示组装流程：

  ┌─────────────────┐
  │  Anthropic 核心  │  ← 定义安全边界、核心能力、行为准则
  │  指令（~16K tokens）│
  └────────┬────────┘
           │
  ┌────────▼────────┐
  │  工具定义        │  ← 18+ 工具的 JSON Schema（每个 900-51K tokens）
  │  (Tool Schemas)  │
  └────────┬────────┘
           │
  ┌────────▼────────┐
  │  模式特定指令     │  ← Plan Mode / Agent Mode / Ask Mode 各有不同指令
  └────────┬────────┘
           │
  ┌────────▼────────┐
  │  CLAUDE.md 文件  │  ← 用户自定义的项目级/全局指令
  └────────┬────────┘
           │
  ┌────────▼────────┐
  │  当前状态注入     │  ← 打开的文件、终端状态、Git 状态等
  └────────┬────────┘
           │
  ┌────────▼────────┐
  │  最终系统提示     │  ← 发送给 Claude 模型
  └─────────────────┘

4.2 核心指令片段分类

分类	数量	示例
核心行为指令	~15	代码编辑规范、安全准则、通信方式
内建工具描述	18+	Write、Bash、TodoWrite、Task 等
子智能体提示	~8	Plan、Explore、Delegate、Agent 等模式
工具类提示	~10	CLAUDE.md 生成、WebFetch、安全审查
模式切换指令	~5	Plan Mode、Ask Mode、Debug Mode
格式与输出指令	~10	代码引用格式、Markdown 规范、行号处理

4.3 CLAUDE.md 指令层次

CLAUDE.md 是用户可控的"记忆"机制，按作用域分层加载：

优先级（高 → 低）：

1. 托管配置（Managed）       ← 企业 IT 强制策略
2. 项目本地（.claude/settings.local.json）← 个人项目配置
3. 项目共享（CLAUDE.md）     ← 团队共享，提交到 Git
4. 目录级别（src/CLAUDE.md） ← 特定目录的约定
5. 用户全局（~/.claude/CLAUDE.md）← 个人全局偏好
6. Anthropic 内建指令        ← 基础行为框架

CLAUDE.md 的执行遵循率约 ~80%（非确定性，由模型判断执行），而 Hooks 的执行率为 100%（确定性，无条件执行）。

五、上下文窗口管理与压缩系统

5.1 上下文窗口空间分配

Claude Code 的 200K token 上下文窗口并非全部可用，其空间被多个固定组件占据：

200K tokens 总容量
├── 系统提示                ~20K tokens（固定）
├── MCP 工具 Schema        ~900 - 51K tokens（按配置变化）
├── CLAUDE.md 文件          ~1K - 5K tokens（按项目变化）
├── 模型输出预留缓冲        ~10K tokens（固定）
└── 实际可用对话空间        ~100K - 140K tokens（动态）

随着对话深入，工具结果（文件内容、命令输出、搜索结果）会迅速消耗可用空间。这就是压缩系统存在的原因。

5.2 三层压缩架构（Three-Layer Compaction）

      空间充裕                     空间紧张                    接近上限
         │                           │                          │
         ▼                           ▼                          ▼
  ┌──────────────┐           ┌──────────────┐          ┌──────────────┐
  │ 微压缩        │           │ 自动压缩      │          │ 手动压缩      │
  │ Microcompact  │           │ Auto-compact  │          │ /compact     │
  │              │           │              │          │              │
  │ 大型工具输出   │           │ 95% 容量时    │          │ 用户主动触发   │
  │ 卸载到磁盘    │           │ 自动触发       │          │ 可指定焦点     │
  └──────────────┘           └──────────────┘          └──────────────┘

微压缩（Microcompaction）

触发条件：工具输出（Read/Bash/Grep/Glob/WebFetch/Edit/Write）体积过大时自动触发

实现原理：

将大型工具结果保存到磁盘文件
上下文中仅保留引用路径
近期工具结果保持完整可见（"热尾"），较早的结果转为引用（"冷存储"）

对话上下文视角：

  [最近 3 次工具调用] → 完整内容可见（Hot Tail）
  [第 4-N 次工具调用] → 仅保留摘要 + 磁盘路径引用（Cold Storage）

自动压缩（Auto-Compaction）

触发条件：上下文使用率达到约 95%（~190K tokens）

执行流程：

检测当前上下文占用，评估是否需要压缩（极短会话跳过）
移除旧的文件读取、Grep 结果和命令输出（通常压缩 60%-80% 的上下文）
将对话历史总结为结构化的"工作状态"文档
从磁盘重新加载 CLAUDE.md 文件（确保项目指令不丢失）
注入延续指令（continuation instructions），保持任务动量

不仅是总结：自动压缩还会恢复最近编辑的文件列表、保留活跃的任务清单、注入"继续当前工作"的提示，确保压缩后的 Claude 能无缝延续之前的任务。

手动压缩（Manual Compaction）

bash

/compact                          # 默认压缩
/compact Focus on the API changes  # 带焦点提示的定向压缩

建议在任务边界处手动触发，避免关键上下文在自动压缩中丢失。

六、权限与安全体系

6.1 分层权限模型

                    ┌─────────────────┐
                    │  拒绝规则 (Deny)  │  ← 最高优先级，不可覆盖
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  询问规则 (Ask)   │  ← 需要用户确认
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  允许规则 (Allow) │  ← 自动批准
                    └─────────────────┘

规则评估顺序：Deny > Ask > Allow

工具权限分类：

权限级别	工具	行为
自动允许（无需权限）	Read, Glob, Grep, TodoWrite	只读操作，安全无副作用
默认询问（需确认）	Write, Edit, Bash, WebFetch, Task	有副作用的修改操作
可配置阻止	自定义	通过 Deny 规则阻止特定命令

6.2 权限模式（Permission Modes）

模式	标志	行为	适用场景
Default	默认	每次工具调用都询问	日常开发
Accept Edits	`--accept-edits`	自动批准文件编辑，命令仍询问	信任编辑但审查命令
Plan	`--plan`	只规划，不执行	审查方案
Auto	`--auto`	半自主执行，后台安全检查	批量任务
Don't Ask	配置项	未预批准的操作自动拒绝	CI/CD 环境
Bypass	`--bypass-permissions`	跳过所有提示（保护 .git/.claude 等）	隔离沙箱

6.3 沙箱隔离机制

Claude Code 使用操作系统原生机制进行隔离：

文件系统隔离：

默认：项目目录及子目录可读写
父目录：只读（无显式权限不可修改）
实现方式：macOS 使用 Seatbelt，Linux/WSL2 使用 bubblewrap

网络隔离：

通过代理服务器实现域名限制
仅可访问已批准的域名
限制适用于所有子进程

内建安全防护：

命令黑名单（默认阻止 curl、wget 等可下载外部内容的命令）
输入清理（防止命令注入）
上下文感知的有害指令分析
凭据安全存储

6.4 权限配置示例

json

// .claude/settings.json（团队共享）
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git *)",
      "Bash(npx prettier *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Write(.env*)",
      "Write(credentials/*)"
    ]
  }
}

七、Hooks 系统

7.1 概述

Hooks 是用户定义的确定性自动化动作，在 Claude Code 生命周期的特定时间点 100% 执行（与 CLAUDE.md 指令的 ~80% 遵循率形成对比）。

7.2 Hook 类型

类型	执行方式	示例
Shell Hook	执行本地 Shell 命令	编辑后自动运行 lint
HTTP Hook	向外部服务发送 POST 请求	通知 Slack/Webhook
Prompt Hook	单轮 LLM 评估（是/否判断）	安全审查门控
Agent Hook	生成子智能体执行任务	自动编写测试

7.3 生命周期事件（22+ 个）

会话生命周期：
  SessionStart → UserPromptSubmit → ... → Stop → SessionEnd

工具执行：
  PreToolUse → [执行工具] → PostToolUse / PostToolUseFailure

子智能体：
  SubagentStart → [子智能体执行] → SubagentStop

上下文管理：
  FileChanged → ConfigChange → PreCompact → PostCompact

权限与任务：
  PermissionRequest → TaskCreated → TaskCompleted → Elicitation

7.4 Hook 执行流程

事件触发
    │
    ▼
收集注册的 Hooks
    │
    ▼
Matcher 模式匹配过滤
    │
    ▼
执行 Hook 回调
    │
    ├── Shell: 通过 stdin 传入 JSON 事件数据
    ├── HTTP: 以 POST Body 发送事件数据
    ├── Prompt: 发送给 LLM 进行评估
    └── Agent: 生成子智能体
    │
    ▼
返回决策
    │
    ├── allow（允许继续）
    ├── block（阻止操作）
    ├── modify（修改参数）
    └── inject（注入额外上下文）

7.5 典型 Hook 配置

json

// .claude/hooks.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": { "tool_name": "Edit", "file_pattern": "*.ts" },
        "type": "shell",
        "command": "npx eslint --fix ${file_path}"
      }
    ],
    "PreToolUse": [
      {
        "matcher": { "tool_name": "Write", "file_pattern": ".env*" },
        "type": "prompt",
        "prompt": "Is this write operation safe? Does it contain any secrets or credentials?",
        "on_fail": "block"
      }
    ],
    "SessionStart": [
      {
        "type": "shell",
        "command": "echo 'Session started at $(date)' >> ~/.claude/session.log"
      }
    ]
  }
}

八、子智能体系统（Subagents）

8.1 架构设计

子智能体是 Claude Code 实现并行任务处理的核心机制。每个子智能体拥有：

独立上下文窗口：不占用主对话的上下文空间
定制系统提示：针对特定任务优化
受限工具集：根据角色限制可用工具
继承权限：继承父对话的权限配置

┌───────────────────────────────────────────────────┐
│  主对话（Parent Conversation）                      │
│  上下文窗口: 200K tokens                            │
│                                                    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐         │
│  │ Explore  │  │ General  │  │ Custom   │         │
│  │ 子智能体  │  │ Purpose  │  │ 子智能体  │         │
│  │          │  │ 子智能体  │  │          │         │
│  │ 独立上下文│  │ 独立上下文│  │ 独立上下文│         │
│  │ 只读工具  │  │ 全部工具  │  │ 自定义   │         │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘         │
│       │             │             │                │
│       └─────────────┼─────────────┘                │
│                     │                              │
│              仅返回摘要结果                           │
└───────────────────────────────────────────────────┘

约束：子智能体不可再生成子智能体（深度限制 = 1）

8.2 内建子智能体类型

子智能体	模型	工具权限	用途
Explore	Haiku（快速低延迟）	只读（禁止 Write/Edit）	代码库探索、文件发现、搜索
Plan	取决于配置	只读	Plan Mode 下的代码库研究
General Purpose	默认模型	全部工具	复杂多步骤任务、代码修改
Shell	快速模型	Bash 为主	命令执行、Git 操作
Browser-Use	默认模型	浏览器工具	前端测试、Web 自动化

8.3 Explore 子智能体的深度配置

Explore 子智能体支持三个彻底程度级别：

quick：基础搜索，适合已知位置的快速查找
medium：中等探索，跨多个目录搜索
very thorough：全面分析，跨多个位置和命名约定深度搜索

8.4 Agent Teams（并行编排）

Agent Teams 是 Claude Code 的高级子智能体能力，允许多个子智能体并行工作：

bash

# Claude 可能自动拆分为多个并行子任务：
"重构这个模块的数据库层，添加缓存，并更新所有相关测试"

# 实际执行：
├── Explore 子智能体 → 分析现有数据库层结构
├── General Purpose 子智能体 1 → 重构数据库层
├── General Purpose 子智能体 2 → 实现缓存层
└── General Purpose 子智能体 3 → 更新测试文件

九、扩展思考（Extended Thinking）

9.1 工作原理

扩展思考允许 Claude 在产生最终响应前进行隐藏的内部推理。模型将一部分输出 Token 分配为"思考 Token"，用于逐步推理，然后才生成最终答案。

普通模式：
  用户输入 → [Claude 生成响应] → 输出

扩展思考模式：
  用户输入 → [Claude 内部推理（thinking tokens）] → [生成最终响应] → 输出
                     │
                     └── 对用户可见为 "thinking" 块

9.2 API 响应结构

json

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze the architecture...\n1. The current implementation...\n2. The bottleneck is..."
    },
    {
      "type": "text",
      "text": "Based on my analysis, here are the recommended changes..."
    }
  ]
}

9.3 配置方式

方式	命令/配置	说明
会话内切换	`/think`	当前会话启用
全局配置	`.claude/settings.json`	所有会话默认启用
API 参数	`thinking: {type: "enabled", budget_tokens: N}`	手动设置思考预算
自适应	`effort: "low" / "medium" / "high"`	模型自动调整思考深度

9.4 适用场景

场景	扩展思考价值
架构设计决策	高 — 需要权衡多方因素
安全审查	高 — 需要系统性分析
间歇性 Bug 调试	高 — 需要推理因果链
多步骤重构实现	高 — 需要全局规划
简单代码生成	低 — 直接生成即可
直接的重命名/格式化	低 — 无需深度推理

十、MCP（Model Context Protocol）集成

10.1 MCP 架构

MCP 是 Claude Code 连接外部工具和服务的标准协议，使其能力从内建工具扩展到 3000+ 外部服务。

┌─────────────┐      MCP       ┌──────────────────────────┐
│ Claude Code │ ◄────────────► │  MCP Server              │
│             │   (标准协议)    │  ├── GitHub Issues        │
│  ┌────────┐ │               │  ├── Database Query        │
│  │MCP     │ │               │  ├── Sentry Errors         │
│  │Client  │ │               │  ├── Figma Designs         │
│  └────────┘ │               │  ├── Jira/Linear Tasks     │
│             │               │  └── Custom Services...    │
└─────────────┘               └──────────────────────────┘

10.2 MCP Server 类型

类型	通信方式	适用场景
HTTP Server	HTTP 请求/响应	远程服务（推荐）
Stdio Server	标准输入/输出	本地进程，需直接系统访问
SSE Server	Server-Sent Events	流式通信（已废弃）

10.3 典型 MCP 工作流

bash

# 从 Issue Tracker 获取需求 → 理解代码库 → 实现功能 → 提交 PR
Claude: "实现 GitHub Issue #42 中描述的用户注册功能"

执行流程：
1. [MCP: GitHub] 读取 Issue #42 的详细描述
2. [内建: Grep/Glob] 分析现有代码库结构
3. [内建: Read] 读取相关文件
4. [内建: Edit/Write] 实现功能代码
5. [内建: Bash] 运行测试
6. [内建: Bash] git commit & push
7. [MCP: GitHub] 创建 Pull Request

十一、记忆系统（Memory System）

11.1 三层记忆架构

时间跨度：  会话内           跨会话             永久
           │               │                  │
           ▼               ▼                  ▼
    ┌──────────────┐ ┌──────────────┐  ┌──────────────┐
    │ 会话记忆      │ │ 自动记忆      │  │ 项目记忆      │
    │ Session      │ │ Auto Memory  │  │ CLAUDE.md    │
    │              │ │              │  │              │
    │ 对话上下文    │ │ Claude 自动   │  │ 用户手动编写   │
    │ 工具结果      │ │ 写入的笔记    │  │ 提交到 Git    │
    │ 会话结束丢失  │ │ 跨会话持久化  │  │ 团队共享       │
    └──────────────┘ └──────────────┘  └──────────────┘

11.2 CLAUDE.md 最佳实践

markdown

# CLAUDE.md 推荐内容（50-200 行）

## 构建命令
- `npm run build` — 构建生产版本
- `npm run test` — 运行测试（Jest）
- `npm run lint` — ESLint 检查

## 架构约定
- 使用 Repository 模式访问数据库
- 所有 API 响应使用统一的 Result<T> 类型
- 错误处理使用自定义 AppError 层次结构

## 编码规范
- TypeScript strict 模式
- 函数优先于类（除 Repository 和 Service 外）
- 测试文件与源文件并列放置（*.test.ts）

## 不要做的事
- 不要直接在 Controller 中写 SQL
- 不要使用 any 类型
- 不要跳过错误处理

十二、使用模式与交互方式

12.1 四种核心使用模式

bash

# 1. 交互模式（默认）—— 多轮对话
claude

# 2. 单次模式 —— 一次性任务
claude "解释这个函数的作用"

# 3. 管道模式 —— 将外部数据作为上下文
git diff | claude "review this change"
cat error.log | claude "分析这个错误"
find . -name "*.ts" | head -20 | claude "这个项目的结构是什么"

# 4. 恢复模式 —— 继续之前的对话
claude --resume                    # 恢复最近的会话
claude --resume <session-id>       # 恢复指定会话

12.2 关键 CLI 标志

标志	功能	示例
`--model`	指定模型	`claude --model claude-opus-4-6`
`--plan`	计划模式（只规划不执行）	`claude --plan "重构数据库层"`
`--accept-edits`	自动批准编辑	`claude --accept-edits "修复 lint 错误"`
`--output-format`	输出格式	`claude --output-format json "分析代码"`
`--max-turns`	限制最大轮次	`claude --max-turns 10 "完成这个任务"`
`--resume`	恢复会话	`claude --resume`

12.3 内建斜杠命令

命令	功能
`/compact`	手动触发上下文压缩
`/clear`	清空对话，开始新会话
`/model`	切换模型
`/think`	启用/禁用扩展思考
`/cost`	显示当前会话的 Token 使用量和费用
`/doctor`	诊断 Claude Code 配置问题
`/fast`	切换到快速模型
`/help`	显示帮助信息
`/config`	打开配置界面

十三、SDK 与编程接口

13.1 Claude Agent SDK

Claude Code 的核心能力通过 @anthropic-ai/claude-agent-sdk（TypeScript，开源 Apache 2.0）暴露给开发者：

bash

npm install @anthropic-ai/claude-agent-sdk

13.2 核心 API

typescript

import { query, tool, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';

// query() — 主交互函数，返回异步生成器流式传输消息
const stream = query({
  prompt: "重构这个模块",
  systemPrompt: "你是一个 TypeScript 专家",
  tools: [myCustomTool],
  model: "claude-sonnet-4-6",
});

for await (const message of stream) {
  console.log(message);
}

// tool() — 创建类型安全的工具定义（使用 Zod Schema 验证）
const myTool = tool({
  name: "database_query",
  description: "执行数据库查询",
  parameters: z.object({
    sql: z.string().describe("SQL 查询语句"),
    database: z.string().optional().describe("数据库名"),
  }),
  annotations: {
    readOnly: true,
    openWorld: false,
  },
  execute: async ({ sql, database }) => {
    return await db.query(sql, database);
  },
});

// createSdkMcpServer() — 创建进程内 MCP 服务器
const mcpServer = createSdkMcpServer({
  tools: [myTool],
});

13.3 工具注解（Tool Annotations）

注解	类型	含义
`readOnly`	boolean	工具只读取数据，不修改状态
`destructive`	boolean	工具可能造成不可逆的变更
`idempotent`	boolean	重复调用产生相同结果
`openWorld`	boolean	工具访问外部世界（网络/API）

十四、与其他工具的差异化优势

14.1 Claude Code 的核心竞争力

维度	Claude Code 优势	对比
推理深度	扩展思考 + Opus 4.6 模型	独立评测 9.0/10（Codex 8.6，Gemini 8.3）
Agent Teams	多子智能体并行编排	业界领先的并行任务能力
Hooks 系统	22+ 生命周期事件的确定性自动化	独特的"100% 执行保证"机制
IDE 集成	VS Code + JetBrains 原生支持	同时覆盖终端和 IDE 用户
企业就绪	分层权限 + 沙箱 + 托管配置	完善的企业安全治理
生态广度	3000+ MCP 服务集成	最丰富的外部工具连接

14.2 局限性

成本较高：平均任务成本 $0.50-$3.00，重度使用日费用可能较高
上下文窗口：200K tokens 相比 Gemini 的 1M tokens 较小
非完全开源：SDK 开源，但 CLI 本身未完全开源
网络依赖：所有推理发生在 Anthropic 服务器，无法离线使用
模型绑定：仅支持 Claude 模型系列

十五、总结

Claude Code 的技术架构可以用一句话概括：一个极其精密的工具编排层（本地 CLI）+ 一个极其强大的推理引擎（云端 Claude 模型）。

它的核心设计理念是简洁性——没有复杂的多智能体通信总线，没有独立的规划引擎，就是一个循环：收集上下文 → 模型推理 → 执行工具 → 反馈结果。这种简洁性带来了可调试性和可靠性。

而在这个简洁的核心之上，Hooks 系统提供了确定性的自动化能力，子智能体系统提供了并行处理能力，MCP 提供了无限的扩展能力，三层压缩系统解决了长时间任务的上下文管理问题。这些模块化的能力层层叠加，构成了当前市场上推理质量最高的 AI 编程智能体。

docs

hook

watcher

Claude Code 深度解析：功能介绍与实现原理 ​

一、概述 ​

二、核心架构与实现原理 ​

2.1 双系统架构（Two-System Architecture） ​

2.2 智能体循环（Agent Loop） ​

2.3 工具调用协议（Tool Use Protocol） ​

三、内建工具体系 ​

3.1 工具总览 ​

3.2 各工具详解 ​

Read — 文件读取 ​

Write — 文件写入 ​

Edit — 精准编辑 ​

Bash — Shell 命令执行 ​

Glob — 文件模式匹配 ​

Grep — 内容搜索 ​

Task — 子智能体任务 ​

四、系统提示工程（System Prompt Engineering） ​

4.1 动态组装架构 ​

4.2 核心指令片段分类 ​

4.3 CLAUDE.md 指令层次 ​

五、上下文窗口管理与压缩系统 ​

5.1 上下文窗口空间分配 ​

5.2 三层压缩架构（Three-Layer Compaction） ​

微压缩（Microcompaction） ​

自动压缩（Auto-Compaction） ​

手动压缩（Manual Compaction） ​

六、权限与安全体系 ​

6.1 分层权限模型 ​

6.2 权限模式（Permission Modes） ​

6.3 沙箱隔离机制 ​

6.4 权限配置示例 ​

七、Hooks 系统 ​

7.1 概述 ​

7.2 Hook 类型 ​

7.3 生命周期事件（22+ 个） ​

7.4 Hook 执行流程 ​

7.5 典型 Hook 配置 ​

八、子智能体系统（Subagents） ​

8.1 架构设计 ​

8.2 内建子智能体类型 ​

8.3 Explore 子智能体的深度配置 ​

8.4 Agent Teams（并行编排） ​

九、扩展思考（Extended Thinking） ​

9.1 工作原理 ​

9.2 API 响应结构 ​

9.3 配置方式 ​

9.4 适用场景 ​

十、MCP（Model Context Protocol）集成 ​

10.1 MCP 架构 ​

10.2 MCP Server 类型 ​

10.3 典型 MCP 工作流 ​

十一、记忆系统（Memory System） ​

11.1 三层记忆架构 ​

11.2 CLAUDE.md 最佳实践 ​

十二、使用模式与交互方式 ​

12.1 四种核心使用模式 ​

12.2 关键 CLI 标志 ​

12.3 内建斜杠命令 ​

十三、SDK 与编程接口 ​

13.1 Claude Agent SDK ​

13.2 核心 API ​

13.3 工具注解（Tool Annotations） ​

十四、与其他工具的差异化优势 ​

14.1 Claude Code 的核心竞争力 ​

14.2 局限性 ​

十五、总结 ​

Claude Code 深度解析：功能介绍与实现原理

一、概述

二、核心架构与实现原理

2.1 双系统架构（Two-System Architecture）

2.2 智能体循环（Agent Loop）

2.3 工具调用协议（Tool Use Protocol）

三、内建工具体系

3.1 工具总览

3.2 各工具详解

Read — 文件读取

Write — 文件写入

Edit — 精准编辑

Bash — Shell 命令执行

Glob — 文件模式匹配

Grep — 内容搜索

Task — 子智能体任务

四、系统提示工程（System Prompt Engineering）

4.1 动态组装架构

4.2 核心指令片段分类

4.3 CLAUDE.md 指令层次

五、上下文窗口管理与压缩系统

5.1 上下文窗口空间分配

5.2 三层压缩架构（Three-Layer Compaction）

微压缩（Microcompaction）

自动压缩（Auto-Compaction）

手动压缩（Manual Compaction）

六、权限与安全体系

6.1 分层权限模型

6.2 权限模式（Permission Modes）

6.3 沙箱隔离机制

6.4 权限配置示例

七、Hooks 系统

7.1 概述

7.2 Hook 类型

7.3 生命周期事件（22+ 个）

7.4 Hook 执行流程

7.5 典型 Hook 配置

八、子智能体系统（Subagents）

8.1 架构设计

8.2 内建子智能体类型

8.3 Explore 子智能体的深度配置

8.4 Agent Teams（并行编排）

九、扩展思考（Extended Thinking）

9.1 工作原理

9.2 API 响应结构

9.3 配置方式

9.4 适用场景

十、MCP（Model Context Protocol）集成

10.1 MCP 架构

10.2 MCP Server 类型

10.3 典型 MCP 工作流

十一、记忆系统（Memory System）

11.1 三层记忆架构

11.2 CLAUDE.md 最佳实践

十二、使用模式与交互方式

12.1 四种核心使用模式

12.2 关键 CLI 标志

12.3 内建斜杠命令

十三、SDK 与编程接口

13.1 Claude Agent SDK

13.2 核心 API

13.3 工具注解（Tool Annotations）

十四、与其他工具的差异化优势

14.1 Claude Code 的核心竞争力

14.2 局限性

十五、总结