Why AI coding agents drift from a small team's conventions without shared written rules, why the rules should update themselves, and how to set them up.
On our five-person team, AI coding help was ad hoc. Every engineer prompted the agent differently, and there were no shared rules for how our codebase works. What the agent knew about our conventions depended on who was asking and what they remembered to tell it.
Without shared rules, an agent’s mistakes look much the same on every team. The code runs and still doesn’t fit. It calls the backend in a new way, builds a component the library already has, or defines a type that already exists. Review catches it, and on a small team the reviewer is usually the person who could have written it right the first time.
The agent isn’t inconsistent. Its inputs are.
An AI coding agent such as Claude Code reads your files, edits them and runs commands in your terminal. It knows a great deal about code in general and nothing about your code in particular. Each session starts with a fresh context window, the text the model can see at one time. Everything it knows about your conventions comes from what’s in front of it in that session: the files it opens and whatever the person types.
On our team, the context that mattered lived in people’s heads. Each engineer gave the agent their own version of it, and every new session forgot all of them. So the same kind of task could get a different answer depending on who asked. That isn’t a flaw in the model. It’s what happens when every session starts from a different, partial picture.
It matters more the more you use an agent. Of my own commits to the platform, 64% are co-written with one. At that share, whatever the agent assumes quietly becomes how the codebase is written, unless the real conventions are somewhere it can read them.
Write it down once, where every agent reads it
The fix is to move that context out of heads and into files, so every engineer’s agent starts each session from the same place. For our frontend I built this as an agent kit: a shared set of rules and skills. Claude Code has a place for each.
Rules are standing instructions. A CLAUDE.md file at the root of the repo loads at the start of every session. When it grows, you can split it into topic files in a .claude/rules/ folder. A rule file without a paths field loads every session. With one, it loads only when the agent works on matching files, so instructions about components stay out of the way while it writes a database query.
Skills are instructions for one kind of task. A skill is a folder with a SKILL.md file and any reference files it needs. Claude sees only each skill’s short description up front, and loads the rest when a task matches or when you call it with /skill-name. That makes skills the right home for long reference material that matters only some of the time.
Neither is enforced. Claude Code treats rules and skills as context, and its docs say specific, concise instructions are followed more consistently. If something must never happen, use a hook, a script Claude Code runs at set points such as before a tool call. And keep code review.
Rules go stale, so let them update themselves
Written rules have a weakness. They describe the codebase on the day you wrote them. Then a new pattern lands, an old helper goes away, someone finds a better way. Rules that drift are worse than no rules, because the agent follows them confidently.
The corrections that would keep them current usually happen in chat. Someone tells the agent “we don’t do it that way here”, the agent fixes the code, and the lesson ends when the session does. The next session, and every other engineer’s agent, is free to make the same mistake.
So I added a rule that tells the agent to update its own rules as it learns. A correction then lands in a file, not just a conversation. The next session starts with it, and so does everyone else’s.
Claude Code also keeps notes of its own, called auto memory. That helps one person, but auto memory stays on the machine it was written on. A rule in the repo is shared with the whole team and shows up in a diff like any other change, so a person can check it before it spreads.
A made-up example of such a rule, not our wording:
# Keeping these rules current
- If you learn how this codebase does something and no rule says so, add it to the rule file for that topic.
- If a rule is wrong or out of date, fix it in the same change.
- Keep each file short and on one topic.How to set it up
- List the questions a new engineer asks in their first week. How does the frontend call the backend? Where does new code go? What does the component library already have? Which data types exist? What do the product’s own terms mean? How should a screen look? Those are the areas our kit covers. Each answer becomes a rule or a skill.
- Use rules for what applies everywhere, and scope them to paths where you can. Use skills for tasks that come up some of the time.
- Keep one topic per file, and keep files short. Claude Code’s docs suggest under 200 lines per
CLAUDE.md, because longer files take more context and are followed less reliably. - Add the rule that updates the rules.
- Commit the kit to the repo, so every engineer’s agent loads the same files.
- Review rule edits like code. A wrong rule reaches every session that loads it.
- Keep tests and review. Tests let an agent check its own work before a person sees it. Review is where a person decides whether the work is right.
What it changed
Every agent on the team now works from the same shared rules and skills, and those rules keep what the agent learns instead of losing it when a chat closes.
The team ships around 1.7 production releases a day, with four code owners, the people who approve changes, reviewing each other. The kit doesn’t get the credit for that pace on its own, and it didn’t make review optional. With an agent writing much of the code, review becomes most of the job. Shared rules are meant to change what review spends its time on: whether a change is right, rather than conventions the agent should have known.
The lesson
An agent only knows what you wrote down. Write it once, where every agent reads it, and let the agent keep it current.
The same habit runs through the rest of our tooling: design notes for decisions, and a daily AI triage run for the bug board. The full picture is in the team case study.
Quick answers
- Why does an AI coding agent ignore my codebase's conventions?
- Usually because it never saw them. Each session starts with a fresh context, so conventions that live in people's heads or in old chats have to be written into files the agent loads.
- What are skills in Claude Code?
- A skill is a folder with a SKILL.md file of instructions for one kind of task. Claude Code sees only its short description until a task needs it, then loads the full instructions. You can also run one yourself with /skill-name.
- What is the difference between CLAUDE.md and .claude/rules in Claude Code?
- CLAUDE.md is one instruction file that loads at the start of every session. The .claude/rules/ folder splits instructions into topic files, and a rule with a paths field loads only when Claude works on matching files.
- Does Claude Code always follow CLAUDE.md and its rules?
- No. Claude Code treats them as context, not enforced configuration. Short, specific instructions are followed more consistently, and a hook is the way to block an action outright.
- Can an AI coding agent update its own instructions?
- Yes. Rules and skills are ordinary files in the repo, so a rule can tell the agent to edit them when it learns something. The change loads in the next session and can be reviewed like any other change.