Design docs are the new source code

I’m building a simulator that teaches manual driving by showing you why you stalled. It’s modelled on my own car and driven with a wheel and pedals I already own. AI agents write most of the code. I wrote almost none of it by hand, and the project still feels more mine than most code I’ve typed.

That’s because the real work happened before any code existed.

The design is the program

Before the first agent run I wrote down four things:

The physics model. Three rotating parts (engine, clutch, wheels) connected by friction and gears, stepped a thousand times a second. Stalling has to come out of that model, not from an if-statement.
The ground truth. I have no data logger on my car, so the truth is how it behaves when I drive it. Each behaviour I know became an automated test: release the clutch slowly on the flat and the car creeps without stalling; dump it and it stalls; stop on a hill and the car holds for about two seconds, then rolls back.
The rules. A short file the agent reads on every run.
The milestones. Hardware check, physics core, drivable prototype, first release. One at a time.

Five rules that do most of the work

The physics core has zero dependencies.
Behaviour must emerge from physics. No special cases.
Never weaken a test to make it pass.
No new hardware. Use what’s on the desk.
One milestone at a time.

Each rule exists because an agent, left alone, will happily do the opposite. Ask it to make a stall test pass and the quickest route is a special case that detects the test. Ask it for force feedback and it may suggest buying a better wheel. The rules close those doors before the agent reaches them.

Split the work by what needs your hands

The physics core needs nothing but a computer, so agents build and test it on their own. Anything that touches the wheel and pedals waits for me at my desk, because only a person can tell whether a clutch feels right. That split lets the agents work while I’m busy, and keeps my time for the part only I can judge.

What I’ve learned so far

This article is written mid-build, with the physics core in progress. The early lesson is already clear: the quality of what an agent builds is capped by the quality of what you wrote before it started. Vague design, vague code. Precise tests, precise code.

I’ll update this when the first drivable version is on my desk.