TLDR: Repo context files are very useful, but each of the leading CLIs wants it to have a different name. My favorite solution is to call it the most generic way (AGENTS.md) and symlink to whatever the other tools want.
These days agentic coding CLIs are all the rage, and as of July 2025 all the leading AI labs have one of their own. There’s Claude Code from Anthropic, OpenAI Codex from OpenAI and Gemini CLI from Google DeepMind.
An emerging best practice for these tools is to capture the context that the agent needs to effectively work with a given repo in a repo context file.
These context files are written in plain natural language, so they’re understandable to the LLMs and easy to grok and expand for human editors. I like Diwank’s description of these files as the “constitution for your codebase”.
Claude Code: Best practices for agentic coding
The gotcha is that each lab wants the files to have a specific name to be automatically loaded by the CLI:
- Claude Code will automatically load the context from
CLAUDE.md - OpenAI Codex will only load it from
AGENTS.md - Gemini CLI wants it to be called
GEMINI.md
At the same time, may repos will have developers using different CLIs contributing to the same codebase.
A simple solution for this is to put the context file in AGENTS.md (kudos to OpenAI for having picked a generic name), and symlink the other two to it. After that, all three files (one source of truth and two symlinks) can be checked in to the repository.
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md
With this setup, all three CLIs automatically load the same context content without any file duplication.