224 lines
16 KiB
Markdown
224 lines
16 KiB
Markdown
---
|
||
title: "Claude 架构师指南 :深度掌握 Claude Code 与 Agentic 系统"
|
||
source: "https://x.com/tvytlx/status/2033455217984041213"
|
||
author:
|
||
- "[[Unknown]]"
|
||
published: 2026-03-16
|
||
created: 2026-03-17
|
||
description:
|
||
tags:
|
||
- "clippings"
|
||
---
|
||
本文适合想要对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](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](https://gist.github.com/tvytlx/2e0c4c823e56e1ddcce8f0634d1f36e6#file-domain1-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](https://gist.github.com/tvytlx/2e0c4c823e56e1ddcce8f0634d1f36e6#file-domain1-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](https://gist.github.com/tvytlx/2e0c4c823e56e1ddcce8f0634d1f36e6#file-domain1-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](https://gist.github.com/tvytlx/2e0c4c823e56e1ddcce8f0634d1f36e6#file-domain1-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](https://x.com/hooeem/status/2033198345045336559) |