--- name: architect description: "在写代码前勾勒类型、签名和模块结构,并在实现填充期间持续参与。用于 /architect、‘架构设计这个’、‘设计这个’,或直接写代码会锁定错误形态的非平凡工作。" disable-model-invocation: true --- # 架构设计 用 `not implemented` 函数体和伪代码勾勒类型、函数签名、类结构及模块边界。综合多个模型视角,然后按选定草图填入代码。 ## 开始 开始前创建待办清单,每个阶段一项。 1. 建立问题认知 2. 绘制草图 3. 达成一致 4. 实现 5. 推倒重来 ## 阶段 A:建立对问题的扎实理解 对新代码涉及的每个系统建立真实心智模型。针对相关子系统运行 **how** 技能。仅指出文件名不算建立理解。产出 `how` 要求的架构说明。如果设计重新定义了责任归属或分层,还要对现有结构运行 **why** 技能,使原有理由成为约束,而非猜测。 只有工作确实是全新项目、没有周边系统要集成时,才跳过阶段 A。 ## 阶段 B:绘制草图 用设计草图任务和阶段 A 的理解制品运行 **arena** 技能。向每个参赛执行者传入 `references/runner-prompt.md` 作为提示词。 从 `pstack-models.mdc` 规则中的 `architect runners` 行选取执行者,替代 `arena runners` 行。如果规则或该行缺失,使用 `claude-opus-5-5-xhigh` 和 `grok-4.7-xhigh-fast`。别名和被拒条目按 **arena** 技能阶段 A 的执行者规则处理。 设计两次。综合之前至少要求两个结构上不同的候选,即使第一个看起来足够。这是 **exhaust-the-design-space** 原则技能的具体实现。需要整体结构替代方案,而非同一结构内部的局部修补。 综合前,按 [`references/design-red-flags.md`](references/design-red-flags.md) 筛查每个候选。假定下一位贡献者是代理,只看自己打开的文件、复制最近的例子,并采用能通过编译的最短路径。优先选择这样的设计:在一个文件里看似正确的变更,对整个仓库也正确。 按接口深度比较可行候选。优先选择在更小、更简单的公开接口后隐藏更多复杂性的设计。丰富的接口可以通过集中能力而非分散到多层,缩短调用链。 Arena 返回一份综合设计包。其综合决策填入理由说明中的“Synthesis decision”章节。 ## 阶段 C:达成一致(主动选择) 默认:直接使用综合设计进行实现,不设置人工检查点。 只有调用者明确要求,例如“/architect with checkpoint”“stop and show me before implementing”或类似意思时,才启用检查点。此时展示综合设计并暂停等待认可。 无论哪种方式,综合结果都可以作为独立提交交付,对应 **foundational-thinking** 原则技能的“先搭骨架”模式。根据 **outcome-oriented-execution** 原则技能,填充期间允许有计划、范围受控的暂时破坏。若要在实现前对设计施加对抗性检验,对综合草图运行 **interrogate** 技能。 如果人类对结构提出异议,无论在检查点还是事后,都把它视为阶段 A 的证据。重新建立理解并重跑阶段 B,然后再继续写代码。 ## 阶段 D:按草图实现 把 `not implemented` 函数体换成代码,把伪代码换成逻辑。综合草图就是契约。偏离它是应显式提出的信号,不是默默吸收的摩擦。如果某函数需要草图未预料的参数,要问:是草图错了、需求遗漏了,还是实现超出了范围? ## 阶段 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` 组织,包括用法草图和综合决策。