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认证的官网,别被误导)。