architect

Architect

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

开始

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

1. 打好基础
2. 勾勒设计
3. 达成一致
4. 实现
5. 搁置

阶段 A：打好问题基础

深入理解新代码涉及的每个系统。针对相关子系统运行 how 技能。只列出文件名不算打好基础。按照 how 的要求产出架构说明。如果设计重新定义了所有权或分层，还要针对现有结构运行 why 技能，让其中的理由成为约束，而非猜测。

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

阶段 B：勾勒设计

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

使用 pstack 设置文件中 architect runners 行指定的 runner（在 Cursor 中为 ~/.cursor/rules/pstack-models.mdc，在其他 harness 中为 ~/.agents/pstack-models.md），而不是 arena runners 行。如果文件或该行不存在，则使用 claude-opus-5-5-xhigh 和 grok-4.7-xhigh-fast。别名和被拒条目遵循 arena 技能阶段 A 中的 runner 规则。

设计两次。在综合之前，至少提出两个结构上有明显差异的候选方案，即使第一个看起来已经足够。这是将 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. 针对已构建的内容，重新运行how技能。
2. 按照从第一性原理重新设计的原则，假设新约束从第一天起就已确定，然后重新设计。
3. 遵循先删减，再添加原则技能，先删减，再添加。新草图在扩展之前应比旧草图更精简。
4. 返回阶段 B，重新运行 arena。

产出

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