Skip to content

zzusp/doc-first-dev / skills/spec-multi

spec-multi

Verified

FileKindSize
SKILL.mdskill md1.8 KB
assets/multi-spec-blank.mdmarkdown1.3 KB
assets/services-index-blank.mdmarkdown559 B
error-handling.mdmarkdown1.6 KB
evals/eval-01-cross-service-feature.mdmarkdown2.5 KB
evals/eval-02-interface-drift.mdmarkdown1.8 KB
evals/eval-03-partial-service-change.mdmarkdown2.2 KB
init.mdmarkdown1.9 KB
phase-a.mdmarkdown4.3 KB
phase-b.mdmarkdown2.6 KB
phase-c.mdmarkdown6.1 KB
phase-d.mdmarkdown2.9 KB
step0.mdmarkdown1.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 轮则提示用户拆分需求范围。
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