Scenario 4 · 主考 Domain 2 / 3 / 1
S4 · Developer Productivity with Claude
陌生代码库探索：built-in tools 与 MCP 的分工
官方设定：用 Claude Agent SDK 构建开发者生产力工具。agent 帮工程师探索陌生代码库、理解遗留系统、生成样板代码、自动化重复任务；它使用 built-in tools（Read、Write、Bash、Grep、Glob）并集成 MCP 服务器。
这个场景没有官方样题 — 12 道样题分布在 S1、S2、S3 与 CI 场景上，S4 与 S6 没有。这不代表它们不考——4 个场景从 6 个里随机抽，S4 被抽中的概率与其他场景相同。没有样题反而意味着只能靠 TS 的原文去推题，所以本章的坑位地图比其他场景更贴着 TS 2.4、TS 2.5、TS 5.4 的措辞写。
一、从零设计：工具箱的三层
第一层：built-in tools 的机械分工
| 要做的事 | 用哪个 | 为什么不是别的 |
|---|---|---|
| 找某个函数的所有调用方 / 定位报错文本 / 找 import | Grep | 这是内容搜索 |
按名字或扩展名找文件（**/*.test.tsx） | Glob | 这是路径模式匹配 |
| 需要整份文件内容 | Read / Write | — |
| 局部定点修改 | Edit | 依赖唯一锚文本；不唯一就会失败 |
Edit 因锚文本不唯一失败后 | Read + Write | guide 明写的 fallback |
第二层：探索的顺序
陌生代码库不能上来读全库。官方给的顺序是增量式的：Grep 找入口 → Read 顺着 import 追踪流程。 追踪 wrapper 模块里的函数使用则另有规程：先列出全部导出名，再逐个名字全库搜索——只搜原始函数名会漏掉重新导出后改名的调用点。
第三层：MCP 补足 built-in 做不了的事
项目级 .mcp.json 放团队共享的服务器，凭证用 ${VAR} 环境变量展开；个人实验服务器放 ~/.claude.json。 标准集成（如 Jira）优先用社区已有的服务器，自建只留给团队特有流程。
二、上线：三次踩坑
① agent 放着更强的 MCP 工具不用
你接了一个懂符号图的 search_code_semantic，agent 却几乎总是用 built-in 的 Grep。根因通常在描述：MCP 工具的描述太简陋，给不出选它的理由。增强 MCP 工具描述，详细说明能力与输出，防止 agent 偏好 built-in 工具。
② 30 次探索调用才开始干活
agent 每次会话开头都在试探「有哪些表、哪些字段、哪些队列」。MCP resources 就是为此设计的——把内容目录（issue 摘要、文档层级、数据库 schema）暴露出来，减少探索性工具调用。
③ 接了三个服务器之后工具选不准了
所有已配置 MCP 服务器的工具在连接时被发现并同时可用——三个服务器各 6 个工具就是 18 个，正好是 guide 用来举反例的数字。 控制手段不是少接服务器，而是按角色收敛工具集（4–5 个），跨角色需求经 coordinator。
三、修复之后：让长探索可恢复
① 长探索之后开始胡说
症状很具体：答案前后不一致，并且引用「典型模式」而不是它先前发现的具体类。 三个对策：scratchpad 文件持久化关键发现、subagent 委派隔离冗长探索输出（主 agent 只做高层协调）、/compact 压缩已经堆积的发现输出。
② 跑了 40 分钟然后进程挂了
多 agent 的探索要设计崩溃恢复：每个 agent 把状态导出到已知位置，coordinator 在 resume 时加载 manifest 并注入 agent prompt。 注意它与 --resume 不在同一层——后者续接一条会话，manifest 恢复的是整个多 agent 系统的进度。
四、坑位地图
| 决策点 | 正确直觉 | 常见干扰项工艺 |
|---|---|---|
| 1. 搜内容还是找文件 | 内容 → Grep；路径模式 → Glob | D2 用 Glob 列全部文件再逐个 Read |
2. Edit 锚不唯一 | 退回 Read + Write | D2 绕到 Bash 用 sed 行号；D5 反复重试同一个 Edit |
| 3. 陌生代码库起步 | Grep 找入口 → Read 顺 import 追踪 | D2 上来读全库；D3 按字母序逐文件 |
| 4. wrapper 重导出 | 先列全部导出名，再逐名全库搜 | D3 只搜原函数名；D5 改名靠编译错误枚举 |
| 5. agent 偏好 built-in | 增强 MCP 工具描述 | D2 删掉 Grep；D6 在 system prompt 里写偏好指令 |
| 6. 大量探索性调用 | 把目录暴露成 MCP resources | D3 加一个 describe_everything 工具；D3 把 schema 抄进 CLAUDE.md |
| 7. 工具过多 | 按角色 scoped 到 4–5 个 | D4 断开服务器；D1 用 tool_choice: "any" 缩小候选 |
| 8. 长会话退化 | scratchpad + subagent 隔离 + /compact | D3 换更大 context window；D3 降 temperature |
外部课程 · CertSafari — 本章 7 个考点（展开查看）
用于补读和错题复盘；第三方 AI 生成练习材料，非官方题库。核验答案时以 Exam Guide 和官方文档为依据。复盘方法 · 链接核对：2026-10-16。
- TS 1.3 · Spawning Subagents: the Agent (Task) Tool and AgentDefinition
- TS 2.1 · Tool Descriptions: How Claude Chooses Which Tool to Call
- TS 2.3 · Scoped Tool Access for Multi-Agent Systems
- TS 2.4 · MCP server scopes and secrets in Claude Code
- TS 2.5 · Grep vs Glob vs Read: Searching a Codebase with Claude Code's Built-in Tools
- TS 3.4 · Plan Mode vs Direct Execution: Choosing by Task Scope
- TS 5.4 · Context Rot, /compact and Scratchpad Files in Long Codebase Sessions
考点回链 — 本场景覆盖：TS 1.3、TS 2.1、TS 2.3、TS 2.4、TS 2.5、TS 3.4、TS 5.4。本场景无官方样题，坑位地图直接对齐 TS 原文措辞。
场景题组
ch18 · Q1 · 准则 P5
An engineer asks your agent to find every place the legacy
AuthContext is consumed across a 900-file frontend repo. What should the agent do first?正确 DTS 2.5 的基本分工：
Grep 搜内容（函数名、import 语句、报错文本），Glob 按路径模式找文件。而且 guide 明确给了增量建立理解的顺序——先 Grep 找入口，再 Read 顺着 import 追踪。D3 治标不治本违反 P6A：用破坏性改名换编译错误来做一次只读的调查。动态引用或字符串形式的使用还根本编译不出错，会静默漏掉。
D2 过度工程违反 P5B：用错工具的适配轴，还要把几百个文件逐个读进上下文——既慢又会在找到答案前耗尽 context。
D2 过度工程违反 P7C：上来读全库正是 TS 2.5 点名要避免的做法（应当增量建立理解）；整张依赖图进上下文还会触发 lost-in-the-middle。
ch18 · Q2 · 准则 P1
You added an MCP server exposing
find_symbol_references, which understands the language server's symbol graph and returns exact references with types. Traces show the agent still reaches for Grep in almost every case, producing noisy string matches. The MCP tool's description is "Finds references." What should you do?正确 BTS 2.4 点名的 skill：增强 MCP 工具描述、详细说明能力与输出，以防 agent 偏好 built-in 工具（guide 举的正是
Grep）。根因与 TS 2.1 同源——"Finds references" 三个词给不出任何选它的理由。D2 过度工程违反 P4A：
Grep 有它真正合适的场景（按字面模式搜内容，如定位报错文本）。为纠正一次选择偏好而删掉一项正当能力，代价过大。「确定性」在这里不是加分项——P3 只把确定性强制留给有正确性/资金/合规后果的场合，而这里的后果只是搜得吵一点；用删能力换确定性，正是 P2 比例原则要拦的那种交易。D6 概率当保证违反 P1C：system prompt 的偏好指令是概率性的，而且 TS 2.1 提醒关键词敏感的 system prompt 指令本身会制造非预期的工具关联——用一个已知有副作用的机制去补描述的缺。
D2 过度工程违反 P4D：再包一层工具会增加工具总数与选择复杂度（TS 2.3），而且用名字暗示等价关系正是 TS 2.1 警告的功能重叠——它制造新的误选，而不是消除旧的。
ch18 · Q3 · 准则 P5
The agent tries to change one of six identical
if err != nil { return err } blocks in a Go file using Edit. The edit fails because the anchor text is not unique. What is the documented fallback?正确 CTS 2.5 明写的 fallback：
Edit 因文本匹配不唯一而失败时，用 Read + Write 做可靠的文件修改。Edit 的机制前提是唯一锚文本，前提不成立就换整文件路径。D5 吞错或炸链违反 P6A：反复调用一个前提已不成立的工具，每次都会同样失败；「直到碰对为止」没有收敛机制，只会产生一串失败调用。
D2 过度工程违反 P5B：绕到 shell 用行号编辑既脆弱（行号随任何前置改动失效）又绕开了内置工具的既定分工——与 CI 场景里
< /dev/null 的错法同一工艺。D4 甩锅错位违反 P1D：改另一个文件不是修改目标文件。
Glob 按路径模式找文件，与解决锚文本不唯一毫无关系。ch18 · Q4 · 准则 P5
An engineer needs every call site of a deprecated
retryWithBackoff helper. The repo re-exports it through two facade modules, one as withRetry and one as resilientCall. What sequence finds all usages?正确 ATS 2.5 点名的 skill：追踪函数在 wrapper 模块间的使用，做法是先识别全部导出名，再逐个名字全库搜索——正是为了覆盖重新导出后改名的调用点。
D3 治标不治本违反 P1B：题干已明说两个 facade 用不同的名字重新导出。只搜原名会漏掉这些调用点——这正是 guide 专门给出这条规程的原因。
D2 过度工程违反 P5C：读全部源文件既慢又会耗尽 context，与 TS 2.5 的增量理解原则相反；而
Grep 一次就能定位内容。D5 吞错或炸链违反 P6D：搜
retry 会淹没在无关匹配里（重试配置、注释、其他重试工具），同时仍然漏掉 resilientCall——既多又漏，两头不讨好。ch18 · Q5 · 准则 P2
Your agent spends 25–35 tool calls at the start of every session discovering which Jira projects exist, which fields each issue type has, and which database tables are available. You control the MCP server behind both systems. What is the appropriate change?
正确 DTS 2.4：MCP resources 的定义用途就是暴露内容目录（guide 举例：issue 摘要、文档层级、数据库 schema），从而减少探索性工具调用。题干的症状与这条 skill 的适应症逐字对应。
D3 治标不治本违反 P4A：把 30 次压成 1 次有改善，但仍要每次会话主动调用一次，而且这个「查一切」的泛化工具与 TS 2.1 提倡的明确 I/O 契约背道而驰。resources 正是为目录场景准备的机制。
D3 治标不治本违反 P9B：会变动的 schema 手抄进始终加载的 CLAUDE.md，既占满每个会话的 context，又立刻开始过期——漂移会让 agent 基于错误信息写查询。
D2 过度工程违反 P2C：自建缓存要处理失效（schema 会变），而现成的 resources 机制没用。scratchpad 的正当用途是跨上下文边界持久化发现（TS 5.4），不是替代服务端的目录能力。
ch18 · Q6 · 准则 P7
Ninety minutes into exploring a legacy billing system, the agent contradicts its earlier answer about which service owns invoice numbering, and starts describing "the usual service-layer pattern" rather than naming the classes it identified an hour ago. What addresses this?
正确 ATS 5.4 把这个症状写得极精确——扩展会话中答案不一致、引用「典型模式」而非先前发现的具体类。对策正是 scratchpad 文件持久化关键发现（跨上下文边界）＋ subagent 委派隔离冗长探索输出，主 agent 保留高层协调。
D3 治标不治本违反 P1B：温度影响措辞随机性，与「先前发现已不在有效上下文中」这个根因无关。降温只会让它更一致地给出泛泛而谈的答案。
D4 甩锅错位违反 P1C：把「记住自己发现了什么」这件系统本该承担的工作转嫁给工程师——而这个 agent 的产品定位恰恰是帮人理解陌生系统。scratchpad 让 agent 自己持久化，成本低得多也可靠得多。
D3 治标不治本违反 P7D：更大的 context window 解决「装不下」，而这里是注意力质量与上下文退化问题；它只把退化的时点推后，长探索照样会撞上。
ch18 · Q7 · 准则 P9
Your team wants a shared GitHub MCP server available to everyone on the repo, authenticated with a token that must never be committed. You separately want to test an experimental profiling MCP server on your own machine only. How should these be configured?
正确 BTS 2.4 的三条规则各就各位：团队共享 → project 级
.mcp.json；个人实验 → user 级 ~/.claude.json；凭证用 ${VAR} 环境变量展开，让配置入库而密钥留在环境里。D3 治标不治本违反 P9A：注释掉的实验性服务器仍在团队共享文件里，把个人实验的维护负担摊给所有人；user 级作用域正是为此存在。
D4 甩锅错位违反 P9C：让每个人手工粘贴配置，正是 project 级作用域要消除的工作；任何一次变更都要全员重做，必然出现版本漂移。
D1 凭空捏造违反 P9D：两处都错。把
.mcp.json gitignore 掉直接取消了它「团队共享」的意义（明文密钥也不该落盘）；而 .claude/config.json 这个机制不存在。ch18 · Q8 · 准则 P4
After adding GitHub, Jira, and observability MCP servers, your single productivity agent has 19 tools. Selection accuracy has dropped and the agent sometimes queries dashboards while answering a code-navigation question. All descriptions are detailed and distinct. What is the right structural response?
正确 CTS 2.3 的两条正面命中：工具过多（guide 举的正是 18 vs 4–5）因决策复杂度上升而降低选择可靠性；拿到专业外工具的 agent 倾向误用。TS 2.4 已说明多服务器工具连接时同时可用——所以控制手段在分配侧。
D4 甩锅错位违反 P4A：断开服务器会连带失去真实能力（排查线上问题时 dashboard 很有用）。多服务器同时可用是设计前提，不是缺陷。
D3 治标不治本违反 P4B：题干已说明 19 个描述各自详尽且互相区分——问题在数量带来的决策复杂度。继续加描述还会让每次决策要读的内容更多。
D1 凭空捏造违反 P4D：
tool_choice: "any" 保证模型调用某个工具而不是返回纯文本，它不缩小候选集合，也不提升选对的概率。ch18 · Q9 · 准则 P5
A four-agent codebase mapping run takes about 50 minutes. When the orchestrating process died at minute 41, everything was lost and the run restarted from zero. What design prevents recurrence?
正确 DTS 5.4 点名的崩溃恢复设计：每个 agent 结构化地导出状态到已知位置，coordinator 在 resume 时加载 manifest 并注入 agent prompt。它恢复的是多 agent 系统的整体进度。
D3 治标不治本违反 P5A：
--resume 续接的是一条命名会话（TS 1.7），覆盖不了四个 agent 的协同状态——哪些子任务已完成、各自产出了什么，不在任何单条会话里。D1 凭空捏造违反 P5B：
/compact 压缩的是会话内的上下文占用，它不做任何持久化。进程一死，压缩过的上下文照样消失。D3 治标不治本违反 P5C：把损失从 100% 降到 25%，但没有任何一个 agent 的成果被持久化；而且四条独立会话之间失去了 coordinator 的编排（TS 1.2 的 hub-and-spoke）。