GEMINI.md Template — Project Context for Gemini CLI

GEMINI.md, AGENTS.md, and which one wins

Google’s Gemini CLI loads project instructions from a context file. By default that file is named GEMINI.md, but the CLI also reads AGENTS.md — the cross-tool standard now stewarded by the Linux Foundation and read by Codex, Cursor, Copilot, Aider, Zed, and Windsurf. The precedence rule is the one detail teams miss: when both files sit in the same directory, GEMINI.md wins. Keep shared, tool-agnostic rules in AGENTS.md so every agent benefits, and reserve GEMINI.md for Gemini-specific overrides — or skip GEMINI.md entirely and let Gemini CLI read your existing AGENTS.md. Do not duplicate the same content into both; the override file silently shadows the shared one and the two drift apart.

How Gemini CLI assembles context

Unlike a single flat config, Gemini CLI concatenates context files hierarchically and sends the combined result with every prompt. The load order, lowest to highest priority, is: the global ~/.gemini/GEMINI.md (defaults for all your projects), then GEMINI.md files walking from the project root down toward the current working directory, then files in the specific subdirectory a tool is touching. Closer-to-the-file instructions override broader ones. This means a short root GEMINI.md plus targeted per-package files beats one giant root file — the model sees only the local rules that matter for the directory it is editing.

The template

# GEMINI.md

This file is read by Gemini CLI on every task in this repository and merged with any
parent-directory GEMINI.md and the global ~/.gemini/GEMINI.md. Keep it short; put
package-specific rules in that package's own GEMINI.md.

## Tech stack

- Vite 7, React 19, TypeScript 6 (strict mode)
- Vitest 3 for unit and component tests
- Tailwind v4 utilities + daisyUI 5 components only
- pnpm 9 — npm and yarn are not used here

## Commands Gemini may run

- pnpm install — refresh dependencies
- pnpm dev — start the local dev server
- pnpm test --run — run the full Vitest suite once
- pnpm build — produce the production dist/
- pnpm exec tsc --noEmit — type-check only

## Conventions Gemini must follow

- TypeScript strict mode is on; do not introduce any-typed values.
- Function components only; no class components.
- Style with Tailwind utilities; do not add CSS Modules or styled-components.
- A new runtime dependency requires explicit human approval — flag and stop.
- Every async UI surfaces a visible loading state and a visible error state.

## Forbidden patterns

- Do not edit pnpm-lock.yaml directly; run pnpm install instead.
- Do not commit .env or .env.local; .env.example is the canonical schema.
- Do not remove an existing test to make a change pass.

## Output format Gemini must emit

1. One paragraph naming the files you will touch and why.
2. The diff per file (full file for new files; minimal diff otherwise).
3. The exact verification commands you ran and their truncated output.
4. One sentence flagging anything you left out of scope.

— lastVerified: 2026-06-14

Why each section earns its place

The Tech stack block stops Gemini reaching for npm install on a pnpm project and stops it suggesting a v3 daisyUI class on a v5 codebase. The Commands block is a real contract: Gemini CLI executes shell commands, so listing the exact, runnable commands keeps it from inventing a pnpm e2e that does not exist and reporting the failure as a code problem. Forbidden patterns earn their own header because folding them into Conventions makes them vanish when the model skims a long concatenated context. The Output format block is what makes a Gemini run reviewable — a diff plus the verification command output, not a prose summary you have to trust.

Refreshing context without restarting

When you edit GEMINI.md mid-session, run the /memory refresh command so Gemini CLI re-reads the hierarchy instead of working from the stale copy it loaded at startup. /memory show prints the exact concatenated context the model currently sees — use it to confirm a parent-directory file is not overriding a rule you expected to apply.

Where this fits with the other agents

Because Gemini CLI honours AGENTS.md, the cleanest setup is a single shared AGENTS.md at the repo root plus thin per-tool override files only where an agent genuinely differs. The Codex AGENTS.md template covers the shared file in depth, and the Vite CLAUDE.md template covers the Claude Code side. To generate all of these from one form — CLAUDE.md, AGENTS.md, and Cursor rules together — use the AI Agent Rules Generator.