원클릭으로 Manus에서 모든 스킬 실행

시작하기

ddev-archive

스타2

포크0

업데이트2026년 7월 19일 03:16

实现 + 调试全部完成后，扫描活跃计划、聚合同主题的多轮迭代计划、归档并生成最终代码事实设计文档

설치

Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.

Manus에서 실행

출처

docevilOck

docevilOck/agent-skills-hook

GitHub 저장소 열기 Creator 저장소 보기

다운로드

Manus에서 실행

ddev-archive — 变更归档与最终设计定型

把同一主题下经过多轮迭代（初始计划、调试迭代、最终版本）的所有活跃计划归档到一个日期目录，并生成一份 final-spec.md 记录最终代码事实设计。

开始时声明： "正在使用 ddev-archive skill 归档变更。"

何时使用

实现 + 所有调试迭代已完成，代码已提交
同一功能经历了多轮 plan（初始 spec → 调试后调整 → 再次调试 → 最终版本）
最终设计与原始 spec 存在差异（调试中修改了方案）
准备关闭 feature 分支、清理工作区或进入发布前
需要给后续维护者留下"实际长什么样"的最终设计文档

不使用的情况：

还没开始实现 → 先用 ddev-spec
还在调试中 → 先调完再说
实现与原计划完全一致且只有一个 plan → 可以归档，但 final-spec.md 只需简述"实现与初始 plan 一致，无偏离"

归档目录结构

docs/plans/archive/YYYY-MM-DD/
├── 01_initial/              ← 初始计划（最早的 spec/detail/exec_plans）
│   ├── spec/
│   ├── detail/
│   └── exec_plans/
├── 02_iter1/                ← 调试后迭代 1（如有）
│   ├── spec/
│   ├── detail/
│   └── exec_plans/
├── 03_iter2/                ← 调试后迭代 2（如有）
│   └── ...
├── 04_final/                ← 最终版本（如有独立 plan）
│   └── ...
├── final-spec.md            ← 综合所有迭代的最终代码事实设计
└── archive-notes.md         ← 归档说明（可选，记录归档决策和未决项）

YYYY-MM-DD 为归档日期（当天）
数字前缀 01_ / 02_ 保持时间顺序
如果只有一个 plan 无迭代，则只有 01_initial/ + final-spec.md

流程

第一步：扫描活跃计划

确定本次变更的主题名/功能名。从当前 spec 文档标题、用户指定或对话上下文提取。
扫描 docs/plans/ 目录（排除 archive/ 子目录），列出所有与本次主题相关的计划目录。
相关性判断：
- 目录名包含相同主题关键词（如 usb-hid、usb_hid、hid-report）
- 目录下的 spec 文档标题或内容引用同一功能
- 用户显式指定了哪些目录属于同一变更
如果扫描结果超过 5 个目录，列出清单让用户确认哪些属于本次变更。

第二步：排序与分类

按日期和时间顺序排列所有相关计划目录：

最早的计划 → 标记为 01_initial（初始计划）
中间的调整计划 → 按时间顺序标记为 02_iter1、03_iter2...
最后的计划 → 标记为 0N_final（最终版本）

如果只有一个计划目录，直接标记为 01_initial。

分类规则：

从目录名中的日期提取时间顺序
如果目录名无日期，按文件修改时间排序
不确定时列出排序结果让用户确认

第三步：读取所有迭代的设计文档

对每个迭代目录，读取以下关键文件：

spec 文档：Delta Summary 表、模块边界图、联动修改清单
detail 文档：结构体定义、数据流、流程图
exec_plans：实现计划中的任务列表和验证结果
implementation-notes.md：Design Decisions、Deviations、Tradeoffs
progress.md：执行日志和验证结果

第四步：生成 final-spec.md

基于所有迭代文档的对比分析，生成最终代码事实设计文档。

文档位置

docs/plans/archive/YYYY-MM-DD/final-spec.md

文档结构

# [功能名] — 最终代码事实设计

> **归档日期**: YYYY-MM-DD | **迭代次数**: N | **最终版本**: 0N_final
>
> 本文档综合 [N] 轮迭代的设计文档，记录经过实机调试后的最终代码事实。
> 如与某轮迭代的设计存在差异，以本文档为准。

## 1. 变更面总览 (Delta Summary)

| 类型 | 对象 | 最终状态 |
|------|------|---------|
| ADDED | ... | ... |
| MODIFIED | ... | ... |
| REMOVED | ... | ... |

> 此表综合所有迭代的最终结果。与初始计划的差异在 §2 中说明。

## 2. 与原计划的关键差异

| 迭代 | 原计划 | 最终实现 | 原因 |
|------|--------|---------|------|
| 01_initial | [初始设计要点] | [实际落地情况] | [调试发现/框架约束/...] |
| 02_iter1 | [迭代1调整] | [实际落地情况] | ... |

> 如果只有一轮且无差异，写"实现与初始 plan 一致，无偏离"。

## 3. 最终架构总览

(ASCII 图 — ddev-diagram 规范 — 反映最终代码的模块边界和调用关系)

## 4. 最终核心数据结构

(经过调试确认的最终结构体、枚举、状态机定义)

每个结构体/枚举必须标注：
- 来源：来自 `01_initial/detail/structures/xxx.md`，在 `02_iter1` 中修改了字段 Y
- 如果与任何一轮设计文档不同，标注差异

## 5. 最终核心流程

(ASCII 图 — 反映最终代码的实际数据流和关键流程)

## 6. 调试发现的问题及修复

### Bug 1: [标题]

| 项目 | 内容 |
|------|------|
| 发现于 | 0N_iterX |
| 症状 | ... |
| 根因 | ... |
| 修复 | ... |
| 影响的设计文档 | 0N_iterX 的 spec/detail 中 xxx 部分 |

## 7. 未覆盖风险与已知限制

- [风险/限制 1]：[说明及缓解措施]
- [风险/限制 2]：[说明及缓解措施]

## 8. 设计决策记录

| 决策 | 触发迭代 | 决策内容 | 替代方案（为什么没选） |
|------|---------|---------|---------------------|
| ... | 02_iter1 | ... | ... |

⚠️ 硬门禁：画图前必须先加载 ddev-diagram

在任何 ASCII 图动笔之前，必须执行 Skill("ddev-diagram") 加载绘制规范。

第五步：创建归档目录并移动文件

创建 docs/plans/archive/YYYY-MM-DD/
将每个迭代目录复制/移动到对应的 0N_xxx/ 子目录
将 final-spec.md 写入归档根目录
删除原 docs/plans/ 下的活跃计划目录（移动后清理）

第六步：生成 archive-notes.md（可选）

如果存在以下情况，创建 archive-notes.md：

# 归档说明

> 归档日期：YYYY-MM-DD

## 归档范围
- 0N_iterX：简述
- ...

## 未归档内容
- [如果有相关但未纳入归档的文件，说明原因]

## 未决项
- [Open Questions 中仍未解决的问题]

图怎么选

优先画：

最终架构总览（模块框 + 调用关系，反映最终代码）
最终核心流程（数据流/时序图）
关键数据结构对比（如有迭代间结构变化）

不需要画：

各迭代中已正确且未变化的部分（引原文档即可）
调试过程中被废弃的方案

写法原则

只写最终状态：不写"调试过程中试过 A 不行换 B 最后选了 C"
差异必须标注：如果最终实现与某轮设计文档不同，必须显式标注
图优先：能用图说清的不用长文
引不抄：原 spec 里正确且不变的部分，一句话引原文档，不重复写
代码事实为准：final-spec 描述的是代码实际行为，不是"应该是这样"

与其他 skill 的关系

上游：ddev-exec（实现）+ 实机调试（可能产生多轮迭代 plan）
并行：ddev-diagram（画图规范）
下游：neat-freak（归档清理时引用 final-spec.md）
替代关系：原各迭代的 spec 文档保留在归档目录中作为设计意图记录，final-spec.md 为最终权威版本

自检

归档完成后逐项核对：

迭代完整性：是否找到了所有相关计划目录？遗漏的目录是否已确认不属于本次变更？
Delta Summary：final-spec.md 的 Delta Summary 是否覆盖了所有迭代的最终变更面？
差异覆盖：是否每轮迭代的"原计划 vs 最终实现"差异都已记录？
最终架构图：是否反映实际代码的模块边界和调用关系（而非某轮设计文档的复制）？
数据结构一致性：final-spec.md 中的结构体/枚举是否与 .h 中的实际定义一致？
ASCII 图规范：所有 ASCII 图是否通过 ddev-diagram 门禁？
目录清理：原 docs/plans/ 下的活跃计划目录是否已移除？
Debug bug 完整：每个调试发现的 bug 是否有症状/根因/修复三要素？

이 저장소의 다른 Skills

같은 저장소

ddev-doc-review

docevilOck/agent-skills-hook

文档审查技能。将文档审查任务派发给独立子代理，重点审查文档基于代码改动的合理性、说明正确性、前后一致性、错漏和逻辑谬误，以及 AI 实现过程中产生的决策记录（implementation-notes.md）。当用户需要审查技术文档、spec文档、设计文档、计划文档、API文档、README 或任何与代码改动相关的文档时使用。

2026-07-192

ddev-detail

docevilOck/agent-skills-hook

代码修改场景下，spec 文档确认后，需要继续以图优先方式梳理结构体定义、数据流和流程时使用

2026-07-192

ddev-diagram

docevilOck/agent-skills-hook

用户需要绘制架构图、流程图、数据流图、对比图时使用。AI 直接按规范手写 ASCII 图到 .md，不经过 PlantUML。

2026-07-192

ddev-spec

docevilOck/agent-skills-hook

在代码修改前需要编写 spec 文档且应优先用图表达边界、入口、流程和改动关系时使用（仅限代码改动场景，非项目级架构文档初始化）

2026-07-192

git-commit-template

docevilOck/agent-skills-hook

进行代码提交时触发。提供统一的提交标题（Conventional Commits）、正文模板、字段含义、写作风格和正反示例。应由 git-commit-standard 等提交流程 skill 强制加载。

2026-07-162

ddev-exec

docevilOck/agent-skills-hook

在当前会话里按已写好的实现计划顺序执行任务时使用

2026-07-102

name	ddev-archive
description	实现 + 调试全部完成后，扫描活跃计划、聚合同主题的多轮迭代计划、归档并生成最终代码事实设计文档

ddev-archive — 变更归档与最终设计定型

开始时声明： "正在使用 ddev-archive skill 归档变更。"

何时使用

实现 + 所有调试迭代已完成，代码已提交
同一功能经历了多轮 plan（初始 spec → 调试后调整 → 再次调试 → 最终版本）
最终设计与原始 spec 存在差异（调试中修改了方案）
准备关闭 feature 分支、清理工作区或进入发布前
需要给后续维护者留下"实际长什么样"的最终设计文档

不使用的情况：

还没开始实现 → 先用 ddev-spec
还在调试中 → 先调完再说
实现与原计划完全一致且只有一个 plan → 可以归档，但 final-spec.md 只需简述"实现与初始 plan 一致，无偏离"

归档目录结构

docs/plans/archive/YYYY-MM-DD/
├── 01_initial/              ← 初始计划（最早的 spec/detail/exec_plans）
│   ├── spec/
│   ├── detail/
│   └── exec_plans/
├── 02_iter1/                ← 调试后迭代 1（如有）
│   ├── spec/
│   ├── detail/
│   └── exec_plans/
├── 03_iter2/                ← 调试后迭代 2（如有）
│   └── ...
├── 04_final/                ← 最终版本（如有独立 plan）
│   └── ...
├── final-spec.md            ← 综合所有迭代的最终代码事实设计
└── archive-notes.md         ← 归档说明（可选，记录归档决策和未决项）

YYYY-MM-DD 为归档日期（当天）
数字前缀 01_ / 02_ 保持时间顺序
如果只有一个 plan 无迭代，则只有 01_initial/ + final-spec.md

流程

第一步：扫描活跃计划

确定本次变更的主题名/功能名。从当前 spec 文档标题、用户指定或对话上下文提取。
扫描 docs/plans/ 目录（排除 archive/ 子目录），列出所有与本次主题相关的计划目录。
相关性判断：
- 目录名包含相同主题关键词（如 usb-hid、usb_hid、hid-report）
- 目录下的 spec 文档标题或内容引用同一功能
- 用户显式指定了哪些目录属于同一变更
如果扫描结果超过 5 个目录，列出清单让用户确认哪些属于本次变更。

第二步：排序与分类

按日期和时间顺序排列所有相关计划目录：

最早的计划 → 标记为 01_initial（初始计划）
中间的调整计划 → 按时间顺序标记为 02_iter1、03_iter2...
最后的计划 → 标记为 0N_final（最终版本）

如果只有一个计划目录，直接标记为 01_initial。

分类规则：

从目录名中的日期提取时间顺序
如果目录名无日期，按文件修改时间排序
不确定时列出排序结果让用户确认

第三步：读取所有迭代的设计文档

对每个迭代目录，读取以下关键文件：

spec 文档：Delta Summary 表、模块边界图、联动修改清单
detail 文档：结构体定义、数据流、流程图
exec_plans：实现计划中的任务列表和验证结果
implementation-notes.md：Design Decisions、Deviations、Tradeoffs
progress.md：执行日志和验证结果

第四步：生成 final-spec.md

基于所有迭代文档的对比分析，生成最终代码事实设计文档。

文档位置

docs/plans/archive/YYYY-MM-DD/final-spec.md

文档结构

# [功能名] — 最终代码事实设计

> **归档日期**: YYYY-MM-DD | **迭代次数**: N | **最终版本**: 0N_final
>
> 本文档综合 [N] 轮迭代的设计文档，记录经过实机调试后的最终代码事实。
> 如与某轮迭代的设计存在差异，以本文档为准。

## 1. 变更面总览 (Delta Summary)

| 类型 | 对象 | 最终状态 |
|------|------|---------|
| ADDED | ... | ... |
| MODIFIED | ... | ... |
| REMOVED | ... | ... |

> 此表综合所有迭代的最终结果。与初始计划的差异在 §2 中说明。

## 2. 与原计划的关键差异

| 迭代 | 原计划 | 最终实现 | 原因 |
|------|--------|---------|------|
| 01_initial | [初始设计要点] | [实际落地情况] | [调试发现/框架约束/...] |
| 02_iter1 | [迭代1调整] | [实际落地情况] | ... |

> 如果只有一轮且无差异，写"实现与初始 plan 一致，无偏离"。

## 3. 最终架构总览

(ASCII 图 — ddev-diagram 规范 — 反映最终代码的模块边界和调用关系)

## 4. 最终核心数据结构

(经过调试确认的最终结构体、枚举、状态机定义)

每个结构体/枚举必须标注：
- 来源：来自 `01_initial/detail/structures/xxx.md`，在 `02_iter1` 中修改了字段 Y
- 如果与任何一轮设计文档不同，标注差异

## 5. 最终核心流程

(ASCII 图 — 反映最终代码的实际数据流和关键流程)

## 6. 调试发现的问题及修复

### Bug 1: [标题]

| 项目 | 内容 |
|------|------|
| 发现于 | 0N_iterX |
| 症状 | ... |
| 根因 | ... |
| 修复 | ... |
| 影响的设计文档 | 0N_iterX 的 spec/detail 中 xxx 部分 |

## 7. 未覆盖风险与已知限制

- [风险/限制 1]：[说明及缓解措施]
- [风险/限制 2]：[说明及缓解措施]

## 8. 设计决策记录

| 决策 | 触发迭代 | 决策内容 | 替代方案（为什么没选） |
|------|---------|---------|---------------------|
| ... | 02_iter1 | ... | ... |

⚠️ 硬门禁：画图前必须先加载 ddev-diagram

在任何 ASCII 图动笔之前，必须执行 Skill("ddev-diagram") 加载绘制规范。

第五步：创建归档目录并移动文件

创建 docs/plans/archive/YYYY-MM-DD/
将每个迭代目录复制/移动到对应的 0N_xxx/ 子目录
将 final-spec.md 写入归档根目录
删除原 docs/plans/ 下的活跃计划目录（移动后清理）

第六步：生成 archive-notes.md（可选）

如果存在以下情况，创建 archive-notes.md：

# 归档说明

> 归档日期：YYYY-MM-DD

## 归档范围
- 0N_iterX：简述
- ...

## 未归档内容
- [如果有相关但未纳入归档的文件，说明原因]

## 未决项
- [Open Questions 中仍未解决的问题]

图怎么选

优先画：

最终架构总览（模块框 + 调用关系，反映最终代码）
最终核心流程（数据流/时序图）
关键数据结构对比（如有迭代间结构变化）

不需要画：

各迭代中已正确且未变化的部分（引原文档即可）
调试过程中被废弃的方案

写法原则

只写最终状态：不写"调试过程中试过 A 不行换 B 最后选了 C"
差异必须标注：如果最终实现与某轮设计文档不同，必须显式标注
图优先：能用图说清的不用长文
引不抄：原 spec 里正确且不变的部分，一句话引原文档，不重复写
代码事实为准：final-spec 描述的是代码实际行为，不是"应该是这样"

与其他 skill 的关系

上游：ddev-exec（实现）+ 实机调试（可能产生多轮迭代 plan）
并行：ddev-diagram（画图规范）
下游：neat-freak（归档清理时引用 final-spec.md）
替代关系：原各迭代的 spec 文档保留在归档目录中作为设计意图记录，final-spec.md 为最终权威版本

自检

归档完成后逐项核对：

迭代完整性：是否找到了所有相关计划目录？遗漏的目录是否已确认不属于本次变更？
Delta Summary：final-spec.md 的 Delta Summary 是否覆盖了所有迭代的最终变更面？
差异覆盖：是否每轮迭代的"原计划 vs 最终实现"差异都已记录？
最终架构图：是否反映实际代码的模块边界和调用关系（而非某轮设计文档的复制）？
数据结构一致性：final-spec.md 中的结构体/枚举是否与 .h 中的实际定义一致？
ASCII 图规范：所有 ASCII 图是否通过 ddev-diagram 门禁？
目录清理：原 docs/plans/ 下的活跃计划目录是否已移除？
Debug bug 完整：每个调试发现的 bug 是否有症状/根因/修复三要素？