Claude认证备考：掌握SDK与Hooks构建真实应用

拿到 Claude 相关认证的备考资料，很多人第一反应是去背提示词模板、研究 few-shot 示例。但做到第六部分，我想先纠正一个可能影响你成绩的判断：认证考试真正要验证的，不是你“会不会和 Claude 聊天”，而是你“能不能用 Claude 构建真实应用”。而构建真实应用的第一道门槛，就是 SDK 和 Hooks。

这篇文章是“Zero to Claude Certified Architect — Complete Beginner’s Guide”系列的第 6 部分，围绕两个关键词展开：SDK 与 Hooks。它们既是认证考试里的高频考点，也是实际项目中出错率最高的两个环节。读完你会得到四样东西：第一，搞清楚官方 SDK 是什么、为什么不能只停留在网页聊天框；第二，亲手跑通 Python 和 TypeScript 两套 SDK 的调用流程；第三，在 Claude Code 里配置 Hooks，理解 PreToolUse、PostToolUse 这些生命周期钩子到底在什么时机运行；第四，一份可以直接拿去复习的考点清单和排错台账。

先说结论：SDK 本身不难，难的是意识到它和直接拼 HTTP 请求之间的工程差异；Hooks 也不难，难的是理解它本质上是一种“可编程的自动化边界”。把这两件事想明白，你的认证备考会少走很多弯路。

1. 为什么 SDK 和 Hooks 是认证备考必须拿下的部分

Claude Certified Architect 这类认证，考核重点从公开的认证体系介绍来看，核心是“架构设计能力”和“工程落地能力”。这意味着考试不会只问你“Claude 的上下文窗口是多少”，而是会考察你是否理解从业务需求到 Claude 能力之间的整个技术链路。SDK 就是这个链路的第一环。

很多初学者会有一种错觉：既然 Claude 有网页版，也有 API，那我直接用网页不就行了？在原型验证阶段确实可以，但一旦进入真实项目，你需要面对的是认证、限流、重试、日志、版本管理、批量任务、工具调用等一系列工程问题。官方 SDK 把这些公共问题封装好了，让你能把注意力放在业务逻辑上。认证考试恰好就是要验证你有没有这种“工程化使用”的思维，而不是停留在“提示词写得好不好”的层面。

Hooks 则是另一个维度的能力。Claude Code 作为终端里的 Agent 工具，已经能完成写代码、跑命令、读文件、操作 Git 等任务。但企业要把它接入正式的研发流程，必须解决一个核心问题：如何审计和控制 Agent 的行为。Hooks 提供的就是这种控制能力。你可以在 Claude 执行工具调用之前插入一段命令做审批，也可以在它读取敏感文件之后写出审计日志。这种“可编程的自动化边界”能力，正是架构师和普通用户之间的重要区别。

所以，第六部分把 SDK 和 Hooks 放在一起讲，不是随机组合，而是因为它们共同代表了一个学习阶段的分水岭：从“会用 Claude”到“能设计和维护一个由 Claude 驱动的软件系统”。如果你正在备考认证，或者准备把 Claude 接入自己的项目，这一篇值得认真读完。

2. 基础概念：Claude SDK 到底是什么

SDK 的全称是 Software Development Kit，也就是软件开发工具包。它的本质是对底层 API 的一层封装，让你不用自己手写 HTTP 请求、处理 JSON 序列化、管理鉴权头，而是直接用熟悉的编程语言调用函数或方法。

2.1 SDK 与 API 的关系

用一个通俗类比：API 是餐厅的菜单，规定了有哪些菜、每道菜什么价格、怎么下单；SDK 则是餐厅提供的预制调料包，已经把葱姜蒜切好、比例配好，你只需要按说明倒进锅里就行。

直接调 Claude API 时，你需要自己构造 HTTP 请求：

curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-3-5-sonnet-latest", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}] }'

这个方式不是不能用，但问题很快会出现：你需要自己管理超时重试、错误码解析、流式响应解析、请求日志，还要在多个语言环境中重复实现同一套逻辑。SDK 把这些细节全部收敛了。以 Python 为例，同样的请求只需要几行代码：

import anthropic client = anthropic.Anthropic() response = client.messages.create( model="claude-3-5-sonnet-latest", max_tokens=1024, messages=[{"role": "user", "content": "Hello"}] ) print(response.content[0].text)

两者的差异，就是“手工拼 HTTP”和“调用封装好的函数”的差异。认证考试之所以围绕 SDK 出题，是因为 Anthropic 官方希望开发者采用这种更可靠、更可维护的集成方式。

2.2 官方 SDK 支持哪些语言

Anthropic 官方维护了两套 SDK：Python SDK 和 TypeScript SDK。包名分别是anthropic和@anthropic-ai/sdk。两套 SDK 的功能基本对齐，都支持消息创建、流式响应、工具调用、视觉模型、长上下文等能力。

这意味着你在备考时，最好至少精通其中一种。不需要两种都深入，但要能理解两种语言的调用逻辑在结构上是对称的：创建客户端、构造参数、调用 messages.create、处理返回。掌握这个对称结构，即使考试里出现另一种语言的伪代码，也能快速读懂意图。

2.3 为什么不建议自己封装 API

有读者可能会问：既然只是封装，那我用 Requests 或者 Axios 自己封装一套行不行？技术上可行，但不推荐。原因是认证考试和生产项目都默认你使用官方 SDK，它持续跟进模型更新、参数变更、API 版本兼容，这些维护成本自己扛并不划算。

从认证的角度看，官方 SDK 的使用方式本身就是考试大纲的一部分。很多考点，比如max_tokens是否必传、system提示放在哪个位置、流式响应对应的回调方法，都是围绕 SDK 的具体用法设计的。你只有亲自用 SDK 跑通过代码，才能对这些细节有肌肉记忆。

3. Hooks 的核心概念与适用场景

Hooks 在不同的技术语境里含义不同。在 React 里，Hooks 是管理组件状态的函数；在 Git 里，Hooks 是提交前后触发的脚本。在 Claude 生态里，Hooks 特指 Claude Code 提供的一种生命周期回调机制，它允许你在 Claude Code 运行过程中的特定节点，自动执行 shell 命令。

3.1 Hooks 到底是干什么的

Claude Code 是一个运行在终端里的 AI 编程助手。它可以读取你的项目文件、执行 Bash 命令、编写代码、操作 Git。能力很强，但随之而来的问题是：谁来保证它不会在你不希望的时候执行某些危险命令？谁来记录它到底做了什么？

Hooks 就是为了解决这个问题而设计的。它让你可以在 Claude Code 的生命周期中插入自己的命令。比如：

• 在 Claude 执行任何 Bash 工具之前，先弹出一个确认窗口，或者先检查命令是否在黑名单里；
• 在 Claude 读取文件之后，记录它读了哪些文件，方便审计；
• 在用户提交提示词之后，做内容过滤或转发到日志系统；
• 在 Claude 即将停止运行的时候，发送通知。

换句话说，Hooks 把 Claude Code 从“一个交互式工具”变成了“一个可以嵌入到工程流程的自动化组件”。这是 Agent 类工具在企业环境落地的关键能力。

3.2 五种内置 Hook 事件

在 Claude Code 的官方配置中，常用的 Hook 事件包括以下五类：

需要特别注意的是 PreToolUse 和 PostToolUse 都带matcher概念。你可以通过 matcher 指定只对某个工具生效，比如只拦截 Bash 工具，或者只监听 Read 工具。这样 Hook 的执行范围是可控的，不会给每一次调用都增加额外开销。

3.3 与 API 流式事件的区别

容易混淆的一点是：Claude API 本身也有类似“事件”的概念，比如流式响应中的message_start、content_block_delta。这些是 API 事件，用来描述模型输出过程的状态；而 Hooks 是 Claude Code 层面的配置，用来控制 Agent 工具的行为。前者是数据流的一部分，后者是工程控制的一部分。

你在认证备考时要分清这两条线：API 的流式事件属于 SDK 调用范畴，Hooks 则属于 Claude Code 工程化配置范畴。两种都是考点，但考察侧重点完全不同。

4. Python SDK 环境搭建与首次调用

讲完概念，我们进入实操。先从 Python SDK 开始。这一节的目标是让零基础读者也能照着跑通第一个 Claude 调用。

4.1 环境准备

需要准备的环境如下：

• Python 3.8 及以上版本
• pip 包管理工具
• 一个有效的 Anthropic API Key

先确认 Python 版本：

python --version

如果版本低于 3.8，建议先升级 Python 环境，再继续后面的步骤。

安装官方 SDK：

pip install anthropic

安装完成后，可以验证版本：

pip show anthropic

这里提醒一点：国内网络环境下 pip 可能较慢，如果下载超时，可以临时使用镜像源，但要注意镜像源的更新速度是否能跟上官方发布节奏。

4.2 配置 API Key

API Key 是调用 Claude 接口的身份凭证。出于安全考虑，不要把它写死到代码里。推荐的方式是使用环境变量。

在 Linux 或 macOS 终端中执行：

export ANTHROPIC_API_KEY="sk-ant-你的密钥"

在 Windows PowerShell 中执行：

$env:ANTHROPIC_API_KEY="sk-ant-你的密钥"

如果希望持久化配置，可以把这行写入 shell 的配置文件，比如~/.bashrc或~/.zshrc。这样每次打开终端环境变量都会自动加载。

4.3 最小可运行示例

创建一个文件claude_quickstart.py，输入下面的代码：

# 文件路径：claude_quickstart.py import os import anthropic # 从环境变量读取 API Key api_key = os.environ.get("ANTHROPIC_API_KEY") if not api_key: raise ValueError("请先设置 ANTHROPIC_API_KEY 环境变量") client = anthropic.Anthropic( api_key=api_key, ) response = client.messages.create( model="claude-3-5-sonnet-latest", max_tokens=1024, system="你是一名资深的软件架构师助教，回答问题简洁、清晰。", messages=[ {"role": "user", "content": "请用三句话说明 SDK 和 API 的关系。"} ] ) print("模型版本:", response.model) print("回复内容:", response.content[0].text)

运行方式：

python claude_quickstart.py

如果一切正常，会看到类似下面的输出：

模型版本: claude-3-5-sonnet-latest 回复内容: SDK 是对 API 的封装，它提供了更方便的编程接口...

这段代码里有几个关键参数需要理解：

• model：指定使用的模型版本。实际项目里建议把模型版本放到配置中心或环境变量里，方便后续升级。
• max_tokens：指定生成的最大 token 数。注意在 Claude API 中，它是必传参数，不能省略。
• system：系统提示词，用于设定模型的行为边界和角色。
• messages：对话消息列表。role可以是user或assistant，用来模拟多轮对话。

运行失败时先做三件事：第一，检查 API Key 是否已经导出，echo $ANTHROPIC_API_KEY看一下；第二，确认anthropic包安装成功；第三，检查网络是否能正常访问 Anthropic API 服务。

4.4 流式输出

网页版 ChatGPT 的效果是逐字输出，而不是一次性等待完整结果。这种体验来自流式响应。SDK 也支持同样的能力：

# 文件路径：claude_stream_demo.py import anthropic client = anthropic.Anthropic() with client.messages.stream( model="claude-3-5-sonnet-latest", max_tokens=512, messages=[ {"role": "user", "content": "用一句话总结什么是 Hooks。"} ], ) as stream: for text in stream.text_stream: print(text, end="", flush=True)

流式输出的好处有两个：对用户来说，首字延迟明显降低，体验更好；对开发者来说，可以在内容生成过程中就做实时处理，比如边生成边翻译、边生成边保存。

5. TypeScript SDK 环境搭建与首次调用

如果你做前端或 Node.js 服务端开发，官方也提供了对应的 TypeScript SDK。这一节我们用相同的最小示例跑通 TypeScript 调用流程。

5.1 环境准备

需要准备的环境如下：

• Node.js 14 及以上版本
• npm 或 yarn

确认 Node 版本：

node --version

新建一个项目目录并初始化：

mkdir claude-ts-demo cd claude-ts-demo npm init -y

安装 SDK 和 TypeScript 相关依赖：

npm install @anthropic-ai/sdk npm install --save-dev typescript tsx @types/node

tsx是一个 TypeScript 直接运行工具，方便我们快速测试脚本，不需要先手动编译。

5.2 配置 API Key

与上节一致，使用环境变量。在package.json的 scripts 里配置会依赖系统环境变量，这里推荐直接在当前终端导出。

5.3 最小可运行示例

创建claude_quickstart.ts：

// 文件路径：claude_quickstart.ts import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY, }); async function main() { const response = await client.messages.create({ model: 'claude-3-5-sonnet-latest', max_tokens: 1024, system: '你是一名资深的软件架构师助教，回答问题简洁、清晰。', messages: [ { role: 'user', content: '请用三句话说明 Hooks 在 Agent 自动化中的作用。' }, ], }); console.log('模型版本:', response.model); console.log('回复内容:', response.content[0].text); } main().catch((err) => { console.error('调用失败:', err); process.exit(1); });

运行方式：

ANTHROPIC_API_KEY="你的密钥" npx tsx claude_quickstart.ts

在 Windows PowerShell 下可以这样运行：

$env:ANTHROPIC_API_KEY="你的密钥" npx tsx claude_quickstart.ts

TypeScript SDK 的整体调用结构和 Python SDK 非常相似。区别主要体现在语言类型系统上：TypeScript 的请求参数和响应类型都是强类型的，IDE 能给出更友好的自动补全。这在大型项目里是一个显著优势，很多编译期就能发现的错误，用 JavaScript 写的话要等到运行时才能暴露。

5.4 流式输出

TypeScript SDK 的流式调用写法如下：

// 文件路径：claude_stream_demo.ts import Anthropic from '@anthropic-ai/sdk'; const client = new Anthropic(); async function main() { const stream = await client.messages.create({ model: 'claude-3-5-sonnet-latest', max_tokens: 512, messages: [ { role: 'user', content: '用一句话总结什么是 SDK。' }, ], stream: true, }); for await (const event of stream) { if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') { process.stdout.write(event.delta.text); } } } main().catch((err) => { console.error(err); process.exit(1); });

注意这里stream: true是显式开启流式模式。SDK 在底层收到的是分块的 HTTP 流，代码里通过for await逐段消费，事件类型需要先判断content_block_delta，再读取delta.text。这个判断逻辑在面试和考试中都属于高频细节。

6. Hooks 实战：在 Claude Code 中配置生命周期钩子

SDK 部分解决了“程序怎么调用 Claude”的问题，Hooks 部分则解决“Claude Code 怎么受控地执行任务”的问题。这一节我们直接在 Claude Code 项目里配置 Hooks。

6.1 配置文件位置

Claude Code 的 Hooks 配置放在项目级设置文件.claude/settings.json中。如果你还没有这个文件，手动创建即可。

mkdir -p .claude touch .claude/settings.json

注意：.claude目录通常应该提交到 Git 仓库，让团队共享同一套 Hooks 规则。但如果你在里面存放了本地私有密钥，则要把密钥部分放到.claude/settings.local.json，并且把该文件加入.gitignore。

6.2 示例：PreToolUse 命令审批日志

先做一个最实用的场景：当 Claude 准备执行 Bash 命令时，把命令内容记录到日志文件。

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "echo \"准备执行命令：$(echo \"$CLAUDE_TOOL_USE_INPUT\" | jq -r '.input.command')\" >> /tmp/claude-pre-tool.log" } ] } ] } }

配置说明：

• matcher是Bash，表示只对 Bash 工具生效；
• $CLAUDE_TOOL_USE_INPUT是 Claude Code 注入的环境变量，内容是一个 JSON 字符串，包含工具名称和输入参数；
• 通过jq从 JSON 中提取出实际的命令内容；
• 把命令追加写入/tmp/claude-pre-tool.log。

保存配置后，重新进入 Claude Code 会话，让 Claude 执行一条命令，比如ls -la，然后打开日志文件查看：

cat /tmp/claude-pre-tool.log

应该能看到类似下面的输出：

准备执行命令：ls -la

这说明 Hook 成功拦截并记录了这次 Bash 调用。

6.3 示例：PostToolUse 文件读取审计

再来看 PostToolUse 场景。假设你想知道 Claude 在会话过程中读取了哪些项目文件，可以为 Read 工具配置一个审计 Hook。

{ "hooks": { "PostToolUse": [ { "matcher": "Read", "hooks": [ { "type": "command", "command": "echo \"$(date) 读取文件: $(echo \"$CLAUDE_TOOL_USE_INPUT\" | jq -r '.input.file_path')\" >> /tmp/claude-read-audit.log" } ] } ] } }

在这个配置中：

• Hook 在 Read 工具执行完成之后触发；
• 从$CLAUDE_TOOL_USE_INPUT中解析出file_path字段；
• 同时记录当前时间，方便追溯时间线。

这个场景在企业里非常实用：当多个开发者共享同一个 Claude Code 工作区时，文件读取审计可以帮你确认 Claude 是否访问了你不希望它访问的敏感文件。

6.4 示例：UserPromptSubmit 提示词存档

第三个场景是针对用户输入做存档。企业如果想对 AI 辅助编程过程做质量回溯，把用户提示词记录下来是最简单的手段。

{ "hooks": { "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "echo \"$(date) 用户输入: $(echo \"$CLAUDE_USER_PROMPT\" | head -c 500)\" >> /tmp/claude-prompt-archive.log" } ] } ] } }

与工具相关 Hook 不同，UserPromptSubmit不需要matcher，因为它的触发点是用户消息提交事件。环境变量$CLAUDE_USER_PROMPT保存了用户输入的文本内容。

6.5 验证 Hooks 是否生效

验证 Hooks 是否生效，有一个通用套路：先看日志文件有没有生成，再看内容是否符合预期。如果日志文件没有出现，优先检查以下几点：

• .claude/settings.json的 JSON 格式是否合法；
• matcher是否写了正确的工具名称，工具名称大小写敏感；
• Hook 命令里使用的命令是否存在于系统 PATH 中，比如jq是否安装；
• 是否重新启动了 Claude Code 会话，配置文件的修改有时需要重启才能加载。

如果命令执行失败，Claude Code 通常会在会话中显示 Hook 的错误输出。看到错误时先读错误信息，不要盲目改配置。

7. 工具调用与 Hooks 的联动

理解 Hooks 之后，再回看 Claude API 里的工具调用机制，你会发现两条线索其实是一体的：API 层定义了“模型怎么描述它想要调用工具”，Hooks 层定义了“Claude Code 怎么在真实系统里执行这些工具”。

7.1 API 层：tools 参数

在 Claude API 中，你可以给模型声明一组工具。模型在需要时会返回工具调用请求，而不是直接回答。

# 文件路径：claude_tool_demo.py import anthropic client = anthropic.Anthropic() tools = [ { "name": "get_weather", "description": "获取指定城市的实时天气信息", "input_schema": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名，例如：北京" } }, "required": ["city"] } } ] response = client.messages.create( model="claude-3-5-sonnet-latest", max_tokens=512, tools=tools, messages=[ {"role": "user", "content": "北京今天天气怎么样？"} ] ) print(response.content)

模型可能返回类似下面的结果：

{ "type": "tool_use", "name": "get_weather", "input": { "city": "北京" } }

这不是模型直接回答天气，而是模型表示“我需要调用 get_weather 工具”。真正的业务逻辑要由你来实现调用，并把结果回传给模型。

7.2 Hooks 层：工具调用的控制边界

在 Claude Code 中，工具调用的逻辑则由 Hooks 来控制。你可以让某个工具在特定项目中被完全禁用：

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "echo \"$CLAUDE_TOOL_USE_INPUT\" | jq -e '.input.command | contains(\"rm -rf\")' >/dev/null && exit 2 || exit 0" } ] } ] } }

这里解释一下逻辑：Hook 命令检查即将执行的 Bash 命令里是否包含rm -rf，如果匹配到，就退出码 2，告诉 Claude Code 阻止这次调用；如果没有匹配到，就退出码 0，放行。

在真实的研发环境里，这种“命令黑名单”很有价值。你可以把git push --force、rm -rf /、shutdown这类高风险操作加入拦截名单，避免 Claude 在无人监督时执行破坏性命令。

7.3 架构视角：为什么工具调用是认证核心

从架构师视角看，工具调用能力决定了 Claude 能做什么。没有工具调用，Claude 只是一个文本生成器；有了工具调用，Claude 才能成为能操作数据库、调用第三方接口、部署服务的 Agent。而 Hooks 则为工具调用提供了安全管理层。认证考试考察工具调用，本质上是在考察你是否具备设计和管控 Agent 行为的能力。

这部分往往是备考者容易忽略的：只关注提示词，不关注工具调用协议和 Hooks 配置。结果就是，考试中一旦出现“如何限制模型执行危险命令”这类综合题，就不知道从哪里入手。

8. 认证备考：SDK 与 Hooks 的高频考点与易错点

这一节回到备考本身。下面是根据认证体系公开的能力要求和实际技术实践整理出的高频考点与易错点，供复习时对照。

8.1 SDK 常见考点

• messages.create的基本参数结构：model、max_tokens、messages、system各自的作用；
• max_tokens是必传还是非必传，不同模型的默认行为；
• 流式事件类型：message_start、content_block_start、content_block_delta、message_stop分别代表什么；
• 多轮对话如何传递历史消息；
• 错误状态码的含义：400 请求错误、401 鉴权失败、429 限流、529 服务过载；
• 工具调用参数tools的定义格式，特别是input_schema的 JSON Schema 写法。

8.2 Hooks 常见考点

• 五种 Hook 事件对应的触发时机；
• PreToolUse和PostToolUse的区别；
• matcher的作用和大小写敏感性；
• Hook 命令退出码对 Claude Code 行为的影响；
• Hook 注入的环境变量：CLAUDE_TOOL_USE_INPUT、CLAUDE_TOOL_USE_RESULT、CLAUDE_USER_PROMPT、CLAUDE_FILE_PATHS；
• Hooks 配置的两个层级：项目级配置和用户级配置。

8.3 高频易错点

说实话，这些易错点几乎都是真实开发中踩过的坑。备考时把这些点背下来，效果比死记硬背 API 文档要好得多。

9. 常见问题与排查方法

整理一套排错台账，遇到问题时按照表格中的顺序逐步排查。

上面的排查思路有一个共同点：先看日志，再看环境变量，最后才怀疑 SDK 本身。遇到问题不要急于改代码，先把错误信息完整读一遍。

10. 最佳实践与工程建议

通过认证考试只是起点，把 Claude 可靠地接入生产系统才是最终目标。下面这些工程建议，来自日常使用 Anthropic SDK 和 Claude Code 的常见经验。

10.1 API Key 与环境变量管理

永远不要把 API Key 硬编码到代码里。开发环境使用.env文件配合python-dotenv或 Node.js 的dotenv加载；生产环境使用云厂商的密钥管理服务或 CI/CD 平台的密钥变量。密钥泄露后要第一时间在控制台吊销并重新生成。

10.2 统一模型配置

模型名称不要散落在业务代码的各个角落。建议通过配置中心或环境变量统一管理，例如：

claude.model=claude-3-5-sonnet-latest claude.max_tokens=1024 claude.temperature=0.7

这样升级模型版本时，只需要修改一处配置，不需要改动业务代码。

10.3 错误处理与重试

网络请求不是 100% 可靠的。建议封装一层统一的 Claude 调用函数，集中处理 429、529 和网络超时。重试时使用指数退避，并加入随机抖动，避免多个请求同时重试造成雪崩。

# 文件路径：claude_safe_call.py import time import anthropic client = anthropic.Anthropic() def safe_call(messages, max_retries=3): for attempt in range(max_retries): try: return client.messages.create( model="claude-3-5-sonnet-latest", max_tokens=1024, messages=messages, ) except anthropic.RateLimitError: wait = 2 ** attempt + 0.1 print(f"触发限流，{wait:.1f} 秒后重试") time.sleep(wait) raise RuntimeError("重试多次仍失败")

这段代码通过捕获RateLimitError并指数退避重试，显著提升了调用稳定性。实际项目中还可以把额度异常告警接入监控系统。

10.4 Hooks 配置的团队协作规范

Hooks 配置放在.claude/settings.json里，建议团队约定统一规范：

• 日志文件统一写到项目的临时目录，不要直接抛到仓库根目录；
• 涉及敏感信息的命令不要写到团队共享的配置里，使用settings.local.json；
• 每个 Hook 命令保持单一职责，避免一个命令做太多事；
• Hook 脚本较长时，应该抽成独立脚本文件，配置里只写调用入口。

例如把命令审批逻辑抽成脚本：

# 文件路径：scripts/check_bash_command.sh #!/bin/bash input_json="$CLAUDE_TOOL_USE_INPUT" command_str=$(echo "$input_json" | jq -r '.input.command') if echo "$command_str" | grep -qE "rm -rf|git push --force"; then echo "检测到高危命令，已阻止执行" exit 2 fi exit 0

然后在settings.json中引用：

{ "hooks": { "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "bash scripts/check_bash_command.sh" } ] } ] } }

这样维护成本大大降低，团队新人也能看懂 Hooks 在做哪些安全检查。

10.5 日志与可观测性

无论是在 SDK 调用层还是 Claude Code Hooks 层，都要有日志意识。至少记录：调用时间、模型版本、输入消息摘要、响应 token 数、耗时、是否触发重试。Hooks 层的日志建议包含工具名称、触发前后信息、最终放行或拦截结果。没有日志，生产环境出了问题基本只能靠猜。

10.6 版本与回归测试

SDK 更新很快，模型版本也在持续迭代。建议在 CI 中保留一组回归测试用例，覆盖核心提示词、工具调用、流式输出三条链路。升级 SDK 或切换模型后先跑一遍回归用例，确认没有破坏现有功能再合入代码。

11. 总结与下一步方向

这一篇讲了 Claude Certifited Architect 备考路上绕不开的两个知识点：SDK 和 Hooks。核心脉络可以概括为三条：

第一，SDK 是工程化使用 Claude 的第一层底座。官方 Python 和 TypeScript SDK 帮你封装了 API 调用的公共复杂性，备考时要能熟练写出最小调用示例，并理解请求参数、流式事件和错误处理。

第二，Hooks 是 Claude Code 自动化能力的安全阀和遥控器。PreToolUse、PostToolUse、UserPromptSubmit 这些生命周期钩子，让你能在 Agent 执行动作的各个节点插入自己的命令。它解决的不是“能不能用 Claude”，而是“能不能可控地用好 Claude”。

第三，工具调用与 Hooks 的联动，是架构师视角下最值得深入的方向。API 层让模型具备调用工具的意图，Hooks 层让真实系统的执行过程可控。两者组合起来，Claude 才真正具备落地到生产环境的能力。

下一步学习建议：先照着第四、五、六节的代码完整跑一遍，再做三个小练习。第一个练习是给 Python SDK 加上自定义重试和日志；第二个练习是给 Claude Code 配置一个拦截git push --force的 PreToolUse Hook；第三个练习是封装一个带工具调用的天气查询函数，让 Claude 先返回工具调用请求，再根据工具结果生成最终回复。三个练习做完，这一部分的知识就基本消化了。

SDK 和 Hooks 是硬功夫，没有太多捷径，但也不需要什么天赋。把示例代码亲手敲一遍，把配置文件的每个字段查一遍，再回到认证大纲对照一遍，你会发现考试里的很多题目，其实考察的就是这些平时最容易忽略的工程细节。建议收藏这篇作为备考和日常开发的对照手册，遇到问题随时回来翻排错台账。