deep-research

深度研究

在构建新东西之前，进行全面的研究与探索。不要直接根据训练数据开始写代码，而是从多个维度深入展开——本地探索、网络研究、竞品分析、生态信号、趋势预测——并产出一份研究简报，让实际构建的效率提升 10 倍。

深度级别

区别在于目标范围，而不只是投入的时间。

深度	目的	范围
focused（聚焦）	回答一个具体问题	一个决策：「CodeMirror 还是 ProseMirror？」——有针对性地搜索、本地扫描、比较 1-2 个选项。产出一页建议。
wide（广泛）	了解整个领域	为新产品或功能梳理全貌。涵盖竞品、生态、用户需求、架构选项。足以撰写规格说明。
deep（深入）	规划大型构建项目	不放过任何细节。包含 wide 的全部内容，外加库／组件研究、插件生态、挖掘 GitHub 问题、社区情绪分析、趋势预测，以及针对每项决策的技术深度分析。足以指导数周的编码工作。

默认：wide

工作流

1. 理解意图

询问用户：

• 要构建什么？（一句话）
• **为什么？**要解决什么问题？面向谁？
• **有哪些约束？**技术栈偏好、预算、时间安排、必备功能？
• **已有成果？**有没有可以在其基础上构建的项目？有哪些代码仓库可供参考？

如果用户只提供了简短提示（「在 Cloudflare 上构建 Obsidian 替代品」），信息就足够了——通过研究补全缺失部分。

2. 本地探索

扫描用户的机器，查找相关的既有工作：

# Find related projects by name/keyword
ls ~/Documents/ | grep -i "KEYWORD"

# Read CLAUDE.md of related projects for architecture context
find ~/Documents -maxdepth 2 -name "CLAUDE.md" -exec grep -l "KEYWORD" {} \;

# Check for reusable patterns, schemas, components
find ~/Documents -maxdepth 3 -name "schema.ts" -o -name "ARCHITECTURE.md" | head -20

对于找到的每个相关项目：

• 阅读 CLAUDE.md（技术栈、架构、注意事项）
• 检查可复用代码（架构定义、组件、实用工具、配置）
• 记录哪些做法有效、哪些无效（查看 git 历史记录、TODO 注释）

还要检查：

• Basalt Cortex（~/Documents/basalt-cortex/）中相关的客户、联系人、知识事实
• grep -rl "KEYWORD" ~/Documents/basalt-cortex/ --include="*.md"

3. 网络研究

广泛搜索，了解整个领域：

• 产品类别：「markdown 笔记应用」、「团队知识管理工具」
• 竞品：搜索「最佳 X」、「X 替代品」、「X 与 Y 对比」，找出排名靠前的 5-10 款产品
• 开源项目：在 GitHub 上搜索开源替代品，查看星标数
• 架构：「如何构建 X」、「X 技术栈」、「使用 [框架] 构建 X」
• 技术文档：查看 llms.txt 和关键技术的官方文档
• 平台示例：「使用 Cloudflare Workers 构建」、「D1 全文搜索示例」
• 教程与案例研究：「从头构建 Y」、「构建 Z 的经验教训」

4. 生态系统与社区调研（广泛 + 深入）

超越核心产品——生态系统能揭示用户的实际需求：

插件和附加组件：

• 主要竞品有哪些插件？最受欢迎的插件能揭示核心产品的不足之处。
• 例如，Obsidian 有 1800 多个插件——排名前 20 的插件能告诉你 Obsidian 原生功能有哪些不足。
• 搜索："top [product] plugins"、"[product] plugin directory"

GitHub 问题和功能请求：

• 查看主要竞品的 GitHub 仓库，了解获赞最多的问题
• 按点赞表情排序——这是直接的用户需求信号
• 查看已关闭的问题，了解功能是如何实现的

论坛讨论：

• Reddit：r/[product]、r/selfhosted、r/webdev 及相关细分主题版块
• Hacker News：搜索产品类别
• Discord/Discourse：产品专属社区
• 用户喜欢什么？他们抱怨什么？他们希望有哪些功能？

应用商店和评价网站：

• 1 星评价 = 尚未满足的需求（产品在这方面表现不佳）
• 5 星评价 = 值得保留的优点（用户喜欢这些，不要破坏）
• 3 星评价 = 值得关注的中间地带（还可以，但是……）
• 搜索：ProductHunt、G2、Capterra、App Store 评价

集成请求：

• 用户希望连接哪些系统？（Zapier 集成、API 请求）
• 这些请求揭示了真实的工作流——用户会把各种工具临时拼凑在一起

5. 竞品深度分析（广泛 + 深入）

针对每个主要竞品（广泛调研选 3-5 个，深入调研选 5-10 个）：

问题	调研方式
功能	落地页、文档、更新日志
定价	定价页面、对比网站
用户投诉	Reddit、HN、应用商店评价
技术栈	Wappalyzer、view-source、招聘信息、博客文章
做得好的方面	5 星评价、产品演示
做得不好的方面	1 星评价、论坛投诉、迁出该产品的迁移指南
文档质量	阅读其文档网站——内容是否全面？哪些主题需要最多解释？（复杂主题 = 用户难以掌握的内容）
帮助与支持内容	帮助中心、FAQ、知识库、支持论坛——用户最常问哪些问题？
新手引导/教程	入门指南、视频教程、交互式导览——他们如何教用户使用产品？他们认为用户已经了解什么？
API 文档	如果有 API——文档完善吗？采用了哪些模式？提供了哪些 SDK？
迁移指南	是否提供“从 X 切换”的指南？这能揭示他们认为自己的优势是什么，以及用户觉得哪些产品难以替换

6. 库和组件研究（深度模式）

研究构建模块——了解已有的可用资源，以及可以借鉴的内容：

React / UI 库：

• 在 npm 上搜索特定类别的包（“react markdown editor”“react kanban”“react data table”）
• 查看每周下载量、最近发布日期、GitHub 星标数和未解决问题数
• 阅读 README 和示例——它们使用了哪些模式？
• 查看包体积（bundlephobia.com）——是否符合项目限制？
• 查看最佳库的源代码——它们的架构经过了真实使用的验证

无头 / 无样式库：

• Headless UI、Radix、React Aria、Downshift——有哪些原语可用于你需要的功能？
• 它们通常优于完整组件库，因为你可以控制样式
• 查看 shadcn/ui 是否已经封装了你需要的内容

Hooks 和工具：

• TanStack（Query、Table、Virtual、Router）——哪些与项目相关？
• React Hook Form、Zod、date-fns、Zustand——这些是解决常见问题的成熟方案
• 搜索“awesome-react”列表和精选合集

平台专属库：

• 对于 Cloudflare：哪些库适用于 Workers？（不支持 Node.js API 和原生模块）
• 查看 Cloudflare 自己的示例和入门模板
• 搜索“cloudflare workers”加上你需要的功能

每个库需要记录的内容：

问题	重要性
它能解决我们的问题吗？	功能是否匹配
包体积	性能预算
最近发布日期	是否仍在维护？
未解决问题 / PR	社区健康状况
能否在我们的平台上运行？	Cloudflare Workers 有一些限制
它使用了哪些模式？	即使我们不使用该库，它的模式也很有价值

启示：即使你决定自行构建，研究现有库也能让你了解经受真实用户检验的模式。一个有 10K 星标的库，其 API 已经经过数千名开发者的改进——借鉴它们的设计决策。

7. 平台能力深入研究（广泛 + 深入）

这至关重要。 Claude 的训练数据总是落后于平台功能。Cloudflare、Vercel、Firebase、Supabase 都在不断推出新功能。你以为不存在的功能，可能上个月才刚刚发布。Basalt Cortex 项目的出现，正是因为有些能力（Workers AI toMarkdown、Vectorize 元数据筛选、D1 FTS5）只有主动查找才能发现。

不要依赖训练数据了解平台能力。 请查阅当前的实际文档。

如何研究平台

1. 获取平台的更新日志 / 博客：

   • Cloudflare：https://blog.cloudflare.com/ + https://developers.cloudflare.com/changelog/
   • Vercel：https://vercel.com/changelog
   • Firebase：https://firebase.google.com/support/releases
   • Supabase：https://supabase.com/changelog

2. 阅读完整的产品目录——不只是你已经在用的服务：

   • Cloudflare：Workers、D1、R2、KV、Vectorize、Queues、Durable Objects、Workers AI、AI Gateway、Workflows、Containers、Browser Rendering、Tunnel、Email Routing、Images、Stream、Hyperdrive、Pipelines、Sandbox
   • Vercel：Functions、Edge Middleware、KV、Postgres、Blob、AI SDK、Cron、Firewall
   • Firebase：Firestore、Auth、Storage、Functions、Hosting、Extensions、Genkit、App Check

3. 针对每项服务，思考：它能解决我们正在构建的产品中的问题吗？

4. 寻找近期推出、拓展了可能性的功能：

   • 边缘端是否有新的 AI 模型可用？
   • 是否有新的存储原语？
   • 是否有新的网络功能？
   • 是否有新的身份验证 / 身份管理功能？
   • 是否有新的构建 / 部署选项？

Cloudflare 能力清单（扩展至其他平台）

逐项查看并思考：“这对我们正在构建的产品有用吗？”

类别	需要调研的服务
计算	Workers、Cron Triggers、Queues consumers、Workflows（多步骤）、Containers、Durable Objects（有状态）、Tail Workers
存储	D1（SQL + FTS5）、R2（对象）、KV（键值）、Durable Object 存储（强一致性）
AI	Workers AI 模型（文本、图像、嵌入、语音、翻译、toMarkdown）、Vectorize（语义搜索）、AI Gateway（缓存／路由）
网络	自定义域名、Tunnel、Spectrum（TCP/UDP）、WebSockets、Hyperdrive（数据库代理）
安全	WAF、Turnstile（CAPTCHA）、Bot Management、API Shield、DDoS
媒体	Images（实时调整大小／优化）、Stream（视频）、Browser Rendering（截图、PDF 生成）
电子邮件	Email Routing（规则）、Email Workers（可编程的入站邮件处理）
可观测性	Workers Logs、Analytics Engine、GraphQL 分析

需要记录的内容

对于每项相关能力，请记录：

• 它的功能（一句话）
• 在本产品中可如何使用
• 任何限制或定价方面的考量
• 示例：“Workers AI toMarkdown() 可在边缘将任何上传的 PDF/DOCX 转换为 markdown——我们可以用它导入文档，而无需任何外部服务”

为什么这很重要

“构建一个笔记应用”和“构建一个笔记应用，它能将任何文件转换为 markdown、对所有笔记进行语义搜索、用 AI 生成摘要、通过后台 Workflows 同步，并用 Browser Rendering 渲染 PDF”之间的区别，在于了解平台提供的能力。大多数开发者只使用平台 20% 的功能，因为他们从未了解其余 80%。

8. 未来展望（深入模式）

思考超越当下的可能性：

平台路线图：根据以上对更新日志和博客的研究，平台将朝什么方向发展？哪些功能处于 Beta 阶段？哪些已发布公告但尚未 GA？

AI 集成：不要只想着“添加聊天机器人”——要深入思考。当工具能够读取用户数据、对其进行推理并采取行动时，有哪些可能性？如果每条笔记都能进行语义搜索呢？如果应用能为自己编写文档呢？如果上传的文件能自动转换为 markdown 呢？

设备与输入方式的演进：移动优先、语音输入、可穿戴设备、空间计算。未来 2-5 年，用户可能会如何与之交互？

数据源：还可以接入哪些新的输入？传感器、API、实时数据、跨应用上下文？

相邻机会：有哪些问题与这个问题相邻？例如，构建笔记应用——相邻领域包括任务管理、项目跟踪、团队沟通。用户如今正把哪些工具勉强拼凑在一起使用？

融合趋势：哪些独立工具正在融合？（电子邮件 + 聊天 + 任务 = Slack。笔记 + 数据库 + Wiki = Notion。下一个会是什么？）

9. 技术调研（深入模式）

针对每项主要架构决策：

决策领域	需要回答的问题
编辑器／UI 框架	选项、权衡、社区规模、我们的经验
数据库	SQL、NoSQL 还是文件；托管还是可自托管；我们的技术栈支持情况
身份验证	Better-auth、Clerk、Auth.js、自定义方案——哪种最合适？
托管／部署	Cloudflare、Vercel、Railway——约束和能力
搜索	FTS5、Elasticsearch、Meilisearch、Vectorize——适用于多大规模？
实时功能	WebSockets、SSE、Durable Objects——我们需要吗？
文件存储	R2、S3、本地存储——访问模式如何？
API 设计	REST、tRPC、GraphQL——用例需要什么？

10. 综合

生成一份研究简报，并保存到 .jez/artifacts/research-brief-{topic}.md：

# Research Brief: [Topic]
**Depth**: [focused|wide|deep]
**Date**: YYYY-MM-DD
**Research time**: [duration]

## Executive Summary
[2-3 sentences: what to build, why, key insight from research]

## Competitive Landscape
| Product | Strengths | Weaknesses | Pricing | Users |

### Key Insights
[What winners do well, what gaps exist in the market]

## Ecosystem Signals
### Most Popular Plugins/Add-ons
[Top plugins for competitors — reveals unmet needs]
### Most Requested Features
[From GitHub issues, forums, reviews — sorted by demand]
### Integration Patterns
[What systems users connect to — reveals real workflows]

## User Needs
[What real users want, from reviews/forums/complaints]

## Technical Landscape
| Decision | Options | Recommendation | Why |

## Libraries and Components
| Need | Library | Stars | Size | Fits platform? | Notes |
[Key libraries evaluated for each major feature]

## Platform Capabilities
| Service | Could use for | Impact |
[Every platform service evaluated against the product's needs]
[Flag recently shipped features the team may not know about]

## Reusable From Existing Projects
| Project | What to reuse | Location |

## Future Possibilities
### Platform roadmap
### AI opportunities
### Adjacent problems
### 2-5 year horizon

## Proposed Architecture
[Stack, data model sketch, key flows]

## Risks and Open Questions
[Things research couldn't answer]

## Suggested Phases
[Build order based on research findings]

## Sources
[Links to everything read]

提示

• 尽早开始编写简报，并在研究过程中不断补充——这份文档就是交付成果
• 对于深度模式，使用子 Agent 并行开展网络研究和本地探索
• “可从现有项目复用的内容”一节通常能节省数周时间
• 生态信号（插件、问题、评价）通常比竞品功能列表更有价值
• 将简报保存到 .jez/artifacts/——它对后续会话和实际构建阶段都很有用
• 简报是一份持续更新的文档——在构建过程中了解更多后，请及时更新