Rodeo Philosophy

this part comes straight from a post by poteto on x. the idea is you want most of your effort at the top, on the codebase itself. then static analysis. then prose. human review goes last because it's the thing that scales the worst.

so within rodeo, the foundation does most of the work. on top of that, lint checks everything, even the design. if an agent reaches for a color or a size that isn't in the theme, lint fails it, so you don't end up with little design papercuts everywhere. and every lint error tells the agent how to fix it. then there are seven short guides an agent only reads when it needs one. and then you, looking at whatever's left.

the trick is making the easy thing the right thing. agents take the shortest path, every time. so if the shortest path is importing server code into a component, that's exactly what you'll get. in rodeo that import fails the build, so the shortest path goes somewhere better.

if your first instinct is a longer AGENTS.md, i get it, mine was too. but every line you add there is a suggestion. a lint rule isn't.

an agent is at its best right after it writes something. the file's open, the context is fresh, and fixing it costs one more edit. the same mistake caught in review costs you a whole round trip.

so rodeo checks all the time. every edit gets formatted, linted and typechecked. the end of a turn checks everything that changed. commits check the staged files, pushes build the app and run every browser test, and CI starts from a clean install and does it all again.

the fast checks only look at the file the agent just touched, so they come back quick. the slow stuff, building the whole app and running browser tests, waits until you push, when you're done anyway.

that's the other thing. every error names its fix. an error that just says no teaches the agent to sneak around it. one that says "use a clearer name" teaches it what you actually wanted.

it sounds small but it changes how the whole thing feels. you stop finding the same mistake in every review, because the agent already heard about it the second it wrote it.

agents read everything you give them. every comment, every test, every doc. all of it costs context they could be spending on the actual task.

and it compounds. every comment is something the next agent reads, and probably copies. every unit test is something the next change has to go fix. so the overhead isn't a one time cost, it grows with the codebase. give it a year and a big chunk of every task is upkeep on stuff that never caught a single bug.

so rodeo drops a few habits that are fine for people and kinda terrible for agents.

Comments

most comments just say the code again in english. the agent can already read the code, so that's tokens for nothing. and agents copy what they see. one comment explaining a workaround and suddenly every other file has one. it spreads like a weed.¹

if the code needs explaining, explain it in code. a better name, a smaller function, a type. and if none of that works, it's usually a workaround, and the fix is fixing it, not writing about it.

// Only the author or an admin can edit
if (user.id === post.authorId || user.role === "admin") {

const canEdit = isAuthor(user, post) || isAdmin(user);
if (canEdit) {

Unit tests

agents love writing tests like "the header says welcome". then you change the header, the test fails even though nothing broke, and the agent burns tokens rewriting a test that never caught anything. a browser test clicks through the app like a person would, so when it fails, something's actually broken.

browser tests are slower, sure. but you need way fewer of them, they test what people actually do, and they don't fall over every time you rename something.

Docs

rodeo has seven short guides and that's it. an agent opens one when the task needs it. a hook blocks new docs anywhere else, because docs go stale and agents trust them anyway.

if something can be a lint rule, it's a lint rule. docs are for the stuff code can't say.

every rule needs a way out, or agents find their own, and theirs is usually worse. so each rule in rodeo has exactly one exit, and it always makes you leave a reason behind.

inline disable comments are just banned. if a rule is wrong for a file, the exception goes in vite.config.ts with a why: comment. it's all in one file, so it's easy to see everything that's been bent, and why.

and when an agent makes the same mistake twice, it becomes a rule, not another paragraph in a doc. that's pretty much how rodeo got built.

none of this is about taking people out of the loop. it's about what you spend your attention on. if the codebase catches the comments and the random colors and the unvalidated inputs, your review goes to the stuff that actually needs a person.

you still review, obviously. but instead of writing "please don't add a comment here" for the hundredth time, you're looking at whether the feature actually makes sense.

after a week in a rodeo app i hope you trust your agents a little more. and maybe sleep a bit better.

none of this is set in stone. models keep getting smarter, and some of these guardrails are going to stop pulling their weight. a rule that saves an agent today might just be noise for the next model.

so here's my commitment: when a guardrail stops catching real mistakes, i'll take it out. rodeo should fit what the current frontier models need, not what they needed a year ago.

the whole point is to stay as lean as possible. give agents exactly what they need and nothing they don't. ideally rodeo just saves you time and money, and it's free.

huge thanks to poteto. the pyramid comes from their post on x, and so does the idea of killing comments. thanks to graphical for the theme and the stickers, and to benji, whose family values post is why this page looks like this.

rodeo stands on vite+, tanstack start, react, tailwind, shadcn/ui, base ui and nitro. thank you all.