The Context File Pattern (CLAUDE.md, AGENTS.md, GEMINI.md)

Three names, one idea

Every major CLI converged on the same primitive: a markdown file in your repo that the agent reads before doing anything else. Claude calls it CLAUDE.md, Codex calls it AGENTS.md, Gemini calls it GEMINI.md. Same shape, same purpose: project memory that travels with the code.

Why this exists at all: prompts evaporate, files persist. If every contributor has to retype "we use TypeScript strict mode and never any" at the start of every session, the rule is functionally absent. Move it into a tracked markdown file and the agent reads it on every cold start, every git clone, every CI run. The repo finally has a memory the AI shares.

The hierarchy is the same across CLIs: global (your ~/.claude/, ~/.codex/, ~/.gemini/) → project (repo root) → nested (subdirectory-specific rules layered on top). Files merge, closer-to-cwd wins. Personal style preferences sit at the global level; team architecture sits at the project root; security-sensitive rules sit deeper.

Code

A repo with all three context files·text

myproject/
├── CLAUDE.md          ← Claude Code reads this
├── AGENTS.md          ← Codex CLI reads this
├── GEMINI.md          ← Gemini CLI reads this
├── src/
│   ├── payments/
│   │   ├── CLAUDE.md  ← extra rules just for payments code
│   │   └── ...
│   └── ...
└── ...

# Same content can live in all three (or share most of it)
# — different agents, same project memory.

What goes in a context file·markdown

# AGENTS.md (or CLAUDE.md / GEMINI.md)

## What this is
TypeScript REST API on Node 22 + Postgres 16. Deployed via Fly.io.

## Standard commands
npm run dev      # localhost:3000, hot reload
npm test         # vitest
npm run db:migrate

## Conventions
- TS strict, no `any` (use `unknown` and narrow)
- All routes have an integration test in tests/
- Error envelope: { data, error, meta }

## Do not
- Commit .env (use direnv)
- Modify schema.prisma without a migration
- Add deps without checking bundle size first

Exercise

In any Git repo of your own, create a 30–80 line context file appropriate for the CLI you use most. Include: tech stack, three standard commands, two coding rules, two "do not" rules. Commit it. Open a fresh CLI session in that repo and ask the agent to summarize the file — confirm it actually loaded.

The Context File Pattern (CLAUDE.md, AGENTS.md, GEMINI.md)

Three names, one idea

Code

External links

Exercise

Progress

Comments 0