experiment-design

experiment-design

帮助用户制定切实可行、可直接启动的实验规范。引导他们完成假设、变体、指标和样本量合理性检查。此技能不会写入 GrowthBook，而是产出一份可直接启动的规范，供 experiment-launch 使用。

所有 API 调用都通过随附的辅助程序完成：${CLAUDE_PLUGIN_ROOT}/scripts/gb-call。它需要 GB_API_KEY——在 shell 中设置，或由 /growthbook:gb-setup 写入 ~/.config/growthbook/.env。如果未设置或无效，gb-call 的错误消息会指引用户返回 /growthbook:gb-setup。

工作流

1. 明确假设。 使用可证伪的“如果／那么／因为”格式：

   如果我们更改 X，那么 Y 会改善，因为 Z。

   如果假设含糊不清，就要求用户具体说明。“我们觉得用户会喜欢”没有指出具体指标——参与度可能代表五种不同的东西。“如果我们把 CTA 移到首屏上方，那么点击率会提高，因为用户会在滚动之前决定是否参与”则给出了明确的预测目标。

2. 定义变体。 默认设为两个：对照组（当前状态）和实验组（所做的更改）。可以设置三个或更多变体，但会降低统计功效；询问用户是否确实需要第三个变体。变体编号从 0（对照组）到 N。

3. 选择目标指标（最好一个，最多两个）。 列出可用模板和指标：

   gb-call GET /api/v1/api/v1/experiment-templates
   gb-call GET /api/v1/metrics
   gb-call GET /api/v1/fact-metrics
   

   如果存在适用的模板，帮助用户选择模板；否则，根据假设预测会发生变化的指标，帮助用户进行选择。指出指标类型（比例、均值、比率、分位数）——这会影响样本量计算。如果目标指标达到三个或更多，就建议用户重新考虑，并将其余指标降为次要指标或护栏指标：GrowthBook 的决策框架设计上允许多个目标指标，但每增加一个目标指标都会降低统计功效，并让上线／停止决策变得复杂。

4. 选择护栏指标（1–3 个）。 这些指标不应出现退化。常见示例：注册率、页面错误率、延迟。如果用户跳过护栏指标，请提出异议；实验通常至少应设置 1 或 2 个护栏指标。护栏指标按设计不参与多重比较校正，因此不要设置过多。

5. 估算样本量。 需要用户提供三个输入：

   • 主要指标的基准率（或均值）
   • 用户关心的最小可检测效应（MDE），以相对值表示（“转化率提升 2%”）。
   • 受影响界面的日流量。

   先用粗略估算进行直觉检查，再引导用户使用 GrowthBook 应用内的 Power Calculator 获取准确数字。GrowthBook 文档中的常见经验法则是：对于比例指标，每个变体至少有 200 次转化；公式 n ≈ 16 × p × (1 - p) / (p × MDE)^2 按 80% 统计功效计算出的每个变体样本量也大致相同。无论使用哪种方法，都不要引用精确到三位有效数字的结果——这些都只是估算值。向上取整，并列出所用的输入值。

   计算预计实验时长：2 × n / daily_traffic。对时长过长或过短的情况都要提示：

   • > 4 周——实际应用中可能统计功效不足；可以考虑增大 MDE、改用更灵敏的指标，或选择流量更高的界面。
   • < 1 周——结果可能受到星期和周末效应的影响。建议至少覆盖一个完整的周周期。

6. 确定项目和数据源。 如果用户提到了具体项目，获取其 ID：

   gb-call GET /api/v1/projects
   

   列出数据源供用户参考（启动步骤会选择一个，但值得让用户了解有哪些可用选项）：

   gb-call GET /api/v1/data-sources
   

7. 生成规范。 输出结构化内容，供用户审阅并交给 experiment-launch 使用：

   ## Experiment spec — <short name>
   
   **Hypothesis:** If <change>, then <outcome>, because <mechanism>.
   
   **Variations:**
   - 0: Control — <description>
   - 1: Treatment — <description>
   
   **Primary metric:** <name> (<type>) — baseline <value>
   **Guardrails:** <metric a>, <metric b>
   **MDE:** <X%>
   **Estimated sample size:** <N> per variation
   **Estimated duration:** <D> days at <T> visitors/day on the affected surface
   **Project:** <project id>
   **Tracking key suggestion:** <kebab-case-name>
   

   移交给 experiment-launch 前，先请用户确认。

约束

• 最好只有一个目标指标，最多两个。 GrowthBook 的决策框架将目标指标设计为复数，功效计算器也支持最多五个，但每增加一个目标指标都会降低统计功效，并让上线/终止决策更复杂。目标指标达到三个或以上时应提出异议；其余指标降为次要指标。
• 至少设置一个护栏指标。 如果用户跳过护栏指标，应提出异议。多重比较校正不适用于护栏指标（这是刻意设计的——护栏信号的作用就是阻止上线），所以也不要堆叠过多护栏指标；1–3 个最合适。
• 假设应可证伪，并采用“如果／那么／因为”的格式。 要推动用户给出具体到足以据此解读结果的预测。“用户会更积极参与”并未说明具体是哪项指标。
• 样本量计算仅为近似值。 将其用作粗略检查；实际数值应引导用户使用应用内的功效计算器。向上取整，并说明所用输入，以便用户核对。
• 留意激活指标偏差。 变体差异下游的激活指标会在不触发 SRM 的情况下悄然造成结果偏差。如果用户选择此类指标，应明确指出风险。
• 建议首次开展实验的用户进行 A/A 测试。 如果组织没有已停止的实验（通过 flag-discovery 或 experiment-brainstorm 检查），GrowthBook 建议先进行 A/A 测试，在运行正式实验前验证实现。
• 星期几效应很重要。 如果实验时长不足一整周，应提出异议。周末的流量和行为与工作日不同。
• 不要通过此技能启动实验。 最终规格 → 用户确认 → 移交给 experiment-launch。不要让范围蔓延。
• 跟踪键命名一旦确定便无法更改。 建议使用根据实验名称生成的 kebab-case 格式。启动步骤会将其用作 trackingKey；它会写入事件数据，之后无法轻易更改。

使用的端点

• GET /api/v1/metrics 和 GET /api/v1/fact-metrics — 列出候选主要指标和护栏指标
• GET /api/v1/metrics/<id> — 获取基线值，用于估算样本量
• GET /api/v1/projects — 将项目名称解析为 ID
• GET /api/v1/data-sources — 列出可用数据源（启动时使用）

移交

• experiment-launch — 接收规格，并在 GrowthBook 中创建实验草稿。
• 手动创建指标 — 如果主要指标尚不存在，用户需要先在 GrowthBook UI 的 <host>/metrics（事实指标则为 <host>/fact-tables）中创建指标，然后才能启动。目前还没有对应的技能；通过将 GB_API_URL 中的 api. 替换为 app. 来推导 <host>。
• experiment-brainstorm — 如果用户没有明确的假设，可将其引导回此处，基于过往结果形成新想法。