workflow-requirements-clarification

Files (2)

• SKILL.md
• spec_template.md · reference/

SKILL.md (first lines)

# 需求澄清

## 核心定位

**AI 负责调研代码背景，用户负责提供需求信息。**

### AI 职责划分

**AI 自己调研（读代码）**：
- 现有实现是怎样的
- 代码路径、数据流
- 已有的接口和数据结构
- 技术约束（如使用的框架）
- 相关模块的职责

**向用户询问**：
- 为什么需要这个功能
- 要解决什么问题
- 具体要做哪些功能
- 目标和成功标准
- 非目标（不做什么）
- 性能/兼容性等非功能需求

**规则**：如果信息可以从 codebase 获取，**AI 必须自己调研**，不问用户。

### 苏格拉底式提问

向用户询问需求信息时，采用**苏格拉底式提问**——刨根问底，理解问题本质：

| 技巧 | 说明 | 示例 |
|------|------|------|
| **追问 Why** | 不接受表面答案，追问到问题本质 | 用户："加个缓存" → AI："为什么需要缓存？慢到什么程度？目标是多少？" |
| **指出矛盾** | 发现用户表述中的矛盾时，引导用户澄清 | 用户："要高并发，但不能改接口" → AI："异步化会改变接口语义，这两个目标是否冲突？" |
| **揭示遗漏** | 引导用户思考未考虑的场景 | AI："你考虑过 X 失败的情况吗？" |

### AI 生成内容的前置条件

1. **AI 已完成代码调研**（理解现状，并向用户确认）
2. **AI 已充分追问**（理解问题本质）
3. **加载相关规范**（如 `bp-distributed-systems` 等）

## 触发条件

- 用户描述功能需求但缺乏具体细节
- 用户请求开发新功能
- `spec.md` 不存在或需求章节为空

---

## 对话模式

### AI 角色边界

| AI 应该做 | AI 不应该做 |
|----------|------------|
| 提问，追问 Why | 未经请求就给答案 |
| 指出矛盾或遗漏 | 未追问清楚就生成内容 |
| 质疑不清晰的表述 | 跳过追问直接给建议 |
| **用户请求时**生成内容 | 生成后不询问用户意见 |

### 每轮对话结构

```
1. 说明当前阶段和目标
2. 提出一个开放式问题（让用户思考）
3. 等待用户回答
4. 评估用户回答：
   - 清晰完整 → 复述确认，进入下一问题
   - 模糊 → 追问具体含义
   - 有矛盾 → 指出矛盾
   - 有遗漏 → 引导思考
5. 用户澄清后，再次确认
```

---

## 工作流程

### Step 0: 评估复杂度并创建 spec

| 复杂度 | 信号 | 处理方式 |
|--------|------|----------|
| **简单** | bug fix、配置调整、单点修改 | 不创建 spec，1-2 轮对话后直接进入 code-generation |
| **中等** | 涉及多文件、单模块功能 | 创建 spec |
| **复杂** | 跨模块、新特性、架构变更 | 创建 spec |

**中等及以上**：立即创建目录并复制模板：

```bash
mkdir -p docs/design-docs/<module>/<feature>/
cp skills/workflow-requirements-clarification/reference/spec_template.md \
   docs/design-docs/<module>/<feature>/spec.md
```

路径规则：根据功能所属模块确定。文件名必须是 `spec.md`。

### Step 1: 代码调研（AI 自主完成）

**目标**：理解现有实现，不询问用户

**AI 操作**：
1. 调用 `codebase-researcher` subagent 深度调研相关代码（模块结构、接口、依赖关系、数据流）
2. 识别相关模块、接口、数据结构
3. 生成现状分析摘要

**向用户汇报（必须）**：
```
我先调研了一下相关代码：

**相关模块**：
- [文件路径1]: [职责说明]
- [文件路径2]: [职责说明]

**现有实现**：
[概述当前的实现方式、数据流、关键接口]

**技术约束**：
- [约束1，如使用的框架、协议]
- [约束2，如已有的接口规范]

From davidYichengWei/agentic-engineering-framework, MIT.

More from davidYichengWei/agentic-engineering-framework