先问对问题，再找答案——hl-research 的完整探索记录

一个关于"不知道自己不知道什么"的问题

在用 Claude Code 开发的过程中，我经常遇到同一个问题：需要在陌生领域做技术选型，但不知道从哪里问起，因为我不知道这个领域有哪些维度需要考虑。

比如我想在 Claude Code 里生成图表，我知道有 Mermaid、HTML、drawio XML 这些选项。但我不知道它们之间的选择背后，还有"渲染环境"、"工具链依赖"、"语法校验"这些维度------我是做完调研之后才知道这些维度的存在的。

在开发语言智能助手的时候，我还遇到过另一个问题：我想让 AI 调用意图理解后直接发 HTTP 请求，我知道大模型有结构化输出，于是我就顺着这个方向去调研了。调研工具也帮我出了一份"用结构化输出拼接 HTTP 调用"的方案。

但是实现后我才发现，这个问题早就被工具调用（Function Calling）和 MCP 协议解决了。我造了一个轮子，一个很差的轮子。

这不只是信息不足的问题，在陌生领域，我们很可能连方向都是错的。

调研工具的集体盲区

市面上已经有各种 AI 调研工具，Claude Code 也自带了 deep-research。它们的工作流高度一致：

用户提出明确问题 → 搜索 → 综合 → 输出答案

但这里有一个隐晦的假设：用户已经提出了正确的问题。

如果用户的问题本身就是基于错误认知拼凑出来的呢？如果用户描述的"需求"其实是一个伪装成需求的、错误的解决方案呢？

结果就是：用户说不清，AI 问不对，两边都卡住了。AI 直接按用户的问题去调研，只是在给一个错误的问题寻找完美的答案。

传统调研工具帮你在一张已知的地图上找最短路径。但它们不会告诉你------你可能连地图都拿错了。

我需要一个能帮我先确认问题本身是否正确 的调研工具。于是 hl-research 诞生了。

把"问对问题"变成一个工作流

解决这个问题，需要的不只是一次性问答，而是一个有中间交互的工作流。我把整个调研过程拆成两个阶段：
#mermaid-svg-zhvWZSb0TeY15EgY{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-zhvWZSb0TeY15EgY .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-zhvWZSb0TeY15EgY .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-zhvWZSb0TeY15EgY .error-icon{fill:#552222;}#mermaid-svg-zhvWZSb0TeY15EgY .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-zhvWZSb0TeY15EgY .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-zhvWZSb0TeY15EgY .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-zhvWZSb0TeY15EgY .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-zhvWZSb0TeY15EgY .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-zhvWZSb0TeY15EgY .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-zhvWZSb0TeY15EgY .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-zhvWZSb0TeY15EgY .marker{fill:#333333;stroke:#333333;}#mermaid-svg-zhvWZSb0TeY15EgY .marker.cross{stroke:#333333;}#mermaid-svg-zhvWZSb0TeY15EgY svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-zhvWZSb0TeY15EgY p{margin:0;}#mermaid-svg-zhvWZSb0TeY15EgY .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-zhvWZSb0TeY15EgY .cluster-label text{fill:#333;}#mermaid-svg-zhvWZSb0TeY15EgY .cluster-label span{color:#333;}#mermaid-svg-zhvWZSb0TeY15EgY .cluster-label span p{background-color:transparent;}#mermaid-svg-zhvWZSb0TeY15EgY .label text,#mermaid-svg-zhvWZSb0TeY15EgY span{fill:#333;color:#333;}#mermaid-svg-zhvWZSb0TeY15EgY .node rect,#mermaid-svg-zhvWZSb0TeY15EgY .node circle,#mermaid-svg-zhvWZSb0TeY15EgY .node ellipse,#mermaid-svg-zhvWZSb0TeY15EgY .node polygon,#mermaid-svg-zhvWZSb0TeY15EgY .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-zhvWZSb0TeY15EgY .rough-node .label text,#mermaid-svg-zhvWZSb0TeY15EgY .node .label text,#mermaid-svg-zhvWZSb0TeY15EgY .image-shape .label,#mermaid-svg-zhvWZSb0TeY15EgY .icon-shape .label{text-anchor:middle;}#mermaid-svg-zhvWZSb0TeY15EgY .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-zhvWZSb0TeY15EgY .rough-node .label,#mermaid-svg-zhvWZSb0TeY15EgY .node .label,#mermaid-svg-zhvWZSb0TeY15EgY .image-shape .label,#mermaid-svg-zhvWZSb0TeY15EgY .icon-shape .label{text-align:center;}#mermaid-svg-zhvWZSb0TeY15EgY .node.clickable{cursor:pointer;}#mermaid-svg-zhvWZSb0TeY15EgY .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-zhvWZSb0TeY15EgY .arrowheadPath{fill:#333333;}#mermaid-svg-zhvWZSb0TeY15EgY .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-zhvWZSb0TeY15EgY .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-zhvWZSb0TeY15EgY .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-zhvWZSb0TeY15EgY .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-zhvWZSb0TeY15EgY .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-zhvWZSb0TeY15EgY .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-zhvWZSb0TeY15EgY .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-zhvWZSb0TeY15EgY .cluster text{fill:#333;}#mermaid-svg-zhvWZSb0TeY15EgY .cluster span{color:#333;}#mermaid-svg-zhvWZSb0TeY15EgY div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-zhvWZSb0TeY15EgY .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-zhvWZSb0TeY15EgY rect.text{fill:none;stroke-width:0;}#mermaid-svg-zhvWZSb0TeY15EgY .icon-shape,#mermaid-svg-zhvWZSb0TeY15EgY .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-zhvWZSb0TeY15EgY .icon-shape p,#mermaid-svg-zhvWZSb0TeY15EgY .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-zhvWZSb0TeY15EgY .icon-shape .label rect,#mermaid-svg-zhvWZSb0TeY15EgY .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-zhvWZSb0TeY15EgY .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-zhvWZSb0TeY15EgY .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-zhvWZSb0TeY15EgY :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 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 生成图片方案（流程图、架构图、时序图等）怎么做比较好？用什么语言？Markdown？HTML？Mermaid？用 agent 还是 skills？

Phase 0 识别出三个独立决策轴：

输出落点：终端内联 / 浏览器预览 / 磁盘文件
触发方式：Skill（方法论） vs MCP Server（能力扩展）vs Agent
图表语言：Mermaid / D2 / HTML+SVG / PlantUML

然后问了我两个需求导向的问题：图表最终在哪里看？这个方案想做成可复用的 Skill 还是临时用法？

我的回答让方向瞬间清晰：需要 PNG/SVG 文件可提交 Git、需要浏览器预览、要做成 dotfiles 里的 /hl-diagram Skill。

Phase 1 的答案收敛得很干净：

维度	选择	理由
图表语言	Mermaid	覆盖所有图类型，Claude 理解最深
文件生成	`mmdc` + Kroki API fallback	本地优先，无依赖时自动降级
浏览器预览	生成 HTML →`/tmp/` → `open`	零依赖，macOS 原生
验证机制	mmdc 校验循环，最多 3 次重试	Claude 生成 Mermaid 有约 20% 语法错误率
Skill 架构	PureSKILL.md + `references/` 子目录	不依赖 MCP，便携

从调研到工具：`/hl-diagram` Skill

基于这份报告，/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 次，失败则停止并暴露错误，不允许无限重试。

实现完成后的第一个任务，是让它给自己画一张工具全景图，以免将来忘记包括它自己在内的工具。
#mermaid-svg-JN6ypDxy4NM6VC0z{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-JN6ypDxy4NM6VC0z .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-JN6ypDxy4NM6VC0z .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-JN6ypDxy4NM6VC0z .error-icon{fill:#552222;}#mermaid-svg-JN6ypDxy4NM6VC0z .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-JN6ypDxy4NM6VC0z .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-JN6ypDxy4NM6VC0z .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-JN6ypDxy4NM6VC0z .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-JN6ypDxy4NM6VC0z .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-JN6ypDxy4NM6VC0z .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-JN6ypDxy4NM6VC0z .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-JN6ypDxy4NM6VC0z .marker{fill:#333333;stroke:#333333;}#mermaid-svg-JN6ypDxy4NM6VC0z .marker.cross{stroke:#333333;}#mermaid-svg-JN6ypDxy4NM6VC0z svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-JN6ypDxy4NM6VC0z p{margin:0;}#mermaid-svg-JN6ypDxy4NM6VC0z .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-JN6ypDxy4NM6VC0z .cluster-label text{fill:#333;}#mermaid-svg-JN6ypDxy4NM6VC0z .cluster-label span{color:#333;}#mermaid-svg-JN6ypDxy4NM6VC0z .cluster-label span p{background-color:transparent;}#mermaid-svg-JN6ypDxy4NM6VC0z .label text,#mermaid-svg-JN6ypDxy4NM6VC0z span{fill:#333;color:#333;}#mermaid-svg-JN6ypDxy4NM6VC0z .node rect,#mermaid-svg-JN6ypDxy4NM6VC0z .node circle,#mermaid-svg-JN6ypDxy4NM6VC0z .node ellipse,#mermaid-svg-JN6ypDxy4NM6VC0z .node polygon,#mermaid-svg-JN6ypDxy4NM6VC0z .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-JN6ypDxy4NM6VC0z .rough-node .label text,#mermaid-svg-JN6ypDxy4NM6VC0z .node .label text,#mermaid-svg-JN6ypDxy4NM6VC0z .image-shape .label,#mermaid-svg-JN6ypDxy4NM6VC0z .icon-shape .label{text-anchor:middle;}#mermaid-svg-JN6ypDxy4NM6VC0z .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-JN6ypDxy4NM6VC0z .rough-node .label,#mermaid-svg-JN6ypDxy4NM6VC0z .node .label,#mermaid-svg-JN6ypDxy4NM6VC0z .image-shape .label,#mermaid-svg-JN6ypDxy4NM6VC0z .icon-shape .label{text-align:center;}#mermaid-svg-JN6ypDxy4NM6VC0z .node.clickable{cursor:pointer;}#mermaid-svg-JN6ypDxy4NM6VC0z .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-JN6ypDxy4NM6VC0z .arrowheadPath{fill:#333333;}#mermaid-svg-JN6ypDxy4NM6VC0z .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-JN6ypDxy4NM6VC0z .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-JN6ypDxy4NM6VC0z .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-JN6ypDxy4NM6VC0z .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-JN6ypDxy4NM6VC0z .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-JN6ypDxy4NM6VC0z .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-JN6ypDxy4NM6VC0z .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-JN6ypDxy4NM6VC0z .cluster text{fill:#333;}#mermaid-svg-JN6ypDxy4NM6VC0z .cluster span{color:#333;}#mermaid-svg-JN6ypDxy4NM6VC0z div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-JN6ypDxy4NM6VC0z .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-JN6ypDxy4NM6VC0z rect.text{fill:none;stroke-width:0;}#mermaid-svg-JN6ypDxy4NM6VC0z .icon-shape,#mermaid-svg-JN6ypDxy4NM6VC0z .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-JN6ypDxy4NM6VC0z .icon-shape p,#mermaid-svg-JN6ypDxy4NM6VC0z .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-JN6ypDxy4NM6VC0z .icon-shape .label rect,#mermaid-svg-JN6ypDxy4NM6VC0z .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-JN6ypDxy4NM6VC0z .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-JN6ypDxy4NM6VC0z .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-JN6ypDxy4NM6VC0z :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-JN6ypDxy4NM6VC0z .sk>*{fill:#dbeafe!important;stroke:#3b82f6!important;color:#1e3a5f!important;}#mermaid-svg-JN6ypDxy4NM6VC0z .sk span{fill:#dbeafe!important;stroke:#3b82f6!important;color:#1e3a5f!important;}#mermaid-svg-JN6ypDxy4NM6VC0z .sk tspan{fill:#1e3a5f!important;}#mermaid-svg-JN6ypDxy4NM6VC0z .ag>*{fill:#dcfce7!important;stroke:#22c55e!important;color:#14532d!important;}#mermaid-svg-JN6ypDxy4NM6VC0z .ag span{fill:#dcfce7!important;stroke:#22c55e!important;color:#14532d!important;}#mermaid-svg-JN6ypDxy4NM6VC0z .ag tspan{fill:#14532d!important;}#mermaid-svg-JN6ypDxy4NM6VC0z .ru>*{fill:#fef9c3!important;stroke:#eab308!important;color:#713f12!important;}#mermaid-svg-JN6ypDxy4NM6VC0z .ru span{fill:#fef9c3!important;stroke:#eab308!important;color:#713f12!important;}#mermaid-svg-JN6ypDxy4NM6VC0z .ru tspan{fill:#713f12!important;} Claude Code 全局配置 --- ~/.claude
Rules（路径匹配后自动注入）
java.md --- Java 工程规范
java-style.md --- Java 格式规范
Agents（子代理）
hl-backend

后端实现专家
hl-frontend

Vue 3 前端专家
Skills（/命令名触发）
评审
/hl-be-review

企业级 Java 代码评审
前端
输出 design-brief.md
/hl-fe-design

前端设计简报
/hl-fe-proto

Vue 3 组件原型
编码
/hl-commit

规范 Git 提交
/hl-test

编写并运行测试
/hl-diagram

Mermaid 图表生成
调研
/hl-research

通用调研，两阶段工作流
/hl-dev-research

项目内开发调研

图出来了，但调研过程本身也值得复盘。

最后通过调研工具本身评估本次 skills 调研的质量，从而形成闭环。

用结果反观过程

整个链条走完后，回头看，发现了几个值得记录的问题。

研究计划里出现了一个假问题。 Phase 1 的调研计划列了五个维度，其中"图表语言选型"被当成了一个需要研究的问题。但实际上，Mermaid 在盲探阶段就已经是压倒性答案------社区生态最全、Claude 理解最深、所有目标图类型全覆盖。它不应该被列为"需要研究的维度"，而应该直接作为前提约束写在计划开头。这个发现让我在 hl-research 的规则里加了一条：如果盲探后某个维度已有压倒性答案，直接声明为"前提约束"，不再列为研究维度。

确认门的价值比预想的更重要。 在确认调研计划时，我只是简单说了"go"，没有做任何修改。这看起来像是纯粹的摩擦。但这个停顿必须要有，它给了我读完计划、对照自己的理解、决定是否追问的机会。对于一个调研工具来说，确认门之前改方向，什么都不损失；过了门再改，前面的时间就白花了。

总结

每次调研后，可以留下调研过程让调研工具评估本次调研的质量，最终形成一个完美的闭环：一个工具被调研工具找到、实现，然后用来证明调研工具的质量。

如果要用一句话总结：理论上完美的设计，第一次运行就会暴露问题；但那些问题，正是让设计变得更好的原材料。

hl-claude/context/research-workflow.md 里现在有完整的设计决策记录和这次执行 trace，下次改动 hl-research 的人（包括几个月后的我自己）能看到每一个决策背后的理由，从而推动下一次的迭代。。

工具代码开源在 dotfiles 仓库。hl-research、hl-diagram 以及其他 Skill 的 SKILL.md 都在 claude/skills/ 目录下。