GEMINI.md Examples: 6 Gemini CLI Context Files to Copy

Published 2026-10-25 · 6 min read · by AgentKit Co

Gemini CLI reads Markdown files named GEMINI.md, joins them together and sends them to the model with every prompt. A short, specific one stops you from repeating "use pnpm, run the tests, don't touch the generated folder" in every session.

This page gives you six files to copy, shows how @ imports and context.fileName let you reuse an existing AGENTS.md, and lists the fixes for when Gemini seems to ignore you. Everything here was checked on 2026-10-25 against the Gemini CLI docs for GEMINI.md context files, the memory import processor and the command reference. Gemini CLI changes often, so re-check anything you rely on.

Where Gemini CLI looks

All the files it finds are concatenated, so there is no "winner": a global rule and a project rule that disagree are both sent. Remove the contradiction instead of relying on order. The CLI footer shows how many context files are loaded.

1. The minimum useful file

Start here. Put it at the root of the repository:

# Project instructions

- This is a Next.js 15 app using TypeScript and pnpm. Never use npm or yarn.
- After every change run `pnpm test` and `pnpm lint`, and fix failures before you say you are done.
- Do not edit anything in `src/generated/`; it is rebuilt by `pnpm codegen`.
- Ask before adding a dependency.

Four exact rules beat a page of style advice. Each one names a command or a path the agent can check.

2. TypeScript library

# Project: payments-sdk (TypeScript library)

## Commands
- Install: `pnpm install`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- Full check before finishing: `pnpm typecheck && pnpm test && pnpm lint`

## Code style
- Strict TypeScript. No `any`; use `unknown` and narrow it.
- Public functions and classes get a JSDoc comment with one example.
- Use `===` and `!==` only.
- Errors: throw the classes in `src/errors.ts`, never plain strings.

## Boundaries
- `src/public/` is the public API. Changing an export there is a breaking change: stop and ask first.
- Never edit `dist/` or `CHANGELOG.md` by hand.

3. Python service

# Project: orders-api (Python 3.12, FastAPI)

## Commands
- Environment: `uv sync`
- Tests: `uv run pytest -q` (a single test: `uv run pytest tests/test_orders.py::test_refund -q`)
- Lint and format: `uv run ruff check . && uv run ruff format --check .`

## Rules
- Type hints on every function. Run `uv run mypy app` after changing signatures.
- Database changes go through a new Alembic migration in `migrations/versions/`. Never edit an old migration.
- Read settings from `app/config.py`, never from `os.environ` directly.
- Do not print secrets or full request bodies in logs.

## When you finish
Paste the last lines of the pytest output so I can see it ran.

The last line matters: asking for real test output is the simplest way to catch an agent that says "tests pass" without running them.

4. Monorepo with a subfolder file

Root GEMINI.md:

# Monorepo (pnpm workspaces + Turborepo)

- Packages live in `apps/` and `packages/`. Run commands from the repo root with a filter, e.g. `pnpm --filter web test`.
- Never change `pnpm-lock.yaml` by hand; run `pnpm install`.
- Shared types are in `packages/types`. Change them only if the task says so.

apps/mobile/GEMINI.md (picked up just in time, when the agent works in that folder):

# apps/mobile (Expo, React Native)

- Test: `pnpm --filter mobile test`
- Use the components in `apps/mobile/src/ui/`; do not add a new UI library.
- Never edit `ios/` or `android/` directly; they are generated by `expo prebuild`.

Folder-level files keep the root file short and only load when they are relevant.

5. Your global file

~/.gemini/GEMINI.md is for preferences that follow you to every project, not project facts:

# My preferences

- Explain your plan in 3 bullet points before editing more than one file.
- Prefer small diffs. Do not reformat code you did not need to change.
- If a command fails, show me the error instead of guessing a fix silently.
- Write commit messages in the imperative mood, under 72 characters.

Keep it to a handful of lines. Everything here is sent in every project, including ones where it doesn't fit.

6. Split a long file with @ imports

Gemini CLI can pull other Markdown files into GEMINI.md with @path:

# Project instructions

@./docs/agents/commands.md
@./docs/agents/architecture.md

## Rules that apply everywhere
- Ask before deleting files.

Relative and absolute paths work, imported files can import others (default maximum depth: 5 levels), circular imports are detected and skipped, and a missing file becomes an error comment instead of a crash.

Already have AGENTS.md? Reuse it

You don't need two copies of the same rules. Either import it from GEMINI.md:

@./AGENTS.md

## Gemini-only notes
- Use `/memory show` if you are unsure which instructions are loaded.

or tell Gemini CLI to read other names directly in .gemini/settings.json:

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

One source of truth means the Claude, Codex, Cursor and Gemini instructions can't drift apart. Our AGENTS.md vs CLAUDE.md vs Cursor rules guide compares the formats.

Why Gemini ignores your GEMINI.md

• It was loaded before you edited it. Edits don't apply to a running session. Run /memory reload (listed as refresh in the command reference) or restart.
• It isn't loaded at all. /memory list shows the paths of the files in use and /memory show prints the exact combined text the model gets. If your file isn't there, check the name (GEMINI.md, or whatever context.fileName says) and that you started the CLI inside the project.
• Conflicting files. Your global file says one thing, the project file another, and both are sent. Delete one of the rules.
• Vague rules. "Write clean code" changes nothing. "Run uv run pytest -q before finishing" does. Add the reason for unusual rules so the agent handles edge cases.
• Too long. Every line costs context on every prompt. Move rarely needed detail into folder-level files or imports.
• You wanted to hide files, not instruct. Use .geminiignore (gitignore syntax) to keep folders like archive/ out of tools that respect it; restart the session after changing it.

FAQ

Can Gemini write the file for me? Yes. /init analyzes the current folder and generates a tailored GEMINI.md. Treat it as a draft: run every command it lists before you trust it.

Does GitHub Copilot read GEMINI.md? GitHub's docs accept a single CLAUDE.md or GEMINI.md at the repository root as agent instructions; see our copilot-instructions.md examples for Copilot's own format.

Where do things Gemini "remembers" go? Its memory feature edits Markdown files: shared project facts go into repository GEMINI.md files and personal preferences into ~/.gemini/GEMINI.md. Review those edits like any other change to the file.

Get the matching files for every tool

The free AGENTS.md generator builds a starting GEMINI.md plus matching AGENTS.md, CLAUDE.md, Cursor, Copilot and Kiro files in your browser from your package.json or pyproject.toml. The AI Coding Agent Config Kit adds 12 stack templates and 12 prompts that audit and test them.

Keep reading