# Technical Research > 技术选型/架构评估/框架/中间件/API/模型调研的证据驱动决策 Skill。 - Skill: `devcxl/technical-research` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add devcxl/technical-research` - Raw SKILL.md: https://api.skillmd.com/api/skills/devcxl/technical-research/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Research & Search - Author: devcxl (https://skillmd.com/u/devcxl) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/devcxl/technical-research --- # Technical Research Skill ## 目标 把"了解某项技术"转化为"基于证据完成技术决策"。 最终结果必须回答： 1. 要解决什么问题。 2. 哪些方案满足硬性约束。 3. 核心结论由什么证据支持。 4. 最大风险和未知项是什么。 5. 推荐哪个方案，以及适用边界。 6. 在什么条件下需要重新评估。 ## 适用场景 当任务包含以下任一目标时启用： - 技术选型或方案对比。 - 架构、框架、中间件、数据库、云服务、API、协议或模型调研。 - 开源项目成熟度、维护状态、安全性或生产可用性评估。 - 性能、稳定性、扩展性、成本或迁移风险评估。 - 为 PRD、技术方案、立项会或架构评审提供决策依据。 - 对已有技术路线进行复盘或替换评估。 不适用于： - 只需查询一个明确事实。 - 只需解释基础概念。 - 用户已明确方案，只要求实现代码。 ## 默认工作模式 默认采用"标准调研"： - 候选方案：3～5 个。 - 证据优先级：官方文档与源码优先。 - 关键未知项：必须提出验证方法。 - 高风险结论：必须通过 PoC、源码、Issue 或多源证据验证。 - 输出：调研报告、对比矩阵、风险清单、推荐结论、ADR。 当决策影响生产核心链路、资金、数据一致性、安全或三个月以上开发投入时，自动升级为"深度调研"，增加源码审查、故障测试、TCO 和退出方案。 ## 强制原则 1. **先定义决策，后收集资料。** 2. **硬性约束优先于加权评分。** 不满足硬性约束的方案直接淘汰。 3. **事实、推断和未知项必须分开。** 4. **每个关键结论必须可追溯到证据。** 5. **优先验证失败路径，不只验证正常路径。** 6. **PoC 只验证高风险假设，不开发完整系统。** 7. **评分用于辅助解释，不代替工程判断。** 8. **推荐必须包含适用边界、代价和退出条件。** 9. **旧决策不得覆盖，应通过新 ADR 标记替代关系。** 10. **无法验证时明确写"待验证"，禁止补全式猜测。** ## 证据分级 按以下顺序使用信息源： | 等级 | 来源 | 用途 | |---|---|---| | A | 官方文档、规范、源码、Release、官方安全公告 | 核心事实与行为确认 | | B | 官方 Benchmark、官方示例、维护者 Issue/Discussion | 实现细节和限制确认 | | C | 独立实测、生产案例、论文 | 性能与生产经验交叉验证 | | D | 高质量社区讨论、技术文章 | 发现问题和补充线索 | | E | 聚合文章、营销材料、无原始数据结论 | 仅作线索，不作为单独依据 | 所有重要证据记录： - 来源标题与链接。 - 发布或更新时间。 - 对应版本。 - 支持的具体结论。 - 证据等级。 - 是否存在利益相关。 ## 结论状态 每条关键结论必须标记为： - `CONFIRMED`：官方资料、源码、可复现实验或多源证据支持。 - `INFERRED`：基于已确认事实推导，并明确推导过程。 - `UNVERIFIED`：当前无法确认，需要 PoC、源码或生产数据验证。 - `CONFLICTED`：不同可靠来源存在冲突，必须展示冲突。 ## 标准 SOP ### Step 0：创建调研任务卡 先输出并补齐： ```markdown # 调研任务卡 ## 背景 为什么需要本次调研。 ## 决策问题 本次最终需要决定什么。 ## 业务场景 用户量、请求量、数据量、峰值、部署环境、团队能力、生命周期。 ## 硬性约束 必须支持的能力、协议、许可证、部署方式、安全要求、预算和时间。 ## 优先级 稳定性、性能、成本、开发效率、运维复杂度等排序。 ## 成功标准 可量化的通过条件。 ## 非目标 本次明确不研究的内容。 ## 决策截止时间 必须完成决策的时间。 ``` 信息不完整时，先列出假设。会显著影响结论的假设必须标记为 `UNVERIFIED`。 ### Step 1：将问题拆成可验证问题 至少覆盖： - 功能是否满足核心场景。 - 是否兼容现有技术栈和部署环境。 - 性能上限及资源消耗是否满足目标。 - 节点、网络、依赖或存储故障时会怎样。 - 数据一致性、幂等、重试和恢复机制如何。 - 部署、监控、升级、备份和回滚复杂度如何。 - 安全模型、权限、审计和供应链风险如何。 - 许可证、商业限制和厂商锁定风险如何。 - 团队学习、接入和长期维护成本如何。 - 迁移进入和退出成本如何。 每个问题必须能通过以下方式之一回答： - 文档查证。 - 源码定位。 - Issue/Release 查证。 - PoC 或 Benchmark。 - 生产案例交叉验证。 ### Step 2：建立候选集 候选通常控制在 3～5 个，并覆盖： - 主流稳定方案。 - 性能或能力上限更高的方案。 - 成本或运维更轻的方案。 - 延续现有系统的方案。 - 必要时加入"不引入新技术"作为基线。 禁止为了凑数量加入明显不匹配的方案。 ### Step 3：设置硬性淘汰条件 示例： - 不支持必需协议或功能。 - 许可证不满足商业使用要求。 - 无法在指定环境部署。 - 无法满足最低性能、可用性或一致性要求。 - 缺少必需的安全、审计或权限能力。 - 项目停止维护且无可接受替代维护方。 - 迁移或退出成本超过项目承受范围。 先淘汰，再评分。不得用其他高分抵消硬性缺陷。 ### Step 4：建立证据矩阵 使用 `templates/evidence-matrix.md`。 每条记录只表达一个结论。不要只收藏链接，必须写清链接证明了什么。 发现资料冲突时： 1. 检查是否对应不同版本、部署模式或配置。 2. 优先使用源码、规范和当前版本官方文档。 3. 无法消除冲突时标记为 `CONFLICTED`。 4. 将冲突转化为 PoC 验证项。 ### Step 5：深入审查候选方案 #### 功能与兼容性 - 核心能力是否原生支持。 - 是否依赖插件、企业版或外部组件。 - API、协议和数据格式兼容性。 - 与现有系统集成复杂度。 - Breaking Change 和向后兼容策略。 #### 性能与容量 - 吞吐、平均延迟、P95/P99。 - CPU、内存、磁盘和网络消耗。 - 数据量、连接数、分区数或租户数上限。 - 横向扩展方式和扩容期间影响。 - Benchmark 环境是否与实际场景可比。 #### 稳定性与恢复 - 高可用机制。 - 节点故障、网络分区和依赖故障行为。 - 重试、幂等、去重和一致性保证。 - 数据备份、恢复、重建和灾备能力。 - 升级失败和回滚路径。 #### 运维与可观测性 - 部署和配置复杂度。 - 日志、指标、Tracing 和告警支持。 - 容量规划和日常维护工作量。 - 滚动升级、版本兼容和配置迁移。 - 故障定位是否需要高度专门知识。 #### 安全与合规 - 身份认证、授权、租户隔离和审计。 - 密钥和敏感配置管理。 - CVE、安全公告和修复速度。 - 依赖供应链及构建发布可信度。 - 数据驻留、加密和合规要求。 #### 生态与维护状态 - 最近提交和 Release 时间。 - Release 频率与版本策略。 - 核心维护者数量和组织稳定性。 - Issue 响应速度和严重问题积压。 - 文档、SDK、插件及人才供给。 - 商业支持和替代供应商情况。 ### Step 6：识别高风险假设 按以下公式排序： ```text 风险优先级 = 发生概率 × 影响程度 × 不确定性 ``` 优先验证同时满足以下条件的问题： - 一旦判断错误会导致路线重做。 - 文档与真实行为可能不一致。 - 与特定负载、配置或故障场景有关。 - 供应商 Benchmark 无法代表实际场景。 - 涉及资金、数据一致性、安全或合规。 ### Step 7：设计和执行 PoC 使用 `templates/poc-plan.md`。 PoC 必须包含： - 单一、明确的验证目标。 - 可复现环境和配置。 - 接近实际的数据分布和流量模型。 - 明确的成功/失败标准。 - 原始日志、指标和测试脚本。 - 结果与限制。 常见测试： - 基线功能验证。 - 峰值与持续负载。 - 冷启动、扩容和重启。 - 节点宕机、网络超时和依赖不可用。 - 重复请求、重复消费和乱序。 - 磁盘写满、连接耗尽和限流。 - 升级、回滚、备份和恢复。 - 安全权限边界和越权检查。 不得将不同硬件、不同数据规模或不同配置的结果直接横向比较而不说明差异。 ### Step 8：计算成本和退出代价 至少计算 1～3 年 TCO： ```text TCO = 软件许可与支持 + 云资源或硬件 + 开发接入 + 数据迁移 + 日常运维 + 监控与备份 + 团队培训 + 升级维护 + 故障风险 + 退出与替换 ``` 同时记录： - 是否产生数据格式锁定。 - 是否依赖专有 API 或企业版能力。 - 是否可以双写、灰度和回滚。 - 替换方案需要多长时间。 ### Step 9：量化比较 建立加权矩阵： | 维度 | 建议权重范围 | |---|---:| | 功能匹配 | 20%～30% | | 稳定性与恢复 | 15%～25% | | 性能与扩展 | 10%～25% | | 运维复杂度 | 10%～20% | | 安全与合规 | 10%～20% | | 生态与维护 | 5%～15% | | 成本与退出 | 10%～20% | 评分规则： - 使用 1～10 分。 - 每个分数必须附一句依据。 - 未验证项不得给高置信度精确分，可使用区间或降低置信度。 - 总分接近时，优先选择风险更低、退出更容易的方案。 ### Step 10：形成结论 推荐结论必须包含： ```markdown ## 推荐方案 明确选择。 ## 核心理由 列出最重要的 3～5 个决策依据。 ## 为什么不选择其他方案 只写决定性差异。 ## 已确认事实 列出关键 `CONFIRMED` 结论。 ## 待验证事项 列出仍为 `UNVERIFIED` 或 `CONFLICTED` 的内容。 ## 已知风险 说明概率、影响和触发条件。 ## 缓解措施 监控、降级、备份、灰度、回滚和替代方案。 ## 适用边界 当前结论适用的规模、版本、团队和部署条件。 ## 重新评估条件 流量、成本、版本、许可证、组织或安全条件发生何种变化时重评。 ``` 禁止输出"各有优劣，请自行选择"作为最终结论。资料不足时，也要给出"暂定方案 + 必须完成的验证项"。 ### Step 11：记录 ADR 使用 `templates/adr.md`。 规则： - 调研报告保存分析过程。 - ADR 保存最终决策及后果。 - 路线改变时新增 ADR。 - 旧 ADR 标记为 `Superseded by ADR-xxx`，不得覆盖原记录。 ## 输出结构 最终报告按以下顺序输出： 1. 执行摘要。 2. 调研任务卡。 3. 场景、约束和假设。 4. 候选方案与初筛结果。 5. 证据矩阵。 6. 关键维度分析。 7. PoC/Benchmark 结果。 8. 对比评分矩阵。 9. 风险与 TCO。 10. 推荐方案与适用边界。 11. 待验证事项。 12. ADR。 13. 证据来源。 ## 执行摘要格式 ```markdown # 执行摘要 - **建议**：选择 / 暂定选择 XXX。 - **适用前提**：XXX。 - **核心依据**：XXX、XXX、XXX。 - **主要代价**：XXX。 - **最大风险**：XXX。 - **下一步**：执行 XXX 验证或进入实施。 ``` ## 质量门禁 交付前逐项检查： - [ ] 决策问题明确，不是泛泛介绍技术。 - [ ] 场景、规模、约束和成功标准明确。 - [ ] 候选方案数量合理，并包含基线方案。 - [ ] 硬性约束已先行筛选。 - [ ] 当前版本、许可证和维护状态已确认。 - [ ] 关键结论都有证据或明确标记待验证。 - [ ] 事实、推断、未知和冲突已区分。 - [ ] 不只引用厂商 Benchmark。 - [ ] 已分析故障、恢复、升级和退出路径。 - [ ] 高风险假设已有 PoC 或验证计划。 - [ ] 评分有依据，没有用平均分掩盖硬缺陷。 - [ ] 成本包含接入、运维、迁移和退出成本。 - [ ] 推荐方案明确，并说明不选其他方案的决定性原因。 - [ ] 适用边界、风险、缓解措施和重评条件完整。 - [ ] ADR 已记录最终决策。 任一核心项缺失时，不得将结果标记为"调研完成"。 ## 常见反模式 - 先选中喜欢的方案，再寻找支持证据。 - 大量罗列功能，没有明确决策问题。 - 只看官网首页、README 或营销 Benchmark。 - 不区分开源版、企业版和云托管版能力。 - 忽略具体版本、配置和部署模式。 - 用 GitHub Star 代替成熟度分析。 - 只测试正常流程，不测试故障恢复。 - PoC 做成完整项目，耗时但没有验证核心风险。 - 只计算机器费用，不计算人力、迁移和退出成本。 - 对未知项给出虚假的精确评分。 - 最终只给对比表，不给明确建议。 ## 与用户交互规则 - 用户已提供的信息不得重复询问。 - 缺少信息但可以合理假设时，先基于假设继续，并显式记录。 - 只有会改变候选集或硬性淘汰结果的信息，才作为关键澄清项。 - 调研过程中优先给出已发现的决定性风险，而不是等到最终报告。 - 用户要求简版时，保留：结论、证据、风险、待验证项和下一步。 ## 文件模板 - `templates/research-report.md`：完整调研报告。 - `templates/evidence-matrix.md`：证据矩阵。 - `templates/poc-plan.md`：PoC 计划与结果。 - `templates/adr.md`：架构决策记录。