architect

架构设计

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

调度约定。 Architect 的 Arena 使用 provider-dispatch.md 中的集中式提供方路由。已配置的条目是描述符，而非原生模型标识。在 Codex 上，按 codex-tools.md 解析剩余的 Claude 工具名称。

开始

开始前，创建一份待办清单，每个阶段对应一项。

1. 调研
2. 勾勒
3. 确认
4. 实现
5. 清理

阶段 A：调研问题

为新代码涉及的每个系统建立真实的心智模型。对相关子系统运行 how 技能。仅仅指出某个文件不算完成调研。按照 how 的要求给出架构说明。如果设计重新定义了职责归属或分层，还要对现有结构运行 why 技能，让设计依据成为约束，而非猜测。

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

阶段 B：勾勒

使用设计草图任务和阶段 A 的调研产物运行 arena 技能。将 references/runner-prompt.md 作为每个 runner 的提示词。

在当前 harness 的 pstack 模型表中使用 architect runners 中的 runner，代替 Arena 的 arena runners。如果模型表或该行缺失，则使用其角色默认值。

设计两轮。综合之前，至少要求两个结构上不同的候选方案，即使第一个看起来已经足够。这是将 exhaust-the-design-space 原则技能落到实处。备选方案应针对整体结构，而非在同一结构内修补局部问题。

综合之前，使用 references/design-red-flags.md 检查每个候选方案。假设下一位贡献者是一个 Agent，它只会查看自己打开的文件、复制最近的示例，并选择能编译的最短路径。优先选择这样一种设计：即使只看一个文件，做出的改动看似正确，对整个仓库而言也确实正确。

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

Arena 会返回一个综合设计方案包。其综合决策将填入 rationale 的“Synthesis decision”部分。

阶段 C：确认（可选）

默认情况下，使用综合后的设计直接开始实现，无需人工检查点。

仅当调用方明确提出要求时才启用检查点，例如“/architect with checkpoint”“停止并在实现前给我看”或类似表达。届时，展示综合后的设计并暂停，等待确认。

无论是否设置检查点，都可以将综合方案作为独立提交发布，作为 foundational-thinking 原则技能的“先搭脚手架”模式。根据 outcome-oriented-execution 原则技能，在补全过程中有计划且范围明确的破坏性变更是可以接受的。如果要在实现前对设计进行对抗式压力测试，请对综合后的草图运行 interrogate 技能。

如果人在检查点或事后对设计结构提出异议，将其视为阶段 A 的证据。重新调研并重新运行阶段 B，然后再编写更多代码。

阶段 D：根据草图实现

用代码替换 not implemented 函数体，用逻辑替换伪代码。综合后的草图就是约定。与草图不符之处是需要指出的信号，而非可以默默消化的阻力。如果某个函数需要草图中未预料到的参数，应先询问：是草图有误、遗漏了需求，还是实现超出了范围？

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

如果实现过程中不断出现草图无法消化的阻力，就推倒草图重来。不要在错误的设计上不断打补丁，遵循从第一性原理重新设计和修复根本原因原则技能。

信号在于模式，而非个别情况。迹象包括：

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

酌情判断。少数边缘情况并不能说明架构有问题。有些问题确实很复杂。数据复杂，不等于设计复杂。

推倒重来时：

1. 针对已构建的内容，重新运行how技能。
2. 按照从第一性原理重新设计的原则，假设新约束从第一天起就已确定，然后重新设计。
3. 遵循先删减，再添加原则技能，先删减，再添加。新草图在扩展之前应比旧草图更精简。
4. 返回阶段 B，重新运行 arena。

产出

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