Agents don’t care about your instructions

Put the code up for review and you still end up reviewing, reworking and refactoring the code three more times after your coworkers’ AI agent puts around 10 review comments on your PR.

No idea what most comments mean, but fixing it is faster than understanding.

It didn’t start like this. At the start of a project, your AI agent loyally follows the few lines in your instruction files. However, after the Jenga tower of complex code, AI-written docs and bible of .rules grows, it struggles to follow all of it to the letter.

And if we got really spoiled by vibing without reading the code, eventually it becomes quite hard to understand. The common reflex is to chase shinier skills, plugins and models to see if that improves things. Maybe some complex unicorn setup with 6 AI agents that write and review code at the same time will help?

Why can’t the AI just follow our rules?

The wrong question

The problem is real, but this is the wrong question to ask. Trying to make an non-deterministic system magically become fully accurate is not going to happen.

The real superchargers of speeding up your AI-first workflow are not that shiny though. And not very new either. We engineers just tend to underutilize them.

Agents ignore instructions, but can’t ignore failing tests.

Unit tests have become almost free, but they are also the most useless type of tests. Don’t get me wrong, I did TDD and I loved the way it forced you to think about behavior and design before coding.

However, with an AI-first workflow it’s useless to write unit tests up front. It’s very easy to assume good habits for humans are also good habits for agents, but this is not always true. Building a testing theater is a real productivity killer.

The biggest enabler of speed and the guardian of comprehensible structure are tools we have all heard of but not used enough.

Instantly prove it still works

A rule is easily skipped. A test cannot be skipped.

Being able to prove the application works as expected as fast as possible is the biggest speed accelerator. We can do this through automated Acceptance Tests. This was already the bottleneck for most teams before AI, but we just ignored it because writing code was more fun than testing it.

But now that we write code in a fraction of the time, the bottleneck of proving that it works has become very noticeable.

More changes means testing more often, and the longer it takes to prove everything is working, the longer it takes until we can ship software.

Rules an agent can’t ignore

But the other side of the coin is that the faster we add code, the more the application grows as a whole and the harder it is to understand for both humans and agents. So if we don’t pay attention to keeping a comprehensible structure, the codebase will still grow out of control. This is the classic example of unmaintainable vibe-coded codebases.

To prevent this from happening without becoming human review robots reviewing pull requests the whole day, we can utilise Architecture Tests.

Architecture tests are seriously underrated. Remember, rules can and thus will be ignored. Tests cannot. A suite of architecture tests will deterministically check if your conventions and agreements are followed.

For example, if you use the classic Controller → Service → Repository pattern, you could add this simple test that checks that a Controller never imports/uses a Repository directly. An instruction in CLAUDE.md might get ignored when an agent feels like it, but this test will always fail and the violation will be fixed immediately:

@Test
void controllersDoNotTouchRepositories() {
    noClasses()
        .that().areAnnotatedWith(RestController.class)
        .should().accessClassesThat()
        .areAssignableTo(CrudRepository.class)
        .because("controllers are the web layer, "
            + "repositories the data layer")
        .check(importedClasses);
}

Another practical example from a project I work on: We publish Spring Modulith events (domain events with an outbox), but the listeners only consume these events after the database transaction commits. This means that a method that is not marked with @Transactional can publish an event, but the event will not be consumed by its listener until we restart our application. No error thrown either, the event just sits in the outbox until the next restart. This was a source of multiple real bugs, until we wrote an architecture test for this that documents the rule:

@Test
void eventPublishingMethodsMustRunInATransaction() {
    methods()
        .that(publishApplicationEvents())
        .should(beTransactionallyCovered())
        .because("listeners run AFTER_COMMIT: "
            + "an event published outside a "
            + "transaction fires on the next restart")
        .check(importedClasses);
}

The best thing: these suites are fast and cheap. AI made it a breeze to write them, so adding them gives a ton of benefit for a very low cost. And they codify your conventions so that everyone on the team knows and follows the same ones.

So if you want to move faster and keep your code understandable, make these two types of tests part of your workflow.

What rules in your CLAUDE.md wish list deserve to become tests?