---
status: draft
chapter-type: appendix
---

# 附录 A —— 常见问题

问题按读者角色分组。每条回答不超过 150 词；大约三分之一会带上一条 `{ref}` 回指书本正文，方便好奇的读者跳进权威小节。

## 面向一线工程师

### 我需要一次把三大护法全采纳吗？

不需要 —— 第 16 章的 30/60/90 清单说得很清楚，一支团队是 *三十天里交付一格，六十天里交付一行或一列*。SDD × 缰绳 是常见的起点，因为 `AGENTS.md` 写起来便宜、在此后的每一回合都能回本。权威制品见 {ref}`sdd-x-bridle`。若你独自作战，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 × 缰绳 要求这些测试 *先红、且作为输入对智能体可见*。参见 {ref}`tdd-x-bridle`。如果你的测试是在功能合并之后才写的，那么它们顶多算在 TDD × 牧场 里，对 TDD × 缰绳 几乎没贡献。

## 面向团队负责人

### 我怎么说服团队在交付之前先投资 SDD？

做一次实打实的演练：用附录 D 的空白模板（见 {ref}`apd-harnesscard-template`）给你现在的仓库打分、点名那一格得分最低的单元、为它交付一件制品、再重新打分。单格 +2 的 delta 已经足够可见，可以支撑下一轮迭代。第 15 章就是这套打法的经典范例。

### 这跟 DORA 度量怎么配合？

DORA 度量的是产出；HarnessCard 度量的是 *通向这些产出的投入*。`deployment frequency` 抬升、`change failure rate` 下降，是一具被照看良好的马具的下游效应。两者同时追踪，就能把"马具在起作用"和"我们刚好走运"分开。把 HarnessCard 绑到生产 SLI 的打分尺，见 12.2 第 61–90 天那一段。

### 我团队所需的最小评审仪式是什么？

每份 PR 配一张按角色划分范围的验证表（见 {ref}`sdd-x-paddock`），以及一份针对 CI 流水线的显式"硬关卡 vs 软关卡"分类。这两件制品合起来每周大约一小时维护，就能消除那种最常见的失败模式——"悄悄返工，从来不回灌回规约"。

### 对那些把这当成额外开销、要反对的工程师，怎么处理？

请他们把 12.2 第 1–30 天的练习跑一周。若单格交付带来的可度量收益是 0，这个实验就算结束——你也学到东西了。本书的经验押注——以 Peng 等 {cite}`peng2023copilotstudy` 与 Ziegler 等 {cite}`ziegler2022productivity` 为依据——是：一格、一周，到第一个月结束时会撬动一条可度量的生产率指标。

### 我们怎么把真正的马具工作，跟马具剧场区分开？

一条每周一都要问的诊断：*上周这具马具拒了什么、度量了什么、掰过什么方向，这些做得对吗？* 一具健康的马具能给出具体答案——它挡下了一次 commit、抓住了一次工具调用、越过了一条仪表盘信号。一具剧场化的马具只会产出一串 *加法*（"我们写了个新 skill"、"我们加了一条钩子"），没有对应事件。若团队只答得出"加法"那一问，说明马具在长肥、却没在起杠杆。术语表中的 *马具剧场* 条目列出了常见子类；第 09 章收尾那一段给出的是正式诊断。

### 我们 HarnessCard 的得分一直在涨，下游却没什么动静。为什么？

这就是第 15 章点名的"虚荣 delta"模式。HarnessCard 是一份 *诊断* 打分尺——它的角色是"识别弱格"，不是"被优化的对象"。当格子得分在涨、DORA 指标却不跟着动，那支团队是在偿还一笔本来根本没在收利息的债。**解法**：为每一项计划中的 HarnessCard delta，配一条它 *被预言要移动* 的产出指标（部署频率、变更失败率、事故数）。若一个季度后该产出未动，上一个季度的投资就是虚荣；下一个季度的投资应换到另一格——或者反思：产品的瓶颈是不是根本就不在马具上。

## 面向怀疑者

### 这不就是 DevOps 换个说法吗？

DevOps 打包的是 CI/CD、基础设施即代码、部署自动化；本书主张——智能体时代的软件工程，需要一套 *上游* 于这些实践的词汇：缰绳在 CI 跑起来之前就在掰方向，SDD 那位护法在代码写下来之前就在塑造规约。第 03 章的对比表把这条边界画得很明确。DevOps 依旧是必需的，并不被马具工作所取代。

### 这不就是 prompt engineering 吗？

Prompt engineering 只是一格（SDD × 缰绳）。其余十一格——护栏、牧场、梳理、TDD、MDD——都不能被还原为"写 prompt"。Karpathy 的 context engineering 说法 {cite}`karpathy2025context` 在 prompt engineering 之上再走了一步；这套"三大护法 × 四区域"矩阵，又在那之上再走一步。

### 你大量引用作者自己的博客，这不是危险信号吗？

四区域这套命名，在 05.Provenance 中被明确承认为"从业者起源"；学术根基是 CAR／HarnessCard 论文 {cite}`car2025decomposition`，以及本书各处列出的五个独立工业三角来源。本书从不掩饰"这份命名是作者的"；它所做的，是让这套命名与三套独立发展起来的相邻框架互相三角印证。

### 我怎么知道这本书到 2027 年还有用？

短答：你不知道。本书的 30 天／60 天／90 天结构假设：*具体制品* 会比 *框架本身* 更快老化。Lehman 的演化定律 {cite}`lehman1980laws` 对本书与对任何代码库同样适用；12.3 点出了那些悬而未决的问题——它们的解决，最有可能驱动一次再版。

### 我的智能体每道检查都通过，却还是把错代码交上去。什么情况？

三种可能，出现频次递减。第一，**错误钉死**：测试之所以过，是因为智能体落在了与测试一致的众多解读之一；人类真正想要的那种解读，从未被钉死（第 07 章）。解法：加一些"针对最便宜变绿路径"的对抗测试。第二，**规约漂移**：智能体在向 `AGENTS.md` 对齐，而代码库已经悄悄漂走（第 07 章）。解法：安排每周一次的"规约 vs 代码" diff。第三，**歧义放大**：规约里一条含糊的条目，正在生出一堆差别巨大却 *局部都对* 的实现（第 07 章）。解法：把那条拧紧，直到有一条钩子能去检查它。这三种在术语表里都有；这三种在第 07 章里都是行内陷阱。

## 面向中文语境读者

### 为什么示例是英文的？我代码库是中文的。

代码类制品（YAML、JSON Schema、shell 脚本）通常与语言无关，可原样拷贝。散文类制品（`AGENTS.md`、`CLAUDE.md`）则以匹配团队工作语言为宜：中文团队可以用中文写规约，但保留 test、lint、danger zone、owner、last_updated 这些英文术语，减少工具与人之间的翻译损耗。本书源码现在以中文为主，不再依赖 `sphinx-intl` 的双语切换。

### 《马书》与本书是什么关系？

《马书》{cite}`zhangbook2026` 是一份针对 Claude Code 的逆向工程研究，做得非常好。第 13 章对它大量引用，也是全书唯一引它的章节。本书站在它之上一层：它构建的是一套 *框架*——一套给"马具"打分的通用尺子——Claude Code 只是其中一个实例。

### 我需要按顺序读这本书吗？

不需要。如果你已经熟悉那几位护法，从第 08 章（那张矩阵）开始，然后跳到 07–10 中任一篇最贴近你日常工作的案例研究，再回到第 15 章看那份 lazy-ai-coder 的实例。序言和第 02 章是有用的背景，但不是理解那张矩阵的前置。

### 你推荐哪些中文资源？

针对 Claude Code，看《马书》{cite}`zhangbook2026`；看作者 2026-03-28 那篇博文，可以读到"四区域"的原始论述 {cite}`walterfan2026guardians`；更全的阅读单见附录 C。

## 关于这本书本身

### 为什么选 Sphinx 而不是 mdBook？

三个理由：`sphinxcontrib-bibtex` 提供一等公民级的学术引用；MyST 指令生态让我们能用 `{literalinclude}` 从 hands-on 制品里原样嵌入；Read the Docs 主题则给长篇技术书一个熟悉、稳定的阅读界面。换一套优先级的团队，选择 mdBook 也完全合理；版权页那页给出了完整理由。

### 为什么第 15 章处于 draft 状态？

第 15 章保持 `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-SA-4.0，代码示例 MIT，被引用的片段保留其上游许可证。完整文本见 `book/LICENSE`。