decision-free-specs

无需决策的重构规范

生成 specs/<target>/spec.md + plan.md 文件对，让约 27B 的本地模型能够在无需做出任何架构决策的情况下执行。规划中成本最高的部分——准确了解每个文件中有什么——应由脚本完成，而不是靠阅读。规划模型（你）只需把 Token 花在判断上：模式选择、接口表和陷阱识别。

以下工作流与语言无关。所有与语言相关的内容（清单工具、提取流程、恢复规则、陷阱）都是插件：

语言	状态	工具
TypeScript / TSX	可用	languages/typescript/
Python	可用	languages/python/
Rust	可用	languages/rust/
Flutter / Dart	可用	languages/dart/

规划前，请先阅读目标语言的 languages/<lang>/NOTES.md。Python/Rust/Dart 工具均已通过固定样例验证（Python 另有一个 CPython 标准库文件）；在新代码库中首次用于生产时，请手动核对一个真实文件与清单输出。对于没有插件的语言，先构建清单工具（契约和流程见 languages/README.md）——不要退回到手动阅读文件；那样会重现这项技能要消除的成本。

步骤 0 — 程序初始化（仅在某个仓库中首次使用时）

如果仓库中没有 specs/README.md + specs/conventions.md，请根据 templates/program-readme-example.md 和 templates/conventions-example.md 创建这两个文件，并调整：适用于此仓库的验证命令、适用于此语言的导入/模块路径表（来自语言 NOTES），以及执行器提示词模板中的仓库根目录。程序 README 负责定义执行器契约（提示词模板、采样设置、每个会话仅执行一步的规则、失败处理协议）——每个规范文件夹都不得重复说明这些内容。

步骤 1 — 通过脚本生成清单（先不要读取文件）

从仓库根目录运行目标语言的清单工具；它会输出契约所需的各部分（见 languages/README.md）：导入项、穷尽的顶层声明表（类型/名称/行号/是否导出）、语言特定信号（例如钩子、API 调用位置、通过动态字符串构建的标识符），以及——至关重要的——有哪些其他文件导入该模块，以及它们导入了哪些名称（需要兼容性重新导出的关键导出项；正是通过这一点，在首次生产运行中发现了一个测试文件导入三个辅助函数的情况）。

只有当你要将特定代码块提取到新单元中时，才直接阅读源代码，以便编写准确的接口表——绝不要为了发现符号而阅读源代码。

步骤 2 — 决定架构（这是你的工作，请记录每项决策）

模式选项菜单，按优先顺序排列：

1. 模型提取（始终执行）：纯类型/常量/辅助函数 → 模型模块。
2. 叶单元迁移：嵌套函数/组件/小部件 → 独立文件。原样迁移。
3. 代码块提取（UI 面板、大型匹配分支）：仅当提供完整接口表（属性/参数）时才执行；该语言的编译器驱动恢复规则会以机械方式处理遗漏项。
4. 策略注册表：仅用于存在至少两种行为差异的情况（字段不同、验证方式不同、请求形态不同）。标签和样式变体不属于行为差异。
5. 共享提取：如果清单显示多个文件中有相同符号，则在最先运行的计划中对其去重，并在程序表中标记依赖关系。

请在 spec.md 中明确记录否定决策（例如：“不创建策略注册表——X 是唯一的变体；不要创建注册表”“抽屉应按决策保留在原处”）。未记录的未决事项，就是执行器会错误处理的决策。

步骤 3 — 编写文档

针对每个目标文件夹：

• spec.md：源文件 + 大小、模式 + 原因、目标文件树、完整的符号映射表（符号 → 目标位置 → 是否导出）、涉及代码块提取的接口表、依赖说明（使用对应语言 NOTES 中的精确导入/模块路径）、验收标准。如果清单的“Imported by”部分对已移动的导出项非空，则指定兼容性重新导出，并注明导入方。
• plan.md：前置条件（按名称 + 步骤列出跨计划依赖项）、编号步骤，每个步骤的工作量都应足以在一次全新上下文会话中完成。每个步骤都需注明精确的提交消息。步骤仅说明与仓库 specs/conventions.md 的不同之处。

生产中总结出的硬性规则：

• 步骤顺序：先纯移动，再移动单元，最后提取代码块——每个步骤都必须能够单独提交，并且每步完成后仓库都保持通过检查。
• 每个步骤的标题都必须写作 STEP k of N，并在计划前言中说明 N。在首次生产运行中，执行者在最难的目标上完成第 1 步（共 3 步）后便停止，却报告整个计划已完成；步骤标题能让执行者在全新上下文会话中明确看到后面还有步骤。
• 每个移动步骤都必须以剩余项检查结束：精确说明移动的符号数量，并通过机械断言确认源文件中不再有这些符号的声明（语言 NOTES 会给出 grep 格式）。生产中有一份 27 个符号的移动清单悄悄漏掉了一个；编译器无法发现某个类型仍留在原处却依然可以编译。
• 锚定在符号名称上，绝不使用行号（行号会变化）。
• 草案计划中每个“如果出现 X，就提问/选择”的内容都是错误。应改为现在直接做出决定，或改为机械规则（“复制版本 A 并报告差异——不要协调”）。
• 每步的验证门槛应遵循仓库规范（格式检查 → 类型检查/构建 → 同目录测试）。如果目标有同目录测试文件，必须在计划中注明——其中的导入项就是确切的兼容性范围。

步骤 4 — 更新项目并提交

1. 在项目 README 的表格中添加行（大小、难度、依赖项）。
2. 抽查规范所依赖的关键声明（重复符号、导入方列表）——脚本会报告这些内容，但必须确认计划正确性所依赖的所有内容。
3. 按照仓库规范提交。

步骤 5 — 审计执行者的输出（不要相信“全部完成”）

计划中的精确提交消息可作为完成清单。执行者（或其操作人员）报告项目完成时，应先将预期与实际差异进行核对，再决定是否相信：

grep -A2 "Commit message" specs/*/plan.md   # expected messages
git log --format=%s <baseline>..HEAD        # actual messages

每条预期消息都必须各自出现在一个提交中。此检查能发现生产中的失误：步骤被悄悄跳过（执行者在最难的目标上提前停止），以及两个步骤被压成一个提交（工作虽然存在，但压缩提交中步骤的验证门槛从未运行——应手动重新验证）。然后在项目级别运行一次完整验证套件，包括逐步验证门槛未注明的重构代码附近的测试文件。

Substrate 语义完成

当此技能作为 Substrate runner 或工作流作业运行时，任何技能或工作流专属状态块都应放在最前面。助手最后一条非空行必须严格为一个 SUBSTRATE_OUTCOME_V1= 声明。

仅当请求的规范/计划不需要决策、预期文件均已存在、所有必要编辑均已提交（或已证明当前工作树满足请求），且声明的验证已通过时，才使用 outcome: "succeeded"。对于失败、受阻或需要人工处理的工作，使用 outcome: "failed"。如实报告 Git 证据，使用 changes.status: "committed" 并附上提交 ID，或使用 "alreadySatisfied"；报告实际通过的命令。切勿根据进程正常退出推断语义上的成功。

SUBSTRATE_OUTCOME_V1={"version":1,"outcome":"succeeded","summary":"Authored and verified the decision-free spec program","evidence":{"changes":{"status":"committed","commitIds":["<commit>"]},"verification":{"status":"passed","commands":["<verification command>"]}}}

不要输出第二条声明，也不要在其后添加任何内容。在 Substrate 作业之外，不要添加此平台专属行。

执行器设置（默认值；每个仓库以程序 README 为准）

目标类别：本地约 27B 指令模型（优先选择 Qwen3.6-27B，以发挥其编码 Agent 能力）。温度 0.2，top_p 0.9——机械式编辑需要确定性。每个全新上下文会话执行一个步骤。某个步骤失败两次 → 重置工作树，报告 FAILED 并停止。绝不要对失败的步骤擅自变通。