让 Agent 自己走完整个流水线

mattpocock/course-video-manager · AI 原生开发实践逆向复盘

这不是一份「用 AI 写代码」的心得，而是一份把软件开发流程改造成机器可执行状态机的工程档案。 15 个月、3534 次提交、483 个 PR，作者把「领域词汇、工程纪律、架构决策、验收标准」全部写成了 Agent 能直接读懂并自我约束的文本， 再用 GitHub label 当状态机驱动一支无人值守的智能体流水线。

分析对象 mattpocock/course-video-manager 提交跨度 2025-07-23 → 2026-10-30 提交 3534 AI 参与 75.6% 取证方式 仓库契约 + git 历史 + 代码

01一页看懂

02这个项目在做什么

Course Video Manager（CVM）是 Matt Pocock（TypeScript 教育者，Total TypeScript 作者）为自己的课程生意写的单人内部工具：管理课程结构、分镜脚本、录制、剪辑、导出、发布到 YouTube / TikTok，一路到交付日历。它不是一个玩具项目——

最后一条是整个实践的分水岭。这不是一个「Agent 搞砸了就 git reset」的项目——写错一行，可能毁掉的是正在录制的素材或生产数据。后面你会看到，作者对「隔离」的偏执程度，直接来自这个前提。

0315 个月的转型曲线：从手工到无人值守

把每个月的提交数（柱）和 AI 参与率（折线）叠在一张图上，能清楚看到这条曲线的形状。注意纵轴已经剔除合并提交，否则 2026-10 的 1354 次提交里有一大半是 merge，会把参与率压到 40% 的假象上。

四个阶段

阶段	时间	AI 参与	在发生什么
手工期	2025-07 → 12	0%	188 次提交，全部人写。脚手架（create-react-router）、Drizzle、db 层、课程视图。唯一的例外是 10 月的 4 次尝试。
跃迁期	2026-01 → 03	87→91%	提交量从 326 冲到 582。RALPH: 前缀提交暴增（2 月 153、3 月 474）——无人值守批处理循环在跑。
平台化期	2026-04 → 07	70→78%	AFK 平台成型：8 个 GitHub Actions 工作流、label 状态机、Sandcastle 运行器契约。RALPH 循环退场（6 月 0、7 月 18）。
质量期	2026-08 → 10	36→89%	8—9 月谷底是 ADR 决策 + Animatic 攻坚；10 月回到 89%，同时 .claude/skills/verify-cvm/ 长到 417 行——重点从「让 AI 写代码」转向「让 AI 自证正确」。

04底层：四层上下文契约

这个项目最贵的资产不是代码，是那 4809 行写给 Agent 读的文本。它们按「加载时机」分成四层，Agent 在不同阶段读不同的层：

作者对这个分层的态度写在 CLAUDE.md 里，值得原样引用：

“Read it while writing code, not only while reviewing it: "every any is a leak" binds the hand that writes the cast. It sits at the repo root rather than in .sandcastle/ for that reason.”

在写代码的时候读它，而不是只在评审的时候读。「每个 any 都是一处泄漏」这句话约束的是写下那句 cast 的那只手。所以它放在仓库根目录，而不是藏在自动化目录里。

05实践一：词汇即接口

多数团队给 Agent 的上下文是「代码库 + 任务描述」。这个项目的第一层给的是一张命名表——578 行的 GLOSSARY.md，每个词条长这样：

**Course**:
The primary domain entity: a structured collection of versions, sections,
lessons, and videos. It is not backed by any repository on disk (ADR 0018).
_Avoid_: Repo, Project

**Draft Version**:
The one CourseVersion that can still change, and the only one that accepts
writes to sections, lessons, videos and clips. There is exactly one per course.
_Avoid_: Current version, Working version

注意三件事：

• 定义里带 ADR 编号（ADR 0018）——词汇和决策是交叉索引的，不是两套文档。
• 每个词都有 _Avoid_ 反义词表。这不是修辞洁癖：一个 Agent 如果把「Course」叫成「Repo」，它会在代码里引入一个不存在的磁盘仓库概念，然后写一堆错误代码去 sync。
• 状态是记录的、不是推断的（Draft Version → Pending Version → Published Version）。Agent 最擅长「看起来合理」的推断，而领域状态恰恰不能推断。

docs/agents/domain.md 把这条纪律变成了对 Agent 的硬要求，并给出了唯一的正确反应：

“If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
_Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_”

如果你的输出和已有 ADR 冲突，显式说出来，不要静默覆盖。

06实践二：决策沉淀为 ADR，且必须写下被否方案

56 份 ADR 覆盖从「课程版本快照」到「录制服务何时启动」的全部结构性决定。但真正有价值的是它们的写法——每份都有 Rejected alternatives 和 Consequences 两节。看 ADR 0008 的片段：

## Why
A PRD's sub-issues are not independent — earlier sub-issues frequently
subsume later ones. By the time the agent reaches sub-issue 4, the rename /
refactor / cascade work it describes may already have landed in the commit
that closed sub-issue 2.

## Rejected alternatives
- **Check "branch is ahead of `main`" instead of "this run produced commits".**
  Closer to the right invariant, but still wrong: it would fail a legitimate
  first-sub-issue scenario...
- **Reorder the workflow so PR creation precedes sub-issue close**...
  Not adopted yet — current ordering is fine once the no-commit case is
  accepted as success.

这份 ADR 记录的是一次系统性的自我纠错：原来的守卫规则是「Agent 一个提交都没产出就算失败」——但这个规则恰好惩罚了正确的行为（工作已经在前面的切片里做完了）。作者把它改成 ADR 而不是悄悄改代码，因为：

• Agent 读到这份 ADR，下次遇到「无事可做」的场景就知道可以合法地什么都不做，而不是强行编点提交出来凑数。
• 被否方案阻止了下一个 Agent（或三个月后的作者自己）把这个坑再踩一遍——「为什么不用『分支领先 main』这个更直观的判据」这个问题已经被回答过了。

“If the agent silently does nothing (genuine bug, not "work already done"), the workflow still chains forward. The PR review step at the end of the PRD is the catch-all for "did this PRD actually deliver its acceptance criteria" — not the per-sub-issue commit count.”

如果 Agent 真的什么都没干（不是「活已干完」而是真 bug），流水线照样往前走。兜底的是 PRD 末尾的评审环节，而不是每个切片的提交数。

07实践三：标准必须是 exit code，不是散文

CODING_STANDARDS.md 有 409 行散文。光靠散文，Agent 会读、会点头、然后照样违反。作者的答案是 19 个 check-*.sh / .ts 脚本（共 2623 行），把纪律编译成退出码：

check = check:static && test && check:client-build
check:static = check-effect-tsc && typecheck && lint && lint:boundaries
  && check-file-tokens   && check-no-dirname   && check-no-gitlinks
  && check-script-db-url && check-db-clients   && check-clip-inserts
  && check-env-example   && check-routes-folder && check-entity-links
  && check-duration-format && check-response-body && check-fs-writes
  && check-toast-import && check-effect-guards && check-frontend-state
  && check-background-jobs && check-complexity

这些守卫不是泛泛的 lint。它们编码的是这个项目的具体教训。看 check-toast-import.sh 开头的注释：

# Every toast goes through apps/local/app/components/ui/toast.tsx, which
# clamps its text, adds "Show more", and gives error toasts a "Copy" action.
# A toast imported straight from "sonner" skips all of that, so only the
# files that wrap sonner (and the wrapper's own test) may import it.

它甚至知道该放过哪些文件（三个白名单），并且报错信息里给了正确的替代方案：

ERROR: sonner imported directly — import toast from "@/components/ui/toast" instead:
"@/components/ui/toast bounds every toast (four-line clamp, Show more, Copy on errors).
For a caught error, use toastError(error, fallback) from the same module.

三个设计细节

1. 每个脚本都支持 --all。默认是扫描 staged 文件（跑在 pre-commit 里，快）；CI 里用 --all 扫全部。提交循环要短，CI 要全。
2. 提交前的检查是 CI 的一半。文档明说：pre-commit 跑快速部分，故意省掉 check:response-body，「为了让提交循环保持短」。
3. oxlint 是「建议」而非「阻塞」。原文：它的 correctness 警告是一份手工清理的存量待办，「你碰到的文件里有一条警告是邀请，不是拦路石」——只有那些编码了已记录标准的规则才是 error。这条区分极其重要：如果所有 lint 都是硬错误，Agent（和人）会学会绕过它。

还有一个更小的例子，说明这条路走得多远——一个 5 行的 hook，专门拦 npx tsc：

# .claude/hooks/block-npx-tsc.sh
if [ "$FIRST_WORD" = "npx" ] && echo "$COMMAND" | head -1 | grep -qE 'npx\s+tsc(\s|$)'; then
  echo 'Use `pnpm run typecheck` instead of `npx tsc`' >&2
  exit 2
fi

注释里还写着：只在 npx 真的是被执行的第一个词时才拦，不拦「提交信息里提到 npx tsc」这种文本参数。

08实践四：用 GitHub label 当状态机

这是整个实践里最激进的一步：作者没有自建任务数据库。议题的状态完全由 label 表达，8 个 GitHub Actions 工作流监听 label 变化来推进。

docs/agents/afk-agent-platform-spec.md（65 KB）是这份设计的完整规格，开篇就声明了它的野心：

“This document is the source of truth. You should be able to re-implement the whole system in a fresh repository from this spec alone, without reading the original workflow YAML.”

这份文档是唯一事实来源。你应该能只靠它，在一个全新的仓库里把整套系统重建出来，而不需要去读原始的 workflow YAML。

label 就是状态

Label	打在	含义
agent:to-issues	PRD 议题	把 PRD 拆成扁平的子议题列表
agent:implement	议题	同一个 label 触发两条不同流程——有子议题就走 PRD 模式，没有就走单议题模式
agent:queued	议题	可以干了，但被原生 GitHub 依赖阻塞着；阻塞者一关闭就自动提升
agent:in-progress	议题	一把锁：加上它属于「接受任务」的一部分，移除它写在 always() 里
agent:review	PR	评审并主动改进这个 PR
agent:blocked	议题 / PR	运行失败或被拒绝，需要人来看

注意 agent:implement 的歧义消解方式——按议题的「形状」判断，而不是靠人选择：

# 有子议题 → 这是 PRD，交给 agent-implement-prd.yml，这里静默跳过
# 有父议题 → 这是别人的子议题，拒绝运行（子议题从不直接打标签）
# 都没有   → 独立议题，正常实现

三条硬不变量

“One issue → one branch → one PR. Branch names are deterministic (agent/issue-<n>-<slug>)…
Nothing auto-merges to the base branch. Review marks a PR ready for review and posts a review with event: "COMMENT" — never APPROVE. A human approves and merges.”

第三条尤其值得注意：评审 Agent 发的永远是 COMMENT，从不 APPROVE。而且它不能关闭 review thread——「解决线程是评审者（人）的活，Agent 只能回复」。

09实践五：编排器独占变更权，Agent 只吐文件

整份规格里最重要的一句话，被作者称为「central design rule」：

“the orchestrator owns every tracker/VCS mutation (labels, comments, pushes, PR creation, issue closing). The agent runner only emits files. This seam is what makes the runner swappable and the system testable — the agent never holds a GitHub token and never calls the GitHub API to mutate state.”

编排器拥有所有 tracker / VCS 变更，Agent 运行器只输出文件。这条接缝让运行器可替换、让系统可测试——Agent 从不持有 GitHub token，从不调用 GitHub API 去改状态。

契约具体长这样：

这个设计的收益是具体的：Architecture Review 工作流（每工作日定时跑一次，扫代码库找深化机会）也是只吐一份 PRD 的结构化输出，由编排器去建议题。作者明确写了：

“This holds universally — even Architecture Review only emits a PRD as structured output; the orchestrator creates the issue.”

10实践六：produce / extract 两遍式，以及输入容忍

这是全篇最「懂 LLM」的一段。问题很具体：让一次 LLM 调用既干活又吐严格 JSON，很脆——一个格式错误的 blob 会让整次运行失败，而活已经干了（副作用已发生）。作者的两种解法：

输入容忍：模型会漂移

更见功力的是作者对「模型输出不稳定」的处理方式——不是加更多约束，而是在 schema 里接受别名：

• 接受 path 或 file；接受 body 或 comment
• 接受单个整数 line，或字符串 lineRange（从中解析出前导整数）
• side 默认 RIGHT
• 解析完之后，编排器脚本会丢弃任何 path+line 不在真实 diff hunks 里的行内评论（幻觉锚点），以及任何 commentId 不在已抓取线程里的回复

最后一条是关键：不指望模型不犯错，而是在落库前用真实 diff 做一遍交叉验证。规格里那句小标题叫 Input tolerance (hard-won robustness)——「hard-won」两个字，说明这是踩出来的。

11实践七：垂直切片，且切片必须扁平

.claude/skills/to-issues-project/SKILL.md 负责把 PRD 拆成子议题。它的核心规则叫 tracer-bullet（曳光弹）：

“Each slice delivers a narrow but COMPLETE path through every layer (schema → API → UI → tests), NOT a horizontal slice of one layer…
Sub-issues are flat — a sub-issue must not itself need sub-issues. If a slice is too big to leaf, split it into multiple peer slices instead of nesting.”

配套的几条约束都很实在：

• 先做 prefactor。「让改动变简单，再做那个简单的改动」——任何前置重构都单独成片，放在列表最前面。
• 每个切片必须能在一次会话里独立完成。「别把切片设计成一次会话做不完的规模」。
• 顺序即依赖。如果 B 依赖 A 的 schema，A 必须在前。
• 正文不写文件路径。原文：「避免具体的文件路径或代码片段——它们很快就会过期。」唯一例外是原型产生的、比散文更精确编码了某个决定的片段（状态机、reducer、schema、类型形状）。

模板里还有一处微妙的安排：子议题正文故意不包含 Closes 指令。关闭子议题是 PRD 模式工作流的职责，关闭 PRD 本身靠 PR 描述里的 Closes #<PRD>。谁关什么，是设计好的，不能让 Agent 顺手关错。

12实践八：验收必须是真实浏览器自证，而不是「测试绿了」

这是我认为整个仓库最值得抄的一份文件：.claude/skills/verify-cvm/SKILL.md，417 行。它解决的是一个所有人都有的痛点——Agent 说「我做完了，测试通过了」，但 UI 根本没生效。

作者把它写成了硬性流程，塞在 CLAUDE.md 的最显眼处：

“Any change with a visible effect in the UI is checked in the browser with verify-cvm before you open the PR. Passing tests and a green check do not replace it… The PR body states what you clicked and what you saw, with screenshots or the evidence path. A change with no UI effect says so in one line — No UI change — instead.”

任何对 UI 有可见影响的改动，在开 PR 之前都要用 verify-cvm 在浏览器里跑一遍。测试通过和 check 变绿不能替代它。PR 正文要写清楚你点了什么、看到了什么，附截图或证据路径。没有 UI 影响的改动就写一行「No UI change」。

最后那半句是点睛之笔：「没有 UI 改动」也必须显式声明。不给 Agent 留「我也不知道算不算」的模糊地带。

三个我觉得最狠的细节

1. 它连「作者正在录视频」都知道。每个动作前自动调用 is-filming.sh，在录制就打印 PAUSED、每 60 秒复查、自己继续。「别绕过暂停」——因为录制时抢 GPU 会毁掉素材。
2. 它拒绝自己造凭据，也拒绝自己更新快照。模板库缺失时的指令是：「停下来问 Matt」，并且明令禁止 Agent 自己跑 db:verify-snapshot（那是唯一读生产的一步）。两个脚本都会拒绝 Agent 的 shell。
3. 它承认自己的盲区。功能地图 features/README.md 末尾老实写着哪些页面「还没画进来」（Diagrams、归档课程、API Token…），以及 6 个已映射功能的多个入口。原文：「在你宣布某功能已验证之前，先查查这个索引有没有列出同一个行为的另一个入口。」

证据的定义也被写死了四条：走真实用户路径（路由 + 按钮，不是自己搓一个 API 调用）、拍动作前和动作后两个状态、验证副作用（回读那一行，而不只是看页面）、看控制台（水合失败的截图是看不出来的）。

13量化复盘

规模与节奏

指标	数值	说明
提交总数	3534	其中 940 个是合并提交，2594 个是实质提交
时间跨度	15.4 个月	2025-07-23 → 2026-10-30
AI 署名提交	1961	占实质提交 75.6%；含合并提交口径则是 56.5%
RALPH: 前缀提交	766	无人值守批处理循环产物，2026-06 后归零
合并的 PR	483	平均每个 PR 约 5.4 个实质提交
提交粒度	中位 9 文件	均值 14.6；59% 的提交 ≤10 个文件；最大 184
峰值日	325 提交	2026-10-09 单日，其中大量是并行 worktree 的合并
代码 / 测试行	347k / 126k	653 个测试文件，测试密度约 36%

模型谱系：一年换了 10 种配置

署名 trailer 里留下了完整的模型演化痕迹，说明作者一直在换模型，而不是绑定某一个：

模型	提交数	说明
Claude Opus 4.6	862	主力，横跨 2026 年上半年
Claude Opus 5	611	2026 下半年主力
Claude Opus 5.5	544	当前默认（merging.md 指定每个提交都带它的署名）
Claude Opus 4.5	238	2026 年初
Claude Sonnet 4.5	95	轻量任务
Claude Opus 4.8 (1M)	68	1M 上下文版本
Claude Sonnet 4.6	60	轻量任务
Claude Opus 4.7 (1M)	44	1M 上下文版本
Claude Opus 5 (1M)	37	1M 上下文版本
Claude Opus 4.6 (1M)	22	1M 上下文版本

口径说明：同一提交可能匹配多个模型名（如「Opus 5」是「Opus 5 (1M」的前缀），所以上表之和大于 1961。趋势可放心引用，绝对数请按「主要型号」理解。

14代价与风险：老实说

15可复用清单（按投入产出比排序）

#	做什么	投入	为什么值 / 怎么起步
1	写一个带 _Avoid_ 的术语表	半天	最便宜、见效最快。20 个核心概念就够。 Agent 立刻停止造同义词。
2	把「不许做」写成守卫脚本	1—2 天	先守三条最痛的（写生产库、绕过 hook、直接依赖底层库）。错误信息必须给出正确替代。
3	「测试绿了」之外加一道 UI 自证	2—3 天	不必做 417 行。最低配：一条命令起隔离环境 + 强制 PR 正文写「我点了什么、看到了什么」。
4	ADR 必须写 Rejected alternatives	边际成本	改模板即可。它拦住的是「看起来更好的错误」——最贵的一类返工。
5	有副作用的 Agent 任务拆成 produce / extract	1 天	今天就能改。凡是「先干活再吐 JSON」，都拆成两遍。失败率立刻下降。
6	模型产出的「位置」一律用真实数据校验	半天	文件名 + 行号 + issue 编号，落库前拿真实 diff 过一遍，不存在就丢。
7	Agent 不持有写权限，只吐文件	架构决定	编排器独占所有远端变更。换模型 / 换 runner 时零改动。
8	垂直切片 + 扁平子任务	边际成本	切片要能独立验收、一次会话能做完。禁止嵌套。
9	永不自动合并；Agent 永不 APPROVE	零成本	一条规则，守住最后一道闸。也别让它关闭 review thread。
10	统计 AI 参与度时先剔除合并提交	5 分钟	否则你的数字会低 20 个百分点，然后得出错误结论。

16证据索引与复算命令

本报告的每一个数字都有一条命令可以复跑。分析过程全程只读，未对被分析仓库做任何修改。

# 克隆
git clone https://github.com/mattpocock/course-video-manager.git
cd course-video-manager

# 总提交 / 合并提交 / 实质提交
git log --oneline | wc -l                       # 3534
git log --merges --format=%H | wc -l            # 940
git log --no-merges --format=%H | wc -l         # 2594

# AI 参与度（两个口径，注意差 20 个百分点）
git log --grep='Co-Authored-By: Claude' --format=%H | wc -l                    # 1995 (56.5%)
git log --no-merges --grep='Co-Authored-By: Claude' --format=%H | wc -l       # 1961 (75.6%)

# RALPH 无人值守循环
git log --grep='^RALPH:' --extended-regexp --format=%H | wc -l                # 766

# 按月聚合（本文图二的数据来源）
git log --no-merges --date=format:'%Y-%m' --format='%H %ad'      # 分母
git log --no-merges --grep='Co-Authored-By: Claude' \
        --date=format:'%Y-%m' --format='%H %ad'                   # 分子

# 模型谱系
for m in "Opus 4.6" "Opus 5" "Opus 5.5" "Opus 4.5" "Sonnet 4.5"; do
  echo "$m $(git log --grep="Co-Authored-By: Claude $m" --format=%H | wc -l)"
done

# 规模
git ls-files | grep -E '\.(ts|tsx)$' | xargs wc -l | tail -1      # 347284
git ls-files | grep -E '\.(test|spec)\.(ts|tsx)$' | wc -l         # 653 个测试文件
ls docs/adr/ | wc -l                                              # 56 份 ADR
ls scripts/ | grep -c '^check-'                                   # 19 个守卫脚本

# PR 数
git log --format='%s' | grep -c '^Merge pull request'             # 483

# 契约体量
cat CLAUDE.md CODING_STANDARDS.md GLOSSARY.md docs/agents/*.md \
    $(find .claude/skills -name '*.md') $(find .sandcastle -name '*.md') | wc -l   # 4809

关键文件路径索引

路径	行数	它证明了什么
CLAUDE.md	81	入口导航；UI 改动必须浏览器自证的硬要求
GLOSSARY.md	578	词汇即接口；每个概念的 _Avoid_ 反义词表
CODING_STANDARDS.md	409	工程纪律散文层（再由脚本编译成 exit code）
docs/agents/afk-agent-platform-spec.md	65 KB	AFK 平台完整规格；可据它在新仓库重建整套系统
docs/agents/merging.md	~60	落地一个改动的 5 步；「永不跳过 hook」
docs/agents/domain.md	~50	ADR 冲突必须显式声明，不许静默覆盖
docs/agents/triage-labels.md	~40	5 个 triage 角色 → 本仓库实际 label 的映射表
docs/agents/queued-promotion.md	~60	竞态处理；label 触发下游需要 PAT 而非 GITHUB_TOKEN
.claude/skills/verify-cvm/SKILL.md	417	真实浏览器自证；隔离边界；Write Ledger
.claude/skills/verify-cvm/features/*.md	6 个	功能地图；老实列出「还没画进来」的页面
.claude/skills/do-work/{DB,FRONTEND}-TDD.md	56	一次只写一个失败测试；不测类型系统已证明的东西
.claude/skills/to-issues-project/SKILL.md	136	tracer-bullet 垂直切片；子议题必须扁平
.claude/skills/to-prd-project/SKILL.md	86	PRD 是 spec 不是 sketch；四类读者
.claude/skills/deploy-migration/SKILL.md	71	生产迁移只由人执行；破坏性变更走两段式
.claude/skills/optimize-loader/SKILL.md	79	性能反模式（重复取数 / 过度取数 / 串行）
.claude/hooks/block-npx-tsc.sh	5	最小可行守卫：拦 npx tsc，且只拦真执行
.sandcastle/*/prompt.md	9 个	提示词即流程操作系统；红-绿-重构写进提示词
.github/workflows/agent-*.yml	7 个	label 状态机的实际实现；形状探测 / 前置检查
scripts/check-*.{sh,ts}	19 个 / 2623 行	把纪律编译成退出码
plans/ralph.sh	~25	第一代自动化：无人值守批处理循环（已被取代）
docs/adr/0008-agent-implement-zero-commit-runs.md	~30	系统性自我纠错；Rejected alternatives 的范本

---