A Repo That Tells the Agent the Rules
Our side project Stem Shovel, the browser-based music collaboration tool we wrote about recently, is now more than 1,100 source files and about 2,300 tests. Most of that code was typed by coding agents working under direction. The question we get about that pace is usually some form of "how does it not turn to mush?" The answer is not a smarter model or a longer prompt. The answer is that the repository itself tells every agent the rules, and it does so in ways an agent can check mechanically, mid-edit, without asking anyone.
That sentence describes a design discipline, so here is what it looks like in practice.
A Working Agreement, Not a Wiki
At the root of the repo sits a 171-line working agreement. It is not reference documentation (that lives in 29 topic documents under docs/); it is the rules of the house, written for a reader who is about to change something. Every mutation is a remote function validated by a schema, never a form action. Every database query scopes by account before anything else. Styling is utility classes only, one helper function per file, transient feedback goes through the notification stack. And the agreement states the social contract too: which branch work lands on, who merges to production, and when to add an entry to the findings file.
The useful property is that each rule is phrased as a decision already made. An agent reading "valibot for validation, native Intl for dates, fetch for HTTP" does not have to weigh options, and neither does the human reviewing its diff. The agreement spends its words where drift would start.
Rules that Check Themselves
A written rule decays unless something enforces it, so the rules that can be checked mechanically are. A file called fallow-rules.json encodes them for Fallow, the repo auditing tool: no $env imports, no form actions, no banned packages (zod, moment, lodash, dotenv, axios), warnings for $effect and raw window listeners. CI runs fallow audit over changed files and files the findings in GitHub's code-scanning tab.
The part we like best runs before the edit, not after. fallow guard <file> answers the question an agent should ask first: which rules and import boundaries apply to this specific file? Point it at a schema file and it prints the file's zone, the zones it may import from, and every policy rule that binds it, each with the reason and the documented escape hatch (a suppression comment that requires a written justification). The agent gets the constraints while there is still time to respect them, in a format it can read in one gulp. A rule that arrives as a failing CI check an hour later teaches the same lesson at ten times the cost.
Agents that Can See and Walk
Two more tools close the loop between "the agent changed something" and "the change is actually right."
The screenshot bot gives agents eyes. bun run shot <path> captures a full-page image of any page on the dev server, signed in as a dedicated bot user when members-only controls need to render, and prints any page or console errors it saw along the way. The agent then reads the image directly, because the models are multimodal now. Layout bugs that no assertion would catch get caught by the thing that caused them.
The smoke script gives agents legs. smoke:urls walks every route in the app, signed out and as the bot, against the dev server, staging, or production. Its sharpest rule is structural: every route under src/routes must have a row in the script, or the script fails. A new page joins the smoke test the day it is written, because forgetting is not an available option.
The Same Idea Pays Twice
We keep finding that the same idea pays twice. Our agent-readiness research measures how well AI agents can use a public website, and the recurring result is that structure beats tricks: a curated index in the right place outperforms clever instructions scattered around. Stem Shovel is that finding turned inward. The working agreement is the curated index. The guard tool is the index made queryable. The screenshot and smoke bots are the feedback channel that tells an agent whether its work held up.
None of this was free. The agreement gets edited when it gives bad advice, the rule pack grows a rule roughly every time a convention gets violated twice, and the smoke script's every-route requirement costs a minute of ceremony per new page. But the return compounds in a way that is easy to state: the cost of the next change stays flat. Agent number forty inherits every lesson agent number one learned, not as folklore in somebody's head but as rules in the tree, checkable before the edit and enforced after it.
If you are starting to work with coding agents on a codebase you care about, our advice is to spend your first day on none of the features. Write the working agreement. Make its checkable rules checkable. Give the agent a way to see its own work. The code that follows will be the proof.
