mirror of
https://github.com/GuDaStudio/commands.git
synced 2026-03-22 19:18:52 +08:00
v1.0：gudaspec正式版，不再依赖于openspec
This commit is contained in:
GuDaStudio
516
gudaspec/research-review.md
Normal file
516
gudaspec/research-review.md
Normal file
@@ -0,0 +1,516 @@
|
||||
---
|
||||
name: GudaSpec: Research Review
|
||||
description: Interactive review of internal research - user-friendly confirmation through guided questions.
|
||||
category: GudaSpec
|
||||
tags: [gudaspec, research, review, internal, interactive]
|
||||
argument-hint: [requirement-id]
|
||||
---
|
||||
|
||||
<!-- GUDASPEC:RESEARCH-REVIEW:START -->
|
||||
|
||||
## Purpose
|
||||
|
||||
以用户友好的方式审查内部研究发现。通过场景化描述和引导式问题，帮助用户理解并确认约束，无需深入技术细节。
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **场景驱动**：将技术约束转化为用户场景
|
||||
2. **选择优先**：尽量提供选项而非开放式问题
|
||||
3. **关联解释**：说明每个决策对后续的影响
|
||||
4. **渐进深入**：先确认大方向，再处理细节
|
||||
5. **智能分组**：将相关约束串联成有意义的主题
|
||||
|
||||
## Guardrails
|
||||
|
||||
- **MUST** use `AskUserQuestions` tool for all confirmations
|
||||
- **MUST** translate technical constraints into user-understandable language
|
||||
- **MUST** explain WHY each confirmation matters
|
||||
- **NEVER** dump raw technical details without context
|
||||
- **NEVER** ask users to confirm things they cannot reasonably evaluate
|
||||
|
||||
---
|
||||
|
||||
## Steps
|
||||
|
||||
### Step 0: Load and Analyze Internal Document
|
||||
|
||||
```bash
|
||||
cat gudaspec/research/<requirement-id>/internal.md
|
||||
```
|
||||
|
||||
After loading, perform **Constraint Clustering**:
|
||||
- Group related constraints by theme/scenario
|
||||
- Identify dependencies between constraints
|
||||
- Rank by importance (blocking vs nice-to-have)
|
||||
- Prepare user-friendly translations
|
||||
|
||||
### Step 1: Welcome and Context Setting
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
📋 需求审查: <Requirement Description>
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
需求ID: <requirement-id>
|
||||
|
||||
我已完成代码库分析，发现了一些需要您确认的关键点。
|
||||
接下来我会通过几个简单的问题来确认这些发现。
|
||||
|
||||
📊 审查概览:
|
||||
┌─────────────────────────────────────┐
|
||||
│ 核心场景确认 ████████░░ 3 个 │
|
||||
│ 技术适配确认 ██████░░░░ 2 个 │
|
||||
│ 实施边界确认 ████░░░░░░ 1 个 │
|
||||
│ 开放问题 ██░░░░░░░░ 2 个 │
|
||||
└─────────────────────────────────────┘
|
||||
|
||||
预计用时: 5-10 分钟
|
||||
|
||||
准备好开始了吗？
|
||||
```
|
||||
|
||||
Use `AskUserQuestions`:
|
||||
```
|
||||
options: ["开始审查", "先看一下完整的研究文档"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Core Scenario Confirmation (场景化约束确认)
|
||||
|
||||
**Strategy**: Group related constraints into user scenarios, ask about the scenario rather than individual constraints.
|
||||
|
||||
**Example Transformation**:
|
||||
|
||||
| 原始约束 (技术) | 转化后 (场景) |
|
||||
|-----------------|---------------|
|
||||
| HC-1: 密码必须bcrypt, cost=12 | |
|
||||
| HC-2: 登录失败5次锁定30分钟 | → "用户登录安全" 场景 |
|
||||
| HC-3: JWT用HS256算法 | |
|
||||
| SC-1: 错误响应用RFC 7807格式 | |
|
||||
|
||||
**Scenario Presentation Format**:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
🔐 场景 1/3: 用户登录安全
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
我发现项目中已有一套完整的登录安全机制：
|
||||
|
||||
【当前实现方式】
|
||||
• 密码存储：使用 bcrypt 加密（业界推荐的安全方案）
|
||||
• 防暴力破解：连续失败 5 次后锁定账户 30 分钟
|
||||
• 登录凭证：使用 JWT Token，15分钟过期
|
||||
|
||||
【这意味着什么】
|
||||
您的新功能需要 [复用/适配/绕开] 这套机制。
|
||||
如果您的功能涉及用户身份验证，必须走这套流程。
|
||||
|
||||
【对您需求的影响】
|
||||
<根据具体需求说明影响，例如>
|
||||
- 如果需要新增登录方式，需要集成到现有的 AuthService
|
||||
- 如果需要延长登录时间，需要调整 JWT 配置
|
||||
```
|
||||
|
||||
Use `AskUserQuestions`:
|
||||
```
|
||||
question: "您的需求与用户登录安全的关系是？"
|
||||
options: [
|
||||
"需要复用现有登录机制（如：新增OAuth登录方式）",
|
||||
"需要修改现有机制（如：调整锁定策略）",
|
||||
"与登录无关，可以跳过",
|
||||
"不确定，需要更多解释"
|
||||
]
|
||||
```
|
||||
|
||||
**If user selects "不确定"**, provide deeper explanation:
|
||||
```
|
||||
让我举个具体例子：
|
||||
|
||||
假设您要添加"Outlook邮件集成"功能：
|
||||
- 如果用户需要登录才能使用邮件功能 → 复用现有机制
|
||||
- 如果Outlook需要单独的OAuth认证 → 可能需要扩展机制
|
||||
- 如果只是后台同步邮件，用户无感知 → 与登录无关
|
||||
|
||||
您的需求更接近哪种情况？
|
||||
```
|
||||
|
||||
**Record Decision**: Update internal.md with user's choice and rationale.
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Technical Adaptation Confirmation (技术适配确认)
|
||||
|
||||
**Strategy**: Present technical constraints as "project rules" that need to be followed, ask if there are special reasons to deviate.
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
🔧 技术适配: 项目规范
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
我发现项目遵循以下规范，新代码应保持一致：
|
||||
|
||||
【代码风格】
|
||||
┌────────────────────────────────────────────┐
|
||||
│ 📁 目录结构: src/<模块>/[router|service|models].py
|
||||
│ 📝 命名规范: 函数用 snake_case, 类用 PascalCase
|
||||
│ 🧪 测试要求: 每个模块需要对应的 tests/<模块>/ 目录
|
||||
│ 📦 依赖管理: 使用 pyproject.toml + poetry
|
||||
└────────────────────────────────────────────┘
|
||||
|
||||
【API规范】
|
||||
┌────────────────────────────────────────────┐
|
||||
│ 🔗 路由风格: RESTful (如 /users/{id}/emails)
|
||||
│ 📄 响应格式: 统一的 JSON 结构
|
||||
│ ❌ 错误处理: 使用项目自定义的 AppException
|
||||
└────────────────────────────────────────────┘
|
||||
|
||||
【为什么这很重要】
|
||||
遵循这些规范可以：
|
||||
• 让代码更容易被团队其他成员理解
|
||||
• 复用现有的工具函数和中间件
|
||||
• 保持项目整体一致性
|
||||
```
|
||||
|
||||
Use `AskUserQuestions`:
|
||||
```
|
||||
question: "关于项目规范，请确认："
|
||||
options: [
|
||||
"遵循以上所有规范（推荐）",
|
||||
"大部分遵循，但有特殊情况需要说明",
|
||||
"这是一个独立模块，可能需要不同的规范"
|
||||
]
|
||||
```
|
||||
|
||||
**If user selects special case**, follow up:
|
||||
```
|
||||
请告诉我特殊情况：
|
||||
• 哪些规范可能需要调整？
|
||||
• 调整的原因是什么？
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Integration Points Confirmation (集成点确认)
|
||||
|
||||
**Strategy**: Visualize where new code connects to existing code, confirm the connection points.
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
🔌 集成点: 新代码如何接入现有系统
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
根据您的需求，新功能需要在以下位置与现有代码对接：
|
||||
|
||||
```
|
||||
现有系统 您的新功能
|
||||
───────── ─────────
|
||||
|
||||
┌─────────────┐ ┌─────────────┐
|
||||
│ 用户模块 │◄─────────────│ Outlook │
|
||||
│ users/ │ 获取用户 │ 集成模块 │
|
||||
└─────────────┘ 信息 └─────────────┘
|
||||
│ │
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────┐ ┌─────────────┐
|
||||
│ 认证模块 │◄─────────────│ OAuth │
|
||||
│ auth/ │ 复用认证 │ 处理 │
|
||||
└─────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
【具体对接点】
|
||||
|
||||
1️⃣ 用户信息获取
|
||||
位置: src/users/service.py → UserService.get_by_id()
|
||||
用途: 获取用户邮箱配置
|
||||
|
||||
2️⃣ 认证复用
|
||||
位置: src/auth/deps.py → get_current_user()
|
||||
用途: 验证用户身份
|
||||
|
||||
【这意味着什么】
|
||||
• 您的代码需要导入并调用这些现有函数
|
||||
• 如果这些函数不满足需求，可能需要扩展（而非重写）
|
||||
```
|
||||
|
||||
Use `AskUserQuestions`:
|
||||
```
|
||||
question: "这些集成点是否符合您的预期？"
|
||||
options: [
|
||||
"符合，按此方案集成",
|
||||
"基本符合，但可能还需要其他集成点",
|
||||
"不太确定，能否解释一下替代方案？"
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Scope Boundary Confirmation (边界确认)
|
||||
|
||||
**Strategy**: Clearly state what IS and IS NOT included, get explicit confirmation.
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
📐 实施边界: 明确范围
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
根据我的分析，本次实施的范围建议如下：
|
||||
|
||||
【✅ 包含在内】
|
||||
• <功能点1>
|
||||
• <功能点2>
|
||||
• <功能点3>
|
||||
|
||||
【❌ 不包含（建议后续处理）】
|
||||
• <排除项1> — 原因: <简要说明>
|
||||
• <排除项2> — 原因: <简要说明>
|
||||
|
||||
【⚠️ 需要您决定】
|
||||
• <边界模糊项> — 包含它会增加约 X 天工作量
|
||||
```
|
||||
|
||||
Use `AskUserQuestions`:
|
||||
```
|
||||
question: "关于实施边界："
|
||||
options: [
|
||||
"同意以上边界划分",
|
||||
"需要包含更多功能（请说明）",
|
||||
"范围太大，需要进一步缩减"
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 6: Open Questions (开放问题 - 智能提问)
|
||||
|
||||
**Strategy**: Transform technical open questions into business decisions with clear options.
|
||||
|
||||
**Example Transformation**:
|
||||
|
||||
| 原始问题 (技术) | 转化后 (业务决策) |
|
||||
|-----------------|-------------------|
|
||||
| "JWT TTL 设置多少？" | "用户需要多久重新登录一次？" |
|
||||
| "是否需要 rate limiting？" | "如何防止用户过于频繁调用？" |
|
||||
| "缓存策略用什么？" | "数据实时性要求高吗？" |
|
||||
|
||||
**Presentation Format**:
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
❓ 需要您决定: 邮件同步频率
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
【背景】
|
||||
Outlook邮件集成需要定期从服务器获取新邮件。
|
||||
同步频率会影响：
|
||||
• 实时性：频率越高，用户越快看到新邮件
|
||||
• 成本：频率越高，API调用次数越多
|
||||
• 性能：频率越高，服务器负载越大
|
||||
|
||||
【选项对比】
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ 选项 │ 延迟 │ API成本 │ 适用场景 │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ A. 实时推送 │ < 1秒 │ 高 │ 即时通讯 │
|
||||
│ B. 每5分钟 │ ≤ 5分钟│ 中 │ 一般办公 │
|
||||
│ C. 每30分钟 │ ≤ 30分钟│ 低 │ 非紧急 │
|
||||
│ D. 手动刷新 │ 用户控制│ 最低 │ 低频使用 │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
Use `AskUserQuestions`:
|
||||
```
|
||||
question: "邮件同步频率选择哪个方案？"
|
||||
options: ["A. 实时推送", "B. 每5分钟（推荐）", "C. 每30分钟", "D. 手动刷新", "需要更多信息来决定"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 7: External Research Determination (智能判断)
|
||||
|
||||
**Strategy**: Don't just ask "need external research?", explain what would be researched and why.
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
🔍 是否需要外部调研？
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
基于以上讨论，我识别到以下可能需要外部调研的点：
|
||||
|
||||
【需要调研的内容】
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ 1. Microsoft Graph API vs EWS │
|
||||
│ 原因: 项目中没有Outlook集成先例 │
|
||||
│ 影响: 决定整体技术架构 │
|
||||
│ 调研内容: API能力对比、认证方式、限制 │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ 2. OAuth 2.0 最佳实践 │
|
||||
│ 原因: 现有OAuth实现仅支持Google │
|
||||
│ 影响: Token管理和刷新策略 │
|
||||
│ 调研内容: Microsoft OAuth流程差异 │
|
||||
└─────────────────────────────────────────────┘
|
||||
|
||||
【如果跳过外部调研】
|
||||
• 我将基于通用知识进行实施
|
||||
• 可能无法选择最优方案
|
||||
• 后续可能需要返工
|
||||
|
||||
【如果进行外部调研】
|
||||
• 预计额外需要 1 轮对话
|
||||
• 将获得针对性的技术选型建议
|
||||
• 降低实施风险
|
||||
```
|
||||
|
||||
Use `AskUserQuestions`:
|
||||
```
|
||||
question: "是否进行外部调研？"
|
||||
options: [
|
||||
"是，进行调研（推荐：涉及新技术）",
|
||||
"否，我对技术选型已有明确想法",
|
||||
"否，这是简单需求，不需要调研"
|
||||
]
|
||||
```
|
||||
|
||||
**If user skips and has clear idea**, follow up:
|
||||
```
|
||||
您提到已有明确想法，请告诉我：
|
||||
• 您倾向使用什么技术方案？
|
||||
• 有什么特殊考虑因素吗？
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 8: Summary and Confirmation (总结确认)
|
||||
|
||||
```
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
✅ 审查总结
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
感谢您的耐心确认！以下是本次审查的结果：
|
||||
|
||||
【您的关键决策】
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ 1. 登录安全: 复用现有机制 │
|
||||
│ 2. 项目规范: 完全遵循 │
|
||||
│ 3. 集成方案: 按建议的3个点对接 │
|
||||
│ 4. 实施边界: 同意建议范围 │
|
||||
│ 5. 同步频率: 每5分钟 │
|
||||
│ 6. 外部调研: 需要 │
|
||||
└─────────────────────────────────────────────┘
|
||||
|
||||
【这些决策的影响】
|
||||
• 实施复杂度: 中等
|
||||
• 预计涉及文件: 8-12 个
|
||||
• 需要新增依赖: 2 个 (msgraph-sdk, msal)
|
||||
|
||||
【下一步】
|
||||
<根据是否需要外部调研显示不同内容>
|
||||
```
|
||||
|
||||
Use `AskUserQuestions`:
|
||||
```
|
||||
question: "以上总结是否准确？"
|
||||
options: [
|
||||
"准确，继续下一步",
|
||||
"需要修改某项决策",
|
||||
"需要补充说明"
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 9: Output and Next Steps
|
||||
|
||||
**If External Research Needed**:
|
||||
```
|
||||
✅ Internal Research 审查完成
|
||||
|
||||
需求ID: <requirement-id>
|
||||
审查状态: 已确认，待外部调研
|
||||
|
||||
📋 下一步操作:
|
||||
1. 输入 /clear 清空当前上下文
|
||||
2. 输入 /gudaspec:deepresearch <requirement-id> 开始外部调研
|
||||
|
||||
外部调研将解答:
|
||||
• Microsoft Graph API 技术选型
|
||||
• OAuth 2.0 集成方案
|
||||
```
|
||||
|
||||
**If No External Research Needed**:
|
||||
```
|
||||
✅ Research 全部完成
|
||||
|
||||
需求ID: <requirement-id>
|
||||
最终需求文档: gudaspec/research/<requirement-id>/requirement.md
|
||||
|
||||
📋 下一步操作:
|
||||
1. 输入 /clear 清空当前上下文
|
||||
2. 输入 /gudaspec:plan gudaspec/research/<requirement-id>/requirement.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Question Design Patterns (问题设计模式)
|
||||
|
||||
### Pattern 1: Scenario-Based (场景式)
|
||||
```
|
||||
【场景描述】
|
||||
当用户执行 <动作> 时，系统当前会 <行为>。
|
||||
|
||||
【问题】
|
||||
您的需求是否需要改变这个行为？
|
||||
```
|
||||
|
||||
### Pattern 2: Impact-Driven (影响驱动)
|
||||
```
|
||||
【发现】
|
||||
项目使用 <技术/模式>。
|
||||
|
||||
【如果遵循】<好处>
|
||||
【如果偏离】<代价>
|
||||
|
||||
【问题】
|
||||
您希望如何处理？
|
||||
```
|
||||
|
||||
### Pattern 3: Trade-off (权衡式)
|
||||
```
|
||||
【权衡点】
|
||||
<选项A> vs <选项B>
|
||||
|
||||
【A的特点】<优劣>
|
||||
【B的特点】<优劣>
|
||||
|
||||
【问题】
|
||||
哪个更符合您的需求？
|
||||
```
|
||||
|
||||
### Pattern 4: Clarification (澄清式)
|
||||
```
|
||||
【我的理解】
|
||||
您希望实现 <功能描述>
|
||||
|
||||
【确认点】
|
||||
- <细节1>: 是这样吗？
|
||||
- <细节2>: 还是这样？
|
||||
|
||||
【问题】
|
||||
我的理解正确吗？
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
- [ ] All scenarios confirmed via interactive questions
|
||||
- [ ] All user decisions recorded with rationale
|
||||
- [ ] External research need determined with clear reasoning
|
||||
- [ ] User explicitly confirmed summary
|
||||
- [ ] Document updated with confirmed decisions
|
||||
- [ ] User directed to appropriate next step
|
||||
|
||||
<!-- GUDASPEC:RESEARCH-REVIEW:END -->
|
||||
Reference in New Issue
Block a user