Claude Code Complete Guide V2 · 中文架构导读

模型是内核，
Harness 才是系统。

Claude Code 的工作，不是“问一次模型，拿一次答案”。它把上下文、模型推理、工具执行、权限闸门、状态存储和验证组织成一个持续回环，直到任务完成、预算耗尽或被安全策略终止。

186左栏正文页面
20主体篇章
44,653Markdown 行
8核心循环步骤
$ claude “修复登录超时并验证”

01 装配规则、环境、记忆与历史
02 模型判断下一步
03 申请读取 / 搜索 / 执行工具
04 Hook + 权限 + 沙箱审查
05 执行并把结果回注
06 继续循环，直到给出可验证结论

result = 代码改动 + 测试证据 + 解释
01 / SYSTEM

总架构：六个平面围绕一条“心脏”运转

点击任一模块查看职责。真正的中心不是 UI，也不是某个工具，而是负责“准备 → 调模型 → 执行 → 回注 → 再判断”的 QueryEngine。

最重要的边界：模型看不到硬盘，也不会直接执行命令。它只看到被装配进上下文的文本，以及工具返回的结构化结果；副作用必须经过工具层与权限层。

→
交互入口
CLI/TUI、IDE Bridge、MCP 服务模式、SDK 是不同入口。它们负责收发信息，但尽量复用同一套编排主轴。
控制面

Prompt + Policy

告诉模型“应该怎样做”，并在工具执行前做真正的硬检查。

数据面

Messages + Tool Results

消息、流式片段、工具意图和工具结果持续穿过主循环。

状态面

AppState + Disk

当前会话在内存中演进，需要保留的部分再被投影到磁盘。

02 / LOOP

一次任务怎么跑：八步 Agent Loop

点击步骤看输入、动作与产出。只要模型还请求工具，结果就会回注历史并开始下一圈。

01 准备消息

输入：历史、项目规则、检索记忆、工具说明、环境。动作：估算窗口，必要时压缩。产出：可发送的 system + messages。

为什么流式？

逐字渲染降低体感延迟，同时增量拼出 tool_use；用户也能随时中断。

何时继续？

存在 tool_use 且预算允许：执行工具，把 tool_result 加进历史，再问模型。

何时结束？

无工具请求、预算耗尽、用户取消、致命错误或压缩熔断。

为什么不是死循环？

每一圈都有三重预算和明确退出条件，异步生成器持续向 UI 发事件。

03 / CONTEXT

上下文：模型的“工作台”，不是数据库

它装着当前需要推理的材料。容量一紧张，系统先删低价值体积，再做摘要，最后重建一份可续写的任务骨架。

静态宪法身份、行为、安全、工具总则；稳定前缀便于缓存
动态政策会话、环境、CLAUDE.md、MCP、预算
对话历史user / assistant / tool 的证据链
压缩旧工具输出清理、摘要、九节骨架
模型请求模型此刻能看到的全部世界
低成本

清旧输出

优先清理早期、巨大的工具结果，教学口径保留最近 5 个结果，用户原话和系统提示通常不动。

为什么先做它

工具日志常是最大的上下文膨胀源；结构化剪枝无需再调用模型，稳定且便宜。

风险

如果只删除不留指针，后续可能知道“跑过测试”却不知道测试结果。

约 87%

触发摘要

指南采用约 87% 作为教学阈值，由策略自动折叠历史；具体数字随产品版本变化。

连续失败保护

教学模型中连续 3 次失败则熔断，避免重复付费和无休止抖动。

用户怎么介入

可主动用 /compact 给出焦点：“保留复现步骤、架构决策和未完成任务”。

最后手段

九节摘要重建任务状态

保留：意图、概念、文件、错误、用户要点、任务、当前工作、环境/风险，以及剥离中间推理后留下的已验证结论。它压缩的是对话，不会替你保存 Git 改动。

三层别混：上下文是“现在正在桌面上的材料”；会话历史是“可恢复的过程记录”；长期记忆是“未来会话可能重新取出的知识”。压缩会改造上下文，但不等于可靠持久化。
04 / MEMORY

记忆怎么用：观察 → 卡片 → 检索 → 注入 → 纠正

记忆的目标不是“记得越多越好”，而是让未来会话少走弯路。点击阶段查看输入、存储与控制点。

观察
从用户明确表达、反复纠正和项目行为中发现潜在偏好或事实。单次试验不能直接变成长期真相。
会话记忆

当前消息与工具轨迹

最鲜活，也最容易因关闭、压缩或新会话而离开热上下文。

项目记忆

CLAUDE.md 层级

全局 → 项目根 → 子目录 → 本地个人文件。适合命令、架构、禁区和团队约定；窄作用域通常更具体。

自动记忆

本地项目记忆目录

偏好与重复痛点以可检索卡片落盘。路径和格式属于版本相关实现，必须可审计、可删除。

一张记忆卡片的教学结构

字段作用例子
id稳定引用与去重mem_7f3a
title给检索器快速判断包管理：优先 pnpm
description1–3 句可执行描述此项目使用 pnpm；命令示例不要用 npm。
scope避免跨项目污染project:acme/web
confidence / time支持审计、衰减与冲突处理0.82 / 2026-04-01

KAIROS / dream 做什么

低活跃或人工触发时，把流水账批量蒸馏成两类卡片：用户偏好与项目背景。重复项合并、一次性试错丢弃、冲突进入人工确认。

检索为何“精确优先”

快模型先扫标题/描述，按项目范围、相关性、时间等信号排序；不确定就注入 0 条。无关记忆会吃 token、扰乱注意力，还可能放大旧错误。

重要真实性说明：指南把自动记忆、双模型检索、KAIROS 与文件形态作为“源码解读 + 教学模型”介绍，多处明确写着路径、阈值、字段和命令以版本实现为准。这里保留其机制，不把示意 JSON 当成稳定官方契约。
05 / GOVERNANCE

模型想动手，还要过两套闸门

工具治理管线负责“调用是否完整、合规、可审计”；权限管线负责“这次副作用到底能不能发生”。

工具治理 · 14 步教学模型

CALL QUALITY
  1. 解析原始 tool_call
  2. Schema 校验
  3. 业务 validateInput
  4. 风险预分类
  5. PreToolUse 拦截或改写
  6. 正式权限决策
  7. 归一化最终输入
  8. 执行 tool.call()
  9. 遥测：耗时、结果、trace
  10. PostToolUse
  11. 统一 ToolResult
  12. 输出再校验
  13. 敏感字段脱敏
  14. 大结果裁剪 / 引用

权限评估 · 7 步

SIDE EFFECT
  1. 工具级 deny：硬拒
  2. 工具级 ask：询问或沙箱例外
  3. Bash AST / Edit 路径专项检查
  4. 工具实现层拒绝
  5. 当前模式是否要求用户确认
  6. 内容级敏感检查
  7. .git、.claude、shell 配置等护栏

规则心智：deny → ask → allow；无明确许可时倾向 fail-closed。

File tools

Read / Edit / NotebookEdit 强调先读后写、路径净化、冲突检测。

Search tools

Glob 找文件，Grep 找文本，LSP 找语义，ToolSearch 按需发现能力。

Bash

不是任意 shell 透传；解析命令结构、检查黑名单、环境和写入边界。

MCP tools

外部服务器动态提供 schema 与 instructions，但同样进入治理和权限链。

为什么工具失败也要回注？错误、拒绝、stderr 都被包装成结构化 tool_result，模型才能换方案、自我修正，而不是把一次失败误判成系统停止。
06 / EXTEND

扩展生态：规则、流程、拦截与外部能力各有位置

这些模块看似都在“教 Claude 做事”，实际作用层不同。混在一起会造成权限含糊、提示膨胀和维护失控。

CLAUDE.md

仓库事实与长期协作约定：怎么运行、怎么测试、架构在哪、什么不能碰。

PROJECT MEMORY
Skills

Markdown + 元数据的可发现 SOP；匹配场景时注入正文，并可声明 allowed-tools。

WORKFLOW
Slash Commands

用户显式触发的命令入口，把固定流程变成可重复操作。

USER ENTRY
Subagents

独立上下文执行探索、规划、实现或验证；向父 Agent 返回蒸馏结果。

DELEGATION
Hooks

SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、Stop 六类生命周期回调。

GOVERNANCE
Plugins

带 manifest、命令、资源和配置的重型扩展包，可要求某些能力只能由用户显式触发。

PACKAGE
MCP

通过协议动态发现外部 tools/resources/instructions；连接外界，但不绕过本地权限。

PROTOCOL

提示层

CLAUDE.md 和 Skills 主要改变模型“知道什么、按什么流程想”。

执行层

Commands、Plugins、MCP 提供新的入口或能力，但必须注册到工具运行时。

治理层

Hooks 与 PermissionPipeline 能真实阻止、改写和审计副作用。

配置与作用域：从稳定到当轮

层适合放什么变化频率
静态系统规范身份、行为、安全底线、工具总则版本级
组织 / 全局设置企业策略、用户通用偏好、Feature Flags低
项目根 CLAUDE.md仓库命令、技术栈、架构与禁区中
目录级 CLAUDE.md子模块特有规则；更贴近工作目录中
本地个人文件个人路径、偏好；通常不提交 Git中
会话动态层当前目标、环境、MCP、检索记忆、剩余预算每轮
07 / STATE

状态、会话与 Bridge：时间和入口如何被统一

运行时状态先在内存中变更，副作用层再决定哪些写进磁盘。IDE 不是第二套 Agent，而是经 Bridge 接到同一条主轴。

启动 / 迁移校验 settings 版本，加载配置与记忆索引
AppStatesession · tools · ui · config
dispatch / reducer纯函数更新状态
effects渲染、遥测、写盘、网络
磁盘settings · mem · sessions
Transcript

保真事件流

JSONL 追加 user / assistant / tool / system 事件，支持审计和尾部恢复。

Checkpoint

恢复快照

保存消息游标、摘要与大工具结果引用；用空间换恢复速度。

Meta

环境身份

记录 sessionId、cwd、模型、CLI 版本与父会话；resume 前必须做健康检查。

claude -c 的心智模型

定位当前项目最近的健康会话 → 读取最新 checkpoint → 加载 transcript 尾部 → hydrate 到 AppState → 检查 cwd、模型和工具版本漂移。

Bridge 的心智模型

IDE 通过 stdio / socket / WebSocket 等传输，用 JSON-RPC 风格消息与 CLI 核心双向通信；JWT、会话隔离、分帧和背压保障连接边界。

状态先真，世界后追：reducer 不直接写文件或发网络；effects 订阅状态变化并负责外部 I/O。这样才能测试、迁移、恢复和审计。
08 / AGENTS

多 Agent：不是开更多模型，而是切分责任与上下文

父 Agent 负责拆分、派工、合并和最终负责；子 Agent 在隔离上下文中完成一个清晰任务，再把证据蒸馏回来。

READ

Explore

只读探索代码、定位入口、收集证据；不改文件。

DESIGN

Plan

基于现状给阶段、测试、回滚与开放问题；不施工。

BUILD

Worker / General

在明确边界里实施任务，输出改动、证据和未解决问题。

COORDINATE

Coordinator

组织并行与串行阶段，避免多人改同一文件，处理结果冲突。

BREAK IT

Verification

独立验证，主动寻找反例；输出 PASS / FAIL / PARTIAL 与实测证据。

BOUNDARY

防递归

指南采用一层派工心智：子 Agent 不再生成子 Agent，复杂拆分回到父层。

父 Agent 定义工单目标、范围、约束、交付格式
子 Agent 独立处理各自上下文、工具白名单与预算
蒸馏返回结论、证据、未解决项
父 Agent 合并处理冲突，决定下一阶段
独立验证尝试破坏，不为实现者背书

并行适合互不写同一状态的探索；有依赖或文件冲突时必须串行。多 Agent 的收益来自隔离和分工，不来自“人数”。

09 / WALKTHROUGH

完整案例：修复“登录偶发超时”到底发生了什么

从用户一句话到可交付结果，点击左侧阶段逐步理解每个模块何时上场。

01 接单与装配

用户输入进入 UserPromptSubmit。系统加载静态规范、当前仓库 CLAUDE.md、环境、相关记忆和会话历史，估算 token 后形成第一轮请求。

  • 输入：目标“修复偶发超时并验证”
  • 关键模块：Prompt builder、Context、Memory retrieval
  • 产出：模型可见的任务世界
10 / COVERAGE

全书模块索引：20 篇 + 前言 + 附录

可搜索和筛选。数字是对应目录中的 Markdown 页面数；左栏合计 186 页，另有站点首页和下载页，共 188 个 Markdown 文件。

P00 · 4页

前言

路线图、术语、环境与阅读方法。

P01 · 5页

背景故事

源码事件、规模、社区重建与法律伦理。

P02 · 8页

快速上手

安装、对话、文件、命令、Git 与成本。

P03 · 10页

架构全景

四入口、目录、数据流、启动与设计哲学。

P04 · 12页

QueryEngine

八步循环、流式、工具收集、预算与终止。

P05 · 10页

提示词工程

静态宪法、动态政策、缓存边界与工具手册。

P06 · 12页

工具系统

42 工具、接口、治理管线、Bash、MCP。

P07 · 10页

权限与安全

六种模式、七步权限、AST 与沙箱。

P08 · 10页

上下文管理

三层压缩、缓存感知、手动 compact。

P09 · 10页

记忆系统

CLAUDE.md、自动提取、检索、KAIROS、持久化。

P10 · 12页

多 Agent

六角色、协调、验证、缓存与防递归。

P11 · 10页

终端 UI

自研渲染、Yoga、Fiber、流式与虚拟滚动。

P12 · 10页

Bridge

CLI ↔ IDE、协议、JWT、会话与传输。

P13 · 8页

状态管理

Store、effects、Memdir、History 与迁移。

P14 · 8页

服务与集成

API、错误、MCP、LSP、OAuth 与 Flags。

P15 · 6页

隐藏功能

Feature Flags、Undercover、Buddy 与规划实验。

P16 · 8页

Hooks / Skills / Plugins

生命周期、拦截、SOP、命令和延迟加载。

P17 · 8页

性能与成本

Prompt 缓存、预取、懒加载与流式管线。

P18 · 6页

遥测与生命周期

追踪、日志、资源清理、重试与生产运维。

P19 · 8页

实战 Lab

从最简 Loop 到工具、权限、MCP、多 Agent 与整合。

P20 · 6页

总结与展望

壁垒、竞品、趋势、开发者启示与学习路线。

APP · 5页

附录

源码索引、命令、50 题、参考阅读和术语。

资料等级：这是一份第三方、非官方、基于公开仓库与作者所称源码解读的教学材料。书中大量代码明确标注“示意 / 伪代码 / 教学口径”，版本数字、路径、阈值、模型名和功能开关可能变化；学习架构思想可以，做生产配置前应再对照当前官方文档与实际版本。
11 / MENTAL MODEL

真正需要记住的七句话

如果你只复习这一屏，也应该能把 Claude Code 的架构讲给别人听。

Claude Code 是一个带反馈的执行系统，不是聊天壳。

模型提出动作，工具把动作变成现实，结果再回到模型，直到满足结束条件。

QueryEngine 是心脏，LLM 是决策内核。

心脏负责节拍和编排；模型负责判断；工具、权限、存储、UI 都是独立器官。

上下文是工作台，记忆是外置存储，历史是时间轴。

三者互相连接，但生命周期、成本与可信度完全不同。

Prompt 是软控制，Permission / Hook / Sandbox 才是硬控制。

不能只靠“请不要做危险操作”；真正副作用必须在执行前被程序化拦截。

扩展能力越多，越要延迟加载和最小权限。

Skills、Plugins、MCP 不应一次全部塞入上下文，也不能自动获得无限权限。

多 Agent 的价值是隔离责任、并行调查和独立验证。

父 Agent 对目标、冲突和交付负责；Verification 必须尝试推翻实现者结论。

好体验的大部分工作发生在模型之外。

缓存、流式、状态恢复、权限、错误处理、遥测和 UI 一起决定“可靠地把事做完”。

建议的最短阅读路线

先看本页 01 → 02 → 03 → 04 → 05，再回原书读第 3、4、6、7、8、9、13、16 篇；需要亲手实现时进入第 19 篇 Labs。

本次覆盖与快照

以仓库提交 27f164468e…（2026-04-03）为基线，核对左栏 186 页；仓库共 188 个 Markdown 文件、44,653 行。