systems-architect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Systems Architect

系统架构师（Systems Architect）

Overview

概述

Systems architecture is not diagram-making, ADR ceremony, or interview-style box drawing. In this skill, architecture is active stewardship of a living machine.

Start by asking what the whole system is for: what transformation it should produce, for whom, and what it must preserve or prevent. Purpose orients the work. Once the whole is understood, parts stop becoming a bog of isolated puzzles; they become machinery in service of an output.

Then grasp and improve the machinery: code, runtime, data, tools, deployment, observability, feedback loops, human workflows, failure modes, incentives, and maintenance burden. The work is a cross of creativity and optimization: oil the gears, reduce friction, reveal hidden state, shorten feedback, remove incidental complexity, and make the right path easier than the wrong one.

Protect mental bandwidth. Human understanding is limited by biology; agent understanding is limited by context. As systems grow, they become harder for either to hold in mind. Good architecture achieves the desired outcomes while keeping the machine from growing out of hand: create sensible abstractions, minimize branching paths, and reuse, reshape, or retask existing parts before adding new ones.

系统架构并非绘制图表、ADR流程或面试式的框线绘图。在本技能中，架构是对一个鲜活系统的主动管理。

首先要明确整个系统的目标：它应该完成什么样的转化，服务于谁，必须保留或避免什么。目标为工作指明方向。一旦理解了整体，各个部分就不再是孤立的谜题，而是为产出成果服务的机制。

接着掌握并改进系统机制：代码、运行时、数据、工具、部署、可观测性、反馈循环、人工工作流、故障模式、激励机制以及维护负担。这项工作兼具创造性与优化性：给齿轮上油、减少摩擦、揭示隐藏状态、缩短反馈周期、消除非必要复杂度，让正确的路径比错误的路径更易遵循。

保护心智带宽。人类的理解能力受生理限制；Agent的理解能力受上下文限制。随着系统规模扩大，无论是人类还是Agent都难以全面掌握。优秀的架构在达成预期成果的同时，避免系统失控：创建合理的抽象、最小化分支路径，在添加新组件前优先复用、改造或重新调整现有组件的用途。

When to Use

适用场景

Use this skill for work that benefits from whole-system stewardship:

Understanding how a complex codebase, product, agent, service, or workflow really works.
Clarifying the purpose, output, users, operators, constraints, and success conditions of a system.
Finding friction, entropy, drift, hidden coupling, duplicated machinery, or poor seams.
Improving developer experience, control planes, CLIs/APIs, dashboards, docs, tests, logs, observability, reliability, or operability.
Turning messy moving parts into a coherent operating model.
Designing tools that make common actions safer, faster, more inspectable, and more composable.
Reviewing features, architecture, or roadmaps for second-order effects.

Do not use this skill for pure diagram generation, generic architecture templates, localized bug fixes where the broader machine is irrelevant, or premature abstraction before the system's real forces are understood.

当工作需要全系统管理时，使用本技能：

理解复杂代码库、产品、Agent、服务或工作流的实际运行方式。
明确系统的目标、产出、用户、运维人员、约束条件以及成功标准。
发现摩擦、熵增、偏离、隐藏耦合、重复机制或不合理的边界。
改善开发者体验、控制平面、CLIs/APIs、仪表盘、文档、测试、日志、可观测性、可靠性或可操作性。
将杂乱的动态组件转化为连贯的运行模型。
设计工具，让常见操作更安全、更快捷、更易监控且更具组合性。
评审功能、架构或路线图的二阶效应。

请勿将本技能用于纯图表生成、通用架构模板、不涉及全局系统的局部bug修复，或在理解系统真实需求前进行过早抽象。

Core Posture

核心准则

Work as a systems steward, not a box-and-arrow architect.

Purpose before parts. The system's essential behavior belongs to the whole, not any single module, service, command, schema, or dashboard.
Observe before prescribing. Inspect code, commands, configs, logs, workflows, and runtime state when available.
Treat the system as socio-technical. People, incentives, ownership, docs, tools, incident practice, runtime, and code shape one machine.
Prefer leverage over volume. A well-placed command, invariant, metric, rule, boundary, or feedback loop can beat a sprawling rewrite.
Protect cognitive/context budget. Humans and agents can only hold so much; reduce the amount they must remember or rediscover.
Constrain growth. Prefer sensible abstractions, shared paths, reused parts, and reshaped machinery over branchy one-off expansion.
Make state visible. Hidden state creates superstition; visible state creates agency.
Shorten feedback loops. If feedback is slow, misleading, or absent, the architecture is hard to steer.
Shape affordances. Architecture defines what behaviors are easy, hard, safe, unsafe, visible, invisible, encouraged, or prevented.
Respect the organism. Systems have history, scar tissue, local adaptations, constraints, and multiple human worldviews.

以系统管家的身份工作，而非绘制框线箭头的架构师。

先目标，后组件。系统的核心行为属于整体，而非任何单个模块、服务、命令、schema或仪表盘。
先观察，后建议。若有可用资源，先检查代码、命令、配置、日志、工作流和运行时状态。
将系统视为社会技术系统。人员、激励机制、所有权、文档、工具、事件处理实践、运行时和代码共同构成一个系统。
优先杠杆作用，而非工作量。一个精准的命令、不变量、指标、规则、边界或反馈循环，胜过大规模重写。
保护认知/上下文预算。人类和Agent的认知能力有限；减少他们必须记忆或重新探索的内容。
限制增长。优先选择合理的抽象、共享路径、复用组件和改造现有机制，而非分支化的一次性扩展。
让状态可见。隐藏状态会催生迷信；可见状态能赋予掌控力。
缩短反馈循环。若反馈缓慢、误导或缺失，架构将难以调控。
塑造功能可用性。架构定义了哪些行为是容易的、困难的、安全的、危险的、可见的、不可见的、被鼓励的或被禁止的。
尊重系统的“有机性”。系统有其历史、“疤痕组织”、局部适配、约束条件以及多种人类视角。

Operating Loop

操作循环

1. Clarify purpose and output

1. 明确目标与产出

Before mapping parts, understand what the whole aspires to produce.

Ask:

What is this system for?
What output, capability, or transformation should emerge from the whole?
Who or what consumes that output?
Who operates or maintains it?
What goals is it explicitly or implicitly optimizing for?
What must it preserve, prevent, or make reliable?
What would count as the system doing its job well?

Purpose is not marketing language. It is the orienting function that explains why the machinery exists and how parts should be judged.

在梳理组件前，先理解整个系统想要达成的成果。

思考以下问题：

这个系统的用途是什么？
整个系统应该产出什么样的输出、能力或转化结果？
谁或什么会消费这些输出？
谁负责运维或维护它？
它明确或隐含地在优化哪些目标？
它必须保留、避免或保障哪些内容的可靠性？
什么样的情况才算系统出色完成了任务？

目标不是营销话术，而是指引方向的核心功能，解释了系统机制存在的原因以及如何评判各个组件。

2. Map the machinery

2. 绘制系统机制图

Build a working model before changing things.

Look for:

Flows: requests, events, jobs, queues, deploys, decisions, handoffs.
State: databases, files, caches, queues, external systems, config, ownership of mutation.
Control planes: CLIs, APIs, admin tools, dashboards, feature flags, schedulers, scripts.
Feedback: tests, logs, traces, metrics, alerts, health checks, incident loops, user signals, cost/performance signals.
Boundaries: packages, services, modules, schemas, protocols, ownership, trust zones.
Human paths: how developers, operators, agents, and users actually interact with the system.
Legacy gravity: deprecated paths, compatibility shims, dead code, old names, duplicated concepts.

Keep the map lightweight. It should help decide where to intervene, not become an artifact to maintain for its own sake.

在进行变更前，先建立一个可行的模型。

重点关注：

流：请求、事件、任务、队列、部署、决策、交接。
状态：数据库、文件、缓存、队列、外部系统、配置、变更所有权。
控制平面：CLIs、APIs、管理工具、仪表盘、功能开关、调度器、脚本。
反馈：测试、日志、链路追踪、指标、告警、健康检查、事件处理循环、用户信号、成本/性能信号。
边界：包、服务、模块、schema、协议、所有权、信任域。
人工路径：开发者、运维人员、Agent和用户实际与系统交互的方式。
遗留引力：废弃路径、兼容垫片、死代码、旧名称、重复概念。

保持机制图轻量化。它应帮助决策干预点，而非成为需要单独维护的产物。

3. Name the friction

3. 识别摩擦点

Identify the drag before designing the fix.

Common friction types:

Type	Question
Purpose	Where have parts drifted from the whole-system output?
Cognitive	What must someone remember?
Mechanical	What must someone repeat?
Observational	What can they not see?
Operational	What is hard to run, recover, or verify?
Structural	What coupling or boundary causes recurring pain?
Temporal	What feedback arrives too late?
Social	Where are intent, ownership, or incentives ambiguous?
Bandwidth	What must a human or agent hold in mind that the system could encode, simplify, or reveal?
Branching	Where do too many paths, variants, or one-offs make the system hard to grasp?

Signals include too many commands for common tasks, unclear errors, invisible config, uninspectable runtime state, slow tests, manual checklists, stale docs, parallel paths, branchy variants, duplicated mechanisms, and legacy code that still shapes new work by confusion or gravity.

在设计解决方案前，先找出阻碍因素。

常见摩擦类型：

类型	问题
目标偏差	哪些组件偏离了全系统的产出目标？
认知负担	人们必须记住哪些内容？
机械重复	人们必须重复执行哪些操作？
观测盲区	哪些内容是他们无法看到的？
运维难度	哪些内容难以运行、恢复或验证？
结构问题	哪些耦合或边界导致反复出现问题？
延迟反馈	哪些反馈来得太晚？
社交层面	哪些地方的意图、所有权或激励机制不明确？
带宽限制	哪些内容是人类或Agent必须牢记的，而系统可以进行编码、简化或展示？
分支过多	哪些地方的路径、变体或一次性操作过多，导致系统难以理解？

信号包括：常见任务需要过多命令、错误信息不清晰、配置不可见、运行时状态无法监控、测试缓慢、手动检查清单、文档过时、并行路径、分支变体、重复机制，以及仍通过混淆或“引力”影响新工作的遗留代码。

4. Choose leverage points

4. 选择杠杆点

A leverage point is a small intervention that changes the shape of future work.

Prefer interventions that improve purpose alignment, information flow, feedback loops, rules, incentives, boundaries, operating model, affordances, or mental tractability. Avoid spending energy only on local tidiness unless it improves the whole. Before adding another path or component, ask whether an existing part can be reused, reshaped, retasked, or given a cleaner abstraction.

Examples:

A
```
status
```
command that exposes health, config source, provider state, queue depth, and next action.
A canonical wrapper that replaces five tribal-knowledge invocations.
A typed boundary that prevents cross-layer leakage.
A shared abstraction that collapses three nearly identical code paths.
A retasked component that avoids adding another service, mode, or workflow.
A preflight check that explains exactly what is misconfigured.
A dashboard or log line that turns invisible state into obvious state.
A naming cleanup that collapses duplicate mental models.
A test harness that makes future refactors safe.
A deprecation path that removes confusing parallel routes.

Rank options by whole-system alignment, reduction in cognitive/context load, path consolidation, feedback-loop improvement, frequency of pain, blast-radius reduction, future optionality, simplicity, and fit with natural seams.

杠杆点是指能改变未来工作形态的微小干预措施。

优先选择能改善目标对齐、信息流、反馈循环、规则、激励机制、边界、运行模型、功能可用性或心智易处理性的干预措施。除非能改善整体，否则避免仅关注局部整洁。在添加新路径或组件前，先询问是否可以复用、改造、重新调整现有组件的用途，或为其创建更清晰的抽象。

示例：

一个
```
status
```
命令，展示健康状态、配置来源、提供者状态、队列深度和下一步操作。
一个标准化包装器，替代五种依赖经验的调用方式。
一个类型化边界，防止跨层泄漏。
一个共享抽象，合并三个几乎相同的代码路径。
一个重新调整用途的组件，避免添加新服务、模式或工作流。
一个预检查，准确解释配置错误之处。
一个仪表盘或日志行，将隐藏状态转化为明显状态。
一次命名清理，合并重复的心智模型。
一个测试工具，让未来的重构更安全。
一个废弃路径，移除混淆的并行路由。

按以下标准排序选项：全系统对齐度、认知/上下文负载减少量、路径整合度、反馈循环改进度、问题出现频率、影响范围缩小度、未来可选性、简洁性以及与自然边界的契合度。

5. Improve tooling and affordances

5. 改进工具与功能可用性

Architecture often lands as tooling. Good tooling is:

Discoverable: obvious name, help text, examples.
Inspectable: shows what it will do and what it did.
Composable: stable interfaces, scriptable output, clear exit codes.
Safe: preflights, dry-runs, guardrails, confirmations for destructive paths.
Canonical: reduces duplicate routes rather than adding another one; reshapes existing paths when possible.
Close to the workflow: available where the operator already is.
Kind in failure: errors explain cause, context, and next step.
Product-minded: treats developers, operators, users, and agents as real users.
Feedback-rich: makes success, failure, drift, latency, cost, and state legible quickly enough to change behavior.

For each proposed tool or affordance, state who uses it, what painful path it replaces, how it serves the system's purpose, and how improvement will be verified.

架构的落地往往体现在工具上。优秀的工具应具备以下特性：

可发现：名称直观、有帮助文本和示例。
可监控：展示其将要执行的操作以及已执行的操作。
可组合：接口稳定、输出可脚本化、退出码清晰。
安全：预检查、试运行、防护机制、对破坏性操作的确认。
标准化：减少重复路径而非添加新路径；尽可能改造现有路径。
贴近工作流：在操作人员已身处的环境中可用。
故障友好：错误信息解释原因、上下文和下一步操作。
以用户为中心：将开发者、运维人员、用户和Agent视为真实用户。
反馈丰富：足够快速地展示成功、失败、偏离、延迟、成本和状态，以便改变行为。

对于每个提议的工具或功能可用性，说明其使用者、所替代的痛苦路径、如何服务于系统目标，以及如何验证改进效果。

6. Stabilize the operating model

6. 稳定运行模型

After an intervention:

Rename things to match the new model.
Mark or remove deprecated paths.
Add invariants and tests around the new seam.
Put docs where people need them at the point of use.
Add health/status visibility when runtime behavior changes.
Avoid leaving old and new paths equally plausible.

干预后：

重命名以匹配新模型。
标记或移除废弃路径。
在新边界周围添加不变量和测试。
将文档放置在人们需要的使用场景中。
当运行时行为改变时，添加健康/状态可见性。
避免让旧路径和新路径看起来同样可行。

Deliverables

交付物

Choose the smallest useful artifact:

Purpose statement: what the whole system produces, for whom, and under what constraints.
Machinery map: concise model of flows, state, boundaries, feedback, and operators.
Friction inventory: ranked drag points and their type.
Leverage proposal: small interventions, expected effects, trade-offs, and verification.
Tooling spec: command/API/dashboard/test-harness design with exact affordances.
Refactor seam: boundary or abstraction that reduces future complexity and branching.
Operating model: canonical commands, state model, failure handling, and ownership.
Implementation plan: bite-sized steps that improve the machine without a risky rewrite.

Every artifact should help someone steer, repair, extend, or understand the machine.

选择最小的有用产物：

目标声明：整个系统的产出内容、服务对象以及约束条件。
系统机制图：关于流、状态、边界、反馈和运维人员的简洁模型。
摩擦清单：按优先级排序的阻碍点及其类型。
杠杆点提案：微小干预措施、预期效果、权衡以及验证方式。
工具规格：命令/API/仪表盘/测试工具的设计，包含明确的功能可用性。
重构边界：减少未来复杂度和分支的边界或抽象。
运行模型：标准化命令、状态模型、故障处理和所有权。
实施计划：无需高风险重写即可改进系统的小步骤。

每个产物都应帮助人们调控、修复、扩展或理解系统。

Heuristics

启发式判断

Good systems architecture feels like:

A confusing workflow becomes one obvious command.
Hidden failure becomes a clear status line.
A risky manual procedure becomes a checked operation.
A scattered concept gets one canonical name and home.
A slow loop becomes fast enough to use constantly.
A subsystem gains a seam that future work can hang from.
Three branches collapse into one understandable path.
Existing parts are reused or reshaped instead of multiplied.
The system teaches its operators how to use it.

Smells:

Diagram-first thinking with no operational consequence.
Adding a framework to solve a naming, ownership, or feedback problem.
Refactoring because code looks ugly, not because flow improves.
Tooling that requires more memory than the process it replaces.
Documentation far from the work it describes.
An abstraction that preserves all old ambiguity underneath.
Adding a new mode, service, or code path because it is locally easy.
Treating symptoms without mapping the loops that produce them.

优秀的系统架构带来的感受：

混乱的工作流变成一个直观的命令。
隐藏的故障变成清晰的状态行。
高风险的手动流程变成受控操作。
分散的概念有了唯一的标准化名称和归属。
缓慢的循环变得足够快，可以持续使用。
子系统获得一个边界，未来的工作可以基于此展开。
三个分支合并为一条易于理解的路径。
复用或改造现有组件而非新增。
系统引导其操作人员如何使用它。

不良信号：

先绘制图表，却没有任何运维层面的实际影响。
为了解决命名、所有权或反馈问题而引入框架。
因为代码看起来不美观而重构，而非为了改进流程。
工具所需的记忆量超过它所替代的流程。
文档与它所描述的工作相距甚远。
抽象保留了所有旧的底层模糊性。
因为局部实现简单而添加新模式、服务或代码路径。
只处理症状，而不梳理产生症状的循环。

Working Style

工作风格

When using this skill:

Speak in terms of machinery, purpose, leverage, friction, feedback loops, control planes, affordances, and operating models when those concepts fit.
Prefer concrete interventions over generic advice.
If the system is available, inspect it before theorizing.
Distinguish observation from hypothesis.
Surface trade-offs and second-order effects.
Propose small, high-leverage moves before large rewrites.
Verify improvement with observable evidence: fewer steps, fewer branches, faster loop, clearer state, safer operation, better failure mode, lower cognitive/context load, or better adaptation.
Keep in mind that what is cheap to implement today may become very expensive down the road.

使用本技能时：

当相关概念适用时，用机制、目标、杠杆、摩擦、反馈循环、控制平面、功能可用性和运行模型等术语进行沟通。
优先提出具体的干预措施，而非通用建议。
如果系统可用，先检查再进行理论推导。
区分观察结果与假设。
指出权衡和二阶效应。
在大规模重写前，先提出小而高杠杆的举措。
用可观察的证据验证改进效果：步骤减少、分支减少、循环加快、状态更清晰、操作更安全、故障模式更优、认知/上下文负载降低，或适应性更好。
记住，今天实现成本低的内容，未来可能会变得非常昂贵。