Back to Details

architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Architecture

架构

Lock how services, modules, endpoints, schemas, and stores talk to each other. Concrete at system boundaries, schematic inside. Types, call stacks, and file layout belong to 
/program-design
.
锁定服务、模块、端点、模式和存储之间的交互方式。系统边界处需具体化，内部采用示意性设计。类型、调用栈和文件布局属于
/program-design
范畴。

Core contract

核心契约

  • One capability or epic — work that will become multiple tickets, or one ticket that still needs new seams.
  • The spec (if any) is the behavioural source of truth. This document is the recommended system shape.
  • Inspect the repository. Prefer evidence over generic best practices.
  • Read-only: inspect code, docs, tests, and history; do not modify production code.
  • Stop after the architecture unless the user asks to continue.
Do not include: per-function signatures, call stacks, file-change maps, implementation sequences, or pattern dumps with existing/proposed bodies. Those are 
/program-design
.
Do not restate the spec. Link or summarise; 
/to-spec
owns product narrative.
  • 聚焦一项功能或Epic需求——这类工作会拆分为多个任务单，或是仍需新增衔接点的单个任务单。
  • 若有规格说明（spec），则其为行为的唯一可信来源。本文档是推荐的系统形态。
  • 检查代码仓库。优先依据实际证据而非通用最佳实践。
  • 只读操作：检查代码、文档、测试及历史记录；不得修改生产代码。
  • 完成架构设计后即停止，除非用户要求继续。
请勿包含：函数级签名、调用栈、文件变更映射、实现序列，或带有现有/拟议代码体的模式汇总。这些内容属于
/program-design
范畴。
请勿重述规格说明。可链接或总结；产品叙事由
/to-spec
负责。

When to use / skip

使用时机 / 跳过时机

text
wayfinder → grill-with-docs → /to-spec
                 ↓
           /architecture     # this skill — new seams / multi-ticket
                 ↓
           /program-design   # code shape, when taste matters
                 ↓
           /to-tickets → /implement
SituationSkill
Idea or trade-offs still open
/grilling
or 
/grill-with-docs
first
External API/vendor semantics unclear
/research
first
Module interface is the unknown
/design-an-interface
, fold the result in
State model or UI feel uncertain
/prototype
first
New seams, naming, or multi-ticket shape
/architecture
Architecture is obvious; code taste is notSkip to 
/program-design
Obvious single-ticket, existing patternsSkip to 
/implement
text
wayfinder → grill-with-docs → /to-spec
                 ↓
           /architecture     # 本技能 — 新增衔接点 / 多任务单场景
                 ↓
           /program-design   # 代码形态，注重风格时使用
                 ↓
           /to-tickets → /implement
场景技能
想法或权衡仍未确定先使用
/grilling
或
/grill-with-docs
外部API/供应商语义不明确先使用
/research
模块接口未知使用
/design-an-interface
，并将结果整合进来
状态模型或UI体验不确定先使用
/prototype
需要新增衔接点、命名或多任务单形态
/architecture
架构显而易见；代码风格存疑直接跳至
/program-design
单个任务单明确，且有现有模式可循直接跳至
/implement

Steps

步骤

1. Establish the capability

1. 明确功能范围

Read the spec, conversation, ADRs, domain glossary (
CONTEXT.md
), and project instructions.
Ready when 
/to-tickets
could slice this into tracer bullets. If the input is already a small ticket on an established pattern, recommend skipping this skill.
Record outcome, in-scope behaviour, non-goals, and constraints. Recommend defaults for non-blocking ambiguity. Stop for the user only when a decision changes behaviour, public APIs, data ownership, security, persistence, compatibility, system boundaries, dependencies, or scope.
This step is complete when outcome, non-goals, and blocking ambiguity are explicit.
阅读规格说明、对话记录、ADRs（架构决策记录）、领域术语表（
CONTEXT.md
）及项目说明。
当
/to-tickets
可将其拆分为tracer bullets（最小可验证功能单元）时，此步骤就绪。若输入内容已是基于既定模式的小型任务单，建议跳过本技能。
记录成果、范围内的行为、非目标及约束条件。针对非阻塞性歧义推荐默认方案。仅当某项决策会改变行为、公共API、数据所有权、安全性、持久性、兼容性、系统边界、依赖关系或范围时，才需暂停等待用户确认。
当成果、非目标及阻塞性歧义均明确后，此步骤完成。

2. Inspect the repository

2. 检查代码仓库

Trace the current path through entry, domain logic, persistence, integrations, and tests. Note existing modules and conventions to reuse. Conflicting patterns: pick one, with evidence.
This step is complete when every proposed seam has an existing counterpart or is named as new and justified.
追踪当前从入口、领域逻辑、持久化、集成到测试的路径。记录可复用的现有模块及约定。若存在冲突模式：选取其中一种，并提供证据支撑。
当每个拟议的衔接点都有对应现有模块，或是已命名为新模块并给出合理依据后，此步骤完成。

3. Design the end state

3. 设计最终状态

Show before/after at module and system boundaries (
mermaid
flowchart or sequence). Not class-level.
Define coarse structure only:
  • Packages, modules, or top-level folders — not every file.
  • Public contracts: endpoints, schemas, events, provider ids.
  • Runtime flow from entry to observable result, at those boundaries.
When integrating external systems, add a short Verified basis citing official docs. Use 
/research
for the long form; distill here.
Prefer, in order:
  1. Existing code over new code.
  2. Local code over a shared abstraction.
  3. Established repository patterns over new patterns.
  4. Explicit code over generic frameworks.
  5. Narrow MVP surface over speculative API roadmaps.
  6. One clear execution path over interchangeable layers.
New interfaces, factories, adapters, registries, or shared utilities require a current problem with multiple immediate call sites.
This step is complete when a reviewer can see the proposed system shape and how work flows through it.
展示模块及系统边界处的前后对比（使用mermaid流程图或序列图）。无需展示类级细节。
仅定义粗略结构：
  • 包、模块或顶级文件夹——无需细化到每个文件。
  • 公共契约：端点、模式、事件、提供者ID。
  • 从入口到可观测结果的运行时流程（基于上述边界）。
集成外部系统时，添加简短的验证依据，引用官方文档。详细内容使用
/research
处理；在此处提炼核心信息。
优先遵循以下顺序：
  1. 现有代码优先于新增代码。
  2. 本地代码优先于共享抽象。
  3. 仓库既定模式优先于新模式。
  4. 显式代码优先于通用框架。
  5. 精简的MVP（最小可行产品）范围优先于推测性API路线图。
  6. 清晰的单一执行路径优先于可互换层。
新增接口、工厂、适配器、注册器或共享工具时，需存在当前有多个直接调用方的问题场景。
当评审人员能够看到拟议的系统形态及工作流时，此步骤完成。

4. Propose tracer-bullet slices

4. 拟议Tracer Bullet拆分方案

Recommend how 
/to-tickets
should break the capability. For each slice:
  • Title
  • Delivers — end-to-end behaviour when this slice merges
  • Blocked by — other slices, or 
    None
  • Architecture anchor — sections or contracts this slice implements
Each slice must be independently demoable or verifiable. Merge slices that only make sense together. Do not attach file lists or test commands.
This step is complete when the breakdown covers the capability and follows tracer-bullet rules.
建议
/to-tickets
如何拆分该功能。每个拆分项需包含：
  • 标题
  • 交付内容——该拆分项合并后可实现的端到端行为
  • 依赖项——其他拆分项，或
    None
  • 架构锚点——该拆分项实现的架构部分或契约
每个拆分项必须可独立演示或验证。合并那些仅组合在一起才有意义的拆分项。无需附加文件列表或测试命令。
当拆分方案覆盖整个功能且遵循tracer bullet规则时，此步骤完成。

5. Resolve architecture questions

5. 解决架构问题

Record material decisions:
  • Question
  • Chosen: recommendation and rationale
  • Options not chosen: and why
Grill before writing when decisions are still unsettled. Include migration, security, performance, observability, and rollback only when the change creates them.
This step is complete when no blocking decision remains implicit.
记录关键决策：
  • 问题
  • 选定方案：建议及理由
  • 未选方案：及未选原因
决策未确定时，先进行讨论再记录。仅当变更引发相关问题时，才需包含迁移、安全、性能、可观测性及回滚内容。
当所有阻塞性决策均已明确后，此步骤完成。

6. Write the document

6. 撰写文档

Capture git metadata for the frontmatter (
branch
, 
sha
).
Write to the repository's established work-artifact location. If none exists, use 
docs/agents/architecture/<short-slug>.md
.
Follow 
references/architecture-template.md
. Before handing off, verify:
  • One capability or epic, not a file tweak.
  • Before/after architecture is visible at module boundaries.
  • Proposed slices are tracer bullets with blocking edges.
  • Public contracts only — no call stacks, function bodies, or file maps.
  • No blocking decision remains implicit.
在文档开头添加git元数据（
branch
、
sha
）。
将文档写入仓库既定的工作产物位置。若不存在该位置，使用
docs/agents/architecture/<short-slug>.md
。
遵循
references/architecture-template.md
模板。移交前需验证：
  • 聚焦一项功能或Epic需求，而非文件微调。
  • 模块边界处的前后架构可见。
  • 拟议拆分项为符合规则的tracer bullets，并带有依赖关系。
  • 仅包含公共契约——无调用栈、函数体或文件映射。
  • 无阻塞性决策未明确。

Shortened form

简化版本

For a bounded capability that is one tracer-bullet ticket but still needs architectural approval:
  • Frontmatter, summary, current / desired state, not doing
  • One architecture diagram
  • Public contracts
  • Resolved decisions (if any)
  • Approval gate
对于属于单个tracer bullet任务单但仍需架构审批的限定性功能：
  • 文档头、摘要、当前/预期状态、排除范围
  • 一张架构图
  • 公共契约
  • 已解决的决策（若有）
  • 审批节点

Handoff

移交

Report:
  1. Path to the architecture document.
  2. Concise summary of the recommended system shape.
  3. Proposed slice count and frontier slice.
  4. Blocking decisions, or 
    None
    .
  5. Confirmation that production code was not modified.
  6. Next step:
text
/program-design using <architecture-path>
If code shape is obvious and the user will slice next:
text
/to-tickets using <architecture-path>
报告内容：
  1. 架构文档的路径。
  2. 推荐系统形态的简洁摘要。
  3. 拟议拆分数量及首个拆分项。
  4. 阻塞性决策，或
    None
    。
  5. 确认未修改生产代码。
  6. 下一步：
text
/program-design using <architecture-path>
若代码形态显而易见，且用户接下来要进行拆分：
text
/to-tickets using <architecture-path>