ce-optimize

运行指标驱动的迭代优化循环——定义可衡量的目标，构建测量脚手架，运行尝试多种方法的并行实验，不断改进，向最佳方向收敛。

ce-optimize 是测量驱动的实验技能。它适用于正确改变不明显的问题，您可以生成几个看似合理的变体，您有一个可重复的测量工具，并且“更好”可以表示为硬指标或法学硕士作为法官的评估。该技能定义目标、构建测量循环、在并行工作树（或通过 Codex）中运行实验、保持胜利、恢复损失，并将每个结果保存到磁盘，以便数小时的运行能够在上下文压缩和崩溃中幸存下来。

受到 Karpathy 的自动研究的启发，针对多文件代码更改和非 ML 领域进行了推广。实际用途包括聚类质量、搜索相关性、构建性能、提示质量、延迟调整，以及优化目标从系统实验而不是猜测和检查中受益的任何地方。

TL;DR

＃＃ 问题

对于优化型问题，常见的故障模式：

• 猜测并检查 — 尝试一项更改、测量、调整；从未见过更广阔的设计空间
• 优化代理，而不是目标 - 改进实际上与质量无关的硬指标（集群计数、响应长度）
• 丢失结果 — 几个小时的运行崩溃、上下文压缩、结果仅存在于聊天中并且消失了
• 症状超过根本原因 - 修复改进了指标，但不能概括，因为它调整了不稳定的代理
• 简并解决方案 — “100% 准确度”，因为算法将所有内容分组到一个桶中
• 当并行可以工作时按顺序 - 当工作树隔离可以并行测试五个时，一次运行一个实验

解决方案

ce-optimize 将实验作为具有显式门的结构化循环运行：

• 规范驱动 — YAML 规范定义了指标、门、范围、测量命令和停止标准（或者该技能可以帮助您交互式地编写一个标准）
• 三层评估 - 退化门（廉价，困难）→ LLM 作为法官（当质量需要语义理解时）→ 诊断（记录，非门控）
• 持久性纪律 — 磁盘上的实验日志是事实的来源；在下一个实验开始之前，每个结果都会被写入并验证
• 工作树隔离的并行实验 - 独立变体在自己的工作树中同时运行，每个变体都在自己的分支上
• 文件不相交的亚军精选 - 涉及不同文件的多个获奖实验被组合并重新测量，以找到复合改进
• 策略摘要 — 将每批的压缩学习内容输入到下一批的假设生成中
• 崩溃恢复 - 工作树中的每个实验 result.yaml 标记可在任何类型的中断后恢复

是什么让它如此新颖

1. 三层评估——退化门、判断、诊断

ce-optimize 不是单一指标，而是分三层评估每个实验：

• 退化门（硬、便宜、快）——在支付昂贵的评估费用之前捕获明显损坏的解决方案。示例：“1 个集群中的所有项目”、“0% 测试通过率”。先跑；如果任何一个门出现故障，请跳过其余的门。
• LLM-as-judge（定性工作的实际优化目标）- 样本输出，根据评分标准对其进行评分，汇总。这就是当“更好”需要语义理解时循环优化的内容。
• 诊断（记录，非门控）——分布统计、计数、时间、成本。对于理解“为什么”判断分数发生变化而不污染优化信号很有用。

三层方法可以防止最常见的故障：优化不跟踪真实质量的代理。

2. 法学硕士作为定性输出的评判

对于聚类、搜索相关性或提示质量等硬指标误导的问题，该技能使用分层抽样和标题来评估输出：

• 分层抽样 - 对输出空间进行分桶（例如，“按大小排序”、“中范围”、“小集群”、“单例”），在所有桶中进行采样，以便法官看到具有代表性的质量
• 评分标准驱动的评分 — 1-5 级，带有具体的级别描述；用于诊断值的补充字段（distinct_topics、outlier_count）
• 单例评估 - 当覆盖范围很重要时，单独对单例进行采样以捕获误报（应该分组的项目）
• 成本上限 — max_total_cost_usd 限制法官总支出；无上限支出需要明确的用户批准

3.持久性纪律——磁盘是真理的来源

多小时运行不能信任内存中的状态。该技能强制实施六个强制性磁盘检查点（CP-0 到 CP-5）：保存规范、记录基线、写入假设待办事项、测量后立即附加每个实验结果、带有策略摘要的批次摘要、最终状态。每次写入后，都会读回文件进行验证——静默写入失败会被捕获，而不是传播。

如果您生成结果表而不首先将这些结果写入磁盘，则会出现错误。 对话上下文适用于用户；实验日志文件是为了持久性。

4.工作树隔离中的并行实验

对于独立假设，该技能会在其自己的分支上创建每个实验工作树。每个子代理都是独立工作的；合并按依赖顺序连续发生；当协调器显式处理合并冲突时，预测的重叠会出现。没有共享目录 git 索引争用，并发实验之间没有测试干扰。

当工作树隔离不可用（某些平台）时，执行会回退到串行子代理 - 正确性相同，并行性较低。

5. 文件不相交亚军精选

一批完成后，技能会根据改进程度对实验进行排名。最好的保留在优化分支上。然后，通过保留的实验检查亚军的文件级不相交 - 如果亚军触及完全不同的文件，则会将其挑选到新的基线上并重新测量。如果综合测量结果确实更好，则保留；否则将恢复为“单独有前途但组合中立/有害”日志条目。每批次最多可配置上限。

6. 策略摘要——压缩学习驱动假设生成

每批之后，策略摘要都会写入磁盘：尝试的类别以及成功/失败计数、关键学习、探索前沿（未尝试的类别）、当前最佳指标。下一批的假设生成会读取摘要（而不是代理的记忆）——保持循环由积累的证据而不是新近度偏差引导。

7. 崩溃恢复和继续

每个实验都会在测量后、协调器更新主日志之前立即在其工作树中写入 result.yaml 标记。在恢复时（阶段 0.4），该技能会扫描工作树以查找尚未记录在日志中的标记，并恢复任何已测量但未记录的实验。优化分支继续存在；磁盘上的实验日志仍然存在；您可以从上次停下的地方继续。

8. 第二阶段之前的硬门

第 1 阶段是一个硬门 - 该技能建立基线指标，验证测量工具，运行并行性就绪性探测，检查工作树预算，并在任何实验调度之前显示判断成本估算（或标记无上限支出）以获得明确批准。没有意外的成本或失控的循环。

简单示例

您希望提高通知分类功能的聚类质量。当前的方法将所有内容分为 12 个集群；有些看起来很弱。

您调用 /ce-optimize "clustering quality on notification categorization"。该技能检测到这是定性的 - 建议 type: judge 因为集群计数等硬指标会优化误导性代理。引导您定义分层采样（按大小、中范围、小集群以及单例）、标题（1-5 以及具体级别描述）和门（solo_pct <= 0.95、max_cluster_size <= 500）。建议首次运行使用串行模式和 4 次迭代上限。

第 1 阶段在基线上运行测量工具，为先前的优化上下文调度 ce-learnings-researcher，运行并行性探测，并在给出判断成本估计的情况下请求明确批准。你批准。

第 2 阶段生成 18 个假设（信号提取、嵌入、算法、参数调整类别）。一个人需要一种新的依赖；您批量批准。

第三阶段分批进行。每个实验都有自己的工作树，应用更改，运行测量工具，首先评估简并门（便宜），对分层样本运行判断（当门通过时），立即将结果写入磁盘，然后进行评估。每批次最好的合并到优化分支；文件不相交的亚军是经过精心挑选和重新测量的。

经过4次迭代，判断分数提高了1.2分，三个实验合并到保留分支中。第 4 阶段显示完成后选项：代码审查、通过 /ce-compound 捕获制胜策略，或创建 PR。

何时去实现它

在以下情况下使用 ce-optimize：

• 正确的改变并不是显而易见的
• 您可以生成几个看似合理的变体
• 您有一个可重复的测量工具（或者可以构建一个）
• “更好”可以表示为硬指标或法学硕士作为法官的评估
• 优化目标存在代理游戏风险（定性输出、退化解决方案）

在以下情况下跳过 ce-optimize：

• 你已经知道正确的改变——就去做吧
• 这一改变是一次性的，无法进行测量
• “更好”无法一致地衡量或判断——优化需要一个信号

用作工作流程的一部分

ce-optimize 是它自己的循环，但它与链互锁：

• 由头脑风暴或计划触发 - 当工作是“让 X 变得更好”而不是“构建 X 新”时，头脑风暴或计划通常会将优化呈现为正确的形状
• 在阶段 0.3 期间调用 ce-learnings-researcher 咨询 docs/solutions/ 以获得类似主题的先前优化工作
• 在第 4.3 阶段移交给 /ce-code-review — 在合并之前审查累积差异（基线到最终）
• 移交给 /ce-compound 将获胜策略记录为机构学习

分支 (optimize/<spec-name>) 和实验日志将在第 4 阶段保留 — 您可以稍后恢复、审核或扩展优化。

使用独立版

ce-optimize 通常是独立的 - 长时间运行的优化是它自己的活动：

• 来自规范 — /ce-optimize path/to/spec.yaml （使用 references/example-hard-spec.yaml 或 references/example-judge-spec.yaml 作为起点）
• 根据描述 — /ce-optimize "reduce build time by 30%" 引导您以交互方式编写规范
• 恢复现有运行 — /ce-optimize <spec-name> 检测现有分支并提供恢复与全新启动

有关该技能的用途、何时使用硬指标与 LLM 作为法官的友好概述以及启动提示示例，请参阅 references/usage-guide.md。

＃＃ 参考

规范架构：references/optimize-spec-schema.yaml。实验日志架构：references/experiment-log-schema.yaml。规范示例：references/example-hard-spec.yaml（硬指标）、references/example-judge-spec.yaml（法学硕士作为法官）。

对于首次运行，建议起始点：execution.mode: serial、max_concurrent: 1、max_iterations: 4、max_hours: 1。对于判断模式：sample_size: 10、batch_size: 5、max_total_cost_usd: 5。一旦测量安全带可信，就将其拧紧。

＃＃ 常问问题

我什么时候应该使用硬指标而不是LLM作为法官？ 客观目标的硬指标，其中越高/越低显然更好（构建时间、测试通过率、延迟）。法学硕士作为定性目标的判断，其中人类审阅者需要查看输出以说“这更好”（聚类质量、搜索相关性、提示质量）。当对定性工作有疑问时，请使用判断——仅硬指标就可以优化误导性代理。

为什么有六个磁盘检查点？ 因为该技能需要运行数小时，并且上下文随时可能丢失。每个检查点都会写入文件并将其读回以进行验证 - 静默写入失败不会传播。最重要的是 CP-3（每个实验结果在测量后立即附加，然后再评估下一个）。

什么是退化门？ 一种廉价、严格、快速的检查，可以发现明显损坏的解决方案。 “1 个集群中的所有项目”是集群的退化门 - 它在某些硬指标上得分完美，但显然是错误的。盖茨先行；如果有任何失败，则实验将被拒绝，而无需支付昂贵的法官评估费用。

如果我的优化需要新的依赖项怎么办？ 假设生成阶段收集所有独特的新依赖项，并在循环开始之前请求批量批准。未经批准的部门的假设将被跳过并在总结时重新提出。

它可以在 Codex 而不是子代理上运行吗？ 是的 — execution.backend: codex 通过 codex exec 将每个实验分派到 Codex 沙箱。如果 Codex 沙箱在当前上下文中不可用（已在 Codex 沙箱内，没有对 .git 的写入权限），则回退到子代理分派。

运行后会保留什么？ 保留所有保留实验提交的优化分支 (optimize/<spec-name>)。实验日志和策略摘要保留在 .context/compound-engineering/ce-optimize/<spec-name>/ 中，用于本地恢复和审核（.context/ 被 gitignored，因此它们不会随分支一起传输）。

另请参阅

• ce-code-review — 用于审查累积差异的阶段 4.3 移交
• ce-compound — 将制胜策略视为机构学习
• ce-worktree — 如果您想在优化循环之外设置隔离，则手动创建工作树