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-a.md

View on GitHub
# Phase A — 分析与更新 spec

## Contents
- A.1 确认需求理解
- A.2 识别受影响章节
- A.3 全量证据分析(分析阶段核心步骤)
- A.4 改写受影响章节
- A.5 新增 T-xxx 任务
- A.6 新增 A-xxx 验收项
- A.7 方案确认(确认门)

---

> **Phase A 写锁:** 本阶段仅允许修改 spec 文档,代码文件不得改动,直至 A.7 确认门通过。
> 若用户在 A.1–A.6 期间要求修改代码,统一回应:`"Phase A 期间代码不开放修改——方案确认后(A.7)直接进入开发。请继续完成 spec 确认。"`

---

## A.1 确认需求理解

用 2–4 句话复述需求要点,无需等待用户回应,直接进入 A.2。(正式确认在 A.7 进行)

## A.2 识别受影响章节

列出需要改写的章节,并给出将要发生的变化:

- **已有 spec 的增量修改**:展示"修改前/修改后"对照,内容越具体越好

```
受影响章节:

■ 第 3 节(接口规范)
  变更原因:新增 firstAuthor 查询参数
  修改前:POST /item/list 接受 title、type 两个筛选条件
  修改后:POST /item/list 增加可选的 firstAuthor 筛选条件

■ 第 5 节(代码地图)
  变更原因:Mapper 方法签名增加参数
  修改前:selectPageList(String title, String type)
  修改后:selectPageList(String title, String type, String firstAuthor)
```

- **新建 spec(空白骨架)**:列出将要填入的章节和核心内容,格式同上,每节说明"将填入 ■ 第 N 节(名称):<核心内容描述>"

spec 标准 8 节:① 需求边界 ② 数据库设计 ③ 接口规范 ④ 架构与设计规则 ⑤ 代码地图 ⑥ 任务状态 ⑦ 验收项 ⑧ 附录。旧版 spec 章节标题不同,按实际内容对应。

## A.3 全量证据分析(分析阶段核心步骤)

分析范围由 A.2 划定,并以用户最新补充/澄清为最高优先输入;在此基础上进行交叉核对:

- 新增/修改字段 → 读对应实体类、DTO、数据访问层映射文件
- 修改查询逻辑 → 读映射文件 + 调用该查询的 Service 方法
- 新增/修改接口 → 读 Controller/Router 类 + Service 接口定义
- 修改 DB 结构或校验现状 → 查实际表结构与关键样本数据(环境可访问时)
- 行为与实现不一致时 → 交叉读取相关日志、配置与中间层代码,定位约束来源

每读一个文件,说明发现了什么以及如何影响后续方案。例:
> "读了 `XxxMapper.xml`,`selectPageList` 已有 title/type 两个条件,新增 author 直接追加条件块,无冲突。"

## A.4 改写受影响章节(原地改写,不追加)

**核心原则:spec 记录当前状态,不记录变更历史。**

- 替换旧内容,不保留"原来是 X,现改为 Y"的说明
- 删除不再准确的字段、方法描述
- 改后重读该章节,确认与其他章节一致(DB设计 ↔ 接口规范 ↔ 代码地图)

**代码地图(第5节)原地更新规则**:修改某个方法的职责描述时,找到该方法已有的行并原地修改;**不新增同名方法行**。只有全新方法才追加行。同一张表中出现两行相同方法名是明确的错误信号。

**附录路径索引(第8节)去重规则**:修改文件路径索引时,先检查同名文件是否已有条目;若已存在,更新路径,不追加新行。

**受变更影响的任务和验收项必须重置状态:**
- 修改了某个 T-xxx 的范围(文件、方法、内容)→ 将该 T-xxx 状态重置为"待开始"
- 修改了某个 A-xxx 的断言或关联任务 → 将该 A-xxx 状态重置为"待验证"
- 未被变更触及的已通过 A-xxx,状态保持不变;已完成的 T-xxx 保留在列表中,若受变更影响则重置为"待开始"

## A.5 新增 T-xxx 任务

在第六节(任务状态)追加行,每条 T-xxx 必须包含:
- 明确的文件范围(哪个文件 + 哪个方法/节点)
- 优先级:P0(阻塞)/ P1(重要)/ P2(可选)
- 状态:待开始

每条 T-xxx 使用**单行列表**格式,字段顺序固定:编号 · 优先级 · 状态 — 内容

✅ 好的 T-xxx:`- T-11 · P0 · 待开始 — 在 XxxMapper.xml selectPageList 追加 author 条件;更新 XxxMapper.java 方法签名`
❌ 差的 T-xxx:`- T-11 · P0 · 待开始 — 扩展筛选功能`(无文件无方法)

**代码位置定位规则**:使用方法名/类名定位,**不使用行号**(行号随代码提交立即失效)。
- ❌ `ModelCanvasServiceImpl.java:334`
- ✅ `ModelCanvasServiceImpl.getCanvasDetail()`

被取消的任务标记为"已取消"并注明原因,不删除。已完成的 T-xxx 保留在任务列表中,**不在验收阶段逐条删除**——任务列表将在 Phase D 所有验收通过后统一清理。编号续接规则:在当前列表中(含已取消行)的最大编号基础上递增,不复用已用编号。

## A.6 新增 A-xxx 验收项

第七节(验收项)所有验收行统一使用 **A-xxx 编号**,每条使用**单行列表**格式,字段顺序固定:编号 · 接口 · 状态 — 验证点

每条 A-xxx 必须包含可执行的断言——具体的 HTTP 请求 + 预期响应,或具体 SQL + 预期结果。

✅ 好的 A-xxx:`- A-05 · POST /item/list · 待验证 — 传 author=张三,返回 total>0,所有结果含"张三"`
❌ 差的 A-xxx:`- A-05 · POST /item/list · 待验证 — 筛选功能正常`(无可执行断言)

编号续接规则同 A.5(取当前列表最大 A-xxx 编号递增,不复用已用编号)。

**对抗性自审(每次写完 A-xxx 后立即执行,不等到 Phase C):**

以挑剔审查者视角逐条检查,发现问题原地修正:
1. 该断言是否在实现错误时也可能侥幸通过(如仅验证状态码、未验证字段值或数量)?→ 收紧断言
2. 是否遗漏关键边界场景(空值/非法参数、越权访问、重复提交、并发写入)?→ 补充新 A-xxx

**安全规则**:验收章节中涉及认证信息时,**密码、token、Cookie、secret 一律用占位符**,不得明文写入 spec:
- ❌ `LOGIN_PASSWORD='Admin@123456'`
- ✅ `LOGIN_PASSWORD='<LOGIN_PASSWORD>'`
- UUID 类业务测试数据(如 modelId、userId)可以保留,但认证凭据不可明文记录。

## A.7 方案确认(确认门)

**在调用 AskUserQuestion 并收到"确认通过"之前,禁止修改任何代码文件或读取 phase-b.md。**

**每次进入确认门前,无论经过几轮修改,必须先完成质量检查,再输出确认材料。**

### 质量检查(每次输出确认材料前执行)

重读本轮所有修改过的章节,逐项核查:

1. **三角一致性**:接口规范字段/参数 ↔ 数据库设计字段 ↔ 代码地图方法签名,三者对齐;发现不一致,以本轮用户意图为准统一修正
2. **任务可追溯**:每个 T-xxx 必须能在数据库设计(第二节)、接口规范(第三节)或代码地图(第五节)中找到对应条目;找不到则补充描述或调整任务范围
3. **断言可执行**:每个 A-xxx 的断言必须基于当前接口规范可以真实执行;若接口变了断言没更新,同步修正并重置状态
4. **全文连贯性**:通读已改章节,确认无拼接感、无遗留矛盾
5. **跨章节技术描述一致性**:若同一 SQL 片段、字段操作符或逻辑规则在多个章节均有描述,必须逐字核对,以代码实现为准统一;同一技术细节不得在不同章节出现两种写法
6. **验收项 ↔ DB 字段覆盖**:若 A-xxx 断言了某个数据库字段,检查第二章字段说明中是否有该字段的定义;缺失则补充字段说明

检查发现问题 → 先修正,再继续。检查通过后,先展示确认材料,再按标准调用序列调用 `AskUserQuestion`。

### 确认材料(必须先展示)

在调用确认器前,**重读本轮修改的章节**,确认摘要内容与文件实际一致,再向用户展示(禁止使用 `git diff` 作为唯一依据):

- **已有 spec 的增量修改**:展示受影响章节的"修改前/修改后"对照(至少覆盖本轮改动段落)
- **新建 spec 或大范围改写**:展示"最新 spec 内容"(至少包含第 1/3/6/7 节,必要时补充其余章节)

随后补充摘要:

```
**改写章节:** X 节(需求边界)、Y 节(接口规范)

**任务变更:**
- 新增:T-12(...),T-13(...)
- 重置:T-08(原✅ → 待开始,原因:接口签名变更)
- 取消:T-06(已取消,原因:...)(如有;无则省略)
- 保持:T-01 ~ T-05, T-07

**验收项变更:**
- 新增:A-09(...)
- 重置:A-05(原✅ → 待验证,原因:断言变更)
- 保持:A-01 ~ A-04

**待确认假设:** <如有;无则省略>
```

### AskUserQuestion 确认器

AskUserQuestion 调用模式同 step0.md(先 ToolSearch 获取 schema,再调用)。参数如下:
- `question`: `"请确认当前 spec"`
- `header`: `"Spec 确认"`
- `multiSelect`: `false`
- `options`:
  - `{ label: "确认通过,开始开发", description: "spec 已确认,进入 Phase B 按任务执行" }`
  - `{ label: "补充或澄清需求", description: "我会回到分析阶段,结合补充信息重新分析并更新 spec" }`

### 回应处理规则

- 选"确认通过,开始开发",且 Other 无补充 → 返回 SKILL.md Step 1,进入 Phase B
- 其他所有情况(选"补充或澄清需求"、或 Other 中含有任何修正/补充/澄清/"但是……")→ 视为方案尚未确认,必须从分析阶段重新开始:
  1. 将本轮确认轮次计数 +1(首次进入 A.7 时轮次为 1,每次重分析后递增),并在回应开头注明:"**当前第 N 轮分析**"
  2. 逐条理解用户反馈,复述新的需求边界与待确认点
  3. 说明将回到分析阶段重新推导方案(spec 未确认前不进入实现,以用户最新补充为最高优先输入)
  4. 回到 A.1(需求理解)→ A.2(受影响章节)→ A.3(全量证据分析)→ A.4/A.5/A.6(更新 spec)
  5. 完成后再次执行 A.7(含质量检查、确认材料展示、AskUserQuestion 确认);若已达**第 3 轮**,在展示确认材料前额外输出提示:
     ```
     ⚠️ 已进行 3 轮分析确认。如需求范围持续变动,建议先缩小本次交付范围,其余内容下轮 /spec-first 再处理。
     ```

**进入 Phase B 的唯一条件:用户选择"确认通过,开始开发"且没有任何保留意见。**

---

> **Checklist 更新**:进入 Phase B 前,输出更新后的开发周期进度 Checklist,将 Phase A 标为 `[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