arc42-spec

name	arc42-spec
description	把一个功能 / 变更 / 重构 / 集成 / 迁移 / 演进需求,转写为符合 arc42 12 章框架的中文技术方案文档,写入本地文件。当用户要求"写技术方案 / 写设计文档 / 出架构方案 / 写 RFC / 写 spec / 生成 arc42",或在实现非琐碎变更前需要先建立结构化方案时使用。输入:需求描述(必填)、目标文件路径(可选)、规模等级 S/M/L(可选)。输出:单个 markdown 文件,含 arc42 全部 12 章节,逐章经过契约校验与跨章一致性门禁。下游 AI 可以基于该文档直接进行代码实现,人类可以基于该文档进行架构评审。

arc42-spec

把一个开发任务(新功能 / 变更 / 重构 / 集成 / 迁移 / 演进 / 修复方案设计)转写为 arc42 结构的技术方案文档。

本 skill 是 契约式协议,不是写作风格指南。每个 Phase 有明确入口 / 动作 / 退出条件;每个章节有 MANDATORY 字段、FORBIDDEN 模式、EXIT 门禁。

不可绕过的规则

1. 不要跳序:必须按 Phase A→B→C→D→E→F→G 执行,前一个 Phase 的 EXIT 未达成不得进入下一个。
2. 不要凭印象写散文:每个 MANDATORY 字段需要从 context_pack 取证或调用 AskUserQuestion 获取。
3. 不要省略 FORBIDDEN 自检:章节写完先按 FORBIDDEN 列表自查,命中即重写。
4. 不要在内部跨章互改造成循环:跨章断言失败时,只回到被引用源章节修补一次;再次失败按 §5 失败回退处理。
5. 不要编造没有的事实:信息缺失则写 > TODO(<要点>),并加入回报给用户的"待决策开放点"。
6. 不要把已有同主题文档覆盖丢失:同主题文件已存在 → 进入 Phase G 的更新模式。
7. 裁剪必须显式:S 级允许标 > 本章不适用:原因是…,但不允许直接删章。

---

0. 触发与不触发

USE 当:

• 用户请求"写技术方案 / 写设计文档 / 写 RFC / 出架构方案 / 写 spec / 生成 arc42"
• 用户描述非琐碎变更(命中以下任一即视为非琐碎):
  • 涉及 ≥2 个文件
  • 跨模块 / 跨服务
  • 涉及外部接口、数据模型、部署、安全、性能预算、并发、一致性、可演进性
  • 引入新依赖
• 用户显式调用本 skill

DO NOT use 当:

• 一行修复 / typo / 纯措辞调整
• 用户只想探索代码或回答问题,不要新产物
• 用户只想看现有架构,不做新设计

---

1. 输入契约

REQUIRED

• requirement:自然语言描述,说明本次需要做什么、解决什么问题

OPTIONAL(能从上下文推断的不要问用户)

• output_path:方案文档绝对路径
  • DEFAULT 选取顺序:
    1. 仓库已有 docs/specs/ → docs/specs/<slug>.md
    2. 仓库已有 docs/design/ → docs/design/<slug>.md
    3. 仓库已有 docs/rfcs/ → docs/rfcs/<slug>.md
    4. 仓库已有 docs/arc42/ → docs/arc42/<slug>.md
    5. 否则 → docs/arc42/<slug>.md(不存在则创建目录)
  • <slug>:requirement 摘要 kebab-case,≤50 字符,英文 ASCII;若 requirement 全中文,允许中文文件名但保留扩展名
• scope_level:S / M / L,DEFAULT:按 Phase B 决策表自动判定
• language:zh / en,DEFAULT:跟随 requirement 语言;混合时默认 zh

ASK USER

仅在以下情形发起一次 AskUserQuestion(单次提问最多 2 个问题):

• requirement 关键信息缺失,无法填满第 1 章 MANDATORY(典型:性能优化未给基线 / 目标值 / 范围)
• output_path 与现有非同主题文件冲突

绝不询问可通过 Read / Grep / git log / 仓库目录结构推断的信息。

---

2. 执行协议

按 Phase A→G 顺序执行。每个 Phase 的 EXIT 未达成前不进入下一个 Phase。

Phase A — 解析输入

ACTION:

1. 提取 requirement 文本
2. 分类变更类型 ∈ {new-feature, refactor, integration, migration, evolution, bugfix-design}
3. 抽取已显式给出的 OPTIONAL 字段
4. 列出 ≤3 处核心歧义;若存在,调一次 AskUserQuestion;否则跳过

EXIT:requirement 清晰 + 变更类型确定 + 已知字段表建立

Phase B — 规模分级

ACTION:套用决策表,从上到下,第一条命中即为最终等级:

触发条件	等级
涉及安全 / 权限 / 数据一致性 / 部署升级 / 跨团队接口契约 / 重大架构演进 / 不可逆迁移	L
跨模块 / 跨服务 / 涉及核心业务流程 / 涉及外部系统 / 引入新依赖 / 改变数据模型或接口语义	M
局部模块改造 / 低风险重构 / 单点功能 / 仅内部接口	S

裁剪规则:

• L:1–12 全部完整,不允许"不适用"
• M:1–12 全部存在;章节内部可压缩,不允许整章缺失
• S:1, 2, 3, 4, 5, 6, 9, 11, 12 必填;7, 8, 10 允许标 > 本章不适用:原因是…,但不得直接删除标题

OUTPUT:SCOPE = S | M | L + 章节存在性表

EXIT:等级与章节存在性确定

Phase C — 上下文发现

ACTION:按变更类型读取必要上下文。禁止全仓扫描;按需读取并记录引用路径与行号。

变更类型	必读	选读
new-feature	README、目标模块入口、≥1 个相邻已存在功能	类似模块的测试、相关 issue
refactor	被改动模块代码、调用方、被调方、相关测试	历史 commit、设计文档
integration	集成目标的现有接口、数据模型、既有适配器	第三方文档
migration	旧实现、新实现目标、迁移文档(若有)、数据样本	中间态历史
evolution	现有架构文档(CLAUDE.md / docs/)、近 30 commits	相关 issue / RFC
bugfix-design	复现路径、错误日志、相关代码、相关测试	上次修复历史

OUTPUT:context_pack = { existing_structure:已有的模块 / 包 / 服务边界, referenced_paths:[文件:行号] 的引用清单, external_deps:外部依赖与版本, discovered_constraints:从代码 / 配置 / CI 推断的约束, naming_conventions:命名 / 目录 / 错误码 / 日志 / 接口风格, nearby_implementations:可参照的相邻实现 }

EXIT:context_pack 至少含 5 条可引用事实(每条带文件路径或来源标注),否则继续读

Phase D — 章节生成

对 c ∈ [1..12](按 Phase B 章节存在性表):

1. 加载 §3.{c} 章节契约
2. 用 context_pack 而非凭空想象填 MANDATORY 字段
3. 应用 FORBIDDEN 列表自检;命中则重写
4. 跑章节 EXIT 门禁;未通过则在该章内修补

逐章完成、逐章过门禁。不要批量先写所有章节再统一检查。

Phase E — 跨章一致性

跑以下断言:

• A1:第 1 章每个"质量目标" → 第 10 章必须有 ≥1 条质量场景对应(M / L 适用)
• A2:第 2 章每条"约束" → 第 4 章策略表中可见其应对(或在该约束行标 not-architecture-shaping)
• A3:第 5 章每个 Level 1 构建块 → 第 6 章至少 1 处时序中出现(否则在 A3 例外说明区给理由)
• A4:第 5 章每个构建块 → 第 7 章映射表中存在(M / L 适用)
• A5:第 9 章每个 ADR → 在第 4 / 5 / 7 / 8 章中至少一处按编号引用
• A6:第 11 章每条 P0 / P1 风险 → 第 10 章有验证手段或第 9 章有相关决策

任意一条失败 → 回到对应源章节修补 → 再跑断言。

EXIT:适用断言全部通过

Phase F — 风险与决策完整性

逐项校验:

• 第 11 章每条 P0 / P1 风险:Owner 非空 + 缓解措施 + 验证方式
• 第 9 章每个 ADR:Status / Context / Decision / Consequences 四字段齐全
• 第 9 章每个 ADR:Negative Consequences ≥1 条
• 第 9 章每个 ADR:含 ≥1 个被驳回的替代方案及不选理由

EXIT:风险表与 ADR 表无空字段

Phase G — 写出与报告

1. 解析最终 output_path
2. 检查路径冲突:
   • 不存在 → Write 新文件
   • 同主题已存在 → 进入"更新模式"(见下)
   • 不同主题已存在 → AskUserQuestion 让用户选择新文件名 / 覆盖
3. 用 §4 骨架填充并 Write
4. 简短回报用户(≤8 行):
   • 文件路径
   • SCOPE 等级
   • 章节存在性(明示哪些写了 / 哪些标"不适用"及理由)
   • ≤3 条仍需用户决策的开放点(若有)
   • 下一步建议(如:进入 /plan-eng-review,或开始实现)

更新模式行为:

• 读取现文件
• 保留稳定字段(背景、术语表、已 Accepted 的 ADR)
• 新决策 → 第 9 章追加,Status: Proposed;若推翻旧 ADR,新 ADR 标 Supersedes ADR-XXX,旧 ADR 标 Superseded by ADR-YYY
• 第 11 章追加新风险
• 顶部"修订记录"追加一行:日期 / 变更摘要 / 触发的需求

---

3. 章节契约

下列 12 个契约是 Phase D 的可执行规约。每个契约独立可读、独立可校验。

§3.1 第 1 章 引言与目标

INPUT:requirement、变更类型、context_pack

MANDATORY:

• 1.1 背景与问题:≥2 段,覆盖 "现状—痛点—为什么现在做"
• 1.2 目标:3–7 条 bullet,每条形如 "动词 + 对象 + 可观测结果"
• 1.3 非目标:≥2 条;若想不出,回 Phase A 重审范围
• 1.4 质量目标表,列:优先级 | 质量目标 | 可验证场景,3–5 行
• 1.5 相关方表,列:相关方 | 关注点 | 需要从文档获得什么,≥3 行

FORBIDDEN:

• 出现 "高性能 / 高可用 / 易维护" 等形容词而无可验证场景
• "提升 X 能力 / 优化 Y" 等不可验证目标
• 相关方写 "用户" 且关注点写 "使用系统"
• 1.4 仅写 "性能 / 安全" 而无具体场景描述

EXIT:

• 每个 1.2 目标可在 1.5 找到 ≥1 个相关方关注点对应
• 每行 1.4 含数字、阈值或可枚举条件之一

§3.2 第 2 章 架构约束

INPUT:context_pack、requirement

MANDATORY:约束表,列:类型 | 约束 | 影响

• 类型 ∈ {技术、运行环境、组织、合规、流程、资源、约定}
• "影响"列必须写出"该约束如何限制了架构选择",不是约束本身的同义重复

FORBIDDEN:

• 把"业务需求"当约束写
• 影响列写"需要遵守该约束"等空话
• 把"我们想做的事"当约束(那是目标)

EXIT:

• ≥5 条约束,覆盖 ≥3 个类型(若 S 级且系统简单,允许 ≥3 条)
• 每条约束在 4 / 5 / 7 / 8 章中至少有一处可被引用,或显式标 not-architecture-shaping

HINT:

• 沿用既有基础设施(audit 表、内部 Redis、现有错误码命名、既有日志通道等)的"约定"与"资源"类约束,默认建议标 not-architecture-shaping,除非本方案对其使用方式做了改动
• 不要为了凑数把这类约束塞进 4 章策略表,会污染目标-策略对应关系

§3.3 第 3 章 上下文与范围

INPUT:requirement、变更类型、context_pack

MANDATORY:

• 3.1 系统边界:一段文字 + 一份"边界要素"清单(以黑盒视角说明系统对外提供什么、不提供什么)
• 3.2 外部参与者与接口表,列:外部对象 | 类型 | 输入 | 输出 | 接口/通道 | 质量要求
  • 类型 ∈ {用户、系统、组件、服务、存储、消息、文件、外部 API}
  • 协议(HTTP / gRPC / MQ / SDK / file / stdio)在"接口/通道"列注明
• 3.3 范围内:≥3 条
• 3.4 范围外:≥2 条,与 1.3 非目标对齐

CONDITIONAL:

• 涉及多租户 / 权限分级 → 列权限边界
• 涉及不同环境差异(如客户私有部署) → 列环境矩阵

FORBIDDEN:

• 3.2 表只写名字不写输入输出
• 把内部模块当外部系统
• 接口列只写协议名不写资源 / 路径 / 主题

EXIT:5 / 6 章引用的外部对象都在 3.2 出现

§3.4 第 4 章 解决方案策略

INPUT:第 1 章质量目标、第 2 章约束、context_pack

MANDATORY:策略映射表,列:质量目标或约束 | 解决方案策略 | 细节位置

• "细节位置"必须指向后续章节锚点(如 §5.2 / §8.3 / ADR-002)

FORBIDDEN:

• 在第 4 章展开实现细节(那是第 5–8 章的事)
• 策略只描述"做什么",不描述"为什么能达成对应质量目标 / 应对对应约束"
• 把"使用 React / Postgres" 这种技术选型当成顶层策略(技术选型应进 ADR)

EXIT:

• 1.4 每个质量目标在表中出现 ≥1 次
• 第 2 章每条约束在表中出现 ≥1 次,或在约束行标 not-architecture-shaping

§3.5 第 5 章 构建块视图

INPUT:第 3 章、第 4 章、context_pack

MANDATORY:

• 5.1 Level 1:整体白盒视图,≥3 个构建块;含构建块图(mermaid 或 ASCII)+ 黑盒说明表
• 5.2 Level 2:展开 ≥1 个 Level 1 中复杂或风险高的构建块
• 黑盒说明表,列:名称 | 职责 | 对外接口 | 依赖 | 质量要求 | 映射位置 | 风险
  • "映射位置"必须可被代码层引用:仓库 / 包 / 目录 / 文件 / 服务名 / 部署单元名
  • "职责"列在必要时显式声明"不负责 X(见 ADR-NNN)":当存在范围决策类 ADR(如 v1 不实现某能力)时,把该 ADR 编号写入相关构建块的职责列,确保 ADR 在第 5 章被引用(避免 A5 失败)

CONDITIONAL:

• L 等级:必须含 5.3 Level 3,展开 ≥1 个最高风险构建块
• M 等级:Level 2 ≥1 个;Level 3 可省

FORBIDDEN:

• 罗列代码包目录而不区分构建块层级
• 缺"映射位置"列(无法对接代码,失去 spec 价值)
• 一个构建块同时承担多个无关职责而不拆分(违反内聚)

EXIT:

• 每个 Level 1 构建块的"对外接口"和"依赖"明确(可用列表或表)
• 至少 1 处图(mermaid flowchart 或 graph 或 ASCII)
• 范围决策类 ADR(若有)在某构建块"职责"列已被引用

§3.6 第 6 章 运行时视图

INPUT:第 3 章、第 5 章

MANDATORY:

• 6.1 主成功路径:≥1 个完整时序(mermaid sequenceDiagram 或编号步骤),覆盖业务主线
• 6.2 关键异常路径:≥1 个,覆盖 {超时、依赖失败、校验失败、状态冲突、并发冲突、权限失败、数据损坏、版本不兼容} 中至少 1 类
• 6.3 启动 / 停止 / 升级 / 恢复路径:当存在状态、缓存、长任务、消息消费、灰度、定时任务时必填

FORBIDDEN:

• 只写"调用 A → B"而不带数据形态、错误模型、重试策略
• 主路径与异常路径合写在一个时序图里
• 每步不写"谁触发"或"携带什么数据"

EXIT:

• 主成功路径所有参与方都在第 5 章存在
• 关键异常路径含具体处置(重试 / 降级 / 失败处理 / 告警 / 补偿)

§3.7 第 7 章 部署视图

适用:M、L 必填;S 允许标 > 本章不适用:… INPUT:第 5 章

MANDATORY:

• 7.1 运行环境:列环境(本地 / CI / 测试 / 预发 / 生产)及差异(资源、配置、外部依赖、流量)
• 7.2 部署单元表,列:部署单元 | 打包形式 | 运行形态 | 扩缩容方式 | 资源预算
• 7.3 构建块到部署单元映射表,列:构建块 | 部署单元 | 环境 | 说明

CONDITIONAL:

• 涉及网络分区 / 多区域 → 网络拓扑图或区域表
• 涉及存储 → 存储类型、容量、备份策略、故障切换
• 涉及离线 / 客户私有部署 → 离线包结构、激活 / 升级流程

FORBIDDEN:

• 写"部署到生产"而不指明运行单元类型(进程 / 容器 / 函数 / 客户端 / 设备)
• 资源预算列空缺(M / L 等级)

EXIT:每个 Level 1 构建块在 7.3 映射表存在

§3.8 第 8 章 横切概念

适用:M、L 必填;S 允许标 > 本章不适用:… INPUT:第 1 章、第 2 章、第 4 章

MANDATORY:从下列概念中选 ≥3 项展开 ∈ {安全、错误处理、日志与追踪、监控告警、配置、并发与资源、数据一致性、接口规范、测试、可演进性} 每项以"规则列表"形式(不要散文):

• MUST:必须遵守的规则
• SHOULD:推荐做法
• DON'T:反例

每项规则需可被实现 / 评审 / 测试三方共同遵守。

FORBIDDEN:

• 用大段散文描述概念(应该是规则列表)
• 规则不可执行(如"提高安全性")
• 与第 4 章策略矛盾

EXIT:≥3 项概念,每项 ≥3 条规则(MUST + SHOULD + DON'T 合计)

§3.9 第 9 章 架构决策(ADR)

INPUT:第 4–8 章过程中识别的关键取舍

MANDATORY:≥3 条 ADR,每条格式:

### ADR-NNN:<标题>
- **Status**:Proposed / Accepted / Superseded by ADR-MMM / Deprecated
- **Context**:背景 + 约束 + 质量目标 + 相互冲突的力量(force)
- **Decision**:选定方案 + ≥1 个被驳回的替代方案及不选理由
- **Consequences**:
  - Positive:≥1 条
  - Negative:≥1 条
  - Neutral:可选

ADR 收录标准(命中任一即必须):

• 改变结构 / 关键质量属性
• 引入或移除关键依赖
• 改变外部接口 / 数据模型
• 改变构建 / 部署 / 安全 / 权限模型
• 对团队协作 / 运维方式产生长期影响
• 未来可能被追问"为什么这么做"

FORBIDDEN:

• ADR 缺 Negative Consequences(永远存在代价)
• ADR 没有被驳回的替代方案
• ADR 仅描述结果而未描述背景张力

EXIT:≥3 条;每条四字段齐全;每条 Negative Consequences ≥1 条;每条至少 1 个被驳回替代方案

§3.10 第 10 章 质量要求

适用:M、L 必填;S 允许标 > 本章不适用:… INPUT:第 1.4 质量目标

MANDATORY:质量场景表,列:场景 | 背景 | 刺激 | 响应 | 指标 | 优先级 每个 1.4 质量目标至少 1 条场景对应;场景总数 ≥ 1.4 行数

FORBIDDEN:

• 用形容词代替数字(如"响应快" → 改为"p95 < 200 ms")
• 场景描述不可被测试
• 同一场景出现两次(去重)

EXIT:每行含数值或可观测条件;与 1.4 行数对应

HINT:

• 防御性安全风险(secret 泄露 / 注入 / 越权 / CSRF / 数据破坏 / 拒绝服务)难以构造正向"用户场景",允许把"扫描器命中拦截 / 审计触发告警 / 演练通过门禁 / CI 检查阻断"等流程性场景写入本表,使得第 11.1 章对应的防御性 P0 / P1 风险能在第 10 章找到验证手段(避免 A6 失败)。
• 防御性场景示例:
  • 场景:client_secret 防泄露 / 刺激:开发者在 PR 中误提交含 secret 的文件 / 响应:CI secret scanner 阻断合并并通知安全 owner / 指标:每月 0 次 secret 泄露到主分支
  • 场景:SQL 注入防御 / 刺激:静态分析在新增查询发现拼接 / 响应:CI 阻断 / 指标:0 次未参数化查询合入

§3.11 第 11 章 风险与技术债

INPUT:context_pack、第 4–8 章

MANDATORY:

• 11.1 风险表,列:风险 | 触发条件 | 影响 | 缓解措施 | 验证方式 | Owner | 优先级
• 11.2 技术债表,列:技术债 | 来源 | 影响 | 偿还条件 | 暂存原因
• 若本方案不引入新技术债 → 显式声明 "本方案未引入新技术债"

FORBIDDEN:

• P0 / P1 风险无 owner
• 风险描述与缓解措施同义复述(如风险:"可能挂掉",缓解:"避免挂掉")
• 技术债无"偿还条件"
• 把"未来可能要做的功能"写成技术债

EXIT:每条 P0 / P1 风险有 owner + 验证方式;每条技术债有偿还条件

§3.12 第 12 章 术语表

MANDATORY:术语表,列:术语 | 含义 | 同义词 / 英文对照 | 出现位置

• 所有缩写必须收录
• 领域名词、状态名、角色名、事件名、接口名收录
• 同概念多名 → 给出推荐名

EXIT:

• ≥5 个术语
• 文档其它章节出现的所有缩写均在表中

---

4. 输出骨架

写入文件时使用以下骨架。<slot> 表示填空位置;保留中文标题与表头格式。

# <方案标题>

> 文档状态:Draft / Review / Accepted / Superseded
> 作者:<auto / 用户>
> 日期:<YYYY-MM-DD>
> 适用范围:<scope>
> 规模等级:<S / M / L>
> 相关材料:<links>

## 修订记录

| 日期 | 变更摘要 | 触发需求 |
| --- | --- | --- |
| <YYYY-MM-DD> | 初版 | <requirement 摘要> |

## 评审清单

- [ ] 第 1 章目标可验证、相关方齐全
- [ ] 第 2 章约束含影响列
- [ ] 第 3 章边界清晰、外部接口含质量要求
- [ ] 第 4 章策略映射 1.4 质量目标与第 2 章约束
- [ ] 第 5 章 ≥1 处图、Level 1 含映射位置
- [ ] 第 6 章主路径 + 关键异常路径
- [ ] 第 7 章构建块到部署单元映射齐全
- [ ] 第 8 章 ≥3 项横切,每项 ≥3 条规则
- [ ] 第 9 章 ≥3 条 ADR,每条 Negative Consequences ≥1
- [ ] 第 10 章每条 1.4 质量目标至少 1 条场景
- [ ] 第 11 章 P0 / P1 风险均有 owner + 验证方式
- [ ] 第 12 章覆盖所有缩写

---

## 1. 引言与目标

### 1.1 背景与问题

<slot>

### 1.2 目标

- <slot>

### 1.3 非目标

- <slot>

### 1.4 质量目标

| 优先级 | 质量目标 | 可验证场景 |
| --- | --- | --- |
| <P0/P1/P2> | <slot> | <slot,含数值或枚举条件> |

### 1.5 相关方

| 相关方 | 关注点 | 需要从文档获得什么 |
| --- | --- | --- |
| <slot> | <slot> | <slot> |

---

## 2. 架构约束

| 类型 | 约束 | 影响 |
| --- | --- | --- |
| <技术/运行环境/组织/合规/流程/资源/约定> | <slot> | <slot,描述对架构选择的限制> |

---

## 3. 上下文与范围

### 3.1 系统边界

<slot:一段文字 + 边界要素清单>

### 3.2 外部参与者与接口

| 外部对象 | 类型 | 输入 | 输出 | 接口/通道 | 质量要求 |
| --- | --- | --- | --- | --- | --- |
| <slot> | <用户/系统/组件/服务/存储/消息/文件/外部 API> | <slot> | <slot> | <协议+资源/路径/主题> | <slot> |

### 3.3 范围内

- <slot>

### 3.4 范围外

- <slot>

---

## 4. 解决方案策略

| 质量目标 / 约束 | 解决方案策略 | 细节位置 |
| --- | --- | --- |
| <slot> | <slot,说明为什么能达成> | <§X.Y 或 ADR-NNN> |

---

## 5. 构建块视图

### 5.1 Level 1:整体系统

```mermaid
flowchart LR
  <slot:Level 1 构建块图>
```

| 名称 | 职责 | 对外接口 | 依赖 | 质量要求 | 映射位置 | 风险 |
| --- | --- | --- | --- | --- | --- | --- |
| <slot> | <slot> | <slot> | <slot> | <slot> | <repo/pkg/file/service> | <slot> |

### 5.2 Level 2:<关键构建块>

<slot:展开图 + 黑盒表>

<!-- L 等级追加 5.3 -->

---

## 6. 运行时视图

### 6.1 主成功路径

```mermaid
sequenceDiagram
  <slot:主成功时序>
```

### 6.2 关键异常路径

<slot:覆盖超时/依赖失败/校验失败/状态冲突/并发冲突/权限失败/数据损坏/版本不兼容 之一>

### 6.3 启动 / 停止 / 升级 / 恢复

<slot 或 "本系统无相关状态">

---

## 7. 部署视图

### 7.1 运行环境

| 环境 | 资源 | 配置差异 | 外部依赖 | 流量 |
| --- | --- | --- | --- | --- |
| <slot> | <slot> | <slot> | <slot> | <slot> |

### 7.2 部署单元

| 部署单元 | 打包形式 | 运行形态 | 扩缩容方式 | 资源预算 |
| --- | --- | --- | --- | --- |
| <slot> | <slot> | <slot> | <slot> | <slot> |

### 7.3 构建块到部署单元映射

| 构建块 | 部署单元 | 环境 | 说明 |
| --- | --- | --- | --- |
| <slot> | <slot> | <slot> | <slot> |

---

## 8. 横切概念

### 8.1 <概念 1,如:错误处理>

- **MUST**:<slot>
- **SHOULD**:<slot>
- **DON'T**:<slot>

### 8.2 <概念 2>

- **MUST**:<slot>
- **SHOULD**:<slot>
- **DON'T**:<slot>

### 8.3 <概念 3>

- **MUST**:<slot>
- **SHOULD**:<slot>
- **DON'T**:<slot>

---

## 9. 架构决策

### ADR-001:<标题>

- **Status**:Proposed
- **Context**:<slot,背景+约束+质量目标+冲突的力量>
- **Decision**:<slot,选定方案>
  - 被驳回的替代方案 A:<slot> — 不选理由:<slot>
- **Consequences**:
  - Positive:<slot>
  - Negative:<slot>

### ADR-002:<标题>
…

---

## 10. 质量要求

| 场景 | 背景 | 刺激 | 响应 | 指标 | 优先级 |
| --- | --- | --- | --- | --- | --- |
| <slot> | <slot> | <slot> | <slot> | <slot,数值或枚举> | <P0/P1/P2> |

---

## 11. 风险与技术债

### 11.1 风险

| 风险 | 触发条件 | 影响 | 缓解措施 | 验证方式 | Owner | 优先级 |
| --- | --- | --- | --- | --- | --- | --- |
| <slot> | <slot> | <slot> | <slot> | <slot> | <slot> | <P0/P1/P2> |

### 11.2 技术债

| 技术债 | 来源 | 影响 | 偿还条件 | 暂存原因 |
| --- | --- | --- | --- | --- |
| <slot> | <slot> | <slot> | <slot> | <slot> |

> 若本方案不引入新技术债,以一句话明示。

---

## 12. 术语表

| 术语 | 含义 | 同义词 / 英文 | 出现位置 |
| --- | --- | --- | --- |
| <slot> | <slot> | <slot> | <§X.Y> |

---

5. 失败回退

触发情形	回退动作
MANDATORY 字段缺信息	不要编造。要么调 AskUserQuestion;要么写 > TODO(<要点>) 并加入"待决策开放点"
取舍信息不足	ADR 标 Status: Proposed,Consequences 注 "待 X 评审 / 验证后转 Accepted"
章节门禁连续 2 次未通过	停止生成,向用户报告卡点(章节、失败的 EXIT 项、缺失信息),等待澄清
跨章断言失败	只回到被引用源章节修补一次;再次失败 → 上一行
现有文件路径冲突	同主题 → 更新模式;不同主题 → AskUserQuestion
用户取消或要求暂停	已写部分以 Draft 状态保留,在文件顶部标 > 文档状态:Draft (暂停于 Phase X)

---

6. 与人类评审的接口

文档应当便于评审:

• 顶部"评审清单"映射到 §3 的 EXIT 项
• ADR 编号显式(ADR-001、ADR-002…),便于评审中按编号引用
• 风险表 / ADR 表用 markdown 表格而非散文,便于 diff 对比
• 修订记录单独成区,每次更新追加一行
• 所有 > TODO(…) 占位符即评审的开放点

---

7. 与代码生成的接口

本方案是后续 AI 代码实现的契约,以下信息会被实现阶段直接消费,必须精确:

• 第 5 章"映射位置"列:实现时按此对齐到具体路径
• 第 3.2 接口表:对外契约;实现严格匹配输入输出与质量要求
• 第 6.2 异常路径:必须覆盖到代码与测试,不要"以后再加"
• 第 8 章 MUST 规则:编码 / 评审 / 测试共同遵守
• 第 9 章 ADR:技术选型依据;实现中发现 ADR 不可行 → 回到本文件追加新 ADR(Supersedes),不要在代码里悄悄偏离
• 第 10 章质量场景:测试与验收基线
• 第 11 章风险:实现阶段需确认每条 P0 / P1 的"验证方式"已落到测试或运行手段

---

8. 命名与风格约束

• 文档语言:默认中文;术语含英文原词 → 中文 + 英文括注(如 "幂等性 (idempotency)")
• 表格优先于散文:可表格化的信息一律用表格
• 列表优先于段落:超过 3 个并列项用 bullet
• 图:用 mermaid(默认)或 ASCII;不要外链图床
• 单文件 ≤2000 行;超过则按 §3 章节拆分到 docs/<slug>/<chapter>.md 并在主文件留索引(极少用到)
• ADR 编号在文档生命周期内单调递增,不重用旧号,即使旧 ADR 已 Deprecated

---

9. 反漂移检查表(自检每次执行)

执行结束前,逐项确认。任意一项 NO → 回退处理。

• Phase A–G 是否按序执行,无跳序
• 是否启用 context_pack 取证,而非凭印象写散文
• 章节存在性是否符合 SCOPE 等级裁剪规则
• 跨章断言 A1–A6 是否全部通过(适用范围内)
• 每条 P0 / P1 风险是否有 owner + 验证方式
• 每条 ADR 是否含 Negative Consequences 与被驳回替代方案
• 1.4 与 10 章是否一一对应
• 5 章映射位置是否真实存在于 repo(可 Grep 验证)
• 是否有任何 > TODO(…) 未在最终回报中告知用户
• 输出路径是否已 Write 成功,且未覆盖不同主题的旧文件