AGENTS.md vs CLAUDE.md vs Cursor Rules vs Gemini Conductor

The single highest-leverage thing you can do with an AI coding agent is stop re-explaining your project in every prompt. The fix is a persistent project-rules file the agent reads automatically at the start of a session: your coding standards, build and test commands, architecture, and the changes it is forbidden to make. Four conventions dominate today — AGENTS.md (OpenAI Codex), CLAUDE.md (Claude Code), Cursor Rules, and Gemini Conductor — and they overlap more than they differ.

What a rules file is for

These files exist because a coding agent cannot infer your conventions from code alone. Per the Claude Code best-practices documentation, CLAUDE.md "is a special file that Claude reads at the start of every conversation," and you should "include Bash commands, code style, and workflow rules" so the agent gets "persistent context it can't infer from code alone." OpenAI's Codex glossary describes AGENTS.md in the same spirit: a "repository or user guidance file that gives Codex persistent instructions." Same job, different filename.

The right contents are remarkably consistent across tools:

• Build/test/lint commands the agent could not guess (e.g. the exact test runner and how to run a single test).
• Code style rules that differ from defaults — module system, import style, naming.
• Repository etiquette — branch naming, commit and PR conventions.
• Architecture decisions specific to your project.
• Environment quirks — required env vars, local gotchas.
• Forbidden changes — directories the agent must not touch (e.g. generated code or migrations).

The four conventions compared

AGENTS.md (OpenAI Codex). A repository- or user-level guidance file giving Codex persistent instructions. It pairs with Codex's broader governance model — approval policies, sandbox modes (read-only, workspace-write, full access), and permission profiles — so the rules file describes intent while the sandbox enforces boundaries. AGENTS.md has become the most cross-tool of the four because several agents now read it.

CLAUDE.md (Claude Code). Loaded every session. The docs are blunt about the main failure mode: keep it short, because "bloated CLAUDE.md files cause Claude to ignore your actual instructions." The litmus test they give for each line is "Would removing this cause Claude to make mistakes?" — if not, cut it. CLAUDE.md can live in several places: ~/.claude/CLAUDE.md (all sessions), ./CLAUDE.md (checked into git for the team), ./CLAUDE.local.md (personal, gitignored), and parent/child directories for monorepos. It can import other files with @path/to/import syntax, and you generate a starter with /init.

Cursor Rules. Cursor's equivalent rule files steer the agent's behavior per project and per directory, the same role as the above. The Cursor 3.0 generation also adds in-editor context tools (Design Mode, agent tabs) on top, but the persistent-rules concept is the foundation.

Gemini Conductor. Google's take, per its Developers Blog, shifts from chat-based to plan-based development. Conductor is a preview extension for Gemini CLI that, rather than "depending on impermanent chat logs," helps you "create formal specs and plans that live alongside your code in persistent Markdown files," turning "your repository into a single source of truth that drives every agent interaction." You install it with gemini extensions install https://github.com/gemini-cli-extensions/conductor, then run /conductor:setup to record product context, tech-stack preferences and workflow standards; /conductor:newTrack to generate a plan.md of phases, tasks and sub-tasks; and /conductor:implement to have the agent execute that plan, "checking off tasks as it completes them." State lives in files, so you can pause and resume across sessions and machines.

How to write rules that agents actually follow

The hard-won advice across these docs converges on a few rules:

• Keep it short. A long rules file gets ignored. The Claude Code docs recommend keeping CLAUDE.md under 200 lines and moving specialized, sometimes-relevant workflows into on-demand skills instead of bloating the always-loaded file.
• Put commands, not prose. "Use the project's test runner" is useless; the exact command is gold. Include things the agent cannot guess and exclude anything it can read from the code.
• State forbidden changes explicitly. If there is a directory the agent must never edit, say so. Pair the instruction with enforcement (a sandbox in Codex, a hook in Claude Code) so it is deterministic, not advisory.
• Check it into git. A shared rules file is the cheapest onboarding document your team has; it compounds in value as people add to it.
• Tune adherence. The Claude Code docs note you can add emphasis ("IMPORTANT", "YOU MUST") to improve compliance — but if the agent keeps ignoring a rule, the file is probably too long and the rule is getting lost.

The deeper point: these files are most powerful when paired with a disciplined prompting workflow rather than used as a substitute for one. A clear rules file plus a well-scoped task brief is what turns an agent from a guesser into a contributor.

Read the Prompt-to-PR Workflow guide

FAQ

Do I need AGENTS.md AND CLAUDE.md?

Only the ones your tools read. AGENTS.md is for Codex (and increasingly other agents), CLAUDE.md is for Claude Code. If you use both tools you can maintain both, but keep them consistent so you are not describing two different projects.

What is the difference between Cursor Rules and CLAUDE.md?

They play the same role — persistent project instructions an agent reads automatically. CLAUDE.md is Claude Code's file (loaded every session, supports imports and per-directory placement); Cursor Rules are Cursor's equivalent. Both should hold commands, style and forbidden changes.

How is Gemini Conductor different?

Conductor is plan-driven rather than a static instructions file. You define context once, then it generates a plan.md of tasks the agent executes and checks off, with state persisted in Markdown so work resumes across machines.

How long should a rules file be?

Short. The Claude Code docs recommend keeping CLAUDE.md under 200 lines and warn that bloated files cause the agent to ignore instructions. Move occasional workflows into on-demand skills.

Bottom line

AGENTS.md, CLAUDE.md, Cursor Rules and Gemini Conductor are four answers to the same problem: give the agent persistent project context so you stop repeating yourself. The static files (AGENTS.md, CLAUDE.md, Cursor Rules) hold commands, style and forbidden changes; Conductor goes further with plan-driven execution. Whichever you use, keep it short, write commands not adjectives, state what the agent must not touch, and check it into git.

Sources and further reading