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-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]`。
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