Hey, Luca here! Welcome to a 🔒 weekly essay 🔒 from Refactoring.
Every week I write an article about how to ship fast and make good software, and interview a world-class tech leader. I also build and maintain Tolaria in the open, publishing my workflows and learnings here.
Refactoring is read every week by 170,000+ engineers and managers from all over the world!
Hey! When I launched Tolaria I promised I would publish ~monthly updates to my AI coding workflow. The last one was in April, so I am late!
In May I also published how I run Tolaria as a project, but this was more about general orchestration, so I wanted to post an update that is more specific to coding.
I will start by saying that things are going... well.
Tolaria by now has a few thousands daily users, most whom are engineers. These are quite eager to report bugs, submit PRs, and suggest improvements on social media, Github discussions, email, and more — so keeping up with everything is quite a lot of work.
Still, I am happy with where we stand. As I write these, we got:
6 open issues — vs 417 closed.
14 open PRs — vs 306 closed.
1 day — average bug fix time.
99.1% crash-free rate — as measured by Sentry.
~28 commits / day — on average.
2 hours a day — I work on Tolaria, give or take.
I released Tolaria on April 22nd, so all of this happened in little more than a month, which is crazy when you think about it. From the day of the release, I added about ~1000 commits, and the codebase has grown a bit, but not massively: right now it’s 150K LOC, plus ~100K LOC of tests.
Most importantly, I don’t feel my velocity has decreased.
If anything, I am probably producing more output per unit of input than two months ago, so the effectiveness feels higher. Code quality also is higher, we are not drowning in regressions, and the rate at which bugs are reported feels stable.
So today I will cover the tweaks I made to my AI coding over the last ~2 months. To catch up with the full process, you can also go back to the previous articles here:
Here is the agenda for today:
🚥 Guides, Gates, and Guards — my mental model for the various types of AI instructions. The core of the article.
🤖 From Claude to Codex — I moved to Codex and (for now) I am not going back.
💸 How much I am spending — monthly cost is now down >90%
🔭 What’s next / missing — what I am trying to improve right now
Let’s dive in!
🚥 Guides, Gates and Guards
When it comes to the dev process, I think about the types of inputs that I can give to AI in three steps:
↪️ Guides — rules and explainers of how to do things.
🔄 Gates — deterministic checks that block bad things and force the AI to steer its output.
↩️ Guards — fallback procedures to improve what falls through the cracks.
These steps are also somewhat sequential:
Guides are the basic context that the AI uses to start the work
Gates get into play to steer the work while it’s in progress
Guards are the last line of defense against enshittification.
Let’s look at all of them:
1) Guides ↪️
We can as well call them rules, but then we’d lose the 3G’s memorability!
These days you write guides for AI agents in two main ways:
AGENTS.md / CLAUDE.md — the core instructions that the agent always loads.
Skills — specific instructions to do particular tasks. A skill gets used only when the task requires it.
It’s worth noting that the boundaries between the two surfaces are not very clear. It’s often dubious whether you should create a separate skill or just slam everything into the AGENTS.md, and even benchmarks are inconclusive about the effectiveness of the various strategies.
I believe that’s because, at their core, they are the same thing: instructions to the agent.
My dev process is simple enough that I can afford to keep everything into the AGENTS.md, and not use any specific skill. I have tried a few and never felt things got noticeably better, so I opted for keeping things simple.
You can inspect the actual file — it’s not perfect, mind you, but gives you a more precise idea.
In my AGENTS.md, the most important instructions are about:
TDD — the agents has to write tests first and do the classic red → green → refactor.
Boy scout rule — leave the code in a better shape than you found it. It should also measure the before/after quantitatively with CodeScene and Codacy.
UI — always use shadcn/ui components when possible, and inspect our design language before implementing new UI (we got basic tokens for colors, typography, spacing, etc).
Localization — extract and translate all the new strings in the supported languages. I use the Lara CLI for this.