Urazuke，验证方法 — 方法论之梯（第 4 版）

作者：Pablo Kuschniroff，由 Claude Code 辅助。第 4 版，始于 2026 年 10 月 18 日，并随着记录（docs/DECISIONES.md）里的每一次后续决定持续更新；起始日期故意保持不变，这样每次有新决定涉及这份文档时，版本历史都不需要重写。这是一份工作文档，我会随着每一个使用它的项目继续打磨；它说的任何东西都还不是定论，不过据我所知，它确实是对一个背后已经有三个生产系统的方法的第一次诚实提炼。

进入正题之前，先说一句关于它是怎么写的，因为这很重要。我是写给没有和我一起经历这些项目的人的：想用人工智能构建软件、并且希望那软件能长久的人，而不是想学编程或收集提示词技巧的人。所以我花时间解释，需要时重复，用日常的语言，并在末尾留一份术语表，收录每个缩写和每个我不小心用上的口语表达。如果你在某处碰到一个陌生的词——"棘轮"、"锁"、"失败即关闭"、"PND"——去查术语表；都在那里。当你读到像 Ref. 26 这样的标记时，要知道它是通向一个真实案例的捷径，我在参考资料文档里讲了它，附日期和证据；你可以忽略它而不丢失脉络，也可以在对细节感兴趣时跟着它走。

方法的公开仓库是 github.com/pkuschnirof/urazuke。那里有这份文档、每级台阶的契约、课程手册和参考资料，以 NAC3 的八种语言。

名字

Urazuke（裏付け）是一个日语词，指一个断言所拥有的依据：从背后支撑它的东西（字面意思是 "背面的衬里"）。动词 urazukeru 是"用证据支撑"。我在 2026 年 10 月 17 日选了它，此前因为与现有公司和项目冲突而排除了几个名字；我选它是因为它恰好说出了方法要求的东西：模型的每条断言都带着它的依据，而且依据可以不读代码就验证。名字不翻译；副标题"验证方法"翻译：*the evidence method*、*o método da evidência*、*la méthode de la preuve*、*die Nachweis-Methode*、*il metodo del riscontro*、裏付けの方法、验证方法。在本文档中，"梯子"是方法的结构——它的二十四级台阶——而"Urazuke"是整个方法。

这是关于什么的

我想说清楚我在教什么、不在教什么。我不是在教一个工具。我在教一个方法：按什么顺序做什么，每个时刻向模型要什么，它必须交给你什么，以及如何——不读代码——知道它交给你的东西是完整的。赌注是，任何人，用任何能用来编程的人工智能工具，都能通过与模型对话而不是手敲代码来构建软件，而且产出的东西稳健、可投入生产，并且——这是重点——不要求项目的所有者审查任何一行代码。我也想把它不是什么说得一样清楚：它不是一个把系统做得更快的流程。它是一个让系统可运维、可维护，而不需要任何人理解它代码里的任何一个比特的流程，因为代码由写它的那个代理式框架来理解和维护。速度，在它出现的时候，是一个后果；正因如此，这份文档里没有任何期限：期限由每个系统的规模和复杂度来定，而方法只定顺序。

有一个澄清是别人要求我写下来的，因为前一句话很容易被读成一种不是我本意的意思："不要求所有者审阅一行代码"并不等于"是为没有系统知识的人编程而设计的"。不是这样的。这个方法的首要目标不是降低技术门槛，让任何人在对软件是怎么构建的一无所知的情况下也能构建软件：而是给必须为一个系统负责的人一个方法论上的支点，让模型构建出来的东西带着一贯的系统工程的扎实，对抗模型在没有人用书面方式要求时应用这些同样原则的脆弱之处。所有者不读代码是我把闸门放在哪里、以及一个人不读实现也能验证什么的结果，而不是承诺任何人，不管懂不懂，都能在完全不理解自己在指挥什么的情况下指挥一个软件项目。合同实际要求的人物画像处在中间：能跑一条命令、能管理一个凭证、能恢复一次备份、能看懂CI配额在告诉他什么、并且能识别出模型交付的东西不够的人——既不是纯粹的外行，也不是已经会编程的人。

还有另一个澄清，关于成本。按这架梯子走，比让模型一次性解决所有问题要多花一些token：每一级台阶都多加一个提示词、一次自己的验证、一个模型也必须维护的产物。一眼看不出来的是它省下的东西。一个在没有这些闸门的情况下构建的系统，迟早会需要重新返工：回头补做没做过的容量估算，追查一个本该在第8级就被红色测试抓住的错误，重写没人及时审计过的东西。这种返工，无论是token、时间还是钱，都比每一级台阶多花的那一点提示词贵得多。我把它花在前面，清醒地花，为的是不在后面盲目地多花一倍。

听起来雄心勃勃，确实如此。但我有几乎没人有的东西：三个正是这样构建、如今和真实客户一起运行的真实系统，接下来的每条规则都是从它们提取的。所以我问自己的问题不是"能行吗？"，因为已经行了。问题是"我做了什么，按什么顺序，其中什么真正起了决定性作用？"。这架梯子是我的答案，也是三件事的基础：方法的文档、课程学员要做的实践，以及手册。之后我会把它作为执行流程导出到我的工具里，让工具来引导方法，而不是靠人的记忆。

方法从哪里来，以及我不希望被误解的

这一切有一种容易的解读，我想在它扎根之前拆掉：方法是我每挨一次打就贴上一块补丁的集合。不是这样，而且我在意把它说准确，因为这改变了读每级台阶的方式。

方法出自两个结合在一起的因素，单独哪一个都不够。第一个是我自己的系统工程知识。我应用那些任何来自系统工程的人一眼就能认出的东西已经很多年了：设计之前先调研，写下来的需求，带数字的容量估算，设计、构建、作为证据的测试、可复现的部署、运维、定期审计、作为产品一部分的文档。我在二十四级台阶里要求的大部分东西，是我在一个带得好的项目里一直要求的。我不是为模型发明的；是从以前带过来的。

第二个因素是这五个月的事故一个接一个让我看到的：模型在哪些地方把这些原则应用得很脆弱。一个模型完全知道什么是测试、什么是根因、什么是容量估算；你问它，它解释得比很多工程师都好。但在实践中它说测了而没测，一脸笃定地估计一个只有业务才有的数据，用它觉得合理的东西填上业务规则的空缺，因为被训练成有用而多报，还建一把不自知地撒谎的量具。这些案例的每一个，我在参考资料里讲了，都准确地告诉我哪里需要收紧：哪里一条对我来说显而易见的原则需要变成提示词里的显式条款、变成闸门、变成我不读代码就做的验证。

所以，当我在某级台阶说"这是我在某次事故之后强制推行的"时，我不是说原则诞生在那里。我是说我在那里证实了模型不会自己应用它，必须以书面形式要求它。方法是一直以来的系统工程，以一个不知疲倦、没有证据就不能相信的构建者所需要的硬度来应用。伤疤是哪里需要硬度的证明，不是原则的起源。

方法的三个使用场景

在往下讲之前，先说一个分叉，它在前几版里没有，是一位读者很有道理地向我提出来的。这份文档是看着一个空文件夹来描述梯子的：第 0 级台阶决定项目要不要接，第 4 级部署没有功能的骨架，第 5 级打开第一个功能块。那是最适合学习的情形，但不是最常见的情形。方法有三个使用场景，在打开代理之前最好知道自己在哪一个里，因为入口不一样：

1. 新项目。 空文件夹，加一个带着请求的所有者。从第 0 级台阶进，二十四级按顺序登。这就是这份文档所描述的，连同它的契约和课程手册。
2. 对一个用方法做出来的系统做演进-纠正。 系统已经登过梯子：有契约、地图、带证据关闭的待办项、测试套件、部署链和手册。从第 5 级台阶进，开一个功能块，然后跟着循环走；第 13 级定期；第 23 级在每个阶段收尾。这是时间线（B 部分）的阶段 4。
3. 对一个不是用方法做出来的系统做演进-纠正。 一个在跑的、有用户的系统，别人做的或者自己没有证据做出来的，现在要纠正它或者让它成长。既不从第 0 级进，也不从第 5 级进：要从一个八个站点（N0 到 N7）的规范化阶段进，它用自动发现把启动阶段各级台阶产出的全部输入物恢复出来并带上来源标记，在不重写系统的前提下给它造一条安全带，之后才以纠正模式或演进模式打开循环。那条路在它自己的一页上，演进-纠正之路，而且它在课程里有自己的一部分，带第二个引导项目。

有一样东西落在外面，我把它点名出来：技术迁移不是方法的使用场景；那是另一个项目，而且一般会落进第 0 级台阶的排他性准则。

AI 没有中断方法：它延续了方法

这是开启一切的论点，我把它放在最前面，因为它在最常见的反对意见出现之前就拆掉了它："你怎么能信任机器写的代码？"。

我的回答是，业界在二十年前就已经不再信任代码的作者了。当大部分编写工作转到初级、外包或轮换的团队时，逐行审查变得无法维持。取而代之生长起来的，是今天我们视为理所当然的一切：自动化测试、持续集成、验收标准、不绿就不放行的流水线、测试的"左移"、作为独立职能的质量控制。那是系统工程对"写的人不可信"的回答：不读他的代码，向他索要证据。

所以让一个模型来写不是跳进虚空。是把一个我们已经不信任的作者换成另一个我们同样不信任的，而且验证装置我们早就搭好了。这应该让人安心，而不是不安。而且新作者更便宜、更快，并且——与初级不同——你让它先证红时它不会生气。

因此这个方法毫不掩饰地建立在经典系统工程之上。骨架还是老样子。不可能是别的样子，因为问题还是老问题：不知道会有多少数据，不知道客户要什么，不知道构建的是不是要求的。AI 没有改变问题；它改变了谁做每一部分、以什么成本。连第 0 级台阶的适格性准则 X2 都是经典工程：可测试性作为合同条件。

这里面什么是旧的，什么是新的

旧的，而且值得说明是旧的：阶段的骨架、验证者相对于构建者的独立、测试作为证据、文档作为产品的一部分、设计前的调研。

真正改变的，也是我的贡献所在的，是三件事：

1. 人的努力去哪里。 在经典方法中，人写规格说明，写代码，另一个人审查。这里人只做两件事：决定，以及验证产出物。其他一切——起草、构建、测试、测量、记录——都由模型做。所以每级台阶都以"不读代码的完整性检验"结束：那正是人仍然不可或缺的地方，再无其他。

2. 作者也制造证据。 这是唯一真正新的点，也是足以撑起整整三级台阶的细微之处。初级写可疑的代码，但不制造证据：测试和测量由别人搭，或者至少由别人看。模型则在同一次会话中生产代码 *和*测试*和*量具*和*报告，无论对错都用同样笃定的语气。我见过：撒了两次谎的量具 Ref. 36，被报告为"成功"的认证错误 Ref. 43，四条断言错了三条。所以"审查证据而不是代码"仍然是正确的原则，但证据必须证明它自己：看到变红的测试（第 8 级台阶）、带守卫的量具（第 7 级）、把已验证和相信分开的报告（第 12 级）、与构建者不同的审计者（第 13 级）。这不是新的担忧：是质量控制独立性的同一种纪律，再往里走一步。

3. 产出物的成本。 在经典方法中文档昂贵，所以做一次就过时。这里重新生成是免费的，所以规则变成"在同一次提交中"和"无需 AI 即可手工复现"。曾经无法达到的理想变成了闸门。

对于课程和公开展示，这诚实地定义了定位：它不是"新的编程方式"；它是应用于一个不知疲倦、却不能轻信的构建者的系统工程。对来自系统工程的人，它听起来熟悉，降低了戒心；对来自 vibecoding 的人，它给了他们缺的东西，恰恰是骨架。它也把我与那些兜售速度、省掉整个骨架的工具区分开。

A 部分 — 如何读每级台阶

每级台阶有八个部分，始终相同，以便比较：

• 意图：它追求什么，一句话。
• 时机：在项目的哪个时刻登它，登一次还是重复。这部分是第 4 版新增的，我在 B 部分详细解释，因为一个没有时间线的方法是一张良好意愿的清单。
• 输入：登它之前必须存在什么。
• 产出物：登上去之后留下什么书面或可执行的东西。总是具体的东西：一个文件、一个测试、一个脚本。
• 闸门：要进到下一级，什么必须为真。不满足，就不登。
• 谁决定：项目的所有者、代理，或者没有人，因为它是自动的。
• 避免的故障：这级台阶防止的那类问题，附一条指向我证实它的真实案例的短引用。
• 契约：写着它如何执行的文件：上下文、提示词、结果、检验、警报信号。

两点重要说明。第一：梯子对工具是中立的。每个产出物是一个文件、一个测试或一个脚本；没有一个要求我的工具或任何其他工具。Forge 把它们自动化（闸门、命令、待办项登记册），但台阶没有 Forge 也存在。第二：台阶是按登的顺序编号的，并归成四个阶段：0 到 4 是启动阶段，每个项目登一次；5 到 12 是随每次变更重复的循环；13 到 20 是上线生产阶段，登一次，在第一次部署之前；21 到 23 是运维阶段，那时系统已经活着。第 23 级闭合循环，回到第 0 级，为下一个项目做准备。在一个阶段内部，编号就说明顺序；在阶段之间，循环反复进行，而另外三个阶段各登一次。但"不是严格顺序的"不意味着"任意顺序"：B 部分准确地说了每一级何时登、中间发生什么。

B 部分 — 时间线：每级台阶何时登，台阶之间发生什么

这部分在之前的版本里不存在，它的缺失是一个严重缺陷：方法说了做什么、怎么验证，但没说何时。而"何时"是一个方法的一半。一个照字面理解它的读者，可能一级接一级地登完二十四级台阶，然后问：那基础设施、持续集成与部署链、需求摄入、功能开发、全部流程的端到端测试、对界面的人工查看，以及人工验收测试，是在什么时候做的？这一切都会发生，而且发生在精确的时刻，在台阶之间和台阶之内。我在这里把它写下来。

B.0 整个流程，用一张图

在表格之前，先看图。它用流程记法画（BPMN 风格：圆形是事件，矩形是任务，菱形是闸门，虚线箭头是返回流），而且它说了三件表格说得更差的事。第一：流程从方法之外开始，从需求工程开始，它是一个前提条件，而且是常设的：它永远不结束，每条新需求都会重新进来。第二：一条新需求不是只进循环；它重新注入到评估类的台阶，因为它可能改变当初决定架构的那些数字（"乘以十"还扛得住吗？），从那里再往下走。第三：流程终结在人对测试用例的手工执行上（第 10 级台阶），而那次执行发现的东西又作为需求回到循环。回路是靠人闭合的，不是靠机器。第四点，这次修正之前的图没有画出来：当系统构建的东西会对世界产生后果（扣款、发送）时，循环会在第 14 级台阶之后重新打开，这时闸锁已经上好，用来在演练模式下构建那部分，然后再继续走向生产链（第 15 级）。这不是回到起点：这是同一道闸门（这个块关闭了吗？）又走了一遍，只不过现在安全网已经准备好了。

flowchart TB
  subgraph RE["需求工程 · 外部的、常设的前提条件"]
    direction TB
    E0((业务的请求)) --> RE1["调研：访谈、用例、领域模型、原型"]
    RE1 --> RE2["新的或改变的需求"]
  end
  subgraph ARR["启动 · 台阶 0 到 4，一次"]
    direction TB
    P0["0 适格性"] --> P1["1 协作契约"] --> P2["2 定义与语义树"] --> P3["3 容量估算"]
    P3 --> G1{"架构扛得住这些数字吗？"}
    G1 -- 是 --> P4["4 带闸门的骨架"]
    G1 -- 否 --> P3
  end
  subgraph LOOP["循环 · 台阶 5 到 12，每次变更"]
    direction TB
    P5["5 带规格的待办项"] --> P6["6 写下的决策"] --> P7["7 测量"] --> P8["8 先证红与端到端"] --> P9["9 代码质量"] --> P10["10 人工测试用例"] --> P11["11 对称性"] --> P12["12 诚实的报告"]
    P12 --> G2{"功能块收尾了吗？"}
    G2 -- 否 --> P5
  end
  H1["由人手工执行测试用例"]
  subgraph OUT["上线生产 · 台阶 13 到 20，一次"]
    direction TB
    P13["13 审计"] --> P14["14 锁"] --> P15["15 到生产的链条"] --> P16["16 可观测性"] --> P17["17 持久化"] --> P18["18 漏洞"] --> P19["19 性能"] --> P20["20 活的文档"]
  end
  D((第一次部署))
  subgraph OPS["运维 · 台阶 21 到 23"]
    direction TB
    P21["21 资源监控"] --> P22["22 错误监控"] --> P23["23 驻留代理与复盘"]
  end
  RE1 --> P0
  P4 --> P5
  RE2 -. "重新注入：数字变了吗？" .-> P3
  RE2 --> P5
  G2 -- 是 --> H1
  H1 -- "发现 = 需求" --> RE2
  H1 --> P13
  P14 -. "有后果的部分现在才构建，闸锁已经上好" .-> P5
  P20 --> D --> P21
  P21 -. "偏离 = 待办项" .-> P5
  P22 -. "错误 = 待办项" .-> P5
  P23 -. "回到第 0 级，为下一个阶段做准备" .-> P0

如果图没显示出来（markdown 阅读器不画 mermaid），上面那段文字完整地描述了它；在 HTML 版里它会自己画出来。

B.1 一个项目的五个阶段

一个用这个方法带的项目经历五个阶段。中间三个对应梯子的循环、上线生产和运维这三个阶段；阶段 1 是启动阶段；阶段 0 是初始摄入，方法同样覆盖它，尽管它本身不是一级"台阶"。我不写时长：时长取决于所要求之物的规模和复杂度，而一个写下来的时长会变成一个虚假的期待。不取决于规模的是顺序。

这张表是给新项目的。当系统已经存在、而且不是用方法诞生的时候，阶段 0 和 1 被规范化阶段取代（阅读、安全带、测量和排序），它在演进-纠正之路那一页；阶段 2、3 和 4 是一样的。

在一个有用户、有后果的项目里，长大的是循环：功能。启动、上线生产和运维在小系统和大系统里形状一样；变的是要测量多少，不是测量什么。

B.2 台阶与台阶之间发生什么

缺的就在这里。对每个阶段，各类任务做什么、在相对于台阶的哪个精确时刻做。按行读这张表：每一行是一类工作，每个单元格说它在那个阶段里何时做。

有个细节我想强调，因为这是来自 vibecoding 的人错得最多的地方：全部流程的端到端测试不是最后做一次。是三次，在三个尺度上。每个待办项，测那个待办项触及的流程。每个功能块收尾时，测到那时为止存在的全部流程。生产之前，用将要提升的精确版本测全部流程。如果你只做第三次，你到最后会得到一个几周内没人端到端测过的系统，上线生产变成一周的修补。

B.3 循环的节奏：一个典型的功能块

一个功能块是四到八个相关待办项的集合，合在一起做出业务能用的东西："基本日程表"、"提醒"、"月报"。它从里面看是这样的：

1. 开启功能块。 所有者用散文讲他想要这块做什么。代理把它转成编号的待办项，附"如何验证"，并问那些不足以写出可验证待办项的东西（第 5 级台阶）。所有者排优先级。
2. 每个待办项。 代理宣布取哪个待办项、为什么。如果途中出现一条没写下的业务规则，停下来问（6）。如果待办项依赖一个数字——多少查询、花多久——先用带测试的仪器测它（7）。构建。完成后，按这个顺序收尾：先证红的测试、绿色、邻近项的回归，以及所触及流程的一次端到端测试（8）；代码质量的闸门为绿（9）；该流程的人工测试用例，写给一个人看（10）；以及，如果变更触及系统两部分之间的契约，另一边在同一次提交中更新（11）。报告把已验证的和相信的分开，并声明盲点（12）。所有者读报告，看界面的截图。不读代码。
3. 功能块收尾。 完整的端到端套件在测试环境里绿色。所有者或一个可信的用户执行该块的人工测试用例（10），记下发生了什么、什么失败了；每一处失败作为纠正型待办项回到循环。读该块的质量报告（9）。用新界面更新用户手册（20，在同一次提交中）。只有那时才开启下一块。

在循环的典型一天里，方法向所有者要的东西又少又有限：回答两三个业务规则的问题，读两三份报告，看两三张截图。仅此而已。如果要求的比这更多，要么代理在问它自己能解决的事（第 1 级台阶），要么所有者在读代码（那第 8 级或第 12 级就有什么没起作用）。

B.4 人工里程碑

我用一张清单总结一个人——所有者或他信任的人——必须看或用系统的时刻。它们很少，在精确的时刻，而且没有一个能委托给代理：

• 启动结束：打开测试环境的 URL，看到空系统。
• 每个触及界面的待办项：看来自测试环境的真实截图。
• 每个功能块收尾时：在测试环境里执行该块的人工测试用例（10）并记下结果；失败的东西作为需求回到循环。
• 第一次部署到生产之前：对全部流程做验收测试，照着全部人工测试用例走。
• 在第 20 级台阶：一个不编程的人在测试环境里照着恢复手册做。
• 每次部署到生产之后：验证运行的版本是想要的那个，并对关键流程做一遍只读的走查。
• 第一次部署之前，在第 19 级台阶：把业务的容忍度放在旁边，读负载测试的数字和断裂点。
• 在监控的每个周期（21 和 22）：和代理一起读周期报告，决定哪个偏离、哪个错误变成待办项。

其他一切——测试、测量、审计、文档——由模型做，人通过产出物验证，而不是通过代码。

B.5 需求如何进来：从调研到语义树再到待办项

我想在这里停一下，因为这是经典系统工程最有话说、而 vibecoding 最热情地忽视它的地方。一个需求不是客户在聊天里的一句话。它是客户的一句话，经过几十年前就存在、在模型在前的情况下依然有效的方法处理过——因为你要求它，模型就非常善于应用这些方法；你不要求，它就非常不善于。

我用的、也是方法在每个阶段要求的方法：

• 与所有者的访谈，开放，散文，有记录。它们是阶段 0。我不试图让它们完整：我试图让代理察觉它们缺什么。
• 用例或用户故事，业务能叫出名字的每个流程一个："前台录入一个预约"、"患者收到提醒"。每个有参与者、触发器、步骤、结果和例外。它们是开启一个功能块的单位。
• 领域模型：业务的实体、它们的属性、它们可能的状态和状态之间的转换。它是语义树（见下）的心脏，也是避免模型发明业务没有的状态的东西。
• 每个故事的验收标准，形式是"给定某种情况，当发生某事，那么看到某结果"。它们变成每个待办项的"如何验证"，之后变成端到端测试。
• 界面原型，哪怕是一张画。对界面的人工查看从这里开始，在代码存在之前。
• 可追溯性：每个需求都能追到实现它的待办项、测它的测试和关闭它的提交。在方法里可追溯性不是一张单独的矩阵：它是待办项本身，它引用自己的来源和证据。

语义树。 它是把这一切理顺的产出物，是代理每次会话读的地图（第 2 级台阶）。它是一棵树，不是一张清单：根上是系统；下面是领域或模块；每个下面是它的参与者、它的流程（用例）、它的实体及其状态、它的界面和它的外部集成；每个节点下挂着触及它的待办项和影响它的决策。由代理根据调研构建，你纠正，随每个功能块增长。它的价值是双重的：给模型提供它将要触及的节点的精确上下文，而不必读整个项目；给你一种不读代码就验证代理理解的系统就是业务要的那个的方式。当一个待办项不挂在任何节点下，要么树不完整，要么待办项超出了范围；两样十秒钟就能看出来。

详细规格活在待办项里。 在经典方法里有一份需求规格文档，长长的，会老化。这里那份文档被分解：每个待办项带着自己的完整规格，待办项之和就是系统的规格。一个写得好的待办项有：标题；它挂在语义树的哪个节点下；引发它的故事或用例，用客户的原话；对所要求之事的详细描述；适用的业务规则，附决定和日期；进出的数据；受影响的界面，有原型就附上；边界情况和例外；验收标准；以及如何验证。代理根据你的散文请求起草它，问那些不足以写成规格的东西，你在它被构建之前读它。读一个待办项的规格是你离读代码最近的地方，而那正是恰当的距离。

已关闭的待办项是文档。 这是闭合圆圈的东西。一个待办项关闭时，不删除，也不空着归档：它保留着规格、引发它的决定、关闭它的证据（红色和绿色的数字、界面的截图、测得的数字）、提交和日期。已关闭的待办项队列于是就是系统的功能历史：建了什么、为什么、什么时候、怎么测的。变更日志、用户手册的新章节，以及六个月后有人问"系统为什么这样做？"时的答案，都从那里来。课程手册教你在每个待办项关闭时、同一次会话中、作为第 5 级台阶例行的一部分，索要这份文档。

C 部分 — 二十四级台阶

它们按登的顺序排列。运维质量的那六级台阶（16 到 19 在第一次部署之前；21 和 22 在之后）是我原本做了却没给它命名的那些：让系统在运行时能被看见，让它扛得住当初估算的量级，让它没有已知的窟窿，以及，一旦进了生产，不要让任何人是从一个生气的用户那里才知道出了问题。两个监控终结在和其他一切同样的地方：循环，作为纠正型待办项。如果你是初学者，这六级的每一份契约，以及第 9 和第 10 级的契约，都以一段用日常语言解释它那些词的段落开头，而术语表里全都有。

步骤 0 — 这个项目能这样做吗？（适格性）

有一件先于一切的事，它不在任何仓库里，因为它总是已经决定好才到来：一个项目是否用这个方法来做的决定。这是一条我在脑子里活了几个月、正在写完的准则。两条排他性准则我已经清楚，它们来自我拒绝过的项目，而不是我接受过的 Ref. 46："不"比"是"更好地定义了边界。加权准则我还在校准，并如此标注。

• 意图：在打开仓库之前，决定一个项目是否用这个方法、由一个代理在前来做。因为如果你进入一个不行的项目，方法就退化为"用 AI 编程"，而那时所有者真的会去读代码。
• 时机：只一次，先于其他一切。如果系统已经存在，这一级台阶要登它的遗留版本（演进-纠正之路的 N0 站点），多四条准则，而且 X2 要一个界面一个界面地测。
• 输入：客户的请求、业务领域、数据、技术、可用的环境，以及谁将是所有者。
• 产出物：一页的适格性表，准则打了分，附决定：可行、不可行，或有条件可行。
• 闸门：排他性准则全部绿色，加权准则的得分超过阈值（阈值我还没定）。
• 谁决定：所有者。今天是我；想法是让方法允许另一个人用同一张表来决定。
• 避免的故障：进入一个代理无法自己验证自己、或没有一个能做决定的领域所有者的项目，最后人逐行审查代码。
• 契约：peldanos/peldano-00-elegibilidad.md。

两条排他性准则。

一条对工具中立价值千金的精确说明：NAC3（我的工具用来让界面可由程序操作的协议）不是条件；它是我今天达成这一点的手段。中立的准则是这样的：界面可由程序执行，界面的每个元素都可通过其各种方法（点击、输入、读取状态）访问，使得一个测试能走完界面，然后在后端验证效果。一种界面不向"驱动"（比如 Playwright）暴露其元素的技术被排除在外，哪怕它有仓库。

还有一个我认为重要的解读：归根到底 X1 和 X2 是同一个条件从两面看。代理必须能自己端到端地验证自己，并把证据留在仓库里。X1 是"证据留在哪里？"的一半；X2 是"证据怎么产生？"的一半。

假设 加权准则，尚无权重。 我把它们标为假设，直到用头几个端到端使用方法的项目校准它们。

之前版本里有两条准则（代理能自己测试，项目是新的或可审计的），我分别把它们吸收进了 X2 和 X1，因为它们是后果，不是单独的准则。

步骤 1 — 协作契约（代码之前的规则）

在写一行代码之前，把你和代理将如何工作写下来。看起来像走形式，其实不是：它是避免第一个月百分之八十挫败的东西。想想代理每天早上到来时不记得昨天；没写下来的你每次都得重复，而且每次都有点不一样。

• 意图：在第一行代码之前确定人和代理如何工作。
• 时机：只一次，紧接着适格性之后。当一次教训要求时复查。
• 输入：项目方面的没有；它是第一个文件。你这方面的：你的工作偏好。
• 产出物：一份质量标准文档，至少说明：人的时间是神圣的（不花在代理能自己解决的事上）；零技术债务，也就是坏了的从根上修并在同一次会话中加回归；范围精确，不多不少只做要求的；用用户的语言说话；文档在同一次提交中更新；以及绝不把没做的事宣布为已完成。
• 闸门：契约在仓库里，每次会话都读。
• 谁决定：所有者。代理可以提议修改，但不能自行编辑契约。
• 避免的故障：因为觉得是好主意而扩大范围来"帮忙"的代理；把债务留到"以后"（而以后永远不来）的代理；以及把它*以为*做了的事报告为已完成的代理。我第一次写它，是在每次会话重复同样的话两周之后 Ref. 1。
• 契约：peldanos/peldano-01-contrato-de-convivencia.md。

步骤 2 — 项目定义与必读

代理的每次会话从零开始。给它一张地图，短的，并强制它在动任何东西之前读。两半同样重要：没人读的地图不起作用，长地图没人读。

• 意图：让每次会话一开始就知道项目是什么、处于什么状态、已经做了哪些决定。
• 时机：写一次，契约之后；整个项目期间随每个新决定保持最新。
• 输入：契约（第 1 级台阶）和业务调研。
• 产出物：一份运行中的项目文件，这里要强调：短。它是纲领，不是历史。加上系统的语义树（见 B.5）：领域、参与者、流程、带状态的实体、界面和集成，每个节点下挂着待办项和决策。加上一个活状态文件，记录正在做的事和开放的疑问。
• 闸门：代理在动代码之前读项目文件和语义树，并且验证过它读了。
• 谁决定：所有者定义；代理保持最新。
• 避免的故障：两个，很具体。因为没读地图而白做的工作 Ref. 9。以及长到没法读的项目文件 Ref. 41：运行中的文件和案例集必须是不同的文件。
• 契约：peldanos/peldano-02-definicion-y-lectura.md。

步骤 3 — 在设计架构之前先做容量估算

这是跳过代价最大的一级台阶，我知道，因为我跳过了。结构性决定用数字来做，而原始数字在业务手里，不在模型手里。

• 意图：让结构性决定（哪个数据库引擎、接口是同步还是异步、多大并发）用数字而不是凭喜好来做。
• 时机：一次，搭骨架之前；业务规模变化时重做。在小项目里是半页和一个决定。
• 输入：和业务一起做的容量数据调研，天然不完整；以及旧系统（如果存在）的读访问权。有些数据只有业务才有，模型推断不出来：所以提示词要求它评估数据是否完整，并索要缺的，而不是一脸笃定地估计。
• 产出物：一份容量估算记录，附固定的选项（三四个具体选项）和选中的那个；以及明确声明的"非对称"决策，比如"持久化接口从第一行起就是异步的，哪怕第一个引擎是同步的"，因为你错了代价很小，你不做代价巨大。
• 闸门：容量估算在搭骨架之前记录在案。
• 谁决定：所有者在固定选项中选择；代理用数字呈现它们。
• 避免的故障：用一个撑不住容量的存储起步，等到改接口要花整整一个重构阶段时才发现 Ref. 15。
• 契约：peldanos/peldano-03-dimensionar.md。

步骤 4 — 带闸门的骨架

在系统做任何有用的事之前，它必须空着启动、测试和部署。是的，空着。因为通往生产的路是产品的一部分，而知道它能走通的唯一方法是在还没有东西可失去的时候走一遍。这是做全部初始基础设施和集成与部署链的台阶，所以它是启动阶段里最长的一级。

• 意图：拥有一个在还没有任何功能时就能启动、测试和部署的系统。
• 时机：一次，在启动阶段末尾，容量估算之后、任何功能之前。它是启动阶段的收尾。
• 输入：容量估算（第 3 级台阶）、环境调研，以及将要部署的地方的凭证。
• 产出物：持续集成绿色的骨架、搭好并带一个冒烟测试的测试结构、一次能用且运行了两次的到测试环境的部署，以及书面声明的流程闸门。
• 闸门：骨架绿色，持续集成运行，到测试环境的部署在零功能下能用。所有者打开了 URL，看到了空界面。
• 谁决定：代理执行；所有者目视批准。
• 避免的故障：启动一个月后才发现部署，为了让它能用连付五个待办项，而功能已经在赌桌上 Ref. 32。
• 契约：peldanos/peldano-04-esqueleto.md。

步骤 5 — 计划就是待办项

这里有一个想法，一旦抓住就再也不放手：没有"计划"归计划、"任务清单"归任务清单。待办项清单就是计划。 而且每个待办项都说如何验证，因为那是你要看的东西，而不是看代码。

• 意图：一条唯一的工作队列，有顺序、有闸门，是项目的真相。
• 时机：在开启第一个功能块时创建，启动阶段一结束就建；整个项目期间每次会话都用。每个新功能块都从把客户的请求转成待办项开始。
• 输入：客户对该块的请求、审计，以及人工测试的发现。
• 产出物：一份编号待办项的登记册，每项附详细规格（见 B.5）：它挂的语义树节点、用客户原话写的来源故事、描述、适用的业务规则、数据、界面、边界情况、验收标准和如何验证。以及，关闭时的已完成待办项文档：证据、提交、日期、途中决定的事。已关闭的待办项是系统的功能历史。
• 闸门：没有带规格的待办项，任何变更都不能进；待办项用有文档的证据关闭，不用"搞定"。
• 谁决定：所有者排优先级；代理按顺序提议并执行。
• 避免的故障：两周内"被超越"而过时的规格 Ref. 17；以及六个月后没人知道为什么做了的工作 Ref. 7。
• 契约：peldanos/peldano-05-pendientes.md。

步骤 6 — 决策写在代码旁边

模型遇到业务规则里的空缺时，把它填上。它不停下来问；它用它觉得最可能的东西补全，和写其他东西一样自然。所以这级台阶不是"写下决策"，而是"要求它缺一条时停下来问"，而当你决定时，决定连同你的原话、你的名字和日期留下来。

• 意图：让每条领域规则或结构性决定有所有者、日期和位置。
• 时机：循环的每次会话中，每当代理碰到一条没写下的规则。通常每个功能块两三次。也在启动阶段（第 0 和第 3 级台阶）和上线生产阶段（12 和 13）。
• 输入：与所有者的对话。这是唯一的输入。
• 产出物：写在提交里和决策记录里的决定，用原话。如果所有者没回答而代理不得不选，就标为 "缺省决策"以便复查。
• 闸门：一条业务规则没有它的来源句就不进代码。
• 谁决定：所有者。永远。没有例外。
• 避免的故障：六周后争论为什么某事是这样；更糟的是，代理因为觉得合理而发明领域规则。把规则连同日期和所有者写进提交的做法来自互助会 Ref. 29，在构建之前冻结决策的做法来自我的工具 Ref. 5。
• 契约：peldanos/peldano-06-decisiones.md。

步骤 7 — 构建之前先测量，用一把自己也要被验证的量具

对我来说，这是所有台阶里最成熟的一级，也是我最晚形式化的一级，因为我以为模型会自己应用它。它不会。规则是：没有一个决定什么的数字出自印象；它出自一把活在仓库里、有测试、你能运行的量具。而且量具也要被验证，因为量具会撒谎。

• 意图：让每个喂给决定的数字都出自一把带测试的仪器，而且仪器本身也被审计。
• 时机：在循环里，每当一个待办项依赖一个数字或一个原因假设时，在构建之前。在启动阶段，容量估算是第一个案例。在小项目里，"测量"就是用一条命令数一数，并把数字连日期记下来。
• 输入：假设，所有者的或代理的，以及对要测量之物的访问权。
• 产出物：仓库里带守卫的量具；数字附命令和日期；双向审计；标出的近似值；以及，如果适用，按路径的预算，收紧到测量值并由测试保护。
• 闸门：五条规则：带守卫的量具；仪器不存在就构建它；双向审计；近似的要标出来；执行者验证规划者的数字。
• 谁决定：数字。所有者带来假设；代理在构建之前测它。
• 避免的故障：撒谎的量具和四个数字错了三个的计划 Ref. 36；看不见 84 次调用的零棘轮 Ref. 35。这些规则是我在会话中写的，在它们成为教义之前 Ref. 45。
• 契约：peldanos/peldano-07-medir.md。

步骤 8 — 作为锁的测试，先证红

一个你从没见它失败过的测试，你不知道它是否证明了什么。所以这里的规则不是"写测试"；是"证明测试对旧代码变红，然后变绿，然后回归仍然绿色"。而从界面到后端的端到端测试，是替代你读代码的东西。

• 意图：让每个重要的行为都有一个坏了就失败的测试，并且确切地知道它会失败。
• 时机：循环里每个待办项关闭时。所触及流程的端到端测试，在同一次收尾里。完整的端到端套件，在每个功能块收尾时和每次部署到生产之前。
• 输入：已实现的变更和附"如何验证"的待办项。
• 产出物：新测试、作为凭据的红色输出（命令、它所针对的版本、数字、退出码：用一条命令重新跑一遍所需要的一切）、带数字的绿色输出、同一会话中邻近项的回归，以及说明对什么先证红的提交。
• 闸门：带凭据展示出来的红色、绿色、回归绿色。而且代理不恰好模拟它要测的那部分。
• 谁决定：代理执行并报告；所有者读报告，不读测试。
• 避免的故障：因为什么都不证明而通过的测试，以及掩盖 bug 的绿色 Ref. 44。计数器的案例是对旧标准先证红的测试的完整例子 Ref. 26。
• 第一个块的红色：上一版本没有该模块时，红色通过变异来证明（植入的缺陷、变红的测试、凭据里的 diff），而不是靠无法加载的文件。
• 契约：peldanos/peldano-08-tests-en-rojo.md。

步骤 9 — 由机器验证的代码质量，带闸门

所有者不读代码，而这正是要点。但代码总得有人维护，而一份今天能跑、明天没人看得懂的代码，就是会在第三个月被讨回的债。如果没人读它，那就得让一台机器来看：在每次提交时，把一个人类评审会看的东西变成一个带限制的数字。我在我所有项目里都做过，只是没把它命名为一级台阶。

• 意图：让代码质量在每次提交时由机器验证，以构建变红作为后果，并且永远不自己退化。
• 时机：在开启第一个功能块时搭起来，在每次 push 时运行；每个待办项都在质量为绿时关闭，在先证红的测试（8）之后；报告在每个功能块收尾时和所有者一起读。在遗留系统里，第一次运行就是基线。
• 输入：持续集成（4）、至少一个已关闭待办项的代码，以及所有者决定的那些限制（作为起点，文件和函数的大小）。
• 产出物：只用一份配置的 linter 和格式化工具；大小和复杂度的限制；重复和死代码的检测；带棘轮的覆盖率；语言允许的话还有类型；docs/CODE_QUALITY.md，每条限制附它的实测值； docs/GATES.md 里的闸门。在任何有用户的项目里必需，只在没有真实用户时可选的变异测试（故意植入的错误，按测试抓住了多少来计数），其按功能块的分数放在覆盖率旁边。
• 闸门：质量为红时什么都不合并；没有写下理由就没有对 linter 的例外；绝不为了通过而调高某条限制。
• 谁决定：所有者定限制，并决定哪些现在修、哪些带日期容忍；代理测量，并在同一次提交中修。
• 避免的故障：一次审计发现的那个两千多行的组件和那个将近一万行的文件，因为没有任何限制拦住它们 Ref. 41；在没人看见的情况下变差的质量数字 Ref. 35。
• 契约：peldanos/peldano-09-calidad-de-codigo.md。

步骤 10 — 人工测试用例和功能一起写，并且由人来执行

自动测试由模型写、由模型跑，它们检验的是模型理解到的东西。还缺一个人用自己的眼睛和手、照着脚本做的那种测试。脚本由构建了那个功能的同一个人、在同一个时刻、根据验收标准写出来；由人在每个功能块收尾时、在验收时和每次部署之后执行；而失败的东西作为需求回到循环。这就是过程图所展示的那个回路的闭合。

• 意图：让每个功能诞生时就带着它的人工测试用例，写给一个不知道系统是怎么造的人看，并让每一次人工执行把失败的东西作为待办项重新注入。
• 时机：每个待办项关闭时，在先证红的测试（8）和质量（9）之后。由人在每个功能块收尾时、第一次部署之前（验收）和每次部署之后以只读方式执行。
• 输入：待办项的验收标准（5）、带数据的测试环境，以及谁执行、什么时候执行的决定。
• 产出物：docs/MANUAL_TESTS.md，每条被触及的流程一个用例（标识符、待办项、前置条件、附做什么和看到什么的步骤、包含一个人可验证的后端效果的预期结果、数据、执行表）；记录在案的执行；每处失败一个纠正型待办项。
• 闸门：没有任何触及界面的待办项在没有它的用例时关闭；没有任何执行没有日期和名字；没有任何失败没有带着那个人原话的待办项。
• 谁决定：所有者或一个可信的用户执行；代理写用例并开待办项；模型绝不把用例标为已执行。
• 避免的故障：没有脚本的人工测试，每次找到的东西都不一样；以及当场被修掉、随后丢失的人为发现；课程引导项目里那个没有任何测试看见、而诊所负责人看见了的别扭下拉菜单。
• 契约：peldanos/peldano-10-casos-de-prueba-manual.md。

步骤 11 — 生产者与消费者之间的对称性，以及反模式记录

当你改动一端（服务器、数据库、一个机器人）时，另一端（界面、计数器、报表）必须在同一次提交中改动。支撑它的原则是每张列表只有一个所有者。而你已经付过一次代价的错误，连同它的自动检查记下来，别付两次。

• 意图：让一端的变更永远拖着另一端，在同一次提交中。
• 时机：每个触及系统两部分之间契约的待办项；契约地图在开启第二个功能块时构建，那时已经有了界面和服务器；反模式记录在每次有东西第二次坏掉时增长。
• 输入：谁生产、谁消费每个契约的地图；反模式记录。
• 产出物：服务器定义列表，消费者读取它；生产者/消费者地图；带气味、根因、修复和提前检测的反模式记录。
• 闸门：自动：代理在宣布一个变更关闭之前找另一边。
• 谁决定：没有人；它是自动的。
• 避免的故障：和查询对不上的计数器 Ref. 26；同一模块的两份副本失去同步 Ref. 41。单一来源的解决方案是我在互助会强制推行的 Ref. 27。
• 契约：peldanos/peldano-11-simetria-y-antipatrones.md。

步骤 12 — 诚实的验证与相称的报告

如果你不打算读代码，代理的报告就必须可信，而这不会自动发生。模型被训练成有用且完整，一份说 "这个我没能验证"的报告感觉上不如一份说"搞定"的有用。所以明确地向它索要坏消息、盲点和它没做的事。

• 意图：让代理的报告可信，而所有者不必读代码。
• 时机：每份报告，每个待办项，整个项目期间。这是代理告诉你的一切必须具备的形式。
• 输入：做完的工作和要求它的待办项。
• 产出物：一份三块的报告：已验证（证据在旁边）、相信（以及为什么没测）、盲点（它从所在的位置看不到的）。覆盖要求的每一项。坏消息先说。
• 闸门：没有一条断言没有它的证据。不光秃秃地说"搞定"。面对"还是坏的"，先比较已发布的版本和含修复的版本。
• 谁决定：所有者信任，或索要证据。从不审查代码。
• 避免的故障：报告为成功的错误，以及把没验证的声明为已验证的报告 Ref. 43；不可见地工作了一小时四十三分的轮次 Ref. 16。验证的诚实规则我在六月写下 Ref. 8。
• 契约：peldanos/peldano-12-verificacion-honesta.md。

步骤 13 — 作为计划输入的定期审计

每隔一段时间要用新鲜的眼光看整个系统，而看到的不进一份归档的报告：进待办项队列。重要的部分是"新鲜的眼光"：让没有构建的人来审计，因为构建的人共享自己的预设。模型的另一次会话、另一个指令文件就够了。

• 意图：每隔一段时间看完整的系统，并把看到的转成待办项。
• 时机：第一次部署到生产之前必需（它开启上线阶段）。在运维中，根据变化节奏每一到两个月一次，以及每个大阶段收尾时。
• 输入：整个仓库和只读的生产环境。
• 产出物：一份带分级发现的报告，每个发现附位置、风险、证据和优先级；按维度的分数；以及已经转成待办项的紧急发现。
• 闸门：在宣布审计关闭之前，每个紧急发现都开了待办项。
• 谁决定：所有者给发现排优先级。
• 避免的故障：读整张表的查询 Ref. 18；直到别人看才发现的两道管理员入口 Ref. 40；一个已知漏洞和一个巨大的组件 Ref. 41。
• 契约：peldanos/peldano-13-auditoria.md。

步骤 14 — 失败即关闭、锁与零静默损害

面对疑问或故障，系统不行动。并且说出来。听起来显而易见，但它是软件默认行为的反面，软件面对疑问会继续往前走。这级台阶在构建作用于现实世界的功能之前，不是之后。

• 意图：让系统面对疑问或故障时不行动，并发出警告。
• 时机：在上线生产阶段，在构建任何收费、发送、批准或删除的功能之前；每有一个新的有后果的动作就复查。新的自动化从演练模式起步，看过它几天的记录后再启用。
• 输入：和所有者一起做的有后果动作调研。
• 产出物：锁表：每个动作附其可逆性、它的锁、它的回退路径；每个锁一个先证红的测试；新的自动化在演练模式下。
• 闸门：每个不可逆的动作都有锁和写下来的回退路径。
• 谁决定：所有者逐个锁批准；系统绝不跳过它们。
• 避免的故障：重复收费、不经人的自动批准、删除客户数据。互助会的锁是范本 Ref. 28；不弄坏整个列表的反射也是 Ref. 25。
• 契约：peldanos/peldano-14-fail-closed.md。

步骤 15 — 持续集成、环境、密钥与作为产品一部分的部署

到达生产必须是一个可复现的包：测试跑一次，部署只打包和上传，配置活在服务器上而不是仓库里，回滚经过测试。这里的大部分从骨架起就已经存在；这级台阶把它向生产补全。

• 意图：让到达生产成为一个可复现的包，测试只跑一次，配置在仓库之外。
• 时机：集成链和到测试环境的部署在第 4 级台阶搭建。面向生产的收尾——真实环境、密钥、提升、经测试的回滚、防密钥的锁——在上线阶段做，在审计和锁之后。每次部署的例行贯穿整个运维。
• 输入：环境与访问调研；带集成的骨架。
• 产出物：每次提交运行一次测试套件的持续集成；等待那个结果、只打包的部署；只在服务器上的配置；书面、可重复的提升流程；经测试的回滚；阻止上传密钥的检查。
• 闸门：动生产之前同一版本测试绿色；回滚经过测试；仓库里和聊天里没有任何未轮换的密钥。
• 谁决定：所有者提升到生产；代理准备一切。
• 避免的故障：每次提交跑三遍的测试和烧光的配额 Ref. 39；因发现太晚而靠一个个待办项硬化的部署 Ref. 32；贴进聊天的密钥 Ref. 42。
• 契约：peldanos/peldano-15-ci-entornos-secretos-deploy.md。

步骤 16 — 完整的可观测性与可追溯性，级别可配置

当生产里有什么东西坏掉时，我想用一个标识符把一个动作从界面跟到数据库，不打开代码；我想能在一分钟内把生产的日志详细程度调高，不重新部署；而且我想让每个有后果的动作都留下一条应用删不掉的痕迹。

• 意图：让系统在运行时能被看见（可观测性），让每个重要动作都有它的痕迹（可追溯性），而详细程度用配置来改。
• 时机：在上线生产阶段，第 15 级之后、第 19 级之前。在遗留系统里，最低级别进安全带（N4），完整级别在这里。"每个新模块都记录并传递"这条规则在整个运维期间有效。
• 输入：按环境的配置（15）、锁的表格（14）、调研里的个人数据清单，以及日志住在哪里的决定。
• 产出物：级别可配置、不部署就能改的结构化日志；每条记录里一个从界面到数据库的关联标识符；有后果动作的一份不可变审计；健康与指标端点；docs/OBSERVABILITY.md。
• 闸门：一个真实标识符被所有层跟踪；级别不部署就改过；日志里没有任何个人数据。
• 谁决定：所有者决定日志住在哪里、保存多久、什么算个人数据；代理搭建。
• 避免的故障：那个活了一小时四十三分钟、靠日志才找到的进程 Ref. 16；没有日志可读就只能瞎着运维的驻留代理 Ref. 13。
• 契约：peldanos/peldano-16-observabilidad-y-trazabilidad.md。

步骤 17 — 持久化层的优化，前后都要测量

数据库是系统慢慢死掉的地方：一百条记录时好好的，十万条时很糟，而没人知道是什么时候开始的。在这里用数字决定，在生产之前，并且用第 7 级台阶的方法：测量、改动、在同样的数据上重新测量。

• 意图：让系统的真实查询，在容量估算的量级下，进入业务能容忍的范围，并带上防止它们再次跑出去的预算。
• 时机：在上线生产阶段，第 16 级之后、第 19 级之前；当某个功能块加进一张大表、或监控（21）显示某条查询超出范围时重复。在遗留系统里，测量来自 N6，几乎一切都"触及时偿还"。
• 输入：容量估算（3 或 N6）、生产者-消费者地图（11）、可观测性（16），以及装载了预期量级的测试环境。
• 产出物：带测试的查询量具；docs/PERSISTENCE.md，带每项改动的前后对比表、按路径的预算和每张表的保留期；每个预算一个测试。
• 闸门：关键流程里没有读整张表的查询；每个预算都有它的测试；最慢的界面在容量估算所预期的范围内。
• 谁决定：所有者逐项批准改动清单；代理测量并应用。
• 避免的故障：一个活着的系统上那些读整张表的查询 Ref. 18；不得不被收紧到测量值的预算 Ref. 37；文件上的几百万行 Ref. 15。
• 契约：peldanos/peldano-17-persistencia.md。

步骤 18 — 漏洞的扫描与解决，放进链条并带日程

审计（13）每隔一段时间带着判断力看整个系统；这级台阶只看一件事，安全，而且一直看、由机器看：依赖、代码、历史里的密钥和服务器配置。还有一条规则：一次依赖更新是一次变更，它要走循环。

• 意图：不让任何已知漏洞进到生产，并且让新的漏洞在没人碰系统的情况下也能自己被发现。
• 时机：在上线生产阶段，第 15 级之后、第一次部署之前；之后，在每次 push 时并带每周日程。在遗留系统里，第一次运行是 N3 的一部分。
• 输入：持续集成（4 和 13）、环境调研、之前的审计，以及所有者关于什么算紧急的判断。
• 产出物：四层扫描跑在链条里并带日程；docs/SECURITY_[日期].md，带发现和未扫描的部分； docs/SECURITY.md，带策略；docs/GATES.md 里的闸门；修好的 P0 和 P1，各带它的待办项。
• 闸门：没有任何 P0 开着的时候才往生产提升；一个新的 P1 自动开一个待办项。
• 谁决定：所有者定义什么是 P0 并批准修复；代理搭建并运行。
• 避免的故障：在质量审计里出现的那个已知漏洞 Ref. 41；只有另一次会话才看到的那些管理员入口 Ref. 40；被当成一张打一次勾的清单来对待的安全 Ref. 23。
• 契约：peldanos/peldano-18-vulnerabilidades.md。

步骤 19 — 量级下的性能测试与断裂点

第 3 级台阶用算式做了容量估算；这一级用跑着的系统核对那些算式：在预期量级下、在"乘以十"下，以及一直到有什么东西坏掉。断裂点是这个阶段最有用的数字，因为第 21 级的告警阈值就是从它来的。

• 意图：在第一个用户进来之前，知道系统在预期量级下、在"乘以十"下表现如何，以及它在哪里、为什么断裂。
• 时机：在上线生产阶段，第 16 级和第 17 级之后，第一次部署之前；在每次会改变架构、持久化或某条关键流程的部署之前重复。在遗留系统里，用 N6 测出来的量级。
• 输入：容量估算、打开的可观测性、优化过的持久化、关键流程，以及业务对最常用界面的容忍度。
• 产出物：仓库里带测试的负载脚本；docs/PERFORMANCE_[日期].md，带三次运行、断裂点和诊断； docs/PERFORMANCE.md，带阈值和闸门；每个瓶颈一个待办项。
• 闸门：最常用的界面在预期量级下进入容忍范围，否则有一个带那个数字的待办项；断裂点写明了是什么断了。
• 谁决定：所有者给出容忍度，并决定现在修到哪个量级的瓶颈。
• 避免的故障：只有看着生产才知道的真实负载 Ref. 12；伪装成测试失败的断裂点 Ref. 44；作为闸门的容量估算 Ref. 14。
• 契约：peldanos/peldano-19-rendimiento-y-punto-de-ruptura.md。

步骤 20 — 活的文档与一个人无需 AI 即可遵循的手册

系统必须在没有代理、也没有你的情况下能用、能维护、能恢复。如果没有代理的那天没法部署，它就没完成。而且既然用模型重新生成文档是免费的，规则就变成"在同一次提交中"。

• 意图：让系统在没有代理、也没有构建者的情况下能用、能维护、能恢复。
• 时机：用户手册随每个功能块在收尾时增长，加入新界面。三份完整的手册在上线生产阶段、第 13 级之后生成，找一个不编程的人做的测试在第一次部署之前完成。同一次提交的例行贯穿整个运维。
• 输入：在测试环境中运行的系统；第 14 和第 15 级的产出物。
• 产出物：附真实截图的用户手册、维护手册，以及写给一个必须在凌晨三点手工完成的人的基础设施与恢复手册；每份都附日期和版本。
• 闸门：文档在同一次提交中是最新的；一个不编程的人照着恢复手册做过。
• 谁决定：代理维护；所有者读手册，不读代码。
• 避免的故障：导致在错误仓库提交的过时文档；变成历史的项目文件 Ref. 41。可手工复现的手册是互助会的那些 Ref. 24。
• 契约：peldanos/peldano-20-documentacion-viva.md。

步骤 21 — 对资源、函数和超出范围查询的监控，带周期报告

第 19 级的测试说的是系统在某一天表现如何；生产是每一天，而且数据在长大。这级台阶看守资源使用，以及每个函数、每条查询的响应时间，对照第 19 级的阈值和它自己的历史，有东西出了范围就报警，并产出一份与所有者一起读的周期报告。每个偏离都是一个待办项。

• 意图：在用户看到之前看到资源或性能的问题，并让每个偏离都有原因或待办项。
• 时机：在第一次部署到生产的那一周搭起来；从那以后自己跑，报告在每个周期读（有后果的每周，小项目每月）。在遗留系统里，第一次阅读就是基线。
• 输入：第 16 级的指标、第 17 级的预算、第 19 级的阈值、只读的生产，以及和所有者一起决定的渠道和周期。
• 产出物：带历史的采集；按阈值和按偏离的告警；自动生成的周期报告；docs/MONITORING.md；写进契约的阅读例行。
• 闸门：一条被挑起来的告警到达了渠道；第一份报告里每个偏离都有原因或提议；没有任何阈值在没有书面理由的情况下被调高。
• 谁决定：所有者决定渠道、周期和现在处理哪个偏离；代理搭建并提议。
• 避免的故障：不得不被收紧到测量值的上限 Ref. 37；在没人看的情况下被烧光的配额 Ref. 39。
• 可验证的窗口：周期测量附带从数据库读取的最早和最晚记录；手工输入的窗口要标明，且只发出提醒。
• 契约：peldanos/peldano-21-monitoreo-de-recursos-y-rendimiento.md。

步骤 22 — 错误监控与周期报告：没有任何错误没有待办项

一个生产中的系统会产生没人报告的错误。这级台阶在它们藏身的三个地方（后端、任务、用户的浏览器）捕获它们，把它们分组，对新出现的和在长大的发出告警，并产出一份周期报告。两条规则：没有任何错误没有待办项，而且不存在"已知错误"，除非有一个待办项说明为什么容忍它、容忍到什么时候。

• 意图：不让生产里任何错误不被看见，并让每一个都用复现它的红色测试来关闭。
• 时机：在第一次部署的那一周搭起来，和第 21 级一起；从那以后自己跑，带当场的告警和周期报告。在遗留系统里，第一天就已经存在的错误带着速度标记变成待办项。
• 输入：第 16 级的日志、锁的表格（14）、包含浏览器在内的生产，以及第 21 级的渠道和周期。
• 产出物：集中且分组的捕获，没有个人数据；按新错误、在长大的复发错误和有后果的错误发出的告警；带按流程错误率的周期报告；docs/MONITORING.md；写进契约的例行。
• 闸门：一个在浏览器里引发的错误被一路跟到报告；没有任何复发错误没有待办项或带日期的理由。
• 谁决定：所有者读报告并决定处理什么；代理捕获、分组并提议。
• 避免的故障：被报告为成功的认证错误 Ref. 43；因为没有复现错误而一直走到根因的四轮折腾 Ref. 22。
• 错误来源：观测系统的工具的错误单独放在报告的专属一节里，不打开待办项。
• 契约：peldanos/peldano-22-monitoreo-de-errores.md。

步骤 23 — 系统里的代理，以及带数字的复盘

最后一级台阶有两部分，闭合同一个循环。第一：代理留驻在生产里，范围受限，以一个人的名义行动。第二：方法本身用数字复查，学到的东西回到第 0 级台阶，为下一个项目做准备。

• 意图：让代理留驻在生产里、范围受限，并让方法用数字复查。
• 时机：驻留代理，在进入运维时，第一次部署到生产之后。复盘，在每个阶段和项目收尾时；必需，哪怕只有一页。
• 输入：生产中的系统、事故、成本。
• 产出物：驻留代理的文档，附它的系统地图、它的范围、它以一个人的名义的凭证，以及范围之外的事会被拒绝的证明；以及带来源数字的复盘，每个事故映射到一级台阶，至少一条对梯子的具体修改提案。
• 闸门：代理不能做所有者没批准的事；复盘至少产生一条对梯子的修改。
• 谁决定：所有者。
• 避免的故障：没有地图就运维的代理；以及一个项目接一个项目原样重复、不学习的方法。砍掉多代理团队的那次带数字的复盘是范本 Ref. 6；驻留代理，是互助会的那个 Ref. 13。
• 契约：peldanos/peldano-23-agente-residente-y-retrospectiva.md。

D 部分 — 如何执行、要求多少，以及用什么工具

每级台阶如何执行：契约

八个部分的卡片说了每级台阶追求什么、何时登、留下什么。但一级台阶只有在看到怎么要、必须回来什么、我怎么知道回来的是完整的时，才算真正理解。所以每级台阶除了卡片之外，还有一份放在 peldanos/ 里独立文件中的契约，始终是同样的五节：

1. 所需上下文，以通用方式命名（"容量数据调研"、"旧系统的读访问权"、"有真实后果的动作清单"），不深入系统工程的细节。调研天然是不完整的；我不试图用一张表单把它们做完整。
2. 提示词，给模型的，原文。初始的，以及当台阶是一次对话时，收尾的。所有提示词都带同一个条款，那是事情的核心：*模型评估上下文是否足够；不够，就在继续之前索要所有缺的；而且不估计、不发明只有业务才有的数据*。知道自己缺什么才能计算的是模型，不是一张表单。而且每条提示词前面都有一个写着"发送提示词之前"的方框：在你粘贴它之前，你（或业务方和你一起）必须已经构建好的文件和输入，连同它们的名字、内容和最低可接受状态。提示词点名它们，方框告诉你它们该做成什么样；没有那个方框，提示词提到的就是一些没人告诉你怎么写的文件。
3. 预期结果：产出物的详细特征。
4. 完整性检验：所有者对产出物做的检查清单，不读代码。有一项是"否"，台阶就没登上。
5. 警报信号：台阶看似登上、其实登错了的两三个症状。

每份契约的标题栏里：阶段、时机、形式和规模（在所有项目必需还是按比例）。

提示词是英文的，每条附翻译。 这是我出于三个原因做的决定：同样的内容用西班牙语要多占 30% 到 50% 的 token；模型遵循指令的能力在英文上校准得更好，所以英文提示词更能承受简短而不变得含糊；而且这行的词汇（test、commit、rollback、mock）是英文。但我不希望英文成为读方法的障碍：每条提示词下面有我在要求什么、为什么每个条款都在那里的解释，HTML 版里有一个按钮显示翻译成文档语言的提示词。贴给模型的提示词是英文；翻译是为了让你理解。而且所有提示词都以"Reply in my language"结尾，因为提示词是英文的，但对话不必是。

根据项目规模，什么是必需的、什么是按比例的

一个马上会出现的问题："一个小系统也要这一整套？"回答是，二十四级台阶不是二十四个漫长的阶段；有几级一次会话就登上，按比例的那些随项目缩小。不缩小的是不可协商的那些的清单。这张表是一个 假设 提案，待第一个端到端使用方法的项目确认：

概括：有十三级台阶在任何项目里都不可协商（0、1、2、3、5、6、8、最低限度的 9、10、12、第 18 级的依赖扫描、第 22 级的错误捕获和第 23 级的复盘），十一级随项目调整规模。

如何与任何工具一起使用

方法对工具是中立的；工具之间变化的是每个产出物放在哪里让模型读到。对 2026 年底最常用的工具，对应关系如下：

Forge 那一列自动化得最多；另外三列只要所有者手工做 Forge 自动做的事，就同样好用：在正确的时刻贴上台阶的提示词，并在进入下一级之前要求完整性检验。事实上，那就是课程的实践。

E 部分 — 尚待展开的

1. 完整的第 0 级台阶：加权准则的权重、阈值，以及更多作为反例的被拒绝项目。我有 X1 和 X2；其余还缺。
2. 每级台阶一个好记的名字，一句话，用于手册和出版物。
3. 导出到 Forge，已大体解决。 这个方法已经作为项目流程完整地在 Forge 里运行，有机械闸门，当前台阶的提示词会注入到聊天里（D-035、D-036）。还缺的是逐条契约对照 Forge 今天实际执行的内容做出的明确对应表，好让这份文档所说的和工具实际做的之间一出现偏差就被发现，而不是积累下去。
4. 端到端测试契约，已经在进行中。 课程的指导项目（Turnera）已经按原样跑完二十四份契约， 24 条里关了 24 条；这一路上发现的问题已经修正了方法本身（D-037 到 D-040）。缺的不是第一次完整通跑——那已经发生了——缺的是让别人的项目去跑它，而不是我在旁边解决契约没预见到的事。
5. 课程的第一期学员，他们会在需要的地方修正时间线的顺序和常见错误，这些今天是从我的项目而不是从学员写出来的。
6. 演进-纠正之路，验证于自己的遗留系统，而不是别人的。 课程的指导性遗留项目（遗留版 Turnera）已经按原样跑完八个站点和梯子的其余部分，27 条里关了 27 条，并促成了方法的三项决定（D-038、D-039、D-040）。缺的是在一个第三方的真实遗留系统上走同样的路，带着它自己的历史和自己的捷径，而不是我为课程搭建的那个系统。
7. 不在梯子里而应该在的 假设：把 token 成本和配额作为显式预算来管理（今天是被动的）；把密钥轮换作为例行而不是事故；以及一条人确实该看代码的时机准则，因为今天的答案是"从不"，而我怀疑有些特定时刻值得看。

F 部分 — 相关工作：世上已有什么相似的东西，以及本方法在哪里不同

写完这架梯子之后，我问了自己那个显而易见的问题：这东西是不是已经以别的名字存在了？我请人做了一次深入的调研，用英语、西班牙语和日语，对象是截至 2026 年 10 月发表的、用人工智能构建软件的方法论、随笔和学术工作。下面是结果，诚实地概括：别处已经有的，我引用而不是据为己有；我没找到的，我说"我没找到"，而不是"不存在"。这一部分会随着新东西的出现不断扩充，而新东西每周都在出现。

简短的回答：我没有找到任何一个已发表的方法把本方法所汇集的东西汇集在一起。我确实找到了一整个领域，从 2025 年中起，分别在它的若干组成部分上趋同；还有一位著名的实践者，在我发表这份文档之前三个月就到达了同一个激进的前提。

F.1 最近的亲戚

F.2 已经存在的东西，与其据为己有不如引用

强加给代理的"绿之前先红"，在 Beck 那里、在 Tsumiki 那里、在 Anthropic 的实践里、在 Simon Willison 2026 年的模式里都有。带文本提示词的有序步骤，在 Spec Kit、Tsumiki 和 Reed 那里都有。表征作为处理遗留系统之前的一步，在 Osmani 那里有，比本文档早一个月发表。从界面出发、由一个不同于生成者的评估者做的端到端测试，在 Anthropic 那里有。需求工程作为前提，在整个规格驱动开发运动里都有。而不读代码的人，在 Uncle Bob 那里有，在 Karpathy 那里（对于可抛弃的东西）有，在 Yegge 和 Kim 的书里也有。

F.3 我在任何地方都没找到的东西

• 对象是谁。 所有文献都假设有一位做评审的工程师。Uncle Bob 不读代码，是因为他有四十年的判断力来建那道栅栏。本方法从一个从不读代码的所有者出发，把其余一切从这条约束推导出来。这种倒转没有在任何工作里被提出。为不编程的人准备的，只有对损害的记录：2026 年 6 月的一项研究，检查了 9,041 个用"vibe coding"工具做出来的应用，在被审计的应用中有 91% 发现了漏洞（arXiv 2606.23130）。
• 作为必交产出物的已验证、相信、盲点报告（第 12 级台阶）。问题已经用数字诊断出来了：代理的完成声明比真实的批准率高出 28 到 38 个点（SpecHarness, arXiv 2609.29921），而在代理之间交接时丢掉"未验证"标签，会让危险动作的批准率从 5% 跳到 60% （arXiv 2609.20211）。没有人把它变成一种面向一个人的问责格式。
• 自己带测试的量具（第 7 级台阶）。"一个喂给决策的数字，要用一个自己有测试的程序来测量"这条规则，在我找到的任何来源里都没有写下来。
• 完整的梯子，从适格性到监控和复盘。我找到的最长的有十步；几乎全部止于合并；只有 AI-DLC 和 Osmani 触及了运维。
• 不设期限作为规则（D-030）。它没有被反驳；它是缺席的。
• 这个组合。 不读代码的人不严格地测试（Ronacher、Yegge）。严格测试的人读代码（Beck、 Osmani、Hashimoto、GitHub）。Uncle Bob 和 old-coder 打破了这个交叉，而且是按任务做的，不是按项目。

F.4 必须回答的反对意见，以及我如何回答

Birgitta Böckeler 在 2026 年 8 月测得，要求代理走先测试的循环并不能可靠地改善质量，因为代理有时会伪造红色，或者在测试之前先实现，好让测试一上来就通过（martinfowler.com）。在她的研究里，唯一能把看守的测试和装饰的测试区分开的，是变异测试。同年的另一项研究表明，一个模型会给自己三分之一的错误背书（arXiv 2605.21537）；还有一项表明，一个干净的会话加一个不同的模型，比同一模型的两个会话找到更多错误（arXiv 2610.01471）。

这是一个严肃的反对意见，我接受它。方法的回答有三块（D-033）。在第 8 级台阶，红色是一张凭据，不是一段叙述：确切的命令、它所针对的版本、失败的数量和退出码，按原样粘贴，好让所有者能用一条命令重新跑一遍，而且每个功能块做一次，用一个随机挑出的待办项。在第 13 级台阶，由另一个会话做的审计重新跑这些凭据中的一个样本。在第 9 级台阶，变异测试在任何有用户的项目里都是必需的（只在没有真实用户时保持可选），其分数在每个功能块收尾时放在覆盖率旁边。这三块没有一块要求所有者读代码。三块都让伪造红色比真的跑一遍更费劲。

要把本方法放到地图上，一个有用的框架是 Macedo 2026 年 6 月的分类法（arXiv 2606.04967）：六个维度（规格、上下文、角色、执行、验证、可移植性），以及一个发现：它比较过的框架没有一个同时覆盖六个维度，在流程深度和可移植性之间存在一种结构性的取舍。Urazuke 瞄准全部六个，而它押注于精确的英文提示词加上工具中立，正是打破这种取舍的尝试。