architect

架构设计

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

开始

开始前，为每个阶段在工作清单中添加一项。

1. 调研
2. 勾勒
3. 达成一致
4. 实现
5. 搁置

阶段 A：调研问题

对新代码涉及的每个系统建立真实的心智模型。针对相关子系统使用 how 技能。

只给文件命名不算调研。请按照 how 的要求产出架构说明。如果设计重新定义了所有权或分层，还要对现有形态使用 why 技能，让其设计依据成为约束，而非猜测。

只有在工作确实是没有周边系统需要集成的全新开发时，才跳过阶段 A。

阶段 B：勾勒

使用 arena 技能，执行设计草图任务，并提供阶段 A 的调研材料。将 references/runner-prompt.md 作为每个运行器的提示词。

使用 architect runners 角色中的运行器，替代 arena runners。其默认值为 fable、opus、sonnet。别名和被拒绝的条目遵循 arena 技能阶段 A 的运行器规则。使用 pstack-harness 技能来启动。其 Spawn a role 部分会解析角色，并构建此 CLI 的启动调用。

设计两次。综合之前至少要求两个结构不同的候选方案，即使第一个看起来已经足够。这是将 exhaust-the-design-space 原则技能落到实处。候选方案应是整体形态各异的方案，而不是同一形态中的局部修补。

综合之前，使用 references/design-red-flags.md 检查每个候选方案。假设下一位贡献者是一个只能看到自己打开的文件、照搬最接近的示例，并选择能编译的最短路径的 Agent。优先选择这样的设计：从单个文件看起来正确的改动，在整个代码库中也正确。

根据接口深度比较可行方案。优先选择能通过更小、更简单的公共接口隐藏更多复杂性的设计。丰富的接口可以集中能力，而不是将其分散到各层，从而缩短调用链。

Arena 会返回一个综合设计方案包。其综合决策会填写理由中的“Synthesis decision”部分。

阶段 C：达成一致（可选）

默认情况下：使用综合后的设计直接进入实现，不设置人工检查点。

当调用者明确要求时，才选择设置检查点，例如“/architect with checkpoint”、“实现前停下来给我看看”或类似说法。然后展示综合后的设计并暂停，等待批准。

如果没有设置检查点，或调用者已批准，综合设计就可以作为单独的提交交付，这符合 foundational-thinking 原则技能中的“先搭脚手架”模式。根据 outcome-oriented-execution 原则技能，补全过程中计划内、范围明确的破坏可以接受。若要在实现前对设计施加对抗性压力，请对综合后的草图使用 interrogate 技能。

如果人类对设计形态提出异议（无论是在检查点期间还是事后），都将其视为阶段 A 的证据。重新调研并重新运行阶段 B，然后再编写更多代码。

阶段 D：根据草图实现

用代码替换 not implemented 函数体，用逻辑替换伪代码。综合后的草图就是契约。与之不符的地方是需要提出的问题，而不是可以默默忽略的摩擦。如果某个函数需要草图未预料到的参数，请判断是草图有误、遗漏了需求，还是实现超出了范围。

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

如果实现持续遇到草图无法化解的阻力，就推倒草图重来。不要在错误的设计上打补丁，应遵循从第一性原理重新设计和修复根因原则技能。

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

• 同一种变通方案反复出现在不相关的代码中。
• 多个不相关的边缘情况都需要特殊分支处理。
• 类型必须借助逃生通道（any、类型转换、实际上总会设置的可选字段）才能通过编译。
• 草图明明说状态并未共享，却本能地觉得“我们需要加锁”。
• 调用方必须了解抽象的内部规则才能使用它。
• 实现中出现两个或更多同类的独立阶段 D 偏离。

请自行判断。少数边缘情况不足以否定一种架构。有些问题确实很复杂。数据本身的复杂性不等于设计的复杂性。

推倒重来时：

1. 再次运用如何技能来审视已构建的内容。
2. 按照从第一性原理重新设计的原则，假设新约束从第一天起就已存在，并据此重新设计。
3. 遵循先删减，再添加原则技能，先做减法，再做加法。新草图在扩展之前应比旧草图更精简。
4. 返回阶段 B，重新运行 arena。

产出

先写出调用方的用法，再据此推导类型草图。小型变更只需一个包含新类型和签名的文件。较大的工作则需提供模块图和类型定义。按照 references/rationale-template.md 的格式随附设计依据，其中包括用法草图和综合决策。