Devdocs Insights

洞察收集

收集来自 UI/UX 审查、文档调研、外部参考等来源的改进建议，经用户确认后转化为开发需求。

语言规则

• 支持中英文提问
• 统一中文回复
• 使用中文生成文档

触发条件

• 用户完成 UI/UX 审查，有优化建议
• 用户调研了文档/方案，发现可借鉴点
• 用户发现外部参考（竞品、最佳实践）可借鉴
• 用户有改进想法需要转化为需求

核心理念

洞察来源

┌─────────────────────────────────────────────────────────────┐
│                      洞察来源                                │
├─────────────────────────────────────────────────────────────┤
│  🎨 UI/UX 审查     │ 界面问题、交互优化、视觉改进            │
├─────────────────────────────────────────────────────────────┤
│  📄 文档调研       │ 技术方案、设计模式、架构参考            │
├─────────────────────────────────────────────────────────────┤
│  🔍 外部参考       │ 竞品分析、行业最佳实践、开源项目        │
├─────────────────────────────────────────────────────────────┤
│  💡 内部反馈       │ 用户反馈、团队建议、性能监控            │
└─────────────────────────────────────────────────────────────┘

转化流程

洞察来源                确认阶段                 输出阶段
    │                      │                        │
    ▼                      ▼                        ▼
┌─────────┐          ┌─────────┐            ┌─────────────┐
│ 收集    │    →     │ 用户    │      →     │ 追加到      │
│ 建议    │          │ 确认    │            │ 需求文档    │
└─────────┘          └─────────┘            └─────────────┘
                          │
                          ▼
                    部分确认 / 全部确认 / 拒绝

核心原则：

• 建议必须经过用户确认才能转化为需求
• 保留建议来源的追溯性
• 区分优先级，避免需求膨胀

工作流程

1. 识别洞察来源
   │
   ▼
2. 收集/整理建议
   ├── UI/UX 审查结果
   ├── 文档调研发现
   ├── 外部参考借鉴
   └── 内部反馈汇总
   │
   ▼
3. 结构化建议列表
   ├── 分类整理
   ├── 评估影响范围
   └── 建议优先级
   │
   ▼
4. 用户确认（AskUserQuestion）
   ├── 逐条确认
   ├── 批量确认
   └── 调整优先级
   │
   ▼
5. 转化为需求
   ├── 生成功能点 (F-XXX)
   ├── 生成验收标准 (AC-XXX)
   └── 追加到 01-requirements.md
   │
   ▼
6. 建议后续流程
   └── 运行 /devdocs-system-design 或 /devdocs-dev-tasks

输出文件

洞察记录（可选）

文件：docs/devdocs/05-insights.md

用于记录洞察来源和转化历史，便于追溯。

需求追加

确认的建议将追加到：docs/devdocs/01-requirements.md

建议结构

单条建议格式

### INS-001: <建议标题>

| 属性 | 内容 |
|------|------|
| **来源** | 🎨 UI/UX 审查 / 📄 文档调研 / 🔍 外部参考 / 💡 内部反馈 |
| **参考** | <来源链接或描述> |
| **现状** | <当前问题或不足> |
| **建议** | <改进建议> |
| **影响范围** | <涉及模块/功能> |
| **优先级** | P0 / P1 / P2 |
| **状态** | ⏳ 待确认 / ✅ 已确认 / ❌ 已拒绝 / 🔄 已转化 |

**预期收益**：
- <收益1>
- <收益2>

建议列表格式

# 洞察收集：<主题>

**收集时间**：YYYY-MM-DD
**来源类型**：UI/UX 审查 / 文档调研 / 外部参考

## 建议汇总

| 编号 | 标题 | 来源 | 优先级 | 状态 |
|------|------|------|--------|------|
| INS-001 | <标题> | 🎨 | P1 | ⏳ |
| INS-002 | <标题> | 📄 | P0 | ⏳ |

## 详细建议

### INS-001: <标题>
...

---

## 确认结果

- [x] INS-001: 已确认 → F-XXX
- [ ] INS-002: 待确认
- [x] INS-003: 已拒绝（原因：...）

来源类型处理

🎨 UI/UX 审查

**输入**：
- 用户提供截图/原型
- 用户描述交互问题
- 运行 /ui-skills 审查结果

**关注点**：
- 可用性问题
- 视觉一致性
- 无障碍性
- 响应式适配
- 交互流畅度

**示例建议**：
- INS-001: 按钮对比度不足，影响可读性
- INS-002: 表单缺少加载状态反馈
- INS-003: 移动端导航菜单难以点击

📄 文档调研

**输入**：
- 技术文档链接
- 设计方案文档
- 最佳实践指南

**关注点**：
- 可借鉴的架构模式
- 更优的实现方案
- 性能优化技术
- 安全加固措施

**示例建议**：
- INS-004: 采用 React Query 替代手动状态管理
- INS-005: 引入乐观更新提升用户体验
- INS-006: 使用 Zod 进行运行时类型校验

🔍 外部参考

**输入**：
- 竞品链接/截图
- 开源项目参考
- 行业报告

**关注点**：
- 竞品优势功能
- 行业通用模式
- 用户期望对齐

**示例建议**：
- INS-007: 参考 Notion 的拖拽排序交互
- INS-008: 借鉴 Linear 的快捷键系统
- INS-009: 采用类似 Figma 的实时协作模式

💡 内部反馈

**输入**：
- 用户反馈记录
- 团队讨论结果
- 性能监控数据

**关注点**：
- 高频用户痛点
- 团队共识问题
- 性能瓶颈

**示例建议**：
- INS-010: 列表加载慢，需要分页或虚拟滚动
- INS-011: 搜索功能缺少高级筛选
- INS-012: 导出功能需要支持更多格式

用户确认流程

使用 AskUserQuestion 进行交互式确认：

单条确认

建议 INS-001: 按钮对比度不足，影响可读性

来源：🎨 UI/UX 审查
优先级：P1
影响范围：全局按钮组件

是否确认转化为需求？
- 确认（转化为 F-XXX）
- 调整优先级后确认
- 拒绝（请说明原因）
- 稍后决定

批量确认

以下建议待确认：

| 编号 | 标题 | 优先级 |
|------|------|--------|
| INS-001 | 按钮对比度不足 | P1 |
| INS-002 | 缺少加载状态 | P1 |
| INS-003 | 移动端导航问题 | P2 |

请选择：
- 全部确认
- 选择性确认（输入编号，如：1,2）
- 全部拒绝
- 逐条审查

需求转化规则

转化映射

功能点格式

### F-XXX: <功能名称> [优化]

**来源**：INS-XXX (<来源类型>)
**优先级**：P0 / P1 / P2

**描述**：
<从建议转化的功能描述>

**验收标准**：
- AC-XXX: <可验证的标准1>
- AC-XXX: <可验证的标准2>

编号规则

• 功能点编号：延续 01-requirements.md 中的编号
• 验收标准编号：延续现有 AC 编号
• 建议编号：INS-XXX（仅在洞察文档中使用）

约束

收集约束

• 必须标明建议来源
• 必须评估影响范围
• 每条建议必须有明确的现状和改进点
• 外部参考必须提供来源链接

确认约束

• 所有建议必须经过用户确认才能转化
• 拒绝的建议必须记录原因
• 批量确认前必须展示完整列表
• 用户可以调整建议优先级

转化约束

• 转化后的需求必须可追溯到原始建议
• 必须生成可验证的验收标准
• 优化类需求必须标记 [优化] 标签
• 转化后更新建议状态为 🔄 已转化

避免需求膨胀

• 单次收集建议不超过 10 条
• 低优先级建议可标记为"待定"
• 鼓励用户聚焦核心改进
• 定期清理过期的待确认建议

Skill 协作

使用示例

示例一：UI/UX 审查后

用户: 我刚审查了登录页面，发现几个问题想优化

Agent: 好的，让我帮你收集这些优化建议。请描述发现的问题：

用户:
1. 密码输入框没有显示/隐藏切换
2. 忘记密码链接不够明显
3. 第三方登录按钮风格不统一

Agent: 已整理以下建议：

| 编号 | 标题 | 优先级 | 状态 |
|------|------|--------|------|
| INS-001 | 添加密码可见性切换 | P1 | ⏳ |
| INS-002 | 突出忘记密码链接 | P2 | ⏳ |
| INS-003 | 统一第三方登录按钮风格 | P2 | ⏳ |

请确认要转化为需求的建议（输入编号，如 1,2,3 或 "全部"）：

用户: 1,3

Agent:
✅ 已确认 INS-001, INS-003
已追加到 01-requirements.md：
- F-015: 密码可见性切换 [优化] (来源: INS-001)
- F-016: 统一第三方登录按钮 [优化] (来源: INS-003)

是否继续运行 /devdocs-dev-tasks 拆分开发任务？

示例二：文档调研后

用户: 我看了这篇文章 https://example.com/react-patterns，想借鉴一些模式

Agent: 让我分析这篇文章并提取可借鉴的点...

[WebFetch 获取内容]

基于文章内容，整理以下借鉴建议：

| 编号 | 标题 | 参考章节 | 优先级 |
|------|------|----------|--------|
| INS-001 | 采用 Compound Components 模式 | 第3节 | P1 |
| INS-002 | 使用 Render Props 替代 HOC | 第5节 | P2 |
| INS-003 | 引入 Custom Hooks 复用逻辑 | 第7节 | P1 |

请确认要采纳的建议：

命令选项

# 标准模式：交互式收集和确认
/devdocs-insights

# 从 URL 提取建议
/devdocs-insights --url <url>

# 从文件提取（如审查报告）
/devdocs-insights --file <path>

# 快速模式：直接输入建议列表
/devdocs-insights --quick

下一步

确认建议并转化为需求后，根据改进复杂度选择路径：

路径选择

确认的改进建议
      │
      ▼
评估是否涉及架构变更
      │
      ├── 无架构变更（简单改进）
      │   ├── UI 微调、配置修改、小功能
      │   └── → /devdocs-dev-tasks 直接拆分任务
      │
      └── 有架构变更（复杂改进）
          ├── 新接口、数据模型变更、新模块
          └── → /devdocs-feature 完整流程
                  └── system-design → test-cases → dev-tasks

架构变更判断

使用 AskUserQuestion 确认

已确认 X 条改进建议，转化为需求。

检测到以下情况：
- INS-001: UI 按钮样式调整 → 无架构变更
- INS-003: 新增导出 API → 涉及架构变更

建议路径：
- INS-001 → /devdocs-dev-tasks（直接拆分任务）
- INS-003 → /devdocs-feature（完整流程）

是否按建议执行？[是/调整]