zzusp/doc-first-dev / skills/spec-first
spec-first
Verified管理项目模块的完整开发周期:需求分析→更新技术方案→spec确认→开发→验收→收尾。适用于功能新增、Bug修复、需求变更、接口调整、重构、字段增删等涉及代码变更的任务;项目下有或无 spec 文档均可触发,无需用户明确指定流程。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.9 KB |
| assets/api-blank.md | markdown | 2.7 KB |
| assets/claude-md-snippet.md | markdown | 1.8 KB |
| assets/project-index.md | markdown | 1.7 KB |
| assets/tech-spec-blank.md | markdown | 4.8 KB |
| error-handling.md | markdown | 1.4 KB |
| evals/eval-01-new-feature.md | markdown | 1.8 KB |
| evals/eval-02-spec-code-mismatch.md | markdown | 1.3 KB |
| evals/eval-03-init-flow.md | markdown | 1.2 KB |
| init.md | markdown | 1.2 KB |
| phase-a.md | markdown | 10.5 KB |
| phase-b.md | markdown | 4.9 KB |
| phase-c.md | markdown | 6.8 KB |
| phase-d.md | markdown | 5.3 KB |
| step0.md | markdown | 3.9 KB |
phase-c.md
View on GitHub# Phase C — 验收
> **上下文隔离策略**:同 Phase B,C.2/C.3/C.4 均通过 subagent 执行,结论返回主会话,过程信息不污染主会话上下文。
## C.0 前置检查:确认所有任务已完成
**进入验收前,必须先扫描第六节(任务状态)**,若存在状态为"待开始"或"进行中"的 T-xxx,**拒绝进入验收**,输出:
```
⛔ 以下任务尚未完成,无法进入验收阶段:
- T-xx(待开始):<内容摘要>
- T-xx(进行中):<内容摘要>
请先在 Phase B 完成或取消上述任务,再进入 Phase C。
```
所有 T-xxx 均为 ✅ 完成或"已取消"后,继续执行 C.1。
## C.1 准备
**具体的启动和认证命令以项目根目录 `CLAUDE.md` 中的"启动与认证"章节为准。**
通常需要:
1. 启动应用(参考 CLAUDE.md 启动命令);若 CLAUDE.md 中无"启动应用"章节,分析项目文件(`README`、`docker-compose.yml`、`package.json`、`pom.xml` 等)推断启动命令并尝试执行;启动成功后,按 `assets/claude-md-snippet.md` 中"启动应用"章节的格式将命令补充写入项目 `CLAUDE.md`;若无法推断,假设应用已在外部运行,直接执行 C.2
2. 获取认证信息,保存请求头(参考 CLAUDE.md 认证命令);若 CLAUDE.md 中无"获取认证 Token"章节,分析项目(README、登录接口、认证中间件等)推断认证方式并尝试获取 token;成功后,按 `assets/claude-md-snippet.md` 中"获取认证 Token"章节的格式将命令补充写入项目 `CLAUDE.md`;若无法推断,跳过此步
3. 验证 spec 第七节中的测试数据(UUID/ID/账号)是否仍有效
## C.2 逐条执行 A-xxx
**执行范围**:仅运行状态为"待验证"或"未通过"的 A-xxx,跳过已为 ✅ 的项(用于 C.3 修复后重入时避免重跑已通过测试)。
**验收 subagent 的信息边界(角色:验证者):** 仅接收 A-xxx 定义、第七节测试数据与认证信息,**不传入实现细节**(T-xxx 内容、代码地图、实现方案等)。C.3 中另有**诊断 subagent(角色:排查者)**,持有完整实现上下文负责根因分析,两者职责严格区分。
对每条待验证的 A-xxx:
1. subagent 真实调用 HTTP / 真实执行 SQL,记录证据(HTTP 状态码 + 响应摘录,或 SQL 结果),返回判定结论(pass / fail 二元)——"基本通过"无法作为交付证据
2. 主会话根据 subagent 返回结论,执行两个写入操作:
- **更新 A-xxx 行状态**(原地):标记 ✅ 或 ❌
- **追加一行到验收历史记录表**(只增不改):若 spec 中尚无该表,在第七节末尾新建;每轮每项均追加一行,**已有行不修改**
验收历史记录表格式:
```markdown
### 验收历史记录
| 轮次 | 项 | 结论 | 证据摘要 | 根因(失败时) |
|------|-------|------|---------------------------------------|------------------------|
| R1 | A-05 | ❌ | POST /item/list → 500 | NPE at ItemService:42 |
| R1 | A-07 | ✅ | GET /item/1 → 200, name:张三 | — |
| R2 | A-05 | ✅ | POST /item/list → 200, total:3, 含张三 | — |
```
轮次 R{N} 与 C.3 步骤 3 中的循环计数器 N 保持一致;首轮记为 R1。
## C.2.5 对抗性审查
本轮实际执行的 A-xxx 全部完成后,**在进入 C.3 前**,以挑剔审查者视角扫描本轮执行结果(已跳过的 ✅ 项在首轮已审查,不需重复):
1. 哪些 A-xxx 在实现错误的情况下也可能"侥幸通过"(例如:断言过于宽松、仅验证状态码未验证字段值)?
2. 有无边界场景(空值/越权/并发写入/重复提交)未被当前 A-xxx 覆盖?
**处理规则:**
- 发现宽松断言 → 直接收紧对应 A-xxx 描述,重新执行该条
- 发现盲区场景 → 补充新 A-xxx 并立即执行
- 无问题 → 继续 C.3
## C.3 失败处理
有 A-xxx 未通过时,先修复再继续——下一阶段的验收建立在当前阶段已通过的基础上:
1. subagent 诊断根因(查日志、查 DB),以**压缩摘要**(根因 + 建议,不超过 3 行)返回主会话,过程日志留在 subagent 内部不带回主会话
2. **归因判断**:主会话根据摘要判断失败根因属于哪类:
- **实现 bug**(代码逻辑错误、字段遗漏、SQL 写错等)→ 继续步骤 3
- **spec/设计问题**(接口设计有缺陷、验收标准错误、方案层面假设有误)→ 暂停并输出:
```
⛔ 验收失败根因属于方案层面问题,回 Phase B 修代码无法解决:
- 问题:<具体描述>
- 涉及 A-xxx:<列表>
请决定:
A) 回 Phase A 重新分析方案
B) 调整验收标准后继续
C) 跳过该项,记录为待后续迭代
```
等待用户选择后按指示执行,不进入后续步骤
3. 在 spec 第七节末尾(验收历史记录表之后)更新循环计数器:首轮失败时新增该行并初始化 N=1,后续每轮递增 N;"最近一次失败"每轮覆盖写入当前失败项:
```
验收循环次数:N(最近一次失败:A-xx, A-xx)
```
**若 N ≥ 3**,强制暂停,从验收历史记录表中提取所有 ❌ 行,输出后等待用户选择:
```
⚠️ 已进行第 N 轮验收循环,建议重新评估方案:
R1 A-05 ❌ — <证据摘要> | 根因:<根因>
R2 A-05 ❌ — <证据摘要> | 根因:<根因>
R{N} A-05 ❌ — <证据摘要> | 根因:<根因>
请决定:
A) 继续修复(进入第 N+1 轮)
B) 回 Phase A 重新分析
C) 挂起当前任务
```
用户选择 A 后方可继续;N ≥ 3 的每一轮均需用户确认
4. 主会话向用户报告:"A-xx 未通过。原因:<根因>。建议:<方案>";将对应 T-xxx 状态重置为"待开始",同时扫描所有 ✅ 的 A-xxx——若其断言涉及该 T-xxx 关联的接口或字段,一并重置为"待验证"(防止修复引入回归)。回到 Phase B 修复,完成后重标 ✅;重新经过 C.0 前置检查,若应用仍在运行可跳过 C.1,重跑所有状态为"未通过"或"待验证"的 A-xxx(已 ✅ 的跳过)
5. 重验通过后,更新 A-xxx 行状态为 ✅,并在验收历史记录表追加对应的 ✅ 行(含证据摘要),无需额外注释——历史表本身即为完整的修复证据链
## C.4 非功能验收
功能项全部通过后,由 subagent 执行第七节中用户定义的非功能类 A-xxx(构建已在 B.4 验过,此处跳过),结论返回主会话更新对应 A-xxx 状态。
所有 A-xxx ✅ 后,读取 [phase-d.md](phase-d.md) 进入 Phase D。
---
> **Checklist 更新**:进入 Phase D 前,输出更新后的开发周期进度 Checklist,将 Phase C 标为 `[x]`。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |