If you’re wondering what Evolve actually does with a change, this page is for you. It walks through one real run (a run is everything Evolve does for one goal), from the demo that comes with Evolve. Every number here is from the record that run wrote. By the end you’ll know all six steps a change goes through.
The setting
Picture a small online shop with a checkout service: the program that works out what an order costs. Every time someone asks for a price, it calls a tax service, another program, which takes about 170 milliseconds to answer. That’s slow. People wait, and the slowest 5% of requests (that’s what “p95” means) take 172 ms.
1. The goal
Someone writes the goal down in a way that can be checked:
p95 under 150 ms, while checkout correctness holds.
That second half matters just as much as the number. Fast and wrong is no good to anyone, and Evolve holds the change to both.
The repository (where the shop’s code lives) also holds Evolve’s policy: which tests prove the prices are right, how speed is measured, and how carefully a change is rolled out. Evolve locks that policy when the run starts. Nothing written during the run can change the rules.
2. Three attempts
Evolve asks for three attempts, each in its own sealed-off copy of the code. Normally a coding agent (an AI tool like Claude Code or Codex) writes them. In the demo they come from a script standing in for an agent, so you don’t need an AI key, the password-like code an AI service gives you to use it.
| Attempt | What it changed |
|---|---|
| skip-tax-lookup | stops calling the tax service at all |
| memoize-tax-table | remembers the tax table instead of asking for it every time |
| prefetch-tax-concurrently | fetches the table while doing other work |
3. The checks
Evolve builds each attempt (turns its code into a program that can run) and runs the checks from the policy: the tests, a set of real checkout requests with known right answers, and a load test, which sends lots of requests at once and times the answers. The agents never see these checks.
| Attempt | Prices right? | p95 | Result |
|---|---|---|---|
| skip-tax-lookup | no: tax missing | 1.4 ms | rejected |
| memoize-tax-table | yes | 1.8 ms | eligible |
| prefetch-tax-concurrently | yes | 172.2 ms | rejected: still too slow |
Look at that first row. The fastest attempt is the wrong one.
It’s exactly the kind of change that looks great in a quick review: tiny, and wildly faster. The checks caught it because the goal says prices have to stay right, and the checks hold every attempt to that.
Every result carries a signature, a digital stamp that shows if anyone changes it later, and is tied to the exact version of the code it was measured on. Change even one byte, and the evidence doesn’t count any more.
4. The decision
Only one attempt passed everything, so this choice is easy. With several, Evolve would still follow the written rule: fastest first, then the smallest change. The decision is recorded along with everything it was based on. Replay it later and you get the same answer.
5. On probation: the canary
Real people still do things the tests never tried. So the chosen version starts small, running next to the current one:
| Step | New version | Current version | Result |
|---|---|---|---|
| 10% of traffic | 103 requests | 1,026 requests | no errors, fast: keep going |
| 50% of traffic | 559 requests | 579 requests | no errors, fast: keep going |
| 100% | 909 requests, watched for a while longer | — | healthy: promoted, so it now serves everyone |
At each step Evolve compares the two versions over the same minutes. That way a busy spell can’t be mistaken for a bad change.
6. The record
The run’s over, and everything is written down. Evolve comes with a command called evolve that you type in a terminal. Ask evolve why about the version that’s running now and you get the whole story in order: the goal, the three attempts, the evidence, the decision, the canary steps and the promotion.
Next
The interesting runs are the ones that go wrong. When it goes wrong follows a change that passed every check and still broke something.