Every team using an AI coding assistant eventually writes some version of a project instructions file, a CLAUDE.md, an AGENTS.md, a .cursorrules. And within a few weeks, most of those files quietly stop working. The assistant starts ignoring the formatting rule on line 40, reintroduces the pattern the file explicitly banned, or writes tests in a style the file never mentioned because the actual rule got buried in paragraph six of a wall of text nobody, human or model, reads carefully twice.
Photo by Vitaly Gariev on Pexels
This isn't a sign the concept is broken. It's a sign the file was written like documentation for humans, who skim and infer intent, instead of like an instruction set for a system that treats every line as equally binding whether or not it's actually important. Getting this right changes an assistant from a fast but sloppy junior contributor into something closer to a teammate who's actually read the codebase's house rules.
Why these files exist in the first place
Anthropic's own documentation on Claude Code describes this class of file as the mechanism for supplying persistent project context automatically, and the pattern has converged across most major coding assistants for the same underlying reason: an AI coding assistant has no persistent memory of your codebase between sessions unless something feeds it that context every time. It doesn't know your team prefers composition over inheritance, that the payments module has a specific reason for its odd error handling, or that a particular directory is legacy code nobody wants touched. A project instructions file is the mechanism for supplying that context automatically, every session, without a human re-explaining it each time.
Without one, the assistant falls back on generic best practices learned from its training data, which are reasonable defaults but frequently wrong for your specific codebase's actual conventions, dependencies, and constraints.
Specificity beats general good advice
The single biggest difference between an instructions file that works and one that gets ignored is specificity. "Write clean, maintainable code" is advice an assistant already believes it's following, so it changes nothing. "Never introduce a new state management library, this project uses Zustand exclusively" is a concrete, checkable rule that directly overrides a default the assistant would otherwise reach for.
Every rule in the file should be specific enough that a reasonable person could look at a piece of generated code and definitively say whether it followed the rule or not. Vague aspirational language reads fine to a human skimming the file but gives a model nothing concrete to actually apply.
Put the highest-stakes rules first, not buried
Assistants weight instructions unevenly depending on where they appear and how the file is structured, and extremely long files dilute the signal on any individual rule. If "never modify the authentication middleware without explicit approval" is rule 47 in a 60-item list, it competes for attention with 46 lower-stakes items about code formatting.
Structure the file so the rules with real consequences, security boundaries, data-destructive operations, billing logic, appear early and are visually distinct from routine style preferences, rather than treated as just more items in one long undifferentiated list.
Encode the conventions the assistant would otherwise guess wrong
The most valuable content in an instructions file isn't generic best practice, it's the specific decisions your team made that aren't discoverable by reading the code casually. Why does this project use a custom validation layer instead of a popular library. Why is there a seemingly redundant caching step in one specific service. Which directories are actively maintained versus legacy code frozen in place.
An assistant reading only the code will often "fix" these decisions by reverting them to a more conventional pattern, not out of malice but because the reasoning behind the unusual choice was never written down anywhere it could see it.
Give it explicit boundaries, not just style guidance
Boundaries matter more than style rules because getting a style rule wrong costs a review comment, while getting a boundary wrong can cost a production incident. OWASP's guidance on secure coding practices is a useful reference for which categories of change, authentication, session handling, data access controls, warrant this kind of explicit stop-and-ask treatment regardless of which assistant or team is involved. Explicitly naming files, directories, or operations that require human approval before touching, database migrations, authentication code, billing integrations, payment webhooks, gives the assistant a clear line it shouldn't cross on its own rather than leaving that judgment implicit.
This is also where a lot of teams get burned by skipping the step entirely: an assistant asked to "fix the failing test" has no way to know that the fix touches a migration file with irreversible production consequences unless the instructions file has told it, in advance, that migrations are a stop-and-ask zone.
Keep it living, not a one-time artifact
A project instructions file that was accurate six months ago and hasn't been touched since is often worse than no file at all, because it actively misdirects the assistant toward conventions the codebase has since moved away from. Treat it the way you'd treat a README that documents actual current setup steps: update it in the same pull request that changes the convention it describes.
Some teams build a habit of reviewing the file quarterly, or whenever a new significant pattern gets adopted project-wide, specifically to catch this kind of drift before it compounds into a file that's actively wrong about half its own claims. Google's own engineering practices documentation takes a similar approach to code review standards generally, treating the written guidance as a living document tied to actual review outcomes rather than a static policy nobody revisits.
Common failure modes worth checking your own file against
A few patterns show up repeatedly in instructions files that don't work. Files that are too long, burying critical rules in low-stakes formatting preferences. Files that contradict themselves because they were edited by different people at different times without anyone reconciling the additions. Files written in vague, aspirational language rather than concrete, checkable rules. And files that were never actually tested, written once and assumed to work rather than verified against real assistant output.
If you haven't looked at your own file recently, a useful exercise is picking three rules at random and asking whether a specific piece of code the assistant generated last week actually followed each one. If you can't answer confidently, the rule probably isn't specific enough to be enforceable. The Model Context Protocol specification is worth a skim too if your team is connecting an assistant to external tools alongside the instructions file, since it shapes what context and actions the assistant can actually see and touch beyond the file itself.
"The instructions files that actually hold up are the ones written like a spec, not like a wiki page. Specific, testable, and edited the moment the codebase's real conventions change." - Dennis Traina, founder of 137Foundry
Testing whether the file is actually working
The only reliable way to know if an instructions file works is to check the assistant's actual output against it, not to trust that writing the rule down was sufficient. Pick a handful of representative tasks, a new component, a bug fix in a sensitive area, a test addition, and review whether the generated code follows the file's specific rules, not just whether it's generally reasonable code.
If the assistant consistently misses a particular rule, the fix is almost always to make that rule more specific and move it earlier in the file, rather than repeating the same vague version more emphatically. Models respond to concreteness and placement far more reliably than to tone or repetition.
Where a written file stops being enough
Even a well-written instructions file has limits. It can't enforce boundaries the way a permissions system or a CI check can, and a team relying purely on the file to keep an assistant away from billing or auth code is trusting a suggestion, not a guardrail. Pairing the instructions file with actual technical enforcement, branch protections, required review on sensitive paths, scoped credentials for anything automated, closes the gap between what the file asks for and what the system actually allows.
Enforcement mechanisms like GitHub's CODEOWNERS and branch protection features exist for exactly this reason, requiring human sign-off on sensitive paths regardless of who or what opened the change. This is the kind of setup 137Foundry's AI automation work covers regularly: not just writing the instructions file itself, but building the surrounding guardrails so a good instructions file is backed by something more durable than an assistant choosing to comply. If you're evaluating how AI coding assistants fit into your own team's workflow, the broader services overview covers where this fits alongside the rest of an engineering practice, and the About page has more on how the team approaches these projects.
Who should actually own the file
One more thing worth deciding explicitly: who's responsible for keeping the instructions file current. Left ownerless, it tends to get one enthusiastic initial draft and then years of neglect while the codebase moves on around it. Teams that keep these files useful over time usually assign it to whoever owns architecture decisions broadly, the same person or group already responsible for noticing when a convention has shifted, rather than treating it as a one-off onboarding task assigned to whoever's free that week.
Making updates to the file part of the normal pull request process for any change that alters a convention, rather than a separate maintenance chore that competes with actual feature work for attention, is what keeps most of these files from going stale within the first quarter after they're written.
Start small and expand deliberately
Teams writing their first instructions file often try to capture everything at once, every style preference, every architectural decision, every edge case anyone can think of, and end up with exactly the bloated, low-signal file described earlier. A better starting point is a short file covering the handful of rules that would prevent the most common and costly mistakes an assistant has actually made in your codebase so far, then expanding it deliberately as new patterns emerge worth codifying.
This also makes it much easier to verify the file is working, since a shorter list of concrete rules is far easier to check against actual generated output than an exhaustive one nobody has the patience to audit line by line.
A good project instructions file is closer to a spec than a memo. Specific, prioritized by actual stakes, and maintained with the same discipline as the code it's meant to guide, and it's worth treating it that way from the first draft rather than writing it once and hoping it holds.
