Building with an AI agent

An agent finishes a change to your drive effect and reports back:

Added smoothing to Drive. Typecheck passes. No clicks. Works as a desktop plugin.

It reads like a finished job. Four short sentences, all confident. Before you accept it, try checking one of them yourself. Sweep Amount quickly on the steady tones below and listen for ticks.

Whatever you heard, notice how you found out: by moving a knob on real sound and listening. No type checker can do that. Now predict: of the four sentences in that summary, which ones does "typecheck passes" actually support? It compiles? It makes sound? It doesn't click? It loads as a desktop plugin?

A summary is a list of claims

A good session player who says "nailed it" might be right. You still listen back on your own monitors before you call the take done. An agent's summary deserves the same treatment, for the same reason: confidence is in how it's written, not in what was checked.

The habit is simple. Split the summary into separate claims, then ask of each one: what would I need to see to believe this?

A type check proves the code is consistent: names, imports and parameter paths line up. It doesn't prove the module makes sound, resets, avoids clicks or loads anywhere. That's not a flaw in type checking; it's just a different question.

Review it claim by claim

Here's one review, step by step. The change and what came with it are an illustration, but every check is one you can run.

1state.drive = onePoleSmoothingStep(state.drive, state.driveTarget, state.driveCoefficient) (highlighted)

Notice that the review didn't throw the work away. Two claims were supported; the smoothing itself may be exactly right. What changed is the summary: from four confident sentences to two facts and two next steps. That version is more useful to you, and to the next person who touches the code.

Write a brief that asks for proof

The best time to ask for proof is before the work starts. A short brief does most of the reviewing for you, because it tells the agent what "done" means.

Start with the music. "Improve the effect" leaves everything open. "Drive changes on a held note should glide without ticks, but a quick flick on a drum fill should still land on time" gives the agent a target and gives you a test. Then add the boundaries and the proof you want back:

On my drive effect, make the Drive parameter glide smoothly while a held note plays, without making quick edits feel late. Read the current parameter path and Processor first. Use the shared slew helpers in @maruaudio/dsp/modulation/slew if they fit. Step the smoothing once per frame, and make a fresh instance start at its setting. Don't change the face or other parameters. When done, render a sudden Drive jump on a steady tone, and report the exact commands you ran with their results, and anything you didn't check.

If you scaffolded your project with npm create maru, it includes an AGENTS.md that spells out the module authoring rules for coding agents. Point your agent at it; it saves explaining where things live.

Ask for the report in a fixed shape. Maru's own rules for finished module work ask for: what changed, the exact commands run and their results, any fingerprints of built files, and what's still blocked. "Behaviour changed, checks run, results, what's left" reviews in a minute. Adjectives about quality take an afternoon.

Read the change for what you'd hear

When you read the diff, follow the sound, not the files. Start at the parameter, follow it into the Processor, and ask the questions from earlier guides: Does the new value start in the right place? Does reset handle it? Does a stereo signal step it once per frame? Does anything outside the brief change?

Then read the tests, closely. An agent under pressure to get a check passing has three easy outs: weaken the check, add an exception, or change the expected output to match whatever the code now does. Sometimes updating a test is correct, after an intentional change in sound. The report should then say so and explain why. A test that went green because its tolerance doubled hasn't proved anything.

And check that results are fresh. A render from before the change, or a cached report, can't show what the new code does. If a step printed SKIPPED, it didn't run, however successfully the command exited.

Same idea, different place: Testing sound and behaviour treats every test as a question. Reviewing an agent is checking that it asked the question your promise needs, and didn't quietly change the question.

Make it yours

Pick your next change, however small, and write a brief: the musical promise, where it starts, what not to touch, which checks to run and what to report. Give it to an agent if you like, or follow it yourself.

When the work comes back, review it with the sheet below. List each claim, what was actually shown, and your verdict. Aim for at least one claim you accept and one you send back for another check, each with its reason. If every claim is genuinely supported, write that down instead; the point is to see the difference, not to catch anyone out.

Keep the brief and the review with the project. Next time, start your brief from this one.

Quick check

1. The type check passed. Can you accept "no clicks"? No. Clicks are about sound while a value moves; a type check never runs the sound. You need a render with the knob moving, listened to or measured.
2. A failing test now passes, and the diff shows its tolerance doubled. What do you ask? Why the tolerance changed, and what behaviour the test is meant to protect. A test made easier to pass doesn't show the code improved.
3. The browser version works but no native build ran. Is the work worthless? Not at all. Accept the browser result and say clearly that the plugin hasn't been checked. Being exact about what's missing is what makes the rest trustworthy.

Next steps

• Use it: What makes an instrument inspiring. You can now build a tool that works and prove it. Will anyone love playing it?
• Sideways: What an audio model learns. A stem separator's output is an estimate, not the answer. An agent's summary is too, and the same habits of checking apply.