ln-814-optimization-executor

パス: ファイルパス（references/、../ln-*）は、このスキルディレクトリからの相対パスです。

ln-814-optimization-executor

タイプ: L3 ワーカー カテゴリ: 8XX 最適化

keep/discard の自動リサーチループを使用して、リサーチャーからの最適化仮説を実行します。複数ファイルの変更、複合ベースライン、あらゆる最適化タイプ（アルゴリズム、アーキテクチャ、クエリ、キャッシュ、バッチ処理）をサポートします。

---

概要

項目	詳細
入力	.hex-skills/optimization/{slug}/context.md または会話コンテキスト（スタンドアロン実行）
出力	分離ブランチ上の最適化されたコード、仮説ごとの結果、実験ログ
パターン	Strike-first: すべて適用 → テスト → 計測。失敗時のみバイセクト。競合する代替案にのみ A/B を実施

---

ワークフロー

フェーズ: 事前チェック → ベースライン → Strike-First 実行 → レポート → ギャップ分析

---

フェーズ 0: 事前チェック

Slug の解決

• slug を含む contextStore を伴ってエージェント経由で呼び出された場合 — それをそのまま使用します。
• スタンドアロンで呼び出された場合 — context_file パスから slug を導出するか、ユーザーに尋ねます。

ステップ 1: コンテキストの読み込み

プロジェクトルートから .hex-skills/optimization/{slug}/context.md を読み込みます。問題記述、プロファイリング結果、リサーチ仮説、対象メトリクスが含まれています。

ファイルが見つからない場合: 会話コンテキストから同じデータを確認します（スタンドアロン実行）。

ステップ 2: 事前検証

チェック	必須	欠落時のアクション
仮説が提供されている（H1..H7）	はい	ブロック — 実行するものがありません
テストインフラ	はい	ブロック（ci_tool_detection.md を参照）
Git がクリーンな状態	はい	ブロック（revert のためにクリーンなベースラインが必要）
Worktree 分離	はい	git_worktree_fallback.md に従って作成
E2E 安全テスト	いいえ（推奨）	コンテキストから読み込み、null の場合は WARN — フォールバックゲートとして全テストスイート

必読: references/git_worktree_fallback.md を読み込みます — optimization 行を使用します。 必読: references/ci_tool_detection.md を読み込みます — Test Frameworks + Benchmarks セクションを使用します。

ツールポリシー: ホストの AGENTS.md の MCP 設定に従います。references/mcp_tool_preferences.md と references/mcp_integration_patterns.md は、ホストポリシーが存在しない場合、または MCP の挙動が不明確な場合にのみ読み込みます。

このワーカーでのコード/設定/スクリプトの編集には、hex-line を主要な手段として使用します。プロファイラーとベンチマークが引き続き信頼できる情報源であり、ここでは hex-graph を実行時の証拠として扱わないでください。

E2E 安全テスト

コンテキストファイルから e2e_test_command を読み込みます（テスト検出フェーズでプロファイラーによって検出されます）。

ソース	アクション
コンテキストに e2e_test_command がある	フェーズ 2 の機能的安全ゲートとして使用
コンテキストの e2e_test_command = null	WARN: フォールバックゲートとして全テストスイート
スタンドアロン（コンテキストなし）	ユーザーがテストコマンドを提供する必要があります。欠落している場合はブロック

---

フェーズ 1: ベースラインの確立

パフォーマンスマップのベースラインを再利用します（すでに実メトリクスで計測済み）。

コンテキストファイルから

.hex-skills/optimization/{slug}/context.md から performance_map.baseline と performance_map.test_command を読み込みます。

フィールド	ソース
test_command	検出/作成されたテストコマンド
baseline	マルチメトリクススナップショット: ウォールタイム、CPU、メモリ、I/O

検証実行

test_command を一度実行して、ベースラインが依然として有効であることを確認します（プロファイリング以降コードは変更されていません）:

ステップ	アクション
1	test_command を実行
2	結果が baseline.wall_time_ms の 10% 以内の場合 → ベースラインを確認
3	結果が 10% を超えて乖離した場合 → 新しいベースラインとして再計測（3 回実行、中央値）
4	テストが失敗した場合 → ブロック: 「未変更のコードでテストが失敗します」

---

フェーズ 2: Strike-First 実行

必読: 実装中のパターン参照のために optimization_categories.md を読み込みます。

最大限の変更を一度に適用します。アプローチについて情報源が真に一致しない場合にのみ、A/B テストにフォールバックします。

ステップ 1：仮説のトリアージ

研究者の仮説を 2 つのグループに分けます。

グループ	条件	対応
異論なし	最善のアプローチが明確で、競合する代替案がない	ストライクでそのまま適用する
意見が分かれる	複数のアプローチがある（例：ソース A ではキャッシュ、ソース B ではバッチと記載）または別の仮説と conflicts_with の関係にある	完全な実装に加えて、代替案ごとに A/B テストを行う

大半の仮説は異論がないはずです。研究者はすでにエビデンスに基づいて順位付けしています。

ステップ 2：ストライク（異論のない仮説をすべて適用）

1. APPLY all uncontested hypotheses at once (all file edits)
2. VERIFY: Run full test suite
   IF tests FAIL:
     - IF fixable (typo, missing import) → fix & re-run ONCE
     - IF fundamental → BISECT (see Step 4)
3. E2E GATE (if e2e_test_command not null):
   IF FAIL → BISECT
4. MEASURE: 5 runs, median
5. COMPARE: improvement vs baseline
   IF improvement meets target → DONE. Commit all:
     git add {all_files}
     git commit -m "perf: apply optimizations H1,H2,H3,... (+{improvement}%)"
   IF no improvement → BISECT

ステップ 3：意見が分かれる代替案（ストライクに加えて A/B テスト）

意見が分かれる各ペア／グループについて、異論のない変更をすべて適用した状態で実施します。

FOR each contested hypothesis group:
  1. Apply alternative A → test → measure (5 runs, median)
  2. Revert alternative A, apply alternative B → test → measure
  3. KEEP the winner. Commit.
  4. Winner becomes part of the baseline for next contested group.

ステップ 4：二分探索（ストライクが失敗した場合のみ）

ストライクでテストに失敗する、または改善が見られない場合：

1. Revert all changes: git checkout -- . && git clean -fd
2. Binary search: apply first half of hypotheses → test
   - IF passes → problem in second half
   - IF fails → problem in first half
3. Narrow down to the breaking hypothesis
4. Remove it from strike, re-apply remaining → test → measure
5. Log removed hypothesis with reason

スコープのルール

ルール	説明
ファイルのスコープ	複数ファイルを変更できます（単一関数に限定されません）
シグネチャの変更	テストに合格する場合は可能です
新規ファイル	作成できます（キャッシュラッパー、バッチアダプター、ユーティリティなど）
新しい依存関係	プロジェクトのエコシステムですでに利用可能な場合は追加できます（設定済みの Redis の使用など）
所要時間	合計 45 分

元に戻す手順

スコープ	コマンド
すべて元に戻す	git checkout -- . && git clean -fd（worktree 内では安全です）
単一の仮説	git checkout -- {files}（二分探索中のみ）

安全ルール

ルール	説明
トレーサビリティ	コミットメッセージに、適用したすべての仮説 ID を記載します
分離	すべての作業を分離された worktree で行います。メインの worktree は変更しないでください
失敗時のみ二分探索	ストライクが失敗した場合、または代替案が実際に競合する場合を除き、仮説を個別にテストしないでください
クラッシュのトリアージ	実行時のクラッシュは、簡単に修正できる場合（誤字、インポートなど）は一度修正し、それ以外は二分探索で原因を特定します

停止条件（実行ループ）

条件	対応
ストライクが合格し、改善が目標を達成	停止 — コミットして「レポート」へ進みます
意見が分かれる代替案をすべてテスト済み	停止 — 最良の案をコミットして「レポート」へ進みます
二分探索ですべての仮説が除外された	停止 — プロファイリングデータとともに「すべての仮説が失敗」と報告します
所要時間を超過（45 分）	停止 — 残りの仮説とともに途中経過を報告します
ストライクと二分探索の後もすべてのテストが失敗	停止 — すべて元に戻し、診断上の価値のみを報告します

---

フェーズ 3：結果を報告する

レポートのスキーマ

フィールド	説明
baseline	元の測定値（指標 + 値）
final	最適化後の最終測定値
total_improvement_pct	全体の改善率
target_met	ブール値 — 目標の指標を達成したか
strike_result	clean（すべて適用）／bisected（一部を除外）／failed
hypotheses_applied	ストライクで適用した仮説 ID の一覧
hypotheses_removed	二分探索中に除外した仮説（理由付き）の一覧
contested_results	意見が分かれる各グループの結果：テストした代替案、最良の案、測定値
branch	Worktree のブランチ名
files_modified	変更したすべてのファイル
e2e_test	{ command, source, baseline_passed, final_passed } または null

結果の比較（必須）

performance_map.baseline のすべての指標について、ベースラインと最終結果を比較して示します。割合と倍率の両方を含めます。

| Metric | Baseline | After Strike | Improvement |
|--------|----------|-------------|-------------|
| Wall time | 7280ms | 3800ms | 47.8% (1.9x) |
| CPU time | 850ms | 720ms | 15.3% (1.2x) |
| Memory peak | 256MB | 245MB | 4.3% |
| HTTP round-trips | 13 | 2 | 84.6% (6.5x) |

Target: 5000ms → Achieved: 3800ms ✓ TARGET MET

関数ごとの差分（計測機能が利用可能な場合）

コンテキストの instrumented_files が空でない場合、ストライクの後に test_command をもう一度実行し、プロファイラーが配置したものと同じ計測コードを使って関数ごとの実行時間を記録します。

| Function | Before (ms) | After (ms) | Delta |
|----------|------------|------------|-------|
| mt_translate | 3500 | 450 | -87% (7.8x) |
| tikal_extract | 2800 | 2800 | 0% (unchanged) |

その後、git checkout -- {instrumented_files} を実行してクリーンアップします。最終コミットの前に、プロファイリング用の計測コードをすべて削除してください。

2 つの表をユーザーに提示します。これが主要な成果物です。最初にユーザーが目にするのは数値です。

実験ログ

{project_root}/.hex-skills/optimization/{slug}/ln-814-log.tsv に書き込みます。

列	説明
timestamp	ISO 8601
phase	strike / bisect / contested
hypotheses	このラウンドで適用した ID（カンマ区切り）
baseline_ms	このラウンドの開始前のベースライン
result_ms	変更後の測定値
improvement_pct	変化率
status	applied / removed / alternative_a / alternative_b
commit	Git コミットハッシュ
files	変更したファイル（カンマ区切り）
e2e_status	pass / fail / skipped

ファイルがすでに存在する場合は追記します（複数回の実行にわたる追跡が可能になります）。

---

フェーズ 4：ギャップ分析（目標未達の場合）

すべての仮説を適用しても目標指標に達しなかった場合：

セクション	内容
達成内容	達成した内容（元の値 → 最終値、改善率）
残存するボトルネック	タイムマップで、引き続き大きな割合を占めるステップ
残りのサイクル数	コーディネーターが複数サイクルを実行する場合：「残り {remaining} 回の最適化サイクルを、残存するボトルネックに利用できます」
インフラストラクチャに関する推奨事項	ボトルネックの解消にインフラストラクチャの変更（スケーリング、キャッシュレイヤー、CDN）が必要な場合
追加調査	今回の実行では検討していない最適化の方向性

---

エラー処理

エラー	対処
Strike ですべてのテストが失敗する	Bisect で問題を起こしている仮説を特定し、取り除いてから再試行します
Strike で改善が見られない	Bisect で効果のない仮説を特定します
測定値にばらつきがある（分散が大きい）	実行回数を 10 回に増やし、中央値を使用します
Worktree の作成に失敗する	git_worktree_fallback.md に従ってブランチに切り替えます
時間の上限を超過する	ループを停止し、未適用の仮説とともに部分的な結果を報告します
複数ファイルのリバートに失敗する	Worktree 内で git checkout -- . を実行します（Worktree は隔離されているため安全です）

---

参考資料

• optimization_categories.md — 最適化パターンのチェックリスト
• references/ci_tool_detection.md（テストとベンチマークの検出）
• references/git_worktree_fallback.md（Worktree の隔離）

---

実行時サマリーアーティファクト

必ず読み込んでください： references/coordinator_summary_contract.md を読み込みます。

optimization-worker サマリーエンベロープを出力します。

マネージドモード：

• ln-810 が決定論的な runId と正確な summaryArtifactPath を渡します
• 指定された summaryArtifactPath にサマリーを書き込みます

スタンドアロンモード：

• runId と summaryArtifactPath は省略します
• .hex-skills/runtime-artifacts/runs/{run_id}/optimization-worker/ln-814--{identifier}.json に書き込みます

モニターとの連携（Claude Code 2.1.98+）

必ず読み込んでください： references/monitor_integration_pattern.md を読み込みます。

複数回の最適化サイクル（ベースライン＋A/B）の実行中： Monitor(command="{test_command} 2>&1 | grep --line-buffered -E 'run|result|error|FAIL'", timeout_ms=600000, description="optimization run")

代替手段：Monitor が利用できない場合は、Bash(run_in_background=true) を使用します。

完了の定義

• 観測された問題と同じ指標の種類を使ってベースラインを確立した
• 仮説を分類した：競合なしと競合あり
• Strike を適用した：競合のない仮説をすべて一度に実装した
• Strike 後にテストが合格した
• 競合する代替案 A/B を完全な実装に加えてテストした
• Strike が失敗した場合にのみ Bisect を実施した（事前には実施しない）
• E2E 安全性テストに合格した（または利用できないことを記録した）
• 実験ログを .hex-skills/optimization/{slug}/ln-814-log.tsv に書き込んだ
• ベースライン、最終値、改善率、Strike の結果を含むレポートを返した
• すべての変更を隔離されたブランチに加え、リモートにプッシュした
• 目標指標に達しなかった場合、ギャップ分析を提示した
• 最適化実行アーティファクトを共有の場所に書き込んだ

---

バージョン： 2.0.0 最終更新日： 2026-03-14