Optimize 指南

入口：spec-optimize · spec-optimize · 契约见 spec-optimize

spec-optimize 用于有明确指标的迭代优化。它不是普通实现入口，也不是“让 AI 多试几种方案”的自由循环。它要求先定义 measurement、预算、可修改范围和停止条件，再运行实验。

适用场景

场景	是否适合
降低构建时间、提升搜索相关性、改进聚类质量、优化 prompt judge 分数	适合
只是实现一个已经确定的功能	不适合，使用 spec-work
测试失败或线上 bug	不适合，使用 spec-debug
“感觉还可以更好”但没有指标、样本或验证命令	不适合，先回到 spec-plan 定义 measurement

输入

可以传入一个 optimization spec YAML，也可以用自然语言描述目标，让 workflow 协助你把目标转成安全 spec。

spec-optimize docs/optimization/search-relevance.yaml
spec-optimize "reduce Vite docs build time with a 1 hour budget"

一个可执行 spec 至少应包含：

字段	作用
metric.primary	主指标、方向和 hard / judge 类型
measurement.command	可重复运行的测量命令
scope.mutable / scope.immutable	哪些文件可改、哪些不能改
stopping.max_iterations / max_hours	实验预算
execution.mode / max_concurrent	串行或并行实验方式
degenerate gates	先过滤明显坏方案，避免 judge 或长测试浪费预算

执行逻辑图

用户运行 spec-optimize
  |
  v
读取 optimization spec 或目标描述
  |
  v
确认 metric、scope、measurement、budget 和 execution mode
  |
  +-- 缺少可重复 measurement
  |     |
  |     v
  |   停止并帮助补 spec，不启动实验
  |
  +-- spec 可执行
        |
        v
      记录 baseline 到 .spec-first/workflows/spec-optimize/<name>/
        |
        v
      运行受限实验，每个结果立即写盘并验证
        |
        v
      根据 hard gates / judge score 保留胜出方案
        |
        v
      汇总指标变化、失败实验、最终 diff 和后续建议

产物边界

运行状态写在本机 scratch 目录：

.spec-first/workflows/spec-optimize/<spec-name>/

常见文件：

文件	作用
spec.yaml	本次优化运行的批准 spec
experiment-log.yaml	baseline、实验结果、最佳方案和最终状态
strategy-digest.md	每轮实验后的压缩学习，用于下一批假设
<worktree>/result.yaml	单个实验的 crash recovery marker

这些文件默认不提交。真正需要提交的是最终通过验证的源码 diff、测试或 benchmark 变更，以及必要的文档说明。

使用边界

• 首轮默认保守：串行执行、少量迭代、有限时间预算。
• judge 模式必须设置有限成本或由用户明确批准。
• 实验结果必须先写入 experiment-log.yaml，再展示给用户。
• 并行 worktree 只用于实验隔离；最终集成仍由 orchestrator 选择和验证。
• 目标变成产品范围问题时，停止优化并回到 brainstorm / plan。

阅读下一步

• 指标还没定义：Plan 指南
• 需要执行确定方案：Work 指南
• 优化后准备合并：Review 指南