Claude Code执行过程详解

分层任务拆解与计划固化（/plan/task）

顶层拆分的基本思路是：将总目标拆解为若干串行依赖的阶段，例如环境初始化→数据库层→接口层→前端→单元测试→上线校验，按阶段顺序推进，不可跳跃。

每个阶段需进一步切分为更细粒度的任务切片，每个切片对应独立的/task条目，并附带明确的验收标准、依赖关系以及所用工具。除清单外，还需预留风险控制：高风险步骤，如大规模文件删除、数据库结构变更，中间必须插入人工确认节点，防止误操作。资源分配方面，每个子任务需设定 token 上限和最大工具调用轮数，避免单一步骤耗尽上下文资源。

阶段2：核心底层——单Agent迭代执行循环（queryLoop引擎）

所有长任务的最小执行单元即为 queryLoop 引擎。其本质是一个无限循环——只要存在工具调用或任务未完成，循环持续运行。这是 Claude Code 的基础执行内核，底层采用异步生成器 AsyncGenerator，流式输出状态，不会阻塞上层会话。

一轮完整循环遵循以下7步标准流程：

上下文组装预处理 → 大模型推理决策 → 工具调用分发 → 权限安全校验 → 多工具并行执行 → 工具结果回写会话 → 判定终止/下一轮循环

上下文压缩方面，需精挑细选保留内容：总任务目标、项目核心架构、关键代码变更、验收标准，这些不可丢弃；其他辅助信息可适当省略。

多层验收校验（防止半成品交付）

1. 自动化工具校验：自动执行测试套件、Lint、构建脚本、数据库迁移脚本，验证功能是否正常；
2. 逻辑对抗校验 Agent：针对产出代码和方案进行反向漏洞推演，排查潜在问题；
3. 目标对齐校验：对比原始需求，核查是否存在子目标遗漏或约束偏离。校验失败时直接回退至对应任务节点，调整方案后重新迭代。

中断恢复机制（超长跨天任务核心能力）

1. 会话意外关闭或终端断开时，自动保存当前 State（任务计划、压缩快照、已完成子任务）；
2. 重启会话后执行/state读取完整进度，从最近 Compact 断点续跑，无需重新扫描项目；
3. Workflow 编排任务同样支持断点续跑：已完成的并行子 Agent 结果会缓存，避免重复执行。

queryLoop核心定位与设计目标

1. 定位

queryLoop 是 Claude Code 所有代码自主执行的最小内核，一个同步/异步的状态机循环引擎。无论是简单单文件修改，还是超大工程任务中的子智能体，底层均复用该循环逻辑。Dynamic Workflow 的 Subagent、普通对话代码模式、终端 Claude Code 插件，共享同一套 queryLoop 实现。

2. 核心设计目标（针对复杂长任务痛点）

1. 标准化工具调用生命周期，统一处理文件读写、Shell、Git、搜索、MCP 插件；
2. 内置多层上下文治理，持续抑制长会话 Token 膨胀和上下文腐烂；
3. 强容错：工具超时、报错、幻觉调用、上下文超限，均内置重试或降级逻辑；
4. 可观测、可断点存储：每一轮状态固化，支持回滚、暂停、续跑；
5. 分层安全拦截，所有外部操作统一通过权限网关。

3. 底层实现形态

工程层面为异步生成器 AsyncGenerator，流式吐出执行状态（思考日志、工具执行进度、压缩提示、报错），不会阻塞上层会话服务。全局仅持有一个 SessionState 状态对象，所有轮次共享该可变上下文。

queryLoop全局依赖组件（循环前置底座）

循环启动前，必须初始化全套依赖，缺一不可：

1. System Prompt 固定基座：内置代码 Agent 行为约束、全部工具 Schema、输出格式规范、终止条件、安全红线。长任务模式会追加「分步规划、定期校验、主动压缩上下文」等强制指令。
2. SessionState 全局状态存储：循环的唯一数据源，字段包括：
   • messages：历史对话 + 工具输入输出消息列表
   • compactSnapshots：历史上下文压缩快照（断点）
   • taskPlan：顶层拆解的任务分阶段计划
   • toolCallBudget：本轮会话剩余工具调用轮数上限
   • fileCache：高频读取文件缓存（cache_control 驱动，减少重复读文件消耗 Token）
   • permissionAudit：文件 / Shell 操作授权记录
   • errorLog：工具执行失败栈，用于重试策略
3. ContextCompressor 分层压缩管线：独立模块，循环每轮推理前自动执行7层裁剪，是长任务稳定的核心。
4. ToolOrchestrator 工具调度器：负责并行/串行工具分发、沙箱隔离、超时控制、结果序列化。
5. SecurityGateway 安全权限网关：deny-first 拦截模型高危操作，区分自动放行、弹窗确认、直接阻断三类。
6. TerminationJudge 终止判定器：输入模型输出内容，判断是否需要继续循环。

步骤6：工具结果回写 SessionState 持久化

1. 将所有 tool_result 消息追加到全局 messages 列表，永久留存；
2. 更新 fileCache：本次读取的文件内容写入内存缓存，下一轮无需重复读取；
3. 更新 errorLog：记录失败工具、报错信息、重试次数；
4. 更新 toolCallBudget：扣除本轮消耗的工具调用配额，达到上限直接终止循环。

queryLoop内置关键容错机制（长复杂任务专用）

1. 工具幻觉修复：模型调用不存在的工具、参数缺失、参数类型错误时，tool orchestrator 返回明确格式化错误，写入 tool_result，下一轮模型会基于报错修正调用参数，无需人工介入。
2. 循环死锁熔断：检测到连续5轮完全相同的工具调用（如无限重复读同一文件、重复执行同一失败命令），触发熔断，自动执行一次全局 compact 并提醒用户任务陷入循环。
3. 断点快照自动保存：每执行10轮循环自动生成一份 compactSnapshots 存入 SessionState；用户可通过 /rewind 回退至任意快照，从历史节点重新跑循环，适配跨天超长任务中断恢复。
4. 预算分级限流：单会话全局工具轮数上限 + 单轮并行工具数量上限双重限制，防止无限制大规模扫描仓库消耗资源。

taskPlan 数据结构示例：

{
  "stages": [
    {
      "stageId": "scan_project",
      "title": "扫描项目目录",
      "completed": true,
      "acceptance": ["读取根目录文件树，梳理依赖"],
      "subTasks": []
    },
    {
      "stageId": "refactor_service",
      "title": "重构用户服务代码",
      "completed": false,
      "acceptance": ["修改User.ja va", "修复单元测试", "Lint无报错"],
      "subTasks": ["修改实体类", "重构接口", "执行测试"]
    }
  ]
}