跳到正文
  1. 技能速查
  2. 设计和把关
  3. /pstack:architect

/pstack:architect

自动调用

一句话写跨模块的代码前,先定好怎么调用、类型怎么定,再比几个方案。

什么时候用
改动跨出一个函数,牵涉好几个模块。
要一起装
arena、how
这样说
/pstack:architect 先设计导入流程,别急着写代码。我最在意别的代码怎么调用它。

用它和不用它

同一件事,直接跟 AI 说,和点名用 /pstack:architect,AI 的做法不一样:

直接说用 /pstack:architect
想到哪写到哪,直接写实现先写类型、函数签名和模块边界,函数体留 not implemented
只出一个方案就开干用 arena 让几个模型各画草图,至少两个结构不同
写不下去就打补丁硬绕过去偏离草图就说出来,同类麻烦反复出现就推倒重画

文档写了什么

原文分 7 节,约 800 个英文单词,中文译文约 1400 字,读完约 4 分钟。点一节直接跳到全文。

开头说明它先画出类型、签名、类和模块边界,函数体空着,综合几个模型的方案后再照草图填代码。

  1. 1开始开工前列一个待办清单,Ground、Sketch、Agree、Implement、Scrap 五步各一条。
  2. 2阶段 A:摸清问题对要碰的每个系统跑 how,动到归属或分层时再跑 why,全新项目才可以跳过。
  3. 3阶段 B:画草图用 arena 让多个模型各画草图,至少两个结构不同,按红旗清单筛,挑接口小又藏得多的。
  4. 4阶段 C:达成一致(可选)默认画完直接写,你说「with checkpoint」才停下等你点头,你反对设计就回 A、B 重来。
  5. 5阶段 D:照着草图实现把 not implemented 换成真代码,草图就是合同,多出参数时先查是草图错了还是写多了。
  6. 6阶段 E:架构错了就推倒重来同类绕路反复出现、类型要靠 any 才编得过时推倒草图,先删后加,再跑 arena。
  7. 7产出先写调用方怎么用,再推出类型草图,附一份按模板写的设计理由和合成取舍。

看写法亮点读全文

写法亮点

挑了几句原文:每句让 AI 做什么、为什么这样写管用、你写提示词时怎么借来用。

  1. 硬要第二个方案

    Require at least two structurally distinct candidates before synthesis, even when the first looks sufficient.

    综合之前,至少要有两个结构上明显不同的候选方案,哪怕第一个看起来已经够用。

    让 AI
    它至少拿出两个结构完全不同的设计来比,不会抓住第一个想法就开写。
    为什么管用
    「哪怕第一个看起来已经够用」提前堵住了 AI 最常用的借口。
    借来用
    要标题时写:「给我两个思路完全不同的标题,哪怕第一个你已经很满意。」
  2. 照最偷懒的接手人设计

    sees only the files it opened, copies the nearest example, and takes the shortest path that compiles

    只看得到自己打开的文件,会照抄离得最近的例子,会走能编译通过的最短路径

    让 AI
    它会挑那种别人照着旁边的例子抄也不会抄错的设计。
    为什么管用
    把接手人会怎么偷懒写成三个具体动作,AI 就能拿每个方案去逐条对照。
    借来用
    排版时写:「假设看这份表格的人只看第一行和加粗的字,照这个来排。」
  3. 把偏差说成信号

    Deviations from it are signal to surface, not friction to absorb silently.

    偏离它的地方是要说出来的信号,不是要默默消化的摩擦。

    让 AI
    写代码时发现和设计对不上,它会说出来,而不是悄悄绕过去。
    为什么管用
    把「默默修掉」重新说成「藏起信号」,AI 就明白小偏差也值得报告。
    借来用
    让 AI 照大纲写时加一句:「哪里觉得大纲不对,标出来告诉我,不要自己改。」
  4. 列出该放弃的迹象

    The signal is a *pattern*, not single instances.

    信号是一种*反复出现的模式*,不是个别的例子。

    让 AI
    只有同类问题反复出现时它才推倒重来,碰到一两个特例不会大动干戈。
    为什么管用
    「什么时候放弃」很难判断;给一串能对照的迹象,再说清单个例子不算,AI 就不会放弃得太早或太晚。
    借来用
    定改流程的门槛:「同一类投诉一周出现三次以上才改流程,只出现一次的先记下来。」
  5. 先说默认,再说例外

    Default: proceed directly to implementation with the synthesized design.

    默认:直接拿综合好的设计去实现。

    让 AI
    默认它设计完就直接动手,只有你说「with checkpoint」它才停下来等你点头。
    为什么管用
    先定死默认做法,再给出触发例外的原话,AI 就不用每次猜要不要停。
    借来用
    交代写作时说:「默认写完直接发;我说『先给我看』时再停下来。」

全文

AI 读到的就是这份 SKILL.md。可以看中文、看原文,或者一段一段对照着看。

descriptionSketch types, signatures, and module structure before code, then stay in the loop while implementation fills in. Use for /pstack:architect, 'architect this', 'design this', or non-trivial work where jumping to code would lock in the wrong shape.

description写代码之前,先画出类型、函数签名和模块结构的草图,然后在填充实现的过程中一直跟着。用于 /pstack:architect、「architect this」、「design this」,或者一上来就写代码会把错误的结构定死的、不简单的活。

Architect

Architect(先设计再动手)

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.

画出类型、函数签名、类的形状和模块边界的草图,函数体写成 not implemented,再配上伪代码。综合多个模型的视角,然后照着选定的草图把代码填进去。

Start

开始

Open a todolist with one entry per phase before starting.

开始之前,先开一个待办清单,每个阶段一项。

  1. Ground
  2. Sketch
  3. Agree
  4. Implement
  5. Scrap
  1. 摸清现状
  2. 画草图
  3. 达成一致
  4. 实现
  5. 推倒重来

Phase A: Ground the problem

阶段 A:摸清问题

Build a real mental model of every system the new code touches. Run the how skill over the relevant subsystems. Naming a file isn't grounding. Produce the architectural explanation 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 技能。说出一个文件名不算摸清。产出 how 规定的那种架构说明。如果设计会重新划定归属或分层,还要对现有的结构运行 why 技能,让当初的理由成为一条要求,而不是一个猜测。

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

只有当这件活真的是从零开始、周围没有要对接的系统时,才跳过阶段 A。

Phase B: Sketch

阶段 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.

用设计草图这个任务,加上阶段 A 摸清现状时得到的材料,运行 arena 技能。把 references/runner-prompt.md 作为每个参赛者的提示词传进去。

Take the runners from the architect runners line in the pstack settings file (~/.cursor/rules/pstack-models.mdc in Cursor, ~/.claude/rules/pstack-models.md in Claude Code, ~/.agents/pstack-models.md in other harnesses), in place of the arena runners line. If the file or that line is missing, use claude-opus-5-5-xhigh and grok-4.7-xhigh-fast. Alias and rejected entries follow the runner rules in the arena skill's Phase A.

参赛者从 pstack 设置文件里的 architect runners 那一行取(Cursor 里是 ~/.cursor/rules/pstack-models.mdc,Claude Code 里是 ~/.claude/rules/pstack-models.md,其他工具里是 ~/.agents/pstack-models.md),代替 arena runners 那一行。如果文件或那一行不存在,就用 claude-opus-5-5-xhigh 和 grok-4.7-xhigh-fast。别名条目和不被接受的条目,按 arena 技能阶段 A 里的参赛者规则处理。

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 原则技能的具体做法。要的是整体结构不同的方案,不是在同一个结构里修修补补。

Screen every candidate against references/design-red-flags.md before synthesis. Assume the next contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Prefer the design where a change that looks right from one file is right for the whole repo.

综合之前,拿 references/design-red-flags.md 把每个候选方案都筛一遍。假设下一个来改代码的是一个 AI:它只看得到自己打开的文件,会照抄离得最近的例子,会走能编译通过的最短路径。优先选这样的设计:在一个文件里看起来对的改动,对整个仓库也是对的。

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. Its synthesis decision fills the rationale's "Synthesis decision" section.

Arena 交回一份综合好的设计方案。它做出的综合决定,填进设计理由里的「Synthesis decision」一节。

Phase C: Agree (opt-in)

阶段 C:达成一致(可选)

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

默认:直接拿综合好的设计去实现。中间不停下来等人确认。

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

只有调用的人明确要求时,才加一个确认点:「/pstack:architect with checkpoint」「实现之前先停下来给我看」,或者类似的话。这时就把综合好的设计拿出来,停下来等对方点头。

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.

不管有没有确认点,综合好的设计都可以单独作为一个提交发出去,这就是 foundational-thinking 原则技能里的「scaffold first」(先搭架子)做法。按 outcome-oriented-execution 原则技能,填充实现期间出现计划之内、范围明确的破坏是可以的。如果想在实现之前给设计施加对抗性的压力,就对综合好的草图运行 interrogate 技能。

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.

如果有人对结构提出反对(在确认点上,或者事后),就把它当成阶段 A 的证据。先重新摸清现状、重跑阶段 B,再继续写代码。

Phase D: Implement against the sketch

阶段 D:照着草图实现

Replace not implemented bodies with code, pseudocode with logic. The synthesized sketch is the contract. Deviations from it are signal to surface, 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.

把 not implemented 的函数体换成代码,把伪代码换成逻辑。综合好的草图就是约定。偏离它的地方是要说出来的信号,不是要默默消化的摩擦。如果某个函数需要一个草图没预料到的参数,就问一问:是草图错了,是漏了需求,还是实现做过头了。

Phase E: Scrap when the architecture is wrong

阶段 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.

如果实现过程中不断冒出草图消化不了的摩擦,就把草图扔掉。按 redesign-from-first-principles 和 fix-root-causes 原则技能,不要在错误的设计上继续打补丁。

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.
  • 同一种绕路的写法,在互不相关的代码里一再出现。
  • 好几个互不相关的边缘情况,全都要单独加分支处理。
  • 类型要靠逃生口(any、强制转换、实际上总会被赋值的可选字段)才能编译通过。
  • 草图说状态不共享,却冒出「我们得加把锁」的条件反射。
  • 调用方必须懂这个抽象的内部规则才能用它。
  • 整个实现里,出现两处或更多处彼此独立、但形状相同的阶段 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.
  1. 对已经建好的部分重新运行 how 技能。
  2. 按 redesign-from-first-principles,重新设计,就当这些新的要求从第一天起就是前提。
  3. 按 subtract-before-you-add 原则技能,先减再加。新草图在变大之前,应该先比旧的小。
  4. 回到阶段 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.

先写调用方怎么用,再从用法推出类型草图。小改动:一个文件,放新的类型和签名。大一点的活:模块地图加上类型定义。设计理由跟着一起交,按 references/rationale-template.md 的格式写,里面包括用法草图和综合决定。

原文作者 Lauren Tan(poteto),MIT 许可。译文由本站翻译,核对到 pstack 镜像 97de40d。 在 GitHub 上看

本站是 pstack 的非官方入门教程,不是官方文档;pstack 由 poteto 开发,命令和行为以官方仓库为准。教程原始源码见 GitHub。

由 airali部署,基于小小东的 MIT 授权教程改编。