Agent 架构：构建 AI 驱动的开发框架

TL;DR： Claude Code 不是带有文件访问能力的聊天框。它是一个可编程运行时，包含 29 个有文档记录的生命周期事件，每个事件都可通过模型无法绕过的 shell 脚本进行挂钩。将 hooks 堆叠成 dispatcher，dispatcher 堆叠成 skills，skills 堆叠成 agents，agents 堆叠成工作流，您就得到了一个自主的开发 harness，它能强制执行约束、委派工作、跨会话持久化记忆，并编排多 agent 协商。本指南涵盖该堆栈的每一层：从单个 hook 到 10-agent 共识系统。无需任何框架。全部使用 bash 和 JSON。

Andrej Karpathy 为围绕 LLM agent 生长出来的东西创造了一个术语：claws（爪子）。这些 hooks、脚本和编排让 agent 得以抓住其上下文窗口之外的世界。¹ 大多数开发者把 AI 编码 agent 当作交互式助手。他们输入一段提示，看着它编辑一个文件，然后继续下一件事。这种思路把生产力上限锁定在您个人能监督的范围内。

基础设施的思维模型则截然不同：AI 编码 agent 是一个带有 LLM 内核的可编程运行时。模型采取的每一个动作都会经过您所控制的 hooks。您定义的是策略，而不是提示。模型在您的基础设施中运作，正如 web 服务器在 nginx 规则中运作一样。您不会坐在 nginx 前面手动输入请求。您配置它、部署它、监控它。

这种区别很重要，因为基础设施具有复利效应。一个在 bash 命令中拦截凭据的 hook，会保护每一次会话、每一个 agent、每一次自主运行。一个编码您评估准则的 skill，无论是您自己调用还是 agent 调用，都会被一致地应用。一个为代码做安全审查的 agent，无论您是否在场观看，都会执行同样的检查。²

核心要点

• Hooks 保证执行；提示不能。 对于代码检查、格式化、安全检查以及任何必须每次都运行、不受模型行为影响的事项，请使用 hooks。退出码 2 会阻止动作。退出码 1 仅给出警告。³
• Skills 编码可自动激活的领域专长。 description 字段决定一切。Claude 使用 LLM 推理（而非关键字匹配）来决定何时应用某个 skill。⁴
• Subagents 防止上下文膨胀。 用于探索和分析的独立上下文窗口能让主会话保持精简。让相互独立的 subagents 并行运行，当工作单元需要持续协调时，则使用 agent 团队。⁵
• 记忆存在于文件系统中。 文件可跨上下文窗口持久存在。CLAUDE.md、MEMORY.md、规则目录以及交接文档共同构成了一个结构化的外部记忆系统。⁶
• 多 agent 协商能捕获盲区。 单个 agent 无法挑战自己的假设。两个具有不同评估优先级的独立 agent 能够发现质量门无法解决的结构性失败。⁷
• harness 模式即是系统。 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。

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 文件在会话之间持久化状态。自定义 agents 提供专门的 subagent 配置。

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

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

托管 vs. 自托管 Harness（2026 年 4 月）

整个 2026 年初，”自建 harness”几乎是唯一可行的路径。2026 年 4 月，这一局面发生了改变。Anthropic 推出了 Claude Managed Agents 公测版（4 月 8 日）：将 harness 循环 + 工具执行 + 沙箱容器 + 状态持久化打包为一个 REST API，按标准 token 计费，外加每会话小时 $0.08。OpenAI 的 Agents SDK 更新（4 月 16 日）正式化了同样的分层方案——将 harness 和计算作为独立的层，原生支持沙箱提供商（Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel），并通过快照/重新水化（snapshot/rehydrate）应对容器丢失。²³²⁴

OpenAI 侧更深入的 SDK 接口落地于 openai-agents Python v0.14.0（2026 年 4 月 15 日发布；4 月 16 日宣布）：Agent 的 SandboxAgent 子类，带有 default_manifest、沙箱指令和 capabilities；描述全新工作区契约的 Manifest（文件、目录、本地文件、Git 仓库、环境变量、用户、挂载点）；用于按运行配置沙箱客户端、实时会话注入、manifest 覆盖、快照和物化并发限制的 SandboxRunConfig。内置 capabilities 涵盖 shell 访问、文件系统编辑、图像检查、skills、沙箱内存和压缩。沙箱内存在多次运行之间持久化提取的经验，并以渐进方式披露；工作区支持本地文件、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）。³⁰

架构上的分叉如今已成现实：

何时选择哪种： 自托管仍然适合已经具备基础设施实力的团队、希望完全控制 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 前置元数据的 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

前置元数据参考

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%，回退值为 8,000 个字符。⁴ 如果您拥有大量 skills，请保持每个描述简洁，并将关键用例放在前面。您可以通过 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量覆盖该预算，¹¹ 但更好的做法是编写更短、更精确的描述。在会话期间运行 /context 可检查是否有 skills 被排除在外。

支持文件与组织结构

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

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

通过相对链接从 SKILL.md 引用它们。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 可在前置元数据中定义自己的 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 相关的提示（变基、合并、cherry-pick，甚至 git status）下都激活的 git-rebase-helper skill 会污染 80% 会话的上下文。修复方法是收紧描述，或添加 disable-model-invocation: true 并要求显式调用 /skill-name。⁴

过多 skills 争夺预算。 Skills 越多，争夺 1% 上下文预算的描述就越多。如果您发现 skills 没有激活，请通过 /context 检查被排除的项。优先选择数量较少、描述清晰的 skills，而不是大量含糊不清的 skills。

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

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

基于 claude-agent-sdk-python v0.1.77+ 构建的自托管 harnesses 应使用 ClaudeAgentOptions 上的 skills 选项来声明可用的 skills，而不是在 allowed_tools 中使用旧式的 "Skill" 值。³⁷ "Skill" 简写形式已被弃用，专用选项为 Claude Code 提供了关于哪些 skills 可用的更结构化信息。v0.1.77 中捆绑的 CLI 是 v2.1.133。

Hook 架构

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

可用事件

截至本指南更新时，Claude Code在八个类别中公开了 29 个有文档记录的生命周期事件。事件列表会随版本发布而增加，因此请将参考文档视为权威来源，并在为生产环境配置 hook 之前查看速查表以获取当前完整表格：¹³

退出码语义

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

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

Hook 配置

Hook 存放于设置文件中。项目级（.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 字段用于过滤事件特定值。对于工具事件，它会匹配 tool_name 值，例如 Bash、Edit、Write、Read、Glob、Grep，类似 mcp__server__tool 的MCP工具名称，或 * 表示所有工具。简单名称和以 | 分隔的列表为精确匹配；包含其他字符的值则被视为JavaScript正则表达式。某些事件不支持 matcher，配置后始终触发。¹³

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 成本。

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

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

Agent hook（type: "agent"）生成具有工具访问权限（Read、Grep、Glob）的 subagent 进行多轮验证。它们处于实验阶段；生产门控请优先使用 command hook，仅在确实需要检查实际文件或测试输出时保留 agent hook：

{
  "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
}

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

调度器优于独立 Hook

七个 hook 都在同一事件上触发，每个独立读取 stdin，会产生竞态条件。两个 hook 同时写入同一JSON状态文件将截断JSON。下游每个解析该文件的 hook 都会失败。²

修复方法：每个事件使用一个调度器，从缓存的 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（exit 1、3 等）仅在详细模式（Ctrl+O）下显示。
3. 留意 jq 失败。 错误的JSON路径会静默返回 null。针对真实工具输入测试 jq 表达式。
4. 验证退出码。 使用 exit 1 的 PreToolUse hook 看似有效，实际上零强制力。
5. 保持 hook 快速。 Hook 同步运行。所有 hook 应保持在 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 等）会从与助手消息和工具结果相同的迭代器中产出。这与TypeScript SDK的 includeHookEvents 选项一致；同一版本中捆绑的CLI升级到了 v2.1.129。

当你的 harness 已经位于Python中，并且你希望 hook 信号与模型输出位于相同的控制流中时，事件流模式是合适的选择。Shell 脚本 hook 契约（退出码、stdin JSON、调度器）对于组合多个工具、在Claude Code和 Codex 间共享 hook 或需要退出码语义进行阻止的 harness 而言，仍然是正确的答案。

工作量与会话来源（2026 年 5 月 7-8 日）

Claude Code v2.1.132 和 v2.1.133 中的两项新增功能为 hook 和子进程提供了关于其执行上下文的更好信号：³⁸³⁹

• hook 输入中的 effort.level。 Hook 现在在携带 tool_input 和 session_id 的同一输入上接收 effort.level JSON字段。同一值作为 $CLAUDE_EFFORT 环境变量导出，因此 Bash 命令无需解析JSON即可读取。利用它根据工作量层级调整 hook 成本：在 low 时跳过昂贵的验证，在 xhigh 或 max 时运行完整的安全门控。
• Bash 子进程上的 CLAUDE_CODE_SESSION_ID 环境变量。 Bash 工具子进程现在可以看到 hook 看到的相同 session_id 值，以 CLAUDE_CODE_SESSION_ID 形式公开。这弥补了那些记录每会话状态、此前无法将子进程事件与 hook 事件关联的工具的来源缺口。

两个信号无需更改代码即可使用；忽略新字段的现有 hook 仍可继续工作。

内存与上下文

每次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条目会浮现出该模式。¹⁵

自动内存(v2.1.32+): Claude Code会自动记录并调用项目上下文。在您工作时,Claude将观察结果写入~/.claude/projects/{project-path}/memory/MEMORY.md。自动内存在会话开始时将前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(继续)启动新会话或阅读交接文档可直接进入实现阶段。¹⁵

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

每次迭代采用全新上下文的方法,以15-20%的开销(用于定向步骤,即读取状态文件、扫描git历史)换取每次迭代获得完整的认知资源。¹⁶ 成本效益计算如下:对于不到60分钟的会话,单一对话效率更高。超过90分钟后,尽管存在开销,全新上下文方法仍能产生更高质量的输出。

策略5:托管式内存管理(Dreaming)

Anthropic的Claude Managed Agents于2026年5月6日将Dreaming作为研究预览版推出。³⁵ 据Anthropic所述:”Dreaming是一个定时进程,会审查您的智能体会话和内存存储,提取模式,并管理内存,使您的智能体随着时间推移不断改进。”³⁵

Dreaming在会话之间的后台运行,不在关键路径上。它是对文件系统即内存模式的补充而非替代:您的MEMORY.md文件仍然是承载性的核心;Dreaming则将精选的内存条目写入Managed Agents内存存储,智能体会在会话开始时读取该存储。这两种模式可以共存于混合了自托管文件系统状态与托管侧管理的harness中。

Dreaming处于研究预览阶段,因此行为可能会发生变化。上文记录的会话交接和CLAUDE.md模式仍然是自托管harness的权威内存机制。

反模式

只需要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 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 隔离至关重要。

并行子代理

对于不需要相互协调的独立研究任务，使用并行子代理：⁵

> 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月）： 谷歌于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 智能体的操作策略,而非给人类阅读的 README。²¹ 智能体不需要理解您为何使用约定式提交,它需要知道运行的确切命令以及”完成”的标准是什么。

优先级层次结构

规则文件会自动加载,在不让 CLAUDE.md 变得臃肿的前提下提供结构化上下文。⁶

哪些内容会被忽略

以下模式可靠地不会对智能体行为产生任何可观察的改变:²¹

没有命令的散文段落。“我们重视整洁、经过良好测试的代码”是文档,而非操作指令。智能体读完后会继续编写没有测试的代码,因为其中没有可执行的指令。

含糊的指令。“对数据库迁移要小心”不是约束。”在应用迁移之前运行 alembic check。如果缺少回滚路径则中止。”才是约束。

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

没有强制执行机制的风格指南。“遵循 Google Python 风格指南”如果没有 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. 目录范围限定(monorepo:保持服务指令彼此隔离)

在前四项发挥作用之前,先跳过风格偏好。

文件导入

在 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 工作流。³³³⁴

实际的对应关系:

重要区别:Claude subagents 可以根据描述自动被选中,而 Codex 目前将 subagent 工作流记录为显式调用。这使得 skills 和 hooks 成为 Codex 中常驻 harness 行为的合理默认选择;subagents 则用于有意为之的并行工作、审查和探索。

测试您的指令

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

# 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 层的防护；精简提示词中”如果工具失败，重试三次”这类脚手架。
• xhigh 工作量级（仅限 Opus-4.7）： 介于 high 和 max 之间。推荐作为编码和 agentic 工作负载的默认值。在长时间运行的 subagent 上，xhigh 显著优于 high，且 token 成本以低于线性比例增长。max 仍然是单次困难推理的正确选择；xhigh 更适合持续性任务。
• token 预算上限： 通过 output_config.task_budget（beta header task-budgets-2026-03-13）按每次 agent 运行进行配置。模型可以看到正在倒数的预算，并优雅地将工作范围控制在预算内，而不是意外地耗尽资源。适用于希望在不牺牲短提示词质量的前提下，让 agentic 循环具有可预测的 token 开销的场景。
• 隐式需求感知： 首个通过”隐式需求”测试的 Claude 模型——即识别用户字面请求与其实际需要之间的差距。这使得 CLAUDE.md 中的”澄清规则”部分变得不那么必要。如果您的 CLAUDE.md 有 200 行”当用户询问 Y 时也考虑 X”这类护栏，可以裁剪那些现在已被原生覆盖的内容。

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

Claude Code v2.1.133 新增了四项管理员级别的设置，对生产 harness 来说值得关注：³⁹

需要向用户提示的重点是 worktree.baseRef 的回退：依赖 v2.1.128-v2.1.132 行为（worktree 从本地 HEAD 创建分支）的 agent 将无法在新 worktree 中访问未推送的工作，除非显式选择恢复该行为。

质量循环

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

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

Evidence Gate

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

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

错误处理模式

原子化文件写入。 多个 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 并行启动。 每个独立审查 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 基金会下属的 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 的智能体，意味着它可以在您的门禁仅盯着主对话的情况下，强制推送到 main、读取凭据文件，或运行破坏性命令。

成本即架构

成本是一项架构决策，而非事后运维问题。² 分为三个层面：

Token 层面。 系统提示压缩。删除教程式代码示例（模型本就熟悉这些 API），合并跨文件的重复规则，并以约束取代解释。”拒绝匹配敏感路径的工具调用”与一段 15 行的”为何不应读取凭据”的解释做的是同一件事。

Agent 层面。 用全新派生取代漫长对话。在自主运行中，每个故事都会获得一个全新的、上下文干净的 agent。上下文不会膨胀，因为每个 agent 都从头开始。以简报取代记忆：模型执行清晰简报的效果，远胜于浏览 30 步累积下来的上下文。

架构层面。 当操作是无状态的，应优先采用 CLI 而非 MCP。一次 claude --print 调用用于一次性评估，成本更低，且不引入连接开销。当工具需要持久状态或流式处理时，MCP 才有意义。

决策框架

何时使用各项机制：

Skills、Hooks 与 Subagents 对比

常见问题

多少个hook算太多?

约束在于性能,而非数量。每个hook都是同步运行的,因此hook的总执行时间会累加到每次匹配的工具调用上。当每个hook在200毫秒内完成时,跨用户级和项目级settings分布的95个hook运行起来不会有明显延迟。需要警惕的阈值是:如果某个PostToolUse hook给每次文件编辑增加超过500毫秒,会话就会显得迟缓。部署前请用time对您的hook进行性能分析。¹⁴

hook能阻止Claude Code运行命令吗?

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

hook配置文件应放在哪里?

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

每个决策都需要deliberation吗?

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

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

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

deliberation对延迟的影响如何?

3个agent的deliberation会增加30-60秒的实际耗时(agent通过Agent tool顺序运行)。10个agent的deliberation会增加2-4分钟。consensus和pride check hook各自的运行时间均在200毫秒以内。主要瓶颈是每个agent的LLM推理时间,而非编排开销。⁷

CLAUDE.md文件应该多长?

每个章节保持在50行以内,整个文件保持在150行以内。过长的文件会被上下文窗口截断,因此请将最关键的指令前置:命令和closure定义应放在样式偏好之前。²¹

这套方法能与Claude Code之外的工具一起使用吗?

架构原则(hook作为确定性gate、skill作为领域专长、subagent作为隔离上下文、文件系统作为memory)在概念上适用于任何agent化系统。具体实现使用了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.

退出码

关键命令

文件位置

更新日志

参考文献