Urazuke — 参考资料：方法背后的案例

作者：Pablo Kuschniroff，由 Claude Code 辅助。第 4 版，2026 年 10 月 18 日。

这份文档存在的目的只有一个：让方法的流程和手册保持干净。当我在主文档、某份台阶契约或课程的某一课里断言"这是吃一堑长一智学来的"或"这是我强制推行的，因为模型应用得不对"之类的话时，我不想用日期、提交标识符和待办项编号弄脏解释。我放一个短标记，[Ref. N]，想查案例的人到这里来，就能找到它的日期、它的证据和我对发生之事的解读。不想查的人，继续往下读，不会被绊倒。

开始之前有两点说明。第一点：这些案例所出自的三个系统是真实的，如今在生产中，有真实的人在用。客户已匿名化，我称他们为"互助会"（连同它的"授权方"）和"协会"；他们的系统我称为 "Autorizaciones"和"Kikan"。第三个仓库是方法诞生的工具，yujin-forge，它是我的，用我的名字。数字、日期和提交标识符是真实的；如果哪天我得到客户的许可，我会把名字放上去。

第二点说明更重要，我在主文档里也重复了，因为我不希望它被误解：方法不是只从故障案例里来的。它来自两样结合在一起的东西。一方面，是我自己的系统工程知识，我在这些模型存在之前很久就在应用它了；我在各级台阶里要求的大部分东西，是我在一个带得好的项目里一直要求的。另一方面，是这五个月的事故一个接一个地让我看到，模型在哪些地方把这些原则应用得很脆弱：哪里说测了而没测，哪里一脸笃定地估计，哪里用一个灵机一动填上业务规则的空缺，哪里多报。所以接下来的案例是哪里需要收紧的证明，不是整个方法的起源。请带着这个视角读它们。

如何引用

在方法的任何文档里，[Ref. 26] 链接到本文件的"Ref. 26"条目。条目按来源系统分组，每组内按时间顺序排列。末尾有三份完整的年表，供想看整个序列的人参考，还有一张把每个故障映射到覆盖它的台阶的表。

A. yujin-forge：方法形成的地方（2026 年 5 月至 10 月）

Ref. 1 — 质量标准诞生（5 月 25 日）

我在 5 月 25 日写了第一份质量标准文档 SQ.md（提交 2219f7a）。它是人与代理之间的第一份 "协作契约"，我写它是因为我已经连续两周在每次会话里向模型重复同样的话：我的时间是神圣的，不花在它能自己解决的事上；不留技术债务，坏了的从根上修；文档保持最新；范围精确，不多不少只做要求的。这些在系统工程里没有一样是新的。新的是不得不把它写给一个每天早上到来时不记得昨天的合作者。这是第 1 级台阶的起源。

Ref. 2 — 第一份反模式记录（5 月 27 日）

5 月 27 日（提交 73f4029）我开了 GOTCHAS.md：一个文件，每个重复过的错误都以固定格式记在里面，它的气味、根因是什么、怎么修的，以及下次怎样在它造成伤害之前检测到它。我开它是因为模型在不同会话里犯同样的错，而对以前犯过毫无记忆。这是第 11 级台阶"反模式"的那一半。

Ref. 3 — 工作流的闸门，只在适用时注入（6 月 2 日）

6 月 2 日（提交 5b47475）我在工作流中定义了显式的闸门，编号 G1 到 G9，还有一个文档闸门 G-DOC，要求文档在变更的同一次提交中更新。我做了一个后来证明很重要的决定：每个闸门的教义只在它适用的那一刻进入代理的提示词，而不是一直在，因为上下文是有限的，多注入的都要用注意力来付账。它是"跨过闸门时注入台阶契约"这个想法的直接前身。

Ref. 4 — 测试政策重新表述（6 月 4 日）

直到 6 月 4 日，我都对一切坚持"先测试，后代码"。那天（提交 a9f59c7，文档 testing-policy.md）我接受了它并非普遍适用：默认测试在实现之后，先写测试作为小而明确的范围的选项保留，骨架必须绿色作为闸门，我还加了一个防循环的保护，一个在代理原地打转不前进时停下一切的弹窗。我讲这个是因为它表明，当我自己的某条规则显得太僵硬时，方法也会自我修正。

Ref. 5 — 决策在构建之前冻结（6 月 4 日）

在一个大冲刺之前，我在 6 月 4 日的一份决策文档中写下并编号了三个结构性决定（D1、D2、D3）。那是我第一次把一件在经典项目里一直做的事形式化：决定在构建之前写下来，附日期，让之后没人凭记忆争论它。它是第 6 级台阶的前身。

Ref. 6 — 我手里拿着一个数字，砍掉了多代理团队（6 月 5 日）

我有一个五个代理的团队（总监、分析师、程序员、测试员、骨架搭建者），它们之间互相传递工作。我做了一个有测量的实验：那个团队花了 60 美元和 73 分钟，交付了一个半成品；一次单代理的单会话花了 90 分钟，交付了可发布的东西。6 月 5 日（提交 7584f8b，记录在一篇内部论文里）我砍掉了整个团队。这是"手里拿着一个数字做复盘，然后重新设计"的第一个案例，也是第 23 级台阶要求数字而不是印象的原因。

Ref. 7 — 计划变成待办项清单（6 月 6 日）

6 月 6 日（提交 4fc82c6，待办项登记册计划）工作计划变成了待办项队列本身：一张规范的、编号的清单，附管理它的命令，每次会话刷新。不再有"计划"归计划、"任务"归任务。这是第 5 级台阶的起源。

Ref. 8 — 验证的诚实与流程类型（6 月 10 日）

6 月 10 日（提交 7ab9d8a 和 2c552c0，文档 verification-honesty.md 和 workflow-kinds.md）我让教义在每条提示词里成为必需，并写下了"验证的诚实"规则：验证网在该变红时真的变红，声明盲点，做出与已核实之事相称的断言。我还分出了三种流程类型：新项目、修正和演进。这是第 12 级台阶以及第 8 级台阶"红色"那一半的起源。

Ref. 9 — 因为没读地图而白做的工作（6 月 12 日）

6 月 12 日，一次会话没读项目的知识图谱就开始构建，整整一个下午的工作都作废了，因为它与已经写下的决定相矛盾。第 2 级台阶的必读规则由此而来：地图存在，但如果不强制读它，它不起作用。

Ref. 10 — 24 小时和 48 小时的自动驾驶（6 月 14 日至 21 日）

6 月 14 日到 21 日之间，我让代理独自工作一天，然后两天，带一份书面授权：每一块都提交并推送，不提问，我收一份摘要。我讲这个是因为它证明，当协作契约和待办项登记册做得好时，方法撑得住长时间的自主；也因为我是在那里学会带着怀疑读摘要的，那就是第 12 级台阶。

Ref. 11 — 对他人系统的诊断模式（7 月）

7 月（文档 diagnostic-mode.md）代理开始以诊断模式进入客户的生产系统：只读、受限、不动任何东西。这是第 23 级台阶驻留代理范围的第一个级别。

Ref. 12 — 从互助会的生产中取来的性能模式（7 月 22 日）

7 月 22 日（提交 873339c）我把从互助会系统中提取的规模模式纳入了工具：两个事务的模式，尤其是"动手前先测量"。那是方法第一次从一个已经在生产中的系统汲取养分，它是第 7 级台阶的一个前身。

Ref. 13 — 代理留驻在互助会的生产中（8 月 14 日）

8 月 14 日，代理被安装在客户的系统内部，作为驻留助手，有三条规则：运维之前必须有系统地图，出问题时"先给出运维解决方案"，以及开工单的能力。这是第 23 级台阶前一半的起源。

Ref. 14 — 容量估算作为闸门（10 月 10 日和 11 日）

10 月 10 日和 11 日（提交 c602725 和 0bd1b05，文档 sizing.md）我把构建之前的容量估算形式化了，在固定的选项中选择，并把它记为又一个闸门（G9）。我形式化得晚了，是在参考资料 15 里讲的 Kikan 那次教训之后，而那正是第 3 级台阶的教训。

Ref. 15 — 从第一行起就异步的持久化接口（10 月 13 日）

10 月 13 日（提交 7391cc5，文档 persistence-interface.md）我写下了这条规则：与数据库的接口从第一行起就是异步的，哪怕第一个引擎是同步的。这是一个"非对称"决定：如果你错了，代价很小；如果你不做，代价巨大。我知道，是因为在 Kikan 我没有及时做它，之后改它花了重构的整整一个阶段 E6，三套测试套件改成了异步。这是第 3 级台阶的一个案例。

Ref. 16 — 一小时四十三分的孤儿轮次（10 月 14 日）

10 月 14 日，代理工作了一小时四十三分钟，对我不可见，在那段时间里做了六次提交。那是方法的一次故障，而且难看。我在 1.18.0 版（提交 b80a659）从根上修了它：一个沉默看门狗，轮次停止给出生命迹象就杀掉它；一根进程间的牵引绳，让子进程随父进程死亡；以及 28 个测试。它落在第 12 级台阶（报告必须可见）和第 14 级（有疑问，系统不继续）。

B. Autorizaciones：真实负荷下的方法（2026 年 6 月至 10 月）

Ref. 17 — 被仓库超越的初始设计（6 月 11 日）

Autorizaciones 以一份设计文档（"选项 C"）起步。仓库飞快地超越了它：建出来的远多于纸上写的。我留下的教训，也写在第 5 级台阶里，是规格作为起点有价值，而活的计划是待办项。

Ref. 18 — 第一次无索引查询审计（6 月 23 日）

6 月 23 日，我对一个活着的系统做了第一次"全表扫描"（因为没有索引而读整张表的查询）审计。发现变成了待办项，而不是一份归档的报告。这是第 13 级台阶的起源。

Ref. 19 — Google 云的教训（6 月 24 日）

在 Google 云上头几周的基础设施错误被写成了教训，以免重复。这是后来成为第 20 级台阶基础设施手册的第一个版本。

Ref. 20 — 用户手册与系统一同诞生（6 月 26 日）

6 月 26 日，系统建到一半，就已经有了用户手册。我是有意这么做的：在经典项目里手册在最后写，那时已经没人记得任何事；有一个免费重新生成它的模型，没有借口不让它与系统一同诞生。第 20 级台阶。

Ref. 21 — 第二层备份（7 月 13 日）

在用真实数据信任系统之前，我放了两层备份：一层本地，一层在 Google 的存储里。第 15 级台阶和第 20 级的恢复手册。

Ref. 22 — PND-300：四轮才到根因（7 月 14 日）

一个 bug 回来了三次，直到 7 月 14 日找到真正的原因。之前的每次"修复"都是修症状。在这里，已经在协作契约里的"修复要么从根上修要么不算修复"，不再是一句话而成了实践：动手前必须测量假设。第 1 和第 7 级台阶。

把算术说出声，因为这两个数字是同一个案例从两边数出来的。 一共有四轮修和这个缺陷的三次回来：第1轮"修好了"它又回来（回来1），第2轮"修好了"它又回来（回来2），第3轮"修好了"它又回来（回来3），而第4轮才是找到根因的那一轮。所以这条参考的标题说四轮，这一段说它回来了三次，而按台阶分的故障表数的是三次不是根因的修：这不是矛盾，是 n 轮和 n−1 次回来。写在这里，是因为没有这一行，那三处提法读起来就像同一件事的三个不同数字——事实上，第一个复现这个案例的外部读者写的是"它回来了四次"。如果一条参考能让一个仔细读它的人得出另一个数字，缺陷在参考这一边。

Ref. 23 — 安全审计（7 月 16 日）

7 月 16 日，我做了第一次正式的安全审计，发现转成了待办项。正是它让我确信要把安全当作定期审计，而不是开头打一次勾的清单。第 13 级台阶。

Ref. 24 — 内部手册与灾难恢复手册（7 月 26 日和 29 日）

7 月 26 日和 29 日（提交 6444ce6，待办项 442，以及 a30cee3，待办项 459）我把所有运维的事 ——部署、恢复、维护——都以"无需 AI 即可手工复现"的方式记录下来。我用的标准，也在第 20 级台阶里，是如果明天没有代理，一个不编程的可信的人能照着手册做。

Ref. 25 — 失败即关闭作为反射（7 月 27 日）

7 月 27 日（提交 e18406d，待办项 452）：如果一张表不存在或一次查找失败，那一行就只是没有它的按钮；绝不弄坏整个列表。有疑问，不行动、不弄坏。而那次修正的测试是"去掉 try/except"先证红的，也就是证明了没有保护，列表会坏。第 8 和第 14 级台阶。

Ref. 26 — 对不上的计数器：1.355 对 1.234（8 月 6 日和 7 日）

对我来说，这是"用仪器验证"最完整的例子。界面上一个计数器显示 1.355 个批准，数据库查询显示 1.234。8 月 6 日和 7 日（提交 ab3e529，待办项 517，以及 1f5feb9，待办项 514），直接在只读的生产环境上核实了根因，把差额一个数一个数地分解（多了 145，少了 24；145 减 24 是 121），写了一个对旧标准先证红的测试，诊断脚本留在仓库里供下次使用。第 8、11 和 7 级台阶。

Ref. 27 — 生产者与消费者之间的对称性（8 月 6 日）

8 月 6 日（提交 50fe968，待办项 510，以及 7251129，待办项 509）我强制规定用户看到的"等待原因"要用机器人做决定时同样的闸门来计算，网格的列清单由服务器定义、前端消费。这样它们就不可能分叉。这是第 11 级台阶"每张列表只有一个所有者"的规则。

Ref. 28 — 带锁的紧急按钮、批准器的演练模式、带守卫的哨兵（8 月 7 日）

8 月 7 日（提交 0954740，待办项 524）系统的锁就位了：一个带双重保险的紧急按钮，自动批准器先在演练模式下运行（做一切，除了批准，并记录它本会批准什么），还有一个推动卡住之事的哨兵，带守卫以免推两次。第 14 级台阶。

Ref. 29 — 写在提交里的领域规则（8 月 10 日）

8 月 10 日（提交 0ae3ae6，待办项 550）提交信息原文写着："Pablo 规则：已批准 + 余额 = 回来"，"Pablo 决定 2026-08-10"。业务决定留下了日期和所有者，贴在实现它的代码旁边。第 6 级台阶。

C. Kikan：成熟的方法（2026 年 8 月至 10 月）

Ref. 30 — 带着已经写好的方法起步，以及 AUD-* 审计系列（8 月 21 日至 29 日）

Kikan 是第一个从第一天起就带着前面所有东西起步的项目：从第一次提交（8 月 21 日）起就有一份运行中的项目文件和作为计划的待办项。8 月 28 日和 29 日我做了一系列早期审计（AUD-1、AUD-2……），直接变成了 19 份待办项文档。第 2、5 和 13 级台阶。

Ref. 31 — 第一周起的持续集成；作为包的部署（8 月 28 日，9 月 23 日和 24 日）

测试从第一周起就在 GitHub 上运行（ci.yml，8 月 28 日）。部署在 9 月 23 日到来（deploy.yml，提交 bb801ed）：一个包，配置活在服务器上而不是仓库里，运行时的版本钉死。部署在启动一个月后才到来，是促成第 4 级台阶的那个错误。

Ref. 32 — 部署靠一个个待办项硬化（9 月 30 日至 10 月 4 日）

9 月 30 日到 10 月 4 日之间，有连续五个待办项只是为了让部署正常工作：两个环境的公开 URL （f85c3c9），重启之前和回滚之前重新加载服务（513c8d0，待办项 108），一个做对账而不是重复的 fixture（076df76，待办项 134），客户的材料移出被镜像的目录树（9d76af8，待办项 130），以及不再弄脏随部署传送的配置的测试套件（0bd20a8，待办项 107，10 月 3 日）。如果骨架在第一周就空着部署，这五次教训会在零功能的情况下发生。第 4 和第 15 级台阶。

Ref. 33 — 从 UAT 到生产的提升（10 月 4 日和 8 日）

10 月 4 日和 8 日（提交 4eb5ad7，待办项 027，以及 7658e2e）留下了一个把配置和活动从测试环境传到生产环境的显式回路。第 15 级台阶。

Ref. 34 — 从代码派生的模式，带锁（10 月 11 日）

在持久化重构的第 1 阶段（提交 6113319 和 68819ce），表和字段的清单从代码本身派生，有一个保护它的测试，并在共享看板上打开供我复查。这是一张只有一个所有者——代码——的列表。第 11 级台阶。

Ref. 35 — 静态棘轮，以及看不见的量具（10 月 11 日至 13 日）

在重构的第 6 阶段（提交 06b2734、f6e5221、2fc6239、1d55a93）我放了一个"棘轮"：一个没有 await、也就是不等待结果的数据库调用计数器，它只能下降，永远不能上升。然后发生了一件值得一讲的事：两次发现量具看不见代码的某些部分。先是 70 次调用，然后 84 次，而计数器为零。如果仪器不被验证，数字让人安心，并且撒谎。第 7 级台阶。

Ref. 36 — 撒谎的量具与 11.b 节的五条规则（10 月 13 日和 14 日）

10 月 13 日的提交原文（880ac0f、f955620）："E7.5 的量具在一个已应用 ALTER 的数据库上撒谎"；"是 44，不是 27"。几天前，一份计划断言某类循环有 121 个，执行的人测得 79。从这一切我写了重构文档的 11.b 节，附今天成为第 7 级台阶的五条规则：带守卫的量具；仪器不存在就构建它；双向审计；近似的要标出来；执行者验证规划者的数字。概括它的那句话是："四条断言里三条是错的；有仪器的地方，精确。"

Ref. 37 — 查询预算与收紧到测量值的上限（10 月 14 日）

在第 8 阶段（提交 5926b3f、10ada00）应用的每条路径都有了一个测量过并由测试保护的数据库查询预算，数据库引擎的切换变成了按环境的开关。在第 9 阶段（0730082、7f5f1af）上限收紧到测量值加一个小余量：60 上 63。预算不是一个发明的数字。第 7 级台阶。

Ref. 38 — 按表的保留期，以及另一次会话做的完整性报告（10 月 14 日）

在第 10 和第 12 阶段（提交 f72b15a、b266f11）真实的包开始携带迁移脚本，数据保留期按表声明并在生产中限定，一份由另一次没有构建过系统的 Claude Code 会话做的完整性报告被吸收为待办项。这是第 13 级台阶里与构建者不同的审计者。

Ref. 39 — 部署只打包，以及烧光的配额（10 月 14 日）

测试每次提交跑三遍，每遍 16 到 27 分钟；16 天里消耗了 2.000 分钟的 GitHub Actions 配额，一个 23 次 push 的日子把它彻底烧光。10 月 14 日（提交 39497b0）我把回路拆开：测试只在持续集成里跑一次；部署等待那个结果，只打包。从每次提交 16 到 27 分钟，到 11 分钟。第 15 级台阶。

Ref. 40 — 二十四小时内两道管理员入口（10 月 15 日）

10 月 15 日，一天之内创建了两道管理员入口（待办项 223 和 257）。一次外部复查发现了它；我撤掉了一道（提交 69bdab2、20fdbe7、1558ee4），只留下唯一一条途径。我讲这个作为方法撑得住"快速撤销"而不出乱子的证据，也作为审计为什么必须由没有构建的人来做的证据。第 13 和第 14 级台阶。

Ref. 41 — 质量审计：一个漏洞、一个巨大的组件、一个 9.661 行的项目文件（10 月 15 日）

10 月 15 日的质量审计发现了一个依赖里的已知漏洞、一个 2.679 行的界面组件、八个在网页版和移动版之间重复的模块，以及一个长到 9.661 行、789 千字节的 CLAUDE.md，一个到了那个地步没人读、连模型也不读的文件。第 2 级台阶的规则由此而来：项目文件是纲领，不是历史，案例集另放。第 2、 11 和 13 级台阶。

Ref. 42 — 贴进聊天的密钥（10 月 14 日和 16 日）

10 月 14 日，一个数据库密钥被打印在一份记录里，16 日，几个 API 密钥出现在贴进聊天的内容里。两者都"没人看到"，两者都照样得轮换，因为一个出现在聊天、日志或提交里的密钥已经不再是密钥。第 13 级台阶。

Ref. 43 — 三份名不副实的报告（10 月 14 日至 16 日）

三个小而极具说明性的第 12 级台阶案例。10 月 14 日，一个认证错误被工具报告成了"success"字样。16 日，服务器的 CORS 只从第一个域名派生，测试环境的配置助手返回 500 错误而报告没提。还有移动应用在报告声明已验证的条件下丢失标签页。三者用同一条规则纠正：把已验证的和相信的分开，并声明盲点。

Ref. 44 — 因内存而死、看起来像测试失败的测试套件

整套测试因为内存不足"死"了（提交 1d7a20b），报告把它读成了一个失败的测试。直到看了完整的输出，才明白没有任何测试失败：是进程崩了。这是第 8 级台阶要求红色和绿色的数字、而不只是结论的原因。

D. 我在会话中强制推行的，以及我拒绝的

Ref. 45 — 四次我在会话中做的纠正，后来变成了规则（10 月）

方法里有些规则不是从提交里来的，而是来自我在会话进行中对代理的纠正，之后才形式化。我引用它们，因为它们显示了方法起源的第二个因素，我自己的工程判断对上模型脆弱的应用。"带守卫的量具，不是 grep"：喂给决定的数字用带测试的程序测，不用文本搜索。"测量假设，不只是症状"：当我以印象的形式带来一个原因时，构建之前得先测它，因为我对症状通常是对的，而原因通常在旁边。 "用日志验证限制，不用散文"：模型的一次拒绝不证明限制已生效；得强制触发并读记录。还有"先比较已发布的版本"：面对"还是坏的"，在重新诊断之前先看我看到问题的地方跑的是哪个版本。第 9 和第 12 级台阶。

Ref. 46 — 我拒绝的项目，以及排他性准则从哪里来（10 月 17 日）

第 0 级台阶的两条排他性准则不是来自我接受的项目，而是来自我拒绝的。我拒绝了没有可访问仓库、或者仓库不遵循标准的遗留技术，因为没有仓库就没有地方留证据。我拒绝了无法端到端测试的技术，那些没法执行界面、没法通过各种方法访问界面的每个元素来验证变更到达了后端的技术。我当时澄清、现在也坚持：NAC3 不是必需的；必需的是从执行界面出发做测试。

E. 完整年表

放在这里供想看整个序列、而不是零散案例的人参考。每一行都带有仓库里原样的证据。

E.1 yujin-forge

E.2 Autorizaciones

E.3 Kikan

F. 每个故障，以及覆盖它的台阶

这张表在某种意义上是梯子的证明：每次教训都必须落在某级台阶上。如果出现一个哪级都不落的，就缺一级台阶。