Agent Architecture：构建 AI 驱动的开发工具体系

摘要： Claude Code不是一个能访问文件的聊天框，而是一个可编程运行时，拥有22个生命周期事件，每个事件都可以通过shell脚本挂钩，且模型无法跳过。将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目录和handoff文档共同构成结构化的外部记忆系统。⁶
• 多智能体协商能发现盲区。 单个智能体无法质疑自身的假设。两个拥有不同评估优先级的独立智能体，能捕获quality gates无法解决的结构性缺陷。⁷
• Harness模式即系统本身。 CLAUDE.md、hooks、skills、agents和memory并非各自独立的功能，它们组合成您与模型之间的确定性层，随自动化程度的提升而扩展。

如何使用本指南

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

为什么智能体架构至关重要

Simon Willison 对当前局势的判断围绕一个核心观察：编写代码现在很廉价。⁸ 没错。但其推论是：验证才是真正昂贵的环节。廉价代码缺少验证基础设施，只会大规模制造缺陷。真正值得投入的不是更好的提示词，而是模型周围那套能捕获模型遗漏的系统。

三股力量使智能体架构成为必需：

上下文窗口有限且有损。 每一次文件读取、工具输出和对话轮次都在消耗 token。微软研究院和 Salesforce 对 15 个 LLM 进行了超过 200,000 次模拟对话测试，发现从单轮交互到多轮交互，平均性能下降了 39%。⁹ 这种退化最早在两轮对话后就开始显现，并遵循可预测的曲线：前 30 分钟还能精准地进行多文件编辑，到第 90 分钟就退化为单文件的隧道视野。更大的上下文窗口并不能解决这个问题。同一研究中的”拼接”条件（将完整对话作为单个提示词）在内容完全相同的情况下达到了单轮性能的 95.1%。退化源于轮次边界，而非 token 限制。

模型行为是概率性的，而非确定性的。 告诉 Claude”编辑文件后始终运行 Prettier”，大约 80% 的情况下有效。³ 模型可能会遗忘、优先考虑速度，或者判定改动”太小”而跳过。对于合规、安全和团队标准而言，80% 远远不够。Hooks 保证确定性执行：每次 Edit 或 Write 操作都会触发格式化工具，每一次，无一例外。确定性胜过概率性。

单一视角无法覆盖多维问题。 一个智能体审查某个 API 端点时检查了身份验证、验证了输入清洗并核实了 CORS 头。一切正常。而另一个以渗透测试员身份独立提示的智能体，却发现该端点接受无限制的查询参数，可能通过数据库查询放大触发拒绝服务攻击。⁷ 第一个智能体从未检查这一点，因为其评估框架中没有将查询复杂度视为安全攻击面。这是结构性缺陷，再多的提示词工程也无法弥补。

智能体架构同时解决了这三个问题：hooks 强制执行确定性约束，subagents 管理上下文隔离，多智能体编排提供独立视角。三者共同构成 harness。

Harness 模式

Harness 不是框架，而是一种模式：一组可组合的文件、脚本和约定，用确定性基础设施包裹 AI 编码智能体。其组成部分：

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

指令层： CLAUDE.md 文件和 rules 目录定义了智能体对项目的认知。它们在会话启动时和每次压缩后自动加载，是智能体的长期架构记忆。

扩展层： Skills 提供基于上下文自动激活的领域专业知识。Hooks 提供在每次匹配工具调用时触发的确定性门控。Memory 文件跨会话持久化状态。自定义 agents 提供专用的 subagent 配置。

编排层： 多智能体模式协调独立智能体进行研究、审查和讨论。生成预算防止递归失控。共识验证确保质量。

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

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

## 安全检查
审查代码时，需验证以下要点：

### 输入验证
- 所有用户输入在数据库操作前已完成净化处理
- 使用参数化查询（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中通过相对链接引用这些文件。Claude在skill激活时按需读取这些文件。建议将 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中定义仅在该skill运行期间激活的hooks。这样可以创建特定领域的行为，而不会影响其他会话：²

---
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 hooks自动激活，在每次会话中注入质量约束，无需显式调用。Skill本身是知识，hook则是执行机制。二者结合，形成一个策略层。

常见的Skill错误

描述过于宽泛。 一个 git-rebase-helper skill如果对任何git相关提示都会激活（rebase、merge、cherry-pick，甚至 git status），会在80%的会话中造成上下文污染。解决方法要么是收紧描述，要么添加 disable-model-invocation: true 并要求通过 /skill-name 显式调用。⁴

过多skill争抢预算。 Skill越多，争抢2%上下文预算的描述就越多。如果发现skill未被激活，请通过 /context 检查是否有被排除的skill。与其创建大量模糊的skill，不如精简数量、优化描述。

关键信息埋藏在辅助文件中。 Claude会立即读取SKILL.md，但辅助文件仅在需要时才会访问。如果关键信息放在辅助文件中，Claude可能无法发现。应将核心信息直接放入SKILL.md中。⁴

Hook 架构

Hook 是由 Claude Code 生命周期事件触发的 shell 命令。³ 它们在 LLM 外部以普通脚本形式运行，而非由模型解释的提示词。模型想执行 rm -rf /？一个 10 行的 bash 脚本会将命令与黑名单进行比对，在 shell 接触到命令之前就将其拦截。无论模型是否愿意，hook 都会触发。

可用事件

Claude Code 提供横跨六个类别的 22 个生命周期事件：¹³

退出码语义

退出码决定 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 字段是匹配工具名称的正则表达式：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": {
    "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 之前，先问自己：我需要哪种保障？¹⁴

格式保障确保事后的一致性。PostToolUse hook 在 Write/Edit 操作后运行格式化工具。模型的输出格式无关紧要，因为格式化工具会统一规范一切。

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

安全保障在危险操作执行之前将其拦截。PreToolUse hook 检查 Bash 命令，通过退出码 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

质量保障在关键决策点验证状态。PreToolUse hook 在 git 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 支持三种 hook 类型：¹³

命令 hook（type: "command"）运行 shell 脚本。速度快、行为确定、无 token 开销。

提示词 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
          }
        ]
      }
    ]
  }
}

异步 Hook

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

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

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

使用 dispatcher 替代独立 Hook

七个 hook 同时响应同一事件，各自独立读取 stdin，会引发竞态条件。两个 hook 并发写入同一个 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 输出调试信息。 写入 stderr 的内容会出现在 Claude 的上下文中。
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 中的条目会将该模式呈现出来。¹⁵

自动记忆（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分钟后，尽管存在额外开销，全新上下文方式能产出更高质量的成果。

反模式

只需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 的不必要预加载。¹⁵

Subagent 模式

Subagent 是专门处理复杂任务的独立 Claude 实例。它们以全新上下文启动（不受主对话污染），使用指定工具运行，并以摘要形式返回结果。探索结果不会膨胀主对话上下文，只有结论会返回。⁵

内置 Subagent 类型

创建自定义 Subagent

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

---
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 隔离

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

并行 Subagent

Claude Code 支持最多 10 个并行 subagent。⁵ 可将并行执行用于独立的研究任务：

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

每个 agent 在独立的上下文窗口中运行，查找相关代码并返回摘要。主上下文保持清洁。

递归守卫

若无生成限制，agent 会不断委派给其他 agent，层层嵌套，逐级丢失上下文并消耗 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 个 agent 仍然是”深度 1”。生成预算追踪每个父级当前活跃的子级总数，设定可配置的上限。预算模型直接对应实际失败模式（活跃 agent 总数过多），而非代理指标（嵌套层级过深）。⁷

Agent Teams（研究预览）

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

启用方式：export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Agent Teams 与 subagent 的选择：

多智能体协调

单智能体AI系统存在一个结构性盲点：它们无法质疑自身的假设。⁷ 多智能体协商机制迫使系统在任何决策锁定之前，从多个独立视角进行评估。

最小可行协商

从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个加权维度为每个方案评分：

双门验证架构

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

第一道门：共识验证（PostToolUse hook）。在每个协商智能体完成后立即运行： 1. 阶段必须至少到达RANKING 2. 至少2个智能体已完成（可配置） 3. 共识分数达到任务自适应阈值 4. 如有智能体持异议，须记录其关注点

第二道门：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分，说明存在共享上下文污染而非独立评估。当五个智能体评估一次身份认证重构时，安全风险评分全部落在7.1到7.4之间，以全新的上下文隔离重新运行后，分数分散到了5.8-8.9。

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

少数派视角缺失： 优先级相互冲突的角色（安全分析师和性能工程师）全票通过——这种情况极不正常，因为他们几乎不可能在所有问题上达成一致。

一致性检测器能捕获明显的情况（大约10-15%的协商中智能体收敛过快）。其余85-90%的情况下，共识验证和Pride Check门已提供充分的验证。

协商中不奏效的方案

自由形式辩论轮次。 针对数据库索引讨论进行了三轮文本往返辩论，产生了7,500个token。第一轮：真正的分歧。第二轮：重申立场。第三轮：用不同措辞重复相同论点。结构化维度评分取代了自由形式辩论，成本降低60%，排序质量反而提升。⁷

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

协商成本

每个研究智能体处理约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 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`

完成定义：

## 完成定义
当以下所有条件均通过时，任务才算完成：
1. `ruff check .` 退出码为 0
2. `pytest -v` 退出码为 0，无失败用例
3. `mypy app/ --strict` 退出码为 0
4. 已暂存并提交所有变更文件
5. 提交信息遵循约定格式：`type(scope): description`

按任务组织的章节：

## 编写代码时
- 每次修改文件后运行 `ruff check .`
- 为所有新函数添加类型注解

## 审查代码时
- 检查安全问题：`bandit -r app/`
- 验证测试覆盖率：`pytest --cov=app --cov-fail-under=80`

## 发布时
- 更新 `pyproject.toml` 中的版本号
- 运行完整测试套件：`pytest -v && ruff check . && mypy app/`

升级规则：

## 遇到阻塞时
- 如果测试在 3 次尝试后仍然失败：停止操作，报告失败的测试及完整输出
- 如果缺少依赖：先检查 `requirements.txt`，再询问
- 绝不：通过删除文件解决错误、强制推送、或跳过测试

编写顺序

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

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 是一项开放标准，已被超过 60,000 个项目采用，并获得所有主流 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 个代码仓库的分析表明，模糊性是导致大多数失败的根本原因。²¹

生产环境模式

Quality Loop

所有非琐碎变更必须执行的审查流程：

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

Evidence Gate

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

如果任何一行无法提供证据，则返回精炼步骤。²²

错误处理模式

原子文件写入。 多个智能体同时写入同一状态文件会导致 JSON 损坏。先写入 .tmp 文件，再通过 mv 实现原子替换。操作系统保证同一文件系统上的 mv 操作是原子性的。¹⁷

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

状态损坏恢复。 当状态损坏时，恢复模式从安全默认值重建，而非直接崩溃：¹⁶

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

((VAR++)) Bash 陷阱。 当 VAR 为 0 时，((VAR++)) 返回退出码 1，因为 0++ 的计算结果为 0，Bash 将其视为 false。在启用 set -e 的情况下，这会直接终止脚本。应改用 VAR=$((VAR + 1))。¹⁶

影响范围分类

根据影响范围对每个智能体操作进行分类，并设置相应的审批门槛：²

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

自主运行的任务规范

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

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

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

需警惕的失败模式

一个具体的会话追踪

以下是一次自主运行处理包含 5 个 story 的 PRD 的会话追踪：²

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

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

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

4. 智能体调用 Write 创建文件。 PreToolUse:Write 触发：文件作用域检查。PostToolUse:Write 触发：代码检查、提交跟踪。

5. 智能体完成 story。 Stop 触发。质量门槛检查：智能体是否引用了证据？是否有模糊措辞？diff 中是否包含 TODO 注释？任何检查未通过则返回退出码 2，智能体继续工作。

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

7. 三个代码审查智能体并行启动。 各自独立审查 diff。任一审查者标记为 CRITICAL，该 story 将重新进入队列。

8. Story 通过，加载下一个 story。 此循环对全部 5 个 story 重复执行。

5 个 story 期间触发的 hooks 总数：约 340 次。Hooks 总耗时：约 12 秒。这些开销在一次通宵运行中阻止了三次凭证泄漏、一次破坏性命令和两次不完整的实现。

安全注意事项

沙箱机制

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 tool 生成subagent，您的 PreToolUse 和 PostToolUse hooks会在subagent使用的每个工具上执行。若没有递归hook执行机制，subagent可以绕过安全门禁。SubagentStop 事件允许您在subagent完成时运行清理或验证操作。

这并非可选项。一个在不受安全hooks约束的情况下生成subagent的智能体，等于放任它强制推送到 main、读取凭证文件或执行破坏性命令——而您的安全门禁却只能眼睁睁看着主会话无所作为。

成本即架构

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

Token层级。 系统提示词压缩。移除教程代码示例（模型已掌握API的用法），合并跨文件的重复规则，用约束替代冗长解释。”拒绝匹配敏感路径的工具调用”与15行解释凭证不应被读取的长文有着同样的效果。

智能体层级。 使用全新实例替代长对话。自主运行中的每个story都会获得一个干净上下文的新智能体。上下文永远不会膨胀，因为每个智能体都从零开始。用简报代替记忆：模型执行清晰的简报比翻阅30步累积上下文要高效得多。

架构层级。 对于无状态操作，优先使用CLI而非MCP。claude --print 调用进行一次性评估成本更低，且没有连接开销。当工具需要持久状态或流式传输时，MCP才更合理。

决策框架

各机制的适用场景：

Skills vs Hooks vs Subagents

常见问题

多少hooks算太多？

性能才是约束条件，数量不是。每个hook同步运行，因此hook总执行时间会叠加到每个匹配的工具调用上。用户级和项目级设置中95个hooks在每个hook 200ms 内完成时不会产生明显延迟。需要关注的阈值：如果一个 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吗？

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

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

需要测试成功路径和失败路径。成功：智能体产生有建设性的分歧并达成共识。失败：智能体过快趋同、始终无法达成共识，或超出生成预算。端到端测试使用确定性智能体响应模拟各种场景，验证两道验证门禁捕获每个已记录的故障模式。一个生产级deliberation系统在三个层级运行141项测试：48个 bash 集成测试、81个Python单元测试和12个端到端流水线模拟。⁷

Deliberation的延迟影响如何？

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

CLAUDE.md文件应该多长？

每个章节控制在50行以内，总文件不超过150行。过长的文件会被上下文窗口截断，因此应将最关键的指令前置：命令和闭包定义优先于风格偏好。²¹

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

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

Skills 前置元数据

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

Subagents 定义

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

退出码

常用命令

文件位置

更新日志

参考文献