/tech-research

技术调研。编码前的技术选型、方案评估、竞品分析时使用。

技术调研

编码前的结构化调研，输出可直接用于 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 项：

目标 — 这次调研要支撑什么决策？
维度 — 上述 5 个维度中哪些相关？（通常 2-3 个）
深度 — 快速扫描（Quick Scan）vs 深度调研（Deep Research）？
约束 — License 要求？语言/运行时偏好？必须自托管？

用一句话向用户确认范围：

"我将调研实时同步方案，聚焦 CRDT 开源库（stars、license、活跃度）和 CRDT vs OT 的 tradeoff。快速扫描深度。OK？"

fork 模式： Skill 以 context: fork 运行时无法交互确认。从调用参数中提取上述 4 项，缺失项按合理默认值处理（深度默认 Quick Scan，维度默认 Open-Source + Best Practices）。

现状分析： 如果调研主题涉及用户项目的现有配置（如选型替换、功能增强），在搜索前先读取相关配置文件，输出"Current State"章节。这能让建议更精准，避免推荐已有或不兼容的方案。

Step 2: 执行调研

根据 Step 1 确定的深度，选择对应模式执行。

模式 A：快速扫描（Quick Scan）

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

全景扫描 — 识别关键玩家
- "awesome-{topic}" github 查找策展列表
- "{topic} comparison {current_year}" 查找近期对比
- "{topic} vs {topic}" 查找直接对比
深度挖掘 — 对 Tier 1 候选项
- 检查 README、架构文档、CHANGELOG
- 通过 web search "github.com/{owner}/{repo}" 获取可见统计数据
标准检索 — 搜索相关规范
- "{domain} RFC", "{domain} W3C spec", "{domain} specification"
实践收集 — 搜索工程博客和演讲
- "{topic} best practices {current_year}"
- "{topic} lessons learned production"
- "how {well-known-company} built {feature}"
竞品扫描 — 如相关
- "{product category} comparison", "alternatives to {known product}"

模式 B：递归深搜（Deep Research）

当快速扫描不够、需要全面覆盖时启用。使用递归加深搜索策略：

deepResearch(query, breadth, depth):
  // breadth: number of parallel search directions (3-10)
  // depth: levels of follow-up (1-5)

  results = webSearch(query, breadth)  // get `breadth` results
  learnings = extractLearnings(results)

  if depth <= 0 OR no new learnings found:
    return learnings  // stop: exhausted or saturated

  for each learning that raises new questions:
    followUpQuery = generateFollowUp(learning, existingLearnings)
    deeperLearnings = deepResearch(
      followUpQuery,
      breadth / 2,     // breadth decays: halve each level
      depth - 1
    )
    learnings += deeperLearnings

  return deduplicate(learnings)

参数选择：

调研类型	breadth	depth	预估搜索轮次
快速验证	3	1	~3
标准调研	5	2	~12
深度对比	7	3	~25
全面报告	10	4-5	~50+

停止条件： 参数耗尽（depth=0）或信息饱和（连续 2 轮无新发现）。

Learning 提取规则： 每轮搜索后提取结构化 Learning：

一句话核心发现
与调研目标的关联度
衍生出的新问题（用于生成下一层 followUpQuery）

Step 3: 综合整理

将结果组织为结构化文档。对每条发现标注三要素：

事实 — 了解到了什么
影响 — 对用户项目意味着什么
置信度标签 — 按以下标准标注：

标签	条件	示例
HIGH	多个独立来源交叉验证 + 官方文档确认	官方 benchmark + 社区复现
MEDIUM	2 个来源一致，但未经独立验证	两篇博客观点一致
LOW	单一来源、或来源可能过时（>12 个月）	仅一篇 2024 年文章
UNVERIFIED	无法找到可靠来源，基于推断或间接证据	从代码结构推测的结论

标注格式：在关键发现后以行内标签标注，如 [HIGH]、[LOW]。

Step 4: 输出建议

以可操作的建议结束：

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

Step 5: 等待确认

IMPORTANT：

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

Step 6: 沉淀

调研报告经用户确认后：

保存到 docs/research/{YYYY-MM-DD}-{slug}.md，添加 frontmatter（title/date/tags）
更新 docs/research/README.md 索引表（日期倒序，最新在上）
提示：如果调研支撑了技术选型，建议用 Prompt 食谱 10-食谱 3 转化为 ADR

fork 模式： 如无法交互确认，默认执行沉淀（保存 + 更新索引）。

参考 doc-22 项目知识沉淀机制 §3

输出格式

格式决策树

根据调研类型和深度，选择最合适的输出格式：

调研范围？
├─ 单一问题快速确认 → Quick Brief（20-50 行）
├─ 单一主题调研 → Research Summary（100-200 行）
├─ 多候选对比选型 → Comparison Table（150-250 行）
└─ 全面技术评估 → Comprehensive Report（200-400 行）

Format 1: Quick Brief

适用于"这个库靠谱吗""这个方案可行吗"等快速验证。

markdown

# Brief: {Topic}

> **Goal:** {决策问题} | **Date:** {YYYY-MM-DD}

## Answer

{3-5 句直接回答，含推荐。关键发现标注置信度。}

## Key Evidence

- {事实 1} [HIGH]
- {事实 2} [MEDIUM]
- {事实 3} [LOW]

## Caveats & Next Steps

- {限制条件或需进一步验证的点}

Format 2: Research Summary

适用于单一主题的标准调研。这是默认格式。

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 句摘要。以推荐方案开头。}

## Current State (optional)

{仅当调研涉及项目现有配置时包含。分析当前实现、已有依赖、配置现状，明确"从哪里出发"。}

## 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:** {一句话 — 适合/不适合/值得原型验证} [HIGH/MEDIUM/LOW]

### 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}

Format 3: Comparison Table

适用于 A vs B vs C 选型决策。

markdown

# Comparison: {Topic}

> **Goal:** {选型决策} | **Date:** {YYYY-MM-DD}
> **Candidates:** {A}, {B}, {C}

## TL;DR

{推荐及一句话理由。}

## Comparison Matrix

| Criterion | Weight | {A} | {B} | {C} |
|-----------|--------|-----|-----|-----|
| {criterion 1} | H/M/L | ... | ... | ... |
| {criterion 2} | H/M/L | ... | ... | ... |

Confidence: {各数据点标注置信度}

## Per-Candidate Deep Dive

### {A}
{优势、劣势、适用场景}

### {B}
...

## Verdict

{最终推荐 + tradeoff 说明}

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

Format 4: Comprehensive Report

适用于深度递归调研的完整输出。包含 Format 2 的全部章节，额外增加：

Research Trail — 递归搜索路径记录（每层的 query 和 key learnings）
Confidence Map — 全部发现的置信度汇总表
Dissenting Views — 来源之间的矛盾观点及分析

按需裁剪 — 不相关的章节直接省略，不要输出空章节。

错误恢复协议

搜索或分析遇到障碍时，使用 3-Strike 递进恢复：

阶段	动作	原则
Strike 1	换搜索关键词或数据源（换 query 策略、换搜索引擎）	下次行动 ≠ 上次行动
Strike 2	换调研角度或降低粒度（从具体库 → 上游领域，从 benchmark → 定性评价）	退一步看更大图景
Strike 3	记录为"无法验证"并标注 `[UNVERIFIED]`，向用户报告阻塞点	诚实面对边界

核心原则：下次行动 ≠ 上次行动。 重复同样的失败搜索是最大的浪费。

反模式：

用相同关键词重试 3 次 — 换词不换策略
搜索失败后编造数据 — 必须标注 [UNVERIFIED]
跳过 Strike 直接放弃 — 至少尝试 2 种不同策略

Tips

时效性优先 — 优先使用近 12 个月的资料。2022 年的"最佳"库现在可能已废弃，务必检查最后提交日期
Stars ≠ 质量 — 50k stars 但一年没提交，不如 2k stars 但每周发版。Stars 仅作为流行度背景
License 是决策因子 — GPL-3.0 vs MIT vs BSL-1.1 可以直接决定项目可行性，显著标注 license 风险
坦诚面对未知 — 找不到可靠 benchmark 数据就明说，不编造数字、不夸大置信度
具体数字必须来自搜索 — GitHub stars、版本号、发布日期等必须从 Web Search 结果中提取。来自记忆的数字标注 [UNVERIFIED] 或改用定性描述（如"活跃维护中"替代具体 stars 数）
考虑用户上下文 — 个人开发者选框架和团队迁移生产系统的需求截然不同，建议要因人而异
交叉验证 — 多个来源一致则置信度高，不一致则标注差异
深度与效率的平衡 — 递归深搜强大但耗时，大多数调研用快速扫描即可。只在决策影响大、信息不确定性高时启用 Deep Research

/tech-research ​

技术调研 ​

适用场景 ​

调研维度 ​

1. 标准与规范 ​

2. 开源生态 ​

3. 最佳实践 ​

4. 竞品分析 ​

5. 性能与规模参考 ​

步骤 ​

Step 1: 界定调研范围 ​

Step 2: 执行调研 ​

模式 A：快速扫描（Quick Scan） ​

模式 B：递归深搜（Deep Research） ​

Step 3: 综合整理 ​

Step 4: 输出建议 ​

Step 5: 等待确认 ​

Step 6: 沉淀 ​

输出格式 ​

格式决策树 ​

Format 1: Quick Brief ​

Format 2: Research Summary ​

Format 3: Comparison Table ​

Format 4: Comprehensive Report ​

错误恢复协议 ​

Tips ​

/tech-research

技术调研

适用场景

调研维度

1. 标准与规范

2. 开源生态

3. 最佳实践

4. 竞品分析

5. 性能与规模参考

步骤

Step 1: 界定调研范围

Step 2: 执行调研

模式 A：快速扫描（Quick Scan）

模式 B：递归深搜（Deep Research）

Step 3: 综合整理

Step 4: 输出建议

Step 5: 等待确认

Step 6: 沉淀

输出格式

格式决策树

Format 1: Quick Brief

Format 2: Research Summary

Format 3: Comparison Table

Format 4: Comprehensive Report

错误恢复协议

Tips