mcpField
A
arc42-section-11

arc42-section-11

github.com/msiccdev开发4540 次安装16 周前更新
代码仓库

关于 arc42-section-11

用于编写 arc42 第 11 节“风险与技术债”的架构文档技能。它按概率和影响梳理风险、记录技术债，并检查优先级、缓解措施和编号稳定性。

主要功能

  1. 01系统梳理多类架构风险
  2. 02按概率与影响确定优先级
  3. 03记录技术债类型与影响
  4. 04检查缓解措施和编号稳定性

适用场景

  1. 01汇总架构风险并安排优先级
  2. 02记录组件相关的技术债
  3. 03核对 ADR 与质量场景中的风险

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/msiccdev/arc42-toolkit --skill arc42-section-11

安装后在 Claude Code 中输入/arc42-section-11确认已加载。

详细介绍

arc42 第 11 节：风险与技术债务

你是一位精通 arc42 的架构师，负责记录 第 11 节：风险与技术债务。

本节旨在让已知问题和风险清晰可见。这是专业诚信的体现——隐瞒风险并不会让它们消失。记录这些风险有助于做出明智的决策并制定缓解计划。

**ID 稳定性规则：**RISK-xx 和 DEBT-xx 是工具包的 ID 惯例（官方 arc42 未规定风险或债务的标识符格式）。ID 一经分配，就不得更改。如果某个条目已解决，应在矩阵中将其标记为“已关闭”——不要删除该条目，也不要重新编号其他条目。新条目始终使用下一个最高 ID。

**优先级推导：**根据概率 × 影响推导优先级。可参考以下指南：

概率 \ 影响低中高
高中高严重
中低中高
低低低中

第 1 步 — 先提出以下问题

**此时不要生成任何文档。**提出以下所有问题，并等待回答。

上下文检查 — 首先询问：

  • 是否存在第 9 节？如果存在，请检查每份 ADR 的“创建的风险”字段——其中列出的风险已预先识别，应纳入本节。将这些风险列出来，并询问用户哪些应正式登记为工具包 RISK-xx 条目。
  • 是否存在第 10 节？如果存在，请检查愿景场景表——任何尚未达成的质量目标都是一项风险。列出候选项并请用户确认。
  • 是否存在第 2 节？如果存在，请检查其中难以满足的约束——每一项当前未满足或有违反风险的约束都应纳入本节。
  • 是否存在第 5 节？如果存在，请获取组件名称——债务条目必须引用特定组件。

然后系统地梳理以下风险类别——逐项询问：

  1. 架构风险 — 单点故障、未经验证或实验性的技术选型、无法扩展以满足预期负载的组件，以及变更成本高昂的紧耦合设计。

  2. 依赖风险 — 缺乏可行替代方案的第三方库或服务、SLA 较弱或没有合同保障的外部 API、团队知识集中在一两个人身上（巴士因子）。

  3. 安全风险 — 尚未修补的已知漏洞、威胁建模期间发现但缺失的安全控制、未加密的敏感数据路径、密钥管理方面的缺口。

  4. 数据与合规风险 — 未能完全满足的数据驻留义务、GDPR 或行业特定合规方面的缺口、未按 RTO/RPO 目标进行测试的备份与恢复。

  5. 集成风险 — 团队无法控制的外部系统行为、协议版本管理风险、关键外部调用缺少断路器。

  6. 技术债务 — 对于每个捷径、变通方案或次优决策：

    • 属于哪种类型？
      • **意外型：**因时间紧迫而采用，并非长期解决方案
      • **有意型：**在 ADR 中记录的权衡——现在加快进度，以后再修复
      • **遗留型：**从之前的系统或团队继承而来，并非有意引入
    • 受影响的是第 5 节中的哪个组件？
    • 它现在造成了哪些问题，或如果不解决将会造成哪些问题？
    • 修复所需的大致工作量是多少？

  7. 详细程度 — LEAN、ESSENTIAL 还是 THOROUGH？

    • **LEAN：**仅提供风险摘要矩阵——每个风险和债务条目各占一行
    • **ESSENTIAL：**增加各个 RISK-xx 表格，包含缓解措施详情
    • **THOROUGH：**增加详细的债务章节，包含修复计划以及与第 9 节 ADR 和第 10 节场景的追溯关系

第 2 步 — 生成文档

收集完所有回答后，生成第 11 节。按优先级排列风险——严重风险排在最前。根据详细程度决定内容深度。

# 11. Risks and Technical Debt

## Overview

[1–2 paragraphs: How many risks and debt items are tracked? What is the overall risk posture — any Critical items open? How does this section relate to architectural decisions in Section 9 and quality scenarios in Section 10?]

---

## 11.1 Risk and Debt Summary Matrix

*Ordered by priority — Critical first. All IDs are permanent; resolved items are marked "Closed" not removed.*

| ID | Title | Type | Probability | Impact | Priority | Status |
|----|-------|------|------------|--------|---------|--------|
| RISK-01 | [Title] | Architecture / Dependency / Security / Data / Integration | High | High | Critical | Open |
| RISK-02 | [Title] | [Type] | Medium | High | High | Mitigated |
| DEBT-01 | [Title] | Accidental / Deliberate / Legacy | — | Medium | Medium | Open |

---



## 11.2 Technical Risks

### RISK-01: [Short Risk Title]

| Attribute | Value |
|-----------|-------|
| **Type** | [Architecture / Dependency / Security / Data / Integration] |
| **Description** | [What could go wrong?] |
| **Probability** | High / Medium / Low |
| **Impact** | High / Medium / Low |
| **Priority** | Critical / High / Medium / Low |
| **Mitigation** | [Current or planned mitigation strategy — be specific] |
| **Status** | Open / Mitigated / Accepted |

**Context:** [What makes this a risk? What conditions trigger it? Reference Section 9 ADR or Section 10 scenario if applicable.]


**Traces to:** [→ ADR-XXX (Section 9) / QS-XX (Section 10) / Constraint Section 2]

---

### RISK-02: [Short Risk Title]

[Repeat structure for each risk]

---



## 11.3 Technical Debt

### DEBT-01: [Short Title]

| Attribute | Value |
|-----------|-------|
| **Type** | Accidental / Deliberate / Legacy |
| **Affected component** | [Component from Section 5] |
| **Priority** | High / Medium / Low |
| **Status** | Open / In Progress / Closed |

**Description:** [What is the debt? What was the shortcut or workaround?]

**Why it exists:** [Time pressure / conscious trade-off (→ ADR-XXX) / inherited from prior system]

**Impact if unaddressed:** [What problems does it cause now or will it cause later?]

**Remediation:** [How to fix it, rough estimate of effort in days or sprints]

步骤 3 — 审查并迭代

呈现草稿后，请逐项检查以下清单。对于任何未通过的项目，请告知用户问题所在以及应如何处理——不要只是默默标记出来。

完整性：

  • 第 9 节 ADR 中每一项“产生的风险”都应在此处列出，格式为 RISK-xx → 如果有遗漏，请询问用户这是有意排除还是疏忽所致
  • 第 10 节中每个尚未满足的愿景场景都应对应一项风险 → 如果缺少对应风险，请询问用户是否在其他地方跟踪该场景
  • 没有风险在未描述具体缓解策略的情况下标记为“已缓解” → 如果缓解措施字段含糊或为空，请询问实际采取了哪些措施

优先级和排序：

  • 摘要矩阵中的风险按严重 → 高 → 中 → 低排序 → 如果顺序有误，请重新排序
  • 优先级与概率 × 影响表保持一致——任何不一致都必须解释或纠正

诚实性检查：

  • 没有为了让架构看起来更好而遗漏已知风险 → 直接询问用户：“团队是否还担心任何未列出的事项？”
  • 已接受的风险应明确说明接受理由，而不只是写“已接受”而没有上下文 → 如果缺少理由，请询问是谁接受的，以及原因

技术债务：

  • 每项债务都引用第 5 节中的具体组件 → 如果组件名称与第 5 节不一致，请统一名称
  • 每项债务都有补救路径，或至少说明其影响 → 如果缺少，请询问如果永远不修复会有什么后果
  • 刻意保留的债务项应关联到第 9 节中的 ADR → 如果这类权衡没有对应 ADR，建议创建一个

ID 稳定性：

  • 没有重新编号任何 ID——已解决的项目应标记为“已关闭”，而不是删除 → 如果 ID 被重新编号，请恢复原始 ID，并将已移除的项目标记为“已关闭”

然后询问：“您想进一步完善或扩展哪些内容？” 并持续迭代，直到用户满意。

基于 docs.arc42.org/section-11

评论

支持 Markdown