How do you write a guide file your agent will follow?

Short, specific, and about decisions rather than description. What belongs in a guide file, what to leave out, and why most of them get ignored.

How do you write a guide file your coding agent will actually follow?

Keep it under about 150 lines, make every line a decision rather than a description, and point at real files instead of explaining them. The failure mode is not that agents ignore instructions, it is that most guide files are documentation, and documentation tells you what exists rather than what to do. A guide file is a map of choices: here is the one right way to do this thing, here is the file to copy, here is the rule that must never be broken.

Why most of them get ignored

Open a typical CLAUDE.md or AGENTS.md and it reads like a README: an overview of the project, a list of directories, a description of the stack, some setup commands.

None of that changes a single decision. The agent can already see the directory structure. It can read the dependency file. Telling it "we use a background job system" is not information; telling it "background work goes through the existing job class, never a thread, and here is the one to copy" is.

The test for every line: if the agent had not read this, would it have done something different? If not, cut the line. A 600-line guide file where 40 lines matter performs worse than a 40-line one, because the signal is diluted and the important rules are somewhere in the middle.

What actually belongs in it

The rule that must never be broken

Every codebase has one or two invariants where a violation is serious and silent. Put them first, in plain language, with the consequence stated.

In this codebase it is data separation:

Every model gets an account reference. Every query is scoped to the current account. Every controller checks permissions. Break this rule and one customer sees another's data.

That is short, it is unambiguous, and it names the cost. An agent reading it has no room to decide that this particular query is an exception.

The one obvious way to do each common thing

Not the options. The choice.

An agent that finds three plausible ways to add a feature will pick one, and it will not be the same one next time. Consistency across features is worth more than any individual choice being optimal, so make the choice once and write it down.

Pointers to real files

This is the highest-leverage thing in the whole document, and it is why a guide file can be short.

Instead of describing the shape of a feature over two pages, name the file that already has that shape:

The canonical example is the example slice: read app/models/project.rb, app/policies/project_policy.rb, app/controllers/projects_controller.rb, and its specs, then copy that shape.

Code is more precise than prose about code, it does not drift out of date, and the agent is better at reading it than at reading your description of it.

The definition of done

One command, and the statement that it must pass.

Verify your work: bin/check. This is the definition of done. It must be green before you are finished.

Without this an agent decides for itself when it has finished, and the only evidence available to it is that the code it wrote looks like code that works.

The traps that fail silently

The most valuable and most commonly missing section. Every mature codebase has a few landmines where the failure produces no error at all: a policy that blocks something with no message, a check that returns an empty result rather than raising, a configuration that has to be updated in two places.

An agent cannot discover these by reading, because there is nothing to read. Write them down, with the symptom:

The content security policy is enforced and it fails silently. Sending a user to an external host means adding that host to the policy. Miss it and the button does nothing: no exception, no message, nothing in the network tab.

That paragraph saves an hour of confused debugging every time it is read.

What to leave out

Anything the agent can see. Directory listings, dependency lists, the framework version.
General best practice. "Write tests", "use meaningful names", "handle errors". It knows. Repeating it costs attention and changes nothing.
History. Why you migrated away from a thing three years ago is interesting and irrelevant.
Aspirations. Rules you do not actually follow are worse than no rules, because they teach the agent that this document describes an imaginary codebase.

Write it for the failure modes you have seen

The best guide files are grown, not drafted.

Every time an agent does something you have to correct, ask whether it could have known. If it could have, and the guide file did not say so, add a line. If it could not have, that is a codebase problem and the fix is in the code.

After a few weeks this converges on a document that is short, specific to your project, and mostly composed of things that were genuinely surprising once.

The structure that works

What this project is, in two sentences.
The rule that must never be broken.
The shape of a feature, pointing at a real example.
Where the source of truth lives for routes, schema, and integrations.
How to run things, including the one verification command.
What is already built, so it does not get rebuilt.
The conventions worth stating, especially the silent traps.

That fits comfortably in 150 lines and does more than a document four times the length.

The part people miss

A guide file is only half of it. The other half is that the codebase has to actually be followable.

If your project does the same thing three different ways, no document will fix that, because the agent reads the code too and the code disagrees with itself. Write the rule, then make the codebase match it. The document describes the grain; it cannot create one.