案例研究：Lazy AI Coder —— 一则四幕剧形式的实证示例

案例研究：Lazy AI Coder —— 一则四幕剧形式的实证示例#

若这套框架连"给本书所承载的仓库打分、再改进它"这件事都做不了，那这框架就是错的。

到目前为止，每一篇案例研究都 关于 别人的马具。本章不同：它把"三大护法 × 四区域"矩阵，套到本书所承载的那个仓库——walterfan/async-harness-book——上，并把真正的修复合入 main。本章以四幕剧的形式展开。

备注

状态。 本章会保持 status: draft，直到第三幕列出的修复 commit 合入宿主仓库的 main 分支。book-lint 脚本会用 git cat-file -e 遍历第三幕的 commit SHA；在至少两笔解析成功之前，本章仍应被视为一份 待验证案例。

第一幕 —— 审计#

起点是一份 HarnessCard，记录仓库在这一轮变更开始那笔 commit 时的状态。每一格的证据都是仓库内一条具体的文件路径；完整打分表以 hands-on 制品形式交付，读者可与之做 diff。

<!-- verified: 2026-04-24 · Ch.11 Act 1 · Audit HarnessCard -->

# HarnessCard — Act 1 (Audit)

**Subject.** `walterfan/async-harness-book`, starting commit SHA: `<TBD — captured when Act-3 fixes land>`.

**Date.** 2026-04-17 (pre-fix baseline).

**Schema version.** CAR-HarnessCard v0.2.

| Cell            | Score | Evidence                                      |
|-----------------|-------|-----------------------------------------------|
| SDD × Bridle    | 3     | `CLAUDE.md`, `AGENTS.md` exist but drift from `openspec/`. |
| SDD × Fence     | 1     | No `make prompts-lint`; `config/prompts.yaml` unchecked.  |
| SDD × Paddock   | 2     | Review is GitHub PR default; no Verification Table.       |
| SDD × Groom     | 1     | No sources-of-truth index; docs drift silently.           |
| TDD × Bridle    | 2     | `tests/` exists but not failing-first.                    |
| TDD × Fence     | 1     | No MCP tool schema check; no secrets scan in pre-commit.  |
| TDD × Paddock   | 3     | GitHub Actions CI runs `go test` + Python tests.          |
| TDD × Groom     | 2     | Flake policy undefined; recent flakes closed ad-hoc.      |
| MDD × Bridle    | 1     | No cost dashboard; LLM spend unobservable.                |
| MDD × Fence     | 2     | Rate limits at provider only; no local cap.               |
| MDD × Paddock   | 2     | Release notes exist; no SLI gate.                         |
| MDD × Groom     | 1     | No weekly audit script.                                   |

**SDD mean.** 1.75.  **TDD mean.** 2.0.  **MDD mean.** 1.5.

**Overall.** 1.75. This is the pre-fix baseline; Act 4 re-scores after
the 14 fixes land.

这份审计稳稳地落在矩阵的左下角：SDD × 护栏、SDD × 梳理、TDD × 护栏、以及 MDD × 缰绳／梳理，是五个最弱的格子。Cunningham 1992 年的"技术债"隐喻 [Cunningham, 1992]，以及 Feathers 的 Working Effectively with Legacy Code [Feathers, 2004]，提供了解释"为什么这很重要"的词汇：这不是一份 糟糕的 仓库，而是一份 其马具累积了普通可生存之债 的仓库——任其发展就会复利恶化。Lehman 的演化定律 [Lehman, 1980] 预言的正是这个模式。

第二幕 —— 缺陷#

五项具体缺陷——每一项都附有严重度、证据指针、以及它映射到的矩阵坐标：

  1. 缺少 make prompts-lint。 config/prompts.yaml 未经 schema 校验就被提交；格式被破坏的模板只能在运行时才被发现。（SDD × 护栏，major；证据 config/prompts.yaml。）

  2. MCP 工具 schema 未与其 handler 做一致性校验。 新加了一个 handler 却没有 schema（反之亦然）——CI 照样绿灯放行。（TDD × 护栏，major；证据 internal/mcp/server.go、internal/mcp/handlers.go。）

  3. LLM 调用没有成本可观测面板。 月度花销在供应商账单到来之前完全不可见。（MDD × 缰绳，major；证据是 deploy/ 下没有任何面板配置。）

  4. CLAUDE.md 与 AGENTS.md 已与 openspec/ 工作笔记漂移。 这两份"门面文档"引用了已经不存在的概念，却没有引用现在已经存在的概念。（SDD × 梳理，minor；证据 CLAUDE.md、AGENTS.md、openspec/。）

  5. 没有 pre-commit 钩子来拦住"被提交进来的密钥"。 .env 文件已被 gitignore 忽略，但作为安全网的钩子层整个缺席。（TDD × 护栏 与 MDD × 缰绳 联合，critical；证据：仓库根目录不存在 .pre-commit-config.yaml。）

Adzic 的 Specification by Example [Adzic, 2011] 与 DORA 度量 [Forsgren et al., 2018]，框定了补救工作的方向：每一项缺陷，都要被转化为一道可执行关卡——它的存在或缺席，本身就成为一条被度量的指标。

第三幕 —— 把马具工程真正落下去#

四项修复合入 main，每一项都收束到单一矩阵格子上，并以 commit SHA 为引用。下文的 SHA 槽位会在后续修复合入时填入；book-lint 脚本在每次构建时都会用 git cat-file -e 遍历它们。

修复

格子

严重度

Commit SHA

make prompts-lint ＋ scripts/prompts_lint.py

SDD × 护栏

major

<待填 SHA>（修复 1）

MCP 工具的 "schema vs handler" 一致性检查

TDD × 护栏

major

<待填 SHA>（修复 2）

openspec/docs/sources-of-truth.md 索引，用以调和 CLAUDE.md ＋ AGENTS.md

SDD × 梳理

minor

<待填 SHA>（修复 3）

带 gitleaks ＋ make secrets-check 的 .pre-commit-config.yaml 基线

TDD × 护栏 联合 MDD × 缰绳

critical

<待填 SHA>（修复 4）

每一份 PR 的描述里，都按名引用本章（book — Ch.11 Act 3），并附上一行 HarnessCard delta 说明：哪一格的分数在动、动了多少。

第四幕 —— 丈量增量#

在第三幕的 commit 合入之后，写出第二份 HarnessCard，把格子得分与第一幕做 diff，并报告量化增量：

<!-- verified: 2026-04-24 · Ch.11 Act 4 · Measuring the Delta -->

# HarnessCard — Act 4 (Post-fix)

**Subject.** `walterfan/async-harness-book`, end-of-Act-3 commit SHA:
`<TBD — captured when Act-3 fixes land>`.

**Date.** 2026-04-17 (post-fix, to be re-verified when Act-3 fixes land).

**Schema version.** CAR-HarnessCard v0.2.

| Cell            | Act 1 | Act 4 | Delta | Fix                                   |
|-----------------|-------|-------|-------|---------------------------------------|
| SDD × Bridle    | 3     | 3     | 0     | (unchanged in 14 scope)              |
| SDD × Fence     | 1     | 4     | +3    | `make prompts-lint` + schema validator |
| SDD × Paddock   | 2     | 2     | 0     | (unchanged)                           |
| SDD × Groom     | 1     | 3     | +2    | `openspec/docs/sources-of-truth.md` index |
| TDD × Bridle    | 2     | 2     | 0     | (unchanged)                           |
| TDD × Fence     | 1     | 4     | +3    | MCP schema check + gitleaks pre-commit |
| TDD × Paddock   | 3     | 3     | 0     | (unchanged)                           |
| TDD × Groom     | 2     | 2     | 0     | (unchanged)                           |
| MDD × Bridle    | 1     | 1     | 0     | (out of 14 scope)                    |
| MDD × Fence     | 2     | 2     | 0     | (unchanged)                           |
| MDD × Paddock   | 2     | 2     | 0     | (unchanged)                           |
| MDD × Groom     | 1     | 1     | 0     | (unchanged)                           |

**SDD mean.** 1.75 → 3.0 (+1.25).
**TDD mean.** 2.0 → 2.75 (+0.75).
**MDD mean.** 1.5 → 1.5 (+0.0).
**Overall.** 1.75 → 2.42 (+0.67).

## Quantitative metrics

| Metric                       | Act 1 | Act 4 | Delta |
|------------------------------|-------|-------|-------|
| prompts-lint rule count      | 0     | 7     | +7    |
| MCP schema mismatches at CI  | N/A   | 0     | —     |
| secrets-scan coverage (% committed files) | 0     | 100   | +100  |
| `sources-of-truth.md` entries | 0     | ≥ 6   | +6    |

本章契约 要求 至少两条量化指标；hands-on 版的 HarnessCard 报告了四条：

  • prompts-lint 规则条数：0 → 7。

  • CI 上的 MCP schema 不一致数：N/A → 0（全新检查）。

  • secrets 扫描覆盖率（已提交文件占比，%）：0 → 100。

  • sources-of-truth.md 条目数：0 → ≥ 6。

HarnessCard 总均值从 1.75 升到 2.42 —— +0.67 的改善集中落在两个"护栏"格（各 +3）和 SDD × 梳理（+2）上。第四幕刻意不动 MDD 那一行；第 12 章的 30/60/90 计划会在下一个季度接手。

这个 delta 不能 证明什么#

第三幕的四个 commit，把 HarnessCard 均值抬升了 0.67。这是一个真实的数字，也是一个 有边界 的数字——在把它当作"马具在起作用"的证据去引用之前，值得先仔细读清楚。

  • 这个 delta 度量的是投入，不是产出。 格子得分上升，意味着仓库里多了一批"评分尺会给分"的制品；它还不等于智能体的输出变好了。DORA 风格的产出指标（部署频率、变更失败率、平均恢复时间），才是"投入有所回报"的证据——第 12 章的 90 天复盘，才是期望这些产出真正移动的时点，而不是第四幕的这张快照。

  • 打分人与作者是同一个人。 第一幕的基线与第四幕的重评，都由同一位工程师执笔，用同一把评分尺，且对"改了什么"心知肚明。这对于"自审计"来说是诚实的，但不是独立验证——这些分数是校准，不是度量。读者在自己仓库上复制这套模式时，应预期自己也会有类似偏置。

  • 四项修复里有三项是"护栏"形的。 护栏格最容易抬分——因为"拒绝"是机械且可测的。缰绳格和牧场格抬得更慢——因为它们需要改变人和智能体所 做 的事，不是仅仅改变 CI 拒绝什么。一份 HarnessCard 的均值主要由"护栏收益"主导，在第一个季度里是一种诚实的模式；但一份 连续四个季度 其 delta 只有 护栏的 HarnessCard，则是一支"只投资于拒绝、却未抬升意图与验收"的团队的画像。

陷阱 —— HarnessCard 虚荣增量

一支团队跑完第 11 章的 playbook，合入了四个"护栏"commit，向上汇报 +0.67 的均值 delta。领导很满意。两个季度之后，产出指标一动未动；这个团队于是加码，又合入四个"护栏"commit；均值再次上升。马具在长胖；产出没在长。为什么：HarnessCard 是一份 诊断 —— 它的角色是"识别弱格"，不是"被优化的对象"。一支为"分数"而非"产出"优化的团队，在跑的是 Goodhart 律的一个变种（Cunningham 的债务隐喻 [Cunningham, 1992] 反着用一次：你 确实 可以去还一笔本来根本没在收利息的债）。症状：格子得分在涨，仪表盘没在涨；回顾会上对"马具工作"描述得温情脉脉，事故复盘里对"产品工作"描述得痛不欲生。解法：每一项 HarnessCard delta 都要配一项它 被预言会移动 的产出指标。若一个季度后该产出未移动，则这份 delta 属于虚荣；下一季度的投资应该换到另一格（或彻底换一个维度）。

阅读单扩展#

第四幕的可复现性主张，建立在一段简短 shell 脚本之上——它针对"第四幕 SHA"处的一份全新 clone，跑三个新的 make 目标：

#!/usr/bin/env bash
# verified: 2026-04-17 · Ch.11 hands-on · reproduce the HarnessCard delta
# Run from a fresh clone of walterfan/async-harness-book at the Act-4 SHA.
set -euo pipefail

# 1. SDD × Fence — prompts-lint validates config/prompts.yaml
make prompts-lint

# 2. TDD × Fence — MCP tool schema-vs-handler consistency check
make mcp-schema-check

# 3. TDD × Fence — pre-commit hooks refuse secrets
make secrets-check

echo "If all three targets exited 0, the harness is at its Act-4 score."

第四项修复里的 pre-commit-config.yaml 基线，也一并交付，方便想原样拿走的读者：

# verified: 2026-04-17 · Ch.11 hands-on · symlink-safe copy of the final pre-commit config
# To be landed on main as the fourth Act-3 fix.
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0
    hooks:
      - {id: trailing-whitespace}
      - {id: end-of-file-fixer}
      - {id: check-yaml}
      - {id: detect-private-key}
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.4
    hooks: [{id: gitleaks}]
  - repo: local
    hooks:
      - id: prompts-lint
        name: prompts-lint
        entry: python scripts/prompts_lint.py config/prompts.yaml
        language: system
        pass_filenames: false
      - id: mcp-schema-check
        name: mcp-schema-check
        entry: go run ./cmd/mcp-schema-check
        language: system
        pass_filenames: false

研究脉络#

  • 技术债 [Cunningham, 1992] —— 第一幕的词汇来源。

  • 遗留代码 [Feathers, 2004] —— 第二幕的补救模式。

  • DORA ／ Accelerate [Forsgren et al., 2018] —— 第四幕所依据的度量谱系。

  • 演化定律 [Lehman, 1980] —— 为什么一旦停止"梳理"投资，总均值就会持续漂移。

动手环节#

在 source/_handson/11-lazy-ai-coder/ 下，住着四份可直接拷走的制品：

  • HarnessCard-Act1.md —— 修复前的基线。

  • HarnessCard-Act4.md —— 修复后的再审计，含 delta。

  • reproduce.sh —— 三个 make 目标，一段脚本。

  • pre-commit-config.yaml —— 最终基线的 symlink-safe 拷贝。

当第三幕那批 commit 合入 main，HarnessCard 将针对真实 SHA 重新打分，本章状态也会翻为 status: complete。