Guardrails so AI-written code doesn't turn into spaghetti

I like open source. I've been using open source projects for many years, and there are some very, very good ones. I wanted to try building one myself, just to see how to set it all up.

At the time I was doing some freelance work for a friend at a company called MagSmith (magsmith.com), and I needed to manage my timesheets. I looked at some of the open source time trackers, the top three alternatives: solidtime, Kimai and TimeTagger, and they're okay. But I don't like it when a product says it's free but has a bunch of paid stuff on top. You want to use a feature and it ends up requiring an upgrade. I hate that.

So I wrote my own, the way I like it. It's called UseHourly, and I use it myself.

My first AI coding experience came at work. We started using AI about a year ago. I started with an AI coding assistant in the IDE, and at that time AI was still not there. It couldn't produce code sophisticated enough for what we needed, and it made way too many mistakes. But it was helpful.

About six months ago, around the time when the Claude Opus model came out, it became good enough. It could implement the code completely from a Jira ticket, and then implement a list of tests by itself, like Cucumber tests for the integration tests. All by itself.

That was my first experience, and I love it.

When I started UseHourly, I was kind of vibe coding it. Nothing was really going bad yet. It wasn't spaghetti code yet, because it's a reasonably small project. But I know that in a larger project it becomes a problem. I know this from experience.

So instead of letting it keep running code until it becomes spaghetti, I added some guardrails to let it know what not to do and what to do. Check for code smells, write good code, maintain good coding practices, enforcement, and stuff like that. Basically, how to keep a clean, tidy code base with well-written code and good test coverage. That's the goal.

First, I wrote the rules down in a file called CLAUDE.md, in the project. The assistant reads it every time it starts. It says how the project is built, how money and dates are stored, and what "done" means.

Second, I made one command that runs all the checks. It's the only definition of "the checks". I run it, the CI runs it, and the git hooks run it, so nobody can say "it passed on my side". If it fails, the work isn't done.

Third, I turned the rules into checks that fail the build. No any types, no ignoring the type checker, no TODO without an issue number, no copy-pasted code, no unused files, and a minimum test coverage that can only go up, never down. The AI can't talk its way past them. If it takes a shortcut, the build says no and it fixes it.

Fourth, I write the tests the way a person uses the app. At one point the AI rewrote a screen and a button did nothing. The tests passed, because none of them ever clicked it. So I added a test that clicks every button on every page, and a rule that every bug fix comes with a test that fails without the fix.

And now I review the code before I commit it, not after. A fresh reviewer reads the change cold, because the assistant that wrote the code is the worst reader of it.

So that's my story. I love open source, and I love working with AI coding assistants. But you can't just let the AI keep going. On a bigger project it turns into spaghetti, and I know that from experience.

So I put guardrails in place. Rules that tell it what to do and what not to do, and checks that make sure it does. The goal is a clean, tidy code base with well-written code and good test coverage.

I've turned these checks into a small tool, so anyone can add them to their own project. It's open source: https://github.com/Zontak-LLC/railing

I dictated this article and had Claude help me put it in order and check the facts against my code.