CLAUDE.md, AGENTS.md, GEMINI.md: A Configuration Guide for AI Coding Agent Instruction Files

Every time an AI coding agent starts a session, it first reads an instruction file. Have you ever checked what's written in yours?

This kind of file is essentially a plain-text note, functioning like a handover memo left for a new colleague. Different tools name it differently—Claude Code reads claude.md in the project root, Codex reads AGENTS.md, Gemini CLI reads GEMINI.md, and Cursor uses its own rule file system. Understanding the loading logic and priority of these files is the prerequisite for getting AI agents to actually work according to your team's conventions.

What Should Actually Go in an Instruction File

The criterion is simple: anything a new colleague must know on their first day should go in. Specifically, three categories of content—how to run tests, code style conventions, and things that are absolutely not allowed.

What these three categories share is that they aren't reflected in the code itself, but violating them causes problems. Get the test command wrong, and the agent wastes time on invalid verification; omit style conventions, and the generated code requires repeated manual rework; leave prohibited actions unclear, and the agent may perform destructive operations.

The original advice is to "start with a small file"—first clearly write down how to test, your style, and what must be asked about first. Don't try to cram every convention in from the start; the value of an instruction file lies in precision, not length.

System Prompt vs. Instruction File: The instruction sources for AI coding agents are typically layered. The system prompt is built in by the tool vendor and defines the agent's fundamental behavioral guidelines (such as safety boundaries and tool-call formats); users cannot modify it. The instruction file, by contrast, is user-editable persistent context that is injected after the system prompt each time a session initializes, serving as project-specific supplementary constraints. Together they form the agent's "initial memory," but the instruction file is more flexible and closer to concrete engineering practice. Understanding this layering helps avoid confusion: you can't override vendor-set safety policies via the instruction file, but you can finely control project-level behaviors like code style and test workflows.

Project-Level vs. User-Level: Two Locations, Two Responsibilities

Instruction files have two storage locations with clearly divided responsibilities:

Project files live in the project repository, are shared by the team, and go into version control. Facts the whole team must follow go here—how to run tests, branch conventions, code review requirements.

User files live in the user's home directory, belong to you alone, and apply to all projects. Personal habits go here, such as "always ask me before adding a dependency package."

This division resolves a common confusion: for a given rule, should it be team-shared or personal? The answer depends on whether it's tied to a specific project. Team conventions go in project files; personal preferences go in user files.

Version Control and Instruction Files: Project-level instruction files should generally be committed to version control systems like Git for team sharing and auditing. But note that some tools (such as Cursor) may have rule files containing local paths or sensitive configuration—it's advisable to exclude user-level files (like ~/.claude/CLAUDE.md) in .gitignore and commit only the shared files in the project root. Additionally, during merge conflicts, changes to instruction files should go through code review like code does, ensuring rule changes are team consensus rather than arbitrary personal edits.

When Both Exist, Which Takes Effect: Agents Merge Rather Than Choose

Many people assume project files and user files are mutually exclusive, but in reality most agents merge and read both, and in terms of read order, files closer to the current project come later—meaning project files have higher priority in sequence.

This means you don't need to repeat user file content in project files; the agent layers them itself. Conversely, if conflicting rules are written on both sides, the final behavior depends on the merge logic, easily producing hard-to-troubleshoot deviations. Keeping the two files' responsibilities non-overlapping is more important than agonizing over priority.

Naming Differences Across Agents and the Universal Status of AGENTS.md

Inconsistent naming is the most easily overlooked pitfall of this mechanism:

• Codex: AGENTS.md
• Gemini CLI: GEMINI.md
• Cursor: its own rule files
• Claude Code: claude.md

One name is shared—AGENTS.md. Codex and Cursor can read it directly; Gemini requires extra setup to recognize it; Claude Code only reads AGENTS.md when there is no claude.md.

This detail has a big impact on mixed-tech-stack teams. If some people on your team use Claude Code and others use Codex, maintaining only a claude.md means Codex users get no instructions at all.

What the AGENTS.md Open Standard Actually Contains: AGENTS.md is a community-driven open specification hosted by the Linux Foundation, aimed at providing AI agents with a unified project instruction entry point. It does not define specific syntax but rather agrees on file location and basic structure (such as using Markdown headings to divide sections), so that different agents can parse it in the same way. Currently, tools like Codex and Cursor natively support it, Gemini CLI requires configuration to enable it, and Claude Code treats it as a fallback. The standard lowers the maintenance cost of multi-tool collaboration, but it hasn't been adopted by all vendors yet—you need to confirm compatibility with the agent you're using in practice.

The Optimal Solution for Mixed Teams: One AGENTS.md + One Line Pointing to It

The original article's solution is straightforward: keep AGENTS.md as the single source of truth, then point to it with one line in claude.md. This way Codex and Cursor read it natively, Gemini accesses it via settings, and Claude Code indirectly obtains the same set of rules through the pointing file.

What supports this solution is a key fact: AGENTS.md is now an open standard maintained by the Linux Foundation. This means it isn't tied to any single vendor, giving it long-term stability as a carrier for team-level instruction files. Compared to locking conventions into a specific tool's proprietary format, betting on an open standard is the safer choice.

Practical Recommendations

Don't aim for completeness when getting started. First establish a minimally viable instruction file covering the three items—test commands, code style, and operations that must be asked about first—then gradually supplement it through actual collaboration. Mixed teams should prioritize implementing the AGENTS.md single-source solution to avoid multiple files drifting apart and causing inconsistent agent behavior.

Instruction files are the invisible constraint layer on agent behavior: when written well, they significantly reduce rework and misoperations; when written poorly, they're as good as nonexistent—after all, the agent reads it every time, but you may not always remember to check it.