auto-optimize

Auto-Optimize: Autonomous Optimization Workflow

Use auto-run-agent to orchestrate Claude Code for continuous autonomous optimization of a target project.

Core Principles (distilled from 30+ real-world sessions)

Not fixing is more important than fixing recklessly — Every finding must be classified as FIX / SKIP / DEFER, and SKIP must include a reason
Rotate scan dimensions — Do not only look for the same type of problem every time; rotate scans by dimension
Atomic verification — Verify each fix independently; do not accumulate them all and run them together at the end
Persist experience — Write pitfalls encountered into MEMORY.md to avoid repeating mistakes across sessions

Scan Dimensions (rotated by round)

Round	Dimension	Scan Target
1	Bug	Logic errors, deadlocks, TOCTOU, panic paths, boundary conditions
2	Architecture	Naming conflicts, confused responsibilities, module coupling, type design flaws
3	Duplication	Code duplication, extractable common logic, copy-paste traces
4	Performance	Unnecessary clone/alloc, O(n²) paths, blocking calls
5	Testing	Missing coverage, fragile assertions, missing boundary cases
6	API	Feature gaps compared with competitors, usability issues, missing documentation

The user may specify dimensions; otherwise, automatically select the most needed dimension based on the project's current state.

Complete Workflow

Phase 1: Exploration and Evaluation

Confirm the target project path (provided by the user or the current directory)
Deeply explore the project:
- Read README, CLAUDE.md, and other project specifications
- Analyze the project structure, tech stack, and dependencies
- Read the core source code and understand the architecture
- Check markers such as TODO/FIXME, #[allow(dead_code)], etc.
Scan in parallel by the current dimension (use sub-agents to scan by module partition)
Output an evaluation report to the user and confirm the optimization direction

Phase 2: Classification and Design

Classify each finding into three categories:

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

SKIP criteria (load the rules for the corresponding language under the rules/ directory):

Touches public API signatures → SKIP (unless the user explicitly requests a breaking change)
"Duplication" used in only 1 place → SKIP (extracting an abstraction is over-engineering)
Similar code with different semantics → SKIP (e.g., inline Span styles vs. global Text styles)
Solvable by macros but would reduce readability → SKIP

Sort FIX tasks by dependency and generate a structured task list:

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

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

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

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

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

Phase 3: Create the Runner Environment

Commit the current state in the target project and create a new branch (e.g., auto-optimize）
Create the runner directory structure:

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

CONTEXT.md must include:
- Project overview and tech stack
- Architecture overview (key modules and responsibilities)
- Project specifications (reference the project's own CLAUDE.md or coding standards)
- Build and test commands (must be verified after every change)
- Commit conventions (e.g., if DCO is required)
- Current scan dimension and round records
config.yaml default configuration:

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: Execution and Verification

Start with auto-run-agent:

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

Worker execution rules:
- After each fix is completed, immediately run the verification command (read from CONTEXT.md)
- Verification fails → immediately roll back that fix, mark it as DEFER, continue to the next one
- Verification passes → commit, mark as DONE, update DONE.md
- After each fix is completed, check whether new issues have been triggered (regression detection)
Monitoring commands:
- tail -f <runner-dir>/logs/orchestrator_*.log — real-time logs
- cat <runner-dir>/memory/DONE.md — view completion records
- cat <runner-dir>/memory/TASKS.md — view remaining tasks

Phase 5: Wrap-up and Learning

After all FIXes are completed, run the full test suite
bump version（patch for fixes, minor for new features）
Update the project MEMORY.md to record the patterns and lessons discovered in this round
Record the scan dimension for this round, and automatically switch to the next dimension next time

Rule System

Rule files are located in the rules/ directory, categorized by language. During scanning, the rules for the corresponding language are automatically loaded.

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

Rule format: each rule has an ID, category, description, and example. Workers refer to these rules during scanning and fixing to determine FIX/SKIP.

Key Points for User Interaction

After Phase 1 is completed, the assessment report must be shown to the user to confirm the optimization direction
The task list for Phase 2 is shown to the user for confirmation before files are created
Before starting, ask the user: number of iterations, time limit, whether there is a cost limit
The runner directory is placed by default in ~/Desktop/code/AI/<project-name>-runner/
Users can edit TASKS.md at any time to insert new tasks or adjust priorities

Notes

auto-run-agent is located in <auto-run-agent 目录>
The target project must be committed cleanly before switching branches to ensure rollback is possible
Use symlinks for the workspace; do not copy code
Multiple projects can run simultaneously without affecting each other (mind the API rate limit)