第 9 章：评审与落地
出处
来源：code-review · resolving-merge-conflicts · wizard · 状态：已读
一句话
评审走两轴并行：规范一条、规格一条，互不掩盖；冲突按意图解，不准中止；人才能做的步骤写成带确认闸的向导脚本，不写进 agent 循环。 落地不是「再聪明一点」，是把人和机器的步骤拆开。
核心概念
两轴评审，故意不合并
code-review 看的是 HEAD 和一个你给定的固定点之间的 diff。两轴：
- 规范：代码是否符合本仓库写下的编码标准
- 规格：代码是否忠实实现了起源议题 / 规格
两轴作为并行子代理跑，免得污染彼此的上下文，再由本 skill 汇总。
固定点是你说的（提交 SHA、分支、标签、main、HEAD~5）。没说就问。diff 命令钉死一次：git diff <fixed-point>...HEAD（三点，对着 merge-base）。往下走之前确认引用能解析、diff 非空——坏引用或空 diff 应该死在这里，而不是死在两个并行子代理里。
规格来源按顺序找：提交说明里的议题引用 → 你传入的路径 → docs/、specs/、.scratch/ 下与分支名或功能匹配的规格文件 → 再问你。没有规格，规格子代理跳过，报告「no spec available」。
规范来源：仓库里任何写明代码该怎么写的文件（CODING_STANDARDS.md、CONTRIBUTING.md）。之上永远带着 Fowler《重构》第 3 章的气味基线，即使仓库什么都没写。两条约束：
- 仓库覆盖基线。 写下的标准总是赢；它背书基线会标的东西，就压住气味
- 永远是判断。 每种气味是带标签的启发式（「可能是 Feature Envy」），不是硬违规。工具已经在强制的，跳过
气味对着 diff 匹配：Mysterious Name、Duplicated Code、Feature Envy、Data Clumps、Primitive Obsession、Repeated Switches、Shotgun Surgery、Divergent Change、Speculative Generality、Message Chains、Middle Man、Refused Bequest。每种带着「是什么 → 怎么修」。
子代理的 brief 限 400 词。规范轴：硬违规引用标准（文件 + 规则）；气味点名并引用 hunk。规格轴：(a) 规格要的但缺失或部分；(b) diff 里没人要过的行为（范围膨胀）；(c) 看起来做了但做得不对的。每条引用规格原句。
汇总时两份报告分列在 ## Standards 和 ## Spec 下，原文或略作清理。不要合并或重排发现，因为两轴故意分开。结尾一行：每轴发现总数，以及各轴内部最糟的那条。不要跨轴评出一个赢家——那正是分开要防的重排。
一份改动可以通过一轴、失败另一轴：
- 每条标准都遵守，但做的是错的事 → 规范过、规格不过
- 恰好做了议题要的，但破了项目惯例 → 规格过、规范不过
分开报告，阻止一轴掩盖另一轴。
/implement 收工必走这条。单独打它，是你想对着固定点审分支或 PR 的时候。
冲突按意图解，总是解完，从不中止
resolving-merge-conflicts 站在每条流之外：已经在冲突中途才去拿它。
- 看清当前合并 / 变基状态。查 git 历史和冲突文件
- 找到每边的一手材料。 深挖每处改动为什么做、原意是什么。读提交说明、PR、起源议题
- 逐个 hunk 解。 能保住两边意图就都保。不相容时，挑符合这次合并所声称目标的那边，并记下取舍。不准发明新行为。 总是解完；从不
--abort - 发现项目的自动检查并跑：通常类型检查，然后测试，然后格式。合并弄坏的修好
- 做完合并 / 变基。全部暂存并提交。若在变基，继续直到所有提交都变完
「按意图、不按行」是整条 skill。挑左边或右边的行，是在解文本；读两边为什么改，才是在解设计。不准 --abort 把「难」变成「退回去让人手动」——那是把冲突从系统路径里拿掉，和 Book 1「错误属于主路径」对着干。
向导：只有人能做的步骤
wizard 生成一份交互 bash，按步带人走过只有人能做的手续：开基础设施、配凭证或 CI 密钥、走不熟的第三方控制台、一次性迁移或切换。agent 自己能做的步骤，不要调它。
向导是一份脚本，带人走一遍用手做很烦、每次向 AI 重讲也很烦的手续。它打开每个 URL，精确说点哪、拷哪，接住值，写到该去的地方（.env、GitHub secrets），每阶段确认，并显示还剩几阶段。
愉快的交互已经由 template.sh 解掉：按阶段的进度、确认闸、跨平台打开 URL（包括 WSL）、隐藏的密钥输入、幂等的 .env 写入、gh secret / gh variable、收尾摘要。你的活只是圈定手续、写它的阶段。 标记以上的库在每个向导里相同；这份一致就是意义：永远不要手改它。
默认是一次性的：为跑一次而建，存到草稿或 scripts/，活完就删。用户要可重复的安装路径、该进仓库时才提交。
过程：
- 圈定。 先读仓库，不要冷问：
.env*、README、compose、工作流里每个secrets.*/vars.*都是向导必须产的值。然后把有序阶段和每阶段产的值摊给你确认 - 映射每阶段的路径。 「Dashboard → Developers → API keys → Reveal test key → copy」。当前界面或确切命令你其实不知道，就说不知道，问人或查文档；不准发明可能不存在的步骤
- 写向导。 拷模板，按依赖序一个
stage一步。URL 先打开再要值；密钥走ask_secret；持久化的值走write_env；CI 真正需要的才set_secret；不可逆动作前confirm。每个 stage 清屏，只留当前步 - 核对并交出。
bash -n；有则shellcheck；chmod +x。不要自己从头跑到尾：它开浏览器、在人输入上阻塞。静态追踪：第 1 步的每个值都被接住、落到第 1 步说的地方，每个set_secret名恰好匹配 CI 里的secrets.*。告诉人怎么跑。可重复的安装路径就提交，并从 README 链过去，让下一个人跑脚本，而不是再问 AI
完成标准在圈定那一步就已经是闸：每个阶段按序有名；每个接住的值你知道人从哪拿、写到哪、是不是密钥。
和主链怎么收
实现收工走双轴评审，然后提交。冲突是独立事件，不进主链。向导是「手续里有一步 agent 做不了」时的出口：配密钥、开控制台、不可逆的切换。把这些步骤留在追问或实现里，agent 会编界面、把密钥回显到日志，或在该确认的地方不停。
setup-matt-pocock-skills 是这套工程 skill 自己的一次向导式配置：每仓库一次，选定议题跟踪、分拣标签、领域文档布局。没有它，第 4 章和第 7 章会停下来让你先跑 setup。它是提示驱动，不是确定性脚本：先探、摊发现、跟你确认、再写。
关键洞察
- 两轴分开，是因为 agent 评审会加权合并。 「代码很干净」会盖住「做了错的功能」；「规格对了」会盖住「在仓库里像外来人」。并行子代理加分列报告，是结构上的防掩盖，不是文风。
- 冲突 skill 拒绝中止，向导 skill 拒绝发明步骤。 两条都是完成标准：冲突必须解完；向导的每条路径必须能追到一个陌生人跟得上的具体指令。做不到就停、问，不准编。
- 人的步骤从 agent 循环里拆出去，循环才能无人值守。 这和探路图把 HITL 票与 AFK 票分开是同一判断。混在一起，无人值守的实现会在浏览器登录页上假睡。
个人思考
九章走完，主链收在这里：对齐过的决定，经会变红的测试做成代码，再分开接受「写得像这个仓库」和「做了规格要的」两道闸。和 Book 1 08-团队落地 对得上——制度比个人技巧重要——但 Matt 把制度收成了可调用的小件，而不是一份团队手册。GSD 那种框架在这一步往往还想再编一层「发布阶段」；这套 skill 停在评审和向导，把发布留给你已经有的 CI。
对照整本：Cookbooks 钉的是模型交什么；Harness 钉的是运行时出了岔子谁收拾；这本钉的是人还没决定时 agent 不准装决定，决定了之后每刀都要能单独变红。