auto-optimize

Auto-Optimize：自動最適化プロセス

auto-run-agent を使用して Claude Code をオーケストレーションし、対象プロジェクトを継続的に自動最適化します。

核心原則（30 回以上の実践セッションから抽出）

1. 修正しないことは、むやみに修正することより重要です — 発見事項はすべて FIX／SKIP／DEFER に分類し、SKIP には必ず理由を付けます
2. スキャンする観点をローテーションします — 毎回同じ種類の問題だけを探さず、観点を切り替えてスキャンします
3. 個別に検証します — 各 fix を個別に検証し、最後にまとめて実行しないでください
4. 経験を永続化します — はまった点を MEMORY.md に記録し、セッションをまたいで同じ間違いを繰り返さないようにします

スキャンする観点（ラウンドごとにローテーション）

ラウンド	観点	スキャン対象
1	バグ	論理エラー、デッドロック、TOCTOU、panic の経路、境界条件
2	アーキテクチャ	名前の衝突、責務の混乱、モジュールの結合、型設計の不備
3	重複	コードの重複、抽出可能な共通ロジック、コピー＆ペーストの痕跡
4	パフォーマンス	不要な clone／alloc、O(n²) の経路、ブロッキング呼び出し
5	テスト	カバレッジの不足、脆弱なアサーション、境界ケースの不足
6	API	競合製品と比較した機能の不足、使いやすさの問題、ドキュメントの不足

ユーザーが観点を指定できます。指定がない場合は、プロジェクトの現在の状態に応じて最も必要な観点を自動的に選択します。

全体の流れ

Phase 1：調査と評価

1. 対象プロジェクトのパスを確認します（ユーザーから指定されたパス、または現在のディレクトリ）
2. プロジェクトを詳細に調査します：
   • README、CLAUDE.md などのプロジェクト規約を読みます
   • プロジェクト構造、技術スタック、依存関係を分析します
   • コアソースコードを読み、アーキテクチャを理解します
   • TODO／FIXME、#[allow(dead_code)] などのマーカーを確認します
3. 現在の観点に沿って並行スキャンします（sub-agent を使い、モジュールごとに分けてスキャンします）
4. 評価レポートをユーザーに提示し、最適化の方向性を確認します

Phase 2：分類と設計

発見事項をそれぞれ次の 3 種類に分類します：

FIX  — 有明确方案，不破坏公开 API，收益 > 风险
SKIP — 附理由：breaking change / over-engineering / not a bug / intentional design
DEFER — 需要更多信息或用户决策，记录到 TASKS.md 的 backlog 区

SKIP の判断基準（rules/ ディレクトリから該当する言語のルールを読み込みます）：

• 公開 API のシグネチャに影響する → SKIP（ユーザーが breaking change を明示的に求めている場合を除く）
• 使用箇所が 1 つだけの「重複」 → SKIP（抽象化の抽出は過剰設計です）
• 意味が異なる類似コード → SKIP（Span のインラインスタイルと Text のグローバルスタイルなど）
• マクロで解決できても、可読性が低下する → SKIP

FIX タスクを依存関係の順に並べ、構造化されたタスクリストを作成します：

## 高优先级
- [ ] [BUG] 描述 | 文件 | 方案摘要
- [ ] [BUG] ...

## 中优先级
- [ ] [DEDUP] 描述 | 文件 | 方案摘要
- [ ] [DESIGN] ...

## 架构审查（高/中完成后触发）
- [ ] [ARCH] 全面审查架构合理性，发现问题追加新任务

## 低优先级
- [ ] [STYLE] ...

## Backlog（DEFER）
- [ ] [DEFER] 描述 | 需要的信息

Phase 3：Runner 環境の作成

1. 対象プロジェクトの現在の状態を commit し、新しいブランチ（auto-optimize など）を作成します
2. runner ディレクトリの構造を作成します：

<runner-dir>/
├── memory/
│   ├── TASKS.md      # Phase 2 设计的任务列表
│   ├── CONTEXT.md    # 项目背景、技术栈、规范、架构概览
│   └── DONE.md       # 自动生成
├── workspace/        # 软链接到目标项目
├── logs/
└── config.yaml

3. CONTEXT.md には次の内容を必ず含めます：

   • プロジェクトの概要と技術スタック
   • アーキテクチャの概要（主要なモジュールと責務）
   • プロジェクト規約（プロジェクト固有の CLAUDE.md またはコーディング規約を参照）
   • ビルドおよびテストコマンド（変更のたびに検証する必要があります）
   • commit 規約（DCO 要件などがある場合）
   • 現在のスキャン観点とラウンドの記録

4. config.yaml のデフォルト設定：

max_iterations: 50
max_cost_usd: 0
max_duration: 6h
consecutive_no_progress: 3
stop_when_empty: true
cooldown_duration: 15s
worker_timeout: 30m
use_git_detection: true

Phase 4：実行と検証

1. auto-run-agent を使用して起動します：

cd <auto-run-agent 目录>
./orchestrator --dir <runner-dir> --max-iterations 50 --max-cost 0 --max-duration 6

2. Worker の実行ルール：
   • 各 fix の完了後、すぐに検証コマンドを実行します（CONTEXT.md から読み取ります）
   • 検証に失敗 → 該当する fix をすぐにロールバックし、DEFER としてマークして次へ進みます
   • 検証に成功 → commit し、DONE としてマークして、DONE.md を更新します
   • fix を 1 つ完了するごとに、新しい問題が発生していないか確認します（リグレッション検出）
3. 監視コマンド：
   • tail -f <runner-dir>/logs/orchestrator_*.log — リアルタイムログ
   • cat <runner-dir>/memory/DONE.md — 完了記録を確認
   • cat <runner-dir>/memory/TASKS.md — 残りのタスクを確認

Phase 5：完了と学習

1. すべての FIX が完了したら、テストスイート全体を実行します
2. バージョンを上げます（修正の場合は patch、新機能の場合は minor）
3. プロジェクトの MEMORY.md を更新し、今回発見したパターンや教訓を記録します
4. 今回のスキャン観点を記録し、次回は次の観点に自動で切り替わるようにします

ルールシステム

ルールファイルは rules/ ディレクトリにあり、言語ごとに分類されています。スキャン時に該当する言語のルールが自動的に読み込まれます。

auto-optimize/
├── SKILL.md
└── rules/
    ├── universal.md   ← 通用规则（所有语言适用）
    ├── rust.md        ← Rust 特定规则
    ├── python.md      ← Python 特定规则
    ├── typescript.md  ← TypeScript 特定规则
    └── go.md          ← Go 特定规则

ルールの形式：各ルールには ID、カテゴリ、説明、例があります。Worker はスキャンおよび修正時にこれらのルールを参照し、FIX／SKIP を判断します。

ユーザーとのやり取りに関する要点

• Phase 1 の完了後、評価レポートを必ずユーザーに提示し、最適化の方向性を確認します
• Phase 2 のタスクリストをユーザーに提示して確認を得てから、ファイルを作成します
• 起動前に、反復回数、時間制限、コスト制限の有無をユーザーに確認します
• runner ディレクトリのデフォルトの保存先は ~/Desktop/code/AI/<project-name>-runner/ です
• ユーザーはいつでも TASKS.md を編集して、新しいタスクを挿入したり、優先順位を調整したりできます

注意事項

• auto-run-agent は <auto-run-agent 目录> にあります
• 対象プロジェクトは、ロールバックできるよう、ブランチを切る前にすべての変更を commit してクリーンな状態にする必要があります
• workspace にはソフトリンクを使用し、コードをコピーしません
• 複数のプロジェクトを同時に実行できます。互いに影響しません（API rate limit に注意してください）