How to Write Rules Files for AI Coding Agents

TL;DR

A rules file is a short contract between you and your AI coding agent. It tells the agent which commands to run, which patterns your project follows, and which mistakes it must never repeat. Setting one up takes about twenty minutes, and it pays off every single session afterward.

• AGENTS.md is the open standard that Codex, Cursor, Zed, and thousands of open source projects already use.
• Claude Code reads CLAUDE.md and can pull in AGENTS.md with a single import line.
• Cursor prefers its own .cursor/rules folder with frontmatter controlled activation.
• GitHub Copilot reads .github/copilot-instructions.md at the repository level.
• Good rules files hold commands, conventions, and guardrails. Bad ones hold essays nobody reads, least of all the agent.

The rest of this guide walks through what each tool expects, what actually belongs in the file, and the maintenance habit that keeps the whole thing from rotting.

What a Rules File Actually Does

An AI coding agent starts every task close to blind. It sees your prompt, whatever context the tool injects, and a token budget. Without a rules file, the agent reconstructs your project conventions from file names and guesswork each time. Sometimes it guesses right. Often it installs a package manager you abandoned two years ago or writes tests in a framework you removed last quarter.

The file fixes that by loading stable facts into the context window before work begins. Think of it as onboarding documentation written for a very fast new hire with perfect recall and zero intuition. The agent does not learn from it permanently. It re-reads it every session, which means the file works only while it stays accurate.

Also Read:

Spec-Driven Development With AI Agents: A Practical Guide

I noticed the difference most in boring places. Commit message style stopped drifting. The agent ran the exact test command instead of inventing a plausible one. Small stuff, but multiplied across dozens of interactions per day, it removes a constant tax on your attention.

The Four Formats Compared

The ecosystem has settled into one open standard plus three tool-specific formats. They overlap heavily, and knowing which tool reads which file saves you from maintaining duplicates that slowly drift apart.

Per the official site, more than 60,000 open source projects now ship an AGENTS.md file, which makes it the closest thing to a portable default. If your team mixes tools, start there. Claude Code does not read it natively, but its memory system supports imports, so one line inside CLAUDE.md pulls the whole standard file in, as documented in the Claude Code memory docs.

Cursor takes a different approach worth understanding. Its project rules live as individual .mdc files with frontmatter, so a rule can apply only to your tests folder or only to TypeScript files. That granularity beats one big file when different parts of your repo follow different conventions.

GitHub closes the loop with repository custom instructions, a single markdown file under .github that shapes Copilot coding agent behavior across the whole repo.

If you are still choosing tools rather than formats, the practical differences between agents themselves matter too. The comparisons of Claude Code vs Cursor vs GitHub Copilot and Aider vs Cline cover that side.

Also Read:

How to Audit Vibe Coded Python Codebases

What Belongs in the File

Every line costs context window space on every future session, so treat the file like a payload, not a wiki page. These five categories earn their tokens.

• Commands. The exact test command, lint command, build command, and dev server startup. Agents copy these verbatim instead of improvising.
• Conventions. Naming style, commit message format, branch naming, error handling patterns. Three lines here prevent fifty small corrections.
• Guardrails. Things the agent must never do. Never edit generated files. Never bump major versions. Never touch migration folders without asking.
• Environment quirks. The package manager actually in use, required environment variables, ports that must stay free, platform specific notes.
• Pointers. Where the real documentation lives, which folders are unstable, who owns what module.

What does not belong: project history, aspirational roadmaps, long architecture essays, and anything already obvious from the README. The agent reads the file fresh every time, so a rule that states the obvious burns tokens on every single interaction. I keep a hard limit of roughly one screen of content per file and move deeper material into linked documents the agent can open on demand.

Tone matters less than precision. Write “run pnpm test, never npm test” rather than “prefer pnpm for testing.” Directives survive paraphrasing; preferences dissolve.

Also Read:

Vibe Coding Workflow Guide for Solo Developers: Ship Apps Faster

Length deserves its own budget. A rules file rides along in every prompt the agent processes, so forty lines cost a little on every call while four hundred lines start crowding out the actual code. When something feels too long to keep, it usually is. Move reference material into docs folders and let the rules file point at it instead of quoting it.

A Skeleton That Works

You do not need a template ceremony. This shape covers ninety percent of projects:

Project Rules

COMMANDS
  tests: pnpm test
  single file: pnpm test path/to/file
  lint: pnpm lint
  dev server: pnpm dev, port 3000

CONVENTIONS
  TypeScript strict mode everywhere
  commits follow Conventional Commits
  components in src/components, one per folder

NEVER DO THIS
  edit files under src/generated
  add new dependencies without asking
  use default exports for components

WHERE THINGS LIVE
  API contracts: openapi.yaml
  deployment docs: docs/deploy.md

Notice what the skeleton avoids. No mission statement, no explanation of why the rules exist, no restating things the linter already enforces. The agent needs instructions, not philosophy.

Mistakes That Quietly Waste Context

After reviewing plenty of repos with agents wired in, the same failure patterns show up again and again.

• The novel. A four hundred line rules file nobody updates. Past a certain length, later instructions contradict earlier ones and the agent picks whichever is closer to the current task.
• The duplicate. CLAUDE.md, AGENTS.md, and cursor rules all maintained by hand with slightly different content. Six weeks later they disagree and the agent behaves differently depending on which tool opened the repo.
• The stale command. The file says npm but the lockfile says pnpm. The agent trusts the rules file, fails, then wastes turns recovering.
• Vague vibes. “Write clean code” and “follow best practices” do nothing. Name the pattern, name the file type, name the exception.
• Buried exceptions. One legacy folder with different conventions gets one line at the bottom, or worse, lives only in someone’s head.

All five have the same root cause: treating the rules file as documentation instead of configuration. Documentation informs humans eventually. Configuration runs on every request, so it deserves the same review discipline as your CI pipeline.

Keeping Rules Alive Across Tools

Multi tool teams need a sync strategy, and there are two reliable ones. The first is the symlink: make CLAUDE.md point at AGENTS.md so both names resolve to identical bytes. The second is the import: Claude Code supports @file references inside CLAUDE.md, so a one line import keeps the open standard file as the single source of truth while staying compatible with tools that only know the native name.

Nested files handle monorepos. Place a root AGENTS.md for shared rules, then drop smaller files into package folders for local overrides. Most implementations give precedence to the nearest file, which matches how developers already think about scoped configuration.

Review cadence matters as much as structure. When I finish a session where the agent made the same mistake twice, that mistake becomes a rule line before I commit anything else. Rules earned from real failures beat any boilerplate list copied from a template. Personal rules deserve a spot too: Claude Code reads a user level CLAUDE.md that applies to every project, which is the right home for editor agnostic preferences like response style or commit tone.

For a broader workflow view of running agents day to day, see the guide to spec driven development with AI agents, and if your setup involves external tools, the Model Context Protocol setup guide covers the other half of agent context.

Final Verdict

Write an AGENTS.md today, wire it into whichever native file your main agent expects, and keep it under one screen. Put exact commands in, keep opinions out, and promote every repeated correction into a permanent rule. The file is cheap to create, nearly free to maintain, and it compounds: every session starts smarter than the last.

Your future sessions are already being shaped by whatever instructions exist right now, even if that is nothing. Twenty minutes of setup buys you an agent that stops asking, stops guessing, and starts shipping the way your repo actually works. Try it on your next task and watch how few corrections you need by the end of the week.