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 |
step0.md
View on GitHub# Step 0 — 接收需求,匹配文档
## Contents
- 0.1 确认输入
- 0.2 意图分类
- 0.3 匹配文档,呈现选择器
---
## 0.1 确认输入
检查用户是否提供了具体的需求或变更描述:
**无输入时**,输出以下提示,停止,等待用户补充,不执行后续步骤:
```
请描述您的需求或变更内容,例如:
· 给用户列表新增按名称模糊搜索
· 修复订单导入时出现重复数据的问题
· 版本发布需要支持批量选择数据集
```
**有输入时**,继续执行 0.2。
## 0.2 意图分类
根据用户描述判断意图类型:只读分析(仅分析不修改代码)、信息检索(定位文档内容后输出结果)、或开发任务。判断不清时默认视为开发任务。所有类型均继续执行 0.3。
## 0.3 匹配文档,呈现选择器
1. 读项目的模块索引文件(通常为 `docs/plans/PROJECT.md`,以项目 CLAUDE.md 中的约定为准),获取全量模块清单和 spec 路径。若读取失败,跳至步骤 3。
2. 根据需求描述,从一级模块名称、二级模块名称、功能点描述中,找出相关性最高的 1–3 个 spec 文档。若未找到置信度足够的匹配(0 个候选,或候选与需求描述无关键词或语义重叠),跳至步骤 3。
3. **兜底扫描**(由步骤 1 文件缺失或步骤 2 匹配失败触发):
- 使用 Glob 工具扫描 `docs/plans/**/*.md`,排除 `PROJECT.md` 和 `init-report.md`,收集所有 spec 文件路径
- 使用 Grep 工具搜索所有文件的 `# ` 开头行,一次操作获取全部标题作为 label
- 将所有扫描到的 spec 全部列入选择器,由用户判断
- 在选择器 header 中注明触发原因:步骤 1 触发时用 `"PROJECT.md 不存在,以下为目录扫描结果"`;步骤 2 触发时用 `"未在 PROJECT.md 中找到匹配模块,以下为目录扫描结果"`
4. 先调用 `ToolSearch`(query: `"select:AskUserQuestion"`)获取工具 schema,然后调用 `AskUserQuestion` 工具呈现文档选择器。
`AskUserQuestion` 是延迟加载工具,不做 ToolSearch 直接调用会失败并退化为渲染 JSON 文本,必须先获取 schema。**全文件所有 AskUserQuestion 调用均遵循此序列:先 ToolSearch,再调用。**
调用参数结构如下(这是参数说明,不是展示给用户的内容):
- `question`: `"请选择对应的技术方案文档"`
- `header`: 正常匹配时用 `"技术文档"`;兜底扫描时按步骤 3 的触发原因填写
- `multiSelect`: `false`
- `options`: 填入匹配到的 spec(最多 3 个,为"Other"留位;兜底扫描时列出全部结果,不限 3 个),每项包含:
- `label`: 模块编号/名称
- `description`: spec 文件路径 + 功能点摘要
- "Other"由工具自动提供,覆盖两种情况:手动指定路径、或说明需要新建文档
**处理用户选择:**
- 选择某个 spec → 读取对应 spec 全文 → 返回 SKILL.md 进入 Step 1
- 选择"Other"且用户提供了路径 → 读取该 spec → 返回 SKILL.md 进入 Step 1
- 选择"Other"且用户说明需要新建 → 询问模块名称和目标路径;读取 `skills/spec-first/assets/tech-spec-blank.md` 作为骨架,将其中 `<模块名>` 占位符替换为用户提供的模块名后写入目标路径 → 返回 SKILL.md Step 1 进行阶段判断
**无论哪种情况,读取 spec 后必须输出以下确认块,再进入下一步:**
```
┌─ 工作文档已建立 ──────────────────────────────────
│ 路径:docs/plans/<module>/xxx-tech-spec.md
│ 设计规则已加载 · 任务状态已加载 · 验收标准已加载
│ ⛔ 若进入 Phase A:spec 确认前(A.7)不修改任何代码文件
└───────────────────────────────────────────────────
```
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 |