By Przemek, last update

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.

Welcome information printed out by Gemini CLI, including a suggestion to create a GEMINI.md file with agent guidance

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”.

A screenshot of Anthropic article about how to write a CLAUDE.md file

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.