# specifier

把复杂需求整理成经过多轮人工评审的 HTML PRD，并在批准后生成交给 long-ship 执行的需求 handoff。

## 什么时候使用

- 要做跨模块、跨页面、跨服务或带数据迁移的复杂功能。
- 要先写 PRD、比较方案、梳理风险，再进入开发。
- 需要把 PRD 给人反复评审，确认后再交给 `long-ship`。

小改动直接使用 `short-ship`；已知 Bug 使用 `/hunt`；单次架构取舍使用 `/think`。

## 使用前准备

- 同时安装 `ship`；批准后的开发走 `long-ship`。
- 项目应位于 Git 仓库中，便于读取现有代码、文档和历史决策。
- 用户需要参与 PRD 评审，并明确批准具体版本。
- 不需要外部账号或网络资源；生成的 HTML 应能离线打开。

## 使用示例

```text
用 specifier 处理“给后台增加多租户权限管理”这个复杂需求：先调研现状，生成 HTML PRD，
我会逐轮评审。批准后再生成 long-ship handoff，不要提前派开发。
```

## Agent 会做什么

1. 判断需求是否需要重量级规格化，读取项目现状和相关决策。
2. 形成目标、范围、非目标、方案、交互/架构、风险、依赖和可观测验收。
3. 生成可离线打开的版本化 HTML PRD；保留每个历史版本并记录本轮变更。
4. 根据用户意见反复修改，直到用户明确批准指定版本。
5. 仅在批准后生成 `spec/handoff.yaml`，供 `long-ship` 创建和执行任务。
6. 用户需要查看 HTML 时，按独立 `previewer` 的契约直接执行共享 Node 脚本，返回 HTTP URL
   和有效期；跨设备查看时可显式设置监听地址。

Specifier 只负责需求规格，不修改业务代码，也不替代 long-ship 的开发和独立测试。

## 如何判断完成

- 评审阶段：得到一个带版本号的 HTML PRD、变更记录、风险和未决问题。
- 交接阶段：用户明确批准某个版本，且 `spec/handoff.yaml` 绑定了该版本和完整验收信息。
- 开发阶段：改用 `long-ship`，任务和证据写在同一个 ship id 下。