architect

架构设计

在 Codex 上，遵循此技能前，请阅读平台映射，包括其中针对各技能的说明。

在 GitHub Copilot 上，遵循此技能前，请阅读平台映射，包括其中针对各技能的说明。

在 Muse 上，遵循此技能前，请阅读平台映射，包括其中针对各技能的说明。

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

开始

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

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

阶段 A：调研问题

对新代码涉及的每个系统，建立切实的心智模型。对相关子系统运行 how 技能。仅仅指出文件名不算调研。按照 how 的要求，产出架构说明。如果设计重新定义了所有权或分层方式，还要对现有结构运行 why 技能，将其设计依据作为约束，而非猜测。

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

阶段 B：勾勒

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

使用 pstack-models.md 中 architect runners 行列出的 runner，替代 arena runners 行。如果该文件或相应行缺失，则使用 模型 中的默认值。别名和拒绝的条目遵循 arena 技能阶段 A 中的 runner 规则。

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

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

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

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

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

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

仅当调用者明确提出要求时，才启用检查点，例如：“/architect with checkpoint”、“实现前先停下来给我看”或类似表述。此时展示综合后的设计，并暂停等待批准。

无论采用哪种方式，综合结果都可以单独提交，作为 foundational-thinking 原则技能中的 “scaffold first” 模式。根据 outcome-oriented-execution 原则技能，在补全过程中有计划、有范围地破坏现有内容是可以接受的。若要在实现前对设计施加对抗性压力，可对综合后的草图运行 interrogate 技能。

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

阶段 D：根据草图实现

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

在结束每个实现单元或将其契约交给下一位工作者之前，请将已接受的偏差与已保存的行为契约、接口和职责分配进行比较。适当的负责人或审查流程接受变更后，更新现有草图和理由中的相关部分，并在那里记录接受变更的依据。如果某项操作从抛出错误改为返回拒绝结果，必须在下一个单元开始前更新结果契约。

对于不影响共享契约的局部偏差，请记录决定及设计仍然成立的原因；局部变量重命名无需重写架构。让未获接受的变更和未解决的分歧保持可见。如果下一位工作者会收到相互矛盾的指示，就不要宣称该单元已协调一致；也不要仅为证明已实现的内容合理而修改规范。使用现有设计产物，而不是为每个单元单独创建平行记录。反复出现的结构性偏差仍会触发阶段 E。

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

如果实现不断产生草图无法消化的摩擦，就丢弃草图。遵循 redesign-from-first-principles 和 fix-root-causes 原则技能，不要在错误的设计上打补丁。

信号看的是模式，而非单个实例。表现包括：

• 在彼此无关的代码中反复出现相同形式的权宜方案。
• 多个互不相关的边缘情况都需要特殊分支。
• 为了通过编译，类型需要逃生口（any、类型转换、实际上总会设置的可选字段）。
• 草图明明表示状态未共享，大家却本能地觉得“我们需要一把锁”。
• 调用方必须了解抽象的内部规则才能使用它。
• 实现中出现两个或更多形式相同、彼此独立的阶段 D 偏差。

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

推倒重来时：

1. 对已构建的内容重新运行 how 技能。
2. 遵循 redesign-from-first-principles，将新约束视为从第一天起就存在的假设，重新设计。
3. 遵循 subtract-before-you-add 原则技能，先做减法再做加法。新草图在扩展前应比旧草图更小。
4. 返回阶段 B，重新运行 arena。

产物

先写调用方的用法，再据此推导类型草图。小型变更只需一个包含新类型和签名的文件；较大型工作则需要模块映射和类型定义。理由应随产物一同交付，按照 references/rationale-template.md 的格式编写，其中包括用法草图和综合决策。

模型

角色默认值来自 plugins/pstack/models.json（在该文件中编辑，然后重新运行 tools/generate.mjs）。运行时，覆盖表 pstack-models.md 中匹配的角色行会覆盖相应默认值；/setup-pstack 会写入该表，并按运行时列出其路径。

• architect runners：opus、fable、sonnet、haiku

推理力度

覆盖表中的角色值可以在模型名称后指定推理力度，例如 opus @xhigh。Claude Code 支持的级别有：low、medium、high、xhigh、max。具体适用哪些级别取决于模型。不带 @ 的值会采用表中的 default effort 行；该行可以指定某个级别或 session。如果表中没有这一行，则采用 session。session 不设置推理力度，因此会按常规方式进行调度。读取模型名称前，先去掉后缀：inherit-parent 或 auto 在所有级别下都会省略 model，而模型名称则会作为 model 传入。将级别作为调度的推理力度字段传入，并保留原本要使用的 subagent_type。Claude Code 的 Agent 调用使用 effort，Codex 的 spawn_agent 使用 reasoning_effort。在 Muse 中，Workflow 子级使用 effort；subagent_spawn 调度则保留会话的推理力度。