CLAUDE.md: one rules file wired into four coding agents with symlinks

The file is loaded before the request, which is the whole mechanism

A coding agent with no instructions produces the average of everything it has ever seen, and the project documentation calls that average mediocre: it stops early, skips tests, invents libraries, and asks permission for things it should just do. The fix is a standing instruction set that is loaded into the model's context at the start of every session, so the agent reads it before it reads your request.

That is the entire design. The repository is one file, CLAUDE.md, and the tests/ and evals/ directories exist only to prove that the shell commands inside the file work. The contract covers how the agent should think, when to write code instead of guessing, what counts as done, and how it should address the human. The README frames the difference as hiring a contractor with no brief versus hiring one with a one-page spec taped to the wall, and the file is opinionated on purpose, with the ideas attributed to Andrej Karpathy, Garry Tan, Matt Shumer and Nick Stinemates.

What it does not do is change the model. The value is entirely in what you tell the agent before it starts.

AGENTS.md is the filename that travels between tools

Claude Code reads a file called CLAUDE.md from the project root, and a global version from ~/.claude/CLAUDE.md. Most other agents read a file called AGENTS.md, which the documentation describes as an emerging cross-tool standard supported by Codex CLI, Cursor, Gemini CLI, Jules and others. The content is identical, only the filename changes.

The repository's answer to the drift problem is symlinks rather than copies, with CLAUDE.md as the real file:

# CLAUDE.md is the real file; everything else points at it
ln -s CLAUDE.md AGENTS.md      # Codex CLI, Cursor, and the AGENTS.md standard
ln -s CLAUDE.md GEMINI.md      # Gemini CLI

One file, edited once, and every agent sees the same bytes. This repository itself ships AGENTS.md as exactly that symlink, and the project explains why there is only one: AGENTS.md is the cross-tool standard, and a second and third alias would be two more files to drift. The README also handles the case where symlinks are not an option, noting that Windows checks out symlinks as plain text files holding the target path unless Developer Mode or core.symlinks=true is enabled, so on Windows you copy the file instead.

Cursor has a second option in the same table, a .cursor/rules/ directory, and GitHub Copilot uses a different file entirely, .github/copilot-instructions.md, so there the content has to be copied in.

The commands in the file are executed by a test suite

Most of a rules file is judgement, and judgement cannot be unit tested. The branching section is different, because it hands the agent shell commands to copy, and the project makes the point that a rules file whose commands are wrong is worse than no rules file. So the commands are extracted from the markdown and run against throwaway repositories:

bash tests/run.sh

The suite creates its own git repositories under $TMPDIR with an overridden $HOME and GIT_CONFIG_GLOBAL, so it does not touch your repositories or your real git configuration.

The defects it covers are specific and worth reading, because they are the failure modes of this kind of tooling. The README lists a sweep that deleted other sessions' live worktrees, a git worktree remove that silently ate a gitignored .env, an unset session id that put two sessions into one tree while reporting success, a git worktree add whose failure was swallowed by the next echo, and a --force-with-lease that was defeated by the git fetch running right before it. Every one of those was caught by running the commands rather than by reading them, and the instruction at the end is direct: if you edit those commands, run the suite again.

An eval checks the guidance is followable, and controls keep the grader honest

Passing the shell suite proves the commands work. It says nothing about whether a section of prose is followable, which the documentation calls the other half of a rules file. That is the job of evals/branching_scenario.md: hand a fresh model the branching section alone and see whether it produces the right commands cold.

The grader has its own check, run before any score is trusted:

bash evals/controls.sh    # prove the grader still discriminates, before trusting a score

The README argues that the controls matter more than the score, and explains why with a concrete failure. An earlier version of the grader gave a broken revision and its fixed replacement the same 7/7, because the positive control was the section's own block, so the grader was comparing the answer against itself. The fix is a regression fixture, evals/fixtures/v1_answer.sh, holding the broken version, which has to fail or the eval is not measuring anything.

That is a small piece of engineering discipline, but it is the part that makes the rest of the claim checkable. A repository that scores its own homework is not evidence of anything.

Making it yours means deleting the parts that are about the author

The file refers to the author by name in several places, with instructions like asking Julien what to restart, and the agent uses that name as the human it answers to. The README gives the two platform-specific sed commands to fix that:

# macOS
sed -i '' 's/Julien/YOUR_NAME/g' CLAUDE.md

# Linux
sed -i 's/Julien/YOUR_NAME/g' CLAUDE.md

The README then lists what to decide while you are in the file. A path in the talk-style section, food_vision/classifier.py:47, is an example that only shows the format the agent should use when pointing at code, so it can stay. The LLM-access rule, which routes through local Claude Code and never an external API, is specific to the author's setup, and if you call the Anthropic or OpenAI API directly you should delete that block or invert it. The gstack and skills references assume Garry Tan's gstack is installed, and without it the check for skills still works but finds fewer skills. The branching rule, one session one worktree one branch, assumes you work on a team and review through pull requests.

That list is the honest cost of the template. You are not installing a config file, you are inheriting a set of decisions and pruning the ones that do not match your setup.

Where a single shared rules file stops working

The first limit is that the rules are written for one agent's habits. An instruction set tuned for one coding agent, tested by running commands in one terminal, does not transfer cleanly to a tool with a different interface, a different permission model and a different way of surfacing context. The AGENTS.md convention helps with file discovery, not with the assumptions inside the file.

The second limit is scope. This is one file, and the project makes that clear. It is a contract about thinking, testing and communication, not a configuration system: there is no per-language section, no per-directory override, no mechanism described for scoping rules to part of a repository. Teams with a monorepo containing a Python service and a TypeScript frontend get one voice for both.

The third limit is the licence question, and here the material is thin. The repository's top-level entries are .gitignore, AGENTS.md, CLAUDE.md, README.md, evals/ and tests/, with no licence file in the tree, and the release list is empty because the repository has no GitHub releases. The README asks you to copy the file, put your own name in it and make it better, but it does not state terms for reuse. If your organisation needs a licence review before a rules file ends up in every repository, that review has to be done from the repository itself rather than from its documentation.

The last push to the repository was on 2026-08-30, so the file is being worked on, and the rules inside it will drift from the tools they describe.

Against a hand-written brief or a tool-native rules file

The alternative for most teams is not another rules file, it is a smaller one. A paragraph in your own issue tracker or a short section at the top of your contributing guide achieves much of what this file does, with none of the drift risk and no symlinks. The difference in approach is scope and enforcement: a brief in a ticket applies to one task, while CLAUDE.md applies to every session in the repository and is read before the request is even read.

The other alternative is to use each tool's native configuration, a .cursor/rules/ directory for Cursor, the GitHub Copilot instructions file for Copilot, a global file in your home directory. The README mentions both of these as options. The difference is that a native file lives in one tool's ecosystem, so you maintain N copies of the same intent, which is exactly the problem the symlink arrangement solves.

There is a third option worth naming: a thin file that only carries what is verifiable. The repository itself demonstrates the split, with judgement in the markdown and shell commands in a tested suite. A team that takes only the parts of CLAUDE.md that their tools can check ends up with a smaller, sturdier rules file than the one they started with, and the README's own framing of the exercise points that way.

Editorial conclusion

CLAUDE.md is worth copying for a team that runs more than one coding agent against the same repository, because the symlink arrangement keeps a single source of truth and the test suite proves the shell commands in the file actually run. It is the wrong starting point for a solo developer who writes their own brief anyway, and for anyone who cannot accept a rules file that arrives with another engineer's opinions baked in. Before you adopt it, check the three things the project documentation itself flags: that you have replaced the author's name, since the agent treats that name as the human it answers to; that you have deleted or inverted the LLM-access rule, which assumes a local setup you probably do not have; and that you have run bash tests/run.sh after every edit to the commands, because the file itself says a rules file whose commands are wrong is worse than no rules file.

Frequently asked questions

Official sources

1. Issues
2. jbarbier/CLAUDE.md on GitHub
3. README