The pattern

Two projects independently discovered the same loop:

The human writes the process. The agent writes the code.

The loop

One file: improve.md

Part config, part prompt. Describes what to change, how to measure, and when to stop.

# autoimprove: make-it-faster
## Change
scope: the checkout handler and its database queries
exclude: test/, vendor/
## Check
test: go test ./...
run: go test -bench=. -benchmem
score: ns/op:\s+([\d.]+)
goal: lower
guard: allocs/op: ([\d.]+) < 500
keep_if_equal: true
timeout: 3m
## Stop
budget: 4h
stale: 15
## Instructions
Reduce allocations in hot paths. Try buffer reuse, fast-path patterns.

Natural language scope

You describe what to optimize. The agent resolves it to specific files.

## Change
scope: the template parsing engine
exclude: test/, benchmark/

Resolved scope "the template parsing engine" to:
  - lib/liquid/parser.rb
  - lib/liquid/lexer.rb
  - lib/liquid/variable.rb
These are the ONLY files that will be modified. Confirm? [y/n]

exclude prevents the agent from grading its own homework.

Three-layer check

test: go test ./...                  # gate
run: go test -bench=. -benchmem     # score
score: ns/op:\s+([\d.]+)
guard: allocs/op: ([\d.]+) < 500    # guard

Goal-aware bootstrap

The optimization goal predicts what the agent will break.

/autoimprove bootstrap --generate

Auto-guided setup

One command. The agent detects what's missing and walks you through it.

10 domain templates

/autoimprove init --type rag

Example: performance

# autoimprove: faster-checkout-api
## Change
scope: the checkout handler and its database queries
exclude: test/, vendor/
## Check
test: go test ./...
run: hey -n 1000 http://localhost:8080/checkout
score: Requests/sec:\s+([\d.]+)
goal: higher
guard: latency_p99: ([\d.]+) < 500
timeout: 3m
## Stop
budget: 4h | stale: 15
## Instructions
Try query batching, connection pooling, response caching.
Don't change the API contract or add dependencies.

Example: RAG pipeline

# autoimprove: better-rag-answers
## Change
scope: the RAG pipeline — chunking, retrieval, generation
exclude: data/, eval/
## Check
test: python -m pytest tests/test_pipeline.py -x
run: python eval/run_eval.py
score: answer_relevancy: ([\d.]+)
goal: higher
guard: error_rate: ([\d.]+) < 0.1
keep_if_equal: true
timeout: 5m
## Stop
budget: 6h | target: 0.92
## Instructions
Try: chunk size tuning, hybrid search, cross-encoder reranking,
query expansion, chain-of-thought generation.

Example: tabular ML

# autoimprove: better-churn-model
## Change
scope: the training pipeline
exclude: data/, evaluate.py
## Check
test: python -m pytest tests/ -x
run: python train.py && python evaluate.py
score: auc_roc: ([\d.]+)
goal: higher
guard: f1_score: ([\d.]+) > 0.6
timeout: 3m
## Stop
budget: 4h | target: 0.95
## Instructions
Try: ratio features, rolling aggregates, target encoding,
XGBoost vs LightGBM vs CatBoost, model stacking.

Goes beyond AutoML: the agent can engineer features, rewrite preprocessing, and try novel model combinations.

Real-world test: round 1

Applied to a RAG search engine: hybrid search over 44K chunks, 301 documents, 20-query golden set.

Real-world test: round 2

Applied the improved protocol (per-experiment commits, guards, keep_if_equal, supersedes).

What the changes actually do

What we learned

Agent-agnostic

The skill runs in Claude Code. The protocol runs anywhere.

/autoimprove                                  # Claude Code (interactive)
claude -p "run /autoimprove on improve.md"    # headless overnight
/autoimprove --export                         # generates program.md
codex -p "follow program.md"                  # any agent can follow it
gemini -p "follow program.md"

Not AutoML

The pattern works anywhere you have: a file to change, a command to run, and a number to improve.