architect

Architect

使用 not implemented 函数体和伪代码，勾勒类型、函数签名、表结构和模块边界。综合多个模型视角，然后根据选定的草图补全代码。

加粗标注的原则位于 principles 技能中：调用一次 Skill 工具并传入 principles，然后阅读每条已命名原则对应的文件。

开始

开始前，创建任务列表（使用你所用工具框架的任务工具；若没有该工具，则在 ~/.local/state/ox/checklists/<repo>-<branch>.md 创建清单文件），每个阶段对应一项。

1. 充分了解
2. 勾勒
3. 确认
4. 实现
5. 搁置

阶段 A：充分了解问题

建立对新代码涉及的每个系统的准确理解。针对相关子系统，调用 Skill 工具并传入 how。仅仅提及文件名并不算充分了解。按照 how 的要求，给出架构说明。如果设计重新定义了所有权或分层，还要针对现有结构调用 Skill 工具并传入 why，让其设计依据成为约束，而非猜测。

只有在工作确实是全新开发、无需与现有系统集成时，才跳过阶段 A。

阶段 B：勾勒

调用 Skill 工具并传入 arena，提供设计草图任务和阶段 A 的了解材料。将 RUNNER-PROMPT.md 的内容，以及此文件、RATIONALE-TEMPLATE.md 和提示词中提及的 principles 文件的绝对路径，一并放入每个 runner 的任务说明中。runner 即 arena 的 panel 席位。

进行两轮设计。在综合之前，至少要求两个结构迥异的候选方案，即使第一个看起来已经足够。这是将 Exhaust the Design Space 落到实处：比较的是整体结构不同的方案，而非同一结构中的局部修补。

在综合之前，使用 DESIGN-RED-FLAGS.md 审查每个候选方案。假设下一位贡献者是一个 Agent：它只能看到自己打开的文件，会照搬最近的示例，并选择能通过编译的最短路径。优先选择这样的设计：从单个文件看来正确的改动，在整个资源中也正确。

根据接口深度比较可行方案。优先选择能通过更小、更简单的公共接口隐藏更多复杂性的设计：导出项和事件更少，但各自功能更强。丰富的接口可以集中能力，而非将能力分散到多层，从而缩短调用链。

Arena 会返回一个综合设计包。综合结论将填入理由说明中的“Synthesis decision”部分。

阶段 C：确认（可选）

默认情况下，直接根据综合设计进入实现阶段，无需人工确认。

仅当调用者明确提出“architect with checkpoint”“停下来给我看看，再开始实现”或类似要求时，才选择设置确认点。此时展示综合设计并暂停，等待批准。

无论采用哪种方式，都可以将综合结果作为独立提交交付，这是 Foundational Thinking 的“scaffold first”模式。根据 Outcome-Oriented Execution，填充实现时可以进行计划内、有范围的破坏性改动。若要在实现前通过对抗性审查施压设计，请针对综合草图调用 Skill 工具并传入 interrogate。

如果人在确认阶段或事后对设计结构提出异议，应将其视为阶段 A 的证据。重新充分了解问题并重跑阶段 B，然后再继续编写代码。

阶段 D：按草图实现

将 not implemented 函数体替换为代码，将伪代码替换为逻辑。综合草图就是契约。偏离草图是需要明确提出的信号，而不是可以默默消化的摩擦。如果某个函数需要草图未预料到的参数，请判断是草图有误、遗漏了需求，还是实现超出了范围。

阶段 E：架构有误时，推倒重来

如果实现过程中不断产生草图无法消化的阻力，就把草图推倒重来。不要在错误的设计上叠加修补方案，参见 从第一性原理重新设计 和 修复根本原因。

判断信号看的是模式，而非个别情况。迹象包括：

• 相同形式的变通方案在彼此无关的代码中反复出现。
• 多个彼此无关的边界情况都需要特殊分支。
• 为了编译或通过类型检查，类型需要逃生通道（any、类型断言、--[[@as T]]，或实际上总会设置的可选字段）。
• 草图明明说状态不共享，却本能地觉得“我们需要一把锁”。
• 调用方必须了解抽象的内部规则才能使用它。
• 实现中出现了两个或更多彼此独立、形式相同的阶段 D 偏离。

请自行判断。少数边界情况不足以否定一种架构。有些问题确实很复杂。数据复杂，不代表设计复杂。

推倒重来时：

1. 针对已构建的内容，调用 Skill 工具，并使用 how。
2. 根据 从第一性原理重新设计，把新约束视为从第一天起就存在的假设，重新设计。
3. 根据 先删减，再添加，先做减法，再做加法。新草图在扩展之前应比旧草图更小。
4. 回到阶段 B，重新运行 arena。

产出

先写出调用方的用法，再据此推导类型草图。小型改动只需一个包含新类型和签名的文件。较大的工作则需要模块映射和类型定义。随附说明理由，并按照 RATIONALE-TEMPLATE.md 的格式编写，其中包括用法草图和综合决策。