智能体架构：构建 AI 驱动的开发框架

简而言之：Claude Code并非一个能够访问文件的聊天框，而是一个可编程运行时，拥有30个已记录的生命周期事件。每个事件都可通过模型无法跳过的 shell 脚本接入 hooks。将 hooks 组合成 dispatchers，将 dispatchers 组合成 skills，将 skills 组合成 agents，再将 agents 组合成 workflows，最终便可构建一套自主开发 harness：它能够强制执行约束、委派工作、跨会话持久保存 memory，并编排多 agent deliberation。Claude Code v2.1.147 新增了默认关闭的Workflow工具（CLAUDE_CODE_WORKFLOWS=1），推动确定性的多 agent orchestration 从纯用户空间脚本逐步演变为第一方运行时原语；v2.1.149 则从安全层面进一步印证了同一原则，修复了 PowerShell 权限绕过问题以及 git-worktree sandbox allowlist 问题。hooks 和 evidence gates 仍然负责保障正确性。⁵²⁵³本指南涵盖该技术栈的每一层：从单个 hook 到由10个 agent 组成的共识系统。无需任何框架。全部使用 bash 和 JSON。

Andrej Karpathy 创造了一个术语，用来描述围绕 LLM agent 逐渐形成的系统：claws。它指的是让 agent 能够突破上下文窗口限制、掌控外部世界的 hooks、脚本与 orchestration 机制。¹大多数开发者将 AI 编码 agent 视为交互式助手：输入提示词，看着它编辑文件，然后继续下一项工作。这种思维方式会将生产力限制在您能够亲自监督的范围内。

基础设施式的思维模型截然不同：AI 编码 agent 是一个以 LLM 为内核的可编程运行时。模型执行的每项操作都会经过您控制的 hooks。您定义的是策略，而非提示词。模型在您的基础设施中运行，就像 Web 服务器在 nginx 规则约束下运行一样。您不会守在 nginx 前逐条输入请求，而是对其进行配置、部署和监控。

这种区别至关重要，因为基础设施的收益会不断叠加。一个能够阻止 bash 命令泄露凭据的 hook，可以保护每个会话、每个 agent 和每次自主运行。一个编码了评估标准的 skill，无论由您还是 agent 调用，都能始终如一地执行。一个负责安全代码审查的 agent，无论您是否在旁监督，都会运行相同的检查。²

核心要点

• Hooks 能保证执行，提示词不能。对于代码检查、格式化、安全检查以及任何无论模型如何操作都必须每次运行的任务，请使用 hooks。退出代码2会阻止操作，退出代码1仅发出警告。³
• Skills 封装可自动激活的领域专业知识。description字段决定一切。Claude使用 LLM 推理（而非关键词匹配）来判断何时应用某个 skill。⁴
• Subagents 可防止上下文膨胀。使用隔离的上下文窗口进行探索和分析，能够让主会话保持精简。并行运行彼此独立的 subagents；当工作单元需要持续协作时，则使用 agent teams。⁵
• Memory 存储在文件系统中。文件可跨上下文窗口持久保留。CLAUDE.md、MEMORY.md、rules 目录和 handoff 文档共同构成结构化的外部 memory 系统。⁶
• 多 agent deliberation 能够发现盲点。单个 agent 无法挑战自身的假设。两个拥有不同评估优先级的独立 agent，可以发现 quality gates 无法解决的结构性缺陷。⁷
• Harness 模式本身就是系统。CLAUDE.md、hooks、skills、agents 和 memory 并非相互独立的功能。它们共同构成位于您与模型之间的确定性层，并可随自动化规模一同扩展。

如何使用本指南

各章节层层递进。末尾的决策框架提供了一张查询表，帮助您针对不同问题类型选择合适的机制。

五分钟黄金路径

在深入剖析之前,先来看从零到可用harness的最短路径。一个hook、一个skill、一个subagent、一个成果。

第 1 步:创建一个安全hook(2 分钟)

创建.claude/hooks/block-secrets.sh:

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -qEi '(AKIA|sk-|ghp_|password=)'; then
    echo "BLOCKED: Potential secret in command" >&2
    exit 2
fi

在.claude/settings.json中接入:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/block-secrets.sh" }]
      }
    ]
  }
}

结果:Claude执行的每一条bash命令现在都会被筛查是否泄露凭证。模型无法跳过此检查。

第 2 步:创建一个代码审查skill(1 分钟)

创建.claude/skills/reviewer/SKILL.md,包含frontmatter(name: reviewer、description: Review code for security issues, bugs, and quality problems. Use when examining changes, reviewing PRs, or auditing code.、allowed-tools: Read, Grep, Glob)以及一份检查清单:SQL注入、XSS、硬编码密钥、缺失的错误处理、超过 50 行的函数。

结果:每当您提到review、check或audit时,Claude会自动激活这项专业能力。

第 3 步:派生一个subagent(30 秒)

在任意Claude Code会话中,请Claude使用独立agent审查最近 3 次提交中的安全问题。Claude会派生一个Explore agent,该agent读取diff、应用您的审查skill,并返回摘要。您的主上下文保持干净。

您现在拥有什么

一个三层harness:确定性的安全门禁(hook)、自动激活的领域专长(skill),以及保护上下文的隔离分析(subagent)。下文每一节都将围绕这三层中的一层展开。

为什么agent架构至关重要

Simon Willison将当下这个时刻概括为一个观察:编写代码如今已经很便宜。⁸ 没错。但其推论是,验证如今才是昂贵的部分。缺乏验证基础设施的廉价代码会大规模制造bug。真正带来回报的投资不是更好的prompt,而是围绕模型构建的系统——那个能捕捉模型遗漏之处的系统。

三股力量使agent架构成为必需:

上下文窗口既有限又会损耗。每一次文件读取、工具输出和对话轮次都会消耗token。Microsoft Research与Salesforce对 15 个LLM进行了 20 万余次模拟对话测试,发现从单轮到多轮交互,性能平均下降 39%。⁹ 这种退化最早在两轮之内就会出现,并遵循一条可预测的曲线:前 30 分钟的精准多文件编辑,到第 90 分钟时会退化为单文件的隧道视野。更长的上下文窗口并不能解决这一问题。同一研究中的”Concat”条件(将整段对话作为单一prompt)在内容完全相同的情况下达到了单轮表现的 95.1%。退化源自轮次边界,而非token上限。

模型行为是概率性的,不是确定性的。告诉Claude”编辑文件后务必运行Prettier”大约 80% 的时候管用。³ 模型可能会忘记、优先考虑速度,或判断该改动”太小”。对于合规、安全和团队规范而言,80% 并不可接受。Hooks能保证执行:每一次Edit或Write都会触发您的格式化工具,次次如此,概莫能外。确定性胜过概率性。

单一视角会错过多维度问题。单个agent审查一个API端点时,检查了身份认证、验证了输入清洗,也核实了CORS头。一切看起来无懈可击。而另一个agent单独以渗透测试员的身份被prompt时,却发现该端点接受无限制的查询参数,可能通过数据库查询放大触发拒绝服务攻击。⁷ 第一个agent从未检查这一点,因为其评估框架中没有任何部分将查询复杂度视为安全攻击面。这是结构性的盲区,再多的prompt工程也无法弥补。

Agent架构同时应对这三点:hooks强制确定性约束,subagents管理上下文隔离,多agent编排提供独立视角。三者合一,构成了harness。

Harness 模式

harness 不是框架，而是一种模式：它由一组可组合的文件、脚本和约定构成，将 AI 编码智能体封装在确定性基础设施中。其组件包括：

┌──────────────────────────────────────────────────────────────┐
│                      THE HARNESS PATTERN                      │
├──────────────────────────────────────────────────────────────┤
│  ORCHESTRATION                                                │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │   Agent     │  │   Agent    │  │  Consensus │             │
│  │   Teams     │  │  Spawning  │  │  Validation│             │
│  └────────────┘  └────────────┘  └────────────┘             │
│  Multi-agent deliberation, parallel research, voting          │
├──────────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Skills   │  │  Hooks   │  │  Memory  │  │  Agents  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  Domain expertise, deterministic gates, persistent state,     │
│  specialized subagents                                        │
├──────────────────────────────────────────────────────────────┤
│  INSTRUCTION LAYER                                            │
│  ┌──────────────────────────────────────────────────────┐    │
│  │     CLAUDE.md  +  .claude/rules/  +  MEMORY.md       │    │
│  └──────────────────────────────────────────────────────┘    │
│  Project context, operational policy, cross-session memory    │
├──────────────────────────────────────────────────────────────┤
│  CORE LAYER                                                   │
│  ┌──────────────────────────────────────────────────────┐    │
│  │           Main Conversation Context (LLM)             │    │
│  └──────────────────────────────────────────────────────┘    │
│  Your primary interaction; finite context; costs money        │
└──────────────────────────────────────────────────────────────┘

指令层：CLAUDE.md 文件和规则目录定义智能体需要了解的项目知识。它们会在会话开始时以及每次压缩后自动加载。这是智能体的长期架构记忆。

扩展层：skills 提供领域专业知识，并根据上下文自动激活。hooks 提供确定性关卡，在每次匹配的工具调用时触发。内存文件用于跨会话保留状态。自定义智能体则提供专门的 subagents 配置。

编排层：多智能体模式协调相互独立的智能体开展研究、审查和研讨。生成预算可防止递归失控，共识验证则用于确保质量。

核心洞见在于：大多数用户完全在核心层中工作，只能眼看上下文不断膨胀、成本节节攀升。高级用户会配置指令层和扩展层，随后仅使用核心层进行编排和最终决策。²

托管与自托管 Harness（2026年4月）

在2026年初的大部分时间里，“构建自己的 harness”是唯一切实可行的选择。2026年4月，情况发生了变化。Anthropic 于4月8日发布了公开测试版 Claude Managed Agents：将 harness 循环、工具执行、沙盒容器和状态持久化封装为 REST API，按标准 token 费用外加每会话小时0.08美元计费。OpenAI 于4月16日更新的 Agents SDK 正式确立了相同的分层方式——将 harness 与计算拆分为独立层，并提供原生沙盒供应商（Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel），以及快照与重新水合功能，以便在容器丢失后继续运行。²³²⁴

OpenAI 侧更深层的 SDK 功能随 openai-agents Python v0.14.0 一同落地（2026年4月15日发布，4月16日宣布）：包括继承自 Agent 的 SandboxAgent 子类，提供 default_manifest、沙盒指令和能力；用于描述全新工作区契约（文件、目录、本地文件、Git 仓库、环境、用户、挂载）的 Manifest；以及 SandboxRunConfig，用于按运行配置沙盒客户端、注入实时会话、覆盖 manifest、设置快照和实体化并发限制。内置能力涵盖 shell 访问、文件系统编辑、图像检查、skills、沙盒内存和压缩。沙盒内存会跨运行保留提取出的经验，并以渐进披露方式提供；工作区支持本地文件、Git 仓库条目和远程挂载（S3、R2、GCS、Azure Blob、S3 Files）；快照可跨供应商移植。后端包括：UnixLocalSandboxClient、DockerSandboxClient，以及通过可选扩展提供的 Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop 和 Vercel 托管客户端。²⁴

对于希望将 Claude Code 运行时作为库嵌入的 Python 项目——介于“通过 shell 调用 claude”和“通过 REST API 调用 Managed Agents”之间——claude-agent-sdk-python 是第三种选择。4月28日至29日发布的一系列版本（v0.1.69 → v0.1.71）将捆绑的 CLI 升级至 v2.1.123，将 mcp 依赖的最低版本提高至 >=1.19.0（旧版本会悄然丢弃进程内 MCP 工具返回的 CallToolResult，导致模型只能收到验证错误数据块），并使 SandboxNetworkConfig 与 TypeScript SDK 的 schema 保持一致（allowedDomains、deniedDomains、allowManagedDomainsOnly、allowMachLookup）。³⁰ 截至2026年8月1日，该软件包在 PyPI 上的版本为 v0.2.128（捆绑 Claude CLI v2.1.220，mcp 最低版本现为 >=1.23.0），TypeScript SDK 的版本则为 v0.3.220；0.2.x 系列是在此处所述0.1.x 功能面的基础上渐进演进而来——下文的 include_hook_events、skills 和沙盒配置选项仍然适用——近期版本主要着力提升子进程清理和 NDJSON 流的可靠性。⁸⁶

如果您的 harness 包含语音或实时层，openai-agents-python v0.17.0（2026年5月8日）已将 RealtimeAgent 的默认模型更新为 gpt-realtime-2。⁴¹ 现有实时会话会自动采用新的默认模型；如果评估工作需要维持原有行为，请显式固定先前的模型。

2026年7月，OpenAI 侧的托管方案也增加了多智能体能力：openai-agents-python v0.18.2（7月11日）和 openai-agents-js v0.13.2（7月10日）新增公开测试版托管多智能体支持——由 OpenAI 以托管服务形式编排多个智能体，与多智能体编排一节介绍的 Anthropic Managed Multiagent Orchestration 公开测试版直接对应。⁷³ 如今，两家供应商在多智能体层面均提供了与下表单智能体方案相同的权衡：供应商负责运行委派循环，而您需要放弃 hooks 功能面。

如今，架构上的分岔已然成为现实：

如何选择：对于已经具备扎实基础设施能力、希望自行掌控 skills/hooks，或需要深入优化特定工作流的团队，自托管仍是合适之选。对于缺少专职平台工程师、价值实现速度比定制能力更重要，或需要智能体在笔记本电脑合盖后仍能可靠运行且不想自行构建持久化层的团队，托管方案更为合适。两者可以兼容——自托管 harness 可以通过 REST API 将特定的长时间运行任务委派给 Managed Agents。

Harness 在磁盘上的结构

~/.claude/
├── CLAUDE.md                    # Personal global instructions
├── settings.json                # User-level hooks and permissions
├── skills/                      # Personal skills (44+)
│   ├── code-reviewer/SKILL.md
│   ├── security-auditor/SKILL.md
│   └── api-designer/SKILL.md
├── agents/                      # Custom subagent definitions
│   ├── security-reviewer.md
│   └── code-explorer.md
├── rules/                       # Categorized rule files
│   ├── security.md
│   ├── testing.md
│   └── git-workflow.md
├── hooks/                       # Hook scripts
│   ├── validate-bash.sh
│   ├── auto-format.sh
│   └── recursion-guard.sh
├── configs/                     # JSON configuration
│   ├── recursion-limits.json
│   └── deliberation-config.json
├── state/                       # Runtime state
│   ├── recursion-depth.json
│   └── agent-lineage.json
├── handoffs/                    # Session handoff documents
│   └── deliberation-prd-7.md
└── projects/                    # Per-project memory
    └── {project}/memory/MEMORY.md

.claude/                         # Project-level (in repo)
├── CLAUDE.md                    # Project instructions
├── settings.json                # Project hooks
├── skills/                      # Team-shared skills
├── agents/                      # Team-shared agents
└── rules/                       # Project rules

此结构中的每个文件都各司其职。~/.claude/ 目录树属于个人基础设施，适用于所有项目。每个仓库中的 .claude/ 目录树则针对具体项目，并通过 git 共享。二者共同构成完整的 harness。

Skills 系统

Skills 是由模型调用的扩展。Claude 会根据上下文自动发现并应用它们，无需您显式调用。⁴一旦发现自己在不同会话中反复解释相同的上下文，就该构建一个 skill 了。

何时构建 Skill

Skills 用于存放始终可供 Claude 使用的知识。斜杠命令则用于由您显式触发的操作。如果正在两者之间权衡，请思考：“应该让 Claude 自动应用它，还是由我决定何时运行？”

创建 Skill

Skills 可以存放在以下4个位置，作用域从最广到最窄：⁴

每个 skill 都需要一个包含 YAML frontmatter 的 SKILL.md 文件：

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

Frontmatter 参考

Description 字段至关重要

会话开始时，Claude Code 会提取每个 skill 的 name 和 description，并将其注入 Claude 的上下文。发送消息后，Claude 会运用语言模型推理判断是否有相关 skill。对 Claude Code 源代码的独立分析证实了这一机制：skill 描述会被注入系统提示词的 available_skills 部分，模型再通过标准语言理解能力选择相关 skills。¹⁰

不佳的 description：

description: Helps with code

有效的 description：

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

有效的 description 应包括：它的功能（审查代码中的特定问题类型）、使用时机（检查变更、PR 和质量分析），以及用户自然会输入的触发词（review、audit、check）。

需要注意，自动激活是一种可调机制，而非铁律：自 v2.1.215 起，Claude 不再自行调用内置的 /verify 和 /code-review skills，只会在显式调用时运行。这是对基于 description 激活机制的一次有意收缩，因为这类重量级审查 skills 在未经请求时运行，成本往往大于收益。⁷⁴

上下文预算

所有 skill 描述共享一项动态扩展的上下文预算，额度为上下文窗口的1%，并以8,000个字符作为回退值。⁴如果有很多 skills，请保持每条描述简洁，并优先写明核心用例。虽然可以通过 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量覆盖预算，¹¹但更好的解决办法是缩短描述并提高准确性。在会话期间运行 /context，可检查是否有 skills 被排除。

支持文件与组织方式

Skills 可以引用同一目录中的其他文件：

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

在 SKILL.md 中使用相对链接引用它们。skill 激活后，Claude 会按需读取这些文件。请将 SKILL.md 控制在500行以内，并把详细参考资料移至支持文件。¹²

通过 Git 共享 Skills

项目 skills（仓库根目录中的 .claude/skills/）可通过版本控制共享：⁴

mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

团队成员拉取代码后会自动获得该 skill。无需安装，也无需配置。这是在团队中统一专业知识最有效的方式。

将 Skills 用作提示词库

除了单一用途的 skills，这种目录结构还可作为井然有序的提示词库：

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

每个 skill 都承载您专业知识的一个不同侧面。它们共同构成知识库，Claude 会根据上下文自动调用。即使是初级开发者，也能在无需主动询问的情况下获得高级开发者级别的指导。

Skills 与 Hooks 组合使用

Skills 可以在 frontmatter 中定义自己的 hooks，这些 hooks 仅在 skill 运行期间激活。由此可创建领域特定的行为，而不会干扰其他会话：²

---
name: deploy-checker
description: Verify deployment readiness. Use when preparing to deploy,
  release, or push to production.
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"deploy|release|publish\"; then echo \"DEPLOYMENT COMMAND DETECTED. Running pre-flight checks.\" >&2; fi'"
---

理念型 skills 通过 SessionStart hooks 自动激活，无需显式调用即可向每个会话注入质量约束。skill 本身承载知识，hook 负责强制执行。二者结合，构成一层策略机制。

Skills 的常见错误

描述过于宽泛。 如果 git-rebase-helper skill 会因任何与 git 有关的提示词而激活（包括 rebase、merge、cherry-pick，甚至 git status），就会污染80%的会话上下文。解决办法是收紧描述，或添加 disable-model-invocation: true，要求通过 /skill-name 显式调用。⁴

过多 skills 争夺预算。 Skills 越多，争夺1%上下文预算的描述就越多。如果发现某些 skills 未能激活，请通过 /context 检查它们是否被排除。与其保留大量含糊的 skills，不如优先维护少量描述清晰的 skills。

关键信息深埋在支持文件中。 Claude 会立即读取 SKILL.md，但只在需要时访问支持文件。如果关键信息位于支持文件中，Claude 可能找不到它。请将必要信息直接写入 SKILL.md。⁴

SDK Skill 接口（2026年5月8日）

基于 claude-agent-sdk-python v0.1.77+ 的自托管 harness 应通过 ClaudeAgentOptions 的 skills 选项声明可用 skills，而不是继续在 allowed_tools 中使用旧版 "Skill" 值。³⁷"Skill" 简写形式已被弃用；专用选项能向 Claude Code 提供结构更清晰的可用 skills 信息。v0.1.77 内置的 CLI 版本为 v2.1.133。

.claude/skills/ 中 Plugin 与 Skill 的融合（2026年5月29日）

Skills 一直从项目的 .claude/skills/ 目录加载。Claude Code v2.1.157 将此目录的支持范围扩展到了插件：如今，将插件放入 .claude/skills/ 即可自动加载，无需在 marketplace 中注册；claude plugin init <name> 也会在此处搭建一个新插件，并预先配置好 manifest 和 SKILL.md。⁵⁸这一变化弥合了两种项目工具形态之间的鸿沟。过去，一种是直接提交到仓库的独立 skill；另一种是将 skill、hooks 和 MCP 服务器捆绑在一起，却必须通过 marketplace 安装的插件。对于 harness 设计，其实际意义在于：项目级工具不再需要绕道 registry 才能交付——编写、提交，团队成员执行 git pull 后即可获得相同的工具接口。插件仍然适用于捆绑式可安装场景（将 hooks、skills、MCP 服务器和 agents 打包在同一个 ZIP 中）；变化在于，项目无需再为了从自身目录树加载插件而专门搭建 marketplace。

将隐藏内置接口作为治理手段（2026年6月8日）

Skills 代表能力，而能力也意味着攻击面。Claude Code v2.1.169 新增了 disableBundledSkills 设置（以及对应的 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS 环境变量），可对模型完全隐藏内置 skills、workflows 和内置斜杠命令。⁶⁰对于经过加固或受到监管的 harness，这是一项有意为之的攻击面削减措施：如果运维人员已经审核并批准了一组特定的项目和个人 skills，就可以屏蔽 Anthropic 随附的全部功能，使模型始终只在经过审核的接口范围内进行推理。应像对待工具允许列表一样对待此设置——默认配置提供广泛能力，而关闭默认能力是一项治理决策，并非单纯为了方便的开关。

嵌套 .claude/skills 与最近者优先解析（2026年6月16日）

Claude Code v2.1.178 让项目工具具备了位置感知能力。在嵌套的 .claude/skills 目录中定义的 skills，如今会在处理该目录下的文件时加载，不再局限于仓库根目录；如果出现名称冲突，嵌套 skill 会显示为 <dir>:<name>，因此二者仍可访问。⁶³同一版本还让项目的其余接口按照离工作目录最近的原则解析：当嵌套 .claude/ 目录中的 agent、workflow 或输出样式发生名称冲突时，以最接近工作目录的定义为准；保存项目作用域的 workflow 时，也会写入最近的现有 .claude/workflows/，而不是一律保存到根目录。⁶³对于 monorepo 或仓库套仓库的结构而言，这意味着项目不再只有一个扁平的全局接口，而是可以拥有按上下文激活的包级工具。例如，services/api/.claude/skills/ 可以包含仅在该目录树中工作时才显示的 API 专用 skills，并且不会与 services/web/ 中同名的 skill 冲突。

Hook Architecture

Hooks是由Claude Code生命周期事件触发的shell命令。³它们在LLM之外以普通脚本形式运行，而不是由模型解释的提示词。模型想运行rm -rf /？一段10行的Bash脚本会根据阻止列表检查该命令，并在shell看到它之前将其拒绝。无论模型是否愿意，hook都会触发。

可用事件

截至本指南更新时，Claude Code提供了分为8类的30个有文档记录的生命周期事件。事件列表会随版本发布不断扩充，因此请以参考文档为准；在配置生产环境hooks之前，请查看速查表中的最新完整表格：¹³

DirectoryAdded（v2.1.219）弥补了会话中途的工作区缺口。自MessageDisplay在v2.1.152中加入以来，事件列表一直保持稳定；DirectoryAdded是此后首个新增的生命周期事件。它会在/add-dir或SDK的register_repo_root控制请求于会话进行期间注册新工作目录后触发。⁸⁴它所弥补的缺口确实存在：此前，即使harness在SessionStart时对工作区进行了详尽验证，第二个存储库仍可能在完全不触发hook的情况下被接入。启动时针对工作区执行的任何断言——信任检查、密钥扫描、根据目录树推导的路径范围规则、按存储库加载策略——都需要在此处重新运行，因为会话的目录集合不再于启动时固定不变。该事件仅提供信息，不具备阻止能力，因此应将其作为重新推导状态和记录来源的触发器，而非gate；如果某个目录绝不允许添加，应在settings中将其拒绝，而不是试图通过hook否决。SDK端的支持也在同一版本落地（TypeScript v0.3.219将DirectoryAdded添加到控制协议生命周期事件中），因此，由SDK托管的harness与CLI托管的harness可以同等处理该事件。⁸⁵

退出代码语义

退出代码决定hooks是否阻止操作：³

Hook配置

Hooks位于settings文件中。项目级hooks放在.claude/settings.json中，用于共享；用户级hooks放在~/.claude/settings.json中，用于个人配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

matcher字段用于筛选特定于事件的值。对于工具事件，它会匹配tool_name值，例如Bash、Edit、Write、Read、Glob、Grep、类似mcp__server__tool的MCP工具名称，或用于匹配所有工具的*。简单名称和以|分隔的列表执行精确匹配；包含其他字符的值则视为JavaScript正则表达式。部分事件不支持matcher，只要完成配置就会始终触发。¹³自Claude Code v2.1.195起，包含带连字符标识符（code-reviewer、mcp__brave-search）的matcher会执行精确匹配，不再意外进行子字符串匹配。因此，针对某个代理或服务器的hook，不会再对名称中仅包含该字符串的所有对象触发；若要涵盖来自带连字符MCP服务器的所有工具，请明确写出模式mcp__brave-search__.*。⁶⁶v2.1.214将同样的规范应用于路径模式：hook的if:条件使用单段dir/**模式时，现在只匹配<cwd>/dir，而不会匹配目录树任意位置所有名为dir的目录；只有在确实需要匹配任意深度时，才应写成**/dir/**。⁷⁴与v2.1.195中的更改一样，此项修复以明确声明的意图取代了意外的宽泛匹配；请审查所有曾暗中依赖旧版任意深度行为的hook条件。

Hook输入/输出协议

Hooks通过stdin接收包含完整上下文的JSON：

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123",
  "agent_id": "main",
  "agent_type": "main"
}

如需进行高级控制，PreToolUse hooks可以输出JSON，以修改工具输入、注入上下文或作出权限决策。请使用hookSpecificOutput包装器——对于PreToolUse，旧版顶层decision/reason格式已弃用：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

三类保证

编写任何hook之前，请先思考：我需要哪种保证？¹⁴

格式保证确保事后的一致性。针对Write/Edit的PostToolUse hooks会在每次文件更改后运行格式化程序。模型输出的具体形式并不重要，因为格式化程序会统一规范所有内容。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; elif [[ \"$FILE_PATH\" == *.js ]] || [[ \"$FILE_PATH\" == *.ts ]]; then npx prettier --write \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

安全保证在危险操作执行前加以阻止。针对Bash的PreToolUse hooks会检查命令，并使用退出代码2阻止破坏性模式：

#!/bin/bash
# validate-bash.sh — block dangerous commands
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "rm\s+-rf\s+/|git\s+push\s+(-f|--force)\s+(origin\s+)?main|git\s+reset\s+--hard|DROP\s+TABLE"; then
    echo "BLOCKED: Dangerous command detected: $CMD" >&2
    exit 2
fi

质量保证在决策点验证状态。针对git commit命令的PreToolUse hooks会运行代码检查工具或测试套件，并在质量检查失败时阻止提交：

#!/bin/bash
# quality-gate.sh — lint before commit
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "^git\s+commit"; then
    if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then
        echo "LINT FAILED -- fix before committing:" >&2
        echo "$LINT_OUTPUT" >&2
        exit 2
    fi
fi

shell命令以外的Hook类型

Claude Code支持5种hook类型：¹³

命令hooks（type: "command"）运行shell脚本。速度快、结果确定，而且不消耗token。 MCP 工具 hooks（type: "mcp_tool"）会调用已连接的 MCP 服务器上的工具。当验证逻辑已位于 MCP 边界之后，且无需单独的 shell 脚本时，请使用此类 hooks。

Prompt hooks（type: "prompt"）会向快速 Claude 模型发送单轮提示。模型返回 { "ok": true } 表示允许，或返回 { "ok": false, "reason": "..." } 表示阻止。适用于正则表达式无法涵盖的细致评估。

Agent hooks（type: "agent"）会生成一个具备工具访问权限（Read、Grep、Glob）的 subagent，以执行多轮验证。此功能仍处于实验阶段；生产环境的 gates 应优先使用 command hooks，仅将 agent hooks 用于确实需要检查实际文件或测试输出的检查：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

自 Claude Code v2.1.140 起，agent hook 输入包含 subagent_type，使共享 hook 无需根据提示文本进行猜测，即可区分 security-reviewer、explorer 或通用 worker 的运行任务。⁴⁹

HTTP hooks（type: "http"）将事件的 JSON 输入作为 POST 请求发送到 URL，并接收返回的 JSON。适用于 webhooks、外部通知服务或基于 API 的验证（v2.1.63+）。不支持 SessionStart 事件：

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook.example.com/hook",
            "headers": { "Authorization": "Bearer $WEBHOOK_TOKEN" },
            "allowedEnvVars": ["WEBHOOK_TOKEN"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

异步 Hooks

Hooks 可以在后台运行而不阻塞执行。对于通知和日志记录等非关键操作，请添加 async: true：¹³

{
  "type": "command",
  "command": ".claude/hooks/notify-slack.sh",
  "async": true
}

异步模式适用于通知、遥测和备份。切勿将其用于格式化、验证或任何必须在下一步操作前完成的任务。

使用 Dispatchers 取代独立 Hooks

如果7个 hooks 均由同一事件触发，并分别独立读取 stdin，就会产生竞态条件。两个 hooks 同时写入同一个 JSON 状态文件会截断其中的 JSON，导致所有解析该文件的下游 hooks 失效。²

解决方法是：为每个事件设置一个 dispatcher，使用缓存的 stdin 依次运行 hooks：

#!/bin/bash
# dispatcher.sh — run hooks sequentially with cached stdin
INPUT=$(cat)
HOOK_DIR="$HOME/.claude/hooks/pre-tool-use.d"

for hook in "$HOOK_DIR"/*.sh; do
    [ -x "$hook" ] || continue
    echo "$INPUT" | "$hook"
    EXIT_CODE=$?
    if [ "$EXIT_CODE" -eq 2 ]; then
        exit 2  # Propagate block
    fi
done

调试 Hooks

以下5种技巧可用于调试无声失败的 hooks：¹⁴

1. 单独测试脚本。 通过管道传入示例 JSON：echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. 使用 stderr 输出调试信息。 退出代码2对应的 stderr 会作为错误消息反馈给 Claude。非阻塞 stderr（退出代码1、3等）仅在详细模式（Ctrl+O）下显示。
3. 留意 jq 失败。 错误的 JSON 路径会悄无声息地返回 null。请使用真实的工具输入测试 jq 表达式。
4. 验证退出代码。 使用 exit 1 的 PreToolUse hook 看似正常工作，实际上毫无强制约束作用。
5. 保持 hooks 快速运行。 Hooks 会同步运行。所有 hooks 的耗时应控制在2秒以内，最好低于500毫秒。

SDK 端 Hook 事件流

基于 claude-agent-sdk-python（v0.1.74+，2026年5月6日）构建的自托管 harness，可以直接从消息流订阅 hook 事件，无需通过 shell 脚本回调。³⁶ 在 ClaudeAgentOptions 上设置 include_hook_events=True 后，HookEventMessage 对象（PreToolUse、PostToolUse、Stop 等）会与助手消息和工具结果通过同一迭代器产出。这与 TypeScript SDK 的 includeHookEvents 选项相对应；同一版本还将捆绑的 CLI 升级至 v2.1.129。

如果 harness 已在 Python 中运行，并希望 hook 信号与模型输出处于同一控制流中，事件流模式最为合适。对于需要组合多个工具、在 Claude Code 与 Codex 之间共享 hooks，或需要利用退出代码语义实现阻止机制的 harness，shell 脚本 hook 契约（退出代码、stdin JSON、dispatchers）仍是恰当选择。

TypeScript SDK 在2026年7月发布的一系列版本（v0.3.205–v0.3.208）进一步明确了流式协议的契约。⁷⁰ 中断现在会返回类型化回执：中断通过 still_queued UUID 确认哪些已排队消息仍在等待处理；会话则在 system/init 中声明 interrupt_receipt_v1 能力，使协调器能够区分“中断已生效”和“中断与已在传输中的消息擦肩而过”。command_lifecycle 帧会分别报告每条消息的已排队、已启动、已完成、已取消和已丢弃状态。这是第一方首次无需推断会话记录，便能回答“我发送的消息发生了什么”。此外还引入了一些较小的接口改进：用于 subagent 完成载荷的 AgentToolCompletedOutput 类型，以及 canUseTool 回调现在可以返回不含 updatedInput 字段的 {behavior: 'allow'}。

该系列中有一项属于安全底线，而非普通功能：v0.3.208 修复了调用方在 hook 等待期间发出的中止被转换为 hook 成功的问题——这意味着受 PreToolUse hook 约束的工具可能在调用方中止后仍然执行。⁷⁰ 如果您的 harness 使用 SDK 端 hooks 作为权限 gate，并依赖中止操作取消进行中的任务，请将 v0.3.208 视为最低版本；在更早版本中，“已中止”并不可靠地等同于“已阻止”。Python v0.2.127（2026年7月24日）是一个月内第二次出现此类绕过：当后台 subagents 仍在运行时，query() 会在收到第一个 result 帧后关闭 stdin，导致其 SDK-MCP 工具调用因 "Stream closed" 而失败，且完全绕过 PreToolUse hooks。⁸⁵ 应明确识别并警惕这一模式：SDK 端 hook 的强制约束会在生命周期边缘失效并放行——例如中止、拆除或流关闭。此时，传输连接会在收集到 hook 裁决之前终止。更棘手的是，这种失败悄无声息，因为被绕过的 hook 与批准操作的 hook 看起来毫无区别。请固定两个 SDK 的最低版本，并保留能够确凿验证其强制约束效果的 shell-hook 层。

Effort 与会话来源（2026年5月7日至8日）

Claude Code v2.1.132 和 v2.1.133 引入的两项功能，为 hooks 和子进程提供了更丰富的执行上下文信号：³⁸³⁹

• hook 输入中的 effort.level。 Hooks 现在会在承载 tool_input 和 session_id 的同一输入中接收 effort.level JSON 字段。相同的值也会导出为 $CLAUDE_EFFORT 环境变量，因此 Bash 命令无需解析 JSON 即可读取。可以根据 effort 层级调整 hook 成本：在 low 层级跳过高成本验证，在 xhigh 或 max 层级运行完整的安全 gate。
• Bash 子进程中的 CLAUDE_CODE_SESSION_ID 环境变量。 Bash 工具子进程现在可以通过 CLAUDE_CODE_SESSION_ID 获取 hooks 所看到的同一个 session_id 值。这弥补了来源追踪方面的缺口：此前，按会话记录状态的工具无法将子进程事件与 hook 事件关联起来。

这两种信号无需修改代码即可使用；忽略新字段的现有 hooks 仍可正常工作。

autoMode.hard_deny 与 v2.1.136 Hook/Plugin 修复（2026年5月8日）

Claude Code v2.1.136 为自动模式新增了一个 hard-deny 层级，并修复了一批影响长时间运行 harness 的 plugin 和 MCP 问题：⁴⁰ - settings.autoMode.hard_deny。 Auto mode分类器中无条件阻止操作的规则，不受用户意图或允许例外影响。它位于现有允许/拒绝匹配器之上，是不容妥协的治理手段。对于绝不能被覆盖的规则（强制推送到main、包含密钥的文件、访问生产数据库），即使操作员已在个人设置中批准相应的大类，也应使用此设置。 - autoMode.classifyAllShell（v2.1.193）。 默认情况下，auto mode分类器只审查与任意代码执行模式匹配的shell命令。此设置会将每一条Bash/PowerShell命令都交由分类器处理，为受治理的harness提供最大覆盖范围。同一版本还会在记录、提示消息和/permissions中显示拒绝原因，将悄无声息的阻止转化为可审计的决策。Codex在v0.142.2中收紧了对应机制：如果PowerShell命令包含安全分类器无法检查的可执行AST区域，现在必须获得批准，而不会再被悄然放行。⁶⁶ - Hook的ask为分类器设定下限（v2.1.211）。 hook与auto mode之间的优先级问题现已明确：如果PreToolUse hook返回ask权限决策，最终结果至少必须提示用户——对于未在沙箱中运行的Bash命令，auto mode无法再将其提升为允许。⁶⁹ 对受治理的harness而言，这正是此前缺失的保障层级：hook的ask会形成确定性的人机协同检查点，即便权限策略完全自动化也始终有效。对于需要人工决策而非直接拒绝的操作，请使用ask（而不只是退出码为2的阻止）。 - 分类器模型在每个会话中固定（v2.1.210）。 auto mode分类器默认使用Sonnet 5，并在会话期间保持固定，因此会话中途切换模型不再改变执行权限分类的模型。分类一致性是治理的一项基本属性；此项改动消除了一个不易察觉的漂移来源。 - MCP服务器在/clear后不再消失。 在VS Code扩展、JetBrains插件和Agent SDK中执行/clear后，通过.mcp.json、plugins和claude.ai连接器配置的服务器曾会悄然从活动集合中消失。该问题已在v2.1.136中修复。如果您曾遇到“MCP服务器X在会话中途消失”，原因正是如此。 - 并发刷新导致MCP OAuth刷新令牌丢失。 使用多个远程MCP服务器的用户应该不再需要每天重新进行身份验证。此前，并发刷新写入会相互覆盖。 - Plan mode现在能够正确阻止文件写入。 匹配的Edit(...)允许规则曾会绕过plan mode的写入保护。现在，无论是否存在允许规则，都会强制执行plan mode。 - Plugin的Stop和UserPromptSubmit hooks在会话中途不再失败。 缓存清理曾会删除当前会话仍在使用的plugin版本文件，导致这两个特定hook事件失效。修复后，正在使用的版本会保持固定。 - plugin.json中的skills条目。 设置skills曾会隐藏plugin的默认skills/目录。现在该条目可以正确组合；如果将其指向文件路径，系统会明确报错，而不再悄然失败。 - CLAUDE_ENV_FILE SessionStart hook环境变量过期。 SessionStart hooks通过CLAUDE_ENV_FILE导出的变量在/resume或/clear后曾会过期。该问题已在v2.1.136中修复。现在，会话会在这些事件发生时重新加载环境文件。

对于治理型harness，值得重点关注的操作项是autoMode.hard_deny（新增治理手段）和MCP消失问题的修复（这种无声故障会破坏长时间运行的会话）。其余改动主要是易用性优化。

结构化Hook参数与阻止后的继续执行（2026年5月11日）

Claude Code v2.1.139新增了两个对生产harness至关重要的hook细节：用于命令hooks的args: string[]执行形式，以及用于PostToolUse hooks的continueOnBlock。⁴²⁴⁴ 当hook需要动态值或路径占位符时，优先使用args。它无需shell即可直接启动命令，从而消除一整类引号转义和注入错误。

如果PostToolUse hook需要将拒绝原因反馈给Claude，并继续当前轮次而非终止流程，请使用continueOnBlock。应将其视为改善操作员体验的功能，而不是绕过安全控制的手段。阻止型门禁仍须阻止不安全的结果。

同一版本还会将CLAUDE_PROJECT_DIR传递给MCP stdio服务器，并允许plugin配置在命令中引用${CLAUDE_PROJECT_DIR}。⁴² MCP工具应依据该值解析项目相对路径，而不是依赖碰巧启动服务器的进程工作目录。2026年7月初发布的版本（v2.1.203–v2.1.206）将同一原则扩展到了协议层：MCP roots/list现在包含会话的其他工作目录，并会在目录变化时发送roots/list_changed通知。因此，遵循MCP roots的服务器能够跟踪多目录工作区的实际结构，而不会假定只有一个项目目录。⁶⁸

对于harness操作员而言，Claude Code v2.1.140主要是一个可靠性版本：它修复了设置变更时ConfigChange hooks未触发的问题，解决了disableAllHooks和allowManagedHooksOnly在不同设置层级无法正确协同的边缘情况，并阻止权限对话框暴露hook结果返回的非预期环境变量。⁴⁹ 这些改动使本节已有的治理模式更加可靠，无需采用新的hook架构。

Claude Code v2.1.141为hook输出新增了terminalSequence字段，可在没有控制终端的情况下用于桌面通知、窗口标题和响铃。⁵⁰ 应将其视为操作员信号机制，而非强制执行手段。安全与质量门禁仍应通过常规阻止约定来传达失败：使用结构化hook输出，并配合能够阻止不安全操作的退出行为。同一版本还新增了claude agents --cwd <path>，用于将Agent View限定在一个目录；新增CLAUDE_CODE_PLUGIN_PREFER_HTTPS，用于在缺少GitHub SSH密钥的环境中安装plugin；并新增ANTHROPIC_WORKSPACE_ID，用于覆盖多个工作区的工作负载身份联合规则。⁵⁰ 对团队harness而言，这些都是架构层面的细节：更聚焦的运维视图、更少的plugin安装前提假设，以及明确的企业令牌作用域。

与hook语义相比，Claude Code v2.1.142对于后台会话编排更为重要。⁵¹ claude agents现在可以使用明确的目录、设置、MCP、plugin、权限、模型和effort标志来调度后台会话，不再依赖封装程序的状态。该版本发布时，fast mode默认使用Opus 4.7；如果某个harness经过测量后确认依赖Opus 4.6的行为，可以使用CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1将其固定——截至v2.1.219，Opus 4.7已完全退出fast mode，/fast适用于Opus 5和Opus 4.8。⁸⁴ 对plugin根目录SKILL.md的发现支持，以及plugin提供的LSP可见性，减少了打包歧义。针对MCP_TOOL_TIMEOUT、已有后台会话worktrees、守护进程休眠/唤醒与升级后清理，以及plugin缓存清理的修复，弥补了若干可靠性缺口；否则，这些问题很容易被误判为编排故障。

Stop-hook引导、跨会话权限与multi-agent v2（2026年6月）

6月初的4项改动对harness和multi-agent设计具有重要意义。⁵⁹

Stop/SubagentStop hooks新增了引导通道。 自Claude Code v2.1.163起，Stop或SubagentStop hook可以返回hookSpecificOutput.additionalContext，向Claude提供反馈并让当前轮次继续执行，同时不会将响应标记为hook错误。在此之前，Stop hook唯一真正有效的手段是通过退出码2进行阻止，但这会显示为错误，并计入连续阻止次数上限。对于质量门禁harness，这是更简洁妥当的基础机制：当Stop hook检测到“您声称已经完成，但测试仍未通过”时，现在可以注入“以下问题仍未解决，请继续处理”，而不必强行阻止。真正需要停止时使用阻止机制；对于“尚未完成，原因如下”的情况，则使用additionalContext。

跨会话消息不再携带借用的权限。 v2.1.166强化了多会话场景：通过SendMessage从另一个Claude会话转发的消息不再携带原用户的权限，因此接收会话会拒绝转发的权限请求，auto mode也会将其阻止。如果您的编排允许agents相互发送消息，应将传入消息视为不可信数据，而非经过身份验证的指令。这与安全部分针对工具输出采用的原则相同，只是扩展到了agent间消息传递。截至v2.1.199，当两个agents名称相同而导致SendMessage路由错误时，Claude Code还会检测并发出警告。这是对上述权限边界的可靠性补充，因为消息抵达错误的同名agent本身就是一类编排故障。 模型韧性已成为一项一等设置。 fallbackModel设置现在可串联最多3个备用模型。当主模型过载或不可用时，会按顺序尝试这些模型；如果发生意外且不可重试的API错误，则会使用备用模型自动重试当前轮次一次。对于长时间运行的自主 harness，这能将主模型的暂时中断转化为平稳降级，而不是导致整个运行中止。claude agents --json还新增了waitingFor字段（v2.1.162），用于显示受阻的后台会话正在等待什么，例如权限提示。这显著提升了协调器轮询代理集群时的可观测性。

用于净室治理和故障排除的安全模式。 Claude Code v2.1.169新增了--safe-mode标志（以及对应的CLAUDE_CODE_SAFE_MODE环境变量），可在启动会话时一次性禁用所有自定义项：CLAUDE.md、插件、skills、hooks和MCP服务器。⁶⁰这与 harness 恰恰相反，是一种有意构建的净室环境。每位运维人员最终都会追问：“这种行为究竟来自模型，还是来自我的某项配置？”安全模式正是用来回答这个问题的。当 hook 错误触发、skill 在不应激活时被激活，或MCP服务器污染上下文时，--safe-mode会提供一个已知为空的基线，便于进行差异对比。它也是一种治理原语：让您能够运行不带任何持久权限的纯模型，而这些权限通常由 harness 授予。当需要复现结果，又不希望任何运维人员定义的支撑结构施加影响时，这一点至关重要。

关于模型层级的说明。 自Claude Code v2.1.197（2026年6月30日）起，Claude Sonnet 5成为新会话随产品提供的默认模型。它原生支持1M上下文，并在8月31日前提供每百万 token 2美元/10美元的促销价格，取代 Opus 4.8成为开箱即用的选择。本指南将Opus 5（claude-opus-5）作为推荐的智能体默认模型：除非有意选择其他模型，否则自主 harness 应使用该模型运行。原因在于，长周期、高风险的智能体循环正是 Opus 的推理深度物有所值之处。Opus 5于2026年7月24日随Claude Code v2.1.219发布，成为新的默认 Opus：支持1M上下文，每百万 token 5美元/25美元（与其取代的 Opus 4.8价格相同），快速模式的价格为10美元/50美元，速度约为默认模式的2.5倍。Anthropic报告称，它在 Frontier-Bench v0.1上的成绩超过 Opus 4.8的两倍，而在 CursorBench 3.2上的得分与 Fable 5相差不到0.5%，成本却只有后者的一半。⁸⁴⁸⁷价格不变、能力更强，而且Anthropic将其描述为“更擅长验证自身工作并谨慎迭代”。这种升级难能可贵，对 harness 工作而言，无须再从成本角度加以论证；从4.8迁移只需更改 ID。对于成本敏感或高吞吐量的任务，可降级使用 Sonnet 5，其速度与智能水平之比更具优势。Opus 之上还有Claude Fable 5（claude-fable-5），于2026年6月9日发布。这是一个全新层级，被称为Anthropic最强大的模型，是一套可供通用场景安全使用的“Mythos-class”系统；在Claude Code v2.1.170中，可通过/model claude-fable-5选择该模型。⁶⁰应有的放矢地使用这一更高层级，只将其用于原始推理深度足以证明成本合理的决策，而不要将其设为整个代理集群的通用配置。Opus 5切换还带来两项维护层面的变化：Opus 4.7已退出快速模式（/fast现在适用于 Opus 5和 Opus 4.8）；自动模式分类器的 Fable-5 fallback 自 v2.1.176起会选择“当前最佳的 Opus 模型”，如今该模型即为 Opus 5。⁸⁴

Codex发布了 multi-agent v2。 Codex CLI v0.137.0让每个线程自行保留运行时选择，为生成的代理提供了更简洁的后续交互和元数据默认值（hide_spawn_agent_metadata现在默认为 true），并将原始父级事件传播给子级监听器。其 subagent 模型仍然明确：内置 default/worker/explorer 代理类型、通过 TOML 定义的自定义代理，以及并发控制（agents.max_threads默认为6，agents.max_depth默认为1）。同一版本还新增了 v1 skills 扩展，支持按轮次解析 skill 目录，并加入新的线程启动和轮次错误生命周期贡献者事件。这缩小了其与Claude Code的 hook/skill 功能差距，同时继续将内核沙箱策略作为默认边界。随后，Codex v0.138.0–v0.139.0进一步强化 multi-agent v2，使其适用于生产环境：代理间消息载荷现已加密；v2代理配置目录与代理驻留 LRU共同管理哪些代理保持驻留；并发量则按活跃执行而非已生成线程计算，因此空闲代理不再占用槽位。⁶¹生命周期API也更加成熟——close_agent在 v0.139.0中更名为interrupt_agent，准确反映其作用是中断正在运行的代理，而非仅仅关闭句柄。此外，subagent 引发的MCP启动警告现在仅限于所属线程，不再向上重复出现在父级转录记录中。⁶¹对于构建 Codex 侧编排的人员而言，这些正是演示原型与生产集群之间的分水岭：加密的消息传输、受限的驻留规模、按执行计数的并发机制，以及不会跨越线程边界泄漏的警告。随后，Codex v0.140.0又打通了一条跨工具通道：/import可选择性地将设置、项目配置和近期聊天从Claude Code导入 Codex；会话也支持永久删除（codex delete / /delete，并配有确认保护措施）。⁶⁴/import首次正式承认运维人员会在不同 harness 之间切换——为某个工具构建的配置不再被困于其中。

记忆与上下文

每次 AI 对话都受限于有限的上下文窗口。随着对话不断推进，系统会压缩较早的轮次，为新内容腾出空间。这种压缩会造成信息损失。第 3 轮记录的架构决策到第 15 轮时可能已经丢失。⁹

多轮对话崩溃的三种机制

MSR/Salesforce 的研究发现了三种相互独立的机制，每种机制都需要采用不同的干预措施：⁹

策略 1：以文件系统作为记忆

跨越上下文边界时，最可靠的记忆存储在文件系统中。Claude Code 会在每次会话开始时以及每次压缩后读取 CLAUDE.md 和记忆文件。⁶

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

MEMORY.md 文件用于记录跨会话的错误、决策和模式。当您发现 VAR 为 0 时，((VAR++)) 在启用 set -e 的 bash 中会失败，便可将其记录下来。三个会话后，当您在 Python 中遇到类似的整数边界情况时，MEMORY.md 中的条目就会呈现这一模式。¹⁵

Auto Memory（v2.1.32+）：Claude Code 会自动记录和回忆项目上下文。在工作过程中，Claude 会将观察结果写入 ~/.claude/projects/{project-path}/memory/MEMORY.md。会话开始时，Auto memory 会将前 200 行加载到系统提示词中。请保持内容精简，并通过链接指向单独的主题文件来记录详细信息。⁶ 自 v2.1.210 起，写入 MEMORY.md 的内容如果超过大小限制，系统会报错，而不再静默截断⁶⁹——故障会在写入时显现，而不会让记忆条目悄无声息地消失。如果您的 harness 会自动写入记忆，请妥善处理此错误；平台是在提示您该文件需要整理，而不是要求重试。

重视记忆整理，而非记忆数量（2026年5月）：最近一篇关于 LLM-agent 协作的 arXiv 预印本指出，扩展回忆范围可能成为一种故障模式：在作者的实验中，更长的可见历史记录导致 28 种模型博弈设置中的 18 种协作效果下降。⁴⁸ 应将其视为设计警示，而非已成定论的法则。生产环境中的规则已经足够明确：保持 MEMORY.md 简短，通过链接指向详细内容，并在交接文档中提供可直接用于决策的摘要。原始对话记录、工具日志和冗长的回忆内容应存入可搜索的存储系统，而不应自动注入当前提示词。

策略 2：主动压缩

Claude Code 的 /compact 命令会总结对话并释放上下文空间，同时保留关键决策、文件内容和任务状态。¹⁵

何时进行压缩： - 完成一个独立子任务后（功能已实现、错误已修复） - 开始处理代码库中的新区域之前 - 当 Claude 开始重复内容或遗忘先前上下文时 - 在高强度会话期间，大约每 25-30 分钟一次

CLAUDE.md 中的自定义压缩指令：

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

压缩可以保护对话；而 /cd 命令（Claude Code v2.1.169）则用于保护提示词缓存。它可以在不中断当前流程的情况下，将会话迁移到新的工作目录，同时保留本轮对话中已经积累的缓存。⁶⁰ 此前，更改目录意味着必须启动新会话，并从冷缓存开始。对于需要从一个代码仓库转向同级仓库的长时间会话——这在单体仓库和多服务工作中十分常见——/cd 能够保留成本高昂的缓存前缀，同时重新定位文件系统上下文。

策略 3：会话交接

对于跨越多个会话的任务，请创建能够记录完整状态的交接文档：

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

Status/Files/Decision/Blocked/Next 结构能够以极低的 token 成本，为后续会话提供完整上下文。使用 claude -c（继续）启动新会话或读取交接文档，即可直接进入实现阶段。¹⁵

策略 4：全新上下文迭代（Ralph Loop）

对于持续时间超过 60-90 分钟的会话，每次迭代都应启动一个全新的 Claude 实例。状态通过文件系统持久化，而不是依赖对话记忆。每次迭代都能获得完整的上下文预算：¹⁶

Iteration 1: [200K tokens] -> writes code, creates files, updates state
Iteration 2: [200K tokens] -> reads state from disk, continues
Iteration 3: [200K tokens] -> reads updated state, continues
...
Iteration N: [200K tokens] -> reads final state, verifies criteria

与单个长会话对比：

Minute 0:   [200K tokens available] -> productive
Minute 30:  [150K tokens available] -> somewhat productive
Minute 60:  [100K tokens available] -> degraded
Minute 90:  [50K tokens available]  -> significantly degraded
Minute 120: [compressed, lossy]     -> errors accumulate

每次迭代使用全新上下文的方法，会在定位阶段产生 15-20% 的额外开销（读取状态文件、扫描 git 历史记录），换来每次迭代都能使用完整的认知资源。¹⁶ 成本效益分析表明：对于不超过 60 分钟的会话，单次对话效率更高；超过 90 分钟后，尽管存在额外开销，全新上下文仍能产出质量更高的结果。

策略 5：托管式记忆整理（Dreaming）

Anthropic 的 Claude Managed Agents 于 2026年5月6日新增了 Research Preview 功能 Dreaming。³⁵ 根据 Anthropic 的说明：“Dreaming 是一种定期运行的流程，它会审查您的 agent 会话和记忆存储，提取模式并整理记忆，使您的 agent 能够不断改进。”³⁵

Dreaming 在会话之间于后台运行，不处于关键路径之上。它是对“以文件系统作为记忆”模式的补充，而非替代：MEMORY.md 文件仍然是承载核心状态的基础；Dreaming 会将整理后的记忆条目写入 Managed Agents 记忆存储，agent 则会在会话开始时读取这些内容。对于同时采用自托管文件系统状态和托管端整理机制的 harness，这两种模式可以并行共存。

Dreaming 目前处于 Research Preview 阶段，其行为可能发生变化。对于自托管 harness，上文介绍的会话交接和 CLAUDE.md 模式仍是权威的记忆机制。

反模式

只需要 10 行，却读取整个文件。读取一个 2,000 行的文件就会消耗 15,000-20,000 个 token。请使用行偏移量：Read file.py offset=100 limit=20 可以节省其中绝大部分成本。¹⁵

在上下文中保留冗长的错误输出。完成错误调试后，上下文中可能仍保留着失败迭代产生的 40 多条堆栈跟踪。修复错误后执行一次 /compact，即可清除这些无用负担。

每次会话开始时都读取所有文件。让 Claude Code 的 glob 和 grep 工具按需查找相关文件，可以避免不必要的预加载，节省超过 100,000 个 token。¹⁵

Subagent 模式

subagents 是专门处理复杂任务的 Claude 实例，能够独立完成工作。它们从干净的上下文开始（不受主对话内容干扰），使用指定工具执行任务，并以摘要形式返回结果。探索结果不会使主对话变得臃肿，只有结论会返回主对话。⁵

内置 Subagent 类型

创建自定义 Subagents

在 .claude/agents/（项目级）或 ~/.claude/agents/（个人级）中定义 subagents：

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code
  changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Subagent 配置字段

Worktree 隔离

Subagents 可以在临时 git worktrees 中运行，从而获得完整且隔离的仓库副本：⁵

---
name: experimental-refactor
description: Attempt risky refactoring in isolation
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

You have an isolated copy of the repository. Make changes freely.
If the refactoring succeeds, the changes can be merged back.
If it fails, the worktree is discarded with no impact on the main branch.

对于可能破坏代码库的实验性工作，worktree 隔离至关重要。

只有边界切实有效，才能称为隔离。 Claude Code v2.1.210 修复了一个缺陷：采用 worktree 隔离的 subagents 可能会修改主检出目录——这恰恰是该机制本应防止的故障。⁶⁹ 如果您将 isolation: worktree 视为安全边界，而不仅仅是便利功能，请将 v2.1.210 作为最低版本。与之配套的权限变更则朝另一个方向发展：从 v2.1.211 起，“始终允许”规则会在仓库根目录跨 worktrees 保留，因此在一个 worktree 中接受的规则也会应用于同一仓库的其他 worktrees。⁶⁹ 这为并行 worktree agents 提供了合理便捷的操作体验，但也意味着在一次性实验中授予的权限会在实验结束后继续存在——授权时应着眼于整个仓库，而不仅仅是眼前的 worktree。

v2.1.216 完成了收尾工作，使 worktree 隔离从缺陷修复提升到可强制执行的级别。⁷⁴ v2.1.210 的修复阻止了 worktree subagents 通过普通 git 调用修改主检出目录，但 git 本身提供了显式重定向机制——git -C <path>、--git-dir 以及 GIT_DIR/GIT_WORK_TREE 环境变量——采用 worktree 隔离的 subagent 仍可利用其中任何一种方式指向共享检出目录。如今，所有这些逃逸通道均已封堵。同一版本还修复了 worktree 会话偶尔落入其他项目遗留 worktree 的问题；阻止工作流和计划任务在 .claude 处被植入符号链接后，将写入操作跟随到项目外部的目标；并使 /rewind 拒绝跨越符号链接和硬链接。这四项修复体现了同一原则：隔离边界不仅要抵御默认行为，还必须能够抵御刻意重定向——例如覆盖 git 环境变量、植入符号链接。如果 isolation: worktree 在您的 harness 中是安全边界，而非便利功能，那么 v2.1.216 就是新的最低版本。

并行 Subagents

对于彼此独立、无需相互协调的研究任务，请使用并行 subagents：⁵

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

每个 agent 都在自己的上下文窗口中运行，查找相关代码并返回摘要。主上下文始终保持干净。

递归防护

如果不限制生成数量，agents 会委派给其他 agents，后者又继续委派给更多 agents。每一层都会损失上下文并消耗 token。递归防护模式通过预算加以约束：¹⁶

#!/bin/bash
# recursion-guard.sh — enforce spawn budget
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"

MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

# Read current depth
current_depth=$(jq -r '.depth // 0' "$STATE_FILE" 2>/dev/null)

if [[ "$current_depth" -ge "$MAX_DEPTH" ]]; then
    echo "BLOCKED: Maximum recursion depth ($MAX_DEPTH) reached" >&2
    exit 2
fi

# Increment depth using safe arithmetic (not ((VAR++)) with set -e)
new_depth=$((current_depth + 1))
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

关键经验： 应使用生成预算，而不能只依赖深度限制。基于深度的限制会追踪父子链条（在第 3 层阻止），却无法约束宽度：第 1 层有 23 个 agents，仍然只是“深度 1”。生成预算会追踪每个父级的活跃子级总数，并设置可配置的上限。预算模型直接对应实际故障模式（agents 总数过多），而不是使用替代指标（嵌套层级过多）。⁷

默认嵌套深度已经变动了 3 次；请勿以此为基础构建系统。 Claude Code v2.1.172（2026年6月10日）允许 sub-agents 生成自己的 sub-agents，最多可嵌套 5 层——此前委派实际上仅限 1 层。⁶² 这一默认值从 v2.1.172 一直保持到 v2.1.216。v2.1.217（2026年7月21日）将其缩减到 1，默认关闭嵌套生成。随后，v2.1.219（2026年7月24日）取了折中值：“Subagents 现在默认可生成嵌套 subagents，最大深度为 3（此前为 1）；设置 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 可禁用嵌套。”⁸⁴ 先是 5，再是 1，然后是 3——后两次调整发生在短短 3 天内。

合理的解读并非其中某个数字才是正确答案，而是平台仍在摸索恰当的默认值。因此，对 harness 而言，继承“当前发布版本所带的值”并不可取。应将嵌套深度视为一项明确的预算：把 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 设置为架构真正需要的深度——对大多数编排而言是 1 或 2——这样升级就无法悄然改变您的 agent 集群委派层数。无论默认值如何反复变化，根本论点始终不变：agents 逐层委派给 agents 的链条消耗上下文和 token 的速度，往往快于其产出结果的速度。深度是一项需要纳入预算的风险，而不是应当追求的能力。无论默认值下一步如何漂移，上述递归防护都能阻止深层树状结构扩散为数百个活跃 agents。只有自行设定的限制，才能确保下次发布后，这个深度数字仍与您的理解一致。

Auto mode 现在会在启动前审查生成操作。 Claude Code v2.1.178 弥补了相应的治理缺口：在 auto mode 下，subagent 生成操作会在 subagent 启动之前由权限分类器评估，而不再等到它开始执行操作后才评估。⁶³ 过去，可以生成一个 subagent，让其请求父会话本应被禁止执行的操作——生成操作本身就成了绕过手段。在生成时进行审查，意味着递归防护终于与权限模型相互衔接：不能再将子级用作洗白步骤，以执行策略禁止的操作。

平台现在原生提供生成预算。 Claude Code v2.1.212（2026年7月）加入了第一方失控循环防护：会话默认最多生成 200 个 subagents（可通过 CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 调整，/clear 会重置计数器），每个会话的 WebSearch 调用也限制为 200 次（CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION）。⁶⁹ 自 v1.0 起，本节一直将生成预算模式记录为用户层脚本；如今平台已原生提供该能力，印证了预算模型优于深度模型。但要留意其校准尺度：200 次生成比上述配置中的 12-agent 预算高出一个数量级。原生上限是防止循环彻底失控的保险丝，并不是针对您的架构调校的预算。请保留用户层防护，以实现每父级预算、深度追踪及符合实际编排需求的限制；再由平台上限兜住任何漏网之鱼。

第一方防护体系现在涵盖 4 个维度。 其中 3 个恰好为本节用户层防护所追踪的指标提供后备保障：每个会话的生成总数（v2.1.212，上限 200，CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION）、嵌套深度（CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH，当前默认值为 3，且事实证明并不稳定），以及并发执行数量（v2.1.217，默认值 20，CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS——一条消息无法再无限扩散出后台 agents）。⁷⁸⁸⁴ v2.1.219 增加了用户层防护通常未覆盖的第 4 个维度：编排宽度，即单个计划工作流可包含的 agent 数量。它以“建议少于 15 个 agents”的默认准则发布，并可通过任意 settings 文件中的 workflowSizeGuideline 配置（将在下文的 Workflow Tool 一节中介绍）。生成预算模式如今在其原本针对的所有维度上都有原生后备保障，此外还多了一个此前未涵盖的维度。

校准方面的提醒仍然适用，但各维度并不均衡。200 次生成和 20 个并发 agents 都是保险丝——比上述配置中的 12-agent deliberation 预算高出一个数量级，其目的在于捕获失控循环，而非塑造架构。宽度准则则是首个与实际预算处于同一尺度的原生数值：每个工作流 15 个 agents，与本指南的 12 个相差无几。采用平台默认值几乎没有成本；如果选择不同的值，则应有切实理由。请将 3 个保险丝设置为您能够充分论证的值，并根据预期编排结构设置宽度准则。

Agent Teams（研究预览版）

Agent Teams 用于协调多个 Claude Code 实例。它们独立工作，通过共享邮箱和任务列表进行沟通，还能相互质疑彼此的发现：⁵

启用方式：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

何时使用 agent teams，何时使用 subagents：

Agent View 与目标循环（2026年5月）

Claude Code v2.1.139 新增了 Agent View。这是一个研究预览版界面，可通过 claude agents 启动，在同一屏幕上显示正在运行、受阻和已完成的 Claude Code 会话。⁴²⁴³ 官方文档将其定位为一种分派和管理多个会话的方式：查看每个会话正在执行的工作，并识别哪些会话需要操作人员介入。⁴³ 这为多 agent 工作提供了最终摘要无法实现的运维视图。

在将 subagent 或 team 模式投入正式使用时，请使用 Agent View：检查哪些会话受阻、哪些仍在运行，以及工作分配是否符合预期架构。不要将其视为质量证明。它提供的是可观测性；工作是否可靠，仍须由测试、审查门禁和证据报告决定。

同一版本还新增了 /goal，用于设置完成条件，使 Claude 能够跨轮次持续运行，直至满足条件；该功能适用于交互模式、-p 和 Remote Control。⁴² 应将 /goal 视为会话级完成循环，而非确定性门禁的替代品。它适合让 agent 始终专注于目标，但在失败必须阻止流程的场景中，测试、引用检查、部署检查和安全 hooks 仍应由命令或脚本提供支持。

Workflow Tool（v2.1.147+）

Claude Code v2.1.147 新增了默认关闭的 Workflow 工具，用于确定性的多 agent 编排。通过 CLAUDE_CODE_WORKFLOWS=1 启用。⁵² 从架构角度看，这一点十分重要，因为它为 Claude Code 提供了第一方编排原语，可处理过去需要自定义分派脚本、邮箱状态和 subagent 协调约定的流程。

不要因此删除外围 harness。Workflow 可以组织执行过程，但无法取代安全模型。请继续将 PreToolUse 和 PostToolUse hooks 作为阻断层；保留生成预算或工作流步骤预算，以防宽度失控；确保文件系统状态可审计；并将最终证据报告置于模型自我评估之外。具体而言：使用 Workflow 规定编排结构；使用 hooks、测试和审查门禁判定事实。

动态工作流现在对宽度有了明确倾向（v2.1.219）。 动态工作流默认采用中等规模准则——“建议少于 15 个 agents”——还可在 /config 的 Dynamic workflow size 下选择其他规模或不设限制。当前准则会显示在运行中工作流的状态行里。⁸⁴ 该数字仅为建议，并不强制执行；它用于引导规划器，而非阻止宽度较大的计划。值得配置它的原因在于其下发机制：新的 workflowSizeGuideline settings 键可在任何 settings 文件中设置，包括托管 settings 和项目 settings；从 v0.3.219 起，它也已包含在 TypeScript SDK settings 类型中。因此，编排宽度可以成为团队或组织统一的标准，而不必由每位操作人员重新摸索。⁸⁵ 请在项目级设置该值，使其反映代码库中工作的实际分解方式。有两点操作注意事项：当 settings 文件控制该值时，/config 中的对应行会隐藏，这是正确行为，但如果不了解原因，看起来就像设置项凭空消失；此外，由于该准则用于引导规划器，而非限制执行，因此它属于结构范畴，而非安全范畴。宽度失控仍应由生成上限负责防范。

值得保留的认知框架是：这是第 4 个第一方防护维度——编排宽度，与生成数量、嵌套深度和并发执行并列——也是 Anthropic 首次按合理工作规模而非失控保险丝来校准数值。每个工作流 15 个 agents，与本指南自 v1.0 起采用的 12-agent deliberation 预算处于同一数量级。当平台默认值与自有预算从不同方向得出相近结论时，这几乎就是此类数字所能获得的最有力独立佐证。

会话分叉与自动后台运行的 MCP（2026年7月）

Claude Code v2.1.212 重塑了两种编排原语。⁶⁹ /fork 现在会根据当前对话状态创建一个新的后台会话——分叉后的会话线独立运行，原会话则继续工作——此前的会话内行为已更名为 /subtask。这种区别对于编排设计十分重要：/subtask 是单个会话生命周期内有明确作用域的临时支线；/fork 则是一种低成本创建并行后台会话的方式，该会话会继承完整上下文，更接近 Ralph-loop 生成，而非 subagent。如果 harness 脚本原本假定 /fork 始终留在当前会话内，那么它们现在会改为分派后台工作。

同一版本会自动将耗时较长的 MCP 调用转入后台：运行超过 2 分钟的 MCP 工具调用会自动转为后台执行（可通过 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 调整阈值）。⁶⁹ 缓慢的 MCP 服务器不再阻塞 agentic 循环——但这也意味着“工具已返回”与“轮次继续执行”不再是同一事件。因此，原本假设 MCP 会同步完成的 hooks 或脚本，应以工具结果为准，而非以轮次边界为准。

对于无头编排，v2.1.211 新增了 --forward-subagent-text（环境变量：CLAUDE_CODE_FORWARD_SUBAGENT_TEXT），可将 subagent 的 assistant 文本转发到 stream-json 输出中。⁶⁹ 消费父级输出流的协调器进程现在可以直接观察 subagent 进度，无需轮询转录记录或等待最终摘要——这是对默认后台运行 subagents 的可观测性补充。v2.1.219 将该能力扩展到了第 1 层之外：深度为 2 或更深层级生成的 subagents 现在也会出现在转发流中，并以生成它们的 Agent tool_use id 作为键。⁸⁴ 这个键才是应当依赖的部分。默认重新启用嵌套后，扁平的 subagent 文本流会产生歧义——该 id 能让协调器识别哪个父级生成了哪个子级，从而直接根据输出流重建委派树，而无需推断。如果您的输出流消费者是按单层 subagents 编写的，它现在将看到此前根本不知道其存在的 agents 所输出的文本；请按生成操作的 tool_use id 分组，不要假定每一条转发行都来自直接子级。

多智能体编排

单智能体AI系统存在结构性盲点：它们无法挑战自己的假设。⁷多智能体审议在任何决策锁定之前，强制要求从多个视角进行独立评估。

跨工具编排（2026年4月）： 谷歌于4月7日开源了Scion——一个多智能体管理程序，可将Claude Code、Gemini CLI和其他”深度智能体”作为并发进程运行，每个进程都拥有独立的容器、git worktree和凭据。可在本地、中心或Kubernetes上运行。其明确的理念是：”以隔离取代约束”——智能体在边界内以高度自治的方式运行，而这些边界由基础设施层强制执行，而非通过提示词。²⁵这直接将子智能体隔离论点扩展到了不同的工具供应商之间。如果您的工作流横跨Claude和OpenAI模型，那么Scion是首个真正实现跨工具子智能体（带有每智能体独立worktree+凭据隔离）的参考实现。

辩论并非银弹： M3MAD-Bench研究集群（2026年初）发现，多智能体辩论会陷入瓶颈，且可能被误导性共识所颠覆——当其他智能体自信地断言错误答案时，有效论证反而会败下阵来。²⁶Tool-MAD通过为每个智能体提供异构工具访问权限，并在评判阶段使用Faithfulness/Relevance分数来改进这一问题。如果您正在构建辩论式编排，请投资于（a）每个智能体的工具异构性，以及（b）量化的评判评分，而不要假定智能体越多=答案越好。

托管式多智能体编排与Outcomes（公开测试版）

如果您不想构建下文所述的审议基础设施，多智能体编排（Multiagent Orchestration）已于2026年5月6日在Claude Managed Agents中进入公开测试阶段。³⁵Anthropic表示：”当工作量过大、单个智能体难以胜任时，多智能体编排允许领导智能体将任务分解为多个部分，并将每个部分委派给具有自身模型、提示词和工具的专家智能体。”³⁵专家智能体”在共享文件系统上并行工作，并为领导智能体的整体上下文做出贡献。”³⁵

追踪功能开箱即用。Anthropic表示：”您还可以在Claude Console中追踪每一个步骤：哪个智能体做了什么、按什么顺序、为什么这样做，让您完全掌握任务委派和执行的全貌。”³⁵

配套的公开测试功能是Outcomes。Anthropic表示：”您编写一份描述成功标准的评分准则，智能体会朝着这一目标工作。一个独立的评分器在自己的上下文窗口中根据您的标准评估输出，因此不会受到智能体推理过程的影响。”³⁵这正是本节后续记录的双门验证模式的托管服务版本：评分准则取代了手写的验证门，独立评分器取代了共识验证器。

当验证需要与您自己的钩子界面（PreToolUse阻塞、退出码语义、自定义dispatcher）集成，或者harness必须在没有外部依赖的情况下运行时，自托管审议仍然是正确的选择。当标准委派加上评分准则评估正是您实际需要的契约时，托管式多智能体则是正确答案。

最简可行审议

从2个智能体和1条规则开始：智能体必须在看到彼此的工作之前进行独立评估。⁷

Decision arrives
  |
  v
Confidence check: is this risky, ambiguous, or irreversible?
  |
  +-- NO  -> Single agent decides (normal flow)
  |
  +-- YES -> Spawn 2 agents with different system prompts
             Agent A: "Argue FOR this approach"
             Agent B: "Argue AGAINST this approach"
             |
             v
             Compare findings
             |
             +-- Agreement with different reasoning -> Proceed
             +-- Genuine disagreement -> Investigate the conflict
             +-- Agreement with same reasoning -> Suspect herding

这一模式涵盖了80%的价值。其余的一切只是渐进式改进。

信心触发器

并非每个任务都需要审议。信心评分模块从四个维度进行评估：¹⁷

1. 歧义性 - 该查询是否存在多种有效的解读？
2. 领域复杂度 - 是否需要专业知识？
3. 风险高低 - 决策是否可逆？
4. 上下文依赖性 - 是否需要理解更广泛的系统？

得分映射到三个级别：

阈值会根据任务类型自适应调整。安全决策需要0.85的共识。文档变更只需0.50。这既能避免对简单任务过度工程化，又能确保高风险决策得到充分审视。⁷

状态机

七个阶段，每个阶段由前一个阶段把关：⁷

IDLE -> RESEARCH -> DELIBERATION -> RANKING -> PRD_GENERATION -> COMPLETE
                                                                    |
                                                              (or FAILED)

RESEARCH： 独立的智能体调查主题。每个智能体获得不同的角色（技术架构师、安全分析师、性能工程师等）。上下文隔离确保智能体在研究期间无法看到彼此的发现。

DELIBERATION： 智能体查看所有研究发现并生成替代方案。辩论智能体识别冲突。综合智能体合并不矛盾的发现。

RANKING： 每个智能体在5个加权维度上对每个提议方案进行评分：

双门验证架构

两个验证门在不同阶段捕获问题：⁷

Gate 1：共识验证（PostToolUse hook）。在每个审议智能体完成后立即运行： 1. 阶段必须至少达到RANKING 2. 至少有2个智能体完成（可配置） 3. 共识得分满足任务自适应阈值 4. 如果有任何智能体提出异议，必须记录其顾虑

Gate 2：Pride Check（Stop hook）。在会话关闭前运行： 1. 多样化方法：代表了多个独特的角色 2. 矛盾透明度：异议有记录在案的理由 3. 复杂度处理：至少生成了2个备选方案 4. 共识信心：被分类为强（高于0.85）或中等（0.70-0.84） 5. 改进证据：最终信心度超过初始信心度

两个钩子位于不同的生命周期节点，恰好契合故障的实际发生方式：有些是瞬时的（评分糟糕），有些则是渐进的（多样性不足、缺失异议记录）。⁷

为何意见一致是危险的

Charlan Nemeth从1986年起一直研究少数派异议，直至她2018年的著作In Defense of Troublemakers。有异见者参与的群体所做的决策，比迅速达成一致的群体更优。异见者并不一定要正确。异议这一行为本身就迫使多数派审视他们原本会跳过的假设。¹⁸

Wu等人测试了LLM智能体是否能够进行真正的辩论，发现如果没有结构性的不同意见激励机制，无论正确与否，智能体都会向最自信的初始回答收敛。¹⁹Liang等人将根本原因识别为”思想退化（Degeneration-of-Thought）”：一旦LLM对某个立场建立起信心，自我反思就无法生成新颖的反驳论点，这使得多智能体评估在结构上成为必需。²⁰

独立性是关键的设计约束。两个智能体在能看到彼此发现的情况下评估同一部署策略，得分为0.45和0.48。同样的智能体在没有可视性的情况下：0.45和0.72。0.48和0.72之间的差距，正是从众的代价。⁷

检测虚假一致

从众检测模块跟踪那些表明智能体在没有真正评估的情况下达成一致的模式：⁷

评分聚集： 每个智能体在10分制下的评分都在0.3分以内，这意味着共享上下文污染，而非独立评估。当五个智能体评估一次身份验证重构，安全风险评分全部介于7.1和7.4之间时，使用全新的上下文隔离重新运行后，分数分散到了5.8-8.9。

模板化异议： 智能体复制彼此的顾虑语言，而非生成独立的反对意见。

缺失少数派视角： 来自具有冲突优先级的角色们（安全分析师和性能工程师很少在所有事情上达成一致）的一致赞同。

从众检测器能捕获明显的情况（约10-15%的审议中智能体过快收敛）。对于其余的85-90%，共识门和Pride Check门提供了充分的验证。

审议中行不通的做法

自由形式的辩论轮次。 关于数据库索引讨论的三轮往返文本辩论产生了7,500个token的辩论内容。第1轮：真正的分歧。第2轮：重述立场。第3轮：用不同的措辞表达相同的论点。结构化的维度评分取代了自由形式的辩论，在提升排名质量的同时将成本降低了60%。⁷

单一验证门。 最初的实现在会话结束时运行一个验证钩子。一个智能体以0.52的共识得分（低于阈值）完成了审议，然后继续处理无关任务长达20分钟，会话结束钩子才标记出该故障。拆分为两个门（一个在任务完成时，一个在会话结束时）后，能在不同的生命周期节点捕获相同的问题。⁷

审议的成本

每个研究智能体处理大约5,000个token的上下文，生成2,000-3,000个token的发现。3个智能体的话，每个决策需要额外消耗15,000-24,000个token。10个智能体的话，大约需要50,000-80,000个token。⁷

按当前的Opus定价计算，3智能体审议的成本约为$0.68-0.90。10智能体审议的成本为$2.25-3.00。该系统会在大约10%的决策上触发审议，因此摊销到所有决策上的成本为每会话$0.23-0.30。这是否值得，取决于一次糟糕决策的代价有多大。

何时审议

CLAUDE.md 设计

CLAUDE.md 是面向 AI agent 的操作策略，而不是供人阅读的 README。²¹agent 无需理解您为何使用约定式提交，只需知道要运行的确切命令，以及怎样才算“完成”。

优先级层次

规则文件会自动加载并提供结构化上下文，避免 CLAUDE.md 变得杂乱。⁶

哪些内容会被忽略

以下模式通常不会对 agent 的行为产生任何可观察的影响：²¹

没有命令的说明性段落。“我们重视整洁且经过充分测试的代码”只是文档，并非操作指令。agent 读过后仍会继续编写没有测试的代码，因为其中没有可执行的指示。

含糊不清的指令。“谨慎处理数据库迁移”并不构成约束。“应用迁移前运行 alembic check。如果缺少降级路径，则中止操作。”才是有效约束。

相互矛盾的优先事项。“快速推进并迅速发布”，同时又要求“确保全面的测试覆盖率”“将运行时间控制在5分钟以内”以及“每次提交前运行完整的集成测试”。agent 无法同时满足这4项要求，最终往往默认跳过验证。²¹

缺乏强制检查的风格指南。仅要求“遵循 Google Python Style Guide”，却不提供 ruff check --select D，agent 就没有验证合规性的机制。

哪些方式有效

命令优先的指令：

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

闭环定义：

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

按任务组织的章节：

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`

升级处理规则：

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- Never: delete files to resolve errors, force push, or skip tests

编写顺序

如果从头开始，请按以下优先级添加章节：²¹

1. 构建和测试命令（agent 必须先掌握这些命令，才能完成任何有用的工作）
2. 完成标准（防止虚假完成）
3. 升级处理规则（防止采用破坏性的变通方案）
4. 按任务组织的章节（减少对无关指令的解析）
5. 目录作用域（对于 monorepos：确保各服务的指令彼此隔离）

在前4项正常发挥作用之前，先跳过风格偏好。

平台现在可以为您审查 CLAUDE.md。从2026年7月初发布的版本（v2.1.203–v2.1.206）开始，/doctor 会分析 CLAUDE.md，并建议精简模型能够从代码库自行推断的内容，例如重复描述的目录布局、代码已经体现的框架惯例，以及与软件包脚本重复的命令列表。⁶⁸这从第一方角度印证了本节的核心观点：只有记录 agent 无法推断的信息（策略、阈值、闭环定义），指令所占用的 token 才物有所值；能够直接从磁盘读取的信息则不必赘述。当 CLAUDE.md 大幅扩充后，请运行 /doctor，并将其精简建议作为起点。不过，如果它将某些操作规则标记为“可推断”，而这些规则实际上是不可或缺的约束，而非单纯描述，请予以保留。

文件导入

在 CLAUDE.md 中引用其他文件：

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

导入语法包括：相对路径（@docs/file.md）、绝对路径（@/absolute/path.md）或主目录路径（@~/.claude/file.md）。最大深度为5层导入。⁶

跨工具指令兼容性

AGENTS.md 是各大主流 AI 编码工具均可识别的开放标准。²¹如果团队使用多种工具，请将 AGENTS.md 作为规范来源，并把相关章节同步到各工具的专用文件中：

无论使用哪种工具，AGENTS.md 中的模式（命令优先、定义闭环、按任务组织）都适用于任何指令文件。不要维护多套逐渐偏离的并行指令。应编写一份权威来源，再将其同步到其他文件。

Codex 对等功能说明

Codex 现在已为主要 harness 层提供一流的对等功能，但迁移需要转换模式，而不是简单复制文件。Codex 会在工作开始前读取 AGENTS.md，并将 ~/.codex 中的全局指导与项目级及嵌套仓库指令分层叠加。³¹Codex skills 采用相同的 SKILL.md 思维模型，并遵循渐进式披露原则：Codex 起初只获取 skill 名称、描述和文件路径，仅在决定使用该 skill 时才加载完整内容。³²Codex 还提供原生 hooks、插件捆绑的 hooks、托管 hooks、MCP 支持和明确的 subagent 工作流。³³³⁴

Codex v0.138.0–v0.139.0 加强了复杂工作区中的 AGENTS.md 发现机制：现在通过环境的文件系统抽象层进行加载，并在发现遍历过程中保留逻辑路径。因此，即使工作区位于远程文件系统或采用符号链接目录树，也能选择正确的文件。⁶¹当规范 AGENTS.md 是权威来源，而 agent 又在挂载、容器实体化或通过符号链接检出的目录中运行时，这一点尤为重要。在这些场景中，简单的路径遍历可能悄无声息地选择错误的指令文件，甚至完全找不到文件。如果在多个服务间同步一份权威 AGENTS.md，应将此版本作为可信基线，以确保 agent 实际加载的文件正是您编写的那一份。

随后，Codex v0.141.0 又加强了远程执行路径：远程执行器现在通过经过身份验证、端到端加密的 Noise 中继通道连接（控制平面和执行器不再需要信任二者之间的中继）；跨平台远程执行会保留执行器的原生工作目录和 shell；TLS 也开始接受企业代理使用的 P-521 证书签名。⁶⁵如果编排系统需要跨越网络边界驱动 Codex 执行器，这意味着安全模型已从“信任中继”转变为“端到端加密”。任何远程执行器拓扑都应以此版本作为基线。

2026年7月的版本线表明，两种运行时正从不同方向趋近于相同的基础能力。⁷²Codex v0.143.0 默认通过工具搜索加载 MCP 工具，即延迟加载工具架构，并按需获取，而不是预先全部载入上下文。这与 Claude Code 通过 ToolSearch 界面提供的延迟工具加载模式相同，也是两种运行时面对大量 MCP 工具导致上下文膨胀时的正确解决方案。Codex v0.144.0 新增 writes 应用审批模式：只读操作无需提示即可运行，写入操作则需要审批。这是一种介于只读与自动批准之间、真正全新的权限模式，而 Claude Code 的模式列表并无直接对应项（最接近的是 plan 模式，但它会完全阻止写入，而不是逐次提示审批）。同一版本还将 MCP 交互式身份验证正式推向 GA。v0.144.5 则扩展了危险命令检测，与 Claude Code 在 v2.1.183 和 v2.1.208 中推出的破坏性命令防护措施相呼应。对于跨运行时 harness 设计而言，趋同才是重点：延迟工具加载、分级写入审批和意图级危险命令阻止正在成为必备能力，而不再是供应商之间的差异化卖点。

Codex v0.145.0 从两个方面进一步推动了这种趋同。⁷⁶选择启用的 multi-agent V2 界面已经趋于稳定：现在可以配置 sub-agent 模型、推理级别和并发量，之前移除的 agent 角色也已恢复。这是 Codex 对 .claude/agents/ frontmatter 中逐 subagent 配置模型和工作强度的回应。此外，/import 已扩展为完整的跨 harness 迁移工具：除了 v0.140.0 已推出的 Claude Code 设置导入功能外，现在还能迁移 Claude Code 和 Cursor 的设置，包括 MCP 服务器、插件、会话、命令和项目作用域内的记忆。对于同时运行两种运行时的团队，二者之间单向迁移的成本正在持续下降。您在 Claude Code 上构建的 harness 层——服务器、作为命令的 skills、记忆——正日益成为可移植状态，而不是供应商锁定。

实际映射如下：

重要区别在于：Claude subagents 可以根据描述自动选择，而 Codex 目前将 subagent 工作流定义为显式调用。因此，在 Codex 中，skills 和 hooks 才是始终启用的 harness 行为的合理默认选择；subagents 则适用于有意识安排的并行工作、审查和探索。

测试您的指令

验证 agent 是否确实读取并遵循您的指令：

# Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
claude --print "What is your definition of done?"

试金石：让 agent 解释您的构建命令。如果它无法逐字复述，说明指令可能过于冗长（内容被挤出上下文）、过于含糊（agent 无法提取可执行指令），或者根本未被发现。GitHub 对2,500个仓库的分析发现，含糊不清是大多数失败的根源。²¹

生产环境模式

Opus 4.7 长时任务模式（2026年4月）

Claude Opus 4.7（2026年4月16日）发布了一系列特定功能，改变了 harness 需要防范的问题：²⁹

• 工具故障韧性： Opus 4.7 能够从导致 Opus 4.6 会话中止的工具故障中恢复并继续执行。您可以减少（但不能完全移除）subagents 代码中的防御性重试封装。保留 hook 层的防护措施；精简提示词中“如果工具失败，则重试3次”之类的脚手架。
• xhigh 工作强度级别（仅限 Opus-4.7）： 位于 high 与 max 之间。建议将其作为编码和智能体工作负载的默认选项。对于长时间运行的 subagents，xhigh 的表现明显优于 high，而 token 成本的增长低于性能增幅。max 仍适合需要一次性完成的高难度推理；xhigh 则更适合持续性任务。
• Token 预算上限： 可通过 output_config.task_budget 为每次智能体运行配置（beta header task-budgets-2026-03-13）。模型能够看到持续更新的倒计时，并根据预算合理调整工作范围，避免预算意外耗尽。适用于智能体循环：既能让 token 开销可预测，也不会牺牲短提示词任务的质量。
• 隐含需求感知： 首个通过“隐含需求”测试的 Claude 模型，能够识别用户的字面请求何时未能充分表达其实际需求。因此，CLAUDE.md 中“澄清规则”部分的重要性有所降低。如果您的 CLAUDE.md 用了200行“当用户询问Y时，还应考虑X”之类的防护规则，请删减模型现已原生覆盖的部分。

Worktree 基准、沙箱路径与管理员设置（2026年5月7日）

Claude Code v2.1.133 新增了4项管理员级设置，生产环境 harness 值得关注：³⁹

最需要向用户特别说明的是 worktree.baseRef 的回退：依赖 v2.1.128-v2.1.132 行为（worktree 从本地 HEAD 创建分支）的智能体，将无法在新 worktree 中访问尚未推送的工作，除非主动恢复原有设置。

用于企业可观测性的 OTel 反馈调查（2026年5月8日）

Claude Code v2.1.136 新增了 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL，让通过 OpenTelemetry 收集反馈的企业能够重新启用会话内质量调查。⁴⁰ 如果您的组织将 OTel 事件汇入集中式可观测性堆栈，此环境变量会将调查重新接入数据路径，使质量信号与延迟和错误指标通过同一管道传输。应将其视为选择启用的功能：默认情况下调查处于关闭状态，这对于未部署 OTel 的环境而言是正确选择。

企业启动器与 MCP 规模下的性能（2026年7月）

v2.1.207 中有两项变更对生产部署至关重要。⁶⁸ CLAUDE_CODE_PROCESS_WRAPPER 允许托管环境通过企业封装二进制文件启动 Claude Code 进程。它为端点代理、启动时策略检查以及所有进程都必须在指定监督程序下运行的环境提供了集成点。如果您的企业过去通过 shell 别名或分叉的启动脚本来变通实现，现在已有正式支持的衔接机制。

同一版本还大幅削减了 harness 最容易感受到的运行时开销：在包含大量 MCP 工具的会话中，工具使用轮次最高可提速 7倍，会话转录内容则最多可缩小 79倍。⁶⁸ 这在一定程度上缓和了（但并未推翻）将成本视为架构因素中的指导原则：对于无状态的一次性操作，CLI 优先仍然占优；但携带数十个 MCP 工具的 harness 不再需要承担春季版本中的逐轮性能损耗，转录内容存储也不再是长时间自主运行的隐性成本。

quality loop

所有非简单变更都必须经过以下审查流程：

1. 实现 - 编写代码
2. 审查 - 重新阅读每一行，发现拼写错误、逻辑错误和表述不清之处
3. 评估 - 执行 evidence gate，检查模式、边缘情况和测试覆盖率
4. 改进 - 修复所有问题，绝不推迟到“以后”
5. 纵观全局 - 检查集成点、导入项和相邻代码是否出现回归
6. 重复 - 如果任一 evidence gate 标准未通过，则返回第4步
7. 报告 - 列出具体变更及验证方式，并引用明确证据

evidence gate

“我认为”和“应该可以”都不算证据。请引用文件路径、测试输出或具体代码。

如果无法为任意一行提供证据，请返回“改进”步骤。²²

人工合并权限

2026年5月一项针对29,585个AI智能体拉取请求生命周期的 arXiv 研究，将操作执行权与合并治理权区分开来。⁴⁷ 其中的架构启示简单明了：智能体可以启动工作、推进分支、创建PR、审查工作并总结风险，而合并权限应继续作为独立的治理边界。

应在 harness 中明确划定这条边界。允许智能体准备PR并收集证据；除非组织另有经过审计的自动化策略，否则合并、发布及破坏性仓库操作必须获得人工批准。如果由自动化系统执行合并，应保留日志，明确区分实际执行者与授权合并的人员或策略。

错误处理模式

原子文件写入。 多个智能体同时写入同一个状态文件会破坏 JSON。先写入 .tmp 文件，再通过 mv 以原子方式移动。在同一文件系统中，操作系统保证 mv 具有原子性。¹⁷

# Atomic state update
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

状态损坏恢复。 如果状态损坏，恢复模式应从安全默认值重新创建状态，而不是直接崩溃：¹⁶

if ! jq -e '.depth' "$RECURSION_STATE_FILE" &>/dev/null; then
    # Corrupted state file, recreate with safe defaults
    echo '{"depth": 0, "agent_id": "root", "parent_id": null}' > "$RECURSION_STATE_FILE"
    echo "- Recursion state recovered (was corrupted)"
fi

((VAR++)) bash 陷阱。 当 VAR 为0时，((VAR++)) 会返回退出码1，因为 0++ 的求值结果为0，而 bash 将其视为 false。启用 set -e 后，这会终止脚本。请改用 VAR=$((VAR + 1))。¹⁶

影响范围分类

根据影响范围对每项智能体操作进行分类，并实施相应的管控：²

Remote Control（通过任意浏览器或移动应用连接到本地 Claude Code）将“外部”管控从阻塞式等待转变为异步通知。您通过手机审查上一项任务时，智能体可以继续处理下一项任务。²

自主运行的任务规范

有效的自主任务应包含3个要素：目标、完成标准和上下文指引：¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

COMPLETION CRITERIA:
- All tests in tests/test_deliberation_lib.py pass (81 tests)
- post-deliberation.sh validates consensus above 70% threshold
- recursion-guard.sh enforces spawn budget (max 12 agents)
- No Python type errors (mypy clean)

CONTEXT:
- Follow patterns in lib/deliberation/state_machine.py
- Consensus thresholds in configs/deliberation-config.json
- Spawn budget model: agents inherit budget, not increment depth

标准必须可由机器验证，例如测试通过或失败、linter 输出、HTTP 状态码和文件存在性检查。早期有一项任务要求智能体“编写能够通过的测试”，结果它生成了 assert True 和 assert 1 == 1。技术上无可挑剔，实际上毫无价值。¹⁶

需要警惕的故障模式

具体会话轨迹

以下是一次自主运行处理包含5个故事的 PRD 时的会话轨迹：²

1. SessionStart 触发。 dispatcher 注入当前日期、项目检测结果、理念约束和成本跟踪初始化信息。共触发5个 hooks，总耗时180ms。

2. 智能体读取 PRD，规划第1个故事。 UserPromptSubmit 触发。dispatcher 注入当前项目上下文和会话漂移基线。

3. 智能体调用 Bash 运行测试。 PreToolUse:Bash 触发，执行凭据检查、沙箱验证和项目检测，耗时90ms。测试运行后，PostToolUse:Bash 触发：记录活动心跳并检查漂移。

4. 智能体调用 Write 创建文件。 PreToolUse:Write 触发，检查文件范围。PostToolUse:Write 触发，执行 lint 检查并跟踪提交。

5. 智能体完成该故事。 Stop 触发。质量关卡检查：智能体是否引用了证据？是否使用含糊推测的措辞？差异中是否存在 TODO 注释？如有任一检查失败，则以退出码2结束，智能体继续工作。

6. 独立验证： 一个全新的智能体运行测试套件，不采信先前智能体的自述报告。

7. 3个代码审查智能体并行启动。 每个智能体独立审查差异。如果任一审查者标记 CRITICAL，该故事将重新进入队列。

8. 故事通过，加载下一个故事。 对全部5个故事重复此循环。

处理5个故事共触发约340次 hooks，hooks 总耗时约12秒。这些开销在一次通宵运行中防止了3次凭据泄露、1条破坏性命令和2次不完整实现。

案例研究：通宵处理 PRD

一个生产环境 harness 在8次通宵会话中处理了12个 PRD（共47个故事）。以下指标对比了前4个 PRD（最简 harness：仅有 CLAUDE.md）与后8个（完整 harness：hooks、skills、质量关卡和多智能体审查）。

两次凭据泄露导致必须轮换 API 密钥并审计下游服务，事件响应耗时约4小时。预防同类事件的 harness 开销仅为每个故事执行2.4秒的 bash。错误完成率从35%降至4%，原因在于 Stop hook 会先独立运行测试，再允许智能体报告任务完成。

安全注意事项

可信 Agent 的五项原则（Anthropic，2026年4月）

Anthropic 于2026年4月9日发布了正式的 Agent 可信度框架。²⁷这五项原则与本指南中的 evidence gate 思想一脉相承，并进一步拓展了它：

Anthropic 还将 MCP 捐赠给 Linux 基金会旗下的 Agentic AI Foundation，与 AGENTS.md（现由 OpenAI、Google、Cursor、Factory、Sourcegraph 共同维护）一道推进生态建设。Agent 互操作性标准如今已实现供应商中立。²⁷

MCP 的无状态轮次与自报身份（2026年7月）。 MCP 规范正在向无状态核心（SEP-2575）过渡，不再使用过去承载服务器身份的有状态初始化握手。7月16日合并的一项规范草案变更（PR #3002）将身份恢复为一个可选接口：服务器可在响应的 _meta 中包含 io.modelcontextprotocol/serverInfo 对象，而请求中的 clientInfo 也变为可选项。⁷¹与安全最相关的是规范对信任的说明：此身份由服务器自行报告且未经验证——仅用于显示和记录——不应作为安全决策的依据。如果您的 harness 根据 MCP 服务器声明的名称设置允许列表、权限规则或基于日志的审计，请牢记：该名称只是一项声明，并非凭据。应将信任固定在传输方式和配置上（即您在何端点配置了哪台服务器），绝不能依赖服务器的自我陈述。最终版无状态规范修订计划于2026年7月28日发布，本节的协议级细节预计将在下次更新中进一步明确。

Skill 沙箱工具：对于将 skills 视为攻击面的团队，Permiso 的 SandyClaw（发布于2026年4月2日）可在专用沙箱中运行 skills，并根据 Sigma/YARA/Nova/Snort 检测结果给出有证据支撑的判定。这是 skill 沙箱类别中的首款产品。²⁸

沙箱

Claude Code 支持可选的沙箱模式（通过 settings.json 或 /sandbox 命令启用），该模式利用操作系统级隔离机制（macOS 上的 seatbelt、Linux 上的 bubblewrap）限制网络访问和文件系统操作。启用后，沙箱会阻止模型任意发起网络请求，也不能访问项目目录之外的文件。未启用沙箱时，Claude Code 采用基于权限的模型，由您批准或拒绝各项工具调用。¹³

2026年5月的安全基线。 Claude Code v2.1.149 修复了 PowerShell 工作目录权限绕过问题、多处 PowerShell 允许规则和陈旧变量的权限分析缺陷，以及一项 git worktree 沙箱写入允许列表错误。后者错误地覆盖了整个主仓库根目录，而非仅覆盖共享的 git 内部数据。⁵³如果您的 harness 允许使用 PowerShell 或采用 worktree 隔离的 Agent，请将 v2.1.149+ 视为最低版本，并严格限制 shell 规则。宽泛的 PowerShell(*) 和整个仓库的写入例外只是编排捷径，不能充当安全边界。

OpenAI Agents SDK 沙箱限制收紧（v0.17.0，2026年5月8日）。 在 OpenAI 方面，openai-agents-python v0.17.0 收紧了一个与之对应的边界：LocalFile.src 和 LocalDir.src 现在必须位于实体化操作的 base_dir 内（应用清单时 SDK 进程的当前工作目录），除非通过带有 SandboxPathGrant 的 Manifest.extra_path_grants 明确授权该来源。⁴¹相对本地来源从 base_dir 开始解析；绝对路径则必须已位于其中，或持有相应授权。此举修复了本地构件边界问题：旧版本允许清单将任意主机路径拉入沙箱工作区。迁移时，请在清单级别使用 SandboxPathGrant(path=..., read_only=True) 声明可信主机根目录，以只读方式挂载。应将 extra_path_grants 视为可信的应用程序配置；绝不能根据模型输出或不可信的清单输入填充授权。

OpenAI Agents SDK 后续基线（v0.17.3）。 0.17.1至0.17.3版本进一步强化了沙箱与会话：限制压缩包解压、验证 GitRepo 子路径、提供更清晰的沙箱提供商错误、避免在沙箱命令中暴露挂载点凭据、拒绝相对沙箱工作区根目录，并处理 Vercel 沙箱的终止状态。⁵⁴如果使用 OpenAI 托管或由提供商支持的沙箱，而非仅使用 Claude Code hooks，请将 0.17.3 视为本节模式的当前最低版本。

跨产品的三种隔离模式（Anthropic，2026年5月）

Anthropic 的工程文章“How we contain Claude across products”（2026年5月25日）以供应商自身的视角，系统阐述了本节分散讲解的各项原则——包括上述设置级沙箱、worktree 隔离基线，以及将一切视为不可信的立场。⁸¹其核心做法是让隔离强度与产品使用场景相匹配，而这种对应关系本身就是要点：不存在唯一正确的隔离设计，只有与监督者身份和潜在风险相称的隔离方案。

• 临时 gVisor 容器（claude.ai）。 服务器端执行发生在隔离基础设施上的 gVisor 容器中，每个会话配有临时文件系统。其威胁模型聚焦基础设施和租户隔离——用户的计算机根本无法被访问，因此无须防护本地内容。
• 人工参与的操作系统沙箱（Claude Code）。 这是上述沙箱段落所述模式的策略化表达：macOS 使用 Seatbelt，Linux 使用 bubblewrap；允许读取，将写入限制在工作区内，并默认禁止网络访问——边界未涵盖的操作由人工审批。Anthropic 已将该运行时开源（sandbox-runtime），使边界可供审计。文章直言不讳地指出了薄弱环节：大约93%的权限提示会被批准。Auto Mode 分类器能在执行前拦截约83%的冒进行为，同时将审批提示减少84%，正是因为审批疲劳属于安全属性，而非单纯的用户体验问题。这正是本指南自 v2.1.193 起持续追踪的检查层立场。
• 密封虚拟机（Claude Cowork）。 在平台虚拟机监控程序上运行完整虚拟机——macOS 使用 Apple Virtualization framework，Windows 使用 HCS——仅挂载选定工作区和 .claude 文件夹；主机上的其他内容完全不可见。凭据绝不进入虚拟机：它们留在主机钥匙串中，每个会话仅获得一个限定范围、可独立撤销的令牌。虚拟机内的防御性 MITM 代理负责强制执行此机制，只放行携带虚拟机自身预配置会话令牌的请求。攻击者嵌入的密钥会在边界处被拒绝，因为只有虚拟机知晓其来源。

这一分类体系背后的设计原则才是真正可迁移的部分。首先在环境层实施隔离，其次才在模型层进行引导：任何概率性防御都存在非零漏检率，因此必须由确定性边界兜住提示词级引导遗漏的风险——这正是本指南“hooks 保证执行”论点的供应商版本。让隔离强度与用户的监督能力相匹配：开发者可以在批准前评估 bash 命令，知识工作者却未必具备这种能力——因此 Code 提供权限对话框，而 Cowork 使用密封虚拟机。优先采用久经考验的基础组件，而非自行编写隔离代码：与 Anthropic 自有的定制允许列表代理和配置解析器相比，虚拟机监控程序、seccomp 和容器运行时经受住了更充分的对抗性检验。将项目本地配置和工具输出视为不可信：文章要求像对待任何来自互联网的入站请求一样，对待项目打开和配置加载；即使工具本身可信，也要将其输出视为攻击面——这与本指南对 Agent 间消息、subagent 读取的内容以及自报的 MCP 身份所采取的立场完全一致。将凭据留在沙箱之外：使用限定范围、可撤销、每个会话独立的令牌，而不是 Agent 可能泄露的环境常驻密钥。

设置接口正逐步落实第一项原则（v2.1.219）。 “首先在环境层实施隔离”容易获得认同，却一直难以真正配置，因为 Claude Code 的沙箱会通过询问来处理规则未覆盖的情况——正如上文93%的批准率所揭示的那样，权限提示不过是披着确定性外衣的概率性防御。sandbox.network.strictAllowlist 消除了出站访问中的询问环节：启用后，沙箱命令向不在允许列表中的主机发出的请求会被直接拒绝，而非弹出提示。⁸⁴将它与 v2.1.216 的 sandbox.filesystem.disabled 配合使用，这两项设置便能组合成明确的安全态势，而非杂乱堆叠的开关——文件系统与网络隔离可以独立选择，网络隔离现在也能变为确定性边界。对于无人值守的 harness，网络隔离更为重要，因为出站通道会让注入指令演变成数据外泄，而审批疲劳的终极情形是键盘前根本无人可感到疲惫。代价则是确定性边界一贯的代价：允许列表必须准确无误，遗漏的主机会遭到不透明的拒绝，而不是触发询问。请列出 Agent 确实需要访问的主机，然后取消提示。

这些措施都无法取代 hook 层，而是位于其下方。隔离模式构成确定性基线，而本指南记录的 worktree 强制执行演进史也从小处印证了同一道理：边界只有在面对蓄意重定向时仍然有效，才称得上真正的边界；最有可能坚守边界的基础组件，往往并非为临时需求专门编写。

权限边界

权限系统在多个层级对操作进行管控：

参数级权限规则（2026年6月）

Claude Code v2.1.178 将权限规则从工具级扩展到参数级：Tool(param:value) 根据工具的输入参数进行匹配，并以 * 作为通配符。典型示例是 Agent(model:opus)——该规则禁止在特定模型层级上生成 subagents。⁶³从架构角度看，这填补了上述四层表格无法表达的空白：过去只能整体允许或拒绝某个工具，无法约束其调用方式。如今，治理策略可以将“允许生成 subagents，但不得使用 Fable 5 层级”或“允许使用 Bash，但不得携带此标志”定义为确定性规则，而非提示词级请求。

与之配套的托管设置 enforceAvailableModels（v2.1.175）自上而下约束模型选择：它固定 Default 模型，并阻止用户或项目范围的设置扩大托管的 availableModels 允许列表。⁶³二者可以协同使用——允许列表定义会话中存在哪些模型层级，参数级规则则限制 subagents 如何从中选择。截至 v2.1.196，管理员还可在组织控制台设置组织范围的默认模型，该模型在 /model 中显示为“Org default”。如此一来，整个 Agent 群体都能继承受治理的默认值，无须每位操作者逐一固定模型——形成与允许列表上限互为补充的基线。

路径范围的允许规则锚定至工作目录（2026年7月）

Claude Code v2.1.214 修复了路径范围权限规则中一个不易察觉的过度匹配问题：使用单层 dir/** 模式的允许规则——例如 Edit(src/**)——过去会自动批准对任意深度、任何名为 src 的目录进行编辑，包括 vendor/some-package/src/ 以及规则编写者从未打算授权的所有其他嵌套 src/。此类规则现在仅锚定至 <cwd>/dir；如果确实需要任意深度匹配，请明确使用 **/dir/**。⁷⁴拒绝和询问规则则有意保留旧有的任意深度匹配方式。这种不对称正是正确的故障安全设计：允许规则匹配范围过窄时会安全失败（弹出提示），而拒绝规则匹配范围过窄时会开放失败（应阻止的路径得以漏网）——因此允许规则变得更严格，拒绝规则则继续保持宽泛。如果您的设置依赖单层允许模式覆盖嵌套路径，那么从 v2.1.214 起，它们已悄然不再这样做。这正是修复按预期生效的表现，但仍值得检查一遍允许列表，重新明确声明真正需要的覆盖范围。

Auto Mode 破坏性命令防护机制（2026年6月）

Claude Code v2.1.183 缩小了 Auto Mode 对可能悄然丢失工作成果或摧毁环境的操作所造成的影响范围。除非您在会话中明确提出，否则 Auto Mode 现在会直接阻止以下操作：破坏性 git 操作（git reset --hard、git checkout -- .、git clean -fd、git stash drop）；当相应提交并非由 Agent 在本会话中创建时执行 git commit --amend；以及基础设施拆除操作（terraform destroy、pulumi destroy、cdk destroy），除非您明确指定了具体堆栈。⁶⁵从架构角度看，这是对上述生成审查和参数级规则的补充：它并非限制使用哪个工具或工具如何生成，而是根据意图管控一小组明确且不可逆的命令——Agent 仍可运行这些命令，但只能遵照明确指令，不能擅自执行。对于自治 harness，应在自己的 PreToolUse hooks 中贯彻同一原则：会破坏状态的命令理应默认拒绝，只有操作者的明确信号才能解除限制。

2026年7月：Auto Mode 进入企业平台，同时一项提示变为不可豁免。 Auto Mode 在 v2.1.207 中于 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 正式可用，并提供 disableAutoMode 托管设置作为企业退出选项——如今，每个第一方企业平台都能采用“分类器充当检查层”的安全态势，禁用它已成为明确的治理决策，而不再是平台能力缺口。⁶⁸随后，v2.1.208 将灾难性删除防护设为绝对规则：灾难性删除的确认提示现在会穿透 --dangerously-skip-permissions 和 Auto Mode。⁶⁸这是一个值得注意的先例——Claude Code 首次出现任何权限态势都无法豁免的确认提示，包括明确的绕过标志。假定 --dangerously-skip-permissions 确实意味着零提示的自治 harness 设计应考虑这一例外；它恰好会在无人值守循环可能造成最严重且无法恢复的破坏时触发。

防伪造防护机制（2026年7月）

v2.1.203至v2.1.206版本封堵了 Agent 伪造自身审计记录的两条路径。⁶⁸首先，一项 Auto Mode 规则现在会阻止篡改会话转录文件——会话自身的工具调用已无法重写会话记录。其次，后台任务通知现在会明确说明任务运行期间没有发生任何人工输入。第二项修复针对一种隐蔽的故障：过去，模型在总结后台任务时可能声称（或编造）转录中出现了从未发生的“批准”，而通知中没有任何内容能够反驳这种说法。如今，通知本身便构成了反证。

这一架构经验同样适用于 Evidence Gate：转录、通知和日志都是审计接口，而审计接口绝不能由其审计对象写入。平台如今会为自己的转录强制执行此规则；您的 harness 也应如此——证据报告、测试输出和 deliberation 记录都应置于模型可写路径之外。

提示词注入防御

Skills 和 hooks 可构成针对提示词注入的纵深防御：

带有工具限制的 Skills可防止遭到入侵的提示词获取写入权限：

allowed-tools: Read, Grep, Glob

PreToolUse hooks会验证每一次工具调用，无论模型受到何种提示：

# Block credential file access regardless of prompt
if echo "$FILE_PATH" | grep -qE "\.(env|pem|key|credentials)$"; then
    echo "BLOCKED: Sensitive file access" >&2
    exit 2
fi

Subagent 隔离可限制影响范围。即使提示词遭到入侵，设置了 permissionMode: plan 的 subagent 也无法进行更改。

平台基线于2026年7月得到提升。 Claude Code v2.1.210 强化了 Agent tool，使其能够更好地抵御由 subagent 所读取内容携带的间接提示词注入——无论是受污染的文件、网页，还是 subagent 获取的工具结果，都更难操纵委派接口本身。⁶⁹v2.1.211 则强化了链条中的人工环节：权限预览现在会消除双向文本覆盖、零宽字符和形似 Unicode 字符的干扰，因此命令已无法被特意构造成在审批对话框中显示得人畜无害，实际却执行其他操作。⁶⁹对于需要人工在时间压力下批准渲染后预览的 harness，第二项修复尤为重要——显示界面本身也曾是注入攻击面。这两项变更都无法取代上述 hook 级防御，而是提升了其下方的平台基线。

Agent 日志和防护规则也是安全接口

2026年5月的两份安全公告进一步印证了一种规律：Agent 基础设施会产生新的敏感内容与可执行策略泄露或逃逸路径。GitHub 公告 GHSA-f3jg-756w-gm35 涉及 Gryph Agents 的有效载荷过滤问题：在默认日志记录行为下，敏感的工具有效载荷内容可能残留在本地 SQLite 日志中。⁴⁵OSV GHSA-wxxx-gvqv-xp7p 则涉及由管理员保护的代理端点中，LiteLLM 自定义代码防护规则发生沙箱逃逸的问题。⁴⁶

生产环境中的准则是：将 Agent 转录、工具有效载荷、SQLite 日志和防护规则执行视为敏感基础设施。持久化前进行脱敏，设置保留期限，并确保自定义防护代码在沙箱中运行且可供审查。提示词级的“不要记录密钥”规则远远不够；日志记录和防护规则路径需要确定性测试。

Hook 安全

将环境变量插入请求头的 HTTP hooks 必须显式提供 allowedEnvVars 列表，以防任意环境变量外泄：¹³

{
  "type": "http",
  "url": "https://api.example.com/notify",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

人类与 Agent 的职责划分

Agent 架构的安全性要求明确划分人类和 Agent 的职责：¹⁷

其模式是：需要组织背景、伦理判断或战略方向的决策由人类负责；需要在巨大可能性空间中进行计算搜索的决策由 Agent 负责。Hooks 负责强制执行这条边界。

递归执行 Hooks

Hooks 同样会在 subagent 操作时触发。¹³如果 Claude 通过 Agent tool 生成 subagent，您的 PreToolUse 和 PostToolUse hooks 会针对该 subagent 使用的每个工具执行。如果不递归执行 hooks，subagent 就可能绕过安全门槛。SubagentStop 事件允许您在 subagent 完成时运行清理或验证操作。

这并非可选配置。如果 Agent 生成的 subagent 不受您的安全 hooks 约束，那么它便可强制推送到 main、读取凭据文件或运行破坏性命令，而您的安全门槛只能眼睁睁看着主对话无动于衷。

将成本视为架构

成本是一项架构决策，而非事后考虑的运维问题。²它分为3个层级：

Token 层级。 压缩系统提示词。删除教程式代码示例（模型了解这些 APIs），合并各文件中的重复规则，并以约束取代解释。“拒绝匹配敏感路径的工具调用”与用15行文字解释为何不应读取凭据具有同样效果。

Agent 层级。 优先全新生成，而非延续冗长对话。自治运行中的每个 story 都交给一个上下文干净的新 Agent。由于每个 Agent 都从头开始，上下文不会无限膨胀。使用任务简报而非 memory：与在积累了30个步骤的上下文中摸索相比，模型更擅长执行清晰的任务简报。

架构层级。 对于无状态操作，优先采用 CLI，而非 MCP。使用一次 claude --print 调用完成单次评估，成本更低，也不会产生连接开销。只有当工具需要持久状态或流式传输时，MCP 才更为合适。

决策框架

何时使用各类机制：

Skills vs Hooks vs Subagents

常见问题

多少 hooks 才算太多？

约束来自性能，而不是数量。每个 hook 都会同步运行，因此总 hook 执行时间会叠加到每个匹配的工具调用上。只要每个 hook 在 200ms 内完成，用户级和项目级设置中合计 95 个 hooks 也能运行且没有明显延迟。需要关注的阈值是：如果某个 PostToolUse hook 给每次文件编辑增加超过 500ms，会话就会显得迟缓。部署前请用 time 分析 hooks 的性能。¹⁴

hooks 能阻止 Claude Code 运行命令吗？

可以。PreToolUse hooks 通过以代码 2 退出，阻止任何工具操作。Claude Code 会取消待执行的操作，并将 hook 的 stderr 输出显示给模型。Claude 会看到拒绝原因，并建议更安全的替代方案。退出码 1 是非阻塞警告，操作仍会继续执行。³

hook 配置文件应该放在哪里？

hook 配置放在 .claude/settings.json 中用于项目级 hooks（提交到仓库，与团队共享），或放在 ~/.claude/settings.json 中用于用户级 hooks（个人配置，应用于每个项目）。两者同时存在时，项目级 hooks 优先。脚本文件建议使用绝对路径，以避免工作目录问题。¹⁴

每个决策都需要 deliberation 吗？

不需要。置信度模块会从 4 个维度为决策评分（歧义性、复杂度、风险、上下文依赖）。只有总体置信度低于 0.70 的决策才会触发 deliberation，约占全部决策的 10%。文档修复、变量重命名和常规编辑会完全跳过 deliberation。安全架构、数据库 schema 变更和不可逆部署则会稳定触发。⁷

如何测试一个为产生分歧而设计的系统？

同时测试成功路径和失败路径。成功：agents 能进行有成效的分歧讨论并达成共识。失败：agents 过快趋同、始终无法达成共识，或超出 spawn 预算。端到端测试使用确定性的 agent 响应模拟每种场景，验证两个 validation gates 都能捕获所有已记录的失败模式。一个生产级 deliberation 系统在 3 层中运行 141 个测试：48 个 bash 集成测试、81 个 Python 单元测试，以及 12 个端到端流水线模拟。⁷

deliberation 对延迟有什么影响？

3-agent deliberation 会增加 30-60 秒的挂钟时间（agents 通过 Agent tool 顺序运行）。10-agent deliberation 会增加 2-4 分钟。consensus 和 pride check hooks 均可在 200ms 内运行。主要瓶颈是每个 agent 的 LLM 推理时间，而不是编排开销。⁷

CLAUDE.md 文件应该多长？

每个小节控制在 50 行以内，整个文件控制在 150 行以内。长文件会被上下文窗口截断，因此应将最关键的指令前置：先写命令和闭环定义，再写风格偏好。²¹

这套方法能用于 Claude Code 之外的工具吗？

这些架构原则（hooks 作为确定性关卡、skills 作为领域专业知识、subagents 作为隔离上下文、文件系统作为 memory）在概念上适用于任何 agentic system。具体实现使用的是 Claude Code 的生命周期事件、matcher patterns 和 Agent tool。AGENTS.md 将同样的模式带到 Codex、Cursor、Copilot、Amp 和 Windsurf。²¹ 即使实现细节依赖具体工具，harness 模式本身并不绑定工具。

快速参考卡片

Hook 配置

{
  "hooks": {
    "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "script.sh"}]}],
    "PostToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "format.sh"}]}],
    "Stop": [{"matcher": "", "hooks": [{"type": "agent", "prompt": "Verify tests pass. $ARGUMENTS"}]}],
    "SessionStart": [{"matcher": "", "hooks": [{"type": "command", "command": "setup.sh"}]}]
  }
}

Skill Frontmatter

---
name: my-skill
description: What it does and when to use it. Include trigger phrases.
allowed-tools: Read, Grep, Glob
---

Subagent 定义

---
name: my-agent
description: When to invoke. Include PROACTIVELY for auto-delegation.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

Instructions for the subagent.

退出码

关键命令

文件位置

更新日志

参考资料