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

TL;DR：Claude Code不是一个带文件访问权限的聊天框。它是一个可编程运行时，拥有29个已记录的生命周期事件，每个事件都可以通过模型无法跳过的 shell 脚本挂接。将 hooks 叠加成 dispatchers，将 dispatchers 组织成 skills，将 skills 交给 agents，再把 agents 编排为 workflows，就能得到一套自主开发 harness：它可以强制执行约束、委派工作、跨会话持久化 memory，并编排 multi-agent deliberation。Claude Code v2.1.147 新增了默认关闭的 Workflow tool（CLAUDE_CODE_WORKFLOWS=1），将确定性的 multi-agent orchestration 从纯 userland 脚本推进到第一方运行时原语；v2.1.149 则从安全侧强化了同一个经验，修复了 PowerShell 权限绕过问题和 git-worktree 沙箱 allowlist 问题。Hooks 和 evidence gates 仍然掌管正确性。⁵²⁵³本指南覆盖该技术栈的每一层：从单个 hook 到10-agent 共识系统。无需任何框架。全程只用 bash 和 JSON。

Andrej Karpathy 为围绕 LLM agent 生长出来的东西创造了一个术语：claws。也就是让 agent 能够抓取其上下文窗口之外世界的 hooks、脚本和 orchestration。¹大多数开发者把 AI 编码 agent 当作交互式助手。他们输入 prompt，看着它编辑文件，然后继续下一步。这种思维框架会把生产力上限限制在您能亲自监督的范围内。

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

这种区别很重要，因为基础设施会复利增长。一个阻止 bash 命令中出现凭据的 hook，会保护每个会话、每个 agent、每次自主运行。一个编码了评估准则的 skill，无论是您调用它，还是 agent 调用它，都会一致生效。一个负责安全代码审查的 agent，无论您是否在旁观察，都会运行同样的检查。²

关键要点

• Hooks 保证执行；prompts 不能。对 lint、格式化、安全检查，以及任何无论模型行为如何都必须每次运行的事项，请使用 hooks。退出码2会阻止动作。退出码1只发出警告。³
• Skills 编码可自动激活的领域专业知识。description 字段决定一切。Claude 使用 LLM 推理（而不是关键词匹配）来决定何时应用某个 skill。⁴
• Subagents 防止上下文膨胀。用于探索和分析的隔离上下文窗口，可以让主会话保持精简。独立的 subagents 可以并行运行；当工作单元需要持续协调时，请使用 agent teams。⁵
• Memory 存在于文件系统中。文件可以跨上下文窗口持久存在。CLAUDE.md、MEMORY.md、规则目录和交接文档共同构成结构化的外部 memory 系统。⁶
• Multi-agent deliberation 能发现盲点。单个 agent 无法挑战自己的假设。两个具有不同评估优先级的独立 agents，可以发现质量门禁无法覆盖的结构性失败。⁷
• Harness pattern 就是系统本身。CLAUDE.md、hooks、skills、agents 和 memory 并不是相互独立的功能。它们组合成您与模型之间的确定性层，并且会随着自动化规模一起扩展。

如何使用本指南

每一节都建立在前一节之上。末尾的 Decision Framework 提供了一张查找表，用于为每类问题选择合适的机制。

五分钟黄金路径

在深入剖析之前,先来看从零到可用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。

框架模式

框架不是一个框架体系，而是一种模式：一组可组合的文件、脚本和约定，将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文件在会话之间持久化状态。自定义agents提供专门的subagent配置。

编排层： 多代理模式协调独立代理进行研究、审查与审议。生成预算可防止递归失控。共识验证确保质量。

关键洞见在于：大多数用户完全在核心层中工作，眼看着上下文膨胀、成本攀升。高阶用户则配置指令层和扩展层，仅将核心层用于编排和最终决策。²

托管框架与自托管框架（2026年4月）

整个2026年初，”自建框架”是唯一可行的路径。2026年4月，这一情况发生了改变。Anthropic于4月8日推出了公开测试版的Claude Managed Agents：将框架循环+工具执行+沙箱容器+状态持久化作为REST API提供，按标准token计费另加每会话小时0.08美元。OpenAI于4月16日发布的Agents SDK更新正式确立了相同的拆分——将框架与计算作为独立层，配备原生沙箱提供商（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用于按运行配置沙箱客户端、实时会话注入、清单覆盖、快照和物化并发限制。内置能力涵盖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返回值，使模型得到一个验证错误blob），并使SandboxNetworkConfig与TypeScript SDK的schema对齐（allowedDomains、deniedDomains、allowManagedDomainsOnly、allowMachLookup）。³⁰

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

架构分叉如今已成现实：

何时选择哪一种： 自托管仍然适合那些已具备基础设施实力、希望掌控自有skills/hooks，或正在深度优化特定工作流的团队。托管则适合没有专职平台工程师的团队、当快速产生价值比定制化更重要时，或当代理运行需要可靠地在笔记本电脑关闭后继续存活、而您又不想自行构建持久化层时。两者是兼容的——您可以运行一个自托管框架，通过其REST API将特定的长时间运行任务委派给Managed Agents。

框架在磁盘上的样貌

~/.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共享。两者共同构成了完整的框架。

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描述会被注入系统提示的available_skills部分，模型则使用标准语言理解来选择相关skills。¹⁰

不佳描述：

description: Helps with code

有效描述：

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.

有效描述包括：它做什么（针对特定问题类型审查代码）、何时使用（检查变更、PR、质量分析），以及用户自然会输入的触发短语（review、audit、check）。

上下文预算

所有skill描述共享一个上下文预算，该预算会动态缩放为上下文窗口的1%，并以8000个字符作为回退值。⁴如果skills很多，请保持每个description简洁，并把关键用例放在最前。您可以通过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中使用相对链接引用它们。Claude会在skill激活时按需读取这些文件。请将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是强制执行。二者结合形成一个策略层。

常见Skill错误

描述过宽。 一个git-rebase-helper skill如果会在任何与git相关的提示上激活（rebase、merge、cherry-pick，甚至git status），就会污染80%的会话上下文。修复方式是收紧description，或添加disable-model-invocation: true并要求显式通过/skill-name调用。⁴

过多skills争抢预算。 skills越多，争抢1%上下文预算的description也越多。如果发现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将该目录扩展到plugins：现在，放在.claude/skills/中的plugin会自动加载，无需marketplace注册；claude plugin init <name>会在那里搭建一个全新的plugin，并已连接好manifest和SKILL.md。⁵⁸这弥合了两种项目工具形态之间的差距：一种是直接提交到仓库的裸skill，另一种是捆绑了skill、hooks以及MCP服务器的plugin，但过去需要通过marketplace安装。对harness设计的实际影响是：项目级工具不再需要绕道registry才能交付。写好、提交，队友在git pull后就能获得同样的界面。Plugins仍然负责可捆绑安装的用例（hooks + skills + MCP服务器 + agents打包在一个ZIP中）；变化在于，项目不再需要仅为从自身目录树加载一个plugin而搭建marketplace。

将捆绑界面隐藏为治理手段（2026年6月8日）

Skills是能力，而能力就是攻击面。Claude Code v2.1.169新增了disableBundledSkills设置（以及匹配的CLAUDE_CODE_DISABLE_BUNDLED_SKILLS环境变量），可将捆绑的skills、workflows和内置slash commands对模型完全隐藏。⁶⁰对于加固型或受监管的harness，这是有意缩减攻击面：如果操作员已经审计并批准了一组特定的项目与个人skills，就可以隐藏Anthropic随附的全部内容，使模型只会基于操作员已审核的界面进行推理。应像对待工具allowlist一样看待它。默认状态是广泛能力；关闭默认能力是一项治理决策，而不是为了方便而切换的开关。

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

Claude Code v2.1.178让项目工具具备了位置感知能力。现在，当您处理某个目录下的文件时，嵌套.claude/skills目录中的skills也会加载，而不再只从仓库根目录加载；若发生名称冲突，嵌套skill会显示为<dir>:<name>，因此两者都仍可访问。⁶³同一版本还让其余项目界面按最接近工作目录的规则解析：当agent、workflow或output-style名称在嵌套.claude/目录之间冲突时，离工作目录最近的那个优先；保存项目范围workflow时，也会写入最近的现有.claude/workflows/，而不是总是写入根目录。⁶³对于monorepo或repo-of-repos而言，这相当于从一个扁平的全局界面，变为可按上下文激活的逐包工具。services/api/.claude/skills/可以携带特定于API的skills，并且只在您处理该目录树时出现，同时不会与同名的services/web/ skill冲突。

Hook 架构

Hooks 是由 Claude Code 生命周期事件触发的 shell 命令。³ 它们作为普通脚本在 LLM 之外运行，而不是由模型解释的 prompts。模型想运行 rm -rf /？一个 10 行的 bash 脚本会先对照阻止列表检查命令，并在 shell 看到它之前拒绝执行。无论模型是否愿意，hook 都会触发。

可用事件

截至本指南更新时，Claude Code 在8个类别中公开了29个有文档记录的生命周期事件。事件列表会随版本发布而增长，因此请将参考文档视为事实来源；在接入生产 hooks 前，请查看 cheat sheet 获取当前完整表格：¹³

退出码语义

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

关键点：每个安全 hook 都必须使用 exit 2，而不是 exit 1。退出码 1 是非阻塞警告。危险命令仍会执行。这是各团队最常见的 hook 错误。¹⁴

Hook 配置

Hooks 存放在 settings 文件中。项目级（.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 正则表达式。有些事件不支持 matchers，一旦配置就总会触发。¹³

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 会在每次文件变更后运行 formatter。模型的输出并不重要，因为 formatter 会规范化一切。

{
  "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 或测试套件；如果质量检查失败，就阻止 commit：

#!/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 类型：¹³

Command hooks（type: "command"）运行 shell 脚本。快速、确定性强、无 token 成本。

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

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

Agent hooks（type: "agent"）会生成一个具备工具访问权限（Read、Grep、Glob）的 subagent，用于多轮验证。它们仍属实验性；生产 gate 请优先使用 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，而不必从 prompt 文本中猜测。⁴⁹

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。每个解析该文件的下游 hook 都会出错。²

修复方法：每个事件使用一个 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

调试静默失败 hooks 的5个技巧：¹⁴

1. 独立测试脚本。通过管道传入示例 JSON：echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. 用 stderr 输出调试信息。退出码 2 的 stderr 会作为错误消息反馈给 Claude。非阻塞 stderr（退出码 1、3 等）只会在 verbose 模式下显示（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）仍然是正确答案。

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

Claude Code v2.1.132 和 v2.1.133 中的两项新增能力，让 hooks 和子进程能更好地感知其执行上下文：³⁸³⁹

• Hook 输入中的 effort.level。Hooks 现在会在同一个输入中收到 effort.level JSON 字段，该输入也携带 tool_input 和 session_id。同一个值还会导出为 $CLAUDE_EFFORT 环境变量，因此 Bash 命令无需解析 JSON 即可读取它。可用它按 effort tier 调整 hook 成本：在 low 上跳过昂贵验证，在 xhigh 或 max 上运行完整安全 gate。
• Bash 子进程上的 CLAUDE_CODE_SESSION_ID 环境变量。Bash 工具子进程现在能看到与 hooks 相同的 session_id 值，并通过 CLAUDE_CODE_SESSION_ID 暴露。这弥合了来源追踪缺口；此前，记录每会话状态的工具无法将子进程事件与 hook 事件关联起来。

这两个信号无需代码变更即可使用；忽略新字段的现有 hooks 会继续正常工作。

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

Claude Code v2.1.136 为 auto mode 添加了新的 hard-deny 层，并修复了一组影响长时间运行 harness 的 plugin 和 MCP 问题：⁴⁰

• settings.autoMode.hard_deny。Auto mode 分类器规则会无条件阻止，不考虑用户意图或允许例外。它位于现有 allow/deny matchers 之上，是一种不可协商的治理杠杆。对于绝不能被覆盖的规则（向 main force-push、包含密钥的文件、生产数据库访问），即便 operator 已在个人设置中批准了更广泛的类别，也应使用它。
• MCP 服务器在 /clear 后不再消失。在 VS Code 扩展、JetBrains plugin 和 Agent SDK 中执行 /clear 后，通过 .mcp.json、plugins 和 claude.ai connectors 配置的服务器曾会静默从活动集合中掉出。该修复已在 v2.1.136 落地。如果您曾看到“MCP server X went missing mid-session”，原因就在这里。
• MCP OAuth refresh-token 在并发刷新时丢失。使用多个远程 MCP 服务器的用户不应再需要每天重新认证。并发刷新写入过去会彼此覆盖。
• Plan mode 现在会正确阻止文件写入。匹配的 Edit(...) allow 规则曾绕过 plan-mode 写入保护。现在无论 allow 规则如何，Plan mode 都会被强制执行。
• Plugin Stop 和 UserPromptSubmit hooks 不再在会话中途失败。缓存清理曾删除运行中会话仍在使用的 plugin-version 文件，专门破坏这两个 hook 事件。修复后，仍在使用的版本会被固定保留。
• plugin.json 中的 skills 条目。设置 skills 曾隐藏 plugin 的默认 skills/ 目录。现在该条目可以正确组合；如果指向文件路径，会抛出明确错误，而不是静默失败。
• CLAUDE_ENV_FILE SessionStart hook 环境变量过期。SessionStart hooks 通过 CLAUDE_ENV_FILE 导出的变量在 /resume 或 /clear 后曾会过期。v2.1.136 已修复。会话现在会在这些事件上重新 source 环境文件。

对于治理型 harness，操作上值得关注的项目是 autoMode.hard_deny（新杠杆）和 MCP 消失修复（会破坏长会话的静默失败）。其他都是使用体验层面的清理。

结构化 Hook 参数与阻塞后继续（2026年5月11日）

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

当 PostToolUse hook 应该把拒绝原因反馈给 Claude，并继续当前 turn 而不是结束流程时，使用 continueOnBlock。请把它视为 operator 体验功能，而不是安全绕过。阻塞 gate 仍然应该阻止不安全结果。

同一版本会将 CLAUDE_PROJECT_DIR 传递给 MCP stdio 服务器，并允许 plugin 配置在命令中引用 ${CLAUDE_PROJECT_DIR}。⁴² MCP 工具应从该值解析项目相对路径，而不是依赖启动服务器的进程工作目录。

Claude Code v2.1.140 主要是面向 harness operator 的可靠性版本：它修复了 settings 变更时 ConfigChange hooks 不触发的问题，关闭了 disableAllHooks 和 allowManagedHooksOnly 在不同 settings 层级间无法正确组合的边界情况，并阻止权限对话框暴露 hook 结果返回的意外环境变量。⁴⁹ 这让本节中的现有治理模式更加可靠；它不要求采用新的 hook 架构。

Claude Code v2.1.141 为桌面通知、窗口标题和无控制终端的响铃添加了 hook 输出 terminalSequence 字段。⁵⁰ 请将其视为 operator 信号，而不是强制手段。安全和质量 gate 仍应通过正常阻塞契约传达失败：结构化 hook 输出，加上阻止不安全动作的退出行为。同一版本还添加了 claude agents --cwd <path>，用于将 Agent View 限定到一个目录；添加了 CLAUDE_CODE_PLUGIN_PREFER_HTTPS，用于无 GitHub SSH keys 环境中的 plugin 安装；并添加了 ANTHROPIC_WORKSPACE_ID，用于覆盖多个 workspace 的 workload-identity federation 规则。⁵⁰ 这些都是团队 harness 的架构细节：更窄的操作视图、更少的 plugin 安装假设，以及明确的企业 token 作用域。

相比 hook 语义，Claude Code v2.1.142 对后台会话编排更重要。⁵¹ claude agents 现在可以使用显式的目录、settings、MCP、plugin、权限、模型和 effort flags 分派后台会话，而不再依赖 wrapper 状态。Fast mode 现在默认使用 Opus 4.7；只有当 harness 已测量并确认依赖 Opus 4.6 行为时，才应固定 CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1。根级 plugin SKILL.md 发现和 plugin 提供的 LSP 可见性降低了打包歧义。对 MCP_TOOL_TIMEOUT、既有后台会话 worktrees、daemon sleep/wake 和升级后清理，以及 plugin 缓存清理的修复，关闭了原本看起来像编排 bug 的可靠性缺口。

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

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

Stop/SubagentStop hooks 获得了 steering 通道。自 Claude Code v2.1.163 起，Stop 或 SubagentStop hook 可以返回 hookSpecificOutput.additionalContext，向 Claude 提供反馈并让当前 turn 继续，而不会把响应标记为 hook 错误。在此之前，Stop hook 唯一真正的杠杆是 exit-2 block；它看起来像错误，并会计入连续阻塞上限。对于质量 gate harness，这是更干净的原语：一个检测到“你说完成了，但测试仍是红的”的 Stop hook 现在可以注入“以下仍在失败，请继续”，而不是硬阻塞。请将 block 用于真正的停止条件，将 additionalContext 用于“尚未完成，原因如下”。

跨会话消息不再携带借来的权限。v2.1.166 强化了多会话场景：通过 SendMessage 从另一个 Claude 会话转发的消息，不再携带发起用户的权限，因此接收会话会拒绝转发的权限请求，auto mode 也会阻止它们。如果您的编排让 agents 彼此发消息，请把入站消息视为不可信数据，而不是已认证指令。这与安全部分应用于工具输出的原则相同，只是扩展到了 agent 间消息。

模型韧性成为一等设置。fallbackModel 设置现在可以按顺序串联最多3个备用模型，在主模型过载或不可用时依次尝试；对于意外的不可重试 API 错误，一个 turn 会在 fallback 上自动重试一次。对于长时间运行的自主 harness，这会将短暂的主模型故障转化为优雅降级，而不是直接丢失运行。claude agents --json 还添加了 waitingFor 字段（v2.1.162），用于暴露被阻塞的后台会话正在等待什么，例如权限 prompt——这对轮询一组 agents 的任何 coordinator 都是可观测性收益。

用于 clean-room 治理和故障排查的 safe mode。Claude Code v2.1.169 添加了 --safe-mode 标志（以及匹配的 CLAUDE_CODE_SAFE_MODE 环境变量），它会启动一个一次性禁用所有自定义项的会话：CLAUDE.md、plugins、skills、hooks 和 MCP 服务器。⁶⁰ 这是 harness 的反面——一个刻意构造的 clean-room。用它回答每个 operator 迟早都会问的问题：“这个行为来自模型，还是来自我的配置？”当 hook 误触发、skill 在不该激活时激活，或 MCP 服务器污染上下文时，--safe-mode 会提供一个已知为空的基线，用来做差异对比。它也是一种治理原语：一种在没有 harness 通常授予的任何持久权限时运行裸模型的方式；当您需要在不受任何 operator 定义脚手架影响的情况下复现结果时，这一点很重要。

关于模型层级的说明。本指南将 Opus 4.8 视为 Claude Code 的 agentic 默认模型——除非另行选择，否则自主 harness 会运行该模型。截至2026年6月9日，Anthropic 发布了 Claude Fable 5（claude-fable-5），这是高于 Opus 的新层级，被描述为其最强大的模型——一个可安全用于通用场景的“Mythos-class”系统——可在 Claude Code v2.1.170 中通过 /model claude-fable-5 选择。⁶⁰ Opus 4.8 仍是 agentic 默认模型；请在原始推理深度足以证明成本合理的决策上，有意识地选用更高层级，而不是把它作为整个 fleet 的一刀切设置。

Codex 发布了 multi-agent v2。Codex CLI v0.137.0 将运行时选择保留在每个 thread 中，为生成的 agents 暴露更清晰的 follow-up 和 metadata 默认值（hide_spawn_agent_metadata 现在默认为 true），并将原始 parent 事件传播给 child listeners。它的 subagent 模型保持显式：内置 default/worker/explorer agent 类型、通过 TOML 定义的自定义 agents，以及并发控制（agents.max_threads 默认为6，agents.max_depth 默认为1）。同一版本添加了 v1 skills 扩展，支持每 turn skill-catalog 解析，并新增 thread-start/turn-error 生命周期 contributor 事件，在保持 kernel-sandbox 姿态作为默认边界的同时，缩小了与 Claude Code hook/skill 表面的差距。随后 Codex v0.138.0–v0.139.0 强化了 multi-agent v2，使其更适合生产：agent 间消息 payload 现在已加密，v2 agent config catalog 加上 agent-residency LRU 会管理哪些 agents 保持驻留，并发按活动执行而非生成的 threads 计数，因此 idle agents 不再占用 slot。⁶¹ 生命周期 API 也更成熟了——close_agent 被重命名为 interrupt_agent（v0.139.0），以反映它会中断正在运行的 agent，而不仅仅是关闭一个 handle——由 subagent 提出的 MCP 启动警告现在会保持限定在所属 thread 中，而不会重复上浮到 parent transcript。⁶¹ 对任何构建 Codex 侧编排的人来说，这些就是 demo 与 fleet 的差别：加密消息传输、有界驻留、按执行计数的并发，以及不会泄漏跨越 thread 边界的警告。随后 Codex v0.140.0 打开了一个跨工具衔接点：/import 可以从 Claude Code 选择性拉取 setup、project config 和 recent chats 到 Codex，并且 sessions 变为可永久删除（codex delete / /delete，带确认保护）。⁶⁴ /import 是官方首次承认 operators 会在 harnesses 之间移动——您为一个工具构建的配置不再被困在那里。

记忆与上下文

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

多轮崩塌的 3 种机制

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 文件用于跨会话记录错误、决策和模式。当您发现 bash 中 VAR 为 0 时，((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 行加载进系统提示。请保持内容简洁，并链接到单独的主题文件，以存放详细笔记。⁶

重视记忆整理，而不是记忆数量（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）保护的是 prompt cache。它可以在不中断本轮已累积缓存的情况下，将会话在进行中切换到新的工作目录。⁶⁰ 在此之前，切换目录意味着必须开启新会话，缓存也会变冷。对于长时间运行、需要从一个仓库转向相邻仓库的会话而言，这在 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（continue）启动新会话，或读取交接文档，即可直接进入实现。¹⁵

策略 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% 的额外开销来完成 orient 步骤（读取状态文件、扫描 git 历史），换取每次迭代完整的认知资源。¹⁶ 成本收益计算如下：对于 60 分钟以内的会话，单个对话更高效。超过 90 分钟后，尽管存在额外开销，新鲜上下文仍能产出更高质量的结果。

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

Anthropic 的 Claude Managed Agents 于 2026年5月6日以 Research Preview 形式加入了 Dreaming。³⁵ 根据 Anthropic 的说法：”Dreaming is a scheduled process that reviews your agent sessions and memory stores, extracts patterns, and curates memories so your agents improve over time.”³⁵

Dreaming 在会话之间的后台运行，不处于关键路径上。它补充而不是替代“文件系统即记忆”的模式：您的 MEMORY.md 文件仍然是承重面；Dreaming 会将整理后的记忆条目写入 Managed Agents 记忆存储，agent 会在会话开始时读取。对于同时混合自托管文件系统状态与托管端整理的 harness，这两种模式可以并存。

Dreaming 仍处于 Research Preview，因此行为可能变化。上文记录的 session-handoffs 和 CLAUDE.md 模式，仍然是自托管 harness 的权威记忆机制。

反模式

只需要 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 实例，可独立处理复杂任务。它们以干净的上下文启动（不会受到主对话污染），使用指定工具运行，并以摘要形式返回结果。探索结果不会撑大主对话；只有结论会返回。⁵

内置 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 隔离对于可能破坏代码库的实验性工作至关重要。

并行 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 总数过多），而不是替代指标（嵌套层级过多）。⁷

递归委派现在是一等深度能力。 自 Claude Code v2.1.172（2026年6月10日）起，sub-agents 可以生成自己的 sub-agents，最多嵌套 5 层；此前的委派实际上只支持一层。⁶² 这让上面的递归保护更加重要，而不是不再重要：平台现在允许正是那种 agents 委派给 agents 的链条，而这类链条会消耗上下文和 token。因此，生成预算和深度上限才是防止 5 层树扩散成数百个活跃 agents 的关键。请将 5 层视为平台允许的上限，而不是默认应达到的目标。

Auto 模式现在会在启动前审查生成请求。 Claude Code v2.1.178 弥合了匹配治理缺口：在 auto 模式下，subagent 生成会在 subagent 启动之前由权限分类器评估，而不是等它开始执行动作后才评估。⁶³ 以前，某个 subagent 可能被生成出来，请求执行父会话本应被禁止的动作；生成本身就成了绕过路径。启动时审查意味着递归保护和权限模型终于衔接起来：子级不能被用作对策略禁止动作的洗白步骤。

Agent Teams（研究预览）

Agent Teams 协调多个独立工作的 Claude Code 实例，这些实例通过共享邮箱和任务列表通信，并可质疑彼此的发现：⁵

启用方式：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

何时使用 agent teams 而不是 subagents：

Agent View 和 Goal Loops（2026年5月）

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

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

同一版本还新增了 /goal，它可设置完成条件，并让 Claude 跨轮次持续运行，直到满足条件；适用于交互式、-p 和 Remote Control 使用场景。⁴² 应将 /goal 视为会话作用域的完成循环，而不是确定性门禁的替代品。它有助于让 agent 聚焦目标，但在失败必须阻断流程的地方，测试、引用检查、部署检查和安全 hooks 仍应由命令或脚本支撑。

Workflow 工具（v2.1.147+）

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

不要删除它周围的 harness。Workflow 可以组织执行过程，但不能替代安全模型。保留 PreToolUse 和 PostToolUse hooks 作为阻断层；保留生成预算或 workflow 步骤预算，防止宽度失控；保持文件系统状态可审计；并将最终证据报告置于模型自我评估之外。实践中：用 Workflow 定义编排形态；用 hooks、测试和评审门禁确认真相。

多智能体编排

单智能体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 不需要理解您为什么使用 conventional commits。它需要知道要运行的确切命令，以及什么状态才算“完成”。

优先级层级

规则文件会自动加载，并在不让 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 中引用其他文件：

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 coding tool 都识别的开放标准。²¹ 如果团队使用多种工具，请将 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 又在挂载、容器物化或符号链接的 checkout 上运行时，这一点至关重要。这些场景中，朴素的路径遍历可能会悄然选错指令文件，甚至完全找不到文件。如果您在多个服务之间镜像一个权威 AGENTS.md，应将此版本视为信任 agent 实际加载了您所写文件的最低基线。

随后，Codex v0.141.0 强化了远程执行路径本身：远程执行器现在通过经过身份认证、端到端加密的 Noise-relay channels 连接（控制平面和执行器不再信任它们之间的中继），跨平台远程执行会保留执行器的原生工作目录和 shell，并且 TLS 接受用于企业代理的 P-521 证书签名。⁶⁵ 如果您的编排需要跨网络边界驱动 Codex 执行器，这就是可信中继假设与端到端加密假设之间的区别。应将其视为任何远程执行器拓扑的基线。

实际映射如下：

重要区别在于：Claude subagents 可以根据描述自动选择，而 Codex 当前将 subagent 工作流记录为显式流程。因此，在 Codex 中，skills 和 hooks 是始终启用型 harness 行为的默认选择；subagents 则用于有意安排的并行工作、review 和探索。

测试您的指令

验证 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会话中断的工具失败。可以减少subagent代码中的防御性重试封装，但不能完全移除。保留hook级别的防护；精简prompt中“如果工具失败，请再试三次”这类脚手架。
• xhigh工作量等级（仅限Opus-4.7）：介于high和max之间。建议作为编码和agentic工作负载的默认值。对于长时间运行的subagents，xhigh相比high有显著优势，token成本增加低于比例。max仍然适合一次性高难度推理；xhigh更适合持续性任务。
• Token预算上限：可通过output_config.task_budget（beta header task-budgets-2026-03-13）按每次agent运行配置。模型会看到持续倒计时，并根据预算稳妥收敛工作范围，而不是意外耗尽。适用于希望token支出可预测、同时不牺牲短prompt质量的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部署是正确的。

Quality loop

所有非平凡变更都必须经过的强制审查流程：

1. 实现 - 编写代码
2. 审查 - 逐行重读。发现拼写错误、逻辑错误和表述不清之处
3. 评估 - 运行evidence gate。检查模式、边界情况和测试覆盖率
4. 优化 - 修复每个问题。绝不推迟到“以后”
5. 拉远视角 - 检查集成点、imports和相邻代码是否有回归
6. 重复 - 如果任何evidence gate标准失败，返回第4步
7. 报告 - 列出变更内容、验证方式，并引用具体证据

Evidence gate

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

如果任意一行无法提供证据，请返回Refine。²²

人类合并权限

2026年5月一项覆盖29,585个AI-agent pull-request生命周期的arXiv研究，将操作性代理能力与合并治理区分开来。⁴⁷有用的架构启示很简单：agents可以开始工作、推进branches、打开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操作分类，并相应设置gate：²

Remote Control（从任何浏览器或移动应用连接到本地Claude Code）会把“外部”gate从阻塞等待变为异步通知。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个stories的PRD时的会话轨迹：²

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

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

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

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

5. Agent完成story。Stop触发。Quality gate检查：agent是否引用了证据？是否有含糊措辞？diff中是否有TODO注释？如果任何检查失败，退出2，agent继续工作。

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

7. 3个代码审查agents并行spawn。每个agent独立审查diff。如果任何审查者标记CRITICAL，该story会回到队列。

8. Story通过。加载下一个story。该循环对全部5个stories重复。

5个stories期间总计触发hooks：约340次。hooks总耗时：约12秒。这点开销在一次通宵运行中防止了3次凭据泄露、1条破坏性命令和2个未完成实现。

案例研究：通宵处理PRD

一个生产harness在8个通宵会话中处理了12个PRDs（47个stories）。指标比较了前4个PRDs（最小harness：仅CLAUDE.md）与后8个（完整harness：hooks、skills、quality gates、多agent审查）。

这2次凭据泄露需要轮换API密钥并审计下游服务，约消耗4小时事件响应时间。用于防止等价问题的harness开销，是每个story 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 互操作标准如今已实现厂商中立。²⁷

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 会阻止模型发起任意网络请求，或访问项目目录之外的文件。不使用 sandbox 时，Claude Code 采用基于权限的模型，由您批准或拒绝单个工具调用。¹³

2026年5月安全基线。Claude Code v2.1.149 修复了 PowerShell 工作目录权限绕过、多个 PowerShell allow-rule 和 stale-variable 权限分析缺口，以及一个 git-worktree sandbox 写入 allowlist bug：该 bug 会覆盖整个主仓库根目录，而不只是共享的 git 内部文件。⁵³如果您的 harness 允许 PowerShell 或 worktree 隔离 Agent，请将 v2.1.149+ 视为基线，并保持 shell 规则收窄。宽泛的 PowerShell(*) 和全仓库写入例外是编排捷径，不是安全边界。

OpenAI Agents SDK sandbox 锁定（v0.17.0，2026年5月8日）。在 OpenAI 侧，openai-agents-python v0.17.0 收紧了一条并行边界：LocalFile.src 和 LocalDir.src 现在被限制在物化 base_dir 内（应用 manifest 时 SDK 进程的当前工作目录），除非通过 Manifest.extra_path_grants 和 SandboxPathGrant 显式授予来源。⁴¹相对本地源从 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 错误、mountpoint 凭据不进入 sandbox 命令、拒绝相对 sandbox 工作区根目录，以及 Vercel-sandbox 终端状态处理。⁵⁴如果您使用的是 OpenAI 托管或提供商支持的 sandboxes，而不只是 Claude Code hooks，请将 0.17.3 视为本节模式的当前基线。

权限边界

权限系统在多个层级对操作设门：

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

Claude Code v2.1.178 将权限规则从工具级扩展到参数级：Tool(param:value) 会匹配工具的输入参数，* 作为通配符。典型示例是 Agent(model:opus)，这条规则会阻止在特定模型层级上生成 subagents。⁶³从架构上看，这补上了上方四层表格无法表达的缺口：以前只能整体允许或拒绝某个工具，却无法约束它如何被调用。如今，治理策略可以用确定性规则表达“subagents 可以生成，但不能使用 Fable 5 层级”，或“允许 Bash，但不能带这个 flag”，而不是停留在提示层请求。

配套的托管设置 enforceAvailableModels（v2.1.175）会自上而下约束模型选择：它固定 Default 模型，并防止用户或项目级设置扩大托管的 availableModels allowlist。⁶³二者可以组合使用：allowlist 定义该会话中实际存在的层级，参数级规则则约束 subagents 如何从中取用。

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 中编码同样的原则：会销毁状态的命令应默认拒绝，只有显式操作员信号才能解除。

提示注入防御

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 也无法进行更改。

Agent 日志和 Guardrails 也是安全面

2026年5月的两条公告进一步强化了一个模式：Agent 基础设施会产生新的位置，让敏感内容和可执行策略发生泄露或逃逸。GitHub Advisory GHSA-f3jg-756w-gm35 涉及 Gryph Agents 的 payload-filter 问题，在默认日志行为下，敏感工具 payload 内容可能保留在本地 SQLite 日志中。⁴⁵OSV GHSA-wxxx-gvqv-xp7p 涉及 LiteLLM 自定义代码 guardrail 在受管理员保护的代理端点中发生 sandbox 逃逸。⁴⁶

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

Hook 安全

将环境变量插入 header 的 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 完成时运行清理或校验。

这不是可选项。一个在没有您的安全 hooks 的情况下生成 subagent 的 Agent，就是一个能在您的门禁盯着主对话无事发生时，强推到 main、读取凭据文件或运行破坏性命令的 Agent。

成本即架构

成本是架构决策，不是运维后的补充思考。²分为三个层级：

Token 层。系统提示压缩。删除教程式代码示例（模型知道这些 APIs），合并跨文件的重复规则，并用约束替代解释。“拒绝匹配敏感路径的工具调用”与一段15行说明为什么不应读取凭据的解释，发挥的是同样作用。

Agent 层。相比长对话，优先使用新生成实例。自治运行中的每个 story 都获得一个带干净上下文的新 Agent。上下文不会膨胀，因为每个 Agent 都从头开始。用 briefing 替代 memory：模型执行清晰 briefing 的效果，优于在30步累积上下文中摸索。

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

决策框架

何时使用各类机制：

Skills vs Hooks vs Subagents

FAQ

多少 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 响应模拟每种场景，验证两个验证门都能捕获每个已记录的失败模式。一个生产级 deliberation 系统会在 3 层运行 141 个测试：48 个 bash 集成测试、81 个 Python 单元测试，以及 12 个端到端流水线模拟。⁷

deliberation 对延迟有什么影响？

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

CLAUDE.md 文件应该多长？

每个 section 控制在 50 行以内，总文件控制在 150 行以内。长文件会被上下文窗口截断，因此请把最关键的指令放在前面：先写命令和收尾定义，再写风格偏好。²¹

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

这些架构原则（hooks 作为确定性门禁、skills 作为领域专业能力、subagents 作为隔离上下文、文件系统作为记忆）在概念上适用于任何 agentic system。具体实现使用了 Claude Code 的生命周期事件、matcher patterns 和 Agent tool。AGENTS.md 将同样的模式带到 Codex、Cursor、Copilot、Amp 和 Windsurf。²¹ 即便实现细节与工具绑定，harness pattern 本身仍然与工具无关。

快速参考卡

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.

退出码

关键命令

文件位置

更新日志

参考资料