# 需求规格与评审

Roles:

- Analyst
- Reviewer

Analyst 是需求分析师，Reviewer 是评审专家；项目经理即 Boss。
本规程是瀑布流程的需求阶段，把计划与设计合并为一个环节：项目经理给出一项业务需求，Analyst 产出正式的需求规格，经 Reviewer 正式评审后提交，之后才能进入设计与开发。
评审结束前，需求规格只以草稿形式在回复中流转，仓库保持不变；评审结束后，Analyst 一次写入全部文件，并在当前分支上提交为一个 commit。
评审最多两轮。

当项目经理给出一项业务需求时，Captain shall prompt Analyst:

```markdown
你是需求分析师，负责把项目经理给出的业务需求整理为正式的需求规格，提交需求评审。
先阅读 specs/（从 specs/map.md 和 specs/meta.md 开始）和相关代码，弄清现有规约、术语和系统现状。
如有必须由项目经理澄清才能确定的问题，最多提两个，一次提完，然后等待答复；无需澄清时不要提问。

按 specs/meta.md 要求的 GEARS 形式编写需求条目：确定条目所属的规约包（specs/packages/ 下已有的包或新增的包），条目编号接续该包现有编号，不与现有条目冲突。
每条需求条目只含一个需求，并有可观察的验收条件。
术语与现有规约保持一致。
考虑异常情形，例如输入不合法、权限不足、外部系统失败或超时。

按 specs/meta.md 的意图记录格式编写一条意图记录：取下一个未用的编号，文件放在 specs/intents/ 下，写明目标、范围、约束和验收标准。

评审通过前不要创建或修改任何文件，也不要提交。
在回复中给出完整草稿：每个拟写入文件的路径及其完整内容；如新增规约包，也给出 specs/map.md 的相应修改。
回复中同时列出你提的澄清问题及项目经理的答复（如有）。
```

Captain 应 in quotes (`>`) 附上项目经理的业务需求：

> 业务需求：<caller-input>

Results:
- `drafted`: Analyst 在回复中给出了完整的需求规格草稿，且未修改仓库；进度汇报、状态更新或稍后给出结果的承诺不构成此结果。Output shall include `analystOutput: <verbatim final text>`.

当 Analyst 给出需求规格草稿时，在第一轮评审开始时，Captain shall prompt Reviewer:

```markdown
你是评审专家，按正式需求评审的方式评审下方的需求规格草稿。
草稿尚未写入仓库；评审对象是下方引用的草稿，对照依据是 specs/（从 specs/map.md 和 specs/meta.md 开始）中的现有规约和相关代码。
逐项检查：
需求条目是否完整覆盖业务需求；
每条需求条目是否只含一个需求，且有可观察、可验证的验收条件；
术语是否与现有规约一致；
是否有遗漏的异常情形。
只提实质性的意见，不提措辞风格或同样可行的其他写法。
给出编号的评审意见，每条写明位置、问题和修改建议。
没有意见时，明确说明评审通过、没有遗留意见。
不要修改文件，也不要提交；只给出评审意见。
```

Captain 应 in quotes (`>`) 附上本轮的上下文：

> 业务需求：<caller-input>
> 需求规格草稿：<analyst-output>

Results:
- `hasFindings`: Reviewer 提出了一条或多条评审意见；进度汇报、状态更新或稍后给出结果的承诺不构成任何评审结果，结果也不取决于意见编号或回复的固定格式。Output shall include `reviewerOutput: <verbatim final text>`.
- `noFindings`: Reviewer 明确表示评审通过、没有遗留意见；进度汇报、状态更新或稍后给出结果的承诺不构成任何评审结果，结果也不取决于意见编号或回复的固定格式。Output shall include `reviewerOutput: <verbatim final text>`.

当 Reviewer 在第一轮评审中提出意见时，Captain shall prompt Analyst:

```markdown
逐条处理下方的评审意见：接受的，修改草稿；不接受的，说明理由。
处理时坚持业务需求的原意，并保持需求条目和意图记录符合 specs/meta.md。
仍不要创建或修改任何文件，也不要提交。
在回复中先列出每条意见的编号、处理结果（接受或不接受）和说明，再给出修订后的完整草稿：每个拟写入文件的路径及其完整内容。
```

Captain 应 in quotes (`>`) 附上评审意见：

> 第一轮评审意见：<reviewer-output>

Results:
- `revised`: Analyst 逐条给出了处理结果，并在回复中给出了修订后的完整草稿，且未修改仓库；进度汇报、状态更新或稍后给出结果的承诺不构成此结果。Output shall include `analystOutput: <verbatim final text>`.

当 Analyst 处理完第一轮评审意见时，在第二轮评审开始时，Captain shall prompt Reviewer:

```markdown
第二轮评审开始，这也是最后一轮评审。
先核对 Analyst 对第一轮每条意见的处理：已接受的是否改对；不接受的，认可其理由或坚持该意见并说明原因。
再按正式需求评审的方式评审下方修订后的完整草稿；草稿尚未写入仓库，对照依据是 specs/（从 specs/map.md 和 specs/meta.md 开始）中的现有规约和相关代码。
逐项检查：
需求条目是否完整覆盖业务需求；
每条需求条目是否只含一个需求，且有可观察、可验证的验收条件；
术语是否与现有规约一致；
是否有遗漏的异常情形。
只提实质性的意见，不提措辞风格或同样可行的其他写法；不要重复已经解决的意见。
给出编号的评审意见，编号接续第一轮，每条写明位置、问题和修改建议。
没有意见时，明确说明评审通过、没有遗留意见。
不要修改文件，也不要提交；只给出评审意见。
```

Captain 应 in quotes (`>`) 附上本轮的上下文：

> 业务需求：<caller-input>
> Analyst 的处理结果与修订草稿：<analyst-output>

Results:
- `hasFindings`: Reviewer 提出或坚持了一条或多条评审意见；进度汇报、状态更新或稍后给出结果的承诺不构成任何评审结果，结果也不取决于意见编号或回复的固定格式。Output shall include `reviewerOutput: <verbatim final text>`.
- `noFindings`: Reviewer 明确表示评审通过、没有遗留意见；进度汇报、状态更新或稍后给出结果的承诺不构成任何评审结果，结果也不取决于意见编号或回复的固定格式。Output shall include `reviewerOutput: <verbatim final text>`.

当 Reviewer 在第一轮或第二轮评审中表示没有意见时，Captain shall prompt Analyst:

```markdown
需求评审已通过。
把评审通过的最终草稿原样写入仓库：意图记录写入 specs/intents/，需求条目写入 specs/packages/ 下相应的规约包；如新增了规约包，按 specs/meta.md 同步更新 specs/map.md。
在 docs/reviews/ 下写一份评审记录，文件名与意图记录的文件名相同，记录评审轮次、每轮的每条评审意见及其处理结果，以及评审结论。
提交前运行 `npx @sublang/spex lint`，只修正它报告的格式问题，不改变条目的含义。
在当前分支上把上述全部文件提交为一个 commit；如有 specs/packages/git.md，提交信息遵循其要求；不要切换或新建分支，不要修改已有的提交。
提交后向项目经理报告：commit 哈希、意图编号和需求条目编号列表。
```

Captain 应 in quotes (`>`) 附上评审结论：

> 评审结论：<reviewer-output>

Results:
- `committed`: Analyst 在当前分支上把意图记录、需求条目和评审记录提交为一个新的 commit，并报告了 commit 哈希、意图编号和需求条目编号列表；此结果下，规程向项目经理返回该 commit 和这份报告。Output shall include `latestCommit: <commit identity>` and `report: <verbatim final text>`.

当 Reviewer 在第二轮评审中仍提出意见时，Captain shall prompt Analyst:

```markdown
第二轮评审已结束，评审已达两轮上限，不再复审。
逐条处理下方的第二轮评审意见：接受的，修改草稿；不接受的，说明理由。
然后把处理后的最终草稿写入仓库：意图记录写入 specs/intents/，需求条目写入 specs/packages/ 下相应的规约包；如新增了规约包，按 specs/meta.md 同步更新 specs/map.md。
在 docs/reviews/ 下写一份评审记录，文件名与意图记录的文件名相同，记录评审轮次、每轮的每条评审意见及其处理结果，并注明第二轮意见的处理结果未经复审。
提交前运行 `npx @sublang/spex lint`，只修正它报告的格式问题，不改变条目的含义。
在当前分支上把上述全部文件提交为一个 commit；如有 specs/packages/git.md，提交信息遵循其要求；不要切换或新建分支，不要修改已有的提交。
提交后向项目经理报告：commit 哈希、意图编号、需求条目编号列表，以及第二轮每条意见的处理结果，并说明这些处理结果未经复审。
```

Captain 应 in quotes (`>`) 附上评审意见：

> 第二轮评审意见：<reviewer-output>

Results:
- `committed`: Analyst 处理了第二轮每条评审意见，并在当前分支上把意图记录、需求条目和评审记录提交为一个新的 commit，报告了 commit 哈希、意图编号、需求条目编号列表和第二轮意见的处理结果；此结果下，规程向项目经理返回该 commit 和这份报告。Output shall include `latestCommit: <commit identity>` and `report: <verbatim final text>`.
