Community编程与开发github.com

鲁棒架构

基于具体流程、不变式、所有权和故障证据来设计或挑战软件架构。适用于新系统设计、模块边界不清晰、跨切面错误集群,或涉及状态、权限、历史记录或外部效应契约的变更。将普通局部修复保持局部化;这不是每次编辑都必须履行的架构仪式。

鲁棒架构 是什么?

该技能引导AI助手执行一种基于后果的、轻量级的软件架构流程。它强调从具体故障或约束条件出发,而非从抽象设计入手,并指导识别四类干预点:模型/所有权缺口、边界缺陷、产品缺口和呈现/局部缺陷。该技能为将事实和规则分配至权威归属点提供了实用模板,包括命名不变式、定义所有权、以及管理状态、历史记录和重试机制。它涵盖了跨网络、进程和异步边界的完整性考量,并推广了“首先尝试证伪”的方法,即通过面向故障的切片和实验来挑战架构。输出为一个结构化的、可审查的设计决策,重点关注具体流程、不变式和边界,而非空洞的形式。此技能适用于通用平台(CLI、Cursor、Codex等),其方法论源自软件工程基础知识(如“边界检查”和“基础”参考文献)。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/pkasarda/skills/tree/HEAD/skills/robust-architecture

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

鲁棒架构 是做什么的?

产出最小的、可解释且可质疑的设计。规则指导决策,而非认证正确性。一个有用的架构能明确重要事实,为规则提供一个权威归宿,并在发生故障或变更时保持可理解性。

从后果出发

对于现有系统,在相信图表或早期提议之前,先检查实际的入口点、调用者、状态存储和校验。对于新系统,区分需求与假设;在选择组件之前,先描述第一个真实流程。

只记录那些会改变决策的约束:用户与权限、运行量、延迟或资源预算、可用性、故障条件、恢复和持久性需求、部署约束,以及团队能够运维的内容。当未选定的产品选择影响正确性时,主动追问该选择。在未决期间,继续独立、可逆的工作。

校准干预力度:

  • 模型/所有权缺口: 必要的事实、完整的操作或一致的权限缺失或分散。在修补其读取者之前,先解决该契约。
  • 边界缺陷: 存在合适的拥有者,但调用者绕过它或其执行不完整。深化或利用该拥有者;跨层的缺陷本身并不要求新架构。
  • 产品缺口: 所需行为尚未决策。呈现具体的后果和最小的选择,而非默默做出选择。
  • 呈现/局部缺陷: 正确的底层事实需要局部的渲染、解析或副本修正。应用正常的局部修复;在此处停止架构工作流。

大文件、重复语法、缺少模式名称或提议的包本身并不构成模型缺口的证据。

对于涉及访问受保护资源的设计或审查,如果已安装,应用授权技能。该技能拥有访问策略的走查权;单独使用本技能时,请保留以下局部的所有权和信任规则。

为事实和规则赋予归属

命名事实或不变式、其逻辑权威,以及允许更改它的操作。权威可以是本地函数、文件发布者、库句柄、进程或服务;不一定是服务器或新模块。

  • 将规则置于能够为每个相关生产者强制执行它的地方。入口适配器建立调用者信任、解析输入、调用该拥有者并翻译结果。有用的早期检查能改善反馈;权威性检查保护实际效果。
  • 显式建模谁拥有共享数据。缺失的父级或作用域值并非自动成为全局权威。对读取、序列化和效果应用参与者的实际策略,而不仅仅是可见的控制。
  • 区分当前关系、不可变的发生事实和投影。存储功能真正需要的历史记录或快照。当前关系无法重建缺失的过去事实;诚实地标记不可知的遗留历史。
  • 为重试赋予操作身份。两个相同的负载可能代表不同的意图。当重试正确性重要时,在当前权限下定义关键范围、不匹配的复用、保留和重放。
  • 为派生规则和表示提供一个维护的定义,供消费者一致使用。保留不同受众、队列、单位和时间含义之间有意为之的差异。当共享会引入人为依赖时,保持廉价的局部呈现副本。
  • 明确指定的多写入者或离线设计是有效的。命名冲突语义、协调和分区行为,而不是假设总能强制使用一个物理写入者。

一个边界通过隐藏一个决策并从调用者那里移除知识来证明其存在。直接检查:改动后,哪个调用者不再知道规则、存储布局或顺序?一个让每个调用者仍然协调相同业务步骤的包装器并未转移所有权。

拥有完整的结果

追踪一个意图贯穿其重要效应。声明必须共同成立的内容、权威完成点,以及执行在完成点之前或之后停止时用户收到的内容。

枚举每个可观察的发布,包括缓存和后台回调。对于异步工作,识别结果所属的操作、身份、版本和生命周期,并在每个相关的发布边界检查适用性。迟到的视图检查无法保护早期的缓存或存储写入。区分取消消费者与撤销已提交的业务效果。

在单个权威内,对于需要不可分割性的不变式,使用实际的原子原语。当并发写入者可能使先前的读取无效时,在效果或等效序列化中强制执行适用的作用域、状态和版本。使机制与可达到的交错匹配;单线程纯转换不需要数据库风格的并发机制。

在网络、进程、文件或异步边界处,阅读边界检查。选择相关分支:持久化效果、资源生命周期、实时工作、或状态/历史记录。本地事务并不能使外部效果原子化;未知结果并不一定是失败。在添加重试之前,定义恢复和诚实的待定/部分结果。

对于可复用的API,明确输入、输出、拒绝、所有权和清理责任。保留有意义的错误/控制流区别。将诊断信息放置在能够在不解锁受保护数据的情况下解释故障的地方;日志不是恢复机制或授权/历史数据库。

选择成比例的结构

优先使用现有的连贯模块和受支持的平台机制。在新的小型应用中,几个边界良好的函数或模块可能就足够了。当具体需求需要独立的扩展、故障隔离、运行时约束或组织所有权时,再考虑分离部署或引入基础设施。在解释重要权衡时,尊重已显式选择的平台。

评估最小的变更及一个合理的替代方案。解释在正确性、资源/运维成本以及可逆性方面的重要差异。将每个设计决策保留在一个归宿中;仅独立提取稳定、有用的接缝。物理文件夹、包和服务遵循已证明的边界,而非提供证明。

在整个变更部署过程中保持整体不变式。迁移和回滚必须考虑现有数据、新旧写入者、公共消费者以及回滚兼容性。移除列、API或资源需要证据表明其义务和消费者已终止。

尝试证伪

选择一个薄薄的垂直切片来测试有争议的边界。使用与主张相关的真实存储、文件、协议或资源接缝;仅隔离真正的外部依赖。对于没有实现的早期设计,指定判别性实验并保持其结果未知。

用相关故障挑战不变式:错误的权限、陈旧状态、重复或重新排序的工作、完成边界处的崩溃、取消、缺失/模糊的历史记录,以及实际的负载或时间限制。使用显式的诱饵和受控的交错或时钟,当它们能够区分规则时。当该规则被移除时,测试应该失败,而不仅仅是计数模拟的调用次数或识别选择的名称。

同时检查安全性和进度:有效操作最终如何完成或给出诚实的拒绝;待处理的工作如何恢复;内存、队列、连接和延迟如何保持有界。从运行环境中选择这些检查,而不是排练每一个理论上的故障。

在声称功能正常时,观察已安装/用户或公共库的流程。单元断言、图表、绿色重试、基准猜测和合成夹具仅建立它们自己测试过的边界。区分测量的结果、源码发现、假设、缺失的决策和未执行的证明。

交付可审查的决策

使产出与决策规模相匹配。对于实质性设计,提供:

  1. 具体流程、约束和重要的未知项。
  2. 不变式、命名的权限和受影响的生产者/消费者。
  3. 状态/历史记录、信任、完成和故障边界,包含足以追踪一次成功和一次失败的契约。
  4. 选定的最小结构、相关的替代方案,以及权衡为何合适。
  5. 第一个切片,包含可观查的验收、恢复和演进/回滚检查。
  6. 已准备好的内容、需要产品决策或证明的内容,以及实际验证过的内容。

仅当小图能清晰揭示边界时才使用它。对于局部修复,跳过空的模板部分。保留用户的作用域:设计/审查请求产生一个决策,而不是实施、迁移、部署、发布或更改实时数据的许可。

当采用或评估此技能时,请参阅评估协议。主要背景列于基础中;它为推理提供信息,而非验证个别设计。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相关技能