方法 · AI 软件 · 开源
Urazuke，验证方法。
Urazuke（裏付け）是日语中一个断言所拥有的依据：从背后支撑它的东西。这是我用人工智能构建软件的方法，产出的软件稳健、可投入生产，而项目所有者不必读一行代码。我从如今正在生产中的三个真实系统提炼了它，依托的是一直以来的系统工程，以及这些系统教给我的、模型在哪些地方脆弱地应用它。
作者：Pablo Kuschniroff，由 Claude Code 辅助。
Creative Commons BY-SA 4.0 · 八种语言 · 工具中立 · 以三个生产系统为来源 · 开源且协作
论点
AI 没有中断方法：它延续了方法。
在论点之前，一个我在意的澄清：这个方法不是我在每次教训之后打上的一堆补丁。它来自两个因素的结合。第一个是我自己的系统工程知识：调研、需求、容量估算、作为证据的测试、可复现的部署、审计；早在这些模型出现之前我就带着它。第二个是三个生产系统一次又一次事故向我展示的：模型在哪些地方脆弱地应用这些原则，因而哪些地方必须以书面形式收紧。伤疤证明的是哪里需要严格，而不是原则的起源。
业界在二十年前就不再信任代码的作者。当编写工作转到初级、外包或轮换的团队，逐行审查变得无法维持，取而代之生长起来的是今天我们视为理所当然的一切：自动化测试、持续集成、验收标准、不绿就不放行的流水线。那是系统工程对"写的人不可信"的回答：不读他的代码，向他索要证据。模型是下一位作者，而不是第一位需要被怀疑的作者。
人的努力去哪里
人只做两件事：决定，以及验证产出物。起草、构建、测试、测量和记录由模型完成。每级台阶都以不读代码的完整性检验结束。
证据证明它自己
一个你从没见它失败过的测试，你不知道它是否证明了什么。没有测试的量具会撒谎。没有盲点的报告在隐藏。质量控制的独立性纪律，再往里走一步。
产出物的成本
过去文档昂贵且会过时。现在重新生成是免费的，所以规则变成"在同一次提交中"和"可手工复现，无需 AI"。曾经无法达到的理想变成了闸门。
是什么，不是什么
应用于一个不知疲倦、却不能轻信的构建者的系统工程。
对来自系统工程的人，它听起来熟悉：调研、需求、容量估算、设计、构建、测试、部署、运维、审计。对来自 vibecoding 的人，它给了他们缺的东西，恰恰是骨架。
是什么
- 一种方法：按什么顺序做什么，向模型要什么，它必须交付什么，以及如何知道它是完整的。
- 四个阶段里的二十四级台阶，每级都有契约：上下文、提示词、预期结果、检验、警报信号。
- 工具中立：Claude Code、Cursor、Codex CLI、Gemini CLI 或 Forge。每个产出物都是一个文件、一个测试或一个脚本。
- 从三个真实的生产系统提炼，每条规则都绑定到引发它的提交和教训。
不是什么
- 不是编程课，也不是框架课。
- 不是让模型写得更好的提示词技巧合集。
- 不是周五演示原型的方法：它是给之后必须继续运转的东西用的。
- 不是适用于所有项目的方法。第 0 级台阶把边界写下来。
梯子
二十四级台阶，四个阶段，按登梯的顺序。
台阶按登梯的时间顺序编号。启动的每个项目登一次；循环的每次变更重复；上线的在首次部署前登一次；运维的在系统上线之后。第 23 级闭合循环，回到第 0 级。每级台阶都有一张八部分的卡片和一份带提示词的契约。没有期限：方法是过程，不是速度的承诺。
每个项目一次，在写功能之前
最让人想跳过、跳过代价最高的五级。
每次变更，贯穿整个项目
按每个待办项的执行顺序排列。在头两个功能块上学会，在整个项目里练习。
首次部署前，只做一次
把"能用"变成"能维持"：审计、锁、通往生产的流水线、可观测性、持久层、漏洞、性能和手册。
系统已经上线之后
两项带周期报告的监控、常驻代理，以及闭合循环并回到第 0 级的回顾。
任何项目都不可商量的十三级台阶
- 适格性（一小时；省几个月）
- 协作契约
- 简短的定义，带"不是什么"
- 用业务的数字做容量估算
- 待办项作为计划
- 带所有者和日期的决定
- 被看到变红的测试
- 已验证 / 相信 / 盲点的报告
- 带数字的回顾
- 流水线中的依赖与密钥扫描
- 集中式错误捕获与报告
- 流水线中的代码质量，最低限度
- 由人执行的手工测试用例
时间线
每级台阶何时登，台阶之间发生什么。
没有时间线的方法只是一份善意清单。这是任何项目的时间线：五个阶段按顺序，每个阶段里除台阶之外要做的事：需求摄入、基础设施、集成与部署流水线、开发、端到端测试、人眼检视、人工测试。没有期限：每个阶段持续多久由系统决定。
采集
用经典的需求工程方法与所有者一起调研：访谈、用例、带状态的领域模型、界面原型。用散文写，故意不完整：代理通过提问来补全。
启动（第 0 到 4 级）
适格性、契约、带语义树的定义、容量估算。以及全部初始基础设施和 CI/CD 链：仓库、测试环境、持续集成、空系统的首次部署。所有者打开 URL，看到空界面。
循环（第 5 到 12 级）
一个功能块接一个功能块。每个待办项：规格、决定、先证红的测试、流程的端到端测试、所有者查看的界面截图。每个块结束时：完整的端到端套件和测试环境中的人工测试。
上线（13 到 20）
由另一个会话审计。在构建收款或发送功能之前加锁。闭合到生产的链路，回滚已测试。三本手册。所有者对全部流程的验收测试。 加上部署前的四级运维质量台阶：可观测性、持久层、漏洞、性能。
运维（21 到 23 和循环）
以某人名义行动的驻留代理。定期审计。每次演进都经过完整循环进入，经部署链路发布。每个阶段结束时带数字的复盘。 两项监控（资源与错误）在首次部署的那一周搭好，并产出所有者阅读的周期报告。
端到端测试不是最后做一次
每个待办项，测它触及的流程。每个块结束，测所有已有流程。上线前，用将要提升的确切版本测所有流程。只做第三种，到最后就有好几周没测过。
三种使用场景
空文件夹、用方法建的系统、还是继承来的系统：从哪里进入。
这把梯子是对着一个空文件夹写的，那是最便于学习的情形，却不是最常见的。打开代理之前，最好先弄清你处于三种情形中的哪一种，因为入口不同。而第三种，已经存在、并非用这个方法诞生的系统，有自己的路：不重写地把它规范化，然后才登梯。
新项目
一个空文件夹和一位有需求的所有者。从第 0 级进入，按顺序登完二十四级：第一个功能之前先有一周的启动。主文档、契约和课程描述的就是这个。
用方法建的系统的演进修正
系统已经登过梯子：有契约、地图、带证据关闭的待办项、测试套件、部署和手册。从第 5 级进入，开一个功能块，然后走循环。这就是第 15 级回到第 0 级。
未用方法建的系统的演进修正
一个在运行、有用户的系统，由别人或你自己在没有证据的情况下建成。八个规范化站点（N0 到 N7）：用自动发现把没人写过的输入找回来，并标注来源；把安全带作为硬闸门；债务在触碰到模块时偿还。之后，以修正或演进模式走循环。
每级台阶的契约
如何提出要求，应该返回什么，以及如何知道返回的是完整的。
每级台阶用一份五节契约执行。给模型的提示词是英文的，在文档的八个版本中完全相同的单一原件，每条之下用读者的语言解释我们在要求什么、为什么每个条款都在那里。
所需上下文
以通用方式命名。调研天然不完整；不靠表单补全，由模型通过提问补全。
提示词
原文。都带同一条款：模型评估上下文是否足够，在继续之前索要缺的东西，并且不估算、不编造只有业务方才有的数据。
预期结果
产出物的详细特征：哪个文件、哪些节、什么不能缺。
完整性检验
所有者不读代码就对产出物做的检查。有一项是"否"，台阶就没登上。
警报信号
即使看起来登上了、其实登得不好的症状。几周后、已经疼了的时候才看到的那些。
一条示例提示词 · 第 7 级台阶
docs/PENDING.md 中带有“给定、当、那么”的验收标准和“如何验证”）、已经实现的变更、docs/STATUS.md 中的测试套件命令，以及正在运行、带有所涉流程数据的测试环境。在文档里，每个提示词前面都有这样一个块：你要构建哪些文件、内容是什么、最低可接受状态是什么。为什么用英文：同样的内容用其他语言要多占 30% 到 50% 的 token，模型用英文遵循指令更精确，而且行业词汇是英文的。但我不想让英文成为障碍：在文档中，每条提示词都附有译成文档语言的翻译和一个像这样的按钮。粘给模型的是英文；翻译是给你理解用的。所有提示词都以“Reply in my language”结尾。
从需求到待办项
一直以来的需求工程，分解为模型能构建、你能验证的单元。
需求不是聊天里客户的一句话。它是那句话经过几十年来就存在的方法处理后的结果，这些方法你要求模型就应用得很好，不要求就应用得很差：访谈、用例、领域模型、验收标准、界面原型、可追溯性。在这个方法里，三个产出物支撑着它们。
语义树
把系统画成一棵树：领域；其下是参与者、过程（用例）、带状态的实体、界面和集成；每个节点上挂着待办项和决定。代理构建它，你修正它，它是代理在动代码之前要读的东西。不挂在任何节点上的待办项就是超出范围，十秒钟就能看出来。
详细规格住在每个待办项里
那份会过时的冗长规格文档被分解了：每个待办项带着它在树上的节点、用客户原话写的来源故事、描述、带决定和日期的业务规则、数据、界面、边界情况、验收标准和验证方式。读这份规格是你最接近读代码的时刻，而这正是合适的距离。
已关闭的待办项就是文档
关闭的待办项不会被删除：它保留着规格、引发它的决定、关闭时的证据、提交和日期。已关闭待办项的队列就是系统的功能历史；变更日志、用户手册，以及六个月后“系统为什么这么做”的答案，都从那里来。
用任何工具
产出物是文件、测试和脚本。变的只是它们放在哪。
Claude Code
契约和例行放进项目的 CLAUDE.md；台阶提示词在登每级台阶时粘到聊天里。
Cursor
例行放进 .cursor/rules/ 作为始终生效的规则；其余相同。
Codex CLI / Gemini CLI
放在仓库根目录的 AGENTS.md 或 GEMINI.md。
Yujin Forge
契约和例行是教义，提示词在跨过每道闸门时自动注入，待办项记录是原生的。同一个方法，更少的复制粘贴。了解 Forge →
课程
二十四节带实践任务的课，直到应用上线生产。
一本课程式手册，每级台阶一节课，把方法应用到自己的项目或引导项目（"Turnera"，一个带提醒、定金和个人数据的预约表：让每级台阶都不是假的所需的一切）。以上线生产清单结束：所有者不打开代码就能验证的二十四个条件。 课程第二部分用同一家诊所的继承系统（“继承来的 Turnera”）教你在修正和演进之前先把它规范化。
你得理解什么
每级台阶的概念，像对一个人解释那样解释，附引发它的真实故障。
任务，一步一步
附给代理的确切提示词以及拿到返回后怎么做。包括故意的测试：留一个问题不回答，看它怎么做。
检验与交付物
你对交付内容自问的问题，不打开代码，以及最后必须存在的文件或证据。
常见错误与引导项目
几乎每个人第一次都会碰到的，以及每节课应用到 Turnera 上是什么样子。
写给新人
手写编程时代之后的初级开发者。
如果代码由模型来写，初级开发者如何成长、学什么、成为什么？一份单独的文档，讲哪些培养重点失去分量、哪些增加、仍然必需的基本素养、目标，以及一个带导师的十二周计划。和整个方法一样，为初学者而写。
团队协作
多名开发者，各带自己的代理，在同一个分支上。
方法是用单数写的。这份文档说明多人时如何应用：共享分支的七条规则（待办项作为所有权单位、小步频繁集成、持续集成作裁判、未完成的放在开关后面、地图作冲突探测器、决策署名、审查证据而非代码）、台阶如何分工，以及提示词。
全部资料，八种语言
用你的语言阅读。
西班牙语是事实来源；其他七个版本是翻译，若有出入，以西班牙语为准。提示词在所有版本中完全相同。每种语言三份文档：主文档（论点、三个系统的调研、二十四级台阶、真实故障和术语表）、二十四份契约，以及课程手册。 从第 5 版起，每种语言再增两份文档：面向已有系统的演进修正之路，以及带继承指导项目的课程第二部分。
本方法以 知识共享 署名-相同方式共享 4.0 发布：可以使用、翻译和改编，只要署名并采用相同许可。仓库是公开且协作的：github.com/pkuschnirof/urazuke。改进通过从 fork 发起的 pull request 提交，附带证据，我审查后合并。
这是否已经以别的名字存在？我深入调查了截至 2026 年 10 月有哪些相似的东西（Uncle Bob 和他的"gauntlet"、Tsumiki、Spec Kit、Consort、IACDM、Osmani 等），哪些宜引用而非自居，哪些在任何地方都没找到，以及最严肃的反对意见及其回答。见主文档的 F 部分"相关工作"。
两本 Forge 执行手册，分步并带截图，基于真实的练习项目：新项目（Turnera）与现有项目（继承的 Turnera）。附每级台阶收集的证据（西班牙语）。
另有两份文档，不在翻译语料之内：闸门的说明（英文，因为它是工具文档，且由数据生成）；以及关于本方法的AI 模型评估（西班牙文）。
如果你要用工具来消费本方法，不必阅读代码仓库：数据接口在 yujin.app/urazuke/api/。它的索引列出每个资源的规范地址、版本与哈希：gates.json（闸门的机械定义）和 prompts.json（提示词）。哈希可按内容重新计算，所以过期的副本会自己暴露出来。
从哪来
三个生产系统，以及四二十四个带日期和证据的记录在案的案例。
我以只读方式调研了三个如今有真实用户在生产中使用的仓库：方法成形的工具（五个月 1,090 次提交），一个有金钱和敏感数据在内的医疗机构自动化系统（641 个待办项，全部关闭），以及一个民间组织的全渠道服务台（第一个测量系统性地先于构建的系统）。方法中引用的每个案例都在参考文献文档中编了号，让流程保持干净，细节一键可达。客户已匿名化；数字、日期和提交是真实的。
模型在哪里连显而易见的都做不到
撒了两次谎的量具。被报告为成功的认证错误。四条断言错了三条。每一个都告诉我，一条对我来说显而易见的原则，在哪里必须变成提示词里的明确条款。
带数字的复盘
我用 60 美元加 73 分钟对 90 分钟砍掉了一整个代理团队。我用 16 到 27 分钟对 11 分钟拆开了部署。梯子本身就是这样来的。
Pablo Kuschniroff，由 Claude Code 辅助
RPAForce / Yujin。方法应用于它自身：它的决定带日期和原话记录在案，仓库自 2026 年 10 月 18 日起在 github.com/pkuschnirof/urazuke 公开。
常见问题
常见问题。
- 我需要会编程吗？
- 不需要。你需要一个有判断力、有时间做决定的领域所有者，以及关于仓库、提交和推送是什么的最基本概念。方法存在的目的正是让所有者验证证据而不是读代码。
- 它适用于任何项目吗？
- 不，而这不是缺陷。有两个排除性条件：一个留证据的标准仓库，以及能程序化操作、可端到端测试的界面。第 0 级台阶把边界写下来。
- 我需要 Forge 或 NAC3 吗？
- 不需要。方法是工具中立的；每个产出物都是一个文件、一个测试或一个脚本。Forge 自动化闸门和提示词注入，但台阶在没有 Forge 时也存在。NAC3 是我们今天实现界面可测试性的手段，不是条件。
- 文档是我的语言，为什么提示词是英文的？
- 因为模型用英文遵循指令更精确、消耗的 token 更少。每条提示词是八个版本中完全相同的单一原件，下面用你的语言解释，并以"Reply in my language"结尾。
- 一个小项目从头到尾要多久？
- 我故意不给期限。这个方法是一个让系统可运维、可维护而无需理解任何一比特代码的过程；不是一个让系统做得更快的过程，哪怕速度会作为结果出现。方法固定的是顺序和闸门；每个阶段花多久，由你系统的规模和复杂度决定。
- 如何提出改进？
- 带着证据：第 15 级台阶要求每次复盘以一条对梯子的具体修改提议结束，附证明它合理的事故。提议通过从 fork 发起的 pull request 提交到 github.com/pkuschnirof/urazuke，由我在合并前审查。