HDD: Hypothesis-Driven Development

六步流程:Step 0 → HT → PT → AT Design → DEV → AT Run → E2E

每个测试阶段的核心动作相同:写测试用例 → 执行 → 判定通过/不通过。 信息收集(查数据、搜网、读文档、跑命令)是写测试用例的输入,不是判定依据。

流程

0. Resource Mapping(资源映射)- 动手前必做

最底层的错误假设,是假设了自己的能力边界而没有去核实。

在提任何技术假设之前,先回答:"我有哪些资源可以帮我解决这个问题?"

- 自身能力:
  - Agent 自身的工具、权限、配置: [我能直接做什么？有没有已有能力可以用？]
  - .env.secrets / API keys: [有没有未使用的认证或服务?]
- 本地知识:
  - product-plan / HANDOFF: [有没有已规划但未实现的方案?]
  - 已有代码/配置/脚本: [有没有相关但未启用的能力?]
  - memory / 文件系统: [之前讨论过这个问题吗?已有什么相关资料?]
- 外部资源 (涉及外部平台/API 时必走这三检):
  - 【时效性】涉及的平台/技术最近 30 天有没有重大变化/官方公告?
    - 必搜:`<平台> agent skill 2026` / `<平台> api 变更` / `<平台> sdk 发布`
    - **不能把训练数据或本地测试结果当成平台当前状态**
  - 【跨入口】除了我熟悉的入口(web 抓取/cookie/反爬绕过),这个平台还有没有别的官方入口?
    - 常见官方入口:Agent Skill / MCP Server / 官方 SDK / Bot API / 开放平台 / API Key (Bearer)
    - 一条路死不等于赛道死。必问:"这是赛道问题还是路径问题?"
  - 【调用上下文】**同一个 endpoint 从不同上下文调可能表现完全不同**。看到 endpoint 返回 errCode 不要先判"endpoint 死了",先试换调用上下文:
    - 从**原始浏览器 session 内部** fetch with `credentials:'include'`(使用 puppeteer.connect / Playwright 内 context / 浏览器内 eval)
    - HttpOnly cookies 自动带、referrer/origin 自动对、TLS 指纹与真实浏览器一致
    - 与 curl/wget 带提取 cookie 调用是两个完全不同的调用路径,反爬机制可能只拦后者
    - 真实案例:某平台的内容 API 从 curl 调用返回错误码、被判定"接口已失效";后验证同一 cookie 从浏览器内部调用,正常返回数百条数据。一个下午浪费在错误结论上。
  - 【生态信号】有没有专门为 AI agent 集成的工具已覆盖了这个平台?
    - 参考:浏览器自动化适配器、MCP servers 社区、Browserbase、Apify、官方 skills 生态
    - 他们已经解决过 = 不要重复造轮
  - 官方文档:[以上三检有发现后,针对具体入口读官方文档]
  - 社区/社交:[社区使用反馈、踩坑记录]

为什么是 Step 0: 如果跳过资源映射直接提假设,你会在错误的解空间里浪费时间--用笨办法绕过一个根本不存在的限制。

0.5 分层定位(多层系统必做)

如果系统有多个层次(如日报→周报、前端→后端→数据库),在提假设之前先定位问题在哪一层。 核心要点:

• 用一句话说清每一层干什么,画出层次图
• 逐层问:如果下层完美工作,这一层会不会独立出问题?
• 追因追到不可再分解为止,判断原因是必然的还是偶发的
• 在问题所在的层修,本层解法锁定本层边界,不依赖下层行为承诺

定位完层次后,在目标层内开始 HT。

1. HT: Hypothesis Test(假设验证)

假设在被验证之前,无论多笃定,都只是假设,应默认大概率不为真。 验证必须基于可观测事实,不基于推理或反思。

1.1 提出假设 & 赋先验

- 假设: [对问题根因/方案可行性的判断]
- 类型: 事后诊断 / 事前规划
- 先验: P(H) = [0.0-1.0],依据: [参考类别]

先验赋值参考(Reference Class Forecasting):

铁律:主观信心 ≠ 先验概率。 "我觉得肯定是"不构成贝叶斯更新。

1.1b 中立性检查

1. 暂停修复思维:HT 阶段禁止同时构思修复方案--这会污染验证的中立性
2. 预写证伪条件:写验证测试前,先写"看到什么则假设为假",与证实条件同等具体
3. 证伪 = 排除一条路:正确反应是"好,少了一个可能",然后换下一个假设

1.2 自我攻击

1. 攻击 Ground Truth:我的判断依据本身有没有破绽?有没有反例?
2. 检查其他可解释性:同一现象是否有完全不同的解释?(问题可能不是"怎么做 X"而是"需不需要 X")
3. 找反例:已有事实中,有没有直接反驳假设的证据?

三项检查不通过 → 假设不成立,重新提假设。

1.3 证据等级

V5 铁律:任何仅在思维层面的推理、反思、挑战,都不构成假设验证为真。假设依然为假设。

V2 证据链闭合三条件:

• 来源可追溯(不是"我记得大概是这样")
• 环环相连(A→B→C,不能跳 A→C)
• 排他性(排除了能解释同一现象的其他假设)

任一条不满足 → 降级为 V3。存在另一条同样闭合的证据链指向不同结论 → 两条都不算 V2。

1.4 验证路径(按假设类型分流)

事后诊断(问题已发生,确认根因):

• 刚性标准:必须达到 V2 或 V1
• 推荐路径:先 V2(找痕迹闭合证据链),再 V1(复现确认)
• V3 及以下:假设仍为假设,不能用于指导 DEV

- 信息收集: [查日志/文件/状态 - 寻找直接痕迹]
- 证据链:
  - 痕迹1: [在哪发现的,说明了什么]
  - 痕迹2: [...]
  - 推导: 痕迹1 → 痕迹2 → 结论
  - 排他性: [是否排除了替代解释?如何排除?]
- 复现测试(如条件允许):
  - 操作: [如何触发]
  - 预期: [如果假设为真应观测到什么]
  - 实际: [观测结果]
- 达到证据等级: V1 / V2 / V3

事前规划(事件尚未发生,确认机制可行性):

整体事件尚未发生,不可能直接 V1/V2。 核心方法:把机制拆成因果链,对每个环节单独验证。 事前的 V1 不是对最终结果的复现,而是对每个因果箭头的微型复现。

刚性标准(必须满足,否则假设不可用于决策):

1. 可证伪性:假设必须有明确的"如果看到X,则假设为假"。不可证伪的假设不是假设,是信仰
2. 预注册:成功/失败标准必须在执行前锁定,不允许事后调整标准适配结果(这是 AT Design 在 DEV 之前的底层理由)
3. 机制分解与逐环验证:拆成因果链 A→B→C→D,每个箭头必须满足以下之一:
   • 有直接类比证据(过去相同环节在相似条件下成立过)
   • 可通过 spike/原型直接测试(对该环节做微型 V1)
   • 有公认理论/文档支撑(物理定律级确定性)
   • 任何一环不满足 → 标记为"未验证环节" → 整体降级为"有条件假设"
4. 最高风险环节优先验证:先验最接近 0.5 的环节,信息增益最大,优先做 spike

建议标准(不强制,但显著提高假设质量):

5. 类比审判:搜索历史上类似方案的成败记录,提供 base rate 锚定
6. 事前尸检(Pre-mortem):假设方案已失败,反推最可能的失败原因,每个原因作为子假设独立 HT
7. 爆炸半径评估:假设为假时的损失决定验证力度

- 可证伪条件: [看到什么则假设为假]
- 预注册标准: [成功 = ?, 失败 = ?]
- 因果链分解:
  - 环节A → B: 验证方式=[类比/spike/理论], 结果=[✅/❌/未验证]
  - 环节B → C: 验证方式=[...], 结果=[...]
  - 环节C → D: 验证方式=[...], 结果=[...]
- 未验证环节: [列出]
- 最高风险环节: [哪个], spike 结果: [...]
- 爆炸半径: 可逆低成本 / 不可逆中成本 / 不可逆高成本
- 达到证据等级: 每环 V? → 整体 V?

1.5 判定

- 直接观测到了什么: [列出具体的观测事实,不含推理。写不出来 → V5]
- 证据等级: V[1-5]
- 后验估计: P(H|E) = [更新后的概率]
- 判定:
  - ✅ 验证通过(V1 或 V2)→ 进入 PT
  - ⚠️ 有条件通过(V3,存在未闭合环节)→ 标注风险,谨慎进入 PT
  - ❌ 验证未通过(V4/V5 或反证据)→ 替换假设,重跑 HT

关键规则:

• 不能提了假设就一直绕,必须先验证假设是否成立
• 假设不通过 → 必须替换假设,不能在错误假设上调方案
• V5(纯推理)永远不能作为通过依据

2. PT: Plan Test(方案验证)

提出方案,用测试用例验证可行性。

- 方案: [具体方案描述]
- 信息收集: [查文档/搜网/确认可行性 - 为写测试服务]
- 测试用例:
  - PT1: [方案前提是否成立] → 预期: [xxx] → 实际: [xxx] → ✅/❌
  - PT2: [关键参数是否可用] → 预期: [xxx] → 实际: [xxx] → ✅/❌
- 判定: ✅ 进入 AT Design / ❌ 调整方案 / ❌❌ 回退 HT

回退规则:

• PT 失败但假设没问题 → 调整方案,重跑 PT
• PT 失败且发现假设有问题 → 回退 HT,重新提假设

3. AT Design: Acceptance Test Design(验收用例编写)

在写代码之前,先定义"做完长什么样"。

- 验收标准:
  - AT1: [输入/操作] → 预期结果: [xxx]
  - AT2: [边界条件] → 预期结果: [xxx]
  - AT3: ...

关键规则:

• 必须在 DEV 之前完成
• 用例要具体可执行,不能是模糊描述

4. DEV: Development(开发)

基于 PT 方案 + AT 用例执行开发。

- 改动清单:
  - [文件1]: [改了什么]
  - [文件2]: [改了什么]

5. AT Run: Acceptance Test Run(验收测试执行)

执行 AT Design 中定义的用例。

- AT1: → 实际: [xxx] → ✅/❌
- AT2: → 实际: [xxx] → ✅/❌
- 判定: ✅ 进入 E2E / ❌ 回 DEV 修复

6. E2E: End-to-End Test(端到端验收)

由用户亲自验收。

- E1: [验收项] → ✅/❌
- E2: ...
- 判定: ✅ 完成 / ❌ 回退 DEV 或 PT

回退路径

HT ←────────────────────┐
 ↓ pass                  │
PT ←─────┐               │
 ↓ pass  │ PT fail       │ 根因在假设
AT Design│               │
 ↓       └→ 调整方案 ────┘
DEV
 ↓
AT Run ──→ fail → 回 DEV
 ↓ pass
E2E ────→ fail → 回 DEV 或 PT
 ↓ pass
Done ✅

6.1 收尾检查(E2E 通过后必做)

E2E 通过后,执行以下 checklist:

- [ ] 是否需要新建/更新项目文档?(按你的项目文档约定判断)
- [ ] 是否有新的经验教训需要记录?
- [ ] 相关的 memory/YYYY-MM-DD.md 是否已更新?

不满足任何一项可以跳过,但必须逐项过一遍再标记 Done。

何时使用

需要 HDD(满足任一):

• 涉及"为什么"(诊断/debug)
• 涉及"哪种方案更好"(优化/选型)
• 改动影响上下游(架构/配置变更)
• 结果不确定,需要验证

不需要 HDD:

• 指令明确、结果确定("把标题改成xxx")
• 纯信息查询("这个 API 怎么用")
• 简单追加/删除操作

信息收集指引

HT 和 PT 阶段都可能需要信息收集,作为写测试用例的输入:

• 查本地文件: read/exec 读配置、日志、源码
• 搜向量库/记忆: 查历史决策和上下文
• 搜网: 查文档、方案、已知问题

以上为能力描述,具体工具名(读写文件、记忆检索、联网搜索、跑命令)按你的 agent 环境替换。

• 跑命令: exec 验证环境、版本、状态

信息收集不是目的,写出可执行的测试用例才是。

异常模式识别(Anomaly Detection)

HT 阶段之前,还有一个更根本的能力:从数据中发现异常。很多 bug 不是用户报告的,而是在做别的事时偶然注意到的。

看整体模式,不只看单条数据

单条结果对不对很难判断,但整体分布的异常一眼就能看出:

• 不自然的一致性:一个分类器把所有输入都归为同一类 → 输入可能是错的(分类逻辑错会随机错,但全部一样说明看到的是同一种东西)
• 不该出现的空值/默认值:某个字段全是 null 或 default → 上游数据没传进来
• 计数不对:预期 8 种分类结果但只看到 1 种 → 系统性问题

实战案例: 原本在讨论"怎么给一个消息分类器新增分类",看 debug log 时发现所有消息(包括 "good"、"可以推进"、所有语音)全部被分为同一类。分类器不可能把所有消息都归同一类--除非它根本没看到实际内容。这个观察直接改变了问题方向:从"加什么分类"变成"为什么分类器输入是错的"。

保持对"正常"的校准

要发现异常,首先要知道什么是正常。在系统运行初期:

1. 主动检查几条典型输入的处理结果,建立基线认知
2. 对关键环节保留日志/统计,方便后续发现偏移
3. 定期抽查,不只是出了问题才看日志

调试技术(Debug Techniques)

HT/PT 阶段经常需要调试来验证假设。以下方法经过实战验证(以一个文本提取 bug 的排查过程为例)。

逐步打桩法(Step-by-Step Instrumentation)

当多步处理链输出不对时:

1. 在每步之间插入 debug log(记录该步的输入和输出)
2. 对比每步结果,定位第一个"输入对但输出错"的步骤
3. 问题就在那一步的逻辑里

// 示例:在 extractUserText 每步加 debug
dbg(`after step1: "${cleaned.slice(0, 120)}"`);
dbg(`after step2: "${cleaned.slice(0, 120)}"`);
// → 发现 step3 输入正确但输出没变 → 问题在 step3 的 regex

关键: 不要猜"可能是这步"然后直接改代码。打桩定位比猜测修复快得多,而且不会引入新问题。

模拟 vs 真实验证

• 本地模拟(node -e / 单元测试)可以快速验证逻辑
• 但模拟的输入格式可能与真实环境不同
• 模拟通过 ≠ 真实通过,必须在真实环境中再验证一次
• 真实与模拟结果不一致时 → 问题在输入格式假设上

实战教训: 本地模拟 extractUserText 时用了多行文本(手动加了换行),regex 匹配成功;但真实 event.prompt 是单行格式(没有换行),regex 中的 .*?\n 匹配失败。模拟给了"代码没问题"的假象。

格式假设检查

正则表达式和解析逻辑依赖对输入格式的假设(换行符、分隔符、字段顺序等)。当"逻辑对但不工作"时:

1. 用 JSON.stringify() 打出原始文本 → 暴露不可见字符、换行、编码
2. 用 .length 确认文本完整性 → 排除截断
3. 用 .startsWith() / .includes() 做简单断言 → 缩小范围
4. 特别注意:单行 vs 多行、\n vs \r\n、空格 vs tab

减少调试来回

真实环境测试往往需要重启服务 + 用户配合,周期长。为减少来回:

1. 每次重启前多加几个 debug 点,一次收集尽可能多的信息
2. 同时打印输入和输出,不要只打输出(看不出输入是否符合预期)
3. 打印长度和关键特征(startsWith、includes),不只是截断内容
4. 保留 debug log 到问题完全解决,过早清理可能需要重新加回来