Plenty of teams have a CLAUDE.md or .cursorrules file sitting in their repo root that nobody has touched since the day they created it, and it shows in the output. Writing the file isn't the hard part. Writing one specific enough to change behavior, without becoming so long it gets skimmed, is the actual skill.
Step 1: Audit What You're Actually Repeating in Chat
Before writing anything, spend a week paying attention to what you type into the assistant chat over and over. "Use our ApiError class, not bare exceptions." "We're on Vitest, not Jest." "Don't touch the billing module without asking." Whatever you find yourself typing more than twice belongs in the file. Everything else is probably noise.
This audit step matters because it grounds the file in real friction instead of a generic checklist copied from someone else's repo. A file built from your team's actual repeated corrections is shorter and more effective than one built from guessing what might be useful.
Step 2: Separate Durable Rules From Temporary Ones
"We use PostgreSQL" is a durable rule. "We're mid-migration off the old billing service, don't extend it" is temporary and needs a review date. Mixing the two without marking which is which means the temporary rules quietly outlive their relevance and start confusing new team members and assistant sessions alike, sometimes for years after the migration finished.
A simple convention works well here: put temporary rules in their own section with a target removal date in a comment. Review that section on a schedule, even a rough quarterly one, and delete what's no longer true.
Step 3: Point at Examples Instead of Describing Patterns Abstractly
"Follow the pattern in handlers/users.py for new API handlers" is more effective than three paragraphs describing what a good handler looks like. Assistants read code better than they read abstract prose about code. If your codebase already has a clean example of the pattern you want repeated, cite the file path directly.
This only works if the example file is actually current. An outdated example is worse than no example, since it actively points the assistant toward a pattern you've since moved away from.
Step 4: Add an Explicit "Ask First" List
Name the modules, files, or operations that need a human in the loop before the assistant touches them: schema migrations, auth logic, anything touching payment processing. This is the single highest-value line item for teams worried about AI-generated changes causing real damage, and it's often missing entirely from instructions files that otherwise look thorough.
This list matters more than almost anything else in the file precisely because the failure mode it prevents is asymmetric. A wrong guess about which HTTP client to use costs a few minutes in review. A wrong guess about a database migration or an authorization check can cost considerably more, and an assistant with no signal that a file is dangerous treats it with exactly the same confidence it applies to a throwaway script.
Step 4b: Test the Rules Against a Real Task
Before considering the file finished, run one real task through it and check whether the assistant actually followed the rules you wrote. This sounds obvious, but it's the step most teams skip, and it's the fastest way to find out that a rule you thought was clear was actually ambiguous. If the assistant still reaches for the wrong library after you've told it not to, the instruction probably needs a concrete file reference rather than a general statement, since assistants tend to follow specific pointers to real code more reliably than abstract descriptions of intent.
Step 5: Keep It Under a Page and Revisit It in Pull Requests
A 2,000-word instructions file gets skimmed by humans and effectively deprioritized by the assistant's limited attention to any single piece of context. Aim for something a new hire could read in two minutes. When a convention changes, update the file in the same pull request that changes the code, not as a separate cleanup task that never happens.
"The instructions files that actually work are the boring ones, five or six specific rules instead of an essay about engineering philosophy." - Dennis Traina, founder of 137Foundry
Step 6: Treat It Like Any Other Documentation Debt
Instructions files rot the same way READMEs rot: quietly, until someone notices the assistant is confidently doing something the team stopped doing months ago. Assign it an owner, even an informal one, and check it during any sprint where the team makes a significant architectural decision.
Version control history is your friend here. If you're not sure whether a rule is still accurate, git log on the file itself usually tells you when it was last touched and by whom, which is a fast way to spot the stale sections before they cause a confusing pull request.
Where This Fits With the Rest of Your Tooling
An instructions file isn't a replacement for the mechanical tooling your team should already have in place. ESLint and Prettier handle formatting and a class of common mistakes automatically, which frees the instructions file to focus on the judgment calls a linter can't make: which of two valid architectural patterns your team has actually settled on, and which parts of the codebase need extra caution.
Whichever tool your team standardizes on, whether that's Cursor or something else entirely, the instructions file format has converged enough across the ecosystem that the same document usually works with minor adjustments regardless of which assistant reads it. That portability is one more reason the file is worth getting right the first time instead of treating it as tool-specific throwaway configuration.
A Realistic Timeline
None of this needs to happen in one sitting. A reasonable rollout looks like a rough first draft in an afternoon, based on whatever repeated corrections you can recall off the top of your head, followed by two or three weeks of quietly noting new corrections as they come up in real sessions. At that point, a short revision pass usually captures the rules that actually matter, and the file is in good enough shape to stop actively iterating on and start just maintaining.
Trying to get it perfect on the first attempt tends to backfire, producing either an overlong document nobody reads or a set of rules based on guesses about what might matter rather than what actually does. The iterative version, grounded in real repeated friction, consistently ends up shorter, more specific, and more likely to actually change the assistant's output.
When to Consider It Done
There's no permanent finished state for a file like this, but there is a reasonable point to stop actively iterating and shift to maintenance mode: when new corrections in chat sessions become rare rather than routine. At that point the file has captured most of what the team actually needed documented, and further additions are more likely to be edge cases that don't generalize well than genuinely useful rules. Keep the maintenance habit, the update-it-in-the-same-pull-request discipline, but stop treating the file as a work in progress once it's earned that stability.
We cover the broader codebase structure that makes an instructions file effective, not just present, in our guide to structuring a codebase so AI coding assistants stop guessing.
The development team at 137Foundry has written and maintained these files across a range of client codebases, and the pattern that works is consistently the same: short, specific, and updated in the same breath as the code it describes.
Top comments (0)