How Do You Teach a Coding Agent Your Team's Rules?

The first few days with an AI coding agent feel like magic. You describe a screen and it appears; you paste an error and it gets fixed. Then week three arrives and a pattern shows up: the agent ignores the folder structure it respected yesterday, writes a second date formatting helper when one already exists, and quietly installs a library you asked it to avoid. You end up typing the same reminders into the chat box over and over.

The fix is not waiting for a smarter model. It is moving your rules out of the chat and into the repository. That is exactly why today's coding agents are built to read a project rules file first — AGENTS.md, CLAUDE.md, Cursor's rules directory, and similar conventions.

Why does the agent repeat the same mistakes?

Because most of the context disappears when the session ends. A human hire remembers week-one instructions two months later; an agent starts a brand new first day with every conversation. Yesterday's instruction simply does not exist today.

There is a second reason: the agent never reads your whole codebase. It picks a few files, reads them, and decides. If it never discovers that lib/format.ts already exists, writing a new helper is the most reasonable move available to it. This is an information problem, not a laziness problem — and information can be delivered as a file.

What should go into the rules file?

Start with the things that cause damage when unknown, not with your personal taste. Twenty lines of facts that are true only in this project beat an encyclopedia of general style advice. These six items remove most repeated mistakes.

• Commands to run and verify: dev server, tests, type check, build — as exact strings. Example: use pnpm only, never npm
• Structure rules: where new pages go, where shared components live, where API calls belong
• What already exists: point to the exact path for date/price formatting, auth checks, toast notifications, so nothing gets reinvented
• Hands-off zones: never run database migrations directly; propose changes to billing logic and wait for human approval; never print or commit .env values
• Domain facts: for example, "all price math lives in lib/pricing.ts only" or "store all amounts as integers in the smallest currency unit"
• Definition of done: type check and tests must pass, commit messages follow the given format

Where should the file live?

One rules file at the project root is the baseline. Tool names differ slightly — Claude Code looks for CLAUDE.md, Cursor uses a rules directory — so check your tool's docs once, then keep the real content in a single file and let the others point to it. If your repo has large frontend and backend folders, a short local rules file inside each one helps too.

Why do agents ignore the rules you wrote?

Usually because the file is too long, too abstract, or older than the code. A line like "we value clean code" changes no behavior. Run the file like this instead.

1. Start with something that fits on one screen. Long files get skimmed and priorities blur.
2. Write commands and paths, not adjectives. Replace "handle errors properly" with "route API failures through handleError in lib/api.ts".
3. The moment the agent breaks a rule, fix it in chat and add one line the same day. This retro habit is what makes the file good.
4. Enforce what truly matters with automation, not prose. Lint, type checks, tests, and CI let the agent see its own failure and fix it.
5. Delete unused lines every quarter. A rules file nobody prunes is a rules file nobody trusts.

A rules file is not documentation — it is the interface between your team and your agents. Even a solo builder gets a large return. When you export the source of a Senuru project and keep building with an agent, dropping one rules file into the first commit makes the next hundred requests far quieter.