Community编程与开发github.com

软件架构工程

编码技能。在持续维护架构完整性的同时设计、实现、重构和审查代码。适用于AI辅助编码、仓库变更、功能开发、API/数据库变更、模块边界、系统设计、迁移、部署选择、可扩展性、可靠性及架构审查。在更改代码前先分析现有架构;选择符合上下文的折衷方案;更改后验证架构约束。对于孤立的低风险编辑保持轻量级。

软件架构工程 是什么?

此技能旨在帮助AI代理在修改软件代码时始终维护架构的连贯性。它基于《软件架构基础》第二版的核心原则,并扩展了适用于持续代理工作流的操作法则。该技能要求代理在修改现有代码前先发现并分析当前系统状态,而非凭空发明;通过评估变更影响、比较备选方案、分步安全实施,并在每个步骤中验证架构适配函数(如禁止的依赖、循环依赖、模块所有权等),有效避免架构漂移。支持所有主流编程语言、仓库托管平台和CI工具。您可配置轻量、标准或深度三种模式,以匹配编辑风险等级,同时配有一整套参考文档(架构风格、分布式系统模式、决策治理)和模板(ADR、合约、影响分析),帮助您做出权衡和记录重大决策。最终,该技能严禁生成无法验证的事实、虚假论断或隐藏耦合,确保每次代码变更都经过可证实的架构验证。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/iAmSerathion/Skills/tree/HEAD/software-architecture-engineering

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

在你喜欢的 AI 中提问

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

文档

软件架构工程 是做什么的?

目的

在软件被修改的过程中保持架构连贯性,包括由AI代理编写的修改。这是一项操作性技能,而非要求重新设计每个项目的命令。其可复用原则源于《软件架构基础》第二版(Richards 和 Ford,2025);连续的代理工作流和工件是原创扩展。不要求特定的模型、编程语言、仓库托管、CI工具或框架。

始终应用三条定律:

  1. 一切都是取舍。 评估成本与收益,并根据实际上下文加权;当条件改变时重新评估。
  2. 为什么比怎么做更重要。 保留理由、被否决的选项、风险和决策负责人,而不仅仅是图表和代码。
  3. 决策处于一个频谱上。 拒绝错误的二元对立、一刀切的微服务规则和架构时尚。

根据影响选择工作模式

模式典型触发条件行动与预期输出
轻量孤立缺陷、格式化、本地实现且无合同/边界影响检查相关代码和约束;进行最小修改;运行相关检查;仅报告实质性问题。无需强制性ADR。
标准跨模块功能、新集成、API/模式变更、重大重构建立项目上下文;检查依赖项;比较现实选项;分增量实现;验证边界和合同;记录重大决策。
深度新平台、服务拆分、重大迁移、高风险的数据/安全/可靠性变更、架构审查完整上下文和架构分析、备选方案、显式数据/故障模式、迁移与回滚、可测量的适配函数、ADR(s)、风险与审批边界。

升级:当表面上小的编辑跨越所有权边界、更改公开合同、更改持久化、引入新的运行时/部署组件、扩大故障影响或揭示架构漂移时。降级:如果调查显示没有有意义的架构影响。用户/项目/安全指令优先。决不为琐碎任务强制生成重型报告。

必需的编码代理循环

对于在已有仓库中工作,执行此循环。关于精确流程、故障处理和并行代理规则,请参见代理实现治理。

0. 发现当前系统——不要发明它

  • 检查相关代码、测试、包/构建文件、基础设施、配置、文档、ADR、目录布局和实际依赖路径 在可访问时。
  • 定位任何项目架构合约(例如 docs/architecture/CONTRACT.md)以及已接受的ADR;将其视为项目约束,而非不可变真理。
  • 分别记录 观察到/提供/假设/未知。如果没有代码/工具访问权限,需说明结果是提案,而非经过验证的仓库分析。
  • 不要默默用偏爱风格替换已在使用的架构。

1. 在编辑前评估影响

  • 定义变更范围、受影响的业务能力、所有者模块、API/合同、数据职责、依赖项、安全边界、部署单元和故障路径。
  • 将任务分类为轻量/标准/深度,并选择最小足够的审查。
  • 对于重大决策,推导出几个优先的架构特性(例如安全性、延迟、可用性、可扩展性、弹性、可维护性、可测试性、可部署性、可恢复性、成本),附有范围、目标和度量。将显式需求与隐式、未确认的需求分开。
  • 对于低风险的未知项,选择最小、可逆的默认值;不要像确认那样处理未经验证的高风险假设。

2. 保留边界并在必要时比较备选方案

  • 偏向高内聚和低耦合。保持业务职责、依赖方向、时间耦合和数据所有权显式化。区分逻辑模块与独立部署服务。
  • 检查对操作和数据架构的影响,而不仅仅是目录结构。共享数据库、事务边界或同步调用可能破坏表面的模块性。
  • 对于重大变更,使用上下文加权的折衷方法比较至少两个可行的选项。候选方案可包括分层、模块化单体、管道、微内核、基于服务、事件驱动、空间驱动、编排驱动的SOA、微服务或混合架构。没有架构风格是通用默认值。
  • 分布式设计必须处理网络故障/延迟、可用性、一致性、事务边界、重试、幂等性、可观测性、安全性和操作成本按适用情况。
  • 列举会导致决策反转的条件。按需使用样式、分布式设计和基础。

3. 规划安全增量的实现

  • 识别预期文件/模块变更、必须保持稳定的合同、迁移顺序以及必要的回滚策略。
  • 陈述架构不变量(必须保持为真的规则):允许的依赖方向、内部API所有权、数据写入权限、租户/认证边界、向后兼容性、错误处理等。
  • 在实现之前为这些不变量选择客观检查。如有用,复制/调整项目架构合约和变更影响模板;未经许可或明确任务范围,不要创建项目文件。
  • 请求或推迟需要人类/业务权威的不可逆/高影响决策。不要伪造审批。

4. 实施时避免架构漂移

  • 做出与当前架构一致的最小连贯变更。不要在没有展示需求的情况下拆分服务、引入代理、全局抽象或新框架。
  • 保持接口和数据所有权显式。不要通过另一个模块的内部创建快捷方式、绕过认证/验证、默默更改事件模式或混合无关变更。
  • 如果实现揭示了计划中的重大缺陷,停止并重新评估受影响的决策,而不是用变通代码掩盖。仅在合理时更新ADR/合约。
  • 在多代理工作中,定义组件/文件所有权、稳定合约和集成负责人。并行变更不覆盖共享架构约束。

5. 验证架构,而不仅仅是功能

  • 运行相关的现有单元/集成/合约测试和构建检查当可用和授权时。
  • 验证架构特定的适配函数:禁止的依赖、循环、模块所有权、API兼容性、模式迁移、幂等性、性能预算、可观测性、弹性、安全性、部署/回滚,按适用情况。
  • 比较前后依赖结构和受影响的不变量。可选的stdlib导入边界检查器配合示例配置可以强制实施选定的Python/JS/TS导入规则;它有意限制了能力,不能证明完全的架构正确性。
  • 用 通过 / 失败 / 未运行 / 不适用 标记证据。不要在没有实际执行/证据的情况下声称测试、可扩展性、生产就绪性、安全性或部署已得到验证。
  • 如果任何强制性关卡失败,修复/回退,或者明确标识未解决的问题和决策负责人。永远不要将失败的关卡呈现为已完成工作。

6. 记录并沟通重大决策

  • 仅针对架构重要变更创建或更新简洁的ADR:标题、状态、上下文、所选解决方案、为什么、备选方案、取舍、后果、实施和重新审视触发条件。使用ADR模板。
  • 当被取代时保留历史决策。将图表视为沟通辅助手段,而非实施或验证的证据。
  • 在最终报告中,陈述:变更了什么;架构影响;通过、失败或未运行的检查;未处理的风险;以及任何需要的人类决策。对于轻量变更,一个简洁段落通常就足够了。

仅设计任务和审计任务

当不是编辑仓库时,按比例应用步骤0-3和6;生成设计、取舍分析、架构概要或审查,而不假装任何内容已实施或测试。对于完整架构审计,清点组件、数据所有权、边界、部署和团队/基础设施约束;用证据排序具体风险;在推荐全面重写之前提出增量补救措施和适配函数。

不可协商的安全保障

  • 无可验证的事实: 不得发明仓库检查、测试输出、负载水平、合规状态、成本、利益相关者审批或度量。
  • 无虚假普遍性: 微服务、单体和事件驱动系统没有哪个是固有最优的。不要仅凭表/实体拆分服务。
  • 无范围混淆: 逻辑模块、已部署单元、数据所有权和架构特性范围是不同的概念。
  • 无隐藏耦合: 检查共享模式、共享库、时间耦合、跨服务调用和事件合约;重用易变领域逻辑可能增加耦合。
  • 无风险消除: 分布式一致性、事务处理、模式变更、故障恢复和回滚在相关时需要显式思考。
  • 无流程表演: 完成的检查清单或自我评估不是证据。优先考虑实际检查和代码证据。
  • 无静默架构变更: 标记重要偏差,记录原因,并将责任保留给人类/项目决策负责人。
  • 无不正当书籍分发: 此技能是原创综合。不要将书籍或其图表复制到下游仓库。

按需参考文件

仅读取任务所需的文件(路径相对于此技能目录):

工件:架构概要、架构合约、变更影响、ADR、取舍矩阵、风险登记册、架构审查、边界策略示例。工作场景:无边界漂移的AI编码。其他模型/运行时指令是可选的;请参见可移植性。

相关技能