spec-optimize ​

围绕可度量目标建立 measurement scaffold，并运行多轮实验优化。

ASCII 链路图 ​

text
Codebase -> Spec -> Plan -> Tasks -> Code -> Review -> Knowledge
  |
  v
  spec-optimize
  entry: spec-optimize
  type: workflow command

基本信息 ​

字段内容
Skillspec-optimize
类型workflow command
研发链路位置Code
当前入口spec-optimize
兼容别名/spec:optimize、$spec-optimize
Sourceskills/spec-optimize/SKILL.md
Governancesrc/cli/contracts/dual-host-governance/skills-governance.json（supported-host skills governance）

描述 ​

Run metric-driven iterative optimization loops. Define a measurable goal, build measurement scaffolding, then run parallel experiments that try many approaches, measure each against hard gates and/or LLM-as-judge quality scores, keep improvements, and converge toward the best solution. Use when optimizing clustering quality, search relevance, build performance, prompt quality, or any measurable outcome that benefits from systematic experimentation. Inspired by Karpathy's autoresearch, generalized for multi-file code changes and non-ML domains.

Source 契约摘要 ​

When To Use ​

Use when a measurable outcome can improve through iterative experiments, hard gates, and/or LLM-as-judge scoring.

When Not To Use ​

Do not use for ordinary implementation, vague improvement requests without a metric, debugging without a feedback loop, or unbounded spend/concurrency.

Inputs ​

An optimization spec or goal, mutable/immutable scope, measurement command or scaffold plan, budget limits, experiment settings, repository instructions, and baseline evidence.

Outputs ​

A measurement scaffold and experiment log, scored experiment results, kept/rejected variants, final integrated changes when appropriate, and post-run recommendations.

Artifacts ​

Run state under .spec-first/workflows/spec-optimize/<spec-name>/, experiment worktrees/results, strategy digests, and no hidden workflow state outside the documented log.

Failure Modes ​

Missing metric, missing measurement command, unsafe scope, excessive or uncapped budget, failed baseline, write verification failure, or unavailable dispatch/worktree backend.

Workflow ​

Validate the spec and budget, establish the baseline, run bounded experiments, measure and write results immediately, select winners, integrate only verified improvements, and summarize evidence.

Downstream Consumers ​

Code review、benchmark maintainer、在性能/相关性变更时参与的 release reviewer，以及检查 experiment logs 的人工审查者。

何时使用 ​

  • 目标能被指标、hard gates 或 judge 标准衡量。
  • 需要比较多个实现或 prompt / search / performance 方案。

工作步骤 ​

  • 读取 plan、task pack、bug report 或明确实现目标。
  • 建立小步任务列表，按现有代码模式做最小必要修改。
  • 运行聚焦验证、测试、构建、浏览器或平台检查。
  • 把 diff、验证结果和剩余风险交给 review 或 knowledge 阶段。

输出 ​

  • 实现 diff、测试结果、构建输出、浏览器截图或运行证据。
  • 必要时输出 blocked 原因，而不是扩大 scope。

Agent / Persona 列表 ​

  • 小任务通常 inline；大任务可按文件边界使用 serial 或 parallel workers。
  • 调试、优化、UI、平台专项可引入对应 specialist agents，但 orchestrator 负责最终集成。

本 skill 在 source 中挂载了 2 个 skill-local 专家资产（agent 2 · persona 0），路径为 skills/spec-optimize/references/{agents,personas}/。跨 skill 复用时，详情页按文件名去重。

名称类型摘要
spec-learnings-researcheragentYou are a domain-agnostic institutional knowledge researcher.
spec-repo-research-analystagentYou are an expert repository research analyst specializing in understanding codebases, documentation structures, and project conventions.

agent 详情页入口仍在 /reference/agents/*；完整按 skill 归属索引见 Agents 参考。persona 目前以 skill-local prompt 形式挂在所属 skill 下，不单独生成全局详情页。

边界 ​

  • 没有可度量目标时不适合。
  • 失败实验必须记录，不能只保留成功叙事。

源码校准 ​

  • 本页由 website/scripts/generate-skill-detail-pages.js 从上游 source skill 生成。
  • 当前入口、兼容别名与宿主投递 metadata 来自 src/cli/contracts/dual-host-governance/skills-governance.json。
  • 当 source skill 或 governance contract 变化后，应重新运行 npm run reference:pages 并执行 npm run content:audit。