القائمة
创建和管理 Stage 文档——串联一轮工作中的所有技能产出物（MISSION、应然文档、实现计划、实然文档、ADR、验证结果），记录应然与实然的差异及其原因，并在封版时提炼学习摘要。当用户显式请求"创建 Stage""开始一个 Stage""封版 Stage"时使用。Stage 创建完全由用户决定，无自动触发条件。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
指导稳定的 RPC、存储协议和接口设计。在设计节点间 RPC、存储协议语义、模块边界或任何公共接口时使用。在定义 gRPC service、对象存储或文件系统语义、节点间的类型契约，或确立组件边界时使用。
自动化 CI/CD 流水线设置。在设置或修改构建和部署流水线时使用。当需要自动化质量门禁、在 CI 中配置测试运行器，或建立部署策略时使用。当需要处理 CI 上不稳定（flaky）的测试时使用。
进行多维度代码审查。在合并任何变更之前使用。在审查由你自己、另一个智能体或人类编写的代码时使用。当需要在代码进入主分支之前评估其跨多个维度的质量时使用。当需要评估变更的正确性、可读性、架构与性能，或审查 PR/diff 时使用。
为清晰性而简化代码。在重构代码以提高可读性而不改变行为时使用。当代码可以正常工作但比应有的更难阅读、维护或扩展时使用。在审查已积累不必要复杂性的代码时使用。当组件过度设计、过于炫技而难以维护时使用。当需要清理越来越难读懂的代码时使用。
验证系统的一致性与持久性承诺。在设计或修改复制协议、写路径、崩溃恢复逻辑时使用。当需要证明已确认的写入不丢失、副本间不发散、崩溃后能恢复到一致状态，或评审 fsync/校验和/事务语义时使用。
优化智能体上下文设置。在开始新会话、智能体输出质量下降、在不同任务之间切换，或需要为项目配置规则文件和上下文时使用。
| name | stage |
| description | 创建和管理 Stage 文档——串联一轮工作中的所有技能产出物（MISSION、应然文档、实现计划、实然文档、ADR、验证结果），记录应然与实然的差异及其原因，并在封版时提炼学习摘要。当用户显式请求"创建 Stage""开始一个 Stage""封版 Stage"时使用。Stage 创建完全由用户决定，无自动触发条件。 |
Stage 是一轮工程变更的串联文档——它不是替代任何一个技能产出物，而是记录每个技能产出了什么、这些产出之间是什么关系、以及这一轮变更的完整故事。
Stage 回答三个问题：
STAGE.md
（串联层 / 索引 + 叙事）
│
┌─────────┬─────────┬─┴─────────┬─────────┐
│ │ │ │ │
MISSION 应然文档 实现计划 实然文档 验证
(目标) (设计) (plan+todo) (结果) (证据)
│
ADR
(强制，每个 Stage 至少一篇)
Stage 创建完全由用户决定。 仅在用户显式请求时创建，无自动触发条件。
用户通常以以下方式发起：
/plan 输出计划后，用户对"是否需要 Stage 文档？"回答"是"典型适用场景（供用户参考，非触发规则）：
不会自动触发：
| 类型 | 动机 | 成功标准 | 应然 vs 实然 | 文档重心 |
|---|---|---|---|---|
| feat | 添加新能力 | 新行为出现且符合规范 | 有差异是正常的，必须记录 | spec + api-contract + api-doc |
| opt | 改善已有行为 | 指标达到目标值 | 简要记录优化效果对比 | 性能基线 + 优化结果 |
| debug | 修复错误行为 | 问题不再复现 + 回归测试覆盖根因路径 | 应然=实然（修复即目标） | 现象 + 根因 + 修复策略 + 预防措施 |
| refactor | 改变内部结构，行为不变 | 所有已有行为保持不变，回归测试全绿 | 应然=实然是硬性要求 | 架构设计 + 结构变更说明 |
/plan 输出后 /build 过程中 /build 全部完成后 /ship 执行时
│ │ │ │
▼ ▼ ▼ ▼
创建骨架 逐任务追加文档 封版 STAGE.md 检查 Stage 存在
(MISSION + (应然文档链接、 (实然文档、ADR、 (pre-launch
应然文档路径、 实现计划链接) 差异分析、验证结果、 checklist
实现计划链接) 学习摘要) 阻断项)
在 /plan 输出 tasks/plan.md 和 tasks/todo.md 后，Agent 询问用户是否需要 Stage 文档。用户确认后：
stages/<stage-id>/ 目录（stage-id 为 kebab-case 简短标题）STAGE.md 骨架，预填：
drafttasks/plan.md 和 tasks/todo.md）stages/INDEX.md 中追加一行在 /build 执行过程中：
所有任务完成且验证通过后，Agent 提醒用户封版。用户确认后：
donestages/INDEX.md 对应行状态/ship 的 pre-launch checklist 中包含：
以下是 stages/<stage-id>/STAGE.md 的规范模板：
# Stage: [简短标题]
**类型**: feat | opt | debug | refactor
**日期**: YYYY-MM-DD — YYYY-MM-DD
**状态**: draft | in-progress | done | abandoned | superseded | split
**决策者**: @username
---
## MISSION（本轮目标）
<!-- feat / opt / refactor 使用标准 MISSION -->
- **目标**: [一句话描述本轮要达成什么]
- **用户**: [谁会受益]
- **成功标准**: [如何知道完成了——具体、可验证的条件]
- **约束**: [绑定限制——技术、资源、时间]
- **不做**: [显式排除的内容及原因]
<!-- debug 类型替换为以下结构：-->
<!--
- **现象**: [用户做了什么、看到了什么、应该看到什么]
- **影响**: [影响范围、持续时间、数据完整性风险]
- **根因假设**: [初步判断——实现完成后更新为确认根因]
- **修复策略**: [止血方案 + 根因修复 + 预防措施]
- **成功标准**: [问题不再复现、回归测试覆盖根因路径、同类问题有静态检查]
-->
→ 详见 [MISSION.md](./MISSION.md)
---
## 应然文档（我们计划怎么做）
| 文档 | 来源技能 | 说明 |
|------|---------|------|
| [spec/xxx.md](./spec/xxx.md) | spec-driven-dev | 功能规范 |
| [design/api-contract.md](./design/api-contract.md) | api-and-interface | API 契约 |
| [design/xxx.md](./design/xxx.md) | — | [补充说明] |
> 实现开始前填充。若某类文档本轮不涉及，删除对应行。
---
## 实现计划
| 文档 | 来源技能 | 说明 |
|------|---------|------|
| [tasks/plan.md](./tasks/plan.md) | planning-and-task | 技术方案 |
| [tasks/todo.md](./tasks/todo.md) | planning-and-task | 原子任务列表 |
---
## 实然文档（我们实际做成了什么样）
> 实现完成后填充本节。
| 文档 | 来源技能 | 说明 |
|------|---------|------|
| [docs/api/xxx.md](./docs/api/xxx.md) | documentation-and-adrs | 实际 API 文档 |
| [docs/adr/XXX-title.md](./docs/adr/XXX-title.md) | documentation-and-adrs | 架构决策记录（必填，每个 Stage 至少一篇） |
### ADR（必填）
每个 Stage **必须**产出至少一篇 ADR。ADRs 记录关键的架构决策及其上下文。
| ADR | 决策内容 | 替代方案 |
|-----|---------|---------|
| [ADR-XXX](./docs/adr/XXX.md) | [一句话描述决策] | [被拒绝的方案及原因] |
**ADR 内容要求：**
- 记录"为什么选择 A 而不是 B"
- 列出被考虑并拒绝的替代方案及拒绝原因
- 描述决策的约束条件和后果
- 如果该决策与已有 ADR 相关，显式引用
**不同类型 Stage 的 ADR 重心：**
| Stage 类型 | ADR 典型内容 |
|-----------|-------------|
| **feat** | 为什么选这个架构/框架/协议；数据模型的设计取舍 |
| **opt** | 为什么选这个优化策略；为什么不选其他方案（如缓存 vs 索引优化） |
| **debug** | 根因为什么会产生；为什么选这个修复方案；预防措施的设计 |
| **refactor** | 为什么选这个新结构；为什么不统一某些边界情况；新旧结构的对比 |
---
## 应然 vs 实然差异
> 实现完成后填写。记录计划与实际之间的每个有意义的偏离。
| 差异 | 应然（计划） | 实然（结果） | 原因 | 是否回溯更新应然文档 |
|------|------------|------------|------|-------------------|
| [简述] | [计划怎么做] | [实际怎么做] | [为什么偏离] | 是 / 否 |
**"是否回溯更新应然文档"列说明：**
- **是**：该差异被认定为正确的设计方向，已回头修改 spec 或 api-contract 使其与实然一致
- **否**：该差异是临时妥协或折中，应然文档保留原样以便后续 Stage 参考
- 所有标"否"的差异行是下一轮 backlog 的候选输入
---
## 验证结果
| 检查项 | 状态 | 证据 |
|--------|------|------|
| [验收标准 1] | ✅ / ❌ | [测试报告、性能数据、截图等] |
| [验收标准 2] | ✅ / ❌ | [证据] |
| 无回归 | ✅ / ❌ | CI 运行链接 |
→ 详见 [VERIFY.md](./VERIFY.md)
---
## 学习摘要
> 封版时填写。不超过两句话。
- **下次这样做**：[本轮做对了什么——值得在其他 Stage 中复用]
- **下次别这样做**：[本轮做错了什么——应该避免、警惕或改进]
---
## 关联
- **上一轮 Stage**: [STAGE-XXX](../stage-XXX/STAGE.md)（或"无"）
- **下一轮计划**: [简述，或"无"]
Stage 封版（状态变为 done）后，如果发现小问题需要修补，但不构成一个新的 Stage，可在 STAGE.md 末尾追加增量章节：
---
## 增量 1（2026-07-28）
- **变更**: [简述修补了什么]
- **原因**: [为什么封版后还需要这个修补]
- **影响范围**: [哪些文件/模块]
追加增量时：
done，不退回 in-progress[增量 1]stages/INDEX.md 是所有 Stage 的导航入口。每个 Stage 创建和封版时维护。
# Stage 索引
| ID | 标题 | 类型 | 状态 | 涉及模块 | 日期 |
|----|------|------|------|---------|------|
| 001 | raft-election-optimization | opt | done | consensus, rpc | 2026-07-15 — 2026-07-17 |
| 002 | wal-checksum-verification | feat | done | storage, wal | 2026-07-18 — 2026-07-20 |
| 003 | replica-sync-refactor | refactor | done | replication, net | 2026-07-22 — 2026-07-23 |
| 004 | multi-az-placement | feat | abandoned | placement, scheduler | 2026-07-23 |
维护规则：
draftdoneabandoned、superseded 或 split 时同步更新涉及模块 列出受影响的顶层模块/目录，便于按模块检索| 状态 | 含义 | 何时使用 |
|---|---|---|
draft | 骨架已创建，实现尚未开始 | Stage 创建后 |
in-progress | 正在实现中 | /build 执行期间（可选使用） |
done | 按计划完成，已封版 | 所有任务完成、验证通过、学习摘要已写 |
abandoned | 中途放弃 | 方向错了、需求取消、被更高优先级打断 |
superseded | 被另一个 Stage 覆盖 | Stage-B 的范围吞掉了 Stage-A |
split | 拆分成了多个更小的 Stage | Stage 过大，拆分为独立子 Stage |
abandoned 的处理：
关联 章节的"下一轮计划"改为"无（已放弃）"superseded 的处理：
关联 章节添加"被取代于: STAGE-XXX"supersededsplit 的处理：
关联 章节添加"拆分为: STAGE-XXX, STAGE-YYY"splitstages/
INDEX.md ← 索引，每行一个 Stage
001-raft-election-optimization/
STAGE.md ← Stage 串联文档
MISSION.md ← 详细目标描述（可选，复杂项目推荐）
spec/ ← 应然：功能规范
design/ ← 应然：协议契约、数据布局
tasks/
plan.md ← 实现计划
todo.md ← 任务列表
docs/
protocol/ ← 实然：协议文档、RPC 接口
adr/ ← 实然：架构决策记录（必填）
verify/ ← 验证证据
fault-injection-report.md
consistency-check.txt
perf-before-after.json
002-wal-checksum/
...
...
目录结构是推荐范式，非强制。核心约束只有两条：STAGE.md 必须存在，每个 Stage 至少包含一篇 ADR。
| 技能 | 交互方式 |
|---|---|
| spec-driven-development | Stage 的 MISSION 从 spec 的 Objective 提取 |
| planning-and-task-breakdown | /plan 输出后，Agent 询问是否创建 Stage 骨架 |
| api-and-interface-design | 应然文档中的协议契约（gRPC/protobuf）和实然文档中的接口文档都链接到 Stage |
| failure-injection-testing | 涉及容错与故障恢复时，故障注入方案和混沌实验报告链接到 Stage 实然文档 |
| consistency-and-durability-verification | 涉及存储或状态复制时，一致性/持久性校验报告链接到 Stage 验证结果 |
| incremental-implementation | /build 全部完成后，Agent 提醒封版 Stage |
| documentation-and-adrs | ADR 是 Stage 的必填产出；每个 Stage 至少一篇 |
| shipping-and-launch | /ship 检查 Stage 是否存在（本轮曾创建则阻断） |
| 合理化借口 | 现实 |
|---|---|
| "这轮改动太小，不需要 Stage" | 如果改动小到不需要 Stage，那它可能也不需要 ADR。但用户已经决定创建 Stage——相信用户的判断。 |
| "需求太简单，应然和实然不会有什么差异" | 差异无处不在——即使最简单的变更也可能在实现中偏离计划。Stage 的核心价值恰好是记录这些差异。 |
| "先把代码写了，Stage 之后补" | 封版前的 Stage 是活的目录，不需要一次性写完。但事后补写意味着差异分析依赖记忆——记忆是不可靠的。 |
| "这个不需要 ADR" | 每个 Stage 都有至少一个值得记录的决策——哪怕只是"我们选择了最简单的实现方式，因为当前约束不允许更复杂的方案"。 |
"已经 abandoned 了，学习摘要没意义" | 放弃的教训往往比成功的更有价值。记录"为什么放弃"至少和记录"为什么成功"同等重要。 |
| "差异表里标'否'就够了，不需要解释" | 差异表的每一行都是未来决策的输入。标"否"的行告诉下一个接手的人"这里有技术债，而且是有意留下的"。 |
| "INDEX.md 可以以后补" | INDEX.md 的价值随 Stage 数量增长——第一个 Stage 时不觉得，第十个时就成了必需品。从一开始就维护。 |
abandoned 的 Stage 没有"放弃原因"——丢失了最有价值的信息draft 状态——要么推进实现，要么标记为 abandoned，不要让骨架腐烂创建 Stage 骨架后：
stages/<stage-id>/STAGE.md 存在drafttasks/plan.md 和 tasks/todo.mdstages/INDEX.md 已追加对应行封版 Stage 后：
done（或其他终态）stages/INDEX.md 对应行状态已同步更新