Tidy up your agent's instructions now and then

Every time your agent does something wrong, you add a line to its instructions. Once about the style, once about the folders, once about a word it must never use. After a few months, your AGENTS.md or CLAUDE.md has become a thick file. And yet your agent sometimes does things you taught it not to do a long time ago. You might recognise that.

In a vibe coding training, I talked about what I call the token tax. We think that more is better. So we write a thousand lines in such a file, with a lot of context, because the more it knows, the better it will work. I actually think that more accurate instructions work better than a lot of instructions. And that includes a bit of tidying up now and then.

Copy the prompt at the bottom of this article. With that, you let your agent check its own instructions.

Why a large file confuses your agent

An instruction file grows like a kitchen drawer. You always add something to it, and you never take anything out. Some rules are in there twice, in different words. Others have become redundant because you work differently. And a few simply contradict each other.

The latter are the most dangerous, because they arise by themselves. Suppose you once worked on an application and put together a colour palette for it, with a certain look and feel. That is somewhere in your instructions. Months later you build another app, and your agent thinks it should use that palette there too. Or it gets two instructions that go against each other, and then it chooses one itself. The file you wrote so it would understand you better, actually makes it uncertain.

And every rule that is there, it reads again with every task. The more of that is duplicated or outdated, the less room is left for what really matters for that task.

Frequently asked questions

Why does a long instruction file work worse?

Your agent reads it again with every task. Rules that are duplicated or outdated take up space without adding anything. And contradictory rules let it choose itself, often the wrong one.

Why should I do this in a new session?

An agent that has been working on a project for a long time is full of that project. In a fresh session, it reads its instructions with new eyes. Then duplicated and contradictory rules stand out faster.

Is my agent allowed to delete rules itself?

Let it make a proposal first and decide for yourself per point. Some rules are there for a reason that only you know.

Where do I learn to work with agents and their instructions?

In the 'Vibe Coding with AI' and 'AI agents' trainings, you work hands-on with agents and their instruction files. You can find all dates at Workshops & Events.

Keep reading for free

Register free with your e-mail address and read on. Your account opens the free articles in the learning space; the rest is for subscribers, from Learn Plus up.

No comments yetRead the comments

Comments

Members comment here and read each other's comments. Register for free or sign in to join the conversation.

No comments yet. What do you take away?