Why Does My AI Coding Agent Ignore My Style Guide?

Your AI coding agent is not ignoring your style guide out of stubbornness. Five distinct, mechanical failures produce that behavior, and each one has its own fix. The guide might never be loaded into the agent's context at all, even though it sits right there in the repo. The agent might be choosing to pass tests over matching your conventions when the two pull in different directions. A save hook might be quietly rewriting what the agent actually produced. The guide itself might describe patterns your codebase abandoned months ago. Or the rule got read once, early in a long session, and buried under everything that happened since.

This is a code problem, not a prompting problem

If you landed here fighting a content or copywriting AI that will not hold a brand voice, you want a different piece. How to prompt AI to follow a style guide without repasting examples covers that: a general prompting technique for prose and writing style, keeping a compact style card as a standing instruction instead of re-pasting examples into every prompt.

This post is about a coding agent instead, something with file access working inside a real repository, running your test suite, reading config files like CLAUDE.md or .cursorrules, producing diffs you review. The failures below are specific to that setup. Why your AI coding agent keeps ignoring instructions covers the broader pattern of an agent dropping any kind of instruction. This one narrows to style guides specifically, and the causes below are the ones unique to writing actual code inside a real project.

Check this first: does the agent ever read the file

Start here. It is the most common cause and the easiest to rule out. Plenty of teams write a STYLE.md, a CONTRIBUTING.md, or a docs/conventions.md, commit it, and never tell the agent it exists. The file is in the repo. It has never been in the agent's context window.

Most coding agents do not read every file in a project by default. They read what you point them at, plus whatever instructions file their tool auto-loads: a CLAUDE.md, an AGENTS.md, a .cursorrules file. A style guide that none of those reference gets opened only if some other task happens to touch it.

The fix is a one-line pointer inside whichever file your agent actually loads automatically.

## Code style
Read STYLE.md before writing or editing any file in this repo.
It documents conventions for naming, error handling, and module
structure. Treat it as binding, not optional.

Then confirm it worked. Open a fresh session and ask the agent to summarize your style guide before it touches any code. If it cannot, the pointer is missing, broken, or the file moved. Have not set up that file at all yet? How to write an AGENTS.md file agents actually follow covers what belongs in it.

It is choosing tests over your conventions

When a task has both a test suite and a style guide pulling in different directions, most agents bend on style before they bend on a failing test. That is not really a bug. A failing test is an objective, checkable failure. A style violation is a much fuzzier one. Given a choice between code that passes and code that matches your conventions, the agent ships the version that passes.

Your guide says use a Result type instead of throwing, but the fastest route to green tests is the try/catch the agent already knows works, so that is what you get. Your guide asks for dependency injection in a constructor, but a test written against direct instantiation makes DI the riskier change, so the agent routes around it.

You will see this most where the tests and the guide were written at different times and quietly disagree. Related: agents will also sometimes edit the test itself to make it pass rather than touch the code, a pattern when AI coding agents rewrite tests to pass covers in more depth.

The fix is to make the two documents agree instead of asking the agent to hold a contradiction in its head under pressure. Where a convention and a test genuinely conflict, decide which one wins and say so explicitly, in writing, rather than leaving the agent to guess which target matters more.

A formatter or autofix is rewriting what it wrote

Sometimes the agent gets it right, and something downstream quietly gets it wrong. A pre-commit hook, a format-on-save extension, or an autofix step in your build pipeline can rewrite the agent's output after the fact, and the diff you review afterward shows the mangled version with no record that anything happened in between.

This one is easy to misdiagnose because it looks exactly like the agent ignoring you. You open the diff, see code that violates the guide, and conclude the model did not follow instructions. What actually happened is the agent wrote compliant code, and a tool with a different or outdated config silently rewrote it on save.

Check this before blaming the agent: take its raw output, run it through your formatter by hand, then diff that against what actually landed in the file. If they differ, the formatter's config disagrees with your style guide, not the agent. Common culprits: a .prettierrc that predates a style change nobody updated everywhere, an editor extension formatting on save with different rules than CI uses, or an autofix step carried over from an older project template.

The fix is one source of truth. If a rule matters enough to be in the style guide, encode it in the formatter or linter config too, so there is exactly one definition of correct rather than two documents that can drift apart. Make an AI coding agent follow your code style goes further into building that kind of enforcement, and is the natural next read once you have ruled out the causes here.

The guide describes a codebase that no longer exists

Style guides rot faster than code, because nobody runs a test suite against prose. A guide written a year ago might still say use moment.js for dates after the codebase moved to date-fns, or specify a folder structure the last refactor abandoned.

An agent handed a stale guide and a current codebase has two disagreeing sources of truth open at once, and it tends to follow whichever is louder in context, usually the actual code it is looking at, not a document describing code that used to exist. That reads as the agent ignoring the guide. It is often the agent correctly noticing the guide is wrong.

There is no shortcut here. Read the guide against the current codebase and delete or update anything the code no longer does. Treat it like documentation that drifts, on a review cadence, not as something written once and considered finished. A guide untouched since before your last big refactor is a strong candidate for this exact problem.

It read the guide once, forty turns ago

Long agent sessions accumulate a lot of text: file contents, test output, your back and forth, prior edits. A style guide read at the start of a session competes for attention with everything that has happened since, and by turn forty of a feature build, that early instruction is one signal under a much larger stack of recent, task-relevant context.

This differs from the first cause above. Here the agent did read the guide, early, and its influence has simply faded relative to everything more recent. The pattern is usually visible: the first few files in a session match the guide closely, and compliance degrades the deeper into the session you go.

The fix is to stop relying on the guide staying salient from turn four. Where your tool supports a persistent instructions file included on every turn, use that instead of a document the agent opens once and moves past. For sessions that run long regardless, ask the agent to re-read the style guide before starting a new file, the same way you would re-orient a person coming back from a break.

Working out which cause you actually have

• Ask the agent to quote a rule from the guide. Cannot? The file is not loaded.

• Diff its raw output against your formatter's output. Differ? An autofix is the real author.

• See if the violation only shows up near a test the agent had to pass. If so, the two conflict.

• See if the pattern the guide describes still exists in the codebase. If not, the guide is stale.

• See if compliance is strong early in a session and weak late in it. That is attention drift.

Different tools handle persistent instructions and long sessions differently, which is worth knowing before you conclude a workflow itself is broken rather than misconfigured. AI coding tools walks through what to look for across the category.

FAQ

Why does my AI coding agent write code that doesn't match my style guide?

Usually one of five mechanical causes: the guide was never loaded into its context, it chose passing tests over matching conventions, a formatter or autofix rewrote its output after the fact, the guide describes patterns the codebase abandoned, or the rule was read once early in a long session and lost salience since.

Does putting a style guide in CLAUDE.md actually work?

It works far better than a standalone file the agent has no reason to open, since most tools auto-load that file every session. It still competes with everything else in context on long sessions, so pair it with re-reads on longer tasks rather than one mention treated as permanent.

Should I use a linter instead of a written style guide?

Use both, for different jobs. A linter enforces what is checkable and mechanical. A written guide covers judgment calls a linter cannot express, like which patterns are architectural rather than stylistic. Move anything checkable out of prose and into the linter.

Why does my agent follow the style guide at first and then drift?

Long sessions push earlier context toward the edge of what the model weighs heavily, even when it is technically still present. A rule read once at turn four has less pull by turn forty than a file the agent just opened. Re-reading the guide partway through long sessions counteracts this.

Can I just ask the AI coding agent why it didn't follow the style guide?

Yes, and it is a useful diagnostic step, but treat the answer as a hypothesis, not a verdict. Ask it to quote the rule it should have followed and describe how it would check its own compliance. If it cannot do either, you have found the actual cause.