Claude 架构师实战指南：拆解那个你考不了的认证考试

很多人想成为 Claude 认证架构师。遗憾的是，这个认证考试不对公众开放，只有 Claude 的合作伙伴才有资格参加。但这重要吗？完全不重要。证书只是一张纸，构建生产级应用的能力才是真本事。

我拆解了整个考试指南，提取了所有核心知识点。如果你能掌握下面这些内容，你就能构建出稳定、高效、可商用的 Claude 应用，哪怕你手里没有那张证书。这篇文章将带你深入代理架构、工具设计、Claude Code 配置、提示工程以及上下文管理这五大核心领域。

领域一：代理架构与编排

这是考试的重头戏，占比高达 27%。如果你这里丢分，基本就过不了关。

代理循环：别再解析自然语言了

本段欲回答的核心问题：如何正确地判断一个代理任务何时结束？

很多开发者犯的最大错误，就是试图通过解析 Claude 的回复文本（比如检查是否包含“我完成了”）来判断任务是否结束。这是完全错误的。自然语言充满了不确定性，模型可能说完了话但任务没结束，也可能话没说完但逻辑已经终止。

正确的做法是依赖 API 返回的 stop_reason 字段。这是唯一的真理来源。

正确的循环逻辑是这样的：

  1. 向 Claude 发送请求。
  2. 检查响应中的 stop_reason。
  3. 如果是 tool_use：执行工具 -> 将结果追加到对话历史 -> 再次发送请求。
  4. 如果是 end_turn：任务结束，展示最终结果。

考试中常考的三个致命反模式：

  • 解析自然语言信号：比如检查回复里有没有“Done”。这不可靠，因为模型的表达方式多变。
  • 强制迭代次数上限：比如“跑 10 次就停”。这要么切断了还没完成的工作，要么浪费算力跑空转。
  • 检查文本内容：认为有文本输出就是结束了。错，模型经常一边输出文本一边调用工具。

多代理架构：中心辐射与内存隔离

本段欲回答的核心问题：为什么我的子代理总是拿不到上下文信息？

这是多代理系统中最容易被误解的概念：子代理不共享协调者的记忆。

很多人以为只要在协调者那里说了“查询用户订单”，子代理就能知道用户是谁。实际上，子代理的上下文是完全隔离的。你必须在提示词中显式地传递所有信息。如果子代理需要用户 ID，你就得在调用它的提示词里把用户 ID 写进去。

架构模式：中心辐射

  • 协调者：坐在中心，负责分解任务、选择子代理、传递上下文、汇总结果。
  • 子代理：是独立的“触手”，专门处理特定任务（如网络搜索、文档分析）。
  • 通信原则：所有信息流必须经过协调者。子代理之间绝对不能直接通信。

任务分解的陷阱：
考试曾给过一个案例：一个研究系统要分析“AI 对创意产业的影响”，结果报告只覆盖了视觉艺术，完全忽略了音乐、写作和电影。问题出在哪？不是子代理偷懒，而是协调者在分解任务时就没分全。如果你发现结果有缺失，先回头检查协调者的任务拆解逻辑。

强制执行与钩子

本段欲回答的核心问题：什么时候该用代码强制执行，而不是靠提示词引导？

如果后果涉及金钱、安全或合规，千万别指望提示词能 100% 管用。提示词是概率性的，它“大多数时候”有效，但在高风险场景下，这 1% 的失败率就能毁了生意。

强制执行的手段：

  • Hooks（钩子）：在工具执行前或执行后拦截。比如，拦截所有超过 500 美元的退款请求，强制转人工审核。这是确定性的保证。
  • 前置门控：程序化地阻止某些工具的调用，直到前置条件满足。

决策法则：

  • 低风险（格式偏好、风格指南）：提示词引导足矣。
  • 高风险（退款、转账、权限变更）：必须用程序化强制执行。

实战建议

如果你想动手练习，试着构建一个包含 3-4 个 MCP 工具的代理。实现正确的 stop_reason 处理，加一个 PostToolUse 钩子来规范化数据格式，再加一个拦截钩子来阻止违规操作。这一个练习能覆盖领域一的绝大部分考点。

领域二：工具设计与 MCP 集成

这个领域占 18%。它考察的是你如何让模型“正确地选择工具”。

工具描述：被忽视的核心

本段欲回答的核心问题：为什么模型总调错工具？

很多时候模型选错工具，不是因为模型笨，而是因为你的工具描述写得太烂。工具描述是模型选择工具的主要依据。如果你写了两个描述差不多的工具，比如 get_customer 和 lookup_order 都写着“检索信息”，模型就会疯掉。

好的工具描述必须包含：

  • 这个工具具体干什么（主要目的）。
  • 期望的输入格式、类型和限制。
  • 它擅长处理的查询示例。
  • 边界情况：什么时候该用 这个 工具而不是另一个。

解决错误路由的正确姿势：
当发现模型总是混淆两个工具时，第一反应应该是优化描述。不要急着去搞什么路由分类器或者 Few-shot 示例，那是舍本逐末。先把描述写清楚，让模型能分得清它们。

结构化错误处理

本段欲回答的核心问题：如何让模型理解工具调用失败了？

工具失败的方式有很多种，处理方式也不一样。MCP 协议中有个 isError 标志，用来告诉模型出错了。但光有个标志不够，你需要告诉模型这错是哪一种。

四种错误类型：

  1. 瞬时错误：超时、服务不可用。这种可以重试。
  2. 验证错误：输入格式不对。需要修正输入后重试。
  3. 业务错误：违反规则（如退款超限）。不能重试，需要换流程。
  4. 权限错误：没权限。需要升级或换凭证。

最容易踩的坑：
模型经常混淆“查询失败”和“查询结果为空”。

  • 如果是查询失败（连不上数据库），模型应该重试。
  • 如果是查询结果为空（客户不存在），模型不应该重试，应该告诉用户“没找到”。
    如果你不把这两者区分开，模型就会对着一个不存在的客户 ID 重试八百次，然后 escalte 给真人，纯属浪费时间。

工具分发与配置

本段欲回答的核心问题：给模型配置多少个工具最合适？

并不是工具越多越好。给一个代理塞 18 个工具，选择准确率会直线下降。最佳实践是将每个子代理的工具限制在 4-5 个，且严格相关。综合代理不需要网络搜索工具，网络搜索代理不需要文档分析工具。

MCP 配置层级：

  • 项目级：放在代码库里的 .mcp.json。这是团队共享的，受版本控制。
  • 用户级：放在本地的 ~/.claude.json。这是你个人的，不共享。
    配置环境变量时，记得用 ${GITHUB_TOKEN} 这种语法，别把真 Token 写进代码库里。

领域三：Claude Code 配置与工作流

这一部分占 20%，主要考察你是否懂得如何为团队配置开发环境。

CLAUDE.md 层级结构

本段欲回答的核心问题：为什么新同事拉了代码后，Claude 的表现不一致？

这是考试最喜欢考的陷阱。Claude Code 的配置有三个层级：

  1. 用户级 (~/.claude/CLAUDE.md)：只对你自己生效。不受版本控制，别人拉不到。
  2. 项目级 (.claude/CLAUDE.md)：对所有人生效。受版本控制，团队共享。
  3. 目录级：只在特定子目录下生效。

如果你把团队的代码规范写在了用户级配置里，新同事克隆了代码库后，根本看不到这些规范，Claude 自然就不会按规范办事。所以，团队共享的规则必须放在项目级配置中。

路径特定规则

本段欲回答的核心问题：如何让规则只对特定类型的文件生效？

如果你有 50 个目录，里面散落着各种测试文件，你想让所有测试文件都遵循同一套规范，怎么办？在每个目录下建 CLAUDE.md 太傻了。

正确的做法是使用 .claude/rules/ 目录。在这里建一个 YAML 文件，写上：

---
paths: ["**/*.test.tsx"]
---

这样，不管测试文件在哪个角落，只要匹配这个路径，规则就会加载。这比目录级配置灵活得多，还能节省 Token，因为只有在编辑相关文件时规则才会被加载。

计划模式 vs 直接执行

本段欲回答的核心问题：什么时候该让 Claude 先做计划，什么时候直接干活？

  • 用计划模式：重构单体应用、大规模迁移文件、涉及架构决策。这时候需要先想清楚再动手。
  • 用直接执行：修单个 Bug、改一行代码、验证一个简单逻辑。这时候磨磨唧唧做计划纯属浪费时间。

CI/CD 集成

在 CI/CD 流水线里用 Claude Code，必须加 -p 标志。这是非交互模式。没有这个标志，你的流水线会一直挂着等待输入，直到超时报错。

另外，如果你要用 Claude 做代码审查，千万别让它审查自己刚写的代码。同一个会话里，它对自己逻辑的盲点是没有感知的。启动一个独立的审查实例，效果要好得多。

领域四：提示工程与结构化输出

占比 20%。这个领域考察的是如何让模型“听话”且“输出稳定”。

显性标准：别整虚的

本段欲回答的核心问题：如何让模型减少误报？

很多人喜欢在提示词里写“保守一点”、“只报告高置信度的发现”。这种废话一点用没有。模型对“保守”的理解和你不一样。

真正管用的是显性标准：
“只有当代码行为与注释描述矛盾时才报告。跳过风格偏好和局部模式。”
你要给出具体的代码示例，告诉它什么是“严重错误”，什么是“可以忽略的小问题”。具体的案例比抽象的形容词强一万倍。

Few-shot 提示

本段欲回答的核心问题：如何让模型处理模棱两可的情况？

当模型在处理边缘情况时犹豫不决，或者提取数据时经常漏掉字段，Few-shot（少样本）提示是最好的解药。给它 2-4 个例子，展示在模棱两可的情况下你为什么选了 A 而不是 B。

这不仅仅是教它模仿格式，更是教它你的决策逻辑。

结构化输出与 tool_use

本段欲回答的核心问题：如何保证输出 JSON 绝对合法？

虽然你可以让模型直接输出 JSON 字符串，但这有风险。它可能漏个括号，或者把字段填错位置。

最稳妥的方法是把 JSON 结构定义成一个工具，然后强制模型调用这个工具。这就是 tool_use 的精髓。

  • 利用 tool_choice 参数："any" 强制模型必须调个工具，{"type": "tool", "name": "..."} 强制模型必须调指定的工具。
  • 防止幻觉：对于可能缺失的信息，字段要设为 nullable（可空）。如果你不设为可空，模型为了填满必填项，可能会编造数据。

批处理

Message Batches API 可以节省 50% 的成本，但它不适合实时场景。它最多要跑 24 小时，而且不支持多轮工具调用。

  • 实时阻塞任务（如提交前检查）：用同步 API。
  • 后台批量任务（如夜间报告）：用 Batch API。

领域五：上下文管理与可靠性

占比 15%。虽然比重最小，但一旦出错，前面的努力全白费。

上下文保留

本段欲回答的核心问题：为什么聊着聊着，模型就把关键数据忘了？

这是“渐进式摘要”惹的祸。随着对话越来越长，系统会压缩历史记录。在这个过程中，具体的数字（如金额 $247.83、订单号 #8891）会被压缩成“用户想要退款”这种模糊的废话。

解决办法：
在每次对话中显式地维护一个“案件事实”块。里面写死金额、日期、ID。这个块永远不要被摘要，每次请求都带上。

另外，还要注意“中间丢失”效应。模型对开头和结尾的内容记得最牢，中间的内容容易被忽略。所以，关键结论要放在开头，别埋在几千个 Token 后面。

升级触发条件

本段欲回答的核心问题：什么时候该把任务转给真人？

只有三种情况是靠谱的触发条件：

  1. 用户明确要求找人。
  2. 政策没覆盖这种奇葩情况。
  3. 代理真的处理不下去了。

千万别依赖“情绪分析”来升级。用户生气不代表问题难解决。很多时候用户骂骂咧咧，其实问题简单得很，代理直接解决了就行。只有在用户明确要求或者真的卡壳时，才转人工。

实用摘要 / 操作清单

  1. 代理循环：永远只信 stop_reason，别解析自然语言判断终止。
  2. 多代理：子代理没记忆，所有信息必须显式传递。
  3. 高风险控制：涉及钱和安全，用代码钩子强制执行，别靠提示词。
  4. 工具设计：描述写清楚是第一位的，工具数量控制在 4-5 个最佳。
  5. 错误处理：分清“查不到”和“查错了”，别对着空结果重试。
  6. 团队配置：共享规则放项目级 (project-level)，别放用户级。
  7. 结构化输出：用 tool_use 强制 JSON 格式，可空字段设 nullable。
  8. 上下文保护：关键数据（ID、金额）单独维护，防止被摘要吞掉。

一页速览

领域 核心考点 关键动作
架构与编排 代理循环、内存隔离、强制执行 检查 stop_reason；显式传参；高风险用 Hooks
工具设计 (MCP) 工具描述、错误分类、工具数量 写详细描述；区分瞬时/业务错误；限制工具数
Claude Code 配置层级、路径规则、CI/CD 规则放项目级；用 Glob 匹配路径；CI 加 -p 标志
提示工程 显性标准、Few-shot、结构化输出 给具体例子；用 tool_use 输出 JSON；设 nullable
上下文管理 渐进式摘要陷阱、升级策略 维护“案件事实”块；按需/无法解决时转人工

常见问答 (FAQ)

Q: 为什么我的代理经常在任务没完成时就停止了？
A: 你可能错误地解析了模型的文本输出（如检测到“完成”字样就停了）。你应该检查 API 返回的 stop_reason 字段，只有当它是 end_turn 时才真正结束。

Q: 子代理为什么访问不到主代理对话中的用户信息？
A: 子代理的上下文是完全隔离的，它们不共享主代理的内存。你必须在调用子代理的提示词中，把用户 ID 等必要信息显式写进去。

Q: 当两个工具功能相似时，模型总选错怎么办？
A: 不要急着训练路由模型。90% 的情况下，是因为你的工具描述写得太像了。重新撰写工具描述，明确写出两者的适用边界和区别。

Q: 如何防止模型在提取数据时编造不存在的字段值？
A: 在定义 JSON Schema 时，对于可能缺失的信息，将字段设为 nullable（可空）。如果不设，模型为了满足必填要求，可能会产生幻觉。

Q: Claude Code 的配置文件放在哪里能让全团队都生效？
A: 必须放在项目根目录下的 .claude/CLAUDE.md（项目级）。放在用户目录下的配置只对你自己生效，新同事拉代码后看不到。

Q: 什么情况下应该使用程序化 Hook 而不是提示词指令？
A: 当操作涉及金钱交易、安全权限或合规要求时，必须使用 Hook。提示词只能引导，不能保证 100% 执行，高风险场景容不得 1% 的失误。

Q: 为什么模型处理长对话时会忘记之前的订单号？
A: 这是因为“渐进式摘要”压缩了上下文。解决方法是维护一个独立的“案件事实”块，包含订单号、金额等关键数据，并在每次对话中显式传递，不依赖历史记录压缩。

Q: 工具调用失败时，如何区分是该重试还是该报错？
A: 检查错误类型。如果是网络超时或服务不可用（瞬时错误），可以重试；如果是“找不到数据”（有效空结果），不应重试，直接返回空；如果是业务规则限制（如退款超额），应转人工或换流程。