architecture-principles

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Edit rule: each line is a principle with its reason and when it yields. Decisions go to the decision records, rules a check can hold go to the check, and a line is added only on a person's yes, after sharpening an existing line is ruled out.

A new need lands on a mechanism, concept and state owner that already exist — figure-out, define, do, task files, the logs, the Ticket — before it earns a new skill, setting, file, ledger or surface, and a named entry is at most a thin wrapper that routes and restates no rule — a second loop or record is a second place to drift and disagree, every added concept is one more thing each user learns, and a rule in a wrapper reaches only runs that start there. Yields when no existing owner can carry it without changing what it means, or when people reach for a name: then add only the wrapper.
Ship skills as the protocol, never the platform: no scheduler, hosting or host-bound runner; start from what the user already runs, use a host capability where it is offered and a plain path where it is not — infrastructure ties the project to one host and adds complexity each user carries. Yields to a coordinating skill, started by hand or by the user's own scheduler, when the alternative leaves users to build the machinery themselves.
A skill that inspects or reports stays blind to its caller's workflow and returns what it saw with hints that name an action on the thing inspected, never a step of the caller's workflow; each decision lives once, in the skill that holds the context to make it — the caller steers toward the hint, a fixed set alone cannot cover the unexpected, and a rule restated per caller drifts. No yield has been stated beyond the verdict itself, which stays fixed.
Every wait or loop a workflow can enter has a stated exit — done, a bounded retry, or a named person — reading the prose missed these: they surfaced as a landing that stalled for good and an escalation that fired every tick. No yield has been stated.

Before calling architecture work done, check it against these principles from a fresh start — a new session, or a reviewer who did not do the work. Fix what departs unless the person chose the departure, and check again only after a fix, until a check finds none. Name each departure kept, with the principle and why.

编辑规则：每一行都是一项原则，并说明其理由以及何时可以让步。决策归入 decision record，check 能够承载的规则归入 check；只有在获得某个人明确同意，并且确认无法通过完善现有条目来解决之后，才能新增一行。

新需求应先落到已有的机制、概念和 state owner——figure-out、define、do、task files、logs、Ticket——之后，才应新增 skill、setting、file、ledger 或 surface；任何命名的 entry 最多只是一个 thin wrapper，只负责路由，不重复陈述规则——第二个 loop 或 record 就是第二个可能发生偏离和分歧的地方；每增加一个概念，都会让每位用户多学习一样东西；而 wrapper 中的规则只能作用于从那里启动的 run。只有当现有 owner 无法在不改变需求含义的情况下承载它，或者人们确实需要一个名称时，本原则才让步：此时只新增 wrapper。
将 skill 作为 protocol 交付，而不要将其做成 platform：不要提供 scheduler、hosting 或与 host 绑定的 runner；从用户已经在运行的环境出发，host 提供 capability 时就使用它，未提供时则采用普通路径——infrastructure 会把项目绑定到特定 host，并增加每位用户都要承担的复杂度。当其他方案会让用户自行搭建相关 machinery 时，本原则可让位于一个 coordinating skill，该 skill 由人工启动，或由用户自己的 scheduler 启动。
用于检查或报告的 skill 应与 caller 的 workflow 保持隔离，并返回所见内容及 hints；这些 hints 只命名可对被检查对象执行的动作，绝不能包含 caller workflow 中的某个步骤；每项 decision 只存在于一处，即掌握作出该 decision 所需 context 的 skill 中——caller 可依照 hint 调整方向；单靠固定集合无法覆盖意外情况，而针对每个 caller 重述规则会产生偏离。除固定的 verdict 外，本原则未规定其他例外。
workflow 可能进入的每一种 wait 或 loop，都必须有明确写出的 exit——完成、有界重试或指定的人——只阅读 prose 会漏掉这些情况：它们可能表现为一个最终卡住的 landing，以及每个 tick 都会触发的 escalation。本原则未规定任何例外。

在宣布 architecture 工作完成之前，应从全新起点——一个新 session，或一位未参与该工作的 reviewer——出发，根据这些原则进行检查。除非负责人有意选择偏离，否则应修复所有偏离之处；并且只在完成一次修复后再次检查，持续到一个检查不再发现问题为止。记录每一项保留的偏离，并说明其对应的原则以及保留偏离的原因。