What is a CLAUDE.md file?

A plain Markdown file in a project root that Claude Code reads at the start of each session. It holds your conventions, your stack and your preferences, so they apply automatically instead of being re-explained in every conversation.

Why does my AI agent ignore my instructions?

Usually because the instruction was given in a previous session and there is no memory across sessions. Move it into a rules file that is read every time. If it is ignored even then, the task is probably long enough that a harness with enforced hooks is the right answer.

Is a rules file enough on its own?

For most people, yes. It steers rather than enforces, so a model can still deviate on a long task, but it removes the large majority of repeated corrections for a few minutes of setup.

Do these files work with agents other than Claude Code?

The principles transfer to any coding agent. The filename and location differ, since each agent reads project instructions from its own path, so you would place the same content wherever your agent looks for it.

Will this stop the agent overcomplicating things?

It substantially reduces it. Overbuilding comes from the agent having no stated standard for how much change is appropriate, so a rule that says make surgical edits and prefer the simplest thing that works addresses the cause directly.

Why Your AI Agent Keeps Making the Same Mistake

An agent that forgets your conventions every session is not badly prompted. It is unconfigured. There are two fixes and they solve different problems.

You tell the agent not to rewrite whole files for a one-line change. It agrees. Next session it rewrites a whole file for a one-line change.

The instinct is to write a better prompt. That is treating a configuration problem as a wording problem, and it is why people end up with a paragraph of preferences they paste at the start of every conversation.

Why it forgets

Each session begins with no memory of the last one. Whatever you established yesterday, the conventions, the corrections, the things you told it to stop doing, is gone.

So the agent falls back on defaults learned from an enormous amount of public code. Those defaults are generic, and generic on your codebase looks like overbuilding, silent assumptions and changes far larger than the task asked for.

The two failure modes

Almost every complaint about coding agents reduces to one of two behaviours.

Silent assumptions. It hits something ambiguous, picks an interpretation without saying so, and builds on it. You find out several steps later, when the wrong thing is already load-bearing.
Overbuilding. You ask for one change and get an abstraction layer, a config option and three files touched. Every addition is defensible in isolation and collectively it is a review burden you did not want.

Both come from the same root: no stated standard, so it invents one. The fix is to state the standard somewhere it will actually be read.

Fix one: a rules file

A rules file is a plain Markdown file in the project root that the agent reads at the start of every session. For Claude Code that file is CLAUDE.md.

It costs minutes and solves most of the problem, because the majority of repeated corrections are conventions rather than anything complicated. The principles worth encoding are consistent across almost every codebase:

01Think before acting. Ask when something is ambiguous rather than choosing silently.
02Keep it simple. Prefer the smallest thing that works over the most general.
03Make surgical edits. Change what the task needs and leave the rest alone.
04Work goal-first. Establish what success looks like, and write the test before the code.

Add your own specifics underneath: the stack, the conventions, the things you have corrected twice. That file is the difference between explaining yourself daily and explaining yourself once.

Fix two: a harness

A harness is a system installed into the agent that adds structure the model cannot simply talk its way past.

Hooks that run on your rules, so a check happens whether or not the model remembered to run it.
Verification steps, so work is reviewed from a fresh context rather than by the same reasoning that produced it.
Persistent memory, so what was learned in one session is available in the next.
A defined loop, typically plan, test, implement, review, verify, remember, improve, rather than whatever order the model chooses.

This is a much larger change and it is not the place to start. Install a harness when you are working on something long-running enough that consistency across sessions genuinely matters.

Which one you need

Start with the rules file. It takes ten minutes, and for most people it removes most of the friction, at which point the harness is unnecessary.

Move to a harness when you notice the rules file being ignored on long tasks, when you want verification you can rely on rather than hope for, or when losing context between sessions is costing real time.

The general principle holds well beyond coding agents, and it is the same one behind every automation worth building: a system you install once beats a process you re-explain every time.