GEMINI.md — Context Hierarchy

~14 min · gemini, gemini-md, context-files, hierarchy

Level 0🌱 Novice

0 XP0/70 lessons0/11 achievements

0/120 XP to next level120 XP to go0% complete

Same idea, three names

GEMINI.md is to Gemini what CLAUDE.md is to Claude Code and AGENTS.md is to Codex: a markdown file the agent reads before doing anything. Hierarchy: ~/.gemini/GEMINI.md (user global) → repo-root GEMINI.md (project) → nested GEMINI.md (subdirectory rules). Files merge top-down; closer-to-CWD wins.

Gemini also reads AGENTS.md as a fallback (Codex compat). If both exist, GEMINI.md wins. Configure other fallback names in ~/.gemini/settings.json via contextFileName.

Code

GEMINI.md at the repo root·markdown

# myproject — GEMINI.md

## What this is
Python data pipeline (Pandas + DuckDB) with a FastAPI surface.

## Setup
poetry install
docker-compose up -d duckdb
poetry run uvicorn app.main:app --reload --port 8000

## Standards
- Python 3.12, type hints everywhere
- Tests use pytest, pytest-asyncio
- Use src/lib/logger.py, never print()
- Schema migrations via Alembic; no raw ALTER

## Do not
- Modify alembic/versions/* (only generate via revision)
- Commit .env (use direnv)
- Use synchronous I/O in API handlers

Multi-name fallback·json

// ~/.gemini/settings.json
{
  "contextFileName": ["GEMINI.md", "AGENTS.md", "AI_GUIDE.md"],
  "contextFileMaxBytes": 65536
}

// Gemini will check each name in order:
// 1. GEMINI.md  (preferred)
// 2. AGENTS.md  (Codex compat)
// 3. AI_GUIDE.md (your team's existing name)

External links

Gemini context files

Exercise

Write a real GEMINI.md (or repurpose an existing AGENTS.md via fallback). Include 5 sections: what-this-is, setup, standards, important-files, do-not. Verify Gemini loads it (ask the agent to summarize the active context).

Progress

Progress is local-only — sign in to sync across devices.

← PreviousInteractive REPL — Themes, History, /help Next →Slash Commands — /tools, /memory, /chat, /save

Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)

No comments yet — be the first.