keel

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Keel

Keel

Use keel for load-bearing facts, transitions, contracts, and accountability. Resolve repository-declared instructions, records, contracts, entry paths, and guards before analysis; use local terms. Conflicting, stale, or missing sources or precedence are findings.
Separate exploration from closure. In greenfield work, treat user goals, external constraints, and provenance-bearing domain inputs as evidence, not inherited architecture. Propose minimal options, label assumptions, and leave decision-changing unknowns open.
使用Keel处理核心负载相关的事实、过渡流程、契约以及问责机制。在分析前先明确仓库中声明的指令、记录、契约、入口路径与防护措施;使用本地术语。若存在冲突、过时或缺失的来源或优先级,均视为待解决问题。
将探索阶段与收尾阶段分离。在全新项目(greenfield)中,将用户目标、外部约束以及带有溯源信息的领域输入视为证据,而非继承的架构。提出最简方案选项,标注假设条件,保留可能改变决策的未知项。

Composition

组成

  • Repository sources set facts, terms, precedence, and contract scope; Keel does not elevate every document.
  • Focused workflows own method, vocabulary, artifact, and completion. Product and UI design, domain modeling, documentation, and professional security, threat, privacy, compliance, legal, financial, or medical judgments remain theirs.
  • Compose Keel only when the same task establishes or changes a load-bearing authority, ownership, contract, cutover, or recovery decision. If those decisions are supplied and unchanged, skip Keel. Consume focused evidence and return only architecture implications.
  • Keel closes authority, accountability, compatibility, dependencies, recovery, guards, migration, and deletion; it does not choose architecture style, framework, stack, or product shape.
  • The user and host grant action authority. Execution workflows govern mutation, work preservation, test mechanics, and verification. Keel proves neither implementation nor production fitness.
A lens applies when its answer could change a load-bearing decision or closure. Proportionate means the lightest evidence or control that closes risk given impact, reversibility, and uncertainty. Resolve each applicable numbered lens; keep decision-changing unknowns open. Give an auditable skip reason when omission could hide risk.
  • 仓库来源定义事实、术语、优先级与契约范围;Keel不会将所有文档都视为核心依据。
  • 聚焦型工作流负责自身的方法、术语、工件与完成标准。产品与UI设计、领域建模、文档编写以及专业的安全、威胁、隐私、合规、法律、财务或医疗判断仍归对应团队负责。
  • 仅当同一任务涉及制定或变更核心负载相关的权限、所有权、契约、切换或恢复决策时,才需结合Keel方法。若这些决策已确定且无需变更,则无需使用Keel。只需参考聚焦型工作的证据,返回架构层面的影响即可。
  • Keel用于明确权限、问责、兼容性、依赖、恢复、防护、迁移与删除规则;它不负责选择架构风格、框架、技术栈或产品形态。
  • 用户与宿主拥有操作权限。执行工作流管控变更、工作留存、测试机制与验证流程。Keel不负责证明实现方案或生产环境的适用性。
当某个视角的答案可能改变核心负载决策或收尾结果时,才需应用该视角。“适度”指的是在考虑影响、可逆性与不确定性的前提下,能够消除风险的最轻量证据或管控措施。逐一解决每个适用的编号视角;保留可能改变决策的未知项。若省略某个视角可能隐藏风险,需给出可审计的跳过理由。

1. Keep The Spine Small

1. 精简核心骨架

Map only the load-bearing points that apply, using repository-native terms. Examples include entry surfaces, mutation admission, accepted state, externally visible effects, completion, and recovery. Do not inventory every example. When a repository-declared or risk-plausible point is omitted, state why it is absent or inapplicable rather than inventing a stage. Changing or adding an applicable point is a boundary decision.
A load-bearing decision chain is not one controller, writer, process, transport, or deployment topology. Multiple execution mechanisms may coexist when they preserve every applicable declared boundary contract. A new or changed load-bearing point is a redesign: name the blocker it solves, its reconciliation rule when relevant, and the path it changes or retires.
Cross-cutting mechanisms may have dedicated owners without becoming parallel authority roots or bypasses. Add a top-level concept only with explicit jurisdiction and decision rights, no undistorted existing owner, and a passing section 8 net-growth review.
仅使用仓库原生术语映射适用的核心负载节点。例如入口界面、变更准入、已接受状态、外部可见影响、完成状态与恢复机制。无需罗列所有示例。若省略仓库中声明或存在风险可能性的节点,需说明其缺失或不适用的原因,而非凭空新增阶段。变更或新增适用节点属于边界决策。
核心负载决策链并非单一控制器、写入器、流程、传输或部署拓扑。当多种执行机制能保留所有已声明的边界契约时,它们可以共存。新增或变更核心负载节点属于重新设计:需说明其解决的阻塞问题、相关的协调规则,以及它所变更或淘汰的路径。
跨域机制可拥有专属所有者,但不能成为平行权限根源或绕过现有规则。仅当具备明确管辖范围与决策权、无现有合适所有者,且通过第8节的净增长评审时,才可新增顶层概念。

2. Grade Every Surface

2. 分级所有界面

Grade each concrete surface by the compatibility promise it carries, using repository categories when available. Otherwise read
references/surface-cutover.md
. Do not assign one grade to an entire domain or mechanism: its private implementation and cross-boundary contract may differ.
Every export, field, flag, option, and consumer-relied observable is a potential promise. Choose the narrowest promise that satisfies the requirement. Public, persisted, and cross-boundary surfaces need an explicit compatibility or cutover strategy; never break one silently.
A clean break may converge directly on the target only when target and cutover decision authority, consumer and data scope, old-entry retirement, and recovery are explicit. Otherwise version or migrate.
根据每个具体界面承载的兼容性承诺进行分级,优先使用仓库中定义的分类。若无相关分类,请参考
references/surface-cutover.md
。不要为整个领域或机制统一分配一个等级:其私有实现与跨边界契约可能存在差异。
每个导出项、字段、标志、选项以及消费者依赖的可观测项均为潜在承诺。选择能满足需求的最窄范围承诺。公开、持久化与跨边界界面需要明确的兼容性或切换策略;绝不能无声地破坏这些承诺。
仅当目标与切换决策权限、消费者与数据范围、旧入口淘汰以及恢复机制均明确时,才可直接采用彻底切换的方式收敛至目标状态。否则需采用版本化或迁移方案。

3. Declare Authority, Writers, And Projections

3. 声明权限、写入者与投影

For each material fact and jurisdiction, use the simplest supported model. Declare only dimensions that exist and keep them independent:
  • Fact authority — source or rule determining accepted truth.
  • Decision authority — actor allowed to approve or change a load-bearing choice.
  • Accountable owner — responsibility for semantics, policy, lifecycle, and escalation; section 4 covers joint accountability.
  • Writers and admission — who may propose a mutation and through which route. Writing grants neither ownership nor fact authority.
  • Data partition — jurisdiction, boundaries, and transfer rules.
  • Replica — role, provenance, freshness, and read semantics.
  • Commit — acceptance, ordering or version, visibility, and quorum.
  • Conflict — prevention or detection plus the convergence rule.
  • Recovery — trigger, decision authority, owner, action, terminal invariant, and evidence required by section 5.
These dimensions coexist; partitioning, replication, quorum, and multi-writer admission do not replace an authority model.
An artifact may project one fact while authoritatively recording another; declare each relation separately. Change a projection through its source and regeneration path. Resolve overlapping fact authority instead of calling writers interchangeable.
针对每个重要事实与管辖范围,使用最简单的支持模型。仅声明实际存在的维度,并保持其独立性:
  • 事实权限 —— 确定可接受事实的来源或规则。
  • 决策权限 —— 有权批准或变更核心负载决策的角色。
  • 问责所有者 —— 负责语义、策略、生命周期与升级事宜;第4节涵盖联合问责。
  • 写入者与准入 —— 可提出变更请求的角色及对应的路径。写入权限不代表所有权或事实权限。
  • 数据分区 —— 管辖范围、边界与传输规则。
  • 副本 —— 角色、来源、新鲜度与读取语义。
  • 提交 —— 接受规则、顺序或版本、可见性与法定人数。
  • 冲突 —— 预防或检测机制,以及收敛规则。
  • 恢复 —— 触发条件、决策权限、所有者、操作、终端不变量,以及第5节要求的证据。
这些维度共存;分区、复制、法定人数与多写入者准入不能替代权限模型。
某个工件可能投影一个事实,同时权威记录另一个事实;需分别声明每个关系。通过其来源与再生路径变更投影。解决重叠的事实权限问题,而非将写入者视为可互换的角色。

4. Make Ownership Explicit

4. 明确所有权

Give each material fact, contract, boundary decision, and lifecycle an accountability model. Owner differs from writer, maintainer, operator, and consumer; one owner is common, not universal. Joint or federated accountability declares jurisdiction, decision rights, tie-break or escalation, and lifecycle.
State what each load-bearing owner owns. Where adjacent duties could be confused, also state what it does not own.
Follow declared dependency direction and cross boundaries through their public surface or assembly seam. Move semantics into a shared domain only when they are neutral and accountability belongs there; two consumers needing the same capability is insufficient. Prefer bounded, declared, tool-enumerable entry surfaces so retirement remains possible.
为每个重要事实、契约、边界决策与生命周期指定问责模型。所有者不同于写入者、维护者、操作者与消费者;通常为单一所有者,但并非绝对。联合或联邦问责需声明管辖范围、决策权、平局决胜或升级机制,以及生命周期。
说明每个核心负载所有者的职责范围。若相邻职责可能混淆,还需说明其不负责的内容。
遵循已声明的依赖方向,通过公开界面或组装接缝跨越边界。仅当语义中立且问责归属该共享领域时,才可将语义移入共享领域;仅两个消费者需要相同功能不足以成为理由。优先采用有界、已声明、可通过工具枚举的入口界面,以便后续能够淘汰。

5. Design The Negative Path And The Time Axis

5. 设计异常路径与时间轴

Every material negative outcome has defined behavior or an explicit unknown; a decision-changing unknown keeps the design open. Examine applicable denial, failure, partial, stale, cancellation, timeout, duplicate, out-of-order, concurrent-conflict, partition, and uncertain-commit cases. For stateful or repeatable work, also examine retry, restart, and replay. Do not invent a state machine for a reversible private choice.
Close each applicable recovery with:
  • detection or trigger;
  • decision authority and recovery owner;
  • rollback, forward repair, or reconciliation action;
  • terminal invariant and completion evidence; and
  • escalation when convergence fails.
Classify effects as reversible, compensable, or irreversible and scale controls accordingly.
references/recovery-guards.md
supplies control examples when needed; the design must establish closure, not merely name a recovery route.
每个重要的负面结果都需定义明确的行为或保留明确的未知项;可能改变决策的未知项需保持设计开放。检查适用的拒绝、失败、部分完成、过时、取消、超时、重复、乱序、并发冲突、分区与提交不确定等场景。对于有状态或可重复的工作,还需检查重试、重启与重放场景。无需为可逆的私有选择设计状态机。
为每个适用的恢复场景明确:
  • 检测或触发条件;
  • 决策权限与恢复所有者;
  • 回滚、向前修复或协调操作;
  • 终端不变量与完成证据;
  • 收敛失败时的升级机制。
将影响分为可逆、可补偿或不可逆,并相应调整管控措施。必要时可参考
references/recovery-guards.md
中的管控示例;设计必须明确收尾标准,而非仅指定恢复路径。

6. Guard Boundaries With Falsifiable Checks

6. 用可证伪检查防护边界

Pair each material architecture rule with a traceable reason and a proportionate falsifiable guard. When automation is not justified, define an explicit auditable review and the evidence it leaves. Layered validation is defense-in-depth only when each layer has a distinct responsibility.
A guard needs evidence that it detects a known or safely planted violation. Keel specifies sensitivity and freshness requirements; an authorized execution workflow decides whether and how to run the negative control. A quiet, falsifiable guard is not dead merely because no real violation occurred.
Default exception baselines to shrink-only. Growth is a boundary decision that records decision authority, reason, narrow scope, and removal condition. Moving code outside a guard's scope is also a boundary change. Read
references/recovery-guards.md
when designing or retiring a guard or changing an exception baseline.
为每个重要的架构规则搭配可追溯的理由与适度的可证伪防护措施。若无需自动化,则需定义明确的可审计评审流程及其留下的证据。分层验证仅在每层具备明确职责时才属于纵深防御。
防护措施需要能检测已知或可控违规的证据。Keel指定敏感度与新鲜度要求;授权的执行工作流决定是否以及如何运行负面测试。即使未发生实际违规,安静的可证伪防护措施也并非无效。
默认将异常基线设置为仅收缩。扩展属于边界决策,需记录决策权限、理由、窄范围与移除条件。将代码移出防护范围也属于边界变更。设计或淘汰防护措施、变更异常基线时,请参考
references/recovery-guards.md

7. Keep The Governed Path Cheapest

7. 让合规路径成本最低

Reduce avoidable friction without weakening controlling product, safety, security, privacy, or compliance policy. Recurring bypass signals route cost, not misconduct. The owning workflow may contain active risk immediately; trace containment scope, decision authority, cost, and exit while repairing the durable path.
在不削弱产品、安全、隐私或合规管控政策的前提下,减少不必要的摩擦。反复出现的绕过行为表明路径成本过高,而非不当行为。所属工作流可立即管控风险;在修复长期路径的同时,需跟踪管控范围、决策权限、成本与退出方案。

8. Keep Change And Deletion Routine

8. 让变更与淘汰成为常规操作

Make drift, migration, and deletion routine. A new noun, layer, or abstraction must remove more ambiguity than it adds. In an existing system, name what it retires; otherwise record net growth, accountability, reason, and review trigger. In greenfield work, compare it with a simpler omitted alternative instead of inventing a retirement ledger.
A retirement closes the active entry surface, enumerates and migrates or retires dependents, and preserves required behavioral evidence outside the implementation. Historical code informs behavior and risk; it does not define the target topology.
Begin a rewrite with the smallest independently replaceable slice and its preserved contracts. Expand only if bounded migration cannot close. Whole-target replacement closes only when the target is bounded and independently replaceable; entry surfaces, dependents, state, and preserved contracts are scoped; sections 2 and 5 close; and every viable smaller slice cannot reach the same terminal invariant or has greater evidenced migration or recovery risk.
让架构漂移、迁移与淘汰成为常规操作。新增名词、层或抽象必须消除更多歧义,而非增加歧义。在现有系统中,需说明其淘汰的对象;否则需记录净增长、问责、理由与评审触发条件。在全新项目中,需将其与更简单的备选方案对比,而非创建淘汰台账。
淘汰操作需关闭活跃入口界面,枚举并迁移或淘汰依赖项,并在实现外部保留所需的行为证据。历史代码用于指导行为与风险评估,但不定义目标拓扑。
重写需从最小的可独立替换切片及其保留的契约开始。仅当有界迁移无法完成时才可扩展。仅当目标有界且可独立替换、入口界面、依赖项、状态与保留契约已明确范围、第2节与第5节的收尾标准已满足,且所有可行的更小切片无法达到相同的终端不变量或存在更高的迁移/恢复风险时,才可进行全目标替换。

References

参考资料

Read only when needed:
  • references/rule-rationale.md
    — rule mechanisms, provenance, omissions.
  • references/task-routes-and-lenses.md
    — design and review routes and matrix.
  • references/surface-cutover.md
    — fallback compatibility and cutover evidence.
  • references/recovery-guards.md
    — recovery, guard, and exception details.
  • references/rot-audit.md
    — drift and long-lived-health indicators.
  • references/architecture-records.md
    — record authority, routing, and delegated structure.
仅在需要时阅读:
  • references/rule-rationale.md
    —— 规则机制、来源与遗漏说明。
  • references/task-routes-and-lenses.md
    —— 设计与评审路径及矩阵。
  • references/surface-cutover.md
    —— 兼容性回退与切换证据。
  • references/recovery-guards.md
    —— 恢复、防护与异常详情。
  • references/rot-audit.md
    —— 架构漂移与长期健康指标。
  • references/architecture-records.md
    —— 记录权限、路由与委托结构。