| 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 自动调用。
[按需加载] 本文件包含完整步骤手册。执行时：
- 启动阶段：仅读快速参考卡和"Step 0"即可开始
- 执行阶段：用 Read(offset/limit) 跳读到对应 Step 章节（参考下方行号区间）
- 已完成阶段：用 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 完成初步思考和上下文探索）。
触发后，先思考再执行。
- 用户给的任务描述是什么？
- 用户是想新增需求还是修改已有功能？
- 当前项目上下文能推导出什么？
- 需求是否可能涉及多个子系统需要拆分？
思考完后，输出思路再进入 Step 1。
Step 1：探索上下文 [进度 5%]
自动执行，不需要用户干预：
- 读取项目结构（
ls、Glob），了解项目类型、语言、框架
- 读取关键文件（
package.json、README.md、入口文件等），理解现有架构
- 检查 git 历史（
git log --oneline -10），了解最近在做什么
- 读取
docs/hany/rules.md（如果存在），了解项目已有的编码规则
- 检查对话历史和 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%]
需求涉及多个独立子系统时，必须先拆分再执行。
- 识别独立子系统
- 使用
AskUserQuestion 确认拆分方案
- 每个子系统生成独立需求文档
- 无依赖的子系统用 Agent/Team 并行执行；有依赖的按顺序执行
- 统一进度汇报：
[拆分进度] 子系统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 开始详细实现。"
