LLM之Agent（五十七）｜Claude Code 智能体循环：从入门到精通的实战指南

开场

你还在把 Claude Code 当高级版 ChatGPT 用吗？

如果是，你可能只发挥了它 10% 的功力。

2026 年 6 月的最新数据显示，Claude Code 每天在全球产生约 13.5 万次 GitHub 提交，占公开代码库的 4%。Anthropic 自家 90% 的代码已经是 AI 写的。这个数字在 13 个月内增长了 42,896 倍。

这不是靠"写个好 prompt"就能做到的。

真正的高效使用者，都掌握了一套五层架构的工程化方法。今天这篇文章，我会把这套方法完整拆解给你 ------ 从底层循环机制，到权限模型、Hook 系统、Skills 构建、MCP 接入，再到千级智能体编排。

读完本文，你将获得：

• 理解 Claude Code 的"智能体循环"底层原理
• 掌握五层配置体系的优先级规则
• 学会用 Hooks 实现确定性自动化（而非依赖模型"听话"）
• 构建自己的 Skills 来封装团队最佳实践
• 通过 MCP 连接外部系统
• 用子智能体和动态工作流实现大规模任务编排

第一层：核心循环 ------ Claude Code 的真正大脑

1.1 这不是聊天，这是读取-评估-执行循环

很多人误解 Claude Code 的本质。它不是一个"带终端功能的聊天界面"，而是一个持续运行的智能体循环。

每一轮循环包含 8 个精确步骤：

步骤 1：上下文组装

系统从多个来源组装上下文窗口：完整对话历史、系统提示（含注入的 CLAUDE.md 内容）、Skills 的名称和描述条目、以及 Hooks 提供的额外上下文。

步骤 2：上下文压缩（如需要）

当上下文接近填满时（标准模型 20 万 token，Opus 4.6 可达 100 万 token），压缩管道自动触发：

• 预算削减（修剪旧工具结果）
• 剪切（移除大段工具输出）
• 微压缩（单轮摘要）
• 上下文折叠（压缩旧轮次）
• 自动压缩（全对话摘要，在约 95% 容量时触发）

步骤 3：模型调用

组装好的上下文发送给模型（默认 Opus 4.8、Sonnet 4.6 或 Haiku 4.5）。模型返回文本和/或工具调用。

步骤 4：工具调度与流式执行

当模型返回工具调用时，运行时并行调度。自 v2.1.154 起，流式工具执行始终启用 ------ 结果在工具调用完成前就开始回流。

步骤 5：授权管道

每个工具调用通过五阶段授权：预过滤 → PreToolUse Hook → 规则评估 → 权限处理 → 沙箱执行。

步骤 6：执行

已批准的调用执行。Linux 上可通过 seccomp-bpf 或 bubblewrap 进行系统级隔离。

步骤 7：PostToolUse Hook

执行后触发，可修改输出或注入额外上下文。

步骤 8：结果注入

工具结果追加到对话历史，循环回到步骤 1。

1.2 停止条件

循环在以下情况终止：

• 模型产生 stop_reason=stop（且无 Stop Hook 强制继续）
• 达到 max_turns 限制
• Token 预算耗尽
• 用户发送 Ctrl+C

关键洞察： Stop Hook 可以检查最终响应并返回 continue: true 信号，强制再跑一轮。这就是质量门禁的实现方式 ------ 确保测试通过才结束会话。

1.3 上下文是核心约束

上下文窗口是 Claude Code 架构中最关键的绑定资源。 其他一切 ------ 模型、工具、子智能体 ------ 都服务于"明智地管理上下文"这个目标。

压缩管道是系统对抗上下文膨胀的主要防线，但它是有损的：摘要会丢失精确细节。

正确的应对策略是架构性的：

• 将探索工作推给子智能体（它们有独立上下文）
• 让主会话专注于编排
• 用 CLAUDE.md 预加载稳定知识，避免每次从头生成

1.4 安全模式逃生舱

自 v2.1.169 起，--safe-mode（或 CLAUDE_CODE_SAFE_MODE=1）启动一个干净会话，禁用所有自定义扩展 ------ 无 Hooks、无 Skills、无 MCP 服务器、无插件。

这是官方推荐的故障排查起点： 如果安全模式下问题消失，说明某个扩展是罪魁祸首。用二分法隔离即可。

第二层：工具层 ------ 内置与扩展的 flat pool

Claude Code 内置工具包括：Read、Edit、Write、Bash、Glob、Grep、LS、WebSearch、WebFetch、NotebookEdit、TodoWrite。

所有 MCP 服务器工具与内置工具出现在同一个扁平池中。 模型无法区分 Read（内置）和 github__create_issue（MCP）------ 对模型来说，它们都是可调用的工具。

SkillTool 是元工具，按名称启动 Skill。AgentTool 是元工具，递归生成子智能体。

第三层：权限与安全 ------ 五阶段授权管道

3.1 授权管道详解

每个工具调用（无论内置、MCP 还是 Skill 脚本）都通过五阶段授权：

阶段 1：预过滤

已知危险命令模式立即被拒绝（如 rm -rf /），无需匹配拒绝规则。

阶段 2：PreToolUse Hook

如果存在匹配的 PreToolUse Hook，它先触发。Hook 可以：

• 发出 block: true 信号完全拒绝调用
• 修改输入参数（重写工具接收的内容）
• 静默通过

Hooks 是外部 shell 命令 ------ 它们可以查询数据库、检查工单系统，或执行任何声明式规则集无法表达的策略。

阶段 3：规则评估

评估 permissions.allow、permissions.deny 和 permissions.ask 中的规则。允许/拒绝规则对文件路径使用 glob 模式，对 bash 命令使用前缀模式。ask 列表触发人机协作提示。拒绝规则始终覆盖允许规则。

阶段 4：权限处理

如果调用到达此阶段且没有明确的允许或拒绝，处理程序会提示用户（交互模式）或阻止（非交互 -p 模式，除非 --allowedTools 明确允许）。

阶段 5：沙箱

在 Linux 上，已批准的 Bash 调用可通过 seccomp-bpf（系统调用过滤）或 bubblewrap（文件系统命名空间隔离）进一步约束。

3.2 规则语法示例

{
  "permissions": {
    "allow": [
      "Read",
      "Read(src/**)",
      "Bash(npm run:*)",
      "Bash(git status)",
      "Edit(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(docker:*)"
    ]
  }
}

3.3 defaultMode 设置

• "default" ------ 首次使用每类工具时询问，然后记住答案
• "acceptEdits" ------ 文件编辑自动批准；bash 命令仍提示
• "bypassPermissions" ------ 所有工具调用自动批准（仅用于完全可信环境）
• "plan" ------ 只读模式；无编辑或 bash 执行

第四层：扩展层 ------ 四种机制，四种问题

4.1 MCP ------ 模型上下文协议

MCP 是连接 Claude 与外部系统的开放标准。把它想象成 AI 的 USB-C：一个协议，多种设备。

传输类型：

• stdio ------ 服务器作为本地进程运行，通过 stdin/stdout 通信。最快、最可靠、零网络延迟。本地工具的首选。
• SSE ------ 服务器作为远程 HTTP 服务运行。用于共享服务器（团队或云托管集成）。

配置示例：

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {"GITHUB_TOKEN": "${GITHUB_TOKEN}"}
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {"DATABASE_URL": "${DATABASE_URL}"}
    }
  }
}

安全提示： 绝不要硬编码密钥 ------ 始终使用环境变量插值（${VAR}）。MCP 配置会提交到 git；其中的密钥会变成公开的。

4.2 Hooks ------ 确定性自动化

Hooks 和 Prompts 的根本区别：Hooks 不能被模型忽略；Prompts 可以。

当你在 CLAUDE.md 中写"提交前总是运行 linter"时，模型可能遵守也可能不遵守，取决于上下文、压缩和推理偏差。当你配置一个 PostToolUse Hook，在每次文件编辑后运行 linter 时，linter 会无条件地、每次、无需模型参与地运行。

六大 Hook 事件：

事件	触发时机	典型用途
SessionStart	会话初始化时	环境验证、认证检查、动态 Skill 加载
PreToolUse	任何工具执行前	安全检查、输入重写、策略执行
PostToolUse	执行后	格式化、lint、自动提交、日志记录
Stop	模型产生 stop 时	质量门禁（测试通过才结束）
SubagentStop	子智能体完成时	子智能体输出验证
Notification	用户通知发出时	Slack 消息、Webhook、短信提醒

质量门禁模式（Stop Hook）：

#!/bin/bash
# stop-test-gate.sh ------ 如果测试失败则强制继续
if npm test 2>&1 | https://zhida.zhihu.com/search?content_id=277582063&content_type=Article&match_order=1&q=grep&zhida_source=entity -q "FAIL"; then
  FAILURES=$(npm test 2>&1 | grep "FAIL" | head -5)
  echo "{\"continue\": true, \"additionalContext\": \"Tests are failing:\\n$FAILURES\\nFix all failing tests before finishing.\"}"
else
  echo "{}"
fi

4.3 Skills ------ 渐进式披露的 expertise

Skills 是 Anthropic 2025 年 10 月推出的机制，用于将可重复的专业知识打包成可重用、可移植的模块。

核心架构特性：渐进式披露。

一个 Skill 是包含 SKILL.md 文件（YAML frontmatter + 可选脚本、模板和参考材料）的目录。会话开始时，Claude 只接收 Skill 的名称和描述（约 100 token）。当任务匹配描述时，Claude 读取完整指令；如果这些引用其他文件，Claude 再读取那些文件。脚本通过 bash 执行，只有它们的输出进入上下文 ------ 源代码从不消耗 token。

这意味着你可以在会话中加载 50 个 Skills，却只有极小的 token 开销。Token 只在需要时才产生。

SKILL.md 结构：

---
name: code-review
description: |
  Use when asked to review a pull request, diff, code change, or any file
  that needs quality review. Enforces the team style guide, security
  checklist, and performance review checklist.
disallowed-tools: [WebSearch, WebFetch]
---

# Code Review Process

## 1. Run automated checks first
Execute `scripts/lint.sh` and include all violations in your review output.
Do not skip this step.

## 2. Work through the checklist
See `templates/review-checklist.md` for the complete checklist.
Mark each item explicitly: PASS, FAIL, or N/A.

## Output format
Start with a summary https://zhida.zhihu.com/search?content_id=277582063&content_type=Article&match_order=1&q=verdict&zhida_source=entity: APPROVE / REQUEST CHANGES / NEEDS DISCUSSION.

description 字段是最关键的部分。 Claude 靠它来决定是否自动触发 Skill。要精确、具体地描述触发条件。"Use when asked to review code" 比 "Use when the user asks to review a pull request, diff, or specific file for quality issues" 差得多。后者可预测地触发；前者会在太多边缘任务上触发。

4.4 Plugins ------ 打包与分发

Plugin 将 MCP 服务器、Skills 和 Hooks 打包成一个带有 plugin.json 清单的单元。可通过 npm 安装或 git URL 分发。

Plugin 解决了分发问题： 不用让每个开发者手动配置三个 MCP 服务器、两个 Skills 和一个 Hook 数组，你创建一个 Plugin，一条命令安装所有内容。

第五层：委托层 ------ 子智能体与动态工作流

5.1 子智能体：上下文隔离的艺术

子智能体处理专注的子任务。主智能体委托工作，子智能体返回结果。

隔离架构是关键特性： 每个子智能体有自己的上下文窗口、自己的对话历史、自己的工具执行环境。子智能体完成时，只有其摘要返回给父级 ------ 不是完整的中间转录。这保持父上下文清洁，并支持多个专注任务的并行执行。

三种内置子智能体类型：

类型	权限	用途
Explore	只读	代码库探索、架构发现、上下文收集
Plan	只读 + 结构化输出	产生结构化计划供父级审查
General-purpose	完整读写	需要读现有代码和写新代码的实现任务

自定义子智能体定义：

---
name: security-auditor
description: |
  Use for security audits of authentication, authorization, input validation,
  and cryptographic code. Expert in OWASP Top 10 and SANS Top 25.
  Returns structured findings with CVSS scores.
model: claude-opus-4-8
agentType: explore
---

# Security Audit Protocol

## Scope
Focus on the code paths provided. Do not read outside the specified scope.

## Output Format
Return findings as JSON:
{
  "findings": [
    {
      "severity": "critical|high|medium|low",
      "cvss": "7.5",
      "location": "src/auth/handler.ts:142",
      "description": "...",
      "remediation": "..."
    }
  ]
}

5.2 动态工作流：千级智能体编排

动态工作流需要 CLAUDE_CODE_WORKFLOWS=1 环境变量或功能标志。

工作流是 JavaScript ES 模块。 meta 块必须是纯字面量 ------ 无动态表达式，无函数调用。运行时在执行任何代码前读取它以显示进度和计划执行。

核心 API：

• agent() ------ 生成单个智能体
• pipeline(items, fn) ------ 流式处理每个项目，文件 1 可以在第 3 阶段而文件 2 还在第 1 阶段。无项目间同步。默认使用。
• parallel(tasks) ------ 屏障。所有智能体同时启动，但下一行代码直到每个智能体都返回才执行。仅当下游阶段需要所有结果才能继续时使用（去重、排序、跨所有结果的合成）。

异构模型选择模式：

// 发现：Haiku ------ 便宜、快速、列表正确
const fileMap = await parallel(dirs.map(d => () =>
  agent(`List relevant files in ${d}`, {
    model: "claude-haiku-4-5-20251001",
    agentType: "explore"
  })
));

// 分析：Sonnet ------ 平衡，主要工作负载
const analyses = await pipeline(files, f =>
  agent(`Analyze ${f} for security issues`, {
    model: "claude-sonnet-4-6",
    schema: ANALYSIS_SCHEMA
  })
);

// 合成：Opus ------ 昂贵模型用于高风险的最终推理
const report = await agent("Synthesize findings into executive risk report", {
  model: "claude-opus-4-8"
});

非确定性禁止： Date.now()、Math.random() 和无参数的 new Date() 在工作流脚本中被禁止。工作流为缓存支持的恢复性记录每个 agent() 调用。非确定性调用会使日志失效。

配置体系：五层优先级

配置通过五个级别解析，每个级别覆盖下面的级别：

1. Enterprise managed-settings ------ 位于系统路径，不能被任何用户或项目设置覆盖
2. CLI flags ------ 仅当前会话有效，会话结束即丢弃
3. Local project settings (.claude/settings.local.json) ------ 个人偏好，应加入 .gitignore
4. Shared project settings (.claude/settings.json) ------ 提交到 git，团队-wide 配置
5. User settings (~/.claude/settings.json) ------ 应用于所有项目的基线

关键配置键：

{
  "model": "claude-opus-4-8",
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5-20251001"],
  "permissions": { ... },
  "hooks": { ... },
  "env": { "NODE_ENV": "development" },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only": "user-invocable-only"
  },
  "autoMemoryDirectory": ".claude/memory",
  "disableBundledSkills": false,
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30
}

fallbackModel 键（v2.1.166 引入）在主模型过载时链式尝试最多三个备用模型。如果 Opus 4.8 返回速率限制错误，Claude Code 自动用 Sonnet 4.6 重试，然后用 Haiku 4.5，不中断会话。

CLAUDE.md：最高 ROI 的配置

CLAUDE.md 不是设置文件 ------ 它是上下文注入机制。 每个会话自动读取它并将其内容直接注入系统提示，使其在压缩事件中持久存在。这是你能为会话质量做的**杠杆率最高的事情**。

加载顺序： 根级 /CLAUDE.md → 父目录向项目根目录 → ~/.claude/CLAUDE.md（用户全局）。每个文件的内容按顺序追加。

应该放入 CLAUDE.md 的内容：

# Project: payments-service

## Build Commands
npm run build         # TypeScript compilation
npm run test          # Jest test suite (run before committing)
npm run lint          # ESLint + Prettier check
docker compose up -d  # Start local deps (postgres:5432, redis:6379)

## Architecture
- src/api/       REST handlers - Express 5, Zod validation
- src/domain/    Business logic - no framework dependencies
- src/infra/     Database, cache, external APIs
- src/workers/   BullMQ background jobs

## Conventions
- Never mutate database state in tests (use transactions, rollback after each test)
- All amounts are stored and computed in cents (integer)
- External API calls must have a timeout (5s default, 10s for payment gateways)

## Known Issues
- The Stripe webhook handler has a race condition on refunds (ticket: PAY-1234)
- Do not edit package-lock.json manually

## Team Context
- Primary reviewer: @dana (architecture) @marcus (security)
- Deployment: ArgoCD auto-deploys main → staging, manual promote to prod

测试命令提示 alone 就能阻止 Claude 运行未测试的代码并提交。 金额以分为单位存储的提示能预防一类在事后几乎不可能发现的货币 bug。

模型选择与成本策略

三档模型

模型	特点	适用场景
Opus 4.8	默认模型，高努力，扩展思考可用	架构推理、安全分析、对抗验证、最终合成
Sonnet 4.6	平衡，200K 上下文，1M 扩展	实现、重构、代码审查、大多数自动化任务
Haiku 4.5	快速、便宜	探索智能体、文件发现、分类、答案明显的任务

最有效的模式：同一工作流的不同阶段使用不同模型档次。

Effort 级别

• /effort low ------ 最小推理，最快响应
• /effort medium ------ 平衡（大多数模型默认）
• /effort high ------ 扩展推理，复杂问题更强
• /effort xhigh ------ 最大推理深度
• /effort ultracode ------ xhigh 推理 + 复杂任务自动工作流编排

计划模式：先规划，后执行

计划模式将 Claude 限制为只读探索 ------ 无文件编辑，无 bash 命令。Claude 映射代码库，产生结构化计划，然后在任何执行前等待批准。

进入计划模式： Shift+Tab 循环模式（正常 → 计划 → 自动接受），或 /plan 带可选描述。

批准后选项：

• "是的，清除上下文并自动接受编辑"（为计划执行提供全新上下文 ------ 最高质量）
• "是的，手动批准编辑"（保留上下文）
• "是的，自动接受编辑"（保留上下文，无逐编辑提示）

何时使用计划模式： 当你无法承受 Claude 开始实现后发现方法错误的情况时。新功能实现、多文件重构、不熟悉的代码库、存在多种有效方法且你想先审查策略的任务。

企业与 CI/CD 部署

托管设置

Enterprise 使用 managed-settings.json 作为治理层：

{
  "permissions": {
    "deny": [
      "Bash(sudo:*)",
      "Bash(curl * | bash:*)",
      "Edit(.env*)",
      "Edit(production/**)"
    ],
    "ask": ["mcp__*"]
  },
  "env": {
    "DISABLE_TELEMETRY": "0",
    "CLAUDE_CODE_USE_BEDROCK": "1"
  },
  "hooks": {
    "SessionStart": [{
      "hooks": [{"type": "command", "command": "/usr/local/bin/claude-audit-start.sh"}]
    }],
    "PostToolUse": [{
      "matcher": "Bash|Edit|Write",
      "hooks": [{"type": "command", "command": "/usr/local/bin/claude-audit-log.sh"}]
    }]
  }
}

非交互式 (-p) 模式

#!/bin/bash
# ci-review.sh ------ CI 管道中的自动代码审查

DIFF=$(git diff HEAD~1 --unified=5)
RESULT=$(echo "$DIFF" | claude -p \
  "Review this diff for: security vulnerabilities, breaking changes, test coverage gaps. Return a structured JSON report." \
  --output-format json \
  --allowedTools "Read,Glob,Grep" \
  --max-turns 5 \
  2>/dev/null)

CRITICAL=$(echo "$FINDINGS" | jq '.findings | map(select(.severity == "critical")) | length')
if [ "$CRITICAL" -gt "0" ]; then
  echo "Critical findings detected - blocking merge"
  exit 1
fi
echo "Code review passed"

常见失败模式与规避

1. 上下文膨胀导致质量下降

症状： 50+ 工具调用后，Claude 忽略之前遵循的指令，做出与早期推理不一致的决定，询问它已经拥有的信息。

规避： 在上下文接近填满前手动 /compact。用子智能体进行探索。保持 CLAUDE.md 更新会话关键事实。

2. 描述模糊导致错误的 Skill 触发

规避： 明确测试触发条件。说出真实用户会使用的准确短语并验证 Skill 是否触发。说出相邻短语并验证它不触发。

3. Hooks 静默失败阻塞循环

规避： 所有 Hooks 应在以非零代码退出前向 stdout 发出结构化错误消息。在接入实时会话前隔离测试 Hooks。

4. MCP 提示注入

规避： 使用 PreToolUse Hook 验证 MCP 工具输入。在允许列表中应用最小权限原则（绝不在生产设置中授予 mcp__*）。

5. 工作流脚本中的非确定性

规避： 通过 args 传递所有非确定性输入。启动昂贵运行前审计工作流脚本中的非确定性调用。

6. Skill 指令被过于字面地解释

规避： 用祈使语气编写 Skill 指令，消除歧义。将"validate if needed"替换为"always run scripts/validate.sh before proceeding. If it fails, report the failure and stop."

总结

Claude Code 的五层架构 ------ 核心循环、工具、权限安全、扩展、委托 ------ 为 AI 辅助开发提供了工程化的框架。

关键洞察：大多数用户停留在第 1 层，看着上下文膨胀和质量下降。高效使用者将探索推到第 5 层，用第 3 层自动化质量门禁，在第 4 层编码专业知识，只在第 1 层进行编排和最终决策。

你的下一步行动：

1. 为你当前的项目创建一个 CLAUDE.md，包含构建命令、架构概述和已知问题
2. 配置一个 PostToolUse Hook，在每次编辑后运行 linter
3. 为你的团队最常重复的工作流创建一个 Skill
4. 尝试用一个 Explore 子智能体进行代码库探索，保持主上下文清洁

💬 讨论

你已经在用 Claude Code 的哪些高级功能？遇到过上下文膨胀的问题吗？欢迎在评论区分享你的经验和技巧。