Files
Obsidian/CSDN等国内/Claude 架构师指南 :深度掌握 Claude Code 与 Agentic 系统.md
T
coco 8b94d76799 a
2026-07-21 13:57:15 +08:00

224 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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)