ce-optimize

迭代式最佳化循环 (Iterative Optimization Loop)

执行以指标驱动的迭代式最佳化。定义目标、建立测量工具链，然后执行收敛至最佳解的平行实验。

初始设定 (Setup)

在每次触发调用的最开始执行一次（在分配任何子 Agent 之前），并遵循其印出的指令——除非指令与本 Skill 关于向使用者提问的规则发生冲突（无论这些规则适用于非交互模式还是所有模式），此时一律以本 Skill 的规则为准，不发起阻塞式提问。切勿在同一次调用中重复执行；后续调用本 Skill 或其它 Skill 时会自行运行其专属的脚本。若环境中无 Node 运行时，本 Skill 将按正常流程继续执行。

SKILL_DIR="<absolute path of the directory containing the SKILL.md you just read>";
NODE="$(for c in node nodejs; do command -v "$c" >/dev/null 2>&1 && "$c" -e '' >/dev/null 2>&1 && { echo "$c"; break; }; done)";
if [ -n "$NODE" ]; then
"$NODE" "$SKILL_DIR/scripts/context.mjs" || echo "context script failed; continue with the skill's normal behavior";
else
echo "no Node runtime; continue with the skill's normal behavior";
fi

交互方式 (Interaction Method)

请使用平台提供的阻塞式提问工具：Claude Code 中使用 AskUserQuestion（若未载入其 Schema，请先调用 ToolSearch 并设置 select:AskUserQuestion）、Codex 中使用 request_user_input、Antigravity CLI (agy) 中使用 ask_question、Pi 中使用 ask_user（需安装 pi-ask-user 扩展）。仅当运行框架中不存在阻塞式工具或工具调用报错时（例如 Codex 编辑模式），才退回到在聊天对话中提供编号选项——绝不能因为需要载入 Schema 就直接跳过。严禁静默跳过提问。

输入 (Input)

最佳化输入即触发本 Skill 时传入的输入——存在于当前的 Prompt 或对话中，无论是由使用者直接提供，或是由上层调用的 Skill 所传递：包含要最佳化的目标，或是最佳化规格 YAML 档案的路径。

若未提供最佳化输入，请主动询问：「您想要最佳化什么？请描述目标，或提供最佳化规格 YAML 档案的路径。」

Artifact 根目录 (Artifact Root)

本 Skill 会读取位于 <root>/solutions/ 下的学习经验。请在首次组合 <root>/ 路径时解析 <root>（参考下方规则），绝对不要提前解析。对 <root>/... 进行写入，或是读取 <root>/solutions/，都算作组合 <root>/ 路径，因此两者都会触发解析；只有完全不碰触任何 <root>/ 路径的执行（仅使用暂存档或无 Repo 流程）才会跳过；解析后的路径请传递给任何子 Agent，而非直接传递设定。

<!-- ce-docs-root:start -->
在组合任何 Artifact 路径之前，请先解析 CE Artifact 根目录 <root>。

• 读取：从 <repo-root>/.compound-engineering/config.local.yaml 读取 docs_root，若无则读取 config.yaml；以第一个非空值为准（<repo-root> = git rev-parse --show-toplevel）。若未设定 -> <root> 默认为 docs（与先前逻辑完全一致）。
• 验证：验证设定的值：必须是相对 Repo 的目录，且其符号连结解析后的实际路径须保留在 Repo 内部，既不能是 Repo 根目录，也不能位于 .git/ 下。若验证失败，请停止执行并报错提示 docs_root 及其设定值——绝不要退回到默认的 docs。
• 使用：将 <root> 作为唯一的 Artifact 保存位置：若不存在则建立，每个路径皆组合为 <root>/<subdir>（使用本 Skill 专属的子目录），且绝不重复读取 docs。
  <!-- ce-docs-root:end -->

最佳化规格 Schema (Optimization Spec Schema)

请参考以下规格 Schema 进行格式验证：

references/optimize-spec-schema.yaml

实验日志 Schema (Experiment Log Schema)

请参考以下实验日志 Schema 进行状态管理：

references/experiment-log-schema.yaml

快速上手 (Quick Start)

首次执行时，请优先针对「信号明确度与安全性」进行最佳化，而非追求最大吞吐量：

• 当指标属于客观且测量成本较低时，请从 references/example-hard-spec.yaml 开始
• 仅当实际品质需要语义层面的判定时，才使用 references/example-judge-spec.yaml
• 建议优先选择 execution.mode: serial 与 execution.max_concurrent: 1
• 首次执行请以 stopping.max_iterations: 4 与 stopping.max_hours: 1 限制执行上限
• 在基线与测量工具链尚未获得充分信任前，避免引入新的依赖套件
• 对于 Judge 模式，建议初始设定为 sample_size: 10、batch_size: 5 及 max_total_cost_usd: 5

有关本 Skill 的使用目的、何时使用硬性指标 (Hard Metrics) 对比 LLM-as-Judge，以及范例启动 Prompt，请参阅：

references/usage-guide.md

---

持久化规范 (Persistence Discipline)

重要：磁盘上的实验日志是唯一的真理来源 (Single Source of Truth)。对话上下文并非耐久储存空间。仅保存在对话中的结果必然会丢失。

位于 .context/compound-engineering/ce-optimize/<spec-name>/ 下的档案属于本地暂存状态。它们会被 git 忽略，因此能在同一台机器的本地恢复执行中保留，但除非使用者另行汇出，否则不会通过提交 (commit)、分支 (branch) 或推送到远程 (push) 来保存。

所有关键状态都必须写入磁盘，而不是保存在 Agent 的记忆体中。

如果您在对话中输出了结果表格，却未先将结果写入磁盘，这就是一个 Bug。 对话是提供给使用者看的，而磁盘上的实验日志文件才是为了实现耐久性。

核心规则

1. 测量完成后立即将每次实验结果写入磁盘 — 不是在批次结束后，也不是在评估结束后，而是「立即」。指标一旦确定，在评估下一个实验前，必须瞬间将实验条目附加写入实验日志档。这是防止崩溃丢失资料的 #1 规则。

2. 验证每一次关键写入 — 写入实验日志后，重新读取该文件并确认记录确实存在。这能捕获静默写入失败。在验证通过前，切勿进入下一个实验。

3. 在每个阶段转换前与决策前重新读取磁盘 — 切勿跨阶段转换、批次边界或在执行可能耗费大量时间的操作后信任记忆体中的状态。请一律从磁盘重新读取实验日志与策略摘要 (strategy digest)。

4. Phase 3 期间实验日志仅限追加 (Append-only) — 切勿覆写整个文件。只需追加新的实验记录。仅当发现新的最佳结果时，才原位更新 best 字段。这可防止写入中断导致资料丢失。

5. 用于崩溃恢复的单次实验结果标记 — 每次实验在测量完成后，需立即在其 Worktree 中写入 result.yaml 标记。恢复执行时，扫描这些标记即可挽回已测量但尚未记录至日志的实验。

6. 每批次结束后、生成新假设前写入策略摘要 — Agent 在决定下一步尝试什么时，读取的是策略摘要（而非自身的记忆）。

7. 绝不在将结果写入磁盘前将其呈现给使用者 — 规范流程为：测量 -> 写入磁盘 -> 验证 -> 然后展示给使用者。绝对不能颠倒。

强制性磁盘检查点 (Mandatory Disk Checkpoints)

这些属于不可妥协的「先写入后验证」步骤。在每个检查点，Agent 必须写入指定文件，然后重新读取以确认写入成功。

检查点	写入的文件	阶段
CP-0：规格已保存	spec.yaml	Phase 0，使用者批准后
CP-1：基线已记录	experiment-log.yaml（包含基线的初始状态）	Phase 1，基线测量完成后
CP-2：假设 Backlog 已保存	experiment-log.yaml（hypothesis_backlog 字段）	Phase 2，假设生成完成后
CP-3：单次实验结果	experiment-log.yaml（追加实验条目）	Phase 3.3，每次测量完成后立即执行
CP-4：批次摘要	experiment-log.yaml（结果 + 最佳值）与 strategy-digest.md	Phase 3.5，批次评估完成后
CP-5：最终总结	experiment-log.yaml（最终状态）	Phase 4，收尾时

验证步骤格式：

1. 使用原生文件写入工具写入文件
2. 使用原生文件读取工具重新读取文件
3. 确认预期内容完整存在
4. 若验证失败，请重试写入。若连续失败两次，请向使用者发出告警。

文件位置（全数位于 .context/compound-engineering/ce-optimize/<spec-name>/ 下）

文件	用途	写入时机
spec.yaml	最佳化规格（执行期间不可变）	Phase 0 (CP-0)
experiment-log.yaml	所有实验的完整历史纪录	于 CP-1 初始化，于 CP-3 追加，于 CP-4 更新
strategy-digest.md	供假设生成使用的浓缩经验总结	每次批次结束后的 CP-4 写入
<worktree>/result.yaml	单次实验崩溃恢复标记	测量完成后立即写入（先于 CP-3）

恢复执行时 (On Resume)

当 Phase 0.4 检测到已存在的执行记录时：

1. 从磁盘读取实验日志 — 此为唯一真理
2. 扫描 Worktree 目录中尚未列入日志的 result.yaml 标记
3. 挽回所有已测量但未记录的实验
4. 从日志记录的中断点继续执行

---

Phase 0: 初始化设定 (Setup)

0.1 确认输入类型

检查输入内容为：

• 规格文件路径（以 .yaml 或 .yml 结尾）：读取并验证该文件
• 最佳化目标描述：互动式地协助使用者建立规格档

0.2 载入或建立规格

若提供了规格文件：

1. 读取 YAML 规格文件。负责协调的 Agent 会原生解析 YAML — 无需透过 Shell 脚本解析。
2. 对照 references/optimize-spec-schema.yaml 中 validation_rules 节区的每一条规则进行验证（该节区是合规规格要求的唯一真理来源 — 切勿依赖凭印象记忆的子集；像单一 Rubric 与排他资源需求等条件规则仅定义于该处）。
3. 若有任何规则验证失败，请回报具体的失败项并要求使用者修正后再继续。

若提供了目标描述：

1. 分析项目以了解有哪些可被测量的指标

2. 侦测最佳化目标属于定性还是定量 — 这将决定采用 type: hard 还是 type: judge，也是规格制定中最关键的决策：

   使用 type: hard 的时机：

   • 指标为标量数字，且有明确的「越好」方向
   • 指标具备客观可测量性（如建置时间、测试通过率、延迟、记忆体使用量）
   • 无需人类判断即可评估「此结果是否真正优良」
   • 范例：降低建置时间、提升测试覆盖率、降低 API 延迟、缩减 Bundle 尺寸

   使用 type: judge 的时机：

   • 产出物品质需要语义层面的理解才能评估
   • 人类审查者必须查看结果才能判定「这是否更好」
   • 存在替代指标 (Proxy metrics)，但可能产生误导（例如「更多分群」并不代表「更好的分群」）
   • 最佳化可能会产生表面上看起来很好但实际退化的劣质解 (Degenerate solutions)
   • 范例：分群品质、搜寻相关性、摘要品质、程式码可读性、UX 文案、推荐相关性

   重要：若目标属于定性，强烈建议使用 type: judge。向使用者说明：单靠硬性指标可能会在没有检查实际品质的情况下最佳化出误导性的替代数字。向使用者展示三层评估法：

   • 退化闸门 (Degenerate gates)（硬性、低成本、快速）：拦截明显损坏的解 — 例如「所有项目都在 1 个分群中」或「0% 覆盖率」。优先执行。若闸门未通过，直接跳过高成本的 Judge 步骤。
   • LLM-as-judge（真正的最佳化目标）：对产出进行抽样，对照 Rubric 评分并汇总。这才是最佳化循环要最佳化的标的。
   • 诊断指标 (Diagnostics)（仅记录，不关卡）：分布统计、计数、耗时 — 有助于理解 Judge 评分变化的原因。

   若使用者坚持对定性目标使用 type: hard，可继续执行，但需警告结果可能会最佳化出一个具误导性的替代指标。

3. 设计抽样策略（针对 type: judge）：

   引导使用者定义分层抽样 (Stratified sampling)。核心问题是：...