Agent Harness 架构 2026：图示参考

摘要： Claude Code不是一个能访问文件的聊天框，而是一个可编程运行时，拥有22个生命周期事件，每个事件都可通过模型无法跳过的shell脚本进行hook。将hooks组合成dispatchers，dispatchers组合成skills，skills组合成agents，agents组合成workflows，就能构建出一套自主开发harness——它能强制执行约束、委派任务、跨会话持久化记忆，并编排多智能体协商。本指南涵盖该架构的每一层：从单个hook到10个智能体的共识系统。无需任何框架，全部基于bash和JSON。

Andrej Karpathy为围绕LLM智能体生长出的基础设施创造了一个术语：claws（爪子）。那些让智能体能够触及上下文窗口之外世界的hooks、脚本和编排机制。¹大多数开发者将AI编程智能体视为交互式助手——输入提示词，看它编辑文件，然后继续下一件事。这种认知将生产力上限锁定在你个人能监督的范围内。

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

这种区别至关重要，因为基础设施具有复合效应。一个在bash命令中拦截凭据的hook能保护每个会话、每个智能体、每次自主运行。一个编码了评估标准的skill，无论是你手动调用还是智能体调用，都能一致地执行。一个负责安全审查的智能体，无论你是否在旁监督，都会执行相同的检查。²

核心要点

• Hooks保证执行，提示词则不能。 将hooks用于代码检查、格式化、安全检查，以及任何必须在每次执行时运行的操作，不受模型行为影响。退出码2会阻止操作，退出码1仅发出警告。³
• Skills编码可自动激活的领域专业知识。 description字段决定一切。Claude使用LLM推理（而非关键词匹配）来判断何时应用某个skill。⁴
• Subagents防止上下文膨胀。 为探索和分析提供隔离的上下文窗口，保持主会话的精简。最多可并行运行10个。⁵
• 记忆存储在文件系统中。 文件跨上下文窗口持久化。CLAUDE.md、MEMORY.md、rules目录和交接文档构成了结构化的外部记忆系统。⁶
• 多智能体协商能发现盲点。 单个智能体无法质疑自身的假设。两个拥有不同评估优先级的独立智能体，能捕获质量门禁无法发现的结构性缺陷。⁷
• 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        │
└──────────────────────────────────────────────────────────────┘

指令层(Instruction Layer): CLAUDE.md 文件与规则目录定义了代理对你项目的认知。它们在会话启动时以及每次压缩之后自动加载。这是代理的长期架构记忆。

扩展层(Extension Layer): skills 提供基于上下文自动激活的领域专业知识。hooks 提供在每次匹配工具调用时触发的确定性关卡。memory 文件跨会话持久化状态。自定义代理提供专门的 subagent 配置。

编排层(Orchestration Layer): 多代理模式协调独立代理完成研究、审阅与审议工作。生成预算可防止失控递归。共识验证确保质量。

关键洞察在于:大多数用户完全在核心层中工作,眼睁睁看着上下文膨胀、成本攀升。而高级用户则会配置指令层与扩展层,仅将核心层用于编排与最终决策。²

托管型与自托管型 Harness 的对比(2026年4月)

在2026年初的大部分时间里,”自建 harness”几乎是唯一可行的路径。2026年4月,情况发生了改变。Anthropic 于4月8日发布了Claude Managed Agents 公开测试版:将 harness 循环 + 工具执行 + 沙箱容器 + 状态持久化作为 REST API 提供,按标准 token 费用外加每会话小时 0.08 美元计费。OpenAI 于4月16日更新的 Agents SDK 正式确立了同样的分层理念——将 harness 与计算作为两个独立层次,原生支持沙箱供应商(Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel),并通过快照/恢复机制应对容器丢失。²³²⁴

架构上的分叉已经成为现实:

如何取舍:自托管方案更适合已具备基础设施能力的团队,或是希望完全掌控 skills/hooks、正在深度打磨特定工作流的团队。托管方案则更适合没有专职平台工程师的团队,或是价值交付速度比定制化更重要的场景,以及希望代理运行能够可靠地在笔记本合盖后继续存活——而您又不想自己搭建那套持久化层——的情形。两者并非互斥:您完全可以运行一个自托管 harness,并通过其 REST API 将特定的长耗时任务委托给 Managed Agents。

磁盘上的 Harness 结构

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

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

此结构中的每一个文件都有其存在的意义。~/.claude/ 目录树是适用于所有项目的个人基础设施。每个仓库中的 .claude/ 目录树则是项目专属的,并通过 git 进行共享。两者共同构成了完整的 harness。

Skills 系统

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

何时应构建 Skill

Skills 用于Claude 始终可以调用的知识。斜杠命令则用于您主动触发的操作。当您在两者之间犹豫时,不妨自问:”这件事应该由 Claude 自动应用,还是应该由我来决定何时执行?”

创建 Skill

Skills 可以存放在四个位置,作用范围从宽到窄依次为:⁴

每个 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

## 安全检查
审查代码时,请验证:

### 输入验证
- 所有用户输入在数据库操作前均已净化处理
- 使用参数化查询(SQL中禁止字符串拼接)
- 对渲染的HTML内容进行输出编码

### 身份验证
- 每个受保护端点均对会话令牌进行校验
- 数据变更前执行权限检查
- 源代码中不得包含硬编码凭证或API密钥

Frontmatter 字段参考

description字段至关重要

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

糟糕的描述:

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描述共享一个动态缩放的上下文预算,其规模为上下文窗口的2%,回退值为16,000个字符。⁴如果您有大量skill,请保持每条描述简洁。可通过SLASH_COMMAND_TOOL_CHAR_BUDGET环境变量覆盖该预算,¹¹但更好的做法是让描述更简短、更精准。会话期间可运行/context检查是否有skill被排除在外。

辅助文件与组织结构

Skill可引用同一目录下的其他文件:

~/.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共享Skill

项目skill(仓库根目录下的.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。无需安装,无需配置。这是在团队中标准化专业知识最行之有效的方式。

Skill作为提示库

除了单一用途的skill之外,目录结构本身也可作为一个组织良好的提示库:

~/.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会根据上下文自动从中提取内容。初级开发者无需主动询问,也能获得资深级别的指导。

Skill与Hooks组合使用

Skill可在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'"
---

哲学类skill通过SessionStart hook自动激活,无需显式调用即可将质量约束注入每个会话。skill本身是知识,hook则是强制执行。二者结合,构成了一个策略层。

常见的Skill使用误区

描述过于宽泛。一个git-rebase-helperskill如果对任何与git相关的提示(变基、合并、cherry-pick,甚至git status)都响应激活,会在80%的会话中污染上下文。解决办法是收紧描述,或添加disable-model-invocation: true并要求通过/skill-name显式调用。⁴

过多skill争抢预算。skill越多,意味着越多描述在争夺那2%的上下文预算。如果您发现某些skill未能激活,请通过/context检查被排除的skill。优先选择少量高质量描述的skill,而非大量含糊不清的skill。

关键信息埋没于辅助文件中。Claude会立即读取SKILL.md,但只在需要时才访问辅助文件。如果关键信息藏在辅助文件里,Claude可能找不到。请将核心信息直接写入SKILL.md。⁴

Hook架构

Hook是由Claude Code生命周期事件触发的shell命令。³它们作为普通脚本在LLM之外运行，而不是由模型解释的提示词。模型想执行rm -rf /？一个10行的bash脚本会对照黑名单检查该命令，在shell看到之前就将其拒绝。无论模型是否愿意，hook都会触发。

可用事件

Claude Code在七个类别中暴露了26+个生命周期事件（事件列表随版本发布而增加——请查看速查表获取当前完整表格）：¹³

退出码语义

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

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

Hook配置

Hook存放在settings文件中。项目级别（.claude/settings.json）用于共享hook。用户级别（~/.claude/settings.json）用于个人hook：

{
  "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字段是匹配工具名称的正则表达式：Bash、Write、Edit、Read、Glob、Grep、Agent，或用*匹配所有工具。对于UserPromptSubmit等没有工具的事件，使用""（空字符串）。

Hook输入/输出协议

Hook通过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 hook可以输出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 hook在每次文件变更后运行格式化工具。模型的输出无关紧要，因为格式化工具会将一切规范化。

{
  "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 hook检查命令，并用退出码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 hook运行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类型：¹³

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

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

Agent hook（type: "agent"）生成一个拥有工具访问权限（Read、Grep、Glob）的subagent用于多轮验证。当检查需要检视实际文件或测试输出时使用：

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

HTTP hook（type: "http"）将事件的JSON输入作为POST请求发送到URL，并接收返回的JSON。适用于webhook、外部通知服务或基于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
          }
        ]
      }
    ]
  }
}

异步Hook

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

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

异步适用于通知、遥测和备份。切勿对格式化、验证或任何必须在下一个动作之前完成的操作使用异步。

用dispatcher取代独立hook

七个hook全部在同一事件上触发、各自独立读取stdin，会产生竞争条件。两个hook并发写入同一JSON状态文件会截断JSON。每一个解析该文件的下游hook都会崩溃。²

修复方法：每个事件配一个dispatcher，从缓存的stdin按顺序运行hook：

#!/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

调试Hook

调试静默失败hook的五种技巧：¹⁴

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. 保持hook快速。Hook同步运行。所有hook应控制在2秒以内，理想情况下低于500毫秒。

内存与上下文

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

多轮崩溃的三种机制

MSR/Salesforce的研究识别出三种独立机制，每一种都需要采取不同的干预措施：⁹

策略1：将文件系统作为内存

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

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

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

Auto Memory（v2.1.32+）： Claude Code自动记录并回忆项目上下文。在您工作时，Claude会将观察结果写入~/.claude/projects/{project-path}/memory/MEMORY.md。Auto memory会在会话开始时将前200行加载到您的系统提示中。请保持简洁，并链接到独立的主题文件以记录详细笔记。⁶

策略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

策略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循环）

对于超过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

每次迭代采用全新上下文的方式，以orient步骤（读取状态文件、扫描git历史）所产生的15-20%开销，换来每次迭代的完整认知资源。¹⁶ 成本-收益的考量是：对于60分钟以内的会话，单次对话效率更高。超过90分钟时，全新上下文方式尽管有开销，但能产出更高质量的成果。

反模式

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

在上下文中保留冗长的错误输出。 调试完一个bug后，您的上下文中保留着40多个失败迭代的堆栈跟踪。在修复bug之后执行一次/compact即可释放这些无效负担。

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

子智能体模式

子智能体是专门的Claude实例，能够独立处理复杂任务。它们从干净的上下文开始（不受主对话的污染），使用指定的工具运行，并以摘要形式返回结果。探索过程的中间结果不会让主对话膨胀，只有结论会返回。⁵

内置子智能体类型

创建自定义子智能体

在.claude/agents/（项目级）或~/.claude/agents/（个人级）中定义子智能体：

---
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.

子智能体配置字段

Worktree 隔离

子智能体可以在临时 git worktree 中运行，提供仓库的完整隔离副本：⁵

---
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最多支持 10 个并行子智能体。⁵ 对独立的研究任务使用并行执行：

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

每个智能体在自己的上下文窗口中运行，查找相关代码并返回摘要。主上下文保持整洁。

递归防护

如果没有生成限制，智能体会委派给智能体，智能体又继续委派给智能体，每一层都会丢失上下文并消耗 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 个智能体仍然是”深度 1”。生成预算跟踪每个父级下活跃子级的总数，上限是可配置的最大值。预算模型映射到实际的故障模式（智能体总数过多），而不是代理指标（嵌套层级过多）。⁷

Agent Teams（研究预览）

Agent Teams 协调多个Claude Code实例，这些实例独立工作，通过共享的邮箱和任务列表进行通信，并且可以相互质疑各自的发现：⁵

启用方式：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

何时使用 Agent Teams 而不是子智能体：

多智能体编排

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

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

辩论并非万能良方：M3MAD-Bench研究集群（2026年初）发现，多智能体辩论会进入平台期，并且可能被误导性共识所颠覆——当其他智能体自信地断言错误答案时，有效论点反而会落败。²⁶Tool-MAD通过为每个智能体提供异构工具访问权限，并在裁决阶段使用忠实度/相关性评分来改善这一问题。如果您正在构建辩论式编排，应投资于（a）每个智能体的工具异构性和（b）定量裁决评分，而不是假设智能体越多答案就越好。

最小可行审议

从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：智能体查看所有研究发现并生成替代方案。Debate智能体识别冲突。Synthesis智能体整合不相矛盾的发现。

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

双关卡验证架构

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

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

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

在不同生命周期节点设置两个hook，契合失败实际发生的规律：有些是瞬时的（评分不佳），有些是渐进的（多样性不足、异议记录缺失）。⁷

为何一致同意很危险

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关卡提供了充分的验证。

审议中行不通的做法

自由形式的辩论回合。针对数据库索引讨论进行三轮往复文本辩论，产出了7,500 tokens的辩论内容。第一轮：真实的分歧。第二轮：重申立场。第三轮：用不同措辞表达相同的论点。结构化的维度评分取代了自由形式辩论，在提升排名质量的同时将成本降低了60%。⁷

单一验证关卡。最初的实现只在会话结束时运行一个验证hook。某个智能体以0.52的共识分数（低于阈值）完成审议后，在会话结束hook标记失败之前，又继续处理了20分钟的无关任务。拆分为两个关卡（一个在任务完成时，一个在会话结束时）后，能在不同生命周期节点捕获相同的问题。⁷

审议的成本

每个研究智能体处理约5,000 tokens的上下文，并生成2,000-3,000 tokens的发现。3个智能体即增加15,000-24,000 tokens每次决策。10个智能体约需50,000-80,000 tokens。⁷

按当前Opus定价计算，3智能体审议成本约为$0.68-0.90。10智能体审议成本为$2.25-3.00。系统对约10%的决策触发审议，因此分摊到所有决策的成本为每次会话$0.23-0.30。是否值得，取决于一个错误决策的代价。

何时需要审议

CLAUDE.md设计

CLAUDE.md是AI智能体的操作策略，而非面向人类的README。²¹智能体不需要理解您为何使用约定式提交，它只需要知道要运行的确切命令以及”完成”的标准。

优先级层次结构

规则文件会自动加载，在不扰乱CLAUDE.md的前提下提供结构化上下文。⁶

哪些内容会被忽略

以下模式在智能体行为中不会产生任何可观察的变化：²¹

没有命令的散文段落。“我们重视整洁、经过充分测试的代码”是文档，不是操作指令。智能体读完之后照样会编写没有测试的代码，因为其中没有可执行的指令。

含糊不清的指令。“处理数据库迁移时要小心”不算约束。”应用迁移前运行alembic check。如果缺少降级路径则中止。”才算。

相互矛盾的优先级。“快速行动并尽快发布”加上”确保全面的测试覆盖率”加上”保持运行时间在5分钟以内”加上”每次提交前运行完整的集成测试”。智能体无法同时满足这四项要求，最终默认跳过验证。²¹

没有强制执行机制的风格指南。“遵循Google Python Style Guide”却没有配套的ruff check --select D，智能体就无从验证合规性。

哪些做法行之有效

命令优先的指令：

## 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. 构建与测试命令（智能体需要这些才能做任何有用的事情）
2. 完成定义（防止虚假完成）
3. 升级处理规则（防止破坏性的变通做法）
4. 按任务组织的章节（减少无关指令的解析）
5. 目录作用域划分（单体仓库：保持服务指令的隔离性）

在前四项生效之前，不必操心风格偏好。

文件导入

在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中的模式（命令优先、闭合定义、任务组织）适用于任何工具的指令文件。不要维护多套会逐渐偏离彼此的并行指令集。只写一份权威来源，然后镜像。

测试您的指令

验证智能体是否真的读取并遵循了您的指令：

# 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?"

试金石：让智能体解释您的构建命令。如果它无法逐字复述，说明指令要么过于冗长（内容被挤出上下文），要么过于含糊（智能体无法提取可执行的指令），要么根本没有被发现。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之间。推荐作为编码和智能体工作负载的默认选项。在长时间运行的subagent上，xhigh以低于比例增长的token成本显著优于high。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”的护栏规则,可以精简掉那些现在已由模型原生覆盖的条目。

质量循环

一个针对所有非琐碎变更的强制审查流程：

1. 实现 - 编写代码
2. 审查 - 逐行重读。捕捉拼写错误、逻辑错误、不清晰的部分
3. 评估 - 运行evidence gate。检查模式、边界情况、测试覆盖率
4. 精炼 - 修复每一个问题。绝不推迟到”以后”
5. 拉远视角 - 检查集成点、导入、相邻代码是否存在回归
6. 重复 - 如果任何evidence gate标准失败，返回第4步
7. 汇报 - 列出变更内容、如何验证、引用具体证据

Evidence Gate

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

如果您无法为任何一行提供证据，请返回精炼阶段。²²

错误处理模式

原子文件写入。 多个agent同时写入同一状态文件会破坏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可以继续处理下一个任务，而您则在手机上审查上一个任务。²

自主运行的任务规范

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

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个story的PRD的自主运行会话追踪：²

1. SessionStart触发。 dispatcher注入：当前日期、项目检测、哲学约束、成本追踪初始化。五个hook，总计180ms。

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

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

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

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

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

7. 三个代码审查agent并行spawn。 每个独立审查diff。如果任何审查者标记CRITICAL,该story重新回到队列。

8. story通过。加载下一个story。 循环重复5个story。

5个story中总共触发hook约340次。hook中总耗时约12秒。这部分开销在一次通宵运行中阻止了三次凭据泄露、一次破坏性命令和两次不完整实现。

案例研究：通宵PRD处理

一个生产级harness在8次通宵会话中处理了12个PRD（47个story）。指标对比前4个PRD（极简harness：仅CLAUDE.md）与后8个（完整harness：hooks、skills、质量关卡、多agent审查）。

那两次凭据泄露需要轮换API密钥并审计下游服务：大约4小时的事件响应。而预防等价问题的harness开销是每个story 2.4秒的bash执行。错误完成率从35%降至4%,原因是Stop hook在允许agent汇报完成之前独立运行了测试。

安全考量

可信智能体的五项原则（Anthropic，2026年4月）

Anthropic于2026年4月9日发布了智能体可信度的正式框架。²⁷ 这五项原则与本指南中的Evidence Gate思想相互呼应，并在此基础上有所拓展：

Anthropic还将MCP捐赠给Linux Foundation的Agentic AI Foundation，与AGENTS.md（现已与OpenAI、Google、Cursor、Factory、Sourcegraph共同维护）一同纳入治理。智能体互操作标准如今已实现厂商中立。²⁷

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

沙箱

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

权限边界

权限系统在多个层级对操作进行把关：

提示注入防御

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即便其提示遭到入侵，也无法做出任何更改。

Hook安全

将环境变量插值到请求头中的HTTP hooks必须显式声明allowedEnvVars列表，以防止任意环境变量被外泄：¹³

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

人类与智能体的职责划分

智能体架构中的安全工作要求人类与智能体之间有清晰的职责划分：¹⁷

规律在于：人类掌管那些需要组织背景、伦理判断或战略方向的决策；智能体掌管那些需要在庞大可能性空间中进行计算搜索的决策。hooks负责守住边界。

递归hook强制执行

hooks对subagent的行为同样会触发。¹³ 如果Claude通过Agent工具派生出subagent，那么您的PreToolUse与PostToolUse hooks会针对该subagent使用的每一个工具执行。若没有递归hook强制执行，subagent便有可能绕过您的安全防线。SubagentStop事件则可让您在subagent完成时执行清理或校验。

这并非可选项。一个在派生subagent时不带上您安全hooks的智能体，等于放任subagent去强推main分支、读取凭证文件或运行破坏性命令，而您的防线却只盯着主对话束手无策。

成本即架构

成本是一项架构决策，而非事后的运维琐事。² 共分三个层级：

Token层级。 系统提示词压缩。删除教程式的代码示例（模型本就熟悉API），合并跨文件的重复规则，并将解释替换为约束。”拒绝匹配敏感路径的工具调用”所起的作用，与一段关于为何不应读取凭证的15行解释别无二致。

智能体层级。 以全新派生取代漫长对话。在自主运行中，每个story都会获得一个上下文干净的全新agent。上下文不会臃肿膨胀，因为每个agent都从零开始。简报优于记忆：模型执行一份清晰简报的效果，要好于在30步累积的上下文中艰难穿行。

架构层级。 当操作无状态时，CLI优先于MCP。一次claude --print调用足以完成一次性评估，成本更低，也无需建立连接。MCP适用于工具需要持久状态或流式传输的场景。

决策框架

各机制的适用场景：

Skills、Hooks与Subagents的对比

常见问题

多少个hooks算太多？

约束在于性能而非数量。每个hook都同步运行，因此hook执行的总时长会累加到每次匹配的tool调用中。当每个hook在200ms内完成时，跨用户级和项目级settings分布的95个hooks运行起来不会有明显延迟。需要警惕的临界点是：如果某个PostToolUse hook给每次文件编辑增加超过500ms，会话就会显得迟滞。在部署前用time对您的hooks进行性能分析。¹⁴

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

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

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

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

每个决策都需要deliberation吗？

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

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

要同时测试成功路径和失败路径。成功：agents富有成效地产生分歧并达成共识。失败：agents过快收敛、永不收敛，或超出生成预算。端到端测试用确定性的agent响应模拟每种场景，验证两道validation gates都能捕获每一种已记录的失败模式。一个生产级deliberation系统跨三层运行141个测试：48个bash集成测试、81个Python单元测试，以及12个端到端流水线模拟。⁷

deliberation对延迟的影响有多大？

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

CLAUDE.md文件应该多长？

每个章节保持在50行以内，整个文件控制在150行以内。过长的文件会被上下文窗口截断，因此请把最关键的指令放在前面：命令和closure定义应排在风格偏好之前。²¹

这能与Claude Code之外的其他工具配合使用吗？

架构原则（hooks作为确定性gates、skills作为领域专长、subagents作为隔离上下文、文件系统作为memory）在概念上适用于任何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前置元数据

---
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.

退出码

关键命令

文件位置

更新日志

参考文献