用途
Architect 是一个“设计先行”的技能:在写实现代码前,先产出类型、函数签名、类形态和模块边界,函数体保持 not implemented 状态,逻辑用伪代码表达。设计确定后,再按草图填充代码,并在实现过程中持续对照草图、发现偏差。
它要解决的问题是:让实现阶段有一份明确的契约,避免一边写一边改结构,也避免把架构问题掩盖成局部修补。
工作流程
技能启动前,先建立一个 todolist,每个阶段对应一项。流程分五个阶段:Ground(打底)、Sketch(草图)、Agree(确认,可选)、Implement(实现)、Scrap(废弃重来)。
Phase A:Ground
为所有将被新代码触及的系统建立真实的心智模型。对相关子系统运行 how 技能,产出架构解释。如果设计涉及重新定义归属或分层,还要对现有形态运行 why 技能,使其理由成为约束条件。只有当工作确实是完全没有周边系统可供集成的全新项目时,才可跳过此阶段。
Phase B:Sketch
以 design-sketch 任务和 Phase A 的打底产物运行 arena 技能,把 references/runner-prompt.md 作为每个 runner 的提示词。要求“设计两次”:在综合之前至少要有两个结构上不同的候选方案,即使第一个看起来已经足够。候选必须是整体形态的替代方案,而不是同一形态内的点状修补。
每个候选方案都要对照 references/design-red-flags.md 进行筛查。筛查时假设下一位贡献者是一个只能看到自己打开文件的智能体,它会复制最近的示例,并选择能编译的最短路径。因此优先选择那种“从单个文件看是对的改动,对整个仓库也是对的”设计。
在可行候选中比较接口深度,优先选择把更多复杂性藏在更小、更简单的公共接口之后的设计。arena 返回一份综合后的设计包,其综合决策填入理由文档的“Synthesis decision”部分。
Phase C:Agree(可选)
默认直接进入实现,不设人工检查点。只有当调用方明确要求(如“/architect with checkpoint”、“stop and show me before implementing”等)时才设置检查点,展示综合设计并暂停等待确认。
如果人对设计形态提出异议,应视为 Phase A 的证据,重新打底并重跑 Phase B,再继续写代码。
Phase D:Implement
用代码替换 not implemented 函数体,用逻辑替换伪代码。综合后的草图就是契约。偏离草图是需要主动暴露的信号,而不是默默吸收的摩擦。如果某个函数需要草图未预见的参数,要追问:是草图错了、需求漏了,还是实现越界了。
Phase E:Scrap
如果实现持续产生草图无法吸收的摩擦,就废弃草图,不要在错误设计上打补丁。判断信号是模式而非单例,例如:同类变通在无关代码中反复出现;多个无关边界情况都需要专门分支;类型需要逃生舱(any、强制转换、实际总被赋值的可选字段)才能编译;草图说状态不共享却出现“我们需要加锁”的反射;调用方必须了解抽象的内部规则才能使用;实现中出现两个及以上同形态的 Phase D 偏离。
废弃时:对已构建内容重跑 how 技能;把新约束当作第一天假设重新设计;先做减法再做加法,新草图在增长前应比旧草图更小;返回 Phase B 重跑 arena。
输出物
先写调用方的使用方式,再从中推导类型草图。小改动输出一个包含新类型和签名的文件;较大工作输出模块图加类型定义。理由文档随附,按 references/rationale-template.md 组织,包含使用草图与综合决策。
工程领域指引
针对受影响的设计决策,只阅读相关领域指南:后端(归属、依赖、持久化、消息、生命周期)、前端(UI/UX、状态、浏览器边界、性能)、HTTP(协议生命周期与请求语义)、OpenAPI(资源、表示与契约演进)。
适用场景与限制
适用于需要先定架构再写代码的中大型改动、涉及所有权或分层调整的设计、希望多模型视角交叉比较的设计决策。资料未提供具体运行环境、依赖安装方式或性能数据。默认不设人工确认,需要确认时须显式要求。是否跳过 Phase A 取决于是否为全新项目,需自行判断。