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

View on GitHub
# Phase B — 按方案开发

> **上下文隔离策略:** B.1 制定计划在主会话执行;B.2 代码实现和 B.4 构建验证应使用 **subagent**(Agent 工具)执行,在独立上下文中运行,完成后仅返回结论和关键证据给主会话,过程日志不会污染 spec 分析所需的上下文。
>
> **使用方式:** 对每个可独立执行的任务,通过 Agent 工具创建 subagent,在独立上下文中完成代码修改、构建等操作。subagent 完成后向主会话返回结果摘要,主会话更新 spec 中的 T-xxx/A-xxx 状态。

## B.0 执行就绪检查

在制定执行计划前,依次确认以下 4 项:

| 维度 | 检查 | 未满足时 |
|------|------|---------|
| 意图 | spec 第 7 节有至少一个可执行的 A-xxx 验收项 | 返回 Phase A 补充验收项后再进入 Phase B |
| 定位 | spec 第 6 节所有待执行 T-xxx 包含具体文件名和方法/类名 | 原地补全定位信息后继续 |
| 构建 | `CLAUDE.md` 中有构建命令,或可从项目文件推断 | 推断并记录后继续(详见 B.4)|
| 边界 | 本次任务是否涉及跨团队接口或外部服务依赖 | 向用户说明依赖关系,确认后继续 |

全部满足后继续 B.1。

## B.1 分析依赖,制定执行计划

读第六节,列出所有"待开始"/"进行中"的 T-xxx。**"进行中"表示上次 session 中断留下的断点标记,对应 subagent 已不存在,应视同"待开始"从头执行。** 若发现"进行中"的 T-xxx,先输出提示 `"检测到上次中断的任务 T-xx,将从头重新执行"`,再将状态改为"待开始"继续流程。

按以下原则分组:

**并行组划分原则:**
- 同一文件的多处修改 → 串行(避免冲突)
- 不同文件且无逻辑依赖 → 并行
- P0 先于 P1 先于 P2;同优先级内再判断是否可并行

输出执行计划后直接开始执行(Phase A 已确认,无需再次等待):

```
执行计划:
- 第 1 批(并行):T-12(XxxServiceImpl)、T-13(XxxMapper.xml)
- 第 2 批(串行):T-14(依赖 T-12 的结果)
```

## B.2 按批次执行

执行分两个阶段,时序如下:

**发起前**:主会话将本批所有 T-xxx 状态统一写为"进行中"(断点标记,用于 session 中断恢复),然后在单条消息中并行发起本批所有 subagent。

**收到结果后**:每个 subagent 返回后,主会话立即将该 T-xxx 状态写为 ✅ 完成(不等整批全部返回,逐条串行写入)。subagent 只执行代码,不写入 spec。若同批中某任务执行失败(编译错误、依赖缺失等普通执行错误),subagent 停止并向主会话报告失败原因,主会话定位问题后重试或按 B.3 处理(若失败原因是 spec 与代码不符);同批中其他已完成任务保持 ✅,不整批回滚。

**subagent 返回的最小结构**(主会话据此更新 spec 状态,格式固定):

```
任务:T-xx
状态:✅ 完成 / ❌ 失败
修改文件:<路径列表,每行一个>
关键发现:<若有 spec 偏差或需主会话决策的问题,在此说明;无则省略此行>
```

## B.3 发现偏差时立即暂停

若 subagent 实现中发现 spec 与实际代码不符:
1. subagent 停止并向主会话报告差异详情
2. 主会话向用户说明:"spec 第 5 节写的是 X,实际代码是 Y,导致 Z 无法按方案实现"
3. 主会话提出解决方案,等用户确认后继续:
   - 若选"以代码为准更新 spec"→ 主会话原地改写 spec 对应章节(通常第 3/5 节),重新发起 subagent 按更新后的 spec 执行该任务
   - 若选"以 spec 为准修改代码"→ 重新发起 subagent 按 spec 原始方案实现,不修改 spec

**同批多个 subagent 同时报告偏差时**:主会话等待本批所有 subagent 返回(或超时),将全部偏差汇总为**一次**用户确认,按偏差逐条展示并列出选项(以代码为准 / 以 spec 为准),一次性收集用户决策后再统一处理,不逐个中断打扰用户。

## B.4 构建验证

所有 T-xxx 完成后,按项目根目录 `CLAUDE.md` 中"构建命令"章节运行构建验证。

**若 CLAUDE.md 中无"构建命令"章节**:分析项目文件(`package.json`、`pom.xml`、`go.mod`、`Makefile`、`build.gradle` 等)推断构建命令并尝试执行;执行成功后,按 `assets/claude-md-snippet.md` 中"构建命令"章节的格式将命令补充写入项目 `CLAUDE.md`,再继续;若无法推断,向用户报告并等待用户提供构建命令或明确确认跳过,不自动跳过——未经构建验证的代码进入验收大概率失败。

构建通过后**立即**读取 [phase-c.md](phase-c.md) 进入 Phase C,不等待用户确认。若构建失败,subagent 定位失败原因并尝试修复后重跑;反复失败时 subagent 停止并向主会话报告,等确认后继续。

---

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