\documentclass[a4paper]{article}

% Basic packages
\usepackage[fontset=fandol]{ctex}
\usepackage{amsmath, amssymb}
\usepackage{graphicx}
\usepackage[margin=2.5cm]{geometry}
\usepackage[most]{tcolorbox}
\usepackage{etoolbox}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{booktabs}
\usepackage{subcaption}
\usepackage{float}
\usepackage{tikz}
\usepackage{enumitem}
\IfFileExists{pgfplots.sty}{
    \usepackage{pgfplots}
    \pgfplotsset{compat=1.18}
}{}

% Highlight boxes
\newtcolorbox{knowledgebox}[1]{
    enhanced, colback=blue!5!white, colframe=blue!75!black, colbacktitle=blue!75!black,
    coltitle=white, fonttitle=\bfseries, title=#1, attach boxed title to top left={yshift=-2mm, xshift=2mm},
    boxrule=1pt, sharp corners
}

\newtcolorbox{importantbox}[1]{
    enhanced, colback=yellow!10!white, colframe=yellow!80!black, colbacktitle=yellow!80!black,
    coltitle=black, fonttitle=\bfseries, title=#1, sharp corners
}

\newtcolorbox{warningbox}[1]{
    enhanced, colback=red!5!white, colframe=red!75!black, colbacktitle=red!75!black,
    coltitle=white, fonttitle=\bfseries, title=#1, sharp corners
}

% Listings
\lstset{
    language=Python,
    basicstyle=\ttfamily\small,
    keywordstyle=\color{blue},
    stringstyle=\color{red!60!black},
    commentstyle=\color{green!60!black},
    breaklines=true,
    frame=single,
    numbers=left,
    numberstyle=\tiny\color{gray},
    captionpos=b,
    extendedchars=false
}

% Front-page metadata
\newcommand{\notetitle}{成为 Claude 架构师的完整学习路径}
\newcommand{\noteauthors}{基于公开课程资料整理}
\newcommand{\notedate}{2026 年 3 月 15 日}
\newcommand{\articlechannel}{hoeem}
\newcommand{\articlepublishdate}{2026 年 3 月 15 日}
\newcommand{\articleurl}{https://x.com/hooeem/status/2033198345045336559}


% Footer with repo info
\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhf{}
\fancyfoot[C]{\thepage}
\fancyfoot[R]{\footnotesize\color{gray}\href{\repourl}{AI Course Notes}}
\renewcommand{\headrulewidth}{0pt}
\renewcommand{\footrulewidth}{0pt}

\begin{document}

\begin{titlepage}
\centering
{\Large 文章笔记\par}
\vspace{1.2cm}
{\huge\bfseries \notetitle\par}
\vspace{0.8cm}
{\large \noteauthors\par}
\vspace{0.3cm}
{\large \notedate\par}
\vspace{2cm}

\begin{tcolorbox}[width=0.9\textwidth, colback=black!2!white, colframe=black!60, sharp corners]
\textbf{原文作者}：\articlechannel\par
\textbf{发布日期}：\articlepublishdate\par
\textbf{来源平台}：X (Twitter) Article\par
\textbf{原文链接}：\href{\articleurl}{\nolinkurl{\articleurl}}\par
\textbf{项目主页}：\href{\repourl}{\nolinkurl{\repourl}}\par
\end{tcolorbox}

\vfill

\begin{knowledgebox}{文章背景}
本文基于 Anthropic 官方 Claude Certified Architect 认证考试指南，由作者 hoeem 拆解整理而成。考试本身仅面向 Claude 合作伙伴开放，但其考纲覆盖的知识体系——Claude Code、Agent SDK、API 和 MCP——是构建生产级 AI 应用的核心技能栈。本笔记对原文五大领域进行系统化整理与补充。
\end{knowledgebox}

\end{titlepage}

\tableofcontents
\newpage

%% --- 正文内容开始 --- %%

\section{概述：Claude 架构师知识体系}

Claude Certified Architect 认证考试涵盖五大领域，考察候选人构建生产级 Claude 应用的综合能力。虽然考试仅对合作伙伴开放，但掌握这些知识本身就足以让你构建高质量的 AI 应用。

\begin{importantbox}{考试覆盖的四大核心技术}
\begin{enumerate}[leftmargin=1.5em]
    \item \textbf{Claude Code}：Anthropic 官方 CLI 工具，支持代码生成、CI/CD 集成
    \item \textbf{Claude Agent SDK}：用于构建 agentic 应用的开发套件
    \item \textbf{Claude API}：模型调用接口，含 tool\_use、Batches API 等
    \item \textbf{Model Context Protocol (MCP)}：工具与上下文集成的标准协议
\end{enumerate}
\end{importantbox}

考试要求候选人能够完成以下六类典型项目：

\begin{itemize}[leftmargin=1.5em]
    \item \textbf{客户支持解决 Agent}：Agent SDK + MCP + 升级机制（escalation）
    \item \textbf{Claude Code 代码生成}：CLAUDE.md 配置 + plan mode + slash commands
    \item \textbf{多 Agent 研究系统}：coordinator-subagent 编排模式
    \item \textbf{开发者生产力工具}：内置工具 + MCP servers
    \item \textbf{Claude Code CI/CD}：非交互式管道 + 结构化输出
    \item \textbf{结构化数据抽取}：JSON schemas + tool\_use + 验证循环
\end{itemize}

五大领域的权重分布如下表所示：

\begin{table}[H]
\centering
\begin{tabular}{lcc}
\toprule
\textbf{领域} & \textbf{权重} & \textbf{核心主题} \\
\midrule
Agentic Architecture \& Orchestration & 27\% & Agent 循环、子 Agent 编排 \\
Tool Design \& MCP Integration & 18\% & 工具描述、MCP 协议 \\
Claude Code Configuration \& Workflows & 20\% & CLAUDE.md 层级、规则 \\
Prompt Engineering \& Structured Output & 20\% & Few-shot、tool\_use \\
Context Management \& Reliability & 15\% & 上下文管理、错误传播 \\
\bottomrule
\end{tabular}
\caption{Claude Architect 考试五大领域及权重}
\end{table}

\subsection{本章小结}

Claude 架构师需要同时掌握 Claude Code、Agent SDK、API 和 MCP 四大技术栈。考试通过六类典型项目来检验综合能力，其中 Agentic Architecture 占比最高（27\%），是核心中的核心。

\section{领域一：Agentic 架构与编排（27\%）}

这是权重最高的领域，考察候选人设计和实现 agent 系统的能力，包括 agentic loop 机制、子 Agent 编排以及安全关键场景下的 hook 设计。

\subsection{三大反模式}

考试会直接测试你能否识别以下三个常见的反模式：

\begin{warningbox}{必须立即拒绝的三种 Agent 停止策略}
\begin{enumerate}[leftmargin=1.5em]
    \item \textbf{解析自然语言判断循环终止}：通过分析模型回复的文本内容来决定是否停止循环。这种方式不可靠，因为自然语言具有歧义性。
    \item \textbf{任意迭代次数上限作为主要停止机制}：例如"最多运行 10 轮"。这不是一个语义上合理的终止条件，应基于 \texttt{stop\_reason} 来判断。
    \item \textbf{检查 assistant 文本作为完成指示器}：模型输出文本并不意味着任务完成，正确做法是检查 API 返回的 \texttt{stop\_reason} 字段。
\end{enumerate}
\end{warningbox}

\subsection{子 Agent 的上下文隔离}

\begin{importantbox}{子 Agent 不共享 Coordinator 的内存}
这是原文作者强调的"最大错误"：很多人假设子 Agent（subagent）可以访问 coordinator 的上下文。实际上，\textbf{子 Agent 的上下文是完全隔离的}，所有信息必须通过 prompt 显式传递。
\end{importantbox}

这意味着在设计多 Agent 系统时，你需要：
\begin{itemize}[leftmargin=1.5em]
    \item 明确定义 coordinator 向每个 subagent 传递的信息边界
    \item 在 subagent 的 prompt 中包含所有必要的上下文
    \item 设计清晰的返回值结构，确保 coordinator 能整合各 subagent 的结果
\end{itemize}

\subsection{安全关键场景的 Hook 机制}

\begin{importantbox}{高风险场景必须用程序化 Hook 而非 Prompt 指令}
当涉及金融交易或安全敏感操作时，仅靠 prompt 中的指令是不够的。必须通过 \textbf{hook} 和 \textbf{prerequisite gate} 以编程方式强制执行工具调用顺序。
\end{importantbox}

例如，在一个涉及退款操作的 Agent 中：
\begin{itemize}[leftmargin=1.5em]
    \item 使用 \texttt{PostToolUse} hook 规范化数据格式
    \item 使用工具调用拦截 hook 阻止违反策略的操作
    \item 通过 prerequisite gate 确保在执行退款前必须先完成身份验证
\end{itemize}

\subsection{推荐实践项目}

\begin{knowledgebox}{动手练习：多工具 Agent}
构建一个包含 3--4 个 MCP 工具的 Agent，实现以下功能：
\begin{itemize}[leftmargin=1.5em]
    \item 正确的 \texttt{stop\_reason} 处理
    \item 一个 \texttt{PostToolUse} hook 用于规范化数据格式
    \item 一个工具调用拦截 hook 用于阻止策略违规
\end{itemize}
这一个练习就能覆盖领域一的大部分考点。
\end{knowledgebox}

\subsection{本章小结}

Agentic 架构的核心在于三点：正确使用 \texttt{stop\_reason} 而非自然语言解析来控制 Agent 循环；理解子 Agent 上下文隔离的本质并显式传递信息；在高风险场景中用程序化 hook 而非 prompt 指令来保障安全。

\section{领域二：工具设计与 MCP 集成（18\%）}

本领域聚焦于如何设计高质量的工具描述（tool description）、理解 MCP 协议，以及正确配置 \texttt{tool\_choice} 参数。

\subsection{工具描述是工具选择的核心}

\begin{importantbox}{工具描述决定 Claude 的工具选择行为}
Tool description 是 Claude 用于决定调用哪个工具的\textbf{主要依据}。如果描述模糊或多个工具描述重叠，工具选择将变得不可靠。
\end{importantbox}

原文举了一个典型案例：\texttt{get\_customer} 和 \texttt{lookup\_order} 两个工具的描述过于相似，导致 Claude 经常选错工具。面对这种情况，正确的修复方案不是：
\begin{itemize}[leftmargin=1.5em]
    \item 添加 few-shot 示例（治标不治本）
    \item 构建路由分类器（过度工程）
    \item 合并工具（丧失功能边界）
\end{itemize}
\textbf{正确做法}：重写工具描述，使每个工具的职责边界清晰、不重叠。

\subsection{tool\_choice 参数详解}

\begin{table}[H]
\centering
\begin{tabular}{lp{9cm}}
\toprule
\textbf{选项} & \textbf{行为} \\
\midrule
\texttt{"auto"} & 模型自行决定是调用工具还是直接回复文本 \\
\texttt{"any"} & 模型\textbf{必须}调用某个工具，但由模型选择具体调用哪一个 \\
\texttt{forced selection} & 模型\textbf{必须}调用指定的特定工具 \\
\bottomrule
\end{tabular}
\caption{\texttt{tool\_choice} 三种模式对比}
\end{table}

\subsection{工具数量的上限原则}

\begin{warningbox}{单个 Agent 的工具不应超过 4--5 个}
给一个 Agent 提供 18 个工具会严重降低工具选择的准确率。正确做法是将工具按角色分配给不同的子 Agent，每个子 Agent 只携带 4--5 个与其职责相关的工具。
\end{warningbox}

\subsection{推荐实践项目}

\begin{knowledgebox}{动手练习：工具描述对比实验}
创建两个功能相似的 MCP 工具，故意写模糊的描述使其产生路由错误。然后修复描述，亲身体验描述质量对工具选择的影响。
\end{knowledgebox}

\subsection{本章小结}

工具设计的关键在于：写出清晰、无歧义的工具描述；熟练掌握 \texttt{tool\_choice} 的三种模式及适用场景；控制单个 Agent 的工具数量在 4--5 个以内，通过子 Agent 分工来扩展能力。

\section{领域三：Claude Code 配置与工作流（20\%）}

这个领域考察的是你是否不仅会\textbf{使用} Claude Code，还能为团队\textbf{配置}它。核心概念包括 CLAUDE.md 层级体系、规则目录、plan mode 与 direct execution 的选择。

\subsection{CLAUDE.md 三级层次结构}

\begin{importantbox}{CLAUDE.md 的三个层级}
\begin{enumerate}[leftmargin=1.5em]
    \item \textbf{User-level}：\texttt{\textasciitilde/.claude/CLAUDE.md}——个人配置，不受版本控制，不会与团队共享
    \item \textbf{Project-level}：\texttt{.claude/CLAUDE.md}（或项目根目录的 \texttt{CLAUDE.md}）——项目级配置，随代码库版本控制
    \item \textbf{Directory-level}：子目录中的 \texttt{CLAUDE.md}——仅对该目录及其子目录生效
\end{enumerate}
\end{importantbox}

\begin{warningbox}{考试常见陷阱：User-level 配置不共享}
如果团队成员缺少某些指令，很可能是因为这些指令被放在了 user-level 的 \texttt{CLAUDE.md} 中。由于该文件不受版本控制，其他团队成员不会看到这些配置。团队共享的配置必须放在 project-level。
\end{warningbox}

\subsection{路径特定规则（Path-Specific Rules）}

\begin{knowledgebox}{.claude/rules/ 目录的 Glob 模式}
\texttt{.claude/rules/} 目录支持 YAML frontmatter 中的 glob 模式，例如 \texttt{**/*.test.tsx} 可以将特定约定应用于整个代码库中匹配的文件。这是 directory-level 的 \texttt{CLAUDE.md} 做不到的，因为后者只对所在目录及子目录生效，无法跨目录匹配文件路径模式。
\end{knowledgebox}

\subsection{Plan Mode vs Direct Execution}

\begin{table}[H]
\centering
\begin{tabular}{lp{9cm}}
\toprule
\textbf{模式} & \textbf{适用场景} \\
\midrule
Plan Mode & 单体应用重构、多文件迁移、架构决策等需要全局视角的任务 \\
Direct Execution & 单文件 bug 修复、单个验证检查等范围明确的小任务 \\
\bottomrule
\end{tabular}
\caption{Plan Mode 与 Direct Execution 的适用场景}
\end{table}

\subsection{其他关键概念}

需要掌握的其他 Claude Code 概念：
\begin{itemize}[leftmargin=1.5em]
    \item \textbf{\texttt{context: fork}}：在 skill frontmatter 中使用，隔离冗长输出，避免污染主会话上下文
    \item \textbf{\texttt{-p} flag}：非交互式模式，用于 CI/CD 管道
    \item \textbf{独立审查实例}：用一个新的 Claude Code 实例来审查代码，比在同一个 session 中自我审查效果更好
\end{itemize}

\subsection{推荐实践项目}

\begin{knowledgebox}{动手练习：完整 Claude Code 配置}
创建一个项目，包含：
\begin{itemize}[leftmargin=1.5em]
    \item 完整的 CLAUDE.md 三级层次结构
    \item \texttt{.claude/rules/} 中带 glob 模式的规则文件
    \item 一个使用 \texttt{context: fork} 的 skill
    \item \texttt{.mcp.json} 中配置带环境变量展开的 MCP server
\end{itemize}
然后分别用 plan mode 处理多文件重构，用 direct execution 处理单个 bug 修复，体会两者的区别。
\end{knowledgebox}

\subsection{本章小结}

Claude Code 的团队配置能力是架构师的分水岭。核心要点：理解 CLAUDE.md 的三级层次并将共享配置放在 project-level；利用 \texttt{.claude/rules/} 的 glob 模式实现跨目录的路径特定规则；根据任务范围选择 plan mode 或 direct execution。

\section{领域四：Prompt 工程与结构化输出（20\%）}

这个领域的核心原则只有两个字：\textbf{明确}（be explicit）。

\subsection{模糊指令 vs 明确指令}

\begin{warningbox}{模糊指令无法提升精度}
以下常见指令实际上不起作用：
\begin{itemize}[leftmargin=1.5em]
    \item "Be conservative"——不会真正提升精度
    \item "Only report high-confidence findings"——不会真正减少误报
\end{itemize}
\textbf{有效做法}：精确定义哪些问题应该上报、哪些应该跳过，并为每个严重级别提供具体的代码示例。
\end{warningbox}

\subsection{Few-shot 示例的杠杆效应}

\begin{importantbox}{Few-shot 是考试中测试的最高杠杆技术}
使用 2--4 个精心设计的示例，展示以下内容：
\begin{itemize}[leftmargin=1.5em]
    \item 模糊情况的处理方式
    \item 为什么选择了某个动作而非其他替代方案
    \item 推理过程的展示
\end{itemize}
关键不在于示例数量，而在于选择\textbf{模糊边界案例}（ambiguous cases）作为示例。
\end{importantbox}

\subsection{tool\_use 与 JSON Schema}

\texttt{tool\_use} 配合 JSON schema 可以消除\textbf{语法错误}，但\textbf{无法消除语义错误}。在 schema 设计中需要注意：

\begin{itemize}[leftmargin=1.5em]
    \item \textbf{nullable 字段}：当源数据可能缺失时，使用 nullable 字段而非让模型编造值
    \item \textbf{"unclear" 枚举值}：为模型提供一个"不确定"的选项
    \item \textbf{"other" + detail 字符串}：覆盖预定义枚举之外的情况
\end{itemize}

\subsection{Message Batches API}

\begin{knowledgebox}{Batches API 的特性与适用场景}
\begin{itemize}[leftmargin=1.5em]
    \item 节省 50\% 成本
    \item 处理时间最长 24 小时，无延迟 SLA
    \item 不支持多轮 tool calling
    \item \textbf{适用}：隔夜批量报告生成
    \item \textbf{不适用}：需要阻塞等待结果的 pre-merge 检查（应使用同步 API）
\end{itemize}
\end{knowledgebox}

\subsection{推荐实践项目}

\begin{knowledgebox}{动手练习：结构化数据抽取管道}
构建一个使用 \texttt{tool\_use} 的数据抽取管道：
\begin{itemize}[leftmargin=1.5em]
    \item 定义包含 required、optional 和 nullable 字段的 JSON schema
    \item 实现 validation-retry 循环
    \item 通过 Batches API 批量处理
    \item 按 \texttt{custom\_id} 处理失败情况
\end{itemize}
\end{knowledgebox}

\subsection{本章小结}

Prompt 工程的核心是"明确"：用具体标准替代模糊指令，用 2--4 个边界案例的 few-shot 示例来引导模型行为。结构化输出方面，\texttt{tool\_use} + JSON schema 解决语法问题，nullable 字段和 "unclear" 枚举值解决语义问题。Batches API 适合非实时批量任务。

\section{领域五：上下文管理与可靠性（15\%）}

权重最小的领域，但原文强调"这里的错误会级联到所有其他地方"。

\subsection{渐进式摘要的陷阱}

\begin{warningbox}{渐进式摘要会丢失关键事务数据}
Progressive summarisation（渐进式摘要）会丢失金额、日期、订单号等事务性数据。正确做法是维护一个持久的 \textbf{"case facts" 块}，包含所有提取的关键数据字段，\textbf{永不摘要}，并在每次 prompt 中包含。
\end{warningbox}

\subsection{"Lost in the Middle" 效应}

\begin{importantbox}{关键信息放在开头}
模型容易遗漏埋在长输入中间的内容（"lost in the middle" 效应）。解决方案：将关键摘要和重要发现放在输入的\textbf{开头}位置。
\end{importantbox}

\subsection{升级触发器（Escalation Triggers）}

\begin{table}[H]
\centering
\begin{tabular}{lp{7cm}c}
\toprule
\textbf{触发器} & \textbf{描述} & \textbf{可靠性} \\
\midrule
客户主动请求人工 & 立即执行，不附加条件 & 可靠 \\
策略空白 & Agent 遇到规则未覆盖的情况 & 可靠 \\
无法推进 & Agent 无法继续完成任务 & 可靠 \\
\midrule
情绪分析 & 基于客户情绪判断是否升级 & \textbf{不可靠} \\
自报置信度分数 & 模型自己报告的置信度 & \textbf{不可靠} \\
\bottomrule
\end{tabular}
\caption{升级触发器的可靠性对比}
\end{table}

\begin{warningbox}{考试陷阱：不可靠的升级触发器}
情绪分析（sentiment analysis）和模型自报置信度分数（self-reported confidence scores）是考试中常见的干扰选项。它们看起来合理，但实际上不够可靠，不应作为升级触发条件。
\end{warningbox}

\subsection{错误传播的正确方式}

正确的错误传播应包含结构化上下文：
\begin{itemize}[leftmargin=1.5em]
    \item 失败类型（failure type）
    \item 尝试的查询（attempted query）
    \item 部分结果（partial results）
    \item 替代方案（alternatives）
\end{itemize}

两种必须避免的反模式：
\begin{itemize}[leftmargin=1.5em]
    \item 静默吞掉错误（silently suppressing errors）
    \item 因单个失败而终止整个工作流（killing entire workflows on single failures）
\end{itemize}

\subsection{推荐实践项目}

\begin{knowledgebox}{动手练习：错误传播与部分结果}
构建一个包含两个子 Agent 的 coordinator 系统：
\begin{itemize}[leftmargin=1.5em]
    \item 模拟一个子 Agent 超时
    \item 验证 coordinator 能收到结构化的错误上下文
    \item 确认 coordinator 能基于部分结果继续推进
    \item 测试面对冲突信息源时的处理逻辑
\end{itemize}
\end{knowledgebox}

\subsection{本章小结}

上下文管理的关键要点：用持久化的 "case facts" 块替代渐进式摘要来保留事务数据；利用 "lost in the middle" 效应的规律将关键信息前置；仅使用可靠的升级触发器（客户请求、策略空白、无法推进）；错误传播要结构化，既不静默吞掉也不因单点失败而全面崩溃。

\section{总结与延伸}

\subsection{五大领域核心要点回顾}

\begin{enumerate}[leftmargin=1.5em]
    \item \textbf{Agentic 架构}（27\%）：基于 \texttt{stop\_reason} 的循环控制、子 Agent 上下文隔离、程序化 hook 保障安全
    \item \textbf{工具设计与 MCP}（18\%）：清晰的工具描述、合理的 \texttt{tool\_choice} 配置、每个 Agent 4--5 个工具的上限
    \item \textbf{Claude Code 配置}（20\%）：三级 CLAUDE.md 层次、glob 模式规则、plan mode vs direct execution
    \item \textbf{Prompt 工程}（20\%）：明确指令、边界案例 few-shot、\texttt{tool\_use} + JSON schema、Batches API
    \item \textbf{上下文管理}（15\%）：持久化 case facts、信息前置、可靠升级触发器、结构化错误传播
\end{enumerate}

\subsection{Anthropic 官方推荐学习资源}

\begin{enumerate}[leftmargin=1.5em]
    \item \textbf{Building with the Claude API}——API 基础与高级用法
    \item \textbf{Introduction to Model Context Protocol}——MCP 协议入门
    \item \textbf{Claude Code in Action}——Claude Code 实战演示
    \item \textbf{Claude 101}——Claude 基础知识
\end{enumerate}

\subsection{学习建议}

\begin{importantbox}{从实践项目入手}
每个领域都配有一个推荐实践项目。建议按以下顺序完成：
\begin{enumerate}[leftmargin=1.5em]
    \item 先完成领域一的多工具 Agent 项目（覆盖面最广）
    \item 然后是领域三的 Claude Code 配置项目（直接提升日常效率）
    \item 再完成领域二和四的工具描述与数据抽取项目
    \item 最后完成领域五的错误传播项目（整合前四个领域的知识）
\end{enumerate}
\end{importantbox}

正如原文作者所言：你不需要证书来构建生产级应用，你需要的是知识本身。掌握这五大领域的核心概念并通过实践项目内化，你就具备了成为 Claude 架构师的能力。

%% --- 正文内容结束 --- %%

\end{document}
