GEMINI.md: hierarchical context that scales with your repo

Every serious agent reads a steering file before it touches your code: Codex has AGENTS.md, Claude Code has CLAUDE.md. Gemini CLI's is GEMINI.md, and its one genuinely distinctive idea is hierarchy: a cascade, merged from your home directory down through the repo to the directory the agent is working in. On a two-package repo that's a curiosity. On a monorepo it's the difference between a context file that steers and a two-hundred-line manifesto nobody dares edit.

The cascade, top to bottom

Gemini CLI assembles instruction context from three levels. A global file at ~/.gemini/GEMINI.md applies to everything you do on the machine. A project file at the repo root carries what's true across the codebase. And any subdirectory can hold its own GEMINI.md whose rules apply when the agent works in that part of the tree. The files are concatenated general-to-specific, so the file closest to the work effectively gets the last word. Two session commands make the system legible: /memory show prints the merged result the model actually sees (run it once and you'll be surprised how big it is), and /memory refresh reloads everything after a mid-session edit. The filename itself is configurable in settings, which is how teams point one steering file at several tools instead of maintaining parallel copies.

What belongs at each level

• Global. Personal defaults that hold everywhere: preferred package manager, commit style, a standing ask-before-adding-dependencies rule. Keep it under ten lines forever.
• Project root. What every task in this repo needs: build and test commands, a three-line architecture sketch, hard conventions for errors and logging, the directories that are off-limits.
• Per-directory. Genuine local law only: this package is generated so edit the templates instead, this service still uses the legacy client, tests here need the database container running.

The per-directory tier is what actually scales. A root file that tries to carry every module's quirks bloats into something nobody maintains; a ten-line file sitting next to the quirk stays readable and stays true. The craft is the same as for any agent context file, and most of what works for CLAUDE.md in practice ports straight over. Hierarchy just gives each piece of advice an address.

Every line of GEMINI.md rides along on every request — an instruction earns that tax or gets cut.

Keep it lean anyway

The merged cascade is prepended to essentially everything the agent does. That costs tokens and latency, but the bigger bill is instruction-following: a model tracks eight rules far more reliably than eighty, and every stale line dilutes the ones that matter. Gemini's 1M-token window makes bloat feel free. It isn't. Hierarchy adds its own failure mode, too: per-directory files are easy to forget. They drift as the code changes, and when a stale local rule contradicts the root file, the agent resolves the conflict silently in whichever direction. You end up debugging behavior when you should be deleting a line of config. When the agent keeps ignoring an instruction, treat that as a signal the file is too long or the rule is ambiguous, not that the model is being dense.

Start with a root GEMINI.md and nothing else. Add a per-directory file the first time the agent breaks a rule that only applies in one place: that's the sign a rule needs a local address. And if your repo is one service and thirty files, skip the hierarchy entirely: one lean file beats three thin ones, and /memory show should never scroll.