软件架构工程 是做什么的?
目的
在软件被修改的过程中保持架构连贯性,包括由AI代理编写的修改。这是一项操作性技能,而非要求重新设计每个项目的命令。其可复用原则源于《软件架构基础》第二版(Richards 和 Ford,2025);连续的代理工作流和工件是原创扩展。不要求特定的模型、编程语言、仓库托管、CI工具或框架。
始终应用三条定律:
- 一切都是取舍。 评估成本与收益,并根据实际上下文加权;当条件改变时重新评估。
- 为什么比怎么做更重要。 保留理由、被否决的选项、风险和决策负责人,而不仅仅是图表和代码。
- 决策处于一个频谱上。 拒绝错误的二元对立、一刀切的微服务规则和架构时尚。
根据影响选择工作模式
| 模式 | 典型触发条件 | 行动与预期输出 |
|---|---|---|
| 轻量 | 孤立缺陷、格式化、本地实现且无合同/边界影响 | 检查相关代码和约束;进行最小修改;运行相关检查;仅报告实质性问题。无需强制性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;生成设计、取舍分析、架构概要或审查,而不假装任何内容已实施或测试。对于完整架构审计,清点组件、数据所有权、边界、部署和团队/基础设施约束;用证据排序具体风险;在推荐全面重写之前提出增量补救措施和适配函数。
不可协商的安全保障
- 无可验证的事实: 不得发明仓库检查、测试输出、负载水平、合规状态、成本、利益相关者审批或度量。
- 无虚假普遍性: 微服务、单体和事件驱动系统没有哪个是固有最优的。不要仅凭表/实体拆分服务。
- 无范围混淆: 逻辑模块、已部署单元、数据所有权和架构特性范围是不同的概念。
- 无隐藏耦合: 检查共享模式、共享库、时间耦合、跨服务调用和事件合约;重用易变领域逻辑可能增加耦合。
- 无风险消除: 分布式一致性、事务处理、模式变更、故障恢复和回滚在相关时需要显式思考。
- 无流程表演: 完成的检查清单或自我评估不是证据。优先考虑实际检查和代码证据。
- 无静默架构变更: 标记重要偏差,记录原因,并将责任保留给人类/项目决策负责人。
- 无不正当书籍分发: 此技能是原创综合。不要将书籍或其图表复制到下游仓库。
按需参考文件
仅读取任务所需的文件(路径相对于此技能目录):
- AI编码与持续架构治理——对于实质性仓库编辑、PR审查、并行代理和架构漂移诊断是必需的。
- 基础与架构特性——需求、耦合、内聚、组件、特性范围。
- 架构风格——九种风格和选择条件。
- 分布式系统与模式——网络现实、事件、事务、一致性、编排、CQRS。
- 决策、适配函数与风险——ADR、治理、风险风暴、图表。
- 人员、数据、基础设施与AI——团队和操作约束。
- 源映射——全部27章以及书籍思想与代理特定扩展之间的区分。
- 验证评估准则——主要设计决策和实现审查的质量标准。
工件:架构概要、架构合约、变更影响、ADR、取舍矩阵、风险登记册、架构审查、边界策略示例。工作场景:无边界漂移的AI编码。其他模型/运行时指令是可选的;请参见可移植性。