SuperAPI AI 工具集

arc42-section-11

编程与开发

查看项目

更新于 10-23 16:17

技能介绍

用途

arc42 Section 11 是一个用于 arc42 架构文档工具集的技能,专门辅助编写 arc42 第 11 章“风险与技术债”。它把已知问题和风险显性化,以支持知情决策与缓解规划,而不是隐藏风险。

主要能力

  • 上下文预填:先检查第 9 章是否存在——若有,则扫描每个 ADR 的“Risks created”字段,列出候选风险并询问哪些应正式登记为 RISK-xx;检查第 10 章——若有,则查看期望质量场景表,未达成的质量目标即视为风险候选;检查第 2 章——若有,则找出难以满足的约束;检查第 5 章——若有,则获取组件名称,技术债条目必须引用具体组件。
  • 分类梳理:系统性地询问架构风险(单点故障、未经验证的技术选型、无法扩展的组件、紧耦合设计)、依赖风险(无可行替代的第三方库或服务、弱 SLA 或无合同保障的外部 API、团队知识集中于个别人即 bus factor)、安全风险(未修补漏洞、威胁建模中识别但缺失的安全控制、未加密的敏感数据路径、密钥管理缺口)、数据与合规风险(数据驻留义务未完全满足、GDPR 或行业合规缺口、备份恢复未按 RTO/RPO 目标验证)、集成风险(外部系统行为不可控、协议版本风险、关键外部调用缺少熔断器)以及技术债。
  • 技术债分类:要求为每项走捷径、变通方案或次优决策说明类型(Accidental 时间压力所致、Deliberate 经 ADR 记录的有意权衡、Legacy 从旧系统继承)、受影响组件、当前或潜在问题及大致修复工作量。
  • 优先级推导:以概率×影响推导优先级,资料给出对照表:概率高×影响高=Critical,高×中=High,高×低=Medium,中×高=High,中×中=Medium,中×低=Low,低×高=Medium,低×中=Low,低×低=Low。
  • 编号稳定规则:RISK-xx 与 DEBT-xx 是工具集约定(官方 arc42 未规定风险或债务的标识格式);编号一经分配不得更改,已解决条目在矩阵中标记为 Closed,不删除、不重新编号,新条目取下一个最大编号。
  • 三档详细程度:LEAN 仅生成风险摘要矩阵;ESSENTIAL 增加带缓解细节的单项 RISK-xx 表;THOROUGH 再增加详细技术债部分,包含修复计划并追溯至第 9 章 ADR 与第 10 章场景。

使用方式

第一步,技能不会立即生成文档,而是先提出上述问题并等待回答。第二步,在获得全部回答后生成第 11 章,内容包括概述(跟踪多少风险与债务、整体风险态势、是否有 Critical 项未关闭、与第 9 章决策和第 10 章质量场景的关系)、按优先级排序的风险与债务摘要矩阵(ID、标题、类型、概率、影响、优先级、状态),并按详细程度添加单项 RISK-xx 表(类型、描述、概率、影响、优先级、缓解、状态)及上下文,THOROUGH 档再加追溯信息;技术债部分包括类型、受影响组件、优先级、状态、描述、存在原因、未处理影响与修复方案。第三步,按清单评审并迭代:检查第 9 章 ADR 的每个“Risks created”条目是否都已登记、第 10 章未达成的期望场景是否有对应风险、标记为 Mitigated 的条目是否有具体缓解措施;检查矩阵是否按 Critical→High→Medium→Low 排序且与概率×影响一致;进行诚实性检查,直接询问团队是否还有未列出的担忧,Accepted 风险需有明确接受理由;检查每项技术债是否引用第 5 章中的具体组件、是否有修复路径或至少影响说明、Deliberate 债务是否追溯至 ADR;检查编号是否被重新排列。对不合格项会指出问题并说明应如何处理,最后询问用户希望完善或扩展的内容并持续迭代。

适用场景

适用于使用 arc42 进行架构文档编写、需要系统记录技术风险与技术债的团队,尤其是已有第 9、10、2、5 章内容、希望保持风险条目可追溯与编号稳定的项目。

限制

资料未提供独立运行环境、安装命令、收费或平台信息,暂未提供。技能以交互提问方式工作,需用户提供各章节上下文与回答后才能生成文档。