architect

Architect

以粗体或反引号标出的技能名称，或以 /<name> 形式运行的技能，是此技能目录旁边的 ../<name>/SKILL.md 文件；未带前缀的原则名称对应 ../principle-<name>/SKILL.md。阅读该文件并遵循其中的要求。大多数 pstack 技能仅供用户使用，因此你的技能工具无法加载它们。

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

开始

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

1. Ground
2. Sketch
3. Agree
4. Implement
5. Scrap

阶段 A：了解问题

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

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

阶段 B：构思草图

使用设计草图任务和阶段 A 的了解材料运行 arena 技能。将 references/runner-prompt.md 的内容粘贴到每个运行器的任务说明中。

使用 ~/.config/pstack/pstack-models.md 中 architect runners 行指定的运行器，替代 arena runners 行。如果文件或该行不存在，则使用 arena 技能阶段 A 中的默认席位。别名和被拒绝的条目遵循 arena 技能阶段 A 中的运行器规则。

进行两轮设计。综合之前，至少要求提出两个结构上不同的候选方案，即便第一个看起来已经足够。这是 exhaust-the-design-space 原则技能的具体实践。要提出整体形状不同的方案，而非在同一种方案中做局部修补。

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

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

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

阶段 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 编写，其中包括用法草图和综合决策。