附录 A —— 常见问题#
问题按读者角色分组。每条回答不超过 150 词；大约三分之一会带上一条 {ref} 回指书本正文，方便好奇的读者跳进权威小节。
面向一线工程师#
我需要一次把三大护法全采纳吗？#
不需要 —— 第 12 章的 30/60/90 清单说得很清楚，一支团队是 三十天里交付一格，六十天里交付一行或一列。SDD × 缰绳 是常见的起点，因为 AGENTS.md 写起来便宜、在此后的每一回合都能回本。权威制品见 SDD × 缰绳 —— 引导智能体的规约。若你独自作战，TDD × 护栏 也是一个合理替代：一条 PreToolUse 钩子——在测试树变红时拒绝编辑——每天都能立刻给你杠杆。
这跟我现有的 CI 流水线有何不同？#
CI 是 TDD 与 MDD 的 牧场。本书主张：仅有牧场是不够的——缰绳在 CI 跑起来之前就在掰方向；护栏在按键时就触发，而不是合并时；梳理则在照看这些关卡本身。如果你的 CI 流水线是在周五晚上抓到那些本可以在周二早上 commit 时就抓到的 bug，那你的"护栏"这一列投资不足。
如果我团队用的是 Cursor，不是 Claude Code，怎么办？#
这套十二格矩阵与平台无关。把 AGENTS.md 当 canonical 入口；Cursor 的 .cursor/rules/、Claude Code 的 CLAUDE.md、Copilot instructions 都可以做成薄镜像或更窄的客户端配置。唯一例外是 SKILL.md 这种格式——截至 2026-04，它是 Claude Code 专属的；Cursor 用户用自己 .cursor/rules/ 下作用范围相当的文件替换即可。
我已经有 CLAUDE.md 或 .cursor/rules/，还要 AGENTS.md 吗？#
要，除非你的仓库永远只服务一个客户端。做法不是复制三份散文，而是把项目事实、命令、边界、danger zones 收敛进 AGENTS.md，再让 CLAUDE.md 作为 symlink 或薄镜像指回它；.cursor/rules/ 只保留 Cursor 特有的窄规则。用 agents-md-generate 可以把这次迁移做成"发现现状 → 合并旧文件 → 验证命令"的工作流。
我已经在写测试了，难道这还不算 TDD？#
写了测试是必要的，但还不充分；TDD × 缰绳 要求这些测试 先红、且作为输入对智能体可见。参见 TDD × 缰绳 —— 先失败的测试作为给智能体的输入。如果你的测试是在功能合并之后才写的，那么它们顶多算在 TDD × 牧场 里，对 TDD × 缰绳 几乎没贡献。
面向团队负责人#
我怎么说服团队在交付之前先投资 SDD？#
做一次实打实的演练：用附录 D 的空白模板（见 空白模板）给你现在的仓库打分、点名那一格得分最低的单元、为它交付一件制品、再重新打分。单格 +2 的 delta 已经足够可见，可以支撑下一轮迭代。第 11 章就是这套打法的经典范例。
这跟 DORA 度量怎么配合？#
DORA 度量的是产出；HarnessCard 度量的是 通向这些产出的投入。deployment frequency 抬升、change failure rate 下降，是一具被照看良好的马具的下游效应。两者同时追踪，就能把"马具在起作用"和"我们刚好走运"分开。把 HarnessCard 绑到生产 SLI 的打分尺，见 12.2 第 61–90 天那一段。
我团队所需的最小评审仪式是什么？#
每份 PR 配一张按角色划分范围的验证表（见 SDD × 牧场 —— 与规约相符的验收），以及一份针对 CI 流水线的显式"硬关卡 vs 软关卡"分类。这两件制品合起来每周大约一小时维护，就能消除那种最常见的失败模式——"悄悄返工，从来不回灌回规约"。
对那些把这当成额外开销、要反对的工程师，怎么处理？#
请他们把 12.2 第 1–30 天的练习跑一周。若单格交付带来的可度量收益是 0，这个实验就算结束——你也学到东西了。本书的经验押注——以 Peng 等 [Peng et al., 2023] 与 Ziegler 等 [Ziegler et al., 2022] 为依据——是：一格、一周，到第一个月结束时会撬动一条可度量的生产率指标。
我们怎么把真正的马具工作，跟马具剧场区分开？#
一条每周一都要问的诊断：上周这具马具拒了什么、度量了什么、掰过什么方向，这些做得对吗？ 一具健康的马具能给出具体答案——它挡下了一次 commit、抓住了一次工具调用、越过了一条仪表盘信号。一具剧场化的马具只会产出一串 加法（"我们写了个新 skill"、"我们加了一条钩子"），没有对应事件。若团队只答得出"加法"那一问，说明马具在长肥、却没在起杠杆。术语表中的 马具剧场 条目列出了常见子类；第 06 章收尾那一段给出的是正式诊断。
我们 HarnessCard 的得分一直在涨，下游却没什么动静。为什么？#
这就是第 11 章点名的"虚荣 delta"模式。HarnessCard 是一份 诊断 打分尺——它的角色是"识别弱格"，不是"被优化的对象"。当格子得分在涨、DORA 指标却不跟着动，那支团队是在偿还一笔本来根本没在收利息的债。解法：为每一项计划中的 HarnessCard delta，配一条它 被预言要移动 的产出指标（部署频率、变更失败率、事故数）。若一个季度后该产出未动，上一个季度的投资就是虚荣；下一个季度的投资应换到另一格——或者反思：产品的瓶颈是不是根本就不在马具上。
面向怀疑者#
这不就是 DevOps 换个说法吗？#
DevOps 打包的是 CI/CD、基础设施即代码、部署自动化；本书主张——智能体时代的软件工程，需要一套 上游 于这些实践的词汇：缰绳在 CI 跑起来之前就在掰方向，SDD 那位护法在代码写下来之前就在塑造规约。第 03 章的对比表把这条边界画得很明确。DevOps 依旧是必需的，并不被马具工作所取代。
这不就是 prompt engineering 吗？#
Prompt engineering 只是一格（SDD × 缰绳）。其余十一格——护栏、牧场、梳理、TDD、MDD——都不能被还原为"写 prompt"。Karpathy 的 context engineering 说法 [Karpathy, 2025] 在 prompt engineering 之上再走了一步；这套"三大护法 × 四区域"矩阵，又在那之上再走一步。
你大量引用作者自己的博客，这不是危险信号吗？#
四区域这套命名，在 05.Provenance 中被明确承认为"从业者起源"；学术根基是 CAR／HarnessCard 论文 [CAR Research Collective, 2025]，以及本书各处列出的五个独立工业三角来源。本书从不掩饰"这份命名是作者的"；它所做的，是让这套命名与三套独立发展起来的相邻框架互相三角印证。
我怎么知道这本书到 2027 年还有用？#
短答：你不知道。本书的 30 天／60 天／90 天结构假设：具体制品 会比 框架本身 更快老化。Lehman 的演化定律 [Lehman, 1980] 对本书与对任何代码库同样适用；12.3 点出了那些悬而未决的问题——它们的解决，最有可能驱动一次再版。
我的智能体每道检查都通过，却还是把错代码交上去。什么情况？#
三种可能，出现频次递减。第一，错误钉死：测试之所以过，是因为智能体落在了与测试一致的众多解读之一；人类真正想要的那种解读，从未被钉死（第 04 章）。解法：加一些"针对最便宜变绿路径"的对抗测试。第二，规约漂移：智能体在向 AGENTS.md 对齐，而代码库已经悄悄漂走（第 04 章）。解法：安排每周一次的"规约 vs 代码" diff。第三，歧义放大：规约里一条含糊的条目，正在生出一堆差别巨大却 局部都对 的实现（第 04 章）。解法：把那条拧紧，直到有一条钩子能去检查它。这三种在术语表里都有；这三种在第 04 章里都是行内陷阱。
面向中文语境读者#
为什么示例是英文的？我代码库是中文的。#
代码类制品（YAML、JSON Schema、shell 脚本）通常与语言无关，可原样拷贝。散文类制品（AGENTS.md、CLAUDE.md）则以匹配团队工作语言为宜：中文团队可以用中文写规约，但保留 test、lint、danger zone、owner、last_updated 这些英文术语，减少工具与人之间的翻译损耗。本书源码现在以中文为主，不再依赖 sphinx-intl 的双语切换。
《马书》与本书是什么关系？#
《马书》[Zhang, 2026] 是一份针对 Claude Code 的逆向工程研究，做得非常好。第 10 章对它大量引用，也是全书唯一引它的章节。本书站在它之上一层：它构建的是一套 框架——一套给"马具"打分的通用尺子——Claude Code 只是其中一个实例。
我需要按顺序读这本书吗？#
不需要。如果你已经熟悉那几位护法，从第 05 章（那张矩阵）开始，然后跳到 07–10 中任一篇最贴近你日常工作的案例研究，再回到第 11 章看那份 lazy-ai-coder 的实例。序言和第 02 章是有用的背景，但不是理解那张矩阵的前置。
你推荐哪些中文资源？#
针对 Claude Code，看《马书》[Zhang, 2026]；看作者 2026-03-28 那篇博文，可以读到"四区域"的原始论述 [Fan, 2026]；更全的阅读单见附录 C。
关于这本书本身#
为什么选 Sphinx 而不是 mdBook？#
三个理由：sphinxcontrib-bibtex 提供一等公民级的学术引用；MyST 指令生态让我们能用 {literalinclude} 从 hands-on 制品里原样嵌入；Read the Docs 主题则给长篇技术书一个熟悉、稳定的阅读界面。换一套优先级的团队，选择 mdBook 也完全合理；版权页那页给出了完整理由。
为什么第 11 章处于 draft 状态？#
第 11 章保持 status: draft，直到第三幕那四笔修复 commit 合入宿主仓库的 main。book-lint 脚本会用 git cat-file -e 遍历第三幕的 commit SHA；在至少两笔解析成功之前，本章仍应被视为一份待验证案例。
我怎么贡献？#
见源代码仓库中的 book/CONTRIBUTING.md。一句话总结：新引用放进 _bib/*.bib 中按类型匹配的那一份；新 hands-on 制品放在 _handson/<chapter-slug>/ 下，并带一条 verified: YYYY-MM-DD 头注；新矩阵格子需要扩展 book_lint.py，以强制执行"引用 ＋ 制品"这条规则。
本书采用什么许可证？#
散文部分 CC-BY-NC-SA-4.0（署名 · 非商用 · 相同方式共享），代码示例 Apache-2.0，被引用的片段保留其上游许可证。完整文本见 book/LICENSE，Apache-2.0 的署名要求见 book/NOTICE。