附录 F —— 工程师落地手册

附录 F —— 工程师落地手册#

本附录回答一个很实际的问题：读完这本书之后，工程师明天该改哪一个文件？它不是新理论，而是把前面章节压成一份可执行 playbook：一个贯穿样例、一张每章行动表、五条迁移路径、四组好坏例子，以及一套按角色分工的落地节奏。

F.1 贯穿样例：todo-cli#

假设你维护一份很小的 Python CLI：todo-cli。它有 todo/、tests/、pyproject.toml，也许还有一份普通的 README.md。它不是平台工程项目，也没有宏大的 AI strategy；它只是一个会被人和智能体反复修改的小仓库。正因为小，它适合展示 Harness Engineering 的最小闭环。

Day 0 · 没有马具#

仓库里通常只有这些东西：

  • README.md 解释怎么运行项目。

  • tests/ 里有一些 pytest。

  • CI 会在 PR 上跑测试。

  • 智能体靠当前 prompt、README 和上下文猜团队习惯。

这不是坏仓库，只是 未被驾驭 的仓库。它的问题不是没有文档，而是没有任何东西能在智能体下笔之前明确告诉它"本仓库的边界在哪里"，也没有任何东西在它越界时立刻拒绝。

Day 1 · 最小三件套#

第一天只交付三份文件：

  • AGENTS.md：说明项目是什么、能改哪里、必须跑哪些命令。

  • .pre-commit-config.yaml：在 commit 前跑 ruff 与快速 pytest。

  • HarnessCard.md：记录这具马具由哪份规约、哪道护栏、哪些信号构成。

这一步对应第 03 章的最小示例。它的价值不在于文件多，而在于三件事第一次对齐：智能体读到的规约、机器执行的护栏、团队复盘的信号。

Day 7 · 第一条可证伪规则#

一周内挑一条最容易被智能体弄错的规则，让它变成可证伪的规则。例如：

坏规则：写代码时保持风格一致。
好规则：修改 `todo/storage.py` 前必须先跑 `pytest tests/test_storage.py`。

前者无法被机器拒绝，后者可以被 hook、CI 或 reviewer checklist 检查。第一个星期的目标不是写完所有规则，而是让团队亲眼看到一条规则从散文变成关卡。

Day 30 · 交付完整 SDD 行#

到第 30 天，todo-cli 至少应该有完整 SDD 行：

  • SDD × 缰绳：AGENTS.md 是 canonical 入口。

  • SDD × 护栏：AGENTS.md 中列出的命令必须存在；坏链接、坏 schema 会失败。

  • SDD × 牧场：PR 模板或验收表逐项确认"交付是否符合规约"。

  • SDD × 梳理：每周检查 AGENTS.md 是否仍与代码和命令相符。

这时团队已经不再只是"写了一份 agent 文档"，而是让规约具备了入口、约束、验收和维护节奏。

Day 60 · 一行或一列#

第 60 天不要争论"先补哪一格最优"。用尴尬测试：把当前 AGENTS.md、CI、仪表盘或评审流程拿给同事看，哪一项最让你不好意思，就补哪一行或哪一列。

常见选择：

  • 智能体总是乱改架构：补完整 SDD 行。

  • 测试经常被跳过：补完整护栏列。

  • 账单、性能、返工没人看：补完整 MDD 行。

Day 90 · 第一次生产级 HarnessCard 评审#

第 90 天不要只问"我们多了哪些文件"。问三句话：

  • 上季度马具拒绝了什么？

  • 上季度马具度量了什么？

  • 上季度马具让哪一次工程决策改变了方向？

三问都答得出，才说明这具马具在工作。答不出，就说明它还只是制品集合，不是运行中的工程系统。

F.2 每章行动页#

章节

今天能做什么

本周能做什么

做成的信号

第 02 章 · 四阶段演进

给当前仓库标注它主要停在哪一阶段：Prompt、Context、Skill 还是 Harness。

找一个阶段跃迁：把一条 prompt 变成 skill，或把一条 skill 变成 hook。

同一类任务的返工次数下降。

第 03 章 · 定义

写下本仓库的最小三件套草稿：AGENTS.md、pre-commit、HarnessCard。

把其中一条规则接到真实命令。

至少一次 commit 被正确拒绝。

第 04 章 · 三大护法

选一个最弱护法：SDD、TDD、MDD。

给该护法交付一件最小制品。

团队能说清这件制品保证了什么属性。

第 05 章 · 矩阵

给 12 格各打 0–5 分，不争论，先填证据。

挑最低一格，合入一件制品。

HarnessCard 有一格提升，且有文件证据。

第 06 章 · 运行

指定一位 Groom owner。

安排一次 30 分钟熵审计。

有一条过期规则、坏链接或无主仪表盘被处理。

第 07 章 · OpenHarness

对照 OpenHarness 的工具边界，列出本仓库智能体可用工具。

给高风险工具加审批或沙箱边界。

高风险工具调用有日志和 owner。

第 08 章 · Superpowers

找一条重复三次以上的工作流。

把它写成 skill 或命令清单。

智能体不再靠口头 prompt 记流程。

第 09 章 · lazy-scrum-team

给关键制品加状态：draft、review、approved、archived。

定义谁能批准、谁能退回、退回时附带什么证据。

返工不再沉默发生。

第 10 章 · Claude Code

清点 hooks、skills、MCP、权限弹窗。

把客户端特有配置指回 AGENTS.md canonical 入口。

客户端配置不再互相复制散文。

第 11 章 · 自审计

用附录 D 给自己的仓库打一张 HarnessCard。

合入一个能复现的修复。

修复前后有 delta，而不是只有叙述。

第 12 章 · 30/60/90

选一格。

给这格安排 owner 和复盘节奏。

30 天后它仍然活着。

F.3 五条迁移路径#

已有 CLAUDE.md#

不要把 CLAUDE.md 和 AGENTS.md 维护成两份长文。把项目事实、命令、边界、danger zones 收进 AGENTS.md；CLAUDE.md 只保留 Claude Code 特有说明，或作为 symlink / 薄镜像指回 AGENTS.md。

完成标准：两份文件没有互相矛盾的规则；修改命令或目录边界时，只需要更新一处。

已有 .cursor/rules#

把 .cursor/rules 看作客户端窄规则，而不是项目总规约。项目级规则进 AGENTS.md；Cursor 专属的 UI、索引、编辑器行为留在 .cursor/rules。

完成标准：换成 Codex、Claude Code 或其他 agent client 时，仍能从 AGENTS.md 读到项目主规则。

已有 CI#

CI 是牧场，不等于护栏。把最常见、最便宜、最应该提前失败的检查前移到 pre-commit 或 tool hook：格式、快速单测、schema、密钥扫描。

完成标准：至少一种错误不再等到 PR 才被发现。

已有文档站#

不是所有文档都该进马具。新员工 onboarding、长篇背景说明仍然是文档；智能体每轮必须遵守的边界、命令和 danger zones 才属于 AGENTS.md。

完成标准：AGENTS.md 像机场标识，只指路和设边界；深文档用链接引用，不复制。

已有 dashboard#

先不要新增第十三块面板。挑一条会改变工程决策的北极星指标，例如 turns-to-green、每周被拒绝次数、成本上限触发次数、规约漂移数。

完成标准：周会里有人根据这条指标改变了下一步行动。

F.4 四组好坏例子#

AGENTS.md#

坏：

请写高质量代码，遵循最佳实践，保持简洁。

好：

Before editing `todo/storage.py`, run `pytest tests/test_storage.py`.
Do not edit `deploy/` or `.env*` unless the task explicitly asks for it.
Every new CLI command gets a `--help` string and `tests/test_<cmd>.py`.

差别：坏例子要求态度，好例子声明边界和命令。

pre-commit#

坏：

- id: pytest
  entry: pytest
  args: ["tests/"]
  pass_filenames: false

如果 tests/ 为空，它会永远通过。

好：

- id: fast-tests
  entry: pytest -q -m "not slow"
  language: system
  pass_filenames: false

再配一条初始化检查：安装当天必须证明它能拒绝一个真实坏例子。

dashboard#

坏：

Agent Dashboard: token count, request count, latency, cache hit, errors, cost...

好：

North Star: mean agent turns-to-green on the fixed benchmark.
Owner: MDD owner.
Review cadence: Mondays, 10:00.
Action threshold: +20% week over week opens a Groom ticket.

差别：坏例子展示数据，好例子改变行为。

PR 验收#

坏：

LGTM. Tests pass.

好：

| Check | Evidence | Owner |
|---|---|---|
| `AGENTS.md` unchanged or versioned | diff link | Architect |
| Fast tests pass | CI link | Developer |
| New behavior has acceptance case | test path | Reviewer |

差别：坏例子给感觉，好例子给证据和角色。

F.5 按角色落地#

角色

应该拥有的东西

每周要问的问题

一线工程师

一条本地可跑的护栏。

我今天有没有把一个反复出现的问题变成命令或测试？

Tech Lead

AGENTS.md 和架构 danger zones。

智能体最近一次越界，是规约没写清，还是护栏没接上？

Reviewer

验收表和 hard / soft gate 分类。

这次 review 是靠记忆，还是靠可复用制品？

EM / TL

HarnessCard 与季度节奏。

分数提升有没有对应产出指标？

Oncall

事故回灌到 Groom 的路径。

这次事故有没有产生一条新规则、新测试或新信号？

F.6 第一次落地会议议程#

时间盒：45 分钟。

  1. 5 分钟：读第 03 章一句话定义。

  2. 10 分钟：给当前仓库 12 格打初分，只填证据，不辩论。

  3. 10 分钟：找最低分的两格，选更尴尬的一格。

  4. 10 分钟：定义一件 30 天内能合入的制品。

  5. 5 分钟：指定 owner。

  6. 5 分钟：写下成功信号，必须是"被拒绝、被度量、或改变决策"中的一种。

会议结束时只需要产出一张卡片：

Cell: SDD × Bridle
Artefact: AGENTS.md
Owner: <name>
First gate: listed test command must exist
Success signal: one incorrect edit is prevented or redirected within 30 days
Review date: <date>

这张卡片比十页战略文档更有用。它小、可合并、可复盘，也会迫使团队把 Harness Engineering 从概念变成工作。