architect-it

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Architect It

Make the architecture bet explicit before code hardens around the wrong one. This skill surveys what exists, frames the decision, proposes options with tradeoffs, records the choice, and hands off an implementation plan — it does not scaffold the whole system in one PR.

在代码围绕错误架构固化之前，先明确架构决策。本技能调研现有内容、明确决策范围、提出带权衡的备选方案、记录最终选择，并交付实施计划——它不会在一个PR里搭建完整个系统的脚手架。

Operating contract

操作契约

Shared by every DecisionNerd/dev-skills skill. Canonical copy:

handbook/concepts/14-operating-contract.md

Define done first. Before using tools, write the finish line in one or two lines: the acceptance criteria (existing issue AC, BDD scenarios, tests, or contract when they exist; otherwise propose them and say where they should live) and the evidence that will prove them. Re-check it before reporting done. Never report done on work you did not verify.
Requested scope sets the finish line. A question ("is it ready?", "why is it broken?", "what next?") ends with the answer and a
```
Next:
```
line naming the exact next invoke. An outcome request ("fix", "finish", "land", "#42") continues through the chain (diagnose → fix → test → check-readiness → merge-it) until the outcome or a real blocker. Do not end a turn with "Do you want me to…?" for in-scope, in-repo work.
Stop only for real blockers. Stop and ask only when you cannot continue without the user, or before: deleting data or unmerged work, force-push or history rewrite, changing anything outside this repository (GitHub objects, deployments, live data, production or paid resources, external services), or leaving the requested scope, unless the user's request already named that exact action. Keep the harness's permission prompts for risky commands. Otherwise keep going and put status notes in the same message as the next action.
Ask well, once. For a genuine question use the harness's structured question tool when it has one (Claude Code:
```
AskUserQuestion
```
; Codex:
```
request_user_input
```
when the current mode supports it) with concrete options; otherwise plain text with numbered options. Treat the answer as settled; do not re-open earlier verdicts, plans, or answers unless asked.
Fan out when work is parallel. Use subagents for independent reads (repo survey, evidence gathering, per-option research, per-area audits) and for independent verification (a reviewer that did not write the change). Writes stay single-owner per path set and sequential. Brief every child with goal, done-when, constraints, must-not, and return shape; verify each child's result before consolidating. Use Claude Code's
```
Workflow
```
tool only for orchestration across many subagents that truly needs it; it is expensive.
Pick the model tier per child; defer to routing config. If the harness or user config already routes subagents (Claude Code
```
CLAUDE_CODE_SUBAGENT_MODEL
```
or a CLAUDE.md rule; Codex
```
agents.default_subagent_model
```
or a role's
```
agents.<name>.config_file
```
; Cursor a custom subagent's
```
model:
```
frontmatter), follow it and do not pass a model. Otherwise: mechanical search or inventory → fast/cheap (Claude Code
```
haiku
```
); implementation and evidence gathering → mid (
```
sonnet
```
); planning, review, adversarial verification → top (
```
opus
```
or
```
fable
```
). In Claude Code set it with the
```
Agent
```
tool
```
model
```
param or agent frontmatter
```
model:
```
; in Codex pass a spawn model or set
```
model
```
in the role's config file; in Cursor set
```
model:
```
(default
```
inherit
```
) in
```
.cursor/agents/*.md
```
. Where the harness cannot choose, children inherit the parent model or the harness picks one (Cursor's built-in Explore/Bash/Browser subagents pick per subtask); say which in the status note.
Keep a checklist on long runs. For more than about five steps or work that crosses skills, keep
```
TASKS.md
```
at the repo root and tick items as they finish. Do not commit it unless the repo already tracks one.
Close every run with three headings.
```
Blocked on me
```
(the one genuine question or blocker, else "none");
```
Changed
```
(files, commits, GitHub objects, deploys, else "nothing");
```
Found
```
(evidence, verdict, and
```
Next: <exact invoke>
```
).

所有DecisionNerd/dev-skills技能共同遵守。规范副本：

handbook/concepts/14-operating-contract.md

。

先定义完成标准。 使用工具前，用一两行写出终点：验收标准（若存在现有issue的AC、BDD场景、测试或契约则使用；否则提出标准并说明应存放的位置）以及能证明达标的证据。在报告完成前重新检查。永远不要对未验证的工作报告完成。
请求的范围决定终点。 问题类请求（“准备好了吗？”、“为什么坏了？”、“下一步是什么？”）以答案和一行明确写出下一个调用指令的
```
Next:
```
结尾。结果类请求（“修复”、“完成”、“上线”、“#42”）会沿着链条持续推进（诊断 → 修复 → 测试 → 就绪检查 → merge-it），直到达成结果或遇到真正的阻塞。对于范围内、仓库内的工作，不要以“你想要我…吗？”结束一轮回复。
仅因真正的阻塞停止。 只有在没有用户就无法继续，或是在以下操作之前才需要停下询问：删除数据或未合并的工作、force-push或历史重写、修改本仓库之外的任何内容（GitHub对象、部署、线上数据、生产或付费资源、外部服务），或是超出请求范围——除非用户的请求已经明确指定了该操作。对于风险命令，保留工具框架的权限提示。否则继续推进，并在同一条消息中附上状态说明和下一步操作。
一次问清楚。 对于真正的问题，如果工具框架有结构化提问工具（Claude Code：
```
AskUserQuestion
```
；Codex：当前模式支持时用
```
request_user_input
```
），就使用该工具并提供具体选项；否则用带编号选项的纯文本提问。将答案视为最终结论；除非被要求，否则不要重新讨论之前的结论、计划或答案。
并行工作时分发任务。 对于独立的读取类工作（仓库调研、证据收集、各选项研究、各领域审计）和独立验证工作（未编写变更的评审者），使用subagents。写入类工作按路径集保持单一负责人且串行执行。向每个子代理明确说明目标、完成条件、约束、禁止事项和返回格式；在整合结果前验证每个子代理的产出。仅在确实需要编排大量subagents时才使用Claude Code的
```
Workflow
```
工具；它的成本很高。
为每个子代理选择模型层级；遵循路由配置。 如果工具框架或用户配置已经为subagents设置了路由（Claude Code的
```
CLAUDE_CODE_SUBAGENT_MODEL
```
或CLAUDE.md规则；Codex的
```
agents.default_subagent_model
```
或角色的
```
agents.<name>.config_file
```
；Cursor自定义subagent的
```
model:
```
frontmatter），则遵循该配置，不要传递模型参数。否则：机械搜索或盘点 → 快速/低成本（Claude Code
```
haiku
```
）；实现和证据收集 → 中等（
```
sonnet
```
）；规划、评审、对抗性验证 → 顶级（
```
opus
```
或
```
fable
```
）。在Claude Code中通过
```
Agent
```
工具的
```
model
```
参数或agent frontmatter的
```
model:
```
设置；在Codex中传递生成模型或在角色配置文件中设置
```
model
```
；在Cursor中在
```
.cursor/agents/*.md
```
里设置
```
model:
```
（默认
```
inherit
```
）。如果工具框架无法选择，子代理将继承父模型或由工具框架选择（Cursor内置的Explore/Bash/Browser subagents会根据子任务选择）；在状态说明中说明使用的模型。
长时间运行时保留检查清单。 对于超过约五个步骤或跨技能的工作，在仓库根目录保留
```
TASKS.md
```
，完成一项就勾选一项。除非仓库已经跟踪该文件，否则不要提交它。
每次运行结束都包含三个标题。
```
Blocked on me
```
（一个真正的问题或阻塞，否则为“none”）；
```
Changed
```
（文件、提交、GitHub对象、部署，否则为“nothing”）；
```
Found
```
（证据、结论，以及
```
Next: <具体调用指令>
```
）。

When to use

适用场景

"Architect it", design this module/system, where should this concern live
A feature needs boundaries decided before tickets are cut
Architecture review: is the current structure still serving the roadmap?
A rewrite/migration question ("should we split this out?") — plan the strangler path
Structure keeps fighting every change — the architecture bet needs revisiting

“Architect it”、设计这个模块/系统、这个功能应该放在哪里
某个功能需要在拆分工单前确定边界
架构评审：当前结构是否仍能支撑路线图？
重写/迁移问题（“我们要不要把这个拆出去？”）——规划绞杀者路径
每次变更都受结构掣肘——需要重新审视架构决策

When NOT to use

不适用场景

Mechanical, behavior-preserving moves →
```
refactor-it
```
"Is this overcomplicated?" audit →
```
kiss
```
Repo split/combine/monorepo moves on GitHub →
```
repos
```
Agent/LLM system design →
```
agents design
```
External library/API research →
```
research-it
```
(feeds this skill)
One bug or feature with clear placement → skip to
```
issues
```
/
```
fix-it
```

机械的、保持行为不变的调整 →
```
refactor-it
```
“这是不是过于复杂了？”类审计 →
```
kiss
```
GitHub上的仓库拆分/合并/单体仓库迁移 →
```
repos
```
Agent/LLM系统设计 →
```
agents design
```
外部库/API调研 →
```
research-it
```
（为本技能提供输入）
位置明确的单个bug或功能 → 直接使用
```
issues
```
/
```
fix-it
```

Workflow

工作流程

Frame the decision
- Name the bet in one sentence: what must be decided (shape, boundary, placement, data flow, dependency direction) and what breaks if it stays undecided.
- Name the quality regime (A/B/C per repo guidance) — it sets the proof bar for the plan.
Survey the codebase
- Entry points, modules, dependency direction, data flow, deploy units; existing
```
AGENTS.md
```
  ,
```
docs/
```
  , ADRs, runbooks.
- Check
```
research-it
```
  output if a prior investigation exists. Note the seams that already exist — good architecture usually amplifies them.
- Fan out per-area reads to parallel read-only subagents (fast tier) when the codebase is large; a top-tier adversarial subagent steelmans the option you did not pick before the ADR is written; verify each child's result before consolidating.
Propose options with tradeoffs
- 2–3 options max, KISS default first (simplest thing that could work — Gall's Law).
- For each: what it makes easy, what it makes hard, blast radius, migration cost.
- For new concerns, answer "what runs where" (browser / edge / API / worker / data / SaaS) before picking hosts.
Decide and record
- Recommend one option; state the reversible/irreversible call explicitly.
- Reversible bets proceed. For irreversible bets (data model, public API, placement), write the ADR draft and ask one structured question:
```
proceed with <option> / choose <alt> / stop
```
  . If the user's request already named the option, proceed.
- Write a short ADR (context, decision, consequences) in the repo's ADR location — create
```
docs/adr/
```
  if none exists.
- Flag future decision points instead of over-designing them now.
Plan the slice
- Tracer-bullet steps: thinnest end-to-end path first, then deepen.
- Mark which steps are
```
refactor-it
```
  (behavior-preserving), feature work (
```
issues
```
  ), or new unit scaffolding.
- Strangler fig over big bang: new grows around old behind a seam; old retires by evidence.
Hand off
- Next:
```
issues create
```
  for the slice tickets,
```
refactor-it
```
  for structural prep,
```
research-it
```
  for open technical questions,
```
kiss
```
  to pressure-test the plan.

明确决策范围
- 用一句话说明架构决策：必须决定什么（形态、边界、归属、数据流、依赖方向），以及如果迟迟不决定会出什么问题。
- 明确质量等级（根据仓库规范分为A/B/C级）——它决定了计划的证明标准。
调研代码库
- 入口点、模块、依赖方向、数据流、部署单元；现有
```
AGENTS.md
```
  、
```
docs/
```
  目录、ADR、运行手册。
- 如果之前有过调研，检查
```
research-it
```
  的输出。留意已有的接缝——好的架构通常会放大这些接缝的作用。
- 当代码库很大时，将各领域的读取工作分发给并行的只读subagents（快速层级）；在编写ADR之前，由顶级对抗性subagent为你未选择的方案做钢人论证；在整合结果前验证每个子代理的产出。
提出带权衡的备选方案
- 最多2-3个选项，默认优先考虑KISS方案（能运行的最简单方案——Gall's Law）。
- 每个方案说明：它让什么变容易、让什么变困难、影响范围、迁移成本。
- 对于新的功能点，在选择宿主之前先回答“在哪里运行”的问题（浏览器 / 边缘节点 / API / 工作进程 / 数据层 / SaaS）。
决策并记录
- 推荐一个方案；明确说明该决策是可逆的还是不可逆的。
- 可逆决策可以直接推进。对于不可逆决策（数据模型、公共API、归属），编写ADR草稿并提出一个结构化问题：
```
proceed with <option> / choose <alt> / stop
```
  。如果用户的请求已经指定了方案，则直接推进。
- 在仓库的ADR存放位置编写简短的ADR（背景、决策、后果）——如果不存在则创建
```
docs/adr/
```
  目录。
- 标记未来的决策点，而不是现在就过度设计。
规划落地切片
- tracer-bullet步骤：先实现最薄的端到端路径，再逐步深化。
- 标记哪些步骤属于
```
refactor-it
```
  （保持行为不变）、功能开发（
```
issues
```
  ）或新单元脚手架搭建。
- 优先采用绞杀者模式而非大爆炸式重写：新系统在接缝处围绕旧系统生长；旧系统根据实际情况逐步退役。
交接
- 下一步：用
```
issues create
```
  创建切片工单，用
```
refactor-it
```
  做结构准备，用
```
research-it
```
  解决未决的技术问题，用
```
kiss
```
  对方案进行压力测试。

Guardrails

护栏规则

Do not scaffold the full system in one go; land the thinnest working slice.
Reversible bets proceed. Irreversible ones (data model, public API, placement) need the ADR draft; ask a structured question before committing only if the user's request did not already name the option.
If the codebase already answers the question, don't invent a second architecture — follow the existing pattern or propose migrating to it explicitly.
Simplification is a valid outcome: sometimes the right architecture is deleting a layer (
```
kiss
```
), not adding one.
Done when: ADR written (or confirmed unnecessary), slice plan with a tracer bullet step, open technical questions named for
```
research-it
```
.

不要一次性搭建完整系统的脚手架；先落地最薄的可工作切片。
可逆决策直接推进。不可逆决策（数据模型、公共API、归属）需要ADR草稿；只有当用户的请求未指定方案时，才需要在提交前提出结构化问题。
如果代码库已经能回答这个问题，不要发明另一套架构——遵循现有模式，或明确提出迁移到现有模式的方案。
简化也是有效的结果：有时候正确的架构是删掉一层（
```
kiss
```
），而不是增加一层。
完成条件：ADR已编写（或确认不需要）、包含tracer-bullet步骤的切片计划、已明确需要
```
research-it
```
解决的未决技术问题。

Output

输出格式

markdown

**Decision**
- <the bet, one sentence>

**Options considered**
1. <option> — <tradeoff>
2. <option> — <tradeoff>

**Chosen**: <option> — <why now>

**Recorded**
- ADR: <path or "none needed">

**Slice plan**
1. ...

**Blocked on me**
(irreversible-bet confirmation if not yet resolved, else "none")

**Changed**
(ADR written to `<path>`, else "nothing")

**Found**
Decision, chosen option, rationale. Next: `issues create <slice tickets>` / `refactor-it <structural prep>` / `research-it <open question>`.

markdown

**Decision**
- <the bet, one sentence>

**Options considered**
1. <option> — <tradeoff>
2. <option> — <tradeoff>

**Chosen**: <option> — <why now>

**Recorded**
- ADR: <path or "none needed">

**Slice plan**
1. ...

**Blocked on me**
(irreversible-bet confirmation if not yet resolved, else "none")

**Changed**
(ADR written to `<path>`, else "nothing")

**Found**
Decision, chosen option, rationale. Next: `issues create <slice tickets>` / `refactor-it <structural prep>` / `research-it <open question>`.

Grounding

理论基础

This skill's TTPs are grounded in current engineering baselines (DORA, GitHub Docs, Fowler/Beck, Google SRE & SWE book, OpenTelemetry, OWASP LLM / NIST AI RMF, Diátaxis — see handbook

sources.md

Deep modules behind small interfaces (Ousterhout); strangler fig over big-bang rewrite (Fowler); loosely coupled architecture for independent deployability (DORA); ADRs so wheels aren't reinvented; working simple systems precede complex ones (Gall).

Handbook card:

handbook/practices/architect-it.md

本技能的TTPs基于当前工程基准（DORA、GitHub Docs、Fowler/Beck、Google SRE & SWE书籍、OpenTelemetry、OWASP LLM / NIST AI RMF、Diátaxis——参见手册

sources.md

）。

小接口背后的深模块（Ousterhout）；优先绞杀者模式而非大爆炸式重写（Fowler）；支持独立部署的松耦合架构（DORA）；用ADR避免重复造轮子；简单可工作的系统优先于复杂系统（Gall）。

手册卡片：

handbook/practices/architect-it.md

。