Auto-Optimize：自主优化流程

使用 auto-run-agent 编排 Claude Code 对目标项目进行持续自动优化。

核心原则（从 30+ 实战 session 提炼）

1. 不修比乱修重要 — 每个发现必须分类为 FIX / SKIP / DEFER，SKIP 必须附理由
2. 扫描维度轮换 — 不要每次只找同一类问题，按维度轮换扫描
3. 原子验证 — 每个 fix 独立验证，不攒到最后一起跑
4. 经验持久化 — 踩过的坑写入 MEMORY.md，避免跨 session 重复犯错

扫描维度（按轮次轮换）

用户可指定维度，否则按项目当前状态自动选择最需要的维度。

完整流程

Phase 1：探索与评估

1. 确认目标项目路径（用户提供或当前目录）
2. 深度探索项目：

• 读取 README、CLAUDE.md 等项目规范
• 分析项目结构、技术栈、依赖
• 阅读核心源码，理解架构
• 检查 TODO/FIXME、#[allow(dead_code)] 等标记

1. 按当前维度并行扫描（用 sub-agent 按模块分区扫描）
2. 输出评估报告给用户，确认优化方向

Phase 2：分类与设计

对每个发现进行三分类：

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 内联样式 vs 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

1. CONTEXT.md 必须包含：

• 项目概述和技术栈
• 架构概览（关键模块和职责）
• 项目规范（引用项目自身的 CLAUDE.md 或编码规范）
• 构建和测试命令（每次修改后必须验证）
• commit 规范（如有 DCO 要求等）
• 当前扫描维度和轮次记录

1. 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

1. Worker 执行规则：

• 每个 fix 完成后立即运行验证命令（从 CONTEXT.md 读取）
• 验证失败 → 立即回滚该 fix，标记为 DEFER，继续下一个
• 验证通过 → commit，标记为 DONE，更新 DONE.md
• 每完成一个 fix，检查是否触发了新问题（回归检测）

1. 监控命令：

• tail -f <runner-dir>/logs/orchestrator_*.log — 实时日志
• cat <runner-dir>/memory/DONE.md — 查看完成记录
• cat <runner-dir>/memory/TASKS.md — 查看剩余任务

Phase 5：收尾与学习

1. 所有 FIX 完成后，运行完整测试套件
2. bump version（patch for fixes, minor for new features）
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）