hany-require

name	hany-require
description	需求确认+示例原型。触发：/hany:require。Brainstorming+Deep-interview式提问→歧义评分→确认需求→输出可行示例+技术说明+架构图+思维过程。
author	hany
version	1.1

hany-require — 需求确认 & 示例原型

触发方式：/hany:require

核心原则：不猜测，不确定就问。指出方案中不合理的地方。给出的方案必须理论上可行、可验证。

快速路径：AI 在 Step 0 中自动判断复杂度，简单需求走 Step 0→1(简化)→5(快速收敛)→10→11。Step 1 简化为只读项目结构和关键文件，跳过 git 历史和 rules.md。复杂需求走全流程。

强制交互规则

详见 hany-common/procedures/interaction_rules.md

质量模式

详见 hany-common/procedures/quality_modes.md

编码约束：读取 hany-common/rules/rules.md，11 条规则全程生效。

概览（必读）

调用方：可独立触发 /hany:require，也可由 hany-auto Step 2 自动调用。

[按需加载] 本文件包含完整步骤手册。执行时：

1. 启动阶段：仅读快速参考卡和"Step 0"即可开始
2. 执行阶段：用 Read(offset/limit) 跳读到对应 Step 章节（参考下方行号区间）
3. 已完成阶段：用 3 行摘要替代详细内容，释放上下文

行号参考（offset 跳读用）：Step 0 约第 76 行 | Step 1 约第 88 行 | Step 2 约第 100 行 | Step 3 约第 112 行 | Step 4 约第 131 行 | Step 5 约第 143 行 | Step 6 约第 185 行 | Step 7 约第 189 行 | Step 8 约第 195 行 | Step 9 约第 208 行 | Step 10 约第 214 行 | Step 11 约第 238 行

快速参考卡

阶段	核心动作	确认节点
Step 0	先想想看，输出思路	—
Step 1	探索上下文（项目结构+关键文件+git 历史）	—
Step 2	Brownfield/Greenfield 检测	—
Step 3	模糊度判断 + 智能推导意图	AskUserQuestion
Step 4	大项目拆分检查（涉及多子系统时）	AskUserQuestion
Step 5	多轮提问（歧义评分+挑战者模式+实体追踪）	每轮 AskUserQuestion
Step 6	需求去重精简	AskUserQuestion
Step 7	多方案对比	AskUserQuestion
Step 8	需求自检	—
Step 9	需求持久化到 docs/hany/requirements/	—
Step 10	输出示例原型（代码+技术说明+设计思路）	—
Step 11	最终确认，引导触发 /hany:implement	AskUserQuestion

概览工作流程

见上方快速参考卡（按顺序从 Step 0 到 Step 11）。

需求文档规范

关键规则：

• Step 9 写入：路径 docs/hany/requirements/YYYY-MM-DD-<主题>.md
• status 标记：初始 in_progress，完成后 completed
• 歧义评分：必须 ≤ 质量模式对应阈值（strict:10%, standard:20%, minimal:30%）
• [NEEDS CLARIFICATION]：写入前必须全部消除
• 拆分规则：多子系统独立文档 YYYY-MM-DD-<主题>-<子系统>.md

标准格式（Step 9 写入时使用）

---
status: in_progress
author: [作者]
version: "[版本]"
created: [日期]
---

# [主题名称]

## 目标
[一句话描述最终想要什么]

## 详细需求
### 需求项 1
[描述]

## 输入/输出
| 类型 | 描述 |
|------|------|
| 输入 | [描述] |
| 输出 | [描述] |

## 技术约束
- [约束]

## 业务规则
- [规则]

## 异常处理
| 场景 | 处理方式 |
|------|---------|
| [场景] | [处理] |

## 不在范围内
- [排除的功能]

## 待澄清项
- [NEEDS CLARIFICATION: 具体问题]

## 歧义评分
| 维度 | 评分 |
|------|------|
| 目标清晰度 | X% |
| 约束清晰度 | X% |
| 验收标准 | X% |
| 综合 | X% |

## 选中方案
[方案名称 + 理由]

快速路径简化格式

---
status: in_progress
author: [作者]
version: "1.0"
created: [日期]
---

# [主题名称]

## 目标
[一句话]

## 约束
- [约束]

## 选中方案
[方案名 + 理由]

## 歧义评分
| 维度 | 评分 |
|------|------|
| 综合 | X% |

完整的协同规范和产出要求详见 hany-common/templates/需求文档模板.md（编排器参考）。

恢复检查

启动时检查 docs/hany/requirements/ 下是否有未完成的需求文档（含 status: in_progress 标记）。如果存在，使用 AskUserQuestion 询问：继续上次 / 重新开始。

---

Step 0：先想想看 [进度 2%]

⚠️ 若由 hany-auto 调用，跳过此步（auto 已在自身 Step 0-1 完成初步思考和上下文探索）。

触发后，先思考再执行。

1. 用户给的任务描述是什么？
2. 用户是想新增需求还是修改已有功能？
3. 当前项目上下文能推导出什么？
4. 需求是否可能涉及多个子系统需要拆分？

思考完后，输出思路再进入 Step 1。

Step 1：探索上下文 [进度 5%]

自动执行，不需要用户干预：

1. 读取项目结构（ls、Glob），了解项目类型、语言、框架
2. 读取关键文件（package.json、README.md、入口文件等），理解现有架构
3. 检查 git 历史（git log --oneline -10），了解最近在做什么
4. 读取 docs/hany/rules.md（如果存在），了解项目已有的编码规则
5. 检查对话历史和 git 记录中是否有之前的尝试

思维过程透明化：写出发现。

Step 2：Brownfield/Greenfield 检测 [进度 10%]

自动检测，调整后续提问策略。

• 有现有源代码 → Brownfield：提问时引用具体文件路径和代码 pattern
• 无源代码、空项目 → Greenfield：正常提问

项目类型	歧义容忍度
Brownfield	更低（已有上下文约束）
Greenfield	更高（白纸一张）

Step 3：智能推导意图 [进度 15%]

用户描述模糊时，先推导再确认。

3.1 模糊度判断

• 描述 < 10 字 → 大概率模糊
• 含"处理一下"、"优化一下"、"改改"、"差不多" → 模糊
• 无明确输入/输出 → 模糊
• 与项目上下文不匹配 → 需澄清

3.2 推导策略

基于项目上下文、git 历史、已有功能推导用户意图，用 AskUserQuestion 确认："根据你的项目，我推导你可能想做的是 [推导结果]。对吗？"

3.3 澄清中断

连续 2 轮无法收敛 → 直接中断，要求用户提供更具体描述。

Step 4：大项目拆分检查 [进度 20%]

需求涉及多个独立子系统时，必须先拆分再执行。

1. 识别独立子系统
2. 使用 AskUserQuestion 确认拆分方案
3. 每个子系统生成独立需求文档
4. 无依赖的子系统用 Agent/Team 并行执行；有依赖的按顺序执行
5. 统一进度汇报：[拆分进度] 子系统A：X% / 子系统B：Y% / 总体：Z%

拆分后每个子系统独立走 Step 5-11。并行处理规则见 hany-common/procedures/split_parallel.md。

Step 5：多轮提问（含挑战者模式 + 实体追踪 + 歧义评分） [进度 25-55%]

5.1 歧义评分

详见 hany-common/procedures/ambiguity_scoring.md

每轮提问后进行打分。综合歧义度低于阈值才能进入下一步。

5.2 [NEEDS CLARIFICATION] 标记

不确定项标记 [NEEDS CLARIFICATION: 具体问题]，同时存在不超过 3 个。超过则必须先解决再继续。

5.3 实体追踪

详见 hany-common/procedures/entity_tracking.md

每轮提取关键名词，追踪稳定性。连续 2 轮稳定率 > 80% 说明核心概念已收敛。

5.4 第一轮：目标澄清

用 AskUserQuestion 问（每次最多 4 个选项）：最终想要什么？输入是什么？输出是什么？

5.5 第二轮：约束探查

基于 Step 1 发现反问："看到你用了 X 技术，这次需要用吗？"

5.6 挑战者模式（第 4 轮+）

轮次	模式	提问方式
第 4 轮+	反问者	挑战核心假设
第 5 轮+	简化者	最简单版本是什么？哪些必须哪些可砍？
第 6 轮+（歧义>30%）	本体论者	核心实体是哪几个？

5.7 边界确认

问异常处理、扩展性、优先级。歧义度达标进入 5.8；否则继续挑战者模式。

5.8 需求总结

整理为结构化文档，用 AskUserQuestion 确认：确认需求 / 需要修改 / 取消。

Step 6：需求去重精简 [进度 60%]

重复需求合并、同义表述保留一个、冗余约束删除。精简前内容保留为备注不丢弃。

Step 7：多方案对比 [进度 65%]

给出 2-3 个可行方案，含实现思路、技术栈、复杂度、性能、可维护性、风险对比。给出推荐方案+理由。

用 AskUserQuestion 确认选择。

Step 8：需求自检 [进度 70%]

自查项	检查内容
占位符扫描	TBD/TODO/待定/NEEDS CLARIFICATION 必须消除
一致性	各章节无矛盾
歧义	无一句话两种理解
范围	单一可控，否则回 Step 4
可测性	每项可验证（"提升体验"不算，"< 2秒"才算）
去重	无重复内容

YAGNI："可能以后需要"的功能现在就砍。自查不通过 → 修改 → 重新自查。

Step 9：需求持久化 [进度 75%]

自动写入，无需确认。

检查通过后直接写入 docs/hany/requirements/YYYY-MM-DD-<主题>.md。

Step 10：输出示例原型 [进度 85%]

10.1 示例代码

理论上可行、可验证的最小实现。标注核心逻辑和占位。不能运行则说明原因。

10.2 技术说明

技术/函数/库	用途	选型理由
[名称]	[做什么]	[为什么选这个]

10.3 设计思路

架构图（模块关系）、数据流、关键决策（为什么这么设计，排除了什么方案及理由）。

10.4 思维过程

写出：首先想到的方案、备选方案、选择理由、当前方案的风险/局限。

10.5 可行性验证点

3-5 个验证点说明方案为什么可行。

Step 11：最终确认 [进度 95%]

用 AskUserQuestion：

• 确认，进入实现 → 引导触发 /hany:implement
• 修改示例 → 回 Step 10
• 有问题 → 回 Step 5 重新澄清

确认通过："示例和思路已确认，请触发 /hany:implement 开始详细实现。"