Should You Commit AI Coding Assistant Config Files to Your Repo?
Commit the Team Rules and Ignore the Personal Ones
- ● Project facts go in version control
- ● Personal preferences stay gitignored
- ● Secrets never go in either one
Yes, commit them, with one carve-out. Files that describe the project belong in version control like any other shared config. Files that describe you belong in a gitignored local file or your home directory.
Cursor stores project rules in .cursor/rules as .mdc files and treats them as version-controlled by design. Claude Code draws the same line, with CLAUDE.md for the team and CLAUDE.local.md for personal notes you keep out of git.
The argument usually starts when a rules file appears in a pull request and a reviewer asks why editor settings are in the diff. That framing is the problem. A good rules file is not editor settings; it is onboarding documentation that happens to be machine readable.
Which File Each Assistant Actually Reads
- ● Cursor reads mdc files under .cursor/rules
- ● Copilot reads .github/copilot-instructions.md
- ● Claude Code reads CLAUDE.md not AGENTS.md
The paths are worth knowing before the debate, because each tool made a slightly different choice.
| Assistant | Committed location | Personal or local option | Scoping mechanism |
|---|---|---|---|
| Claude Code | CLAUDE.md or .claude/CLAUDE.md |
CLAUDE.local.md, plus ~/.claude/CLAUDE.md |
.claude/rules/*.md with a paths glob |
| Cursor | .cursor/rules/*.mdc |
User rules held in editor settings | Four rule types, including glob matching |
| GitHub Copilot | .github/copilot-instructions.md |
Personal instructions on github.com | .github/instructions/NAME.instructions.md with applyTo |
| Broad agent support | AGENTS.md at the repo root |
None defined by the format | Nested files, closest one wins |
| Monorepo subprojects | Nested AGENTS.md or CLAUDE.md |
Same as the parent tool | Directory position does the scoping |
Two details in that table cause most of the confusion. A plain .md file dropped into .cursor/rules is ignored, because the rules system needs the frontmatter that .mdc files carry.
The second is that Claude Code reads CLAUDE.md and not AGENTS.md, so a repo standardised on the open format needs a small bridge. The documented options are an import line or a symlink, which we come back to below.
The Line Between Shared and Personal
Ask one question about every line you are tempted to add. Would a new contributor need this on day one?
Build commands, test invocation, directory layout, naming conventions, and the pitfalls that keep biting reviewers all pass that test. They are the same facts you would put in a contributing guide, written for a reader that never skims.
Your preferred commit message style, your local database URL, and the shortcut you like for running one flaky test do not pass it. Those go in a gitignored local file, or in your user-level config where they apply across every project.
The split also survives contact with reality better than the alternatives. Nobody has to negotiate personal taste in a pull request, and the shared file stays short enough that people keep reading it.
What Belongs in a Committed Rules File
Start with the corrections you type more than once. If you have explained the same convention to an assistant in two separate sessions, that is the signal to write it down.
Be concrete enough that compliance is checkable. “Use two space indentation” and “run the test suite before committing” are verifiable; “format code properly” and “write clean code” are decoration.
Point at the code rather than restating it. A line saying that API handlers live in src/api/handlers/ ages well, while a copied directory tree goes stale the first week somebody adds a folder.
Keep it short on purpose. Claude Code documentation targets under 200 lines for a CLAUDE.md, and Cursor suggests keeping a rule under 500 lines and splitting anything larger into composable pieces.
Length matters because these files are loaded into a limited context window every session. A bloated rules file competes with the code the assistant is meant to be reading.
What Should Never Go In One
Secrets are the obvious exclusion and still show up. A committed file travels into every clone and fork, so store the credential in your secret manager and write the retrieval command instead.
Internal hostnames, customer names, and unreleased product details deserve the same caution in a public repository. Rules files are rarely reviewed with the care applied to code, which is exactly why they leak.
Also leave out anything that must happen, rather than should happen. Instructions are context, not enforcement, and an assistant can decide to skip them.
For hard requirements, use the mechanism the tool provides. Claude Code documents hooks for that purpose, and a pre-commit hook or CI check works the same way for the rest of the team.
Merge Conflicts and the Other Practical Costs
The most common complaint about committed rules files is conflict noise. Several people edit one markdown file for unrelated reasons, and git has no idea the sections are independent.
The fix is structural. Both Claude Code and Cursor support a rules directory of topic files, so testing conventions and API conventions live in separate files that rarely collide.
Scoping helps twice over. A rule with a paths glob loads only when the assistant touches matching files, which cuts context cost and keeps frontend rules out of a backend session.
The second cost is staleness. A rules file that contradicts the codebase is worse than no file, because the assistant follows the instruction and produces confidently wrong work.
Treat contradictions as bugs. When two files disagree, an assistant may pick either one, and the resulting behaviour looks random to whoever hits it.
Keeping One Set of Rules for Several Assistants
Mixed toolchains are the normal case now. One developer runs Cursor, another runs Copilot in an IDE, and a third runs a terminal agent, all in the same repository.
Duplicating instructions across three files guarantees drift. Pick one canonical file and make the others reference it, rather than maintaining parallel copies that diverge within a month.
AGENTS.md is the pragmatic base for that role. The format is read by a broad set of agents, supports nested files where the closest one wins, and its site reports use across more than 60,000 open-source projects.
Claude Code can then point at it in two documented ways. An import line keeps both files in play, and a symlink works when no Claude specific content is needed.
# Option A: import AGENTS.md from CLAUDE.md, then add tool-specific notes below
printf '@AGENTS.md\n\n## Claude Code\n\nUse plan mode for changes under src/billing/.\n' > CLAUDE.md
# Option B: one file, two names (Windows needs Developer Mode for symlinks)
ln -s AGENTS.md CLAUDE.md
Imports resolve recursively up to four hops, so a canonical file can pull in a testing guide without a wall of duplicated text. Our guide to setting coding standards an assistant will follow goes deeper on what to write inside those files.
Who Should Commit What
- ● Solo repos can commit almost everything
- ● Open source needs a contributor read
- ● Regulated teams review rules like code
You work alone in a private repo: commit nearly everything, since the personal and project scopes collapse into one. Keep secrets out anyway, because private repositories get shared later.
You are on a small team with one toolchain: commit the shared rules file and gitignore the local variant. Add the local filename to .gitignore on day one, before somebody commits their sandbox URL.
You maintain an open source project: commit a short rules file and read it as a contributor would. Anything that assumes internal knowledge either gets explained or moves out.
You work in a monorepo: commit nested files next to the code they describe. The closest file wins for most tools, so a package level file beats a root file full of conditionals.
You are in a regulated or security sensitive environment: commit the file and review it like code. Instructions shape behaviour without enforcing it, so pair the rules file with hooks or CI checks that fail loudly.
Your team runs three different assistants: commit one canonical file and bridge the rest. Duplication is the failure mode here, not the file count.
Reviewing Rules Files Like Code
Put the rules file in the same review path as everything else. A one line change to an instruction can alter how an assistant behaves across the whole repository.
Ask the reviewer two questions. Is this fact true today, and would a new contributor need it? Anything that fails both belongs in a personal file or nowhere.
Prune on a schedule. Stale instructions accumulate quietly, and the cost shows up as an assistant confidently following a convention the team abandoned last quarter.
Watch for the file becoming a dumping ground. When it grows past a screen or two, split it into scoped rules rather than adding another bullet nobody reads. The same discipline applies when you migrate between tools, which our walkthrough of switching AI coding assistants without losing your setup covers in more detail.
The File Is Documentation Either Way
The strongest argument for committing these files has nothing to do with AI. A well written rules file is the contributing guide people actually maintain, because it pays them back the same day.
The strongest argument against committing a specific line is usually that the line was never about the project. That is a content problem with a clean fix, not a reason to gitignore the file.
Split by audience, keep it short, review it like code, and the debate stops being interesting. Your assistant gets the context it needs, and the next contributor gets the same briefing without asking anyone.
A committed rules file is also loaded on every request, which means it spends the same budget your code does. What context window size really means for coding work explains why a short file split by audience reads better to the assistant than a long one that says everything.
FAQ
Should AGENTS.md or CLAUDE.md be committed to git?
Commit them when they describe the project rather than the person. Build commands, test conventions, and directory layout help every contributor and belong in version control. Personal preferences belong in a gitignored local file instead.
Do AI assistant rules files create merge conflicts?
They can, because several people edit the same markdown file for different reasons. Splitting rules into topic files under a rules directory keeps most edits in separate files, which removes the majority of the conflicts.
Can one rules file work for several AI coding assistants?
Partly. AGENTS.md is read by a wide range of agents, and Claude Code reads CLAUDE.md instead, so many teams keep one canonical file and have the other import or symlink to it rather than maintaining two copies.
Is it safe to put project secrets in an AI assistant instructions file?
No. A committed instructions file is readable by everyone with repository access and travels into forks and clones. Keep credentials in your secret manager and reference the retrieval command instead of the value.
How long should a committed rules file be?
Shorter than most teams expect. Claude Code documentation suggests keeping a CLAUDE.md under about 200 lines, and Cursor advises keeping a rule under 500 lines and splitting larger ones, because long files reduce adherence.
Sources
- Claude Code documentation — checked 2026-09-07
- Cursor documentation — checked 2026-09-07
- Anthropic pricing — checked 2026-09-07
Some links may be affiliate links. We may earn a commission at no extra cost to you.
This article was written with AI assistance. It is researched and fact-checked, not based on personal hands-on testing unless explicitly stated.
Comments
Post a Comment