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

TL;DR： Claude Code不是一个能访问文件的聊天框。它是一个可编程运行时，拥有31个已记录的生命周期事件；每个事件都可通过模型无法跳过的 shell 脚本挂接。将 hooks 叠加为 dispatcher，dispatcher 调度 skills，skills 组成 agents，agents 编排为 workflows，您就能得到一个自主开发 harness：它会强制执行约束、委派工作、跨会话持久化记忆，并协调多 agent 审议。Claude Code的动态 workflows（v2.1.154+）使确定性的多 agent 编排成为第一方原语——可通过/workflows运行数十到数百个后台 agent——该平台现在默认在后台运行 subagents（20个并发，3层嵌套深度），支持您的会话以对等方式相互传讯（v2.1.224），并可在自托管 runner 上执行云端会话。正确性仍由 hooks 和 evidence gates 掌控。⁵²⁵³⁸⁷本指南覆盖该技术栈的每一层：从单个 hook 到10-agent 共识系统。无需任何框架。全部使用 bash 和JSON。

Andrej Karpathy 为围绕LLM agent 逐渐形成的体系创造了一个术语：claws。它指让 agent 能够触及其上下文窗口之外世界的 hooks、脚本和编排。¹大多数开发者将 AI 编程 agent 视为交互式助手：输入提示，观察它编辑文件，然后继续下一项工作。这种思维框架会将生产力上限锁定在您个人能够监督的范围内。

基础设施的心智模型则不同：AI 编程 agent 是一个以LLM为内核的可编程运行时。模型执行的每项操作都会经过您控制的 hooks。您定义的是策略，而不是提示。模型在您的基础设施中运行，就像 Web 服务器在 nginx 规则中运行一样。您不会坐在 nginx 前手动输入请求；您会配置、部署并监控它。

这种区别至关重要，因为基础设施会产生复利效应。一个能阻止 bash 命令中出现凭据的 hook，会保护每个会话、每个 agent 和每次自主运行。一个编码了您评估准则的 skill，无论由您调用还是由 agent 调用，都会保持一致应用。一个审查代码安全性的 agent，无论您是否在旁监督，都会执行同样的检查。²

核心要点

• Hooks 保证执行；提示不能。 对于 lint、格式化、安全检查，以及任何无论模型行为如何都必须每次运行的事项，请使用 hooks。退出码2会阻止操作；退出码1仅发出警告。³
• Skills 编码可自动激活的领域专业知识。 description字段决定一切。Claude使用LLM推理（而非关键词匹配）来决定何时应用 skill。⁴
• Subagents 可防止上下文膨胀。 用于探索和分析的隔离上下文窗口可让主会话保持精简。并行运行相互独立的 subagents；当 worker 需要持续协作时，使用 agent teams。⁵
• Memory 存在文件系统中。 文件可跨上下文窗口持久保存。CLAUDE.md、MEMORY.md、规则目录和交接文档共同构成结构化外部记忆系统。⁶
• 多 agent 审议能发现盲点。 单个 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为每次匹配的工具调用提供确定性关卡。Memory文件在会话之间持久化状态。自定义代理提供专门的subagent配置。

编排层：多代理模式协调独立代理开展研究、审查和研讨。生成预算可防止递归失控。一致性验证确保质量。

关键洞察在于：大多数用户完全在核心层工作，眼看上下文不断膨胀、成本持续攀升。高级用户会配置指令层和扩展层，然后仅将核心层用于编排和最终决策。²

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

在2026年初的大部分时间里，“自行构建harness”是唯一真正的选择。2026年4月，这一情况发生了变化。Anthropic于4月8日以公开测试版推出Claude Managed Agents：harness循环+工具执行+沙盒容器+状态持久化，作为REST API提供；按标准token计费，另加$0.08/会话小时。OpenAI的Agents SDK更新（4月16日）正式确立了同样的划分——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、沙盒指令和能力；用于描述全新工作区契约的Manifest（文件、目录、本地文件、Git仓库、环境、用户、挂载）；以及SandboxRunConfig，用于按运行配置沙盒客户端、注入实时会话、覆盖manifest、快照和实体化并发限制。内置能力涵盖shell访问、文件系统编辑、图像检查、skills、沙盒memory和压缩。沙盒memory会跨运行持久化提取出的经验，并渐进式披露；工作区支持本地文件、Git仓库条目和远程挂载（S3、R2、GCS、Azure Blob、S3 Files）；快照可跨提供商移植。后端包括：UnixLocalSandboxClient、DockerSandboxClient，以及通过可选extras提供的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月12日，该软件包在PyPI上的版本为v0.2.137，TypeScript SDK为v0.3.229（均已对照实时注册表验证）；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公开测试版。⁷³ 两家供应商如今都在多代理层提供与下表针对单代理所描述的同类取舍：供应商运行委派循环，而您放弃hook接口。

架构分岔如今已成为现实：

何时选择哪一种：对于已经具备基础设施能力、希望自行控制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 始终可用的知识。Slash commands 用于由您显式触发的操作。如果在两者之间犹豫，不妨问自己：“应当让 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 description 会被注入系统提示中的 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、质量分析），以及用户自然会输入的触发短语（审查、审计、检查）。

请注意，自动激活是可调节的机制，而非铁律：截至 v2.1.215，Claude 不再自行调用内置的 /verify 和 /code-review skills——它们仅在显式调用时运行。这是对依赖 description 的自动激活的一次刻意收缩，因为这些高成本审查 skills 的未提示运行成本高于其收益。⁷⁴

上下文预算

所有 skill descriptions 共用一个上下文预算：动态按上下文窗口的 1% 缩放，备用上限为 8,000 个字符。⁴ 如果 skills 很多，请保持每个 description 简洁，并将关键使用场景放在开头。您可以通过 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量覆盖该预算，¹¹ 但更好的解决办法是编写更短、更精准的 descriptions。会话期间运行 /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，仅在该 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 则负责执行。二者结合，构成一层策略层。

常见 Skill 错误

Description 过于宽泛。 一个 git-rebase-helper skill 若会在任何与 git 相关的提示上激活（rebase、merge、cherry-pick，甚至 git status），就会污染 80% 的会话。解决办法是收紧 description，或添加 disable-model-invocation: true，要求显式调用 /skill-name。⁴

过多 skills 争夺预算。 Skills 越多，争夺 1% 上下文预算的 descriptions 就越多。如果发现 skills 没有激活，请在 /context 中检查被排除的项目。与其使用大量含糊的 skills，不如优先保留更少、描述更清晰的 skills。

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

SDK Skill Surface（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 将该目录扩展到 plugins：放置在 .claude/skills/ 中的 plugin 现可自动加载，无需 marketplace 注册；claude plugin init <name> 会在其中创建新的脚手架，manifest 与 SKILL.md 已预先连接。⁵⁸ 这弥合了过去位于不同位置的两种项目工具形态之间的差距——一种是直接提交到仓库的裸 skill，另一种是将 skill、hooks 和 MCP server 打包在一起、但此前需要 marketplace 安装的 plugin。对 harness 设计而言，实际效果是：项目作用域工具不再需要绕道 registry 才能交付——编写、提交后，团队成员通过 git pull 即可获得相同的 surface。Plugins 仍负责可打包安装的使用场景（将 hooks、skills、MCP servers 和 agents 打包到一个 ZIP 中）；变化在于，项目不再需要仅为了从自身目录加载一个 plugin 而搭建 marketplace。这种融合如今也具备跨厂商基础：Agent Plugins 1.0.0（发布于 2026年8月6日）将相同的包形态标准化——即 plugin.json manifest、包含 SKILL.md 文件夹的 skills/ 目录，以及可选的 mcp.json——称为“AI agents 的可移植包格式”；VS Code、Cursor、GitHub Copilot、ChatGPT & Codex 和 Kiro 在发布时即已采用。它明确是围绕 Agent Skills 和 MCP 的打包层，而非替代品；需要注意的是，Agent Skills spec 的作者 Anthropic 尚未加入该联盟——因此，应将 Claude 向外的可移植性视为格式层面的兼容，而非官方的双向契约。⁸⁹

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

Skills 是能力，而能力就是攻击面。Claude Code v2.1.169 增加了 disableBundledSkills 设置（以及对应的 CLAUDE_CODE_DISABLE_BUNDLED_SKILLS 环境变量），可将内置 skills、workflows 和内建 slash commands 完全从模型中隐藏。⁶⁰ 对于强化或受监管的 harness，这是一项有意的攻击面缩减：已审计并批准特定项目和个人 skills 的运营方，可以屏蔽 Anthropic 随附的所有内容，使模型只会基于运营方审核过的 surface 进行推理。应当像对待工具 allowlist 一样对待它——默认提供广泛能力，而关闭默认值是一项治理决策，并非便利开关。

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

Claude Code v2.1.178 使项目工具具备了位置感知能力。嵌套 .claude/skills 目录中的 skills 现在会在您处理该目录下的文件时加载，而不再只从仓库根目录加载；若名称冲突，嵌套 skill 会显示为 <dir>:<name>，因此两者都可访问。⁶³ 同一版本还让其余项目 surface 按距离工作目录最近的原则解析：当 agent、workflow 或 output-style 名称在嵌套 .claude/ 目录中发生冲突时，最接近工作目录的版本优先；而项目作用域 workflow 保存时，会写入最近的现有 .claude/workflows/，而非始终写入根目录。⁶³ 对于 monorepo 或 repo-of-repos，这意味着从一个扁平的全局 surface 转变为按包划分、在上下文中激活的工具体系——services/api/.claude/skills/ 可以承载仅在该目录树中工作时出现的 API 特定 skills，而不会与同名的 services/web/ skill 冲突。

Hook 架构

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

可用事件

截至本指南更新时，Claude Code 在八个类别中公开了 31 个有文档说明的生命周期事件。事件列表会随版本发布而增长，因此应将参考文档视为权威来源；在接入生产 Hooks 前，请查看速查表获取当前完整表格：¹³

DirectoryAdded（v2.1.219）填补了会话中途工作区的空白。自 v2.1.152 引入 MessageDisplay 以来，事件列表一直保持稳定；DirectoryAdded 是此后首个新增的生命周期事件，并会在 /add-dir——或 SDK 的 register_repo_root 控制请求——在会话中途注册新的工作目录后触发。⁸⁴它填补的缺口真实存在：此前 harness 可以在 SessionStart 时彻底验证工作区，随后却眼看第二个仓库被接入，而完全没有 hook 触发。凡是在启动时对工作区作出的断言——信任检查、密钥扫描、从目录树推导的路径范围规则、按仓库加载的策略——都需要在此重新运行，因为会话的目录集合不再在启动时固定。该事件是信息性的而非可阻止的，因此应将其视为重新推导状态并记录来源的触发器，而非关卡；如果某个目录绝不能被添加，应在设置中拒绝它，而不是试图通过 hook 否决。SDK 端也在同一版本发布（TypeScript v0.3.219 将 DirectoryAdded 添加到控制协议生命周期事件中），因此由 SDK 托管的 harness 与 CLI 托管的 harness 一样能够收到该事件。⁸⁵

退出代码语义

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

Hook 配置

Hooks 位于设置文件中。项目级（.claude/settings.json）用于共享 hooks，用户级（~/.claude/settings.json）用于个人 hooks：

{
  "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 工具名称（如 mcp__server__tool），或者用 * 匹配所有工具。简单名称和以 | 分隔的列表为精确匹配；包含其他字符的值则是 JavaScript 正则表达式。部分事件不支持 matcher，配置后始终触发。¹³自 Claude Code v2.1.195 起，包含带连字符标识符（code-reviewer、mcp__brave-search）的 matcher 会进行精确匹配，而不再意外进行子字符串匹配——针对某个 agent 或服务器的 hook 不会再对名称中仅包含该字符串的所有对象触发；若要覆盖来自带连字符 MCP 服务器的所有工具，请写明模式 mcp__brave-search__.*。⁶⁶v2.1.214 将同样的原则应用于路径模式：使用单段 dir/** 模式的 hook if: 条件现在只匹配 <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 包装器——旧版顶层 decision/reason 格式已不再推荐用于 PreToolUse：

{
  "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 会运行 linter 或测试套件，并在质量检查失败时阻止提交：

#!/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 支持五种 hook 类型：¹³ 命令 hooks（type: "command"）运行 shell 脚本。速度快、结果确定，且不消耗 token。

MCP 工具 hooks（type: "mcp_tool"）调用已连接的 MCP 服务器上的工具。当验证逻辑已位于 MCP 边界之后，且无需单独的 shell 脚本时，请使用此类 hooks。

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

Agent hooks（type: "agent"）会启动具有工具访问权限（Read、Grep、Glob）的 subagent，用于多轮验证。它们仍处于实验阶段；生产环境的门禁应优先使用命令 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
}

将 async 用于通知、遥测和备份。绝不要将 async 用于格式化、验证，或任何必须在下一项操作前完成的工作。

使用 Dispatcher 替代独立 Hooks

在同一事件上运行 7 个 hooks，并让每个 hook 独立读取 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 秒以内，最好低于 500ms。

SDK 端 Hook 事件流

基于 claude-agent-sdk-python（v0.1.74+，2026年5月6日）的自托管 harness，可以直接从消息流订阅 hook 事件，而无需经过 shell 脚本回调。³⁶ 在 ClaudeAgentOptions 上设置 include_hook_events=True 后，HookEventMessage 对象（PreToolUse、PostToolUse、Stop 等）会与 assistant 消息和工具结果从同一迭代器中产生。这与 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 帧会按消息报告 queued/started/completed/cancelled/discarded 状态——这是第一方首次无需通过转录推断，即可回答“我发送的消息发生了什么”。还引入了较小的接口：用于 subagent 完成载荷的 AgentToolCompletedOutput 类型，以及 canUseTool 回调现在可以在没有 updatedInput 字段的情况下返回 {behavior: 'allow'}。

该系列中的一项改动是安全底线，而非功能：v0.3.208 修复了在 hook 等待期间调用方 abort 被转换为 hook 成功的问题——这意味着受 PreToolUse hook 门禁控制的工具，可能在调用方已 abort 后仍然执行。⁷⁰ 如果您的 harness 使用 SDK 端 hooks 作为权限门禁，并依赖 abort 取消进行中的工作，应将 v0.3.208 视为最低版本；在此版本以下，“已 abort”并不可靠地意味着“已阻止”。Python v0.2.127（2026年7月24日）是一个月内第二个同类绕过：query() 在后台 subagents 仍运行时，于首个 result 帧关闭 stdin，导致其 SDK-MCP 工具调用因 "Stream closed" 失败，并且完全绕过了 PreToolUse hooks。⁸⁵ 应明确这一模式并保持警惕：SDK 端 hook 强制执行会在生命周期边缘——abort、拆除、流关闭——失效开放，此时传输会在收集 hook 裁决前终止；而且它会静默失效，因为被绕过的 hook 与批准操作的 hook 看起来完全相同。固定这两个 SDK 最低版本，并保留您能够证明有效的 shell-hook 层作为强制执行手段。

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

Claude Code v2.1.132 和 v2.1.133 中的两项新增功能，让 hooks 和 subprocesses 能够更好地获取其执行上下文信号：³⁸³⁹

• hook 输入中的 effort.level。 Hooks 现在会在携带 tool_input 和 session_id 的同一输入中接收 effort.level JSON 字段。该值也会导出为 $CLAUDE_EFFORT 环境变量，因此 Bash 命令无需解析 JSON 即可读取。可据此按 effort 层级调整 hook 成本：在 low 时跳过高成本验证，在 xhigh 或 max 时运行完整安全门禁。
• Bash subprocesses 中的 CLAUDE_CODE_SESSION_ID 环境变量。 Bash 工具 subprocesses 现在能够看到 hooks 所见的同一 session_id 值，并以 CLAUDE_CODE_SESSION_ID 形式提供。这弥合了按会话记录状态的工具此前无法将 subprocess 事件与 hook 事件关联的来源缺口。

这两个信号无需修改代码即可使用；忽略新字段的现有 hooks 会继续正常运行。

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

Claude Code v2.1.136 为自动模式新增了硬拒绝层级，并修复了一组影响长时间运行 harness 的 plugin 和 MCP 问题：⁴⁰ - settings.autoMode.hard_deny。 Auto mode 分类器规则会无条件阻止操作，不受用户意图或允许例外影响。它位于现有 allow/deny 匹配器之上，是不可协商的治理控制杆。即使操作员已在个人设置中批准更广泛的类别，也应将绝不可覆盖的规则（如向 main 强制推送、含密钥的文件、访问生产数据库）放在这里。 - autoMode.classifyAllShell（v2.1.193）。 默认情况下，auto-mode 分类器只会审查符合任意代码执行模式的 shell 命令。此设置会将每一条Bash/PowerShell 命令都送入分类器——这是受治理 harness 的最大覆盖策略；同一版本还会在转录记录、toast 和 /permissions 中显示拒绝原因，将静默拦截转化为可审计的决策。Codex 在 v0.142.2 中收紧了对应机制：其安全分类器无法检查的可执行 AST 区域所在的 PowerShell 命令，现在需要审批，而非静默放行。⁶⁶ - Hook ask 为分类器设定下限（v2.1.211）。 hook 与 auto mode 的优先级问题现已明确：返回 ask 权限决策的 PreToolUse hook，会将最终结果限制为提示——auto mode 无法将其重新提升为允许无沙箱的 Bash 命令。⁶⁹ 对受治理 harness 而言，这是缺失的保证层：hook 的 ask 是确定性的人在回路停止点，即使在完全自动化的权限策略下也依然有效。对于希望由人工决策而非直接拒绝的操作，请使用 ask（而不只是 exit-2 拦截）。 - 分类器模型按会话固定（v2.1.210）。 auto-mode 分类器默认使用 Sonnet 5，并在整个会话期间固定，因此会话中途切换模型不再改变执行权限分类的模型。⁶⁹ 分类一致性是一项治理属性；此举消除了一个隐蔽的漂移来源。 - /clear 后 MCP 服务器不再消失。 .mcp.json、plugins 和 claude.ai connectors 中配置的服务器，过去会在 VS Code extension、JetBrains plugin 和 Agent SDK 中执行 /clear 后，静默地从活跃集合中消失。修复已在 v2.1.136 中推出。如果您遇到过“MCP server X 在会话中途消失”，原因就在于此。 - 并发刷新时 MCP OAuth refresh-token 丢失。 使用多个远程 MCP server 的用户不应再需要每天重新认证。并发刷新写入过去会相互覆盖。 - Plan mode 现在会正确阻止文件写入。 匹配的 Edit(...) allow 规则此前会绕过 plan-mode 写入保护。现在，无论是否存在 allow 规则，都会强制执行 Plan mode。 - Plugin Stop 和 UserPromptSubmit hooks 不再在会话中途失败。 缓存清理会删除运行中会话仍在使用的 plugin-version 文件，导致这两个 hook event 特别容易失效。修复后会固定仍在使用的版本。 - plugin.json 中的 skills 条目。 设置 skills 曾导致 plugin 默认的 skills/ 目录被隐藏。现在该条目可以正确组合；将其指向文件路径时，会抛出明确错误，而非静默失败。 - CLAUDE_ENV_FILE SessionStart hook 环境变量过期。 SessionStart hooks 通过 CLAUDE_ENV_FILE 导出的变量，会在 /resume 或 /clear 后过期。已在 v2.1.136 中修复。会话现在会在这些事件发生时重新加载 env file。

对于治理型 harness，真正值得关注的条目是 autoMode.hard_deny（新的控制杆）和 MCP 消失修复（会破坏长会话的静默故障）。其余均属于体验与可靠性清理。

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

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

当 PostToolUse hook 应将其拒绝原因反馈给 Claude，并继续当前轮次而非结束流程时，请使用 continueOnBlock。应将其视为操作员体验功能，而非安全绕过机制。拦截门仍应阻止不安全的结果。

同一版本会将 CLAUDE_PROJECT_DIR 传递给 MCP stdio servers，并允许 plugin configs 在命令中引用 ${CLAUDE_PROJECT_DIR}。⁴² MCP tools 应从该值解析项目相对路径，而不是依赖恰好启动服务器的进程工作目录。2026年7月初发布的版本（v2.1.203–v2.1.206）将同一原则扩展到协议层：MCP roots/list 现在包含会话的附加工作目录，并在其变更时发送 roots/list_changed 通知——因此，遵循 MCP roots 的 server 会跟踪真实的多目录 workspace 结构，而非假定只有单个项目目录。⁶⁸

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

Claude Code v2.1.141 增加了 hook-output terminalSequence 字段，可在没有控制终端时发送桌面通知、更新窗口标题和触发响铃。⁵⁰ 应将其视为操作员信号，而非强制执行机制。安全和质量门仍应通过常规拦截契约传达失败：结构化 hook 输出，以及阻止不安全操作的退出行为。同一版本还增加了 claude agents --cwd <path>，用于将 Agent View 限定在单个目录；增加了 CLAUDE_CODE_PLUGIN_PREFER_HTTPS，用于在缺少 GitHub SSH keys 的环境中安装 plugins；还增加了 ANTHROPIC_WORKSPACE_ID，用于覆盖多个 workspace 的 workload-identity federation rules。⁵⁰ 对团队 harness 而言，这些是架构细节：更窄的操作视图、更少的 plugin-install 假设，以及明确的企业 token 作用域。

Claude Code v2.1.142 对后台会话编排的重要性高于对 hook 语义的重要性。⁵¹ claude agents 现在可通过明确的目录、设置、MCP、plugin、权限、模型和 effort flags 来分派后台会话，而非依赖 wrapper 状态。该版本中，Fast mode 默认使用 Opus 4.7；对于经测量确实依赖 Opus 4.6 行为的 harness，可使用 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、daemon sleep/wake 与升级后清理，以及 plugin cache cleanup 的修复，填补了那些原本会被误认为是编排 bug 的可靠性缺口。

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

6月初的四项变更对 harness 和 multi-agent 设计至关重要。⁵⁹

Stop/SubagentStop hooks 获得了引导通道。 自 Claude Code v2.1.163 起，Stop 或 SubagentStop hook 可以返回 hookSpecificOutput.additionalContext，向 Claude 提供反馈并保持当前轮次继续，而不会将响应标记为 hook error。在此之前，Stop hook 唯一真正的控制手段是 exit-2 拦截；这会显示为错误，并计入连续拦截上限。对于 quality-gate harness，这是更简洁的原语：检测到“您声称已完成，但测试仍然失败”的 Stop hook，现在可以注入“以下内容仍在失败，请继续”，而不必硬性拦截。真正需要停止时使用 block；对于“尚未完成，原因如下”的情况则使用 additionalContext。

跨会话消息不再携带借用的权限。 v2.1.166 加固了多会话场景：通过另一 Claude session 的 SendMessage 转发的消息，不再携带原始用户的权限，因此接收会话会拒绝转发的权限请求，auto mode 也会将其拦截。如果您的编排机制让 agents 相互发送消息，应将入站消息视为不可信数据，而非经过认证的指令。这与安全章节对 tool output 采用的原则相同，只是将其扩展到了 inter-agent messaging。截至 v2.1.199，Claude Code 还会在两个 agents 使用相同名称而导致 SendMessage 路由错误时进行检测和警告——这是对该权限边界的可靠性补充，因为消息到达错误的同名 agent 本身就是一类编排 bug。 会话现已成为一等对等实体（v2.1.224+）。 跨会话消息传递已从中继加固升级为完整功能面：SendMessage/ListAgents允许您的会话在多台机器（macOS/Linux）之间相互发现和通信；接收端则通过crossSessionInbound控制接受、暂缓或拒绝。self-hosted runners还允许Claude Code网页和移动端会话在您掌控的硬件上执行。对于harness架构而言，这使“一个会话”成为可寻址节点：发现、入站策略以及前述权限边界如今都是平台原语，而非邮箱脚本（Claude Code指南记录了完整契约）。⁸⁷ 还有一项需要同步调整的立场：auto mode将于2026年8月14日成为Pro、Max和Team套餐的默认权限模式。如果harness将Manual模式提示视为人工介入的最后防线，就应明确固定defaultMode，而不要想当然。⁸⁷

模型韧性成为一项一等设置。 fallbackModel设置现可串联最多3个备用模型；当主模型过载或不可用时，将按顺序尝试。若出现意外的不可重试API错误，该轮还会使用备用模型自动重试一次。对于长期运行的自主harness，这会将主模型的短暂故障转化为平稳降级，而非直接丢弃一次运行。claude agents --json还新增了waitingFor字段（v2.1.162），用于展示受阻后台会话正在等待什么，例如权限提示——这为任何轮询agent集群的协调器带来了可观测性提升。

适用于洁净室治理与故障排查的安全模式。 Claude Codev2.1.169新增--safe-mode标志（以及对应的CLAUDE_CODE_SAFE_MODE环境变量），可在禁用全部自定义项的情况下启动会话：CLAUDE.md、plugins、skills、hooks和MCP服务器。⁶⁰ 这是harness的反面——一个刻意构建的洁净室。可借此回答每位运维人员终将面对的问题：“此行为来自模型，还是来自我的某项配置？”当hook误触发、skill在不应激活时激活，或某个MCP服务器污染上下文时，--safe-mode会提供一个已知为空的基线，供您进行差异比对。它也是一项治理原语：让您在不具备harness通常授予的任何持久权限的情况下运行裸模型；当您需要复现结果，且不希望任何由运维人员定义的脚手架影响它时，这一点尤为重要。

关于模型层级的说明。 截至Claude Codev2.1.197（2026年6月30日），Claude Sonnet 5是新会话的已发布默认模型——原生1M上下文，促销价为每MTok $2/$10，优惠持续至8月31日——取代了Opus 4.8，成为开箱即用的选择。本指南将Opus 5（claude-opus-5）视为推荐的agentic默认模型：除非您有意作出其他选择，否则应使用它运行自主harness，因为长周期、高风险的agent循环正是Opus的推理深度最能体现其成本价值的场景。Opus 5于2026年7月24日在Claude Codev2.1.219中发布，成为新的默认Opus——1M上下文、每MTok $5/$25（与其取代的Opus 4.8价格相同）；快速模式为$10/$50，速度约为默认模式的2.5倍。Anthropic报告称，它在Frontier-Bench v0.1上的表现超过Opus 4.8两倍，并以一半成本达到Fable 5的CursorBench 3.2分数0.5%以内。⁸⁴⁹¹ 价格不变、能力更强，且Anthropic将其描述为“在验证自身工作和谨慎迭代方面强得多”的模型——这类升级对于harness工作无需再从成本角度论证；从4.8迁移只需更改id。对于成本敏感或高吞吐量的工作，如果Sonnet 5的速度与智能比更具优势，则可降级使用Sonnet 5。Opus之上还有Claude Fable 5（claude-fable-5），于2026年6月9日发布——这是一个新层级，被描述为Anthropic最强大的模型，是一个可安全用于通用场景的“Mythos-class”系统，可通过Claude Codev2.1.170中的/model claude-fable-5选择。⁶⁰ 应当审慎使用这一更高层级，仅用于原始推理深度足以证明其成本合理的决策，而非将其作为整个agent集群的统一设置。Opus 5切换还带来两项日常维护影响：Opus 4.7退出快速模式（/fast现适用于Opus 5和Opus 4.8），而自v2.1.176起被定义为“最佳可用Opus模型”的auto-mode分类器Fable-5备用方案，如今会解析为Opus 5。⁸⁴

Codex发布了multi-agent v2。 Codex CLIv0.137.0让每个线程保留运行时选择，为已生成agent提供更清晰的后续操作和元数据默认值（hide_spawn_agent_metadata现默认设为true），并将原始父事件传播给子监听器。其subagent模型仍保持明确：内置default/worker/explorer agent类型、由TOML定义的自定义agent，以及并发控制（agents.max_threads默认值为6，agents.max_depth默认值为1）。同一版本还新增v1 skills扩展，支持每轮skills目录解析，以及新的线程启动/轮次错误生命周期贡献者事件；这缩小了与Claude Code的hook/skill功能面之间的差距，同时仍将kernel-sandbox姿态作为默认边界。Codex v0.138.0–v0.139.0随后为生产环境加固了multi-agent v2：agent间消息负载现已加密；v2 agent配置目录和agent驻留LRU负责管理哪些agent保持驻留；并发按活跃执行而非已生成线程计数，因此空闲agent不再占用一个槽位。⁶¹ 生命周期API也趋于成熟：close_agent被重命名为interrupt_agent（v0.139.0），以反映它会中断正在运行的agent，而不只是关闭一个句柄；subagent引发的MCP启动警告如今也会保留在所属线程范围内，不再重复显示到父级转录中。⁶¹ 对于构建Codex侧编排的人而言，这些正是演示与agent集群之间的差别：加密消息传输、受限驻留、按执行计数的并发，以及不会跨越线程边界泄漏的警告。Codex v0.140.0随后开放了一条跨工具衔接：/import可选择性地将设置、项目配置和近期聊天记录从Claude Code导入Codex；会话也变得可以永久删除（codex delete//delete，包含确认保护措施）。⁶⁴ /import首次正式承认运维人员会在不同harness之间迁移——您为其中一个构建的配置不再被困在其中。

记忆与上下文

每次 AI 对话都在有限的上下文窗口内运行。随着对话不断增长，系统会压缩较早的轮次，为新内容腾出空间。这种压缩会造成信息损失。在第 3 轮记录的架构决策，到了第 15 轮可能已无法保留。⁹

多轮崩塌的三种机制

MSR/Salesforce 研究识别出 3 种彼此独立的机制，每种都需要不同的干预措施：⁹

策略 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 时，bash 中的 ((VAR++)) 会因 set -e 而失败，便将其记录下来。3 次会话之后，当您在 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 命令会总结对话，并释放上下文空间，同时保留关键决策、文件内容和任务状态。¹⁵

何时压缩： - 完成一个明确的子任务后（功能已实现、bug 已修复） - 开始代码库中的新区域之前 - 当 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）则保护提示缓存。它可以在不中断当前轮次累计缓存的前提下，将会话在中途切换到新的工作目录。⁶⁰ 在此之前，更改目录意味着需要新建会话，并且缓存处于冷启动状态。对于从一个仓库转到同级仓库的长时间运行会话——这在 monorepo 和多服务工作中很常见——/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: [fresh context] -> writes code, creates files, updates state
Iteration 2: [fresh context] -> reads state from disk, continues
Iteration 3: [fresh context] -> reads updated state, continues
...
Iteration N: [fresh context] -> reads final state, verifies criteria

与单个长会话相比：

Minute 0:   [fresh context]        -> productive
Minute 30:  [context filling]      -> somewhat productive
Minute 60:  [mostly consumed]      -> degraded
Minute 90:  [compaction pending]   -> significantly degraded
Minute 120: [compressed, lossy]    -> errors accumulate

每次迭代使用全新上下文的方法，以 15-20% 的开销来换取 orient 步骤（读取状态文件、扫描 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 能节省绝大多数成本。¹⁵

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

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

Subagent 模式

subagents 是专门的 Claude 实例，能够独立处理复杂任务。大多数实例启动时都使用干净的上下文（不会受到主对话的干扰）；但下文的 fork 类型例外，它会有意继承全部内容。subagents 使用指定工具执行任务，并以摘要形式返回结果。探索结果不会让主对话变得臃肿，只有结论会返回主对话。⁵

内置 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 起，“always allow”规则会在仓库根目录中跨 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 拒绝遍历符号链接和硬链接。这4项修复体现了同一原则：隔离边界必须能抵御蓄意重定向——如 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，后者又继续委派；每一层都会损失上下文并消耗 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 现在默认最多可生成深度为3的嵌套 subagents（此前为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 模式现在会在生成启动前进行审查。 Claude Code v2.1.178 补上了相应的治理缺口：在 auto 模式下，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项：编排宽度，即单个计划工作流允许包含的 agents 数量。其默认指导原则是“尽量少于15个 agents”，并可通过任意 settings 文件中的 workflowSizeGuideline 设置（详见下文 Workflow Tool 一节）。生成预算模式如今在原本设计针对的每个维度上都有平台兜底，此外还多了一个最初未覆盖的维度。

不过，上述量级说明仍然适用，只是各项程度不同。200次生成和20个并发 agents 都是保险丝——比上述配置中的12-agent 审议预算高出一个数量级，旨在捕获失控循环，而不是塑造架构。宽度指导原则则是首个与实际预算处于同一量级的原生数值：每个工作流15个 agents，与本指南的12个相差无几。采用平台默认值几乎不会付出代价；若不同意，理应有充分理由。请把3个保险丝设置为您能够合理辩护的数值，并根据实际想要构建的编排形态设置宽度指导原则。

Agent Teams（研究预览）

Agent Teams 会协调多个独立工作的 Claude Code 实例。它们通过共享邮箱和任务列表通信，并能相互质疑对方的发现：⁵

启用方式：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

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

Agent View 与 Goal 循环（2026年5月）

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

推广 subagent 或团队模式时，应使用 Agent View 检查哪些会话已阻塞、哪些仍在运行，以及工作分配是否符合预期架构。但不要把它当作质量证明。它提供的是可观测性；工作是否可靠，仍应由测试、审查门禁和 evidence reports 决定。

同一版本还加入了 /goal。它用于设置完成条件，让 Claude 跨轮次持续工作，直至满足条件，并支持交互式、-p 和 Remote Control 使用方式。⁴² 应将 /goal 视为会话级完成循环，而不是确定性门禁的替代品。它有助于让 agent 始终聚焦目标；但在失败必须阻止继续执行的场景中，测试、引用检查、部署检查和安全 hooks 仍应由命令或脚本提供支持。

Workflow Tool（v2.1.147+）

Claude Code 的动态工作流已正式发布，并默认可用：从 v2.1.154 起，它们可在后台编排数十到数百个 agents，通过 /workflows 监控；v2.1.202 加入了“Dynamic workflow size”/config 控件；v2.1.219 又加入 workflowSizeGuideline settings 键，其默认指导级别为 medium——除非另有要求，否则尽量少于15个 agents。该功能最初在前一个版本 v2.1.147 中以默认关闭的 Workflow 工具亮相，需要通过 CLAUDE_CODE_WORKFLOWS=1 启用；如今这一 flag 阶段已成为历史，但它所体现的架构意义依然成立。⁵² 对于此前需要自定义调度脚本、邮箱状态和 subagent 协调约定的流程，它为 Claude Code 提供了官方编排原语。

不要因此删除外围的 harness。Workflow 可以组织执行，但无法取代安全模型。应继续将 PreToolUse 和 PostToolUse hooks 用作阻止层；保留生成预算或工作流步骤预算，防止宽度失控；确保文件系统状态可审计；并让最终 evidence reports 独立于模型的自我评估。具体而言：使用 Workflow 规划编排形态；使用 hooks、测试和审查门禁判断事实。

动态工作流现在对宽度提供了明确的官方建议（v2.1.219）。 动态工作流默认采用 medium 规模指导原则——“尽量少于15个 agents”——同时在 /config 的 Dynamic workflow size 中提供其他规模和无限制选项，运行中工作流的状态行也会显示当前指导原则。⁸⁴ 这一数值是建议，而非强制限制；它会引导规划器，但不会阻止宽度较大的计划。值得配置它的关键在于其交付机制：新的 workflowSizeGuideline settings 键可在任意 settings 文件中设置，包括托管 settings 和项目 settings；从 v0.3.219 起，它也已加入 TypeScript SDK settings 类型。因此，编排宽度可以由团队或组织统一规范，无须每位操作员各自摸索。⁸⁵ 建议在项目级设置，使其反映代码库中工作的实际分解方式。这里有2项操作提示：当 settings 文件控制该值时，/config 中的对应行会自动隐藏。这种行为是正确的，但如果不了解原因，可能会误以为该设置缺失；此外，由于这一指导原则只是引导规划器，而非阻止执行，因此它属于形态维度，而非安全维度。宽度失控仍应由生成上限负责。

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

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

Claude Code v2.1.212 重塑了2种编排原语。⁶⁹ /fork 现在会基于当前对话状态创建一个新的后台会话——分叉后的线路会独立运行，原始会话则继续工作——此前的会话内行为则更名为 /subtask。这一区别对编排设计至关重要：/subtask 是单个会话生命周期内范围受限的支线任务；/fork 则是创建继承完整上下文的并行后台会话的一种低成本方式，更接近 Ralph-loop spawn，而不是 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 将其扩展到第一层之外：深度为2或更深处生成的 subagents 现在也会出现在转发数据流中，并以生成它们的 Agent tool_use id 作为键。⁸⁴ 这个键才是应当据此构建系统的部分。嵌套默认重新启用后，扁平的 subagent 文本流会产生歧义；该 id 能告诉协调器哪个父级生成了哪个子级，从而直接通过数据流重建委派树，而无须依赖推断。如果数据流消费者是针对单层 subagents 编写的，现在它将看到此前根本不知道其存在的 agents 所产生的文本；请按生成时的 tool_use id 分组，不要假定每一条转发行都来自直接子级。

多智能体编排

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

跨工具编排（2026年4月）： Google 于4月7日开源了 Scion——一款多智能体虚拟机管理程序，可将 Claude Code、Gemini CLI 及其他“深度智能体”作为并发进程运行；每个进程都有隔离的容器、git worktree 和凭据。支持本地、hub 或 Kubernetes 运行。其明确理念是：“隔离优于约束”——智能体在基础设施层面强制执行的边界内拥有高度自主性，而非依靠提示词约束。²⁵ 这直接将 subagent 隔离的论证扩展到了不同工具供应商之间。如果您的工作流覆盖 Claude 和 OpenAI 模型，Scion 是首个针对跨工具 subagent 且具备按智能体划分的 worktree + 凭据隔离的真实参考实现。

辩论并非万能药： M3MAD-Bench 研究集群（2026年初）发现，多智能体辩论会遇到瓶颈，也可能被误导性共识所颠覆——当其他智能体自信地断言错误答案时，合理的论据反而会落败。²⁶ Tool-MAD 通过为每个智能体提供异构工具访问权限，并在裁判阶段采用忠实度/相关性评分来改进这一点。如果您正在构建辩论式编排，建议投入于：（a）为每个智能体提供工具异构性；以及（b）量化的裁判评分，而不是假设智能体越多答案就越好。

托管多智能体编排与 Outcomes（Public Beta）

如果您不想构建下文所述的审议基础设施，Multiagent Orchestration 已于2026年5月6日进入 Claude Managed Agents 的 Public Beta。³⁵ 据 Anthropic 所述：“当单个智能体难以高质量完成过多工作时，多智能体编排让主智能体将工作拆分，并把每个部分委派给拥有各自模型、提示词和工具的专家。”³⁵ 专家“在共享文件系统上并行工作，并为主智能体的整体上下文作出贡献。”³⁵

Tracing 开箱即用。据 Anthropic 所述：“您还可以在 Claude Console 中追踪每一步：哪个智能体做了什么、按什么顺序执行、以及为什么执行，从而全面了解任务如何被委派和完成。”³⁵

配套的 Public Beta 功能是 Outcomes。据 Anthropic 所述：“您编写一份描述成功标准的 rubric，智能体便会朝着该标准努力。独立的 grader 会在其自身的上下文窗口中根据您的标准评估输出，因此不会受到智能体推理过程的影响。”³⁵ 这正是本节后文记录的双门验证模式的托管服务版本：rubric 取代手写 gate，独立 grader 取代共识验证器。

当验证需要与您自己的 hook surface 集成（PreToolUse 阻断、退出代码语义、自定义 dispatcher），或 harness 必须在不依赖外部服务的情况下运行时，自托管审议仍是正确选择。当您真正需要的是标准委派加 rubric 评分时，托管 Multiagent 则是正确选择。

最小可行审议

从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%的价值。其余所有内容都只是渐进式改进。

置信度触发器

并非每项任务都需要审议。置信度评分模块会评估4个维度：¹⁷

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

评分映射到3个等级：

阈值会随任务类型调整。安全决策需要0.85的共识。文档修改只需0.50。这样既能避免对简单任务过度设计，也能确保高风险决策得到审查。⁷

状态机

共7个阶段，每个阶段均受前一阶段约束：⁷

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

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

DELIBERATION： 智能体查看所有研究发现并生成备选方案。Debate 智能体识别冲突。Synthesis 智能体整合不存在矛盾的发现。

RANKING： 每个智能体都会从5个加权维度对每种拟议方法评分：

双门验证架构

两个验证 gate 会在不同阶段捕捉问题：⁷

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. 改进证据：最终置信度高于初始置信度

生命周期中不同节点的两个 hooks，契合了故障的实际发生方式：有些是即时的（评分不佳），有些则是渐进的（多样性不足、缺少异议记录）。⁷

为什么一致意见很危险

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分以内，表明是共享上下文污染，而非独立评估。当5个智能体评估一次身份验证重构时，所有智能体对安全风险的评分都在7.1至7.4之间；使用全新的上下文隔离重新运行后，评分分布扩展至5.8-8.9。

模板化异议： 智能体复制彼此的关切措辞，而不是独立提出反对意见。

缺失的少数派视角： 具有冲突优先级的角色一致批准（安全分析师和性能工程师很少会在所有事项上都意见一致）。

一致性检测器能捕捉明显情况（约占智能体过快趋同的审议的10-15%）。对于其余85-90%，共识和 pride check gates 可提供充分验证。

审议中未奏效的方法

自由形式的辩论轮次。 针对数据库索引讨论进行3轮来回文本辩论，产生了7,500个 token 的辩论内容。第1轮：真实分歧。第2轮：重述立场。第3轮：用不同措辞表达相同论点。结构化维度评分取代自由形式辩论后，成本降低60%，同时提高了排序质量。⁷

单一验证 gate。 第一版实现在会话结束时运行一个验证 hook。某智能体以0.52的共识评分（低于阈值）完成审议，随后又在无关任务上继续工作20分钟，直到会话结束 hook 才标记该失败。拆分为两个 gates（一个在任务完成时，一个在会话结束时）后，可在不同生命周期节点捕捉同类问题。⁷

审议成本

每个研究智能体会处理约5,000个 token 的上下文，并生成2,000-3,000个 token 的发现。使用3个智能体时，每项决策会增加15,000-24,000个 token。使用10个智能体时，约为50,000-80,000个 token。⁷

按当前 Opus 5 定价（每 MTok $5/$25），一次3智能体审议的成本约为$0.23-0.30。一次10智能体审议的成本为$0.75-1.00。系统仅在约10%的决策中触发审议，因此所有决策的摊销成本为每个会话$0.08-0.10。（早期版本引用的数字是这3倍，按旧版$15/$75的 Opus 4.x 定价计算。）这是否值得，取决于错误决策的代价。

何时进行审议

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 层级的防护；精简提示词中“如果工具失败，重试三次”的脚手架。
• xhigh 努力等级： 与 Opus 4.7 一同推出，目前受当前 Opus 模型支持（Opus 4.8 在 v2.1.154 中以 /effort xhigh 发布；Opus 5 继承此功能）。介于 high 与 max 之间。建议将其作为编程和 agentic 工作负载的默认选择。对于长时间运行的 subagents，xhigh 的表现显著优于 high，而 token 成本增幅低于比例增长。max 仍适合单次高难度推理；xhigh 更适合持续性任务。
• Token 预算上限： 可通过 output_config.task_budget（beta header task-budgets-2026-03-13）为每次 agent 运行配置。模型会看到持续递减的倒计时，并根据预算平稳收束工作范围，而非意外耗尽。适用于希望 token 支出可预测、又不牺牲短提示词质量的 agentic 循环。
• 隐含需求感知： 首个通过“隐含需求”测试的 Claude 模型——能够识别用户字面请求未充分说明其实际需求的情形。这降低了 CLAUDE.md 中“澄清规则”章节的必要性。如果您的 CLAUDE.md 有 200 行“当用户请求 Y 时还要考虑 X”之类的防护规则，可以删减那些现已由模型原生覆盖的内容。

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

Claude Code v2.1.133 新增了 4 项值得了解、面向生产 harness 的管理员级设置：³⁹

需要提醒用户的是 worktree.baseRef 的回退：依赖 v2.1.128-v2.1.132 行为（worktrees 从本地 HEAD 分支创建）的 agents，除非重新选择启用，否则会在新 worktrees 中失去对未推送工作的访问权限。

面向企业可观测性的 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 进程——这为端点 agents、启动时策略检查，以及要求每个进程均在指定监管程序下运行的环境提供了集成点。如果您的企业此前通过 shell 别名或分叉的启动脚本模拟这一能力，现在已有受支持的衔接点。

同一版本还降低了 harness 最敏感处的运行时开销：在拥有大量 MCP 工具的会话中，工具使用轮次最高可快 7 倍，会话转录内容最高可缩小 79 倍。⁶⁸ 这缓和——但并未推翻——成本即架构的建议：对于无状态的一次性操作，CLI 优先仍然更胜一筹；但携带数十个 MCP 工具的 harness 不再承担春季时每轮的性能代价，转录存储也不再是长时间自主运行中的隐性成本。

质量循环

所有非平凡变更都必须遵循的审查流程：

1. 实施 - 编写代码
2. 审查 - 逐行重新阅读。发现拼写错误、逻辑错误和表述不清的部分
3. 评估 - 运行 evidence gate。检查模式、边界情况和测试覆盖率
4. 完善 - 修复每一个问题。绝不推迟到“以后”
5. 全局审视 - 检查集成点、导入和相邻代码是否存在回归
6. 重复 - 若任一 evidence gate 标准未通过，返回第 4 步
7. 报告 - 列出变更内容、验证方式，并引用具体证据

Evidence Gate

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

如果无法为任一行提供证据，请返回“完善”阶段。²²

人工合并权限

一项发表于 2026年5月、研究了 29,585 个 AI-agent pull-request 生命周期的 arXiv 研究，将执行自主权与合并治理区分开来。⁴⁷ 其有价值的架构启示很简单：agents 可以启动工作、推进分支、创建 PR、审查工作并总结风险，而合并权限仍是独立的治理边界。

应在 harness 中明确这一边界。允许 agents 准备 PR 并收集证据；除非组织另有经过独立审计的自动化策略，否则合并、发布和破坏性仓库操作必须经人工批准。如果自动化执行合并，应保留日志，区分执行者与授权该操作的人员或策略。

错误处理模式

原子文件写入。 多个 agents 同时写入同一个状态文件会损坏 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))。¹⁶

影响范围分类

按影响范围对每项 agent 操作分类，并据此设置门控：²

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

自主运行的任务规范

高效的自主任务包含 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 状态码、文件存在性检查。早期有一项任务要求 agent“编写能通过的测试”，结果产生了 assert True 和 assert 1 == 1。从技术上说完全正确，实际上却毫无价值。¹⁶

需要留意的失败模式

一个具体的会话轨迹

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

1. SessionStart 触发。 Dispatcher 注入：当前日期、项目检测、哲学约束、成本跟踪初始化。共 5 个 hooks，总计 180ms。

2. Agent 读取 PRD，规划第一个故事。 UserPromptSubmit 触发。Dispatcher 注入：活跃项目上下文、会话漂移基线。

3. Agent 调用 Bash 运行测试。 PreToolUse:Bash 触发。执行凭据检查、sandbox 验证、项目检测。90ms。测试运行。PostToolUse:Bash 触发：记录活动心跳，执行漂移检查。

4. Agent 调用 Write 创建文件。 PreToolUse:Write 触发：文件范围检查。PostToolUse:Write 触发：lint 检查、提交跟踪。

5. Agent 完成故事。 Stop 触发。质量门检查：agent 是否引用了证据？是否使用模棱两可的语言？diff 中是否有 TODO 注释？若任一检查失败，则退出 2，agent 继续执行。

6. 独立验证： 一个新的 agent 不信任前一个 agent 的自我报告，独立运行测试套件。

7. 3 个代码审查 agents 并行启动。 每个 agent 独立审查 diff。若任一审查者标记为 CRITICAL，该故事将重新进入队列。

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

5 个故事中触发的 hooks 总数：约 340 个。hooks 总耗时：约 12 秒。这些开销在一次夜间运行中阻止了 3 次凭据泄露、1 条破坏性命令和 2 次不完整实施。

案例研究：夜间 PRD 处理

一个生产 harness 在 8 次夜间会话中处理了 12 个 PRD（47 个故事）。指标将前 4 个 PRD（最小 harness：仅 CLAUDE.md）与后 8 个（完整 harness：hooks、skills、质量门控、多 agent 审查）进行对比。

两次凭据泄露需要轮换 API 密钥并审计下游服务：事件响应约耗时 4 小时。用于避免同类问题的 harness 开销则是每个故事 2.4 秒 bash 时间。虚假完成率从 35% 降至 4%，因为 Stop hook 在允许 agent 报告完成之前独立运行了测试。

安全注意事项

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

Anthropic于2026年4月9日发布了关于 Agent 可信赖性的正式框架。²⁷这五项原则与本指南中的 Evidence Gate 思路相呼应，并在此基础上进一步拓展：

Anthropic还将MCP捐赠给 Linux Foundation 的 Agentic AI Foundation，与 AGENTS.md（现由 OpenAI、Google、Cursor、Factory、Sourcegraph 共同维护）并列。Agent 互操作性标准如今已实现供应商中立。²⁷

MCP的无状态轮次与自报身份。 MCP规范通过2026年7月28日修订版（现为 Current spec）完成向无状态核心（SEP-2575）的过渡，移除了此前用于携带服务器身份的有状态 initialize 握手。7月16日合并的一项草案规范变更（PR #3002）将身份恢复为一个可选界面：服务器可在响应_meta中包含io.modelcontextprotocol/serverInfo对象，而请求中的clientInfo变为可选项。⁷¹与安全相关的关键在于规范对信任的说明：该身份由服务器自行报告，未经验证——仅用于显示和日志记录——且不应作为安全决策依据。如果您的 harness 根据某个MCP服务器声明的名称设置 allowlist、权限规则或基于日志的审计，该名称只是声明，而非凭据；信任应固定在传输层与配置上（即您将哪台服务器配置在何个端点），绝不能基于服务器自称的身份。无状态修订版已于2026年7月28日如期发布（强制性server/discover、通过_meta进行协议版本协商、Streamable HTTP header）；以上信任指导描述的是已发布的行为。

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

Sandbox

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

2026年5月安全底线。 Claude Code v2.1.149 修复了 PowerShell 工作目录权限绕过、多个 PowerShell allow-rule 与陈旧变量权限分析缺口，以及一个 git-worktree sandbox 写入 allowlist 漏洞；后者错误覆盖了整个主仓库根目录，而非仅限共享的 git 内部文件。⁵³若您的 harness 允许 PowerShell 或 worktree 隔离的 Agent，应将 v2.1.149+ 视为最低版本，并保持 shell 规则范围收窄。宽泛的PowerShell(*)和全仓库写入例外只是编排捷径，并非安全边界。

OpenAI Agents SDK sandbox 锁定（v0.17.0，2026年5月8日）。在 OpenAI 侧，openai-agents-pythonv0.17.0 收紧了一条并行边界：除非通过Manifest.extra_path_grants使用SandboxPathGrant明确授予源路径，否则LocalFile.src和LocalDir.src现在必须位于 materialization base_dir之内（应用 manifest 时，SDK进程的当前工作目录）。⁴¹相对本地源从base_dir解析；绝对路径必须已位于其中，或附带授权。此举修复了本地产物边界问题：此前版本允许 manifest 将任意主机路径拉入 sandbox 工作区。迁移方式：在 manifest 层级通过SandboxPathGrant(path=..., read_only=True)为只读挂载声明可信主机根目录。应将extra_path_grants视为可信的应用配置；切勿根据模型输出或不可信的 manifest 输入填充授权。

OpenAI Agents SDK后续底线（v0.17.3）。 0.17.1-0.17.3 版本线增加了更多 sandbox 与会话加固措施：归档提取限制、GitRepo 子路径验证、更清晰的 sandbox-provider 错误、将挂载点凭据排除在 sandbox 命令之外、拒绝相对 sandbox 工作区根目录，以及 Vercel-sandbox 终态处理。⁵⁴若您使用 OpenAI 托管或 provider-backed sandboxes，而不只是Claude Code hooks，应将 0.17.3 视为本节模式的当前最低版本。

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

Anthropic的工程文章《How we contain Claude across products》（2026年5月25日）是该供应商对本节零散讲解原则的完整阐述——上述设置级 sandbox、worktree 隔离底线，以及将一切视为不可信的立场。⁸¹其核心做法是将隔离强度映射到产品界面，而这一映射本身就是关键所在：不存在唯一正确的隔离设计，只有与监督能力及潜在风险相匹配的隔离。

• 临时 gVisor 容器（claude.ai）。服务器端执行在隔离基础设施上的 gVisor 容器中运行，并使用按会话划分的临时文件系统。其威胁模型侧重于基础设施与租户隔离——用户机器永远无法访问，因此无需防护本地资源。
• 人工参与的操作系统 sandboxing（Claude Code）。即上文 sandbox 段落所述模式，以策略形式表述：macOS 使用 Seatbelt，Linux 使用 bubblewrap；允许读取，将写入限制在工作区内，并默认拒绝网络——边界未覆盖的内容由人工批准。Anthropic开源了运行时（sandbox-runtime），因此该边界可被审计。该文章坦率指出了薄弱环节：约93%的权限提示都会被批准；而 auto-mode 分类器会在执行前拦截约83%的过度行为，同时减少84%的批准提示，它的存在正是因为批准疲劳属于安全属性，而非 UX 抱怨。这正是本指南自 v2.1.193 起一直强调的检查层立场。
• 密封 VM（Claude Cowork）。在平台 hypervisor 上运行完整虚拟机——macOS 使用 Apple Virtualization framework，Windows 使用 HCS——仅挂载选定的工作区和.claude文件夹；主机上的其他内容均不可见。凭据从不进入 VM：它们保留在主机 keychain 中，每个会话获得一个范围受限、可独立撤销的 token。VM 内的防御性 MITM proxy 会强制执行此规则，仅转发携带 VM 自身预配会话 token 的请求——攻击者植入的密钥会在边界处被拒绝，因为只有 VM 知道其来源。

该分类法背后的设计原则才是可迁移的核心。先在环境层隔离，再在模型层引导：任何概率性防御都有非零漏检率，因此确定性边界必须拦截提示层引导漏掉的内容——这正是本指南关于 hooks 保证执行的论点，现由供应商重新表述。使隔离强度与用户的监督能力相匹配：开发者可以在批准前评估 bash 命令；知识工作者则无法做到——因此 Code 获得权限对话框，而 Cowork 获得密封 VM。优先采用久经考验的原语，而非自定义隔离代码：hypervisor、seccomp 和容器运行时经受住了比Anthropic自身的自定义 allowlist proxy 和配置解析器更严苛的对抗性审查。将项目本地配置和工具输出视为不可信：文章要求将打开项目和加载配置视同来自互联网的任意入站请求，并将工具输出视为攻击面，即使该工具本身可信——这与本指南对 Agent 间消息、subagent 读取的内容以及自报MCP身份所采取的立场一致。将凭据置于 sandbox 之外：使用范围受限、可撤销、按会话划分的 token，而不是 Agent 可能泄露的环境密钥。

设置界面正在追赶第一原则（v2.1.219）。“先在环境层隔离”很容易认同，却一直难以实际配置，因为Claude Code对其规则未覆盖的情况会通过提问来处理——而权限提示是一种披着确定性外衣的概率性防御，正如上文93%的批准率所承认。sandbox.network.strictAllowlist移除了出站请求的提问：设置后，sandboxed 命令对不在 allowlist 中的主机发出的请求会被直接拒绝，而非弹出提示。⁸⁴将其与 v2.1.216 的sandbox.filesystem.disabled配合使用，这两个设置便可组合成一种安全姿态，而非一堆开关——文件系统和网络隔离可独立选择，网络隔离现在也可实现确定性。对于无人值守的 harness，这两者中网络隔离更重要，因为出站通道正是被注入的指令变成数据外泄的地方，而批准疲劳的终极情形是键盘前根本无人可疲劳。代价则是确定性边界的常规代价：allowlist 必须正确，遗漏的主机会以不透明的拒绝失败，而不是向您提问。请枚举 Agent 合法需要访问的主机，然后移除提示。

这些措施均不能替代 hook 层；它们位于其下方。隔离模式构成确定性底线，而本指南中的 worktree 强制执行历史则以更小的尺度说明了同一个道理：边界只有在面对蓄意重定向时仍能守住才算数，而最可能守住的原语往往并非为了某个特定场景临时编写。

权限边界

权限系统在多个层级控制操作：

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

Claude Code v2.1.178 将权限规则从工具层级扩展到参数层级：Tool(param:value)会匹配工具的输入参数，其中*为通配符。标准示例为Agent(model:opus)——该规则可阻止以特定模型层级生成 subagents。⁶³从架构角度看，这填补了上方四级表无法表达的缺口：此前只能整体允许或拒绝一个工具，无法约束其调用方式。现在，治理策略可以规定“允许生成 subagents，但不得使用 Fable 5 层级”，或“允许 Bash，但不得使用此 flag”，并将其作为确定性规则，而非提示层请求。

一项配套的托管设置enforceAvailableModels（v2.1.175）从顶层约束模型选择：它固定 Default model，并防止用户范围或项目范围的设置扩大托管的availableModelsallowlist。⁶³两者可以组合使用——allowlist 定义会话中哪些层级可用，而参数级规则约束 subagents 如何从中选择。截至 v2.1.196，管理员还可在组织控制台设置组织范围的默认模型，并在/model中显示为“Org default”；因此整个团队可继承受治理的默认值，而无需每位操作员单独固定模型——这是对 allowlist 上限的下限补充。

路径范围 Allow 规则锚定到工作目录（2026年7月）

Claude Code v2.1.214 修复了路径范围权限规则中的一项隐蔽过度匹配：带有单段dir/**模式的 allow 规则——例如Edit(src/**)——此前会自动批准任意深度、名称为src的目录中的编辑，包括vendor/some-package/src/以及规则作者从未打算允许的所有其他嵌套src/。此类规则现在仅锚定到<cwd>/dir；若确实需要匹配任意深度，应明确声明为**/dir/**。⁷⁴Deny 和 ask 规则则有意保留原先的任意深度匹配。该不对称性是正确的故障安全设计：匹配过窄的 allow 规则会安全失败（您会收到提示），而匹配过窄的 deny 规则会开放失败（被阻止的路径可能漏过）——因此 allow 规则变得更严格，deny 规则仍保持宽泛。若您的设置依赖单段 allow 模式覆盖嵌套路径，那么从 v2.1.214 起它们已悄然不再生效；这是修复按预期运行，但仍值得检查您的 allowlists，以重新声明您实际需要的匹配范围。

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），除非您指定具体 stack。⁶⁵从架构角度看，这是对上述生成审查和参数级规则的补充：它不再控制使用哪种工具或如何生成，而是按意图控制一小组特定的不可逆命令——Agent 仍可运行它们，但必须依据明确指令，而不能自行决定。对于自主 harness，应在自己的 PreToolUse hooks 中编码同一原则：销毁状态的命令应采用默认拒绝规则，只有明确的操作员信号才能解除。

2026年7月：auto mode 走向企业级，且有一项提示无法豁免。在 v2.1.207 中，Auto mode 在 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 达到 GA，并提供disableAutoMode托管设置作为企业退出选项——分类器作为检查层的安全姿态现已适用于所有第一方企业平台，禁用它成为一项明确的治理决策，而不再是平台缺口。⁶⁸随后 v2.1.208 使灾难性删除防护成为绝对规则：灾难性删除的确认提示现在会穿透--dangerously-skip-permissions和 auto mode。⁶⁸这是一个值得注意的先例——Claude Code中首个任何权限姿态（包括显式绕过 flag）都无法豁免的确认机制。假定--dangerously-skip-permissions意味着完全零提示的自主 harness 设计，应考虑这一例外；它恰恰会在无人值守循环可能造成最不可恢复损害的地方触发。

反伪造护栏（2026年7月）

v2.1.203–v2.1.206 版本关闭了 Agent 伪造自身审计轨迹的两条路径。⁶⁸首先，auto-mode 规则现在会阻止篡改转录文件——会话记录不再是会话自身工具调用可以重写的内容。其次，后台任务通知现在会明确说明任务运行期间未发生人工输入。第二项针对一种微妙的失败模式：模型此前可在总结后台任务时展示（或虚构）一项从未发生的转录内“批准”，而通知中没有任何内容与其矛盾。现在，通知本身就是反证据。

这一架构经验可泛化到 Evidence Gate：转录记录、通知和日志都是审计界面，而审计界面不得由其所审计的对象写入。平台现在为自己的转录记录强制执行此规则；请将同一规则应用于您的 harness——证据报告、测试输出和审议记录应位于模型的可写路径之外。

提示注入防御

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 的 payload-filter 问题，在默认日志记录行为下，敏感工具 payload 内容可能保留在本地 SQLite 日志中。⁴⁵OSV GHSA-wxxx-gvqv-xp7p 涉及 LiteLLM自定义代码 guardrail 在受管理员保护的 proxy endpoint 中逃逸 sandbox 的问题。⁴⁶

生产环境规则是：将 Agent 转录记录、工具 payload、SQLite 日志和 guardrail 执行视为敏感基础设施。持久化前进行脱敏，设置保留期限，并保持自定义 guardrail 代码处于 sandbox 中且可供审查。提示层的“不要记录密钥”规则并不足够；日志与 guardrail 路径需要确定性测试。

Hook 安全性

将环境变量插入 headers 的 HTTP hooks 需要显式allowedEnvVars列表，以防止任意环境变量外泄：¹³

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

人类与 Agent 的职责划分

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

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

递归 Hook 强制执行

Hooks 也会针对 subagent 操作触发。¹³如果Claude通过 Agent tool 生成 subagent，您的 PreToolUse 和 PostToolUse hooks 会针对该 subagent 使用的每个工具执行。若没有递归 hook 强制执行，subagent 便可能绕过您的安全门。SubagentStop事件让您可在 subagent 完成时执行清理或验证。

这不是可选项。一个生成 subagent 却未使用您的安全 hooks 的 Agent，能够在您的门控只监视主对话而无所作为时，强制推送到 main、读取凭据文件或运行破坏性命令。

成本即架构

成本是架构决策，而非运营层面的事后考虑。²分为三个层级：

Token 层级。压缩系统提示。删除教程代码示例（模型知道APIs），合并跨文件的重复规则，并以约束替代解释。“拒绝匹配敏感路径的工具调用”与用15行解释为何不应读取凭据，起到相同作用。

Agent 层级。优先使用新生成的 Agent，而非长对话。自主运行中的每个 story 都分配一个具有干净上下文的新 Agent。由于每个 Agent 都从头开始，上下文不会不断膨胀。用 briefing 取代 memory：模型执行清晰 briefing 的效果优于在累积了30步的上下文中导航。

架构层级。当操作是无状态的，优先使用CLI而非MCP。一次性评估的claude --print调用成本更低，且不会增加连接开销。当工具需要持久状态或流式传输时，MCP才有意义。

决策框架

何时使用各类机制：

Skills、Hooks 与 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 配置文件放在哪里？

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

每个决策都需要 deliberation 吗？

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

如何测试一个旨在产生分歧的系统？

应同时测试成功路径与失败路径。成功路径：agents 富有成效地提出分歧并达成共识。失败路径：agents 过快趋同、始终无法趋同，或超出 spawn 预算。端到端测试使用确定性的 agent 响应模拟每种场景，验证两道验证门都能捕获每种已记录的失败模式。一个生产级 deliberation 系统在三个层级运行141项测试：48项 Bash 集成测试、81项Python单元测试，以及12项端到端管道模拟。⁷

deliberation 对延迟有何影响？

3-agent deliberation 会增加30—60秒的实际耗时（此 deliberation 设计通过 Agent tool 依次运行 agents；自v2.1.198起，平台本身会在后台并发运行 subagents）。10-agent deliberation 会增加2—4分钟。共识和 pride check hooks 均可在200ms内运行完成。主要瓶颈是每个 agent 的LLM推理时间，而非编排开销。⁷

CLAUDE.md 文件应有多长？

每个部分应控制在50行以内，整个文件不超过150行。长文件会被上下文窗口截断，因此应将最关键的指令置于前部：先列出命令和完成定义，再写风格偏好。²¹

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

架构原则（hooks 作为确定性门禁、skills 作为领域专业知识、subagents 作为隔离上下文、文件系统作为记忆）在概念上适用于任何 agentic 系统。具体实现使用了Claude Code的生命周期事件、matcher 模式和 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.

退出代码

关键命令

文件位置

更新日志

参考资料