Tech scout

Tech Scout

目标

在开始新项目、增加重要模块或引入关键依赖之前，先完成项目分析、技术侦察、候选比较和最小验证设计，避免重复造轮子，也避免为了“先进”而过度设计。

最终目标不是选出理论上最强的技术，而是选出：

• 能解决当前真实问题；
• 能较快完成可运行 MVP；
• 与现有项目和部署环境兼容；
• 对当前开发者基础和 AI 辅助工作流友好；
• 有足够文档、社区和维护保障；
• 许可证、安全和长期替换风险可接受；
• 后续仍有合理扩展空间；

的技术路线。

未完成技术侦察前，不得直接进入大规模正式编码。

适用对象与默认偏好

默认面向低基础或正在通过 AI 辅助开发提升工程能力的开发者。

除非项目明确要求，否则优先考虑：

• 学习成本；
• 开发速度；
• MVP 可落地性；
• 可维护性和可排错性；
• 官方文档与社区资料；
• 中文资料和国内开发环境适配；
• 企业实际使用情况；
• 是否适合作为简历、实习或求职项目；
• 后续扩展与替换成本。

不要默认选择微服务、分布式系统、复杂消息队列、Kubernetes、事件溯源或其他重型架构。只有需求、规模或现有系统明确证明其必要性时，才能推荐。

核心规则

• 先检查当前项目，再搜索外部方案。
• 先确认现有依赖是否已经提供所需能力。
• 先拆分问题和系统模块，再选择技术。
• 搜索必须使用多个具体英文关键词，不能只用用户原话。
• 优先使用官方文档、官方仓库、包注册中心和持续维护的一手来源。
• GitHub Star 只能作为发现信号，不能作为选型结论。
• 未预览内容前，不得安装未知 Agent Skill。
• 未检查仓库前，不得执行陌生项目中的脚本。
• 不得把教学 Demo 直接包装成生产方案。
• 不得为了避免少量简单代码而引入沉重依赖。
• 不能验证的信息必须明确标记为“不确定”。
• 结论必须记录关键版本、来源和检索日期。
• 用户只要求调研时，在报告完成后停止，不得擅自编码。

工作流

第 0 步：收集上下文并声明假设

优先从以下来源获取信息：

1. 当前对话；
2. 当前项目文件；
3. README、AGENTS.md 和架构文档；
4. 已有代码、依赖和配置；
5. 用户已明确提供的背景和约束。

需要明确以下信息：

1. 项目一句话描述；
2. 主要用户；
3. 核心功能；
4. 是否需要登录注册；
5. 是否需要角色权限；
6. 是否需要后台管理；
7. 是否需要数据库；
8. 是否存在设备接入、实时通信、视频、文件上传、AI 模型调用等特殊需求；
9. 预期数据量、并发量和设备数量；
10. 部署环境；
11. 开发者当前技术基础；
12. MVP 最小可行目标；
13. 安全、许可证和合规限制；
14. 时间、预算和硬件资源限制。

不要机械地逐条询问用户。

缺失但不会改变主要路线的信息，应做合理假设并明确列出。只有缺失信息会导致高风险、不可逆或完全不同的技术路线时，才提出最少量的关键问题。

输出：

已知信息

明确假设

仍需验证的关键问题

---

第 1 步：检查当前项目

读取适用的项目文件，包括但不限于：

• package.json；
• pom.xml；
• build.gradle 或 build.gradle.kts；
• requirements.txt；
• pyproject.toml；
• Cargo.toml；
• go.mod；
• Dockerfile；
• Docker Compose 文件；
• README.md；
• AGENTS.md；
• 架构和部署文档；
• 依赖锁文件；
• 数据库迁移文件；
• 环境配置示例。

识别：

• 编程语言和版本；
• 框架及版本；
• 依赖管理工具；
• 当前已有依赖；
• 前后端结构；
• 数据库、缓存、消息系统和存储；
• 网络协议和设备接入方式；
• 部署环境；
• 测试、CI 和日志体系；
• 安全和权限要求；
• 许可证限制；
• 性能和规模约束。

必须先回答：

1. 当前技术栈是否已经提供所需能力？
2. 能否通过当前框架的官方扩展完成？
3. 是否只需要少量本地代码？
4. 引入新依赖的收益是否大于集成、维护和安全成本？

输出：

当前组件	版本/状态	已有能力	与本需求的关系	是否需要变更

---

第 2 步：判断项目类型

一个项目可以同时属于多个类型。

从以下类型中判断：

• 管理后台 / CRUD 系统；
• 普通业务后端；
• 物联网设备接入系统；
• 实时通信系统；
• 文件、图片或视频管理系统；
• 流媒体系统；
• AI 应用后端；
• 数据分析或可视化系统；
• 小程序或移动端后端；
• 桌面应用；
• 自动化工具；
• 基础设施或运维系统；
• 其他。

输出：

项目类型	命中原因	对技术选型的影响

必须说明项目类型对以下方面的影响：

• 核心框架；
• 数据模型；
• 网络通信；
• 存储；
• 实时性；
• 部署；
• 测试；
• 安全；
• 可观测性。

---

第 3 步：拆分系统模块

不要试图用一个框架解决全部问题。

把系统拆成可独立判断的模块，例如：

• 用户端前端；
• 后台管理页面；
• 后端 API；
• 身份认证与权限；
• 设备接入层；
• 实时通信层；
• 业务处理层；
• 数据库；
• 缓存；
• 消息队列；
• 文件或对象存储；
• 视频或流媒体；
• AI 模型接入；
• 定时任务；
• 日志、监控与告警；
• 部署和运维。

输出：

模块	作用	是否 MVP 必需	当前项目已有能力	候选技术	备注

将模块分为：

• MVP 必须；
• MVP 可选；
• 后续扩展；
• 当前不应实现。

---

第 4 步：生成搜索策略并执行外部侦察

4.1 生成搜索词

不能只使用用户原始措辞。

生成多组具体英文搜索词，覆盖：

• starter；
• template；
• boilerplate；
• reference implementation；
• production ready；
• framework；
• library；
• plugin；
• SDK；
• integration；
• best practices；
• awesome list；
• 对应语言、框架、协议、数据库和部署环境。

搜索词必须区分：

1. 完整技术路线；
2. 单个系统模块；
3. 当前技术栈的官方扩展；
4. 可二次开发的完整系统；
5. 最小参考实现。

4.2 搜索 Agent Skills

使用 GitHub CLI 搜索相关 Skill：

gh skill search "<topic>" --limit 10

对候选 Skill 先预览：

gh skill preview OWNER/REPOSITORY SKILL_NAME

检查：

• Skill 是否真正匹配当前任务；
• 仓库所有者和可信度；
• 指令是否清晰；
• 是否包含危险命令；
• 是否会下载或执行未知内容；
• 是否与现有 Skill 重复。

不得因为 Star 较高而直接安装。

4.3 搜索 GitHub 仓库

至少执行两类搜索：

1. 按相关度或 Star 排序；
2. 按最近更新时间排序。

示例：

gh search repos "<query>" \
  --archived=false \
  --sort stars \
  --order desc \
  --limit 20 \
  --json fullName,description,stargazersCount,pushedAt,updatedAt,license,url

gh search repos "<query>" \
  --archived=false \
  --sort updated \
  --order desc \
  --limit 20 \
  --json fullName,description,stargazersCount,pushedAt,updatedAt,license,url

还应根据场景查询：

• 官方框架文档；
• 官方组织仓库；
• Maven Central、npm、PyPI、crates.io、NuGet 等包注册中心；
• 官方 Starter 或示例项目；
• Release Notes；
• Migration Guide；
• Security Advisory；
• 国内企业场景中的公开技术资料；
• 中文社区资料，但不能用中文二手文章替代官方证据。

输出：

实际使用的搜索词

搜索来源

初步候选池

---

第 5 步：形成并评估候选路线

给出至少 3 条有真实可行性的完整路线。若确实只有 1 到 2 条合理路线，不得为了凑数加入明显不合适的方案，应说明原因。

最终严肃候选不得超过 5 条。

每条路线必须解释：

• 由哪些技术组成；
• 每项技术解决什么问题；
• 哪些部分可直接复用；
• 哪些部分仍需自行开发；
• 是否适合当前 MVP；
• 是否适合当前开发者基础；
• 是否适合 AI 辅助开发；
• 是否适合简历或实习项目。

对每个候选检查：

• 需求匹配度；
• 支持的语言、运行时和框架版本；
• 最近提交；
• 最近 Release；
• 发布频率；
• Issue 和 PR 活跃度；
• 维护者响应情况；
• 维护者数量与连续性；
• 文档质量；
• 测试和 CI；
• 部署方式；
• 升级和迁移说明；
• 安全敏感设计；
• 已知漏洞或过旧依赖；
• 许可证；
• 与当前项目的兼容性；
• 集成成本；
• 运维复杂度；
• 性能和资源占用；
• 中文资料；
• 国内企业使用情况；
• 后续替换成本；
• 项目锁定风险。

排除：

• 已归档仓库；
• 长期无人维护且没有可信继任者的项目；
• 许可证不兼容的项目；
• 文档与当前代码明显不一致的项目；
• 只适合教学的 Demo；
• 集成或运维成本大于实际收益的方案；
• 明显超出需求的重型依赖；
• 仅因流行或“现代”而被推荐的方案。

输出：

方案	技术组成	解决的问题	需求匹配	MVP 速度	学习成本	AI 开发友好度	中文资料/企业使用	维护状态	部署复杂度	许可证	主要风险

---

第 6 步：过度设计与反向过度设计审查

对每个候选路线进行批判性检查。

必须回答：

1. 哪些功能现在不该做？
2. 哪些技术只是为了炫技？
3. 哪些技术会增加部署和排错难度？
4. 哪些技术对低基础开发者风险过高？
5. 哪些功能可以后期再加？
6. 哪些需求可以先用更简单的实现验证？
7. 是否为了避免几十行简单代码而引入了沉重依赖？
8. 是否把未来可能发生的问题当成了现在必须解决的问题？
9. 是否存在单体方案已经足够，却错误引入微服务或分布式组件的情况？
10. 是否存在“看起来适合简历”，但实际上无法证明工程能力的功能堆砌？

输出：

风险点	所属方案	为什么危险	对 MVP 的影响	降级方案

---

第 7 步：核验排名最高的候选

对排名最高的两个候选使用 Context7 查询当前版本和官方文档。

确认：

• 当前安装方式；
• 当前稳定版本；
• 支持的语言和框架版本；
• 准确 API 或配置；
• 官方推荐集成方式；
• 已废弃功能；
• 破坏性变更；
• 迁移要求；
• 已知限制。

不得在可以查询当前文档时依赖模型记忆。

如果 Context7 未收录该项目，则使用：

1. 官方文档；
2. 官方仓库；
3. Release Notes；
4. Migration Guide；
5. 源码和测试；

作为主要证据。

如果两个方案仍存在必须通过实验才能解决的重大不确定性，例如：

• 性能；
• 兼容性；
• 协议行为；
• 部署方式；
• 故障恢复；
• 资源占用；

则调用 $create-technical-spike，设计限时最小实验。

不得为了形式完整而对所有普通选型都执行技术 Spike。

输出：

核验项	候选 A	候选 B	证据来源

---

第 8 步：给出最终 MVP 技术路线

必须给出明确推荐，不能只罗列方案后让用户自己猜。

输出结构：

推荐方案

项目与需求摘要

当前项目约束

推荐技术栈

按模块说明：

模块	推荐技术	版本	使用方式	选择理由

选择理由

说明：

• 为什么适合当前需求；
• 为什么适合当前开发者基础；
• 为什么适合 MVP；
• 为什么比自行从零实现更合理；
• 为什么不会造成不可接受的长期负担。

不选择其他方案的理由

逐项说明真正的淘汰原因，不得使用“综合考虑”等空话。

可直接复用的部分

必须自行开发的部分

MVP 功能范围

只列第一阶段必须跑通的功能。

暂不实现功能

明确说明推迟原因和未来触发条件。

技术、运维、安全和许可证风险

后续扩展路线

说明扩展条件，不得默认提前建设。

第一周开发任务

按可验收的任务拆分，不得只列“搭建环境”“学习框架”等模糊事项。

最小 PoC

说明：

• 要验证的核心假设；
• 最小代码范围；
• 测试数据；
• 成功条件；
• 失败条件；
• 回滚方式。

验收标准

验收标准必须可操作、可观察、可复现。

来源、版本与检索日期

未能验证的信息

---

第 9 步：生成给 AI 编程工具的开发提示词

在技术路线确定后，生成一段可直接交给 Codex、Cursor 或 Claude Code 的开发提示词。

提示词必须包括：

1. 项目目标；
2. 用户和使用场景；
3. 已确定的技术栈及版本；
4. 模块边界；
5. MVP 功能；
6. 暂不实现的功能；
7. 当前已有项目和依赖；
8. 第一阶段任务；
9. 目录和代码边界；
10. 禁止过度设计；
11. 禁止未经论证擅自更换技术路线；
12. 先完成最小可运行版本；
13. 每一步完成后的验证方法；
14. 错误处理和日志要求；
15. 测试要求；
16. 重大技术不确定性出现时重新调用 $tech-scout；
17. 需要实验验证时调用 $create-technical-spike。

开发提示词不得要求一次性实现全部未来功能。

实现边界

如果用户只要求：

• 调研；
• 技术选型；
• 框架比较；
• 架构建议；
• 依赖选择；
• 项目规划；

则在交付报告和开发提示词后停止。

如果用户明确要求实现：

1. 完成技术侦察；
2. 选择推荐方案；
3. 创建最小 PoC；
4. 验证关键路径；
5. 验证兼容性、部署、性能和失败行为；
6. 记录验证结果；
7. PoC 成功后再集成到正式项目。

在重大技术不确定性未解决前，不得进行大规模生产实现。

PoC 期间不得修改与验证目标无关的项目部分。

不得擅自安装未知 Skill、执行陌生脚本、引入重型依赖或改变主技术路线。