一个关于不知道自己不知道什么的问题在用 Claude Code 开发的过程中我经常遇到同一个问题需要在陌生领域做技术选型但不知道从哪里问起因为我不知道这个领域有哪些维度需要考虑。比如我想在 Claude Code 里生成图表我知道有 Mermaid、HTML、drawio XML 这些选项。但我不知道它们之间的选择背后还有渲染环境、“工具链依赖”、语法校验这些维度——我是做完调研之后才知道这些维度的存在的。在开发语言智能助手的时候我还遇到过另一个问题我想让 AI 调用意图理解后直接发 HTTP 请求我知道大模型有结构化输出于是我就顺着这个方向去调研了。调研工具也帮我出了一份用结构化输出拼接 HTTP 调用的方案。但是实现后我才发现这个问题早就被工具调用Function Calling和 MCP 协议解决了。我造了一个轮子一个很差的轮子。这不只是信息不足的问题在陌生领域我们很可能连方向都是错的。调研工具的集体盲区市面上已经有各种 AI 调研工具Claude Code 也自带了 deep-research。它们的工作流高度一致用户提出明确问题 → 搜索 → 综合 → 输出答案但这里有一个隐晦的假设用户已经提出了正确的问题。如果用户的问题本身就是基于错误认知拼凑出来的呢如果用户描述的需求其实是一个伪装成需求的、错误的解决方案呢结果就是用户说不清AI 问不对两边都卡住了。AI 直接按用户的问题去调研只是在给一个错误的问题寻找完美的答案。传统调研工具帮你在一张已知的地图上找最短路径。但它们不会告诉你——你可能连地图都拿错了。我需要一个能帮我先确认问题本身是否正确的调研工具。于是hl-research诞生了。把问对问题变成一个工作流解决这个问题需要的不只是一次性问答而是一个有中间交互的工作流。我把整个调研过程拆成两个阶段Phase 1 — 定向深研Phase 0 — 盲探与澄清Research Workflow开始开始盲搜了解技术全景识别独立决策维度翻译成需求导向问题用户回答确认调研计划定向深研并行搜索所有维度每维度给出默认推荐跨维度一致性校验输出完整报告Phase 0 不做方案调研。它只做一件事帮用户发现自己不知道的维度然后翻译成不需要领域知识就能回答的问题。这里有一条规则Phase 0 的所有问题必须是需求导向的不能是技术导向的。错误问法「应该用 Mermaid 还是 HTML」正确问法「你希望图表最终在哪里查看——浏览器终端还是提交到 Git 的文件」区别在于用户来做调研就是因为不懂这个领域。如果问题需要领域知识才能回答那这个问题本身就是错的。回到之前那个用结构化输出发 HTTP的例子。Phase 0 不会直接开始调研怎么拼接 HTTP 请求。它会先盲搜整个AI 调用外部服务的技术全景然后识别出用户可能不知道的维度。比如是否希望 AI 自动选择调用时机“需要调用的目标系统有没有现成的 API 描述规范”。然后反过来问用户。在这些问题的答案出来之前不会开始任何方案调研。另一个关键设计是调研计划确认门Phase 0 结束后会把即将研究的维度和方向列出来等用户确认再进入 Phase 1。这个停顿不是摩擦。调研一旦跑偏花掉的时间就回不来了。确认门之前改方向什么都不损失过了门再改前面的时间就白花了。这可以让我读完计划对照自己的理解决定要不要追问。至于第二个阶段反而和其他的调研工具差不多因为问对问题确定方向才是最重要的第一次实战Claude Code 画图方案hl-research写完后的第一个实战/hl-research Claude Code 生成图片方案流程图、架构图、时序图等怎么做比较好用什么语言MarkdownHTMLMermaid用 agent 还是 skillsPhase 0 识别出三个独立决策轴输出落点终端内联 / 浏览器预览 / 磁盘文件触发方式Skill方法论 vs MCP Server能力扩展vs Agent图表语言Mermaid / D2 / HTMLSVG / PlantUML然后问了我两个需求导向的问题图表最终在哪里看这个方案想做成可复用的 Skill 还是临时用法我的回答让方向瞬间清晰需要 PNG/SVG 文件可提交 Git、需要浏览器预览、要做成 dotfiles 里的/hl-diagramSkill。Phase 1 的答案收敛得很干净维度选择理由图表语言Mermaid覆盖所有图类型Claude 理解最深文件生成mmdc Kroki API fallback本地优先无依赖时自动降级浏览器预览生成 HTML →/tmp/→open零依赖macOS 原生验证机制mmdc 校验循环最多 3 次重试Claude 生成 Mermaid 有约 20% 语法错误率Skill 架构PureSKILL.md references/子目录不依赖 MCP便携从调研到工具/hl-diagramSkill基于这份报告/hl-diagram实现了skills/hl-diagram/ ├── SKILL.md # 主流程类型推断、生成、校验循环、输出 └── references/ ├── flowchart.md # 从 mermaid.js.org 裁剪的语法参考 ├── sequence.md ├── architecture.md ├── class.md ├── er.md └── common-errors.md # 常见语法错误速查两个设计细节按需加载 reference。每次调用只读入对应图类型的参考文件而不是把所有语法文档一次性塞进 context。实测发现如果五种图类型的语法全部加载无关内容会干扰 Claude反而更容易把不同图类型的语法混淆。语法验证是强制循环。Claude 生成的 Mermaid 代码大约有 20% 的语法错误率不是不懂语法而是长 context 下容易漏掉细节。所以 Skill 硬编码了生成 → 验证 → 修复 → 再验证最多 3 次失败则停止并暴露错误不允许无限重试。实现完成后的第一个任务是让它给自己画一张工具全景图以免将来忘记包括它自己在内的工具。Claude Code 全局配置 — ~/.claudeRules路径匹配后自动注入java.md — Java 工程规范java-style.md — Java 格式规范Agents子代理hl-backend后端实现专家hl-frontendVue 3 前端专家Skills/命令名 触发评审/hl-be-review企业级 Java 代码评审前端输出 design-brief.md/hl-fe-design前端设计简报/hl-fe-protoVue 3 组件原型编码/hl-commit规范 Git 提交/hl-test编写并运行测试/hl-diagramMermaid 图表生成调研/hl-research通用调研两阶段工作流/hl-dev-research项目内开发调研图出来了但调研过程本身也值得复盘。最后通过调研工具本身评估本次 skills 调研的质量从而形成闭环。用结果反观过程整个链条走完后回头看发现了几个值得记录的问题。研究计划里出现了一个假问题。Phase 1 的调研计划列了五个维度其中图表语言选型被当成了一个需要研究的问题。但实际上Mermaid 在盲探阶段就已经是压倒性答案——社区生态最全、Claude 理解最深、所有目标图类型全覆盖。它不应该被列为需要研究的维度而应该直接作为前提约束写在计划开头。这个发现让我在hl-research的规则里加了一条如果盲探后某个维度已有压倒性答案直接声明为前提约束不再列为研究维度。确认门的价值比预想的更重要。在确认调研计划时我只是简单说了go没有做任何修改。这看起来像是纯粹的摩擦。但这个停顿必须要有它给了我读完计划、对照自己的理解、决定是否追问的机会。对于一个调研工具来说确认门之前改方向什么都不损失过了门再改前面的时间就白花了。总结每次调研后可以留下调研过程让调研工具评估本次调研的质量最终形成一个完美的闭环一个工具被调研工具找到、实现然后用来证明调研工具的质量。如果要用一句话总结理论上完美的设计第一次运行就会暴露问题但那些问题正是让设计变得更好的原材料。hl-claude/context/research-workflow.md里现在有完整的设计决策记录和这次执行 trace下次改动hl-research的人包括几个月后的我自己能看到每一个决策背后的理由从而推动下一次的迭代。。工具代码开源在hl-claude-plugins。本文首发于个人博客先问对问题再找答案——hl-research 的完整探索记录