tech-research.md

来自 cli/templates/level-3/

---
name: tech-research
context: fork
description: >
  技术调研。编码前的技术选型、方案评估、竞品分析时使用。
  评估开源项目、调研行业标准、分析竞品方案、收集最佳实践，输出结构化调研文档。
---

# 技术调研

编码前的结构化调研，输出可直接用于 ADR、spec.md 和技术决策的调研文档。

## 适用场景

- 新项目或大功能启动前的技术选型
- 库 / 框架 / 协议之间的对比选择
- 竞品如何解决类似问题
- 相关标准或 RFC 调研
- Build vs Buy vs Adopt 决策
- 任何"先调查再动手"能避免返工的场景

## 调研维度

每次调研从以下 5 个维度中选取 2-3 个相关维度，不需要全做。

### 1. 标准与规范
行业标准、RFC、W3C/ISO 规范。
- 收集：名称、版本、状态（draft/ratified）、发布机构、采纳程度、对实现的关键约束、规范链接

### 2. 开源生态
同领域或相邻领域的开源项目。

**每个项目收集：**
- 名称、一句话描述、主语言
- GitHub stars（作为流行度参考，非质量指标）
- License 类型及商用影响
- 最近提交/发布日期、提交频率、贡献者数量
- 架构亮点（单体 vs 插件、同步 vs 异步等）
- 优势、劣势、已知坑
- 社区健康度：issue 响应速度、文档质量、社区活跃度

**分层策略：**
- Tier 1（深度）：2-3 个最有前途的候选 — 阅读文档、扫描代码结构
- Tier 2（概览）：3-5 个值得提及的 — 快速统计 + 一句话总结
- 跳过：明显废弃的项目（2 年+ 无提交、<100 stars、无 release）

### 3. 最佳实践
来自生产系统、工程博客、技术大会的实战经验。
- 收集：模式名称、适用场景、奏效原因（解决了什么 tradeoff）、已知反模式、来源

### 4. 竞品分析
现有产品（商业或开源）如何实现相关功能。
- 收集：产品名称、目标用户、实现方式（UI/API/数据模型）、用户好评点、常见抱怨、定价模型

### 5. 性能与规模参考
类似系统的 benchmark 和容量数据。
- 收集：指标类型（吞吐/延迟 p50/p99/内存/冷启动）、测试条件、来源日期、方法论可信度

---

## 步骤

### Step 1: 界定调研范围

开始搜索前，明确以下 4 项：
1. **目标** — 这次调研要支撑什么决策？
2. **维度** — 上述 5 个维度中哪些相关？（通常 2-3 个）
3. **深度** — 快速扫描 vs 深度调研？
4. **约束** — License 要求？语言/运行时偏好？必须自托管？

用一句话向用户确认范围：
> "我将调研实时同步方案，聚焦 CRDT 开源库（stars、license、活跃度）和 CRDT vs OT 的 tradeoff。快速扫描深度。OK？"

### Step 2: 执行调研

使用 Web Search 按以下顺序收集数据：

1. **全景扫描** — 识别关键玩家
   - `"awesome-{topic}" github` 查找策展列表
   - `"{topic} comparison {current_year}"` 查找近期对比
   - `"{topic} vs {topic}"` 查找直接对比

2. **深度挖掘** — 对 Tier 1 候选项
   - 检查 README、架构文档、CHANGELOG
   - 通过 web search `"github.com/{owner}/{repo}"` 获取可见统计数据

3. **标准检索** — 搜索相关规范
   - `"{domain} RFC"`, `"{domain} W3C spec"`, `"{domain} specification"`

4. **实践收集** — 搜索工程博客和演讲
   - `"{topic} best practices {current_year}"`
   - `"{topic} lessons learned production"`
   - `"how {well-known-company} built {feature}"`

5. **竞品扫描** — 如相关
   - `"{product category} comparison"`, `"alternatives to {known product}"`

### Step 3: 综合整理

将结果组织为结构化文档。对每条发现提供：
- **事实** — 了解到了什么
- **影响** — 对用户项目意味着什么
- **置信度** — 这个数据点可靠程度如何

### Step 4: 输出建议

以可操作的建议结束：
- 明确的"推荐路径"及理由
- 备选方案及 tradeoff
- 需要进一步调查的开放问题
- 建议的下一步（原型 X、基准测试 Y、阅读 Z）

### Step 5: 等待确认

IMPORTANT：
- 调研文档输出后必须等待用户确认，不要自行开始技术设计或编码。
- 下一步引导用户使用 `/plan` 进行技术方案设计，或使用 `/spec` 进行需求定义。

---

## 输出模板

输出 Markdown 文件到用户指定路径（默认：`docs/research/{topic-slug}.md`）。
按需裁剪，不相关的章节直接省略。

```markdown
# Research: {Topic}

> **Goal:** {一句话 — 支撑什么决策？}
> **Date:** {YYYY-MM-DD}
> **Depth:** Quick scan / Deep dive
> **Dimensions:** Standards, Open-Source, Best Practices, Competitors, Performance

## TL;DR

{3-5 句摘要。以推荐方案开头。}

## Standards & Specifications

| Standard | Version | Status | Issuing Body | Key Implication |
|----------|---------|--------|-------------|-----------------|
| ...      | ...     | ...    | ...         | ...             |

{简要叙述标准与项目的关联。}

## Open-Source Landscape

### Tier 1: Deep Dive

#### {Project Name}
- **Repo:** {URL}
- **Stars:** {count} | **License:** {type} | **Last Release:** {date}
- **Language:** {primary} | **Contributors:** {count}
- **Commit Activity:** {e.g., "~20 commits/week, very active"}

**Architecture:** {2-3 sentences}

**Strengths:**
- ...

**Weaknesses:**
- ...

**Verdict:** {一句话 — 适合/不适合/值得原型验证}

### Tier 2: Overview

| Project | Stars | License | Last Release | One-liner |
|---------|-------|---------|-------------|-----------|
| ...     | ...   | ...     | ...         | ...       |

## Best Practices

{按主题分组叙述，而非按来源。}

## Competitor Analysis

| Product | Approach | Strengths | Weaknesses | Pricing |
|---------|----------|-----------|------------|---------|
| ...     | ...      | ...       | ...        | ...     |

## Performance References

{Benchmark 数据表格或叙述。}

## Recommendations

### Recommended Path
{推荐方案及理由。}

### Alternatives Considered
{其他方案及排序偏低的原因。}

### Open Questions
- {需要进一步调查的问题}

### Suggested Next Steps
1. {具体下一步行动}
2. {另一个行动}

## Sources
- {编号列表，附 URL}

---

Tips

• 时效性优先 — 优先使用近 12 个月的资料。2022 年的"最佳"库现在可能已废弃，务必检查最后提交日期
• Stars ≠ 质量 — 50k stars 但一年没提交，不如 2k stars 但每周发版。Stars 仅作为流行度背景
• License 是决策因子 — GPL-3.0 vs MIT vs BSL-1.1 可以直接决定项目可行性，显著标注 license 风险
• 坦诚面对未知 — 找不到可靠 benchmark 数据就明说，不编造数字、不夸大置信度
• 考虑用户上下文 — 个人开发者选框架和团队迁移生产系统的需求截然不同，建议要因人而异
• 交叉验证 — 多个来源一致则置信度高，不一致则标注差异