用途
将只读源代码转化为两层职责不重叠的产物:一份忠实的复现规格(足以重建可观察行为),以及一份抽象设计文档(表达意图与体验,刻意剥离复现细节)。
适用场景
- 从既有程序恢复意图与可复现行为。
- 产出文档,使其既能让人重建行为(规格),又能单独理解设计意图(设计文档),且两者互不污染。
不适用场景
- 纯摘要或 README 工作,不要求复现保真度。
- 已存在维护中的规格,只需编辑。
所需输入
- 只读源代码(仅作为输入,绝不编辑)。
- 任何引擎/运行时约定文档,使共享辅助行为只被引用一次,而不在每个产物中重复规定。
流程
规格层
只保留会改变可观察游玩/行为的内容:目标、核心循环、必需状态与资源、输入行为、计分/失败、平衡关键常量与公式。丢弃外观性内容。详细的保留与丢弃规则——同刻顺序、碰撞/判定框/阈值语义、生成/目标/随机/输入边沿行为、可复用的计分/安全脉冲——是一份检查清单;撰写规格时加载 references/spec-preservation-checklist.md。
设计层
仅依据规格撰写抽象文档:体验核心、向用户提出的决策、风险/回报、张力如何建立、学习曲线、可重新诠释的空间,以及不变结构。将数值平衡转化为定性意图。绝不泄漏精确常量、公式、随机范围、刻数或源名称。加入明确的恢复指引:哪些视为未指定、哪些可安全假设,以及恢复优先级顺序。
不可抽象的下限
以下内容属于意图而非复现细节,必须以定性方式出现在设计层。丢弃它们是本阶梯的典型错误抽象,因为它们读起来像机械细节,会随常量一起被过滤掉:
- 效果与各类实体接触时做什么——武装它、摧毁它、穿过它、被它吸收。“爆炸会武装其邻居”与“爆炸会引爆其邻居”描述的是两种不同的游戏,且都不需要数字。
- 边界处的行为——移动中或已提交的对象在墙或屏幕边缘做什么。
- 什么计入目标与失败条件——尤其是玩家未引发的事件是否被计入。
以上每项都可以不写任何常量,而缺失它们的设计文档无法传达核心循环——而文档自身的恢复优先级恰恰称核心循环为最重要的东西。观察到的案例:三项都被当作“实现细节”丢弃,门禁捕获了这一点,所有修复都落在设计层而规格层没有,因为规格层一直都有它们。
记录被抽象、保留、省略以及作为恢复指引新增的内容,使抽象可审计。将其作为设计文档内的简短小节,或者——如果日志需要引用具体被抽象的常量或源名称——放在同级日志文件中,因为把这些具体内容放进设计文档会违反其不泄漏规则。
验证
交接前运行一次零成本自检:如果一位盲读者必须用一句话陈述核心循环,他们会依据设计文档的哪一句来构建?如果没有单一段落能回答,抽象已经失败,门禁只会在付出全部代价后确认这一点。
验证本身不由你(提取者)运行——你已读过源代码,无法盲判产物。它由独立方运行(编排器生成一个只看到产物文本的全新智能体)。将产物交给在防火墙下运行的隔离盲恢复门禁:
- 仅规格 → 能否恢复出可实现的结构?(通过 / 弱通过 / 失败)
- 仅设计 → 能否恢复出复现规格假设?
任一层失败意味着该层丢失了必需结构(规格丢了影响行为的细节,或设计省略了不可恢复的内容)。修订并重新过门禁。设计层的弱通过是预期且可接受的——抽象文档有意丢弃复现细节。
如果无法生成隔离门禁,则显式降级:对每层运行检查清单的自检小节,并记录验证为自审而非盲门禁——不要将其呈现为已过门禁。
常见失败模式
- 复现细节泄漏进设计文档(常量、刻数、源名称)——两层不再有各自不同的职责。
- 丢弃顺序/边沿行为,悄然改变主导策略。
- 过度规定外观,规定不足的时序/碰撞。
- 从源代码而非从规格撰写设计文档,重新引入规格本应过滤掉的细节。
输出
两份产物——一份复现规格和一份抽象设计文档——外加一份提取日志,每份都由恢复门禁验证。