Skip to content

zzusp/doc-first-dev / skills/spec-first

spec-first

Verified

管理项目模块的完整开发周期:需求分析→更新技术方案→spec确认→开发→验收→收尾。适用于功能新增、Bug修复、需求变更、接口调整、重构、字段增删等涉及代码变更的任务;项目下有或无 spec 文档均可触发,无需用户明确指定流程。

FileKindSize
SKILL.mdskill md3.9 KB
assets/api-blank.mdmarkdown2.7 KB
assets/claude-md-snippet.mdmarkdown1.8 KB
assets/project-index.mdmarkdown1.7 KB
assets/tech-spec-blank.mdmarkdown4.8 KB
error-handling.mdmarkdown1.4 KB
evals/eval-01-new-feature.mdmarkdown1.8 KB
evals/eval-02-spec-code-mismatch.mdmarkdown1.3 KB
evals/eval-03-init-flow.mdmarkdown1.2 KB
init.mdmarkdown1.2 KB
phase-a.mdmarkdown10.5 KB
phase-b.mdmarkdown4.9 KB
phase-c.mdmarkdown6.8 KB
phase-d.mdmarkdown5.3 KB
step0.mdmarkdown3.9 KB

phase-d.md

View on GitHub
# Phase D — 收尾

条件:所有 T-xxx 均为 ✅ 或已取消,且所有 A-xxx ✅

## Contents
- D.1 一致性检查
- D.2 输出简报,提示收尾

---

## D.1 一致性检查

逐项执行,其中 ③④ 发现问题时停止并向用户报告,等待确认后再处理;①②⑤⑥ 为自动处理步骤:

**① 任务列表清理**
扫描第六节(任务状态)并执行清理。**删除前先将第六节全文原样复制到本消息内(作为 D.2 简报数据来源)**:
- ✅ 完成的行 → **统一删除**
- "已取消"的行 → 删除;spec 不保留已取消行
- 存在"待开始"/"进行中"行 → 不应出现(C.0 已阻止未完成任务进入验收),标记为"已取消"并在 D.2 简报"待后续迭代"节中注明,建议用户收尾后重新运行 `/spec-first` 处理
- 第七节末尾的循环计数器行(`验收循环次数:N`)→ 删除(过程状态,交付后无意义)

**② 验收列表完整性**
扫描第七节(验收项):
- 存在"待验证"/"未通过"行 → 报告并返回 Phase C,不进入收尾

**③ 代码与 spec 一致性**
对照第五节(代码地图),检查本次**所有 T-xxx 任务快照中涉及的方法**(覆盖全部,不做随机抽样):
- 接口签名是否与第三节(接口规范)一致
- 字段/参数是否与第二节(DB 设计)一致
- 发现不一致 → 描述差异,询问用户:"以代码为准更新 spec,还是以 spec 为准修改代码?"等待确认后再处理
  - 若选"以代码为准更新 spec"→ 原地改写对应章节,继续 D.1 剩余检查
  - 若选"以 spec 为准修改代码"→ 在 D.2 简报中注明该不一致项,本轮收尾后建议用户重新运行 `/spec-first` 发起新一轮分析,在 Phase A 中将修正纳入完整方案

**④ 需求边界覆盖**
对比第一节(需求边界)与本次 T-xxx 覆盖范围:
- 发现需求点无对应任务 → 在 D.2 简报中注明该遗漏项,本轮收尾后建议用户重新运行 `/spec-first` 发起新一轮分析;在第一节对该需求点标注"待后续迭代"

**⑤ 字段使用闭环**
遍历第二节所有字段,每个字段在第三节或第五节中至少有一处读写说明:
- 找不到说明的字段 → 在第二节该字段旁注明"暂未使用 / 预留"(可直接写入,无需用户确认)

**⑥ 更新 PROJECT.md 功能清单**
读取 `docs/plans/PROJECT.md`,在功能清单总表中找到本次工作的模块行:
- 若技术方案列为 `—` → 更新为当前 spec 的相对路径链接(如 `[用户管理技术方案](user/user-tech-spec.md)`)
- 若该模块行不存在(本次是新建 spec)→ 在对应一级模块下追加新行,填入模块名称和 spec 链接
- 若 PROJECT.md 功能清单总表为空或模块结构不完整 → 在 D.2 简报中提示用户手动补全

**⑦ 架构可持续性扫描**
检查本次新增/改动的代码(不扩展到历史存量代码):
- 业务规则(条件判断、计算逻辑、权限校验)是否混入了 I/O 层(Controller、Mapper、HTTP Client)?
- 有无仅为单一场景创建的复杂抽象(多层继承、通用工厂),可以用直接代码替代?

此项自动执行,不询问用户确认。发现问题时,在 D.2 简报"待后续迭代"节中列出,不阻断收尾流程。

所有项检查通过(或用户确认处置方案)后,进入 D.2。

## D.2 输出简报,提示收尾

整理简报所需数据来源:
- **完成任务 / 取消任务**:来自 D.1 ① 复制到本消息内的第六节原文
- **验收结果**:读自 spec 第七节的验收历史记录表(含每轮轮次数据)和 A-xxx 列表
- **变更文件**:从任务列表的"内容"字段提取涉及的源码路径,加上 spec 文件路径

直接以消息形式发送给用户,不写入任何文件:

---
## 本次交付简报

**模块:** <模块名>

**完成任务:**
- T-12 ✅ 在 XxxMapper.xml 追加 author 查询条件
- T-13 ✅ 更新 XxxMapper.java 方法签名

**验收总览(共 N 项,N 项一次通过,N 项修复后通过):**

从验收历史记录表中读取所有数据,输出如下表格(每个 R 列对应一个验收轮次,仅展示实际发生的轮次):

| 项 | 验证点摘要 | R1 | R2 | R3 | 根因(失败时) |
|----|-----------|----|----|----|-|
| A-05 | POST /item/list 传 author 筛选 | ❌ 500, NPE | ✅ 200, total:3 | — | 缺少 null 检查 |
| A-07 | GET /item/1 返回正确字段 | ✅ 200, name:张三 | — | — | — |
| A-08 | 越权访问返回 403 | ❌ 200 未拦截 | ❌ 200 仍通过 | ✅ 403 | 权限中间件逻辑修正 |

> 若验收历史记录表不存在(全程一次通过,未触发 C.3 循环),表格仅含 R1 列,所有行均为 ✅。

**取消任务(如有):**
- T-xx 已取消 — <取消原因>(无则省略此节)

**待后续迭代(如有):**
- <需求点或不一致项> — 建议下轮运行 `/spec-first` 重新分析(无则省略此节)

**变更文件:**
- <源码文件路径1>
- <源码文件路径2>
- docs/plans/<module>/xxx-tech-spec.md

---

> 如需记录本次开发决策背景,运行 `/whylog-record`。

---

> **Checklist 更新**:简报发送后,输出最终开发周期进度 Checklist,将 Phase D 标为 `[x]`,所有项均为 `[x]`。
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 197kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall