docs: align runbooks and validation structure

This commit is contained in:
windyboy
2026-08-23 17:42:31 +08:00
parent fea9a6560f
commit 7bc7d3f99b
10 changed files with 68 additions and 32 deletions
+3 -2
View File
@@ -45,7 +45,8 @@ runbooks/
## 章节约定
- 每份 runbook 顶部含 `## Purpose`12 行)与 `## Scope`(适用/不适用情形)。
- 变更型 runbook 额外含 `## Approval gates` 表;破坏性/不可逆操作必须获得明确批准。
- 变更型 runbook 必须记录明确的审批门:门控命令式使用 `## Approval gates` 表;
流程式在步骤中记录审批动作、证据位置和未批准时的 `STOP`。破坏性/不可逆操作必须获得明确批准。
- 语言约定:**runbook 正文统一使用英文**(由 agent 逐字执行,降低二义性);
元规范文件(AGENTS.md / RUNBOOKS.md / 模板注释)可保留中文。
- 变更型 runbook 的两种形态:
@@ -55,7 +56,7 @@ runbooks/
- **门控命令式(gated command reference**:已稳定、低歧义、可验证的
操作以命令集 + 门控呈现(现有:`mailcow-update.md`
`ansible-operations.md``home-assistant-maintenance.md`
`vaultwarden-sqlite-to-postgres.md`),必须含 Approval gates 或确认变量
`matrix-e2ee-update.md``vaultwarden-sqlite-to-postgres.md`),必须含 Approval gates 或确认变量
要求 + 显式 STOP,不替代流程式形态。新写的变更 runbook 默认用流程式。
- 统一在 `## Safety` 或正文中复用以下通用安全规则(更严格要求优先)。