The first real fight I had with a teammate over AI tooling was not about which model to use. It was about which config file we were supposed to be editing.
We had a CLAUDE.md at the repo root, written by me back in February. We had a .cursorrules file from the engineer who joined in March, who only used Cursor and refused to even open Claude Code. We had a copilot-instructions.md under .github/, dropped in by whoever turned on Copilot for the org. And we had a half-empty AGENTS.md that someone had heard about at a conference. Four files. Four different versions of the truth. Three subtly different opinions on how to write a database migration. Zero shared understanding.
The bug that triggered the argument was small. A junior engineer asked Cursor to write a Postgres migration. Cursor produced something fine by its own rules. The PR review pointed out that "our convention is to always wrap migrations in a transaction and write a rollback." Junior engineer pointed at .cursorrules. Nothing about transactions. We checked CLAUDE.md. It had the rule. We checked copilot-instructions.md. Different wording, same intent. We checked AGENTS.md. Empty.
Nobody had written the rule into Cursor's file because nobody used Cursor when the rule was added. The model did exactly what the file told it to. The file was just wrong by neglect.
This is the new shape of team coding standards in 2026. The standards exist. They just live in five places, in five formats, with five different update schedules. If you are leading any team larger than two people that uses more than one AI coding tool, this post is for you. I am going to walk through what each config file actually does, where the meaningful differences are, and the layout that finally got my team off the Monday argument loop.
The Four Files That Run Your Codebase Now
Before we compare anything, here is the lineup. There are more than four config files in the wild, but these are the ones you actually need to care about.
CLAUDE.md is the Claude Code config. It lives at the root of your repo (or in ~/.claude/CLAUDE.md for personal global rules). Claude Code reads it on every session start and treats the contents as a permanent system prompt. It supports @path/to/file imports up to five levels deep, which means you can split your standards into multiple files and reference them. It also supports auto-memory, where Claude writes notes back into a memory directory based on your corrections and preferences during a session.
.cursorrules (or the newer .cursor/rules/*.mdc directory layout) is the Cursor config. The legacy .cursorrules is a single Markdown file. The new directory format lets you have multiple rules with frontmatter that controls when they apply. The frontmatter supports globs, alwaysApply, and description fields, so you can have a rule that only fires for .tsx files, or only fires when the user asks about migrations. This is genuinely useful and an underused feature on most teams I have seen.
copilot-instructions.md is the GitHub Copilot config. It lives at .github/copilot-instructions.md and applies to Copilot Chat, code review, and the autonomous coding agent. Copilot also supports path-specific instructions under .github/instructions/*.instructions.md with YAML frontmatter that uses glob patterns. The path-specific files combine with the root file when both match, so a TypeScript rule plus a general rule both apply to a .ts file.
AGENTS.md is the closest the ecosystem has to a neutral standard. It started as the OpenAI Codex CLI config, then got adopted by Cursor, Aider, and a handful of smaller tools as a fallback. It supports nothing fancy. No imports, no globs, no path-specific overrides. Just plain Markdown that any compliant agent will read. The widest cross-tool support means it is also the lowest common denominator.
There are others. GEMINI.md for Google Gemini CLI. .windsurfrules for Windsurf. WARP.md for Warp's agent mode. The pattern is identical to the four above. Pick the ones your team actually uses and ignore the rest.
What Each File Is Actually Good At
Treating these files as interchangeable is the first mistake most teams make. They are not. The features they support are different, and the optimal content for each one is different. Here is what I have ended up using each for.
CLAUDE.md is the longest-lived, most opinionated file in the system. Claude Code's harness is the most autonomous of the three big tools, which means the rules you write get the most leverage. A single sentence like "always run typecheck before declaring work complete" actually changes behavior across a 40-step agent session. The @import feature lets you split standards into topical files (@.claude/standards/api.md, @.claude/standards/testing.md, @.claude/standards/database.md) and keep the root file as a table of contents. That is how I structure mine now. The auto-memory layer also makes CLAUDE.md grow over time without you babysitting it, which is either a feature or a footgun depending on how much you trust the model's judgment about what to remember. I cover the broader Claude Code workflow in the agentic coding 2026 piece; the short version is that the leverage on a long-running agent is high enough that CLAUDE.md is worth the most editorial care.
Cursor rules are best treated as path-specific overrides. The new .cursor/rules/*.mdc format with globs is the killer feature. I have a rule that fires only for *.test.ts files and tells the agent to never use mocks for the database layer. I have another that fires only for *.tsx files and tells the agent the design tokens we use. The base file under .cursor/rules/ stays small and general. The path-specific files do the heavy lifting. If you write a 600-line .cursorrules at the root, you are using the tool wrong. Split it.
Copilot instructions are best for repo-wide truths. Copilot's strength is breadth: every developer with the extension reads it whether they like it or not. Its weakness is that the instructions are short, get truncated more aggressively than CLAUDE.md, and are mostly used for Copilot Chat and the PR-review agent rather than for long autonomous sessions. The right content for copilot-instructions.md is the high-signal rules that you want every developer's autocomplete and PR-review agent to enforce. Stack choices. Banned patterns. The five things that should never make it into a PR. Not a 200-line essay on architecture.
AGENTS.md is the politeness file. Its job is to exist for the tools that do not read your other files. Treat it as a redirect, not the source of truth. A typical AGENTS.md for my projects is twenty lines: "See CLAUDE.md for full standards. The most important ones are: A, B, C. Run bun test before claiming work is done." That is enough for an unfamiliar agent to do something reasonable without needing the full CLAUDE.md context.
The mistake teams make is treating all four as parallel. They are not. There is a hierarchy.
The Layout That Finally Worked
After three months of fighting with this, here is the layout my team settled on. It has stayed stable for the last six months, which is the longest any AI tooling decision has lasted in our org.
We have one source of truth: .claude/standards/. Inside it, one file per topic.
.claude/standards/
api.md
database.md
testing.md
frontend.md
observability.md
security.md
Each file is short. 100 to 200 lines. Each one is reviewed by the team lead for that area. Each one has the same structure: a one-paragraph statement of intent, then a list of rules with reasons, then a list of bans with reasons. The structure matters because it forces the writer to justify the rule. A rule with no reason gets removed.
The root CLAUDE.md is a 30-line file that imports the topical files and adds the cross-cutting rules that do not belong to any single domain.
# Project Standards
This project uses Bun, Postgres, Astro, Vercel.
## Topical standards
@.claude/standards/api.md
@.claude/standards/database.md
@.claude/standards/testing.md
@.claude/standards/frontend.md
@.claude/standards/observability.md
@.claude/standards/security.md
## Cross-cutting rules
- Never run destructive SQL without showing the rows first.
- Always run `bun test` and `bun run typecheck` before declaring work complete.
- No em dashes in any file we ship. Ever.
## Workflow
- We use trunk-based development. Feature branches are short-lived.
- PRs are reviewed by the area owner. Big changes get a Linear ticket first.
That is the whole root file. Everything else gets pulled in by import.
The AGENTS.md is fifteen lines and points at the same standards. It is a redirect with a fallback for tools that cannot import.
# Agent Standards
See `.claude/standards/` for full rules. If you cannot read those files,
the four rules you must follow are:
1. Use Bun, not npm or yarn.
2. Never write to the database without showing the rows first.
3. Always run `bun test` and `bun run typecheck` after changes.
4. Follow the existing code style and import order.
Full standards: github.com/our-org/our-repo/tree/main/.claude/standards
The copilot-instructions.md mirrors the same content but compressed for Copilot's shorter context window. We auto-generate it from the topical files using a small script that runs on pre-commit. That removes the drift problem at the cost of accepting that Copilot reads a summary, not the full standards.
The Cursor rules live in .cursor/rules/ and are tied to globs. The database.mdc rule has globs: ["**/migrations/**", "**/db/**"]. The testing.mdc rule has globs: ["**/*.test.ts", "**/*.spec.ts"]. The frontend.mdc rule has globs: ["**/*.tsx", "**/*.css"]. Each one is the relevant content from the corresponding .claude/standards/ file. We auto-generate these too, from the same source.
The script that does the generation is fifty lines of TypeScript. It reads the topical files, applies a compressor that strips reason-paragraphs and keeps only the rule lines for the shorter formats, and writes the four output files. Pre-commit runs it. The PR review checks that the generated files are in sync. If you edit a generated file by hand, the hook complains.
The point is not that you need exactly this layout. The point is that you need one source of truth and a way to project it into the formats every tool wants to read. Without that, you are running four parallel codebases of rules and one of them will silently drift.
The Things That Actually Cause Drift
Once you understand the file layout, the next problem is keeping the content in sync over time. This is where most teams fail, and the failure mode is always the same.
A new rule gets added to one file and not the others. A senior engineer adds a rule about transaction wrappers to CLAUDE.md after a bad incident. Six months later a junior engineer using Cursor produces the exact code the rule was meant to prevent, because Cursor never saw the rule. The fix is the projection layer above. One source, many outputs. Adding a rule means adding it in one place and letting the script handle the rest.
Old rules are never removed. AI coding standards files have a tendency to grow forever. A rule from 2024 about a deprecated library is still in the file in 2026. The model dutifully follows it. The newer engineer wonders why their code keeps getting rewritten to use Lodash. The fix is quarterly review. One thirty-minute meeting per quarter, the team lead walks down each topical file, and any rule that nobody can defend gets cut. We delete more than we add. The file shrinks roughly 20% per year. That is healthy.
The reasons get lost. A rule that exists without a reason is impossible to refactor. The team cannot evaluate whether the rule still applies, because the original context is gone. The fix is to require a reason for every rule. We use the same structure as my feedback memories in Claude Code: the rule itself, then Why: and How to apply: lines. The reason is mandatory. If you cannot articulate the reason, the rule does not belong in the file.
The standards contradict the codebase. A rule says "always use Tanstack Query for client-side data fetching." The codebase has 40 SWR calls because it predates the rule. The model sees both and picks one at random. The fix is to either migrate the codebase or update the rule. There is no third option. A standard that contradicts reality is worse than no standard at all, because it teaches the model to ignore standards in general.
Personal preferences sneak into the team file. This one is the hardest. An engineer who hates trailing commas adds "no trailing commas in object literals" to CLAUDE.md. The team has never discussed this. Six months later the codebase is half-formatted that way and the linter has been disabled to accommodate it. The fix is process. New rules go to PR. The team lead reviews. Rules with no team-wide consensus get rejected. The standards file is a team contract, not a personal scratchpad.
The pattern across all four is the same. Drift is a process problem, not a tooling problem. The tools project the rules. The team writes them. If the team is sloppy, no tool will save you.
The Difference Between a Rule and a Skill
There is a deeper distinction that most teams miss, and it is the one I would write into the back of every developer's hand if I could.
A rule is a constraint. It tells the model what not to do, or what it must do in a specific situation. "Never use mocks in integration tests." "Always wrap migrations in transactions." "Use Bun, not npm." Rules are short. Rules are imperative. Rules belong in CLAUDE.md and friends.
A skill is a procedure. It tells the model how to do a specific task well. "How to add a new API endpoint to this codebase." "How to review a PR for security issues." "How to migrate a table without downtime." Skills are long. Skills are explanatory. Skills belong in the Claude Code plugin marketplace, in SKILL.md files under .claude/skills/, or in the equivalent system for whichever tool you use.
The mistake teams make is putting skills into CLAUDE.md. The file balloons to 800 lines. The model still uses it, but each rule loses leverage because it is buried in three pages of procedural content. Worse, the procedures get triggered every session even when they are not relevant, which wastes tokens and slows everything down.
The right home for a procedure is a skill that fires on demand. Claude Skills, Cursor's path-globbed rules, GitHub's path-specific instruction files. Each tool has its own way of saying "load this content when this condition is true." Use them. Keep the main config file lean. Keep the heavy procedural content in the skill system, where it loads only when needed.
If you read CLAUDE.md files in the wild, you will find this distinction violated everywhere. The 1,200-line CLAUDE.md is almost always 200 lines of rules and 1,000 lines of procedures that should have been skills. Splitting them is a one-day refactor with month-long benefits.
What Each Tool Is Actually Best At, In Practice
After running all three of these tools in production for the better part of a year, here is my honest read on where each one earns its keep. This is also the distribution my team has settled on.
Copilot is the default for everyone. Junior, mid, senior, every laptop in the org. It is the autocomplete baseline. The instructions file gets the most universal rules, the ones we want every PR to enforce. We do not expect Copilot to do agentic work for us. We expect it to make every developer 15% faster on the boring 90% of their day and to catch the obvious mistakes in PR review.
Claude Code is the senior engineer's tool. It is what we use for the high-leverage agentic work: a multi-file refactor, a migration plan with rollback, a new feature that touches the backend, the frontend, and the database in one shot. The CLAUDE.md and .claude/skills/ are where the senior engineers invest. We do not push Claude Code on the juniors. They graduate into it when they are ready to direct an agent rather than press tab.
Cursor is the IDE-first option for engineers who want a richer editor experience. Some of our team prefers the Cursor UI, some prefers VS Code with Copilot, some lives in Claude Code in the terminal. We do not standardize. The Cursor rules are auto-generated from the same source. The cost of supporting three tools is small once the projection layer exists. The cost of forcing everyone onto one tool is high, because half the team would lose 20% productivity in the switch.
If you compare these tools head-to-head, the deeper comparison lives in the Claude Code vs Cursor vs Copilot 2026 piece. The TL;DR for the config-file question is: each tool needs its config file, the content overlaps 80%, the projection layer is what keeps them honest.
The Workflow For Adding A New Rule
The last thing worth writing down is the workflow itself. Without a workflow, you are back to ad-hoc edits and silent drift.
A new rule starts as a Linear ticket or a Slack thread. Someone notices a recurring problem. Someone writes up the pattern, the proposed rule, and the reason. The team reviews. If there is consensus, the rule lands in the relevant topical file under .claude/standards/ via PR. The PR includes the reason in the commit body. The PR is reviewed by the area owner.
After merge, the projection script runs. The generated files update. Copilot, Cursor, AGENTS.md all reflect the new rule on the next session.
If a new rule contradicts the existing codebase, the PR includes a migration plan. Either the codebase changes to match the rule, or the rule changes to match the codebase. We do not ship a standard that lies about the code.
Every quarter, the team lead reviews each topical file. Rules with no defender are deleted. The file shrinks. The standards stay relevant.
This sounds heavy. It is not. Most quarters the review takes thirty minutes. Most new rules get reviewed in a five-minute Slack thread. The investment is upfront, in building the projection layer and the review habit. Once it is built, it runs itself.
The Part Nobody Talks About
The hidden cost of AI coding standards is not the tooling. It is the social cost of writing them down.
For years, senior engineers got away with carrying the standards in their heads. They reviewed PRs, they corrected the juniors, they shaped the codebase one line of feedback at a time. The standards existed, but they were tacit. The senior was the standard.
The AI tools force tacit standards out into text. Every rule the senior used to hold in their head now has to be articulable, defensible, written. The first time an engineer sits down to write the database.md file for their team, they hit the wall: half of what they "know" is actually preference, not principle. The other half they cannot defend without a long story about an incident from two years ago. Writing the rules surfaces every weak link in your team's thinking. It is uncomfortable. It is also exactly the thing that makes the team stronger.
The teams I have seen do this well treat the standards file as a team artifact, not a personal one. The senior writes the first draft. The team reviews. The juniors ask why. The senior either has a good answer or removes the rule. After six months, the file is denser and shorter than the first draft, because the only rules that survive are the ones the team can defend.
That is the real prize. Not faster agents. Not more lines of code per day. A team that can explain, to a piece of software, what good looks like. The agents read the file. The juniors read the file. The future senior who joins next year reads the file. The standard is no longer locked in one person's brain. It is on disk, versioned, reviewable, improvable.
The tools are the surface. The discipline of writing down what you actually believe is the substance.
Pick the layout you can defend. Build the projection script. Run the quarterly review. Stop arguing about which file is the source of truth and start arguing about what the rules should actually be. That is the conversation that makes a team better.
The Monday argument on my team has changed. It is not "which file should we have edited." It is "should this rule exist at all, and what is the reason." That is the right argument to be having. If you are not having it yet, that is the goal.
Top comments (0)