zzusp/doc-first-dev / skills/spec-multi
spec-multi
Verified| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 1.8 KB |
| assets/multi-spec-blank.md | markdown | 1.3 KB |
| assets/services-index-blank.md | markdown | 559 B |
| error-handling.md | markdown | 1.6 KB |
| evals/eval-01-cross-service-feature.md | markdown | 2.5 KB |
| evals/eval-02-interface-drift.md | markdown | 1.8 KB |
| evals/eval-03-partial-service-change.md | markdown | 2.2 KB |
| init.md | markdown | 1.9 KB |
| phase-a.md | markdown | 4.3 KB |
| phase-b.md | markdown | 2.6 KB |
| phase-c.md | markdown | 6.1 KB |
| phase-d.md | markdown | 2.9 KB |
| step0.md | markdown | 1.2 KB |
phase-a.md
View on GitHub# Phase A — 链路追踪与需求文档填充
**本阶段只写文档,不修改任何服务代码。**
---
## A.1 复述需求
用 2-4 句话复述需求的核心目标和预期结果。不需要用户确认,直接进入 A.2。
---
## A.2 确定入口服务
读取 `docs/plans/SERVICES.md` 了解服务全景。
根据需求描述判断用户交互从哪个服务开始(通常是:前端页面触发 → 面向用户的 API → 内部数据服务)。
展示判断:
```
入口服务判断:<服务名>
理由:<一句话说明,如"需求从前端操作发起,frontend 是入口">
```
使用 AskUserQuestion 让用户确认或纠正。
---
## A.3 沿调用链追踪(读代码)
从入口服务的关键文件出发(Controller / Handler / Router / Page Component),读取代码:
1. 判断此处需要什么变更(新增方法/修改逻辑/新增页面等)
2. 若代码中有跨服务调用(HTTP 请求、RPC、消息队列等),追踪到被调用服务的对应入口文件
3. 递归执行直到链路末端
**记录格式:**
```
调用链路:
frontend(ExportPage.vue)→ backend(ExportController.export)→ data-service(DataHandler.process)
```
**边界规则:**
- 最多追踪 3 跳;超出时列出候选服务,使用 AskUserQuestion 询问用户是否继续追踪
- 若某跳服务无对应代码(新服务),标注"新建服务,待实现"
---
## A.4 确认受影响服务
使用 AskUserQuestion 展示:
- 完整调用链路图
- 每个受影响服务的变更类型(附代码中的依据,如"backend/ExportController.java 需新增 export 方法")
- 未在链路中的服务,明确标注"不涉及"及理由
用户可补充漏掉的服务或排除误判。确认后继续。
---
## A.5 填充需求文档
对每个受影响服务,可启动并行 subagent 收集信息。每个 subagent 负责:
1. 按需补读该服务关键代码(链路追踪中已读的可复用)
2. 整理该服务在此需求下需要变更的内容
汇总后,在需求文档中填充以下各节:
**数据库设计节**(仅对有 DB 变更的服务):
- 列出新增/修改的表和字段
- 若无 DB 变更,跳过本节
**接口定义节**:
- 提供方服务:完整定义接口(Method、路径、请求格式、响应格式、规则)
- 调用方服务:仅写"调用 `[<提供方>] <METHOD> <路径>`(见上方定义)",不重复字段
**代码地图节**:
- 按服务分小标题
- 每行格式:`` `文件路径:方法名()` — 职责描述 ``
**任务节**:
- 为每个受影响服务追加 T-xxx,含 `[服务名]` 标签
- 格式:`T-<序号> · [<服务名>] · P0/P1/P2 · 待开始 — 描述(file:method)`
- 优先级:P0 = 核心功能阻塞,P1 = 重要,P2 = 可选优化
- 序号全文档唯一递增
**验收节**:
- 为每个受影响服务追加单服务 A-xxx
- 追加 `[E2E]` 集成验收(覆盖完整跨服务请求链路)
- 格式:`A-<序号> · [<服务名>|E2E] · <接口/场景> · 待验证 — <具体请求+预期响应>`
- A-xxx 必须是可执行断言:含具体参数和预期结果,而非"功能正常"
**对抗性自审(每次写完 A-xxx 后立即执行,不等到 Phase C):**
以挑剔审查者视角逐条检查,发现问题原地修正:
1. 该断言是否在实现错误时也可能侥幸通过(如仅验证状态码、未验证字段值或数量)?→ 收紧断言
2. 是否遗漏关键边界场景(空值/非法参数、越权访问、重复提交、跨服务传参丢失)?→ 补充新 A-xxx
---
## A.6 更新涉及服务与依赖顺序节
根据 A.3 链路追踪发现的实际调用关系,更新需求文档顶部"涉及服务与依赖顺序"节:
```
1. data-service(链路末端,无跨服务依赖)
2. backend(调用 data-service,需后者先就绪)
3. frontend(调用 backend,需后者先就绪)
```
---
## A.7 确认门
使用 AskUserQuestion 展示确认材料:
```
受影响服务:<列表>
服务依赖顺序:<顺序>
任务汇总:backend 3 项,frontend 2 项,共 5 项
验收汇总:单服务 4 项,E2E 1 项,共 5 项
```
**用户确认后** → 进入 [phase-b.md](phase-b.md)
**用户提出修改** → 按影响范围局部重做对应步骤,最多 3 轮。超过 3 轮则提示用户拆分需求范围。
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 |