--- name: architect description: "先勾勒类型、签名和模块结构,再在实现填充过程中持续参与。用于 /architect、‘为它做架构设计’、‘设计这个’,或直接写代码会锁定错误形态的非平凡工作。" disable-model-invocation: true --- # 架构设计 在 Claude Code 中,每个会话在遵循此技能前,先阅读一次 [Claude Code 适配器](../../docs/harness/claude-code.md)。它将 pstack 技能中的 Cursor 名称映射到 Claude Code。 用 `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 返回一个综合设计包。其综合决策填入理由文档的“综合决策”一节。 ## 阶段 C:达成一致(按需启用) 默认:直接根据综合设计进入实现。无需人工检查点。 调用者明确要求时才启用检查点,例如“/architect with checkpoint”“先停下来展示给我,再实现”等。此时展示综合设计,并暂停等待认可。 无论采用哪种方式,综合结果都可独立形成一次提交,这是 **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`,包含使用草图和综合决策。