10 - 技术调研食谱
编码前的技术选型、方案评估、竞品分析、调研成果转化，以及功能拆解为可执行任务。
适用场景
| 场景 | 你的状态 | 目标 |
|---|---|---|
| 新项目启动前需要技术选型 | 有多个候选方案，不确定选哪个 | 结构化对比，输出决策依据 |
| 需要评估开源项目 | 看到多个 GitHub 项目，不知优劣 | 快速评估质量、活跃度、适用性 |
| 调研结论需要落地 | 调研报告写完了，但没有转化为行动 | 输出 ADR + 更新 CLAUDE.md + 指导编码 |
| 大功能需要拆解为任务 | 方案确定，但不知从哪写起 | 输出有依赖、可并行的任务清单 |
| 行业标准需要梳理 | 做支付/认证等领域，需要了解规范 | 梳理协议、标准、最佳实践 |
食谱 1：技术选型对比
场景描述
面对多个候选技术方案，需要从性能、生态、学习曲线、社区活跃度等维度做结构化对比，输出明确的选型建议。
核心模板
text
我要做：{{项目/功能描述}}
技术栈现状：{{已有的技术栈}}
请对比以下候选方案：
{{方案A}}：{{一句话描述}}
{{方案B}}：{{一句话描述}}
{{方案C}}：{{一句话描述}}（可选）
对比维度：
1. 性能 — 基准测试数据（如有）、已知瓶颈
2. 生态 — npm 下载量 / GitHub Star / 配套工具链
3. 学习曲线 — 文档质量、社区教程、API 复杂度
4. 社区活跃度 — 最近 commit、Issue 响应速度、维护者数量
5. AI 友好度 — Claude/Copilot 的代码生成质量（基于训练数据覆盖度）
6. 与现有栈兼容性 — 集成成本、类型支持
输出格式：对比表格 + 结论（推荐方案 + 理由）+ 风险提示。变量说明
| 变量 | 说明 | 示例 |
|---|---|---|
{{项目/功能描述}} | 要解决的问题 | 为 Next.js 项目添加实时通知 |
{{已有的技术栈}} | 当前技术环境 | Next.js 14 + Prisma + PostgreSQL + Vercel |
{{方案A/B/C}} | 候选技术 | Socket.io / SSE / Pusher |
好坏对比
text
❌ "WebSocket 和 SSE 哪个好？"
→ 没有项目上下文，AI 只能给通用建议
✅ "我的 Next.js 项目部署在 Vercel（Serverless），需要给用户推送通知。
对比 Socket.io / SSE / Pusher：性能、Vercel 兼容性、成本、AI 友好度。
重点：Serverless 环境下的长连接限制。"
→ 有环境约束、有重点维度实战案例
text
我要做：为个人博客添加评论系统
技术栈现状：Next.js 14 + SQLite + Cloudflare Pages
对比：自建（Prisma 存储） / Giscus（GitHub Discussions） / Disqus
维度：隐私、加载速度、维护成本、Cloudflare 兼容性、AI 友好度。Claude 增强
- 使用
/tech-researchSkill 一键启动，自动 Web Search 获取最新数据 - 追加
请同时输出 ADR 格式的决策记录直接固化选型结论 - 搭配
context: fork在隔离上下文中调研，不消耗主会话
食谱 2：开源项目评估
场景描述
发现一个开源项目，需要快速评估其质量、成熟度和适用性，判断是否值得引入。
核心模板
text
请评估以下开源项目是否适合引入我的项目：
项目：{{项目名}} ({{GitHub URL}})
用途：{{我打算用它做什么}}
我的技术栈：{{现有栈}}
评估维度：
1. 项目健康度 — Star/Fork 趋势、最近 release、Issue 处理速度
2. 代码质量 — TypeScript 支持、测试覆盖、文档完整度
3. 维护风险 — 核心维护者数量、Bus Factor、是否有商业支持
4. 集成成本 — API 复杂度、Bundle Size、破坏性更新频率
5. 替代方案 — 如果不用它，最佳替代是什么
结论：✅ 推荐引入 / ⚠️ 有条件引入 / ❌ 不推荐，附理由。变量说明
| 变量 | 说明 | 示例 |
|---|---|---|
{{项目名}} | 开源项目名 | tRPC |
{{GitHub URL}} | 仓库地址 | https://github.com/trpc/trpc |
{{我打算用它做什么}} | 使用目的 | 替代 REST API，实现端到端类型安全 |
{{现有栈}} | 当前技术环境 | Next.js + Prisma + Zod |
好坏对比
text
❌ "tRPC 好不好用？"
→ 无上下文，AI 只能给官方宣传式回答
✅ "评估 tRPC 是否适合我的 Next.js + Prisma 项目：
用途是替代 REST API。重点关注 Bundle Size、
Prisma 集成成本、和现有 Zod schema 的复用性。"
→ 有明确用途和关注点实战案例
text
评估 Drizzle ORM 是否适合替换我项目中的 Prisma：
用途：简化 SQL 查询、减少 ORM 抽象层
现有栈：Next.js + Prisma + PostgreSQL，已有 15 个 model
重点：迁移成本、类型推断质量、Edge Runtime 兼容性。Claude 增强
- Web Search 工具获取最新 Star 数和 Release 日期
- 追加
请列出迁移步骤和预估工时可直接接入任务拆解 - 评估后用
/plan规划引入方案
食谱 3：调研成果转化
场景描述
技术调研完成后，结论散落在对话中。需要将调研成果系统性转化为项目可用的资产：ADR 文档、CLAUDE.md 规则、编码参考。
核心模板
text
请根据 {{调研文档路径}} 的调研结论，完成以下转化：
1. ADR 文档 — 输出 docs/adr/ADR-{{编号}}-{{标题}}.md
格式：
- 状态：已采纳
- 日期：{{日期}}
- 背景：为什么需要做这个决策
- 决策：选择了什么，为什么
- 备选方案：考虑过的其他方案及优劣
- 后果：正面影响 + 负面影响 + 需关注的风险
2. CLAUDE.md 规则 — 提取需要长期遵循的技术约束
格式：追加到 CLAUDE.md 的 Key Rules 章节
只加真正有约束力的条目，不加常识
3. 编码参考 — 提取可直接用于 prompt 的锚定信息
格式：列出关键 API 用法、配置模式、注意事项变量说明
| 变量 | 说明 | 示例 |
|---|---|---|
{{调研文档路径}} | 调研报告位置 | docs/research-payment.md |
{{编号}} | ADR 编号 | 003 |
{{标题}} | 决策标题 | 选择 Stripe 作为支付网关 |
{{日期}} | 决策日期 | 2026-02-19 |
好坏对比
text
❌ 调研完直接开始编码，结论留在聊天记录里
→ 下次开新会话时结论丢失，重复踩坑
✅ 调研 → ADR（固化决策）→ CLAUDE.md（约束 AI）→ 编码引用
→ 结论在项目中可检索、可复用，跨会话持久生效实战案例
text
请根据 docs/research-auth.md 的调研结论，完成转化：
1. ADR：ADR-002-选择NextAuth作为认证方案.md
2. CLAUDE.md：追加认证相关的技术约束
3. 编码参考：NextAuth 的 Provider 配置模式和 Session 类型扩展方式Claude 增强
/tech-researchSkill 输出的报告天然适合作为输入- ADR 文件可被后续
/plan会话引用：参考 docs/adr/ADR-002 的决策 - CLAUDE.md 更新后，所有后续会话自动遵循新规则
食谱 4：任务拆解与排期
场景描述
技术方案确定后，需要将大功能拆解为可独立交付的小任务。每个任务有明确的输入输出、验收标准，标注依赖关系和并行机会。
核心模板
text
请将以下功能拆解为开发任务：
功能描述：{{功能描述}}
技术方案：{{方案位置或简述}}
涉及模块：{{模块列表}}
要求：
1. 每个任务控制在 1-2 小时可完成
2. 标注任务间的依赖关系（A → B 表示 A 完成后才能做 B）
3. 标注哪些任务可以并行（无依赖的任务组）
4. 每个任务包含：
- 简述（一句话）
- 输入条件（开始前需要什么）
- 产出物（完成后交付什么）
- 验收标准（怎么判断做对了）
5. 按推荐执行顺序排列
输出格式：编号任务列表 + 依赖关系图（文本描述）+ 并行分组。变量说明
| 变量 | 说明 | 示例 |
|---|---|---|
{{功能描述}} | 要实现的功能 | 用户认证模块（邮箱注册+登录+OAuth） |
{{方案位置或简述}} | 技术方案来源 | 见 /plan 输出的方案 |
{{模块列表}} | 涉及的代码模块 | types/、services/、app/api/、middleware/ |
好坏对比
text
❌ "帮我把认证功能拆分一下。"
→ 没有方案参考、没有粒度要求，拆出来太粗或太细
✅ "拆解用户认证模块（邮箱+GitHub OAuth，用 NextAuth）：
模块：types/ + services/ + app/api/ + middleware/。
每个任务 1-2 小时，标注依赖和并行机会。
验收标准用可执行的检查命令。"
→ 有方案、有粒度、有输出格式实战案例
text
拆解知识库 API Phase 2（三个 Service）：
功能：Space CRUD Service + Document CRUD Service + Tag Service
方案：契约先行（types → tests → implementation），参考 Phase 1 的模式
模块：src/types/、src/services/、src/services/__tests__/
要求：每个任务含验收标准，标注并行机会。
已知：Space 和 Document 有 1:N 关系，Document 和 Tag 有 N:M 关系。Claude 增强
/planSkill 的输出天然适合作为本食谱的输入- 拆解后的任务可直接作为
TodoWrite或 GitHub Issues 的内容 - 用子代理并行执行无依赖的任务组，搭配
context: fork隔离上下文 - 结合 design/12 §3.5 的"按规模选择开发模式"判断拆解粒度
食谱 5：行业标准与协议梳理
场景描述
做支付、认证、数据安全等领域功能时，需要先了解行业标准协议和技术规范，避免闭门造车。
核心模板
text
我要实现：{{功能描述}}
技术栈：{{技术栈}}
请梳理相关的行业标准和技术规范：
1. 核心协议/标准 — 名称、版本、适用范围
2. 关键术语 — 该领域的专业术语定义（避免误解）
3. 合规要求 — 必须遵守的规范（如有）
4. 最佳实践 — 业界推荐的实现模式
5. 常见陷阱 — 该领域最容易犯的错误
6. 参考实现 — 推荐的开源项目或官方 SDK
输出格式：按维度分节，协议/标准用表格，最后给实施建议。变量说明
| 变量 | 说明 | 示例 |
|---|---|---|
{{功能描述}} | 要实现的功能 | 微信小程序 JSAPI 支付 |
{{技术栈}} | 技术环境 | Node.js + Express + MySQL |
好坏对比
text
❌ "帮我接微信支付。"
→ 跳过了理解协议的步骤，直接写代码容易踩安全坑
✅ "我要接微信小程序 JSAPI 支付。先梳理：
核心协议（V3 API）、签名验证流程、回调安全要求、
常见陷阱（重复通知、金额校验）。不写代码。"
→ 先理解规范再编码，减少返工实战案例
text
我要实现：OAuth 2.0 + OIDC 登录（GitHub + Google）
技术栈：Next.js + NextAuth.js
请梳理：OAuth 2.0 授权码流程、OIDC 的 ID Token 验证规范、
PKCE 扩展的适用场景、Token 存储的安全最佳实践。
重点：哪些安全措施是必须做的（state 参数、HTTPS、Token 过期）。Claude 增强
- Web Search 获取最新的协议版本和安全公告
- 梳理后接食谱 3（调研成果转化）固化为 ADR 和 CLAUDE.md 规则
- 术语定义直接写入 CLAUDE.md 词汇表，避免 AI 后续误解
组合技巧
调研驱动开发流程（推荐）
完整的从调研到编码的五轮流程：
text
第 1 轮：技术调研（食谱 1+2+5）
→ 输出 docs/research-[主题].md
→ /clear
第 2 轮：成果转化（食谱 3）
→ 引用调研文档，输出 ADR + 更新 CLAUDE.md
→ /clear
第 3 轮：方案设计（配合 prompts/01 架构设计食谱）
→ 引用 ADR，设计实现方案
→ /clear
第 4 轮：任务拆解（食谱 4）
→ 基于方案拆解任务，标注依赖和并行
→ /clear
第 5 轮起：逐个任务编码
→ 每个任务一个会话 → commit → /clear → 下一个快速选型决策（食谱 1 + 3）
text
1. 用食谱 1 对比候选方案（一轮对话完成）
2. 直接接食谱 3 转化为 ADR（同一轮或下一轮）
→ 10 分钟完成从调研到决策固化调研 + 拆解一步到位（食谱 2 + 4）
text
1. 用食谱 2 评估开源项目
2. 确认引入后，用食谱 4 拆解集成任务
→ 从评估到可执行任务列表一气呵成相关资源
- /tech-research Skill — 自动化技术调研流程
- /plan Skill — 方案设计（食谱 4 的上游）
- /impact Skill — 改动影响分析
- doc-14 技术栈选型指南 — AI 友好度分级与推荐组合
- doc-06 文档体系 — ADR 模板与文档规范
- 01-架构设计食谱 — 调研后的下一阶段