architect

先设计再实现

Design before implementing. Sketch types, function signatures, class shapes, and module boundaries with not implemented bodies and pseudocode. Synthesize across multiple model perspectives, then fill in code against the chosen sketch. If implementation proves the sketch wrong, throw it out and redesign.

实现前先设计。用 not implemented 函数体和伪代码草拟类型、函数签名、类形状、模块边界。综合多个模型视角，再按选定的 sketch 填代码。若实现证明 sketch 错了，扔掉重设计。

Start

开始

Open a todolist with one entry per phase before starting.

开始前打开 todolist，每个阶段一条。

1. Ground

2. Sketch

3. Agree

4. Implement

5. Scrap

6. Ground（摸清现状）

7. Sketch（草拟）

8. Agree（对齐，可选）

9. Implement（实现）

10. Scrap（推倒）

Phase A: Ground the problem

Phase A: 摸清问题

Build a real mental model of every system the new code touches. Run the how skill over the relevant subsystems.

对新代码碰到的每个系统，建起真正的心智模型。对相关子系统跑 how skill。

Naming a file isn’t grounding. Produce the traced model how prescribes. If the design redefines ownership or layering, also run the why skill on the existing shape so the rationale becomes a constraint, not a guess.

点个文件名不算摸清。要产出 how 规定的追踪模型。若设计会重定归属或分层，还要对现有形状跑 why skill，让理由变成约束，而不是猜测。

Skip Phase A only when the work is genuinely greenfield with no surrounding system to integrate.

只有真正从零、没有周边系统要接入时，才跳过 Phase A。

Phase B: Sketch

Phase B: 草拟

Run the arena skill with the design-sketch task and the Phase A grounding artifacts. Pass references/runner-prompt.md as each runner’s prompt. Each candidate produces a design package shaped per references/rationale-template.md.

带着 design-sketch 任务和 Phase A 的摸底材料跑 arena skill。把 references/runner-prompt.md 作为每个 runner 的 prompt。每个候选产出按 references/rationale-template.md 成形的设计包。

Use your configured architect runners (defaults claude-opus-5-5-max, gpt-5.6-sol-max, grok-4.7-xhigh-fast).

用你配置的 architect runners（默认 claude-opus-5-5-max、gpt-5.6-sol-max、grok-4.7-xhigh-fast）。

Design it twice. Require at least two structurally distinct candidates before synthesis, even when the first looks sufficient. This is the exhaust-the-design-space principle skill made concrete. Whole-shape alternatives, not point fixes inside one shape.

设计两遍。综合前至少要两个结构上不同的候选，哪怕第一个看起来够用。这是 exhaust-the-design-space principle skill 的落地：整形状的备选，不是同一形状里的点状修补。

Screen every candidate against references/design-red-flags.md before synthesis. Reject or revise shallow modules, information leakage, temporal decomposition, and pass-through methods.

综合前用 references/design-red-flags.md 筛每个候选。浅模块、信息泄漏、按时间切分、透传方法：拒绝或改。

Compare viable candidates on interface depth. Prefer the design that hides more complexity behind a smaller, simpler public surface. A rich interface can keep call chains short by concentrating capability instead of scattering it across layers.

在可行候选上比接口深度。优先把更多复杂度藏在更小、更简单公开面后面的设计。丰富接口可以通过集中能力缩短调用链，而不是把能力散在各层。

Arena returns one synthesized design package. The synthesis decision populates the rationale’s “Synthesis decision” section.

Arena 返回一份综合后的设计包。综合决策写入 rationale 的 “Synthesis decision” 小节。

Phase C: Agree (opt-in)

Phase C: 对齐（可选）

Default: proceed directly to implementation with the synthesized design. No human checkpoint.

默认：用综合后的设计直接进入实现。不等人卡点。

Opt in to a checkpoint when the invoker explicitly asks: “/architect with checkpoint,” “stop and show me before implementing,” or similar. Then surface the synthesized design and pause for sign-off.

调用方明确要求时才设卡点：如 “/architect with checkpoint”、“stop and show me before implementing” 等。然后亮出综合设计，停下来等人签字。

The synthesis can ship as its own commit either way, as the “scaffold first” mode of the foundational-thinking principle skill. Planned and scoped breakage during fill-in is fine, per the outcome-oriented-execution principle skill. For adversarial pressure on the design before implementing, run the interrogate skill on the synthesized sketch.

无论有没有卡点，综合结果都可以单独成 commit——这是 foundational-thinking principle skill 的「先脚手架」模式。按 outcome-oriented-execution，填空期间有计划、有范围的破坏可以。实现前要对设计加压，对综合 sketch 跑 interrogate skill。

If the human pushes back on the shape (in a checkpoint or after the fact), treat that as Phase A evidence. Re-ground and re-run Phase B before writing more code.

人对形状推回（卡点上或事后），当作 Phase A 证据。再摸底，重跑 Phase B，再写更多代码。

Phase D: Implement against the sketch

Phase D: 按 sketch 实现

Replace not implemented bodies with code, pseudocode with logic. The synthesized sketch is the contract.

把 not implemented 换成代码，伪代码换成逻辑。综合后的 sketch 就是契约。

Deviations from the sketch are signal worth surfacing, not friction to absorb silently. If a function needs a parameter the sketch didn’t anticipate, ask whether the sketch was wrong, the requirement was missed, or the implementation is overreaching.

偏离 sketch 是值得亮出来的信号，不是默默吞掉的摩擦。若函数需要 sketch 没料到的参数，问：是 sketch 错了、需求漏了，还是实现越界了。

Phase E: Scrap when the architecture is wrong

Phase E: 架构错了就推倒

If implementation keeps producing friction the sketch can’t absorb, throw the sketch out. Don’t bolt fixes onto a wrong design, per the redesign-from-first-principles and fix-root-causes principle skills.

若实现不断产生 sketch 吸收不了的摩擦，扔掉 sketch。别往错误设计上钉补丁——按 redesign-from-first-principles 和 fix-root-causes principle skills。

The signal is a pattern, not single instances. Tells:

信号是模式，不是单次。迹象：

• The same shape of workaround appearing repeatedly across unrelated code.

• Multiple unrelated edge cases that all need special-case branches.

• Types that need escape hatches (any, casts, optional fields always set in practice) to compile.

• The “we need a lock” reflex when the sketch said the state wasn’t shared.

• Callers having to know the abstraction’s internal rules to use it.

• Two or more independent Phase D deviations of the same shape across the implementation.

• 同形状的 workaround 在无关代码里反复出现。

• 多个无关边界情况都要特判分支。

• 类型靠逃生舱才能编译（any、强转、实践中总被设的 optional 字段）。

• sketch 说状态不共享，却条件反射「我们需要一把锁」。

• 调用方得懂抽象内部规则才能用。

• 实现里出现两次及以上同形状、彼此独立的 Phase D 偏离。

Use judgment. A few edge cases don’t condemn an architecture. Some problems are legitimately complex. Complexity in the data is not complexity in the design.

用判断。几个边界情况不判死刑。有些问题本来就复杂。数据里的复杂不等于设计里的复杂。

When you scrap:

推倒时：

1. Re-run the how skill over what’s been built.

2. Redesign as if the new constraints had been day-one assumptions, per redesign-from-first-principles.

3. Subtract before adding, per the subtract-before-you-add principle skill. The new sketch should be smaller than the old one before it grows.

4. Return to Phase B and re-run arena.

5. 对已建成的部分重跑 how skill。

6. 按 redesign-from-first-principles，把新约束当作第一天就有的假设重新设计。

7. 按 subtract-before-you-add，先减后加。新 sketch 在长大前应比旧的更小。

8. 回到 Phase B，重跑 arena。

Outputs

产出

The caller’s usage is written first and the type sketch derived from it. One file with new types and signatures for small changes. Module map plus type definitions for larger work. The rationale ships alongside, shaped per references/rationale-template.md, including the usage sketch and the synthesis decision.

先写调用方用法，再从中推出类型 sketch。小改动：一个文件装新类型和签名。大活：模块图加类型定义。rationale 一并交付，按 references/rationale-template.md 成形，含 usage sketch 和综合决策。