requirement-refiner

name	requirement-refiner
description	从原始需求素材（PRD、会议纪要、设计文档等）提炼结构化开发需求文档。通过三层模板（意图层/边界层/关联层）和五条逻辑校验规则，生成逻辑自洽的需求文档，暴露缺失和矛盾。触发词："提炼需求"、"结构化需求"、"需求文档"、"需求整理"、"refine requirement"。适用于 AI Coding Agent 开发前的需求整理，也适用于人类开发者审查和完善需求。

Requirement Refiner：需求提炼器

将模糊、零散的需求素材转化为结构化、逻辑自洽的开发需求文档。

核心原理

Agent 开发出错有三类根因，对应三个元维度：

失败类型	元维度	回答的核心问题
不知道做什么	意图层	要解决什么问题？为谁？成功标准？
不知道不做什么	边界层	做什么？不做什么？约束条件？
理解自相矛盾	关联层	各部分如何关联？数据/状态如何流转？

模板概要

10 个必填字段，每个字段的存在都有推导依据。详细定义和示例见 template.md。

意图层 ─── 问题陈述
        ├── 用户与场景
        └── 成功标准

边界层 ─── 功能范围
        ├── 显式排除
        ├── 约束条件
        └── 异常与边界情况

关联层 ─── 数据模型          [前端：API 响应结构 + 组件 state]
        ├── 状态流转          [前端：UI 状态机（加载/成功/失败）]
        ├── 交互流程          [前端：用户操作 → 界面响应链路]
        └── 依赖关系          [前端：API 端点 + 设计系统组件 + 路由]

字段名是通用的，不同角色填充的内容类型不同。前端开发者看到关联层字段时，直接按方括号内的提示理解即可。不相关的字段填「不适用：[原因]」。

三阶段工作流

阶段一：提取与填充

1. 读取用户提供的所有需求素材
2. 按模板 10 个字段逐个提取信息，按层顺序填充（意图层 → 边界层 → 关联层）
3. 每个字段标注信息来源（哪个文档的哪段内容）
4. 无法从素材中提取的字段标记为 ⚠️ 待确认
5. 每填完一个层，执行层内校验

阶段二：校验与补全

运行 5 条逻辑校验规则：

规则	检查什么
实体覆盖	数据模型的每个实体，在功能范围中是否都有对应操作？
状态闭环	状态流转中每个终态是否可达？每个状态是否有出口？
流程-状态对齐	交互流程的每步操作，在状态流转中是否有对应转换？
排除一致性	显式排除的功能，是否与功能范围或约束条件矛盾？
异常-功能覆盖	功能范围的每个功能，是否都考虑了异常情况？

校验结果标记：

• ❌ 矛盾 — 字段间逻辑不一致，附具体矛盾描述
• ⚠️ 待确认 — 字段缺失或信息不足，附补充建议

交互模式：非阻塞式。所有 ⚠️ 和 ❌ 项及其建议写入输出文档，用户事后审查决定是否采纳。

阶段三：输出

生成结构化开发需求文档，格式如下：

# [需求名称] — 开发需求文档

## 意图层

### 问题陈述
[内容或 ⚠️ 待确认]

### 用户与场景
[内容或 ⚠️ 待确认]

### 成功标准
[内容或 ⚠️ 待确认]

## 边界层

### 功能范围
[内容或 ⚠️ 待确认]

### 显式排除
[内容或 ⚠️ 待确认]

### 约束条件
[内容或 ⚠️ 待确认]

### 异常与边界情况
[内容或 ⚠️ 待确认]

## 关联层

### 数据模型
[内容或 ⚠️ 待确认]

### 状态流转
[内容或 ⚠️ 待确认]

### 交互流程
[内容或 ⚠️ 待确认]

### 依赖关系
[内容或 ⚠️ 待确认]

## 校验结果

### ❌ 矛盾
- [矛盾描述及建议修复方向]

### ⚠️ 待确认
- [缺失项及补充建议]

## 信息溯源表

| 字段 | 来源文档 | 来源段落/位置 |
|------|---------|-------------|
| 问题陈述 | [文档名] | [段落] |
| ... | ... | ... |

关键原则

1. 字段粒度自适应：模板只定义 10 个必填字段，字段内部子结构由 Agent 根据需求规模决定。简单需求用一段文字即可，复杂需求可展开为实体关系图、状态机图等。

2. ⚠️ 待确认不是失败：原始需求不完整是常态。目标不是强行填充每个字段，而是把缺失变成显性知识。

3. 关联层允许「不适用」：关联层的字段（数据模型、状态流转、交互流程、依赖关系）对纯 UI 展示或无状态需求可能不相关。此时填写「不适用：[原因]」而非强行填充或标记 ⚠️。「不适用」是确认性的判断，不是缺失。

4. 信息溯源：每个字段标注来源，方便用户追溯和验证提取的准确性。

5. 按层校验，条件适配：填完一层后校验层内一致性，全部填完后执行跨层校验。当「状态流转」字段标记为「不适用」时，跳过「状态闭环」和「流程-状态对齐」校验，仅执行其余 3 条。

6. 聚焦业务需求，技术上下文由项目文档提供：本模板只承载业务需求的结构化。技术栈、项目结构、代码风格等技术上下文应由项目的 AGENTS.md / CLAUDE.md 等文档提供，不在此文档范围内。Agent 开发时应同时参考本需求文档和项目技术文档。