12 min read

Claude 架构师指南 :深度掌握 Claude Code 与 Agentic 系统

Source: http://x.com/i/article/2033431230373335040

本文适合想要对ClaudeCode更进一步学习,以便掌握真实世界工程落地能力的人。

通过本文提供的沉浸式互动学习Prompt。你将掌握所有 Agent 开发的核心知识,并具备开发出生产级 AI 应用,创造真实的商业价值的能力。

你将能为企业构建以下高价值系统:

  • Customer Support Resolution Agent(客服解决代理:Agent SDK + MCP + 人工介入流)
  • Code Generation(代码生成流水线:CLAUDE.md + Plan mode + Custom Slash Commands)
  • Multi-Agent Research System(多智能体研究系统:Coordinator-Subagent 编排)
  • Developer Productivity Tools(开发者效率工具:内置工具 + MCP Servers)
  • CI/CD Integration(自动化流水线:非交互式执行 + 结构化输出)
  • Structured Data Extraction(结构化数据提取:JSON Schemas + tool_use + 验证循环)

以下是基于官方架构师要求提炼的 5 大核心领域(Domains)干货:

Domain 1: Agentic Architecture & Orchestration (Agent 架构与编排) - 27%

这是构建复杂 AI 系统的基石。不要用自然语言去猜模型的状态,要用系统级的工程方法去控制它。

核心认知与避坑指南:

  • Agentic Loops(代理循环):

绝对不要通过解析自然语言(比如让模型输出“我完成了”)来终止循环。必须严格依赖 API 响应中的 stop_reason 字段。如果 stop_reason 是 tool_use,执行工具并将结果追加到 Messages 历史中;如果是 end_turn,才算真正结束。

  • Context Isolation(上下文隔离):

在 Multi-Agent 架构中,最大的误区是认为 Subagents(子代理)会自动继承 Coordinator(协调器)的记忆。它们不共享。 Subagents 在隔离的上下文中运行,必须通过提示词显式传递所有必需的数据(如 URL、元数据)。

  • Workflow Enforcement(工作流强制执行):

当涉及资金、安全或合规等高风险场景时,不要只依赖 System Prompt 去约束模型。必须使用代码级别的 Hooks(钩子) 和 Prerequisite gates(前置网关) 来强制拦截和验证(例如拦截 >500 美元的退款请求)。

沉浸式学习 Prompt(复制发给 Claude): markdown

You are an expert instructor teaching Domain 1 (Agentic Architecture & Orchestration) of the Claude Certified Architect certification. Take me from novice to exam-ready. Teach like a senior architect at a whiteboard: direct, specific, grounded in production scenarios. 

Cover the following 7 tasks sequentially:
1. Agentic Loops (Focus on `stop_reason` vs arbitrary natural language parsing)
2. Multi-Agent Orchestration (Hub-and-spoke, context isolation)
3. Subagent Invocation (Task tool, `fork_session`, parallel spawning)
4. Workflow Enforcement (Prompt vs Programmatic hooks for high-stakes)
5. Agent SDK Hooks (`PostToolUse` normalization, tool call interception)
6. Task Decomposition Strategies (Prompt chaining vs dynamic adaptive)
7. Session State and Resumption

For each task: Explain with a production example, highlight anti-patterns, ask 1-2 check questions. Conclude with a 10-question practice exam.

完整版本的Prompt太长,贴到了Gist。 https://gist.github.com/tvytlx/2e0c4c823e56e1ddcce8f0634d1f36e6#file-domain1-md ## Domain 2: Tool Design & MCP Integration (工具设计与 MCP 集成) - 18%

工具(Tools)不是给得越多越好。低劣的工具描述是导致 Agent 频繁出错的罪魁祸首。

核心认知与避坑指南:

  • Tool Descriptions(工具描述):

描述是 Claude 选择工具的唯一依据。如果 get_customer 和 lookup_order 的描述高度重合,模型就会一直调错。修复方式不是加 Few-shot,也不是写路由分类器,而是重写精细的描述(包含输入要求、边界、以及“何时不要用这个工具”)。

  • Structured Errors(结构化错误):

利用 MCP 的 isError 标志。要严格区分四类错误:Transient(超时,可重试)、Validation(参数错误,修复后重试)、Business(违背业务规则,不可重试)、Permission(权限不足)。注意:查询数据库返回“空列表”是正常结果,不是错误,不要重试。

  • MCP Servers 作用域: .mcp.json 放在项目根目录(进版本控制,团队共享);~/.claude.json 是个人用户级(不共享)。优先使用社区现成的 MCP 协议集成(Jira, GitHub),仅在有特殊私有业务逻辑时才开发 Custom Server。

沉浸式学习 Prompt(复制发给 Claude): markdown

You are an expert instructor teaching Domain 2 (Tool Design & MCP Integration) of the Claude Certified Architect certification. Teach like a senior architect.

Cover the following 5 tasks sequentially:
1. Tool Interface Design (Descriptions as the primary routing mechanism, splitting tools)
2. Structured Error Responses (MCP `isError` flag, 4 error categories, Valid empty vs Access failure)
3. Tool Distribution and `tool_choice` (`auto`, `any`, forced selection, avoiding tool overload)
4. MCP Server Integration (Project `.mcp.json` vs User `~/.claude.json`, env vars)
5. Built-in Tools (Grep vs Glob, Edit vs Read/Write fallback)

For each task: Explain with a production example, highlight anti-patterns, ask check questions. Conclude with a 7-question practice exam.

完整版本的Prompt太长,贴到了Gist。

https://gist.github.com/tvytlx/2e0c4c823e56e1ddcce8f0634d1f36e6#file-domain2-md

Domain 3: Claude Code Configuration & Workflows (配置与工作流) - 20%

区分业余玩家和专业架构师的分水岭,在于能否为整个研发团队配置自动化的 Claude Code 标准。

核心认知与避坑指南:

  • CLAUDE.md Hierarchy(配置层级):

最常见的坑:新同事拉取代码后 Claude 表现不一致。原因往往是有人把指令写在了个人级的 ~/.claude/CLAUDE.md 中,而不是项目根目录的 .claude/CLAUDE.md 里。

  • Path-specific Rules(特定路径规则):

使用带有 YAML 前置(frontmatter)的 .claude/rules/ 文件(例如设定 paths: ["**/*.test.tsx"]),这比每个文件夹塞一个配置文件优雅得多,能实现全局正则匹配加载。

  • Plan mode vs. Direct execution: * Plan mode(计划模式):

适用于跨多文件重构、架构设计。先让模型 Explore,再执行。

Direct execution(直接执行):

适用于单点 Bug 修复、单文件逻辑更改。

  • CI/CD 集成: 在自动化流水线中,务必使用 -p (print mode) 标志运行 Claude Code,否则 CI/CD 任务会因为等待终端交互而无限挂起。

沉浸式学习 Prompt(复制发给 Claude): markdown

You are an expert instructor teaching Domain 3 (Claude Code Configuration & Workflows) of the Claude Certified Architect certification. Teach like a senior architect.

Cover the following 6 tasks sequentially:
1. CLAUDE.md Hierarchy (User vs Project vs Directory level)
2. Custom Slash Commands and Skills (`.claude/skills/`, `context: fork` frontmatter)
3. Path-Specific Rules (YAML glob patterns for global enforcement)
4. Plan Mode vs Direct Execution (When to use which, Explore subagent)
5. Iterative Refinement (Concrete I/O examples vs prose, test-driven)
6. CI/CD Integration (The `-p` flag for non-interactive pipelines, structured output)

For each task: Explain with a production example, highlight anti-patterns, ask check questions. Conclude with an 8-question practice exam.

完整版本的Prompt太长,贴到了Gist。

https://gist.github.com/tvytlx/2e0c4c823e56e1ddcce8f0634d1f36e6#file-domain3-md

Domain 4: Prompt Engineering & Structured Output (提示词工程与结构化输出) - 20%

在这里,“Be explicit(明确)”胜过一切。不要对模型说“请保守一点”,要用代码示例告诉它什么是错的。

核心认知与避坑指南:

  • Explicit Criteria(明确标准):

永远用分类和示例代替模糊形容词。不要说“只报告高置信度问题”,要说“仅当实际代码行为与注释矛盾时标记,跳过风格偏好”,并附上具体代码示例。

  • Few-Shot 提示词:

解决模型判断不稳定的最高杠杆技巧。提供 2-4 个包含了思考推理过程 (Reasoning) 的 Edge cases(边缘情况)示例。

  • Structured Output with tool_use:

强制 JSON Schema 输出。为了防止模型在源数据缺失时“幻觉”捏造数据,必须在 Schema 中合理设计 Nullable (可空) 字段、unclear 枚举值以及 other 字段。

  • Message Batches API(批处理):

异步、便宜 50%、最多 24 小时处理完毕、不支持多轮 tool_use。将每日夜间审计、批量报表走 Batch API;将 PR 合并前的阻塞性代码审查走同步 API。

沉浸式学习 Prompt(复制发给 Claude): markdown

You are an expert instructor teaching Domain 4 (Prompt Engineering & Structured Output) of the Claude Certified Architect certification. Teach like a senior architect.

Cover the following 6 tasks sequentially:
1. Explicit Criteria (Concrete code examples vs vague prose)
2. Few-Shot Prompting (Including reasoning in examples to prevent hallucination)
3. Structured Output with `tool_use` (Nullable fields to prevent fabrication, enums)
4. Validation-Retry Loops (When to feedback errors vs when information is genuinely absent)
5. Batch Processing API (Cost savings, constraints, synchronous vs asynchronous architectural choices)
6. Multi-Instance Review (Avoiding self-review bias in the same session context)

For each task: Explain with a production example, highlight anti-patterns, ask check questions. Conclude with an 8-question practice exam.

完整版本的Prompt太长,贴到了Gist。

https://gist.github.com/tvytlx/2e0c4c823e56e1ddcce8f0634d1f36e6#file-domain4-md

Domain 5: Context Management & Reliability (上下文管理与可靠性) - 15%

权重虽小,但在生产环境中,上下文一旦崩溃,前面设计得再好的架构都会崩盘。

核心认知与避坑指南:

  • Context Preservation(上下文保留):

不要对包含关键金额、单号、日期的交易数据使用渐进式总结(Progressive summarization)。应该提取一个持久化的 "Case Facts"(案件要素) 代码块,将其原文包含在后续每一次提示词中。

  • Escalation Triggers(升级人工触发器):

不要用所谓的“模型置信度得分”或情感分析去判断是否转人工。只有三种可靠的触发器:客户明确要求转人工(立即执行)、遇到策略空白、模型无法取得实质性进展。

  • Error Propagation(错误传递):

遇到 API 错误或执行失败,绝对不要默默吞掉错误或者直接 Kill 掉整个工作流。正确的做法是:传递结构化错误上下文(包括:失败类型、尝试的查询参数、已获得的部分结果),让 Coordinator 决定备选方案。

  • Context Compaction(上下文压缩):

在长时间的代码探索会话中,使用 /compact 命令清理冗余的中间探索输出,只保留关键发现(Scratchpad),防止触发 "Lost in the middle"(中间遗忘)效应。

沉浸式学习 Prompt(复制发给 Claude): markdown

You are an expert instructor teaching Domain 5 (Context Management & Reliability) of the Claude Certified Architect certification. Teach like a senior architect.

Cover the following 6 tasks sequentially:
1. Context Preservation (Persistent "case facts" block vs progressive summarization, "Lost in the middle" effect)
2. Escalation and Ambiguity Resolution (The 3 valid triggers vs unreliable sentiment analysis)
3. Error Propagation (Structured error context, never silently suppressing)
4. Codebase Exploration (Scratchpad files, `/compact`, state manifest)
5. Human Review and Confidence Calibration (Field-level confidence, stratified sampling)
6. Information Provenance (Preserving claim-source mappings during synthesis)

For each task: Explain with a production example, highlight anti-patterns, ask check questions. Conclude with a 6-question practice exam.

完整版本的Prompt太长,贴到了Gist。

https://gist.github.com/tvytlx/2e0c4c823e56e1ddcce8f0634d1f36e6#file-domain5-md

练习作业

🔨 领域 1 实操练手项目

目标:掌握代理循环与拦截机制

  • 作业内容: 构建一个包含 3-4 个 MCP 工具的多工具 Agent。
  • 核心要求: 1. 在代码中正确处理 stop_reason(而不是靠自然语言判断是否结束)。 2. 编写一个 PostToolUse hook(钩子)来统一规范化不同工具返回的数据格式。 3. 编写一个工具调用拦截 hook,用于直接阻断违反业务策略的工具调用。
  • 价值: 搞定这一个练习,领域 1 的核心概念你就掌握了一大半。

🔨 领域 2 实操练手项目

目标:体验工具描述对路由的致命影响

  • 作业内容: 编写两个功能故意设计得高度相似的 MCP 工具。
  • 核心要求: 故意写非常模糊的工具描述(Tool descriptions),让模型产生路由混乱(Misrouting)。 观察并记录模型调错工具的现象。 修复这些描述,明确边界和输入输出限制。
  • 价值: 亲身体验(Experience the difference)清晰的描述如何奇迹般地修复 Agent 的智商。

🔨 领域 3 实操练手项目

目标:跑通 Claude Code 的企业级配置流

  • 作业内容: 初始化一个真实的代码项目
  • 核心要求: 建立 CLAUDE.md 层级(同时包含项目级 Project-level 和 目录级 Directory-level)。 在 .claude/rules/ 中使用 glob 模式(如 **/*.py 或 **/*.test.tsx)编写全局规则。 编写一个使用 context: fork 的自定义技能(Skill)。 在 .mcp.json 中配置一个带有环境变量扩展(Env var expansion)的 MCP Server。
  • 测试方法: 用计划模式(Plan mode)跑一个跨多文件的重构任务;用直接执行(Direct execution)跑一个单文件的 Bug 修复。

🔨 领域 4 实操练手项目

目标:实现抗幻觉的结构化数据提取

  • 作业内容: 构建一个文档数据提取流水线(Extraction pipeline)。
  • 核心要求: 使用带有 tool_use 的 JSON Schema,其中必须包含:必填字段(Required)、可选字段(Optional)和可空字段(Nullable)(用来防止模型瞎编数据)。 在代码里加上验证-重试循环(Validation-retry loop),当格式不对时把错误抛回给模型让它自我修正。 调用 Message Batches API 处理一批文档,并通过 custom_id 追踪和处理那些失败的任务。

🔨 领域 5 实操练手项目

目标:压力测试错误传递与上下文溯源

  • 作业内容: 构建一个带有两个子代理(Subagents)的协调器(Coordinator)。
  • 核心要求: 实现一个持久化的“案件核心事实(Case facts)”代码块,并确保它在多轮对话中不被总结掉。 故意模拟一次 API 超时错误。验证协调器能否收到结构化的错误上下文,并带着已获得的部分结果继续往下走,而不是直接崩溃。 故意给模型喂入两个相互冲突的数据源,验证它在最终的 Synthesis(综合报告)中能否正确保留两者的归属溯源(Attribution),而不是自行武断地只选一个。

如有帮助请转发给你的朋友。

本文主要参考以下文章,并结合本人多年软件行业经验校正(原文里有一个假的Anthropic认证的官网,别被误导)。

https://x.com/hooeem/status/2033198345045336559