Organizing AI Agent Context Files

AI and Coding
1

It seems like every AI CLI tool creates its own context/instructions file with the /init command:

  • Codex creates AGENTS.md
  • Gemini CLI creates GEMINI.md
  • Claude Code creates CLAUDE.md

I didn’t want to duplicate the instructions, so I’ve created one AGENTS.md file.

For Gemini CLI, I create .gemini/settings.json and point it at AGENTS.md (docs):

{
  "context": {
    "fileName": ["AGENTS.md"]
  }
}

Then I put this in CLAUDE.md:

# CLAUDE.md

This repository's canonical agent instructions are in AGENTS.md.

Before doing any work, read AGENTS.md and follow it as the source of truth.

I’m wondering if anyone has other ways of managing it.

2

I switch between agents, so I actually prefer that each agent has its own markdown file. You can always ask any agent to read all the docs (granted this burns context). I have my own ./docs/agent_instructions.md file and whichever agent’s root markdown file is used, I ask that it point to (and follow) my docs, too.

1 Like