import { Callout } from '@/components/ui/callout';
"What exactly should I put in GEMINI.md?" — this is one of the most common questions I hear from developers starting with Gemini CLI. The official guidance says "describe your project context," but the moment you open your repo and start writing, you hit a thousand small decisions about what to include and what to leave out.
After iterating on GEMINI.md across several projects of my own, one thing became clear: the template that works depends heavily on the project type. A Next.js frontend codebase and a Python data pipeline have completely different priorities for what the agent needs to know.
This article shares four GEMINI.md templates I've actually used in production, organized by project type. Copy them, adapt them to your situation, and you should be able to skip the awkward "what do I write here?" phase entirely.
Three Principles That Make GEMINI.md Effective
Before the templates, let me share three rules of thumb that hold across every project.
First, don't write what the code already shows. Listing dependencies that package.json already declares, or rebuilding the directory tree the agent can see, just burns context window for no value. GEMINI.md exists to communicate the implicit rules that aren't in code.
Second, lean on prohibitions. "Don't do X" tends to be more effective than "do Y." In my experience, adding a clear list of forbidden patterns improves the agent's output quality by a noticeable 30–40%.
Third, keep it under 500–1500 tokens. This directly affects Gemini CLI's response quality. Longer is not better. Trim to the essentials and the agent's decisions become both faster and sharper.
Example 1: Next.js + TypeScript Web App
The most common case. With frontend, backend, and database concerns mixed together, missing context here often leads the agent to start unwanted refactors.
# Project Overview
This repo is a SaaS dashboard built on Next.js 16 (App Router) with TypeScript
and Tailwind CSS. It deploys to Cloudflare Workers, with Stripe handling billing.
## Architectural Assumptions
- App Router only. Never convert to the Pages Router (`pages/` directory)
- Server Components by default. Add "use client" only when useState/useEffect is required
- Data fetching: prefer Server Actions or Route Handlers. Don't introduce SWR or React Query
- Auth is Auth.js v5 (formerly NextAuth). Don't swap for Clerk or Firebase Auth
## Directory Conventions
- `src/app/` — App Router routes
- `src/components/ui/` — reusable UI primitives (shadcn/ui base)
- `src/lib/` — business logic, DB clients, Stripe helpers
- `src/server/` — server-only code (importing from client is forbidden)
## Things to Avoid
- The `any` type (use `unknown` + type guards instead)
- Data fetching in `useEffect` (handle it in Server Components)
- Direct `process.env` access (route through the zod-validated `src/lib/env.ts`)
- Leaving `console.log` in production code (use Sentry)
## Tests and Lint
- After any change, run `pnpm tsc --noEmit` and `pnpm lint`
- Unit tests use Vitest, E2E uses Playwright
- Migrations: `pnpm db:generate` then `pnpm db:migrate`The "things to avoid" section is the workhorse here. Next.js has so many overlapping APIs (old and new) that agents will happily generate pages/-style code or useEffect data fetching unless you explicitly forbid it.
Example 2: Python Data Science / ML Pipeline
When notebooks and .py modules coexist, the priorities are reproducibility and memory awareness.
# Project Overview
ML pipeline that segments e-commerce customers from purchase logs.
Training data lives in BigQuery, features in Feast, model registry in MLflow.
## Environment
- Python 3.12 (managed by Poetry)
- Core libraries: pandas 2.x, polars 0.20+, scikit-learn 1.5+, lightgbm 4.x
- No GPU available (cost reasons). Stick to CPU training with XGBoost or LightGBM
## Data Scale and Cautions
- Purchase logs: 8M rows/month, ~100M rows/year
- Loading the full dataset with pandas blows up memory. **Prefer polars or DuckDB**
- Always test BigQuery queries with `LIMIT` before running for real
- Filter on partition column (`event_date`) — full scans get expensive fast
## Experiment Management
- Every experiment is logged to MLflow. Don't keep results local-only
- Register features through Feast before using them. Don't feed notebook DataFrames
directly into models
- Pin random seeds: `RANDOM_STATE = 42` in every experiment
## Things to Avoid
- `pandas.read_csv()` on files >100MB (use polars or `chunksize`)
- DataFrame mutation inside `for` loops (vectorize or use `.apply()`)
- Saving models with `pickle` (use `MLflow.sklearn.log_model`)
- Hardcoding credentials in notebook cells (use `.env` + `python-dotenv`)
## Code Style
- Type hints required (`from typing import ...`)
- Docstrings in Google style
- Formatter: ruff (black-compatible config)What works especially well in data projects is stating the data scale upfront. Code that runs on 100 sample rows looks completely different from code that runs on 100M rows. Once the agent knows the scale, it stops suggesting fragile small-data patterns.
Example 3: CLI Tool / Open Source Library
For a CLI or library you ship publicly, the priorities are user experience and backward compatibility.
# Project Overview
Rust-based CLI that converts Markdown files to PDF.
Published on crates.io with ~2,000 monthly downloads.
## User Base
- Developers and technical writers who write docs in Markdown
- Mostly macOS/Linux users (Windows support must be maintained)
- Installation via `cargo install` or Homebrew
## Design Principles
- **Backward compatibility is paramount**: never rename CLI flags
- New features ship opt-in (don't change existing behavior)
- Error messages are English only (no i18n)
- Binary size stays under 5MB (be careful adding dependencies)
## Directory Layout
- `src/main.rs` — CLI entrypoint (parsed with clap)
- `src/lib.rs` — public library API
- `src/converter/` — conversion logic (extracted for testability)
- `tests/` — integration tests (run with `cargo test`)
## Things to Avoid
- Renaming existing CLI flags (`--input`, `--output`, `--theme`)
- Adding dependencies, especially C-binding ones (consult before adding)
- Using `unsafe` blocks
- `.unwrap()` calls that can panic (return `Result` with proper error types)
## Release Flow
1. Bump version in `Cargo.toml` (strict semver)
2. Update `CHANGELOG.md`
3. Verify with `cargo publish --dry-run`
4. Merge PR — GitHub Actions publishes to crates.io automaticallyFor public libraries, "don't break things" matters far more than "ship features." Agents tend to add convenience APIs and tidy up signatures, so explicit guardrails go a long way.
Example 4: React Native / Expo Mobile App
The platform differences and native module concerns make this its own category.
# Project Overview
iOS/Android meditation and sleep app, built on Expo SDK 53 + React Native 0.76.
EAS Build for builds, TestFlight / Google Play Internal Testing for distribution.
## Tech Stack
- Expo SDK 53 (managed workflow)
- React Native 0.76 (New Architecture enabled)
- State: Zustand (Redux is not used)
- Navigation: Expo Router v3
- Database: Supabase (Postgres + Realtime)
- Billing: RevenueCat
## Platform Differences
- Branch on `Platform.OS` only when behavior must differ; always leave a comment
- Use `useSafeAreaInsets()` for iOS safe area (don't use `SafeAreaView`)
- Status bar handled via `expo-status-bar` on Android
- All sound and haptic feedback goes through `expo-haptics`
## Things to Avoid
- Adding `react-native-*` native modules (breaks managed workflow)
- Suggesting `eject`
- iOS-only or Android-only logic without a `Platform.OS` check
- Heavy `AsyncStorage` reads/writes at startup (slows cold start)
## Store Review Considerations
- All in-app purchases go through RevenueCat (Apple/Google compliance)
- Avoid health-related claims ("treats," "cures," etc.) in UI text
- Privacy policy link must be reachable from the settings screen
## Build & Distribution
- Dev: `npx expo start`
- Production build: `eas build --platform all --profile production`
- Store submission: `eas submit`A surprising side-effect of including the "store review" section: the agent's generated copy and UI text naturally drift toward safer wording, which saves you from rewriting strings later.
Patterns That Worked Across All Four
Looking at the four examples side by side, several patterns stand out.
Including 2–3 "bad → good" pairs was effective in every project type. Concrete contrasts like "useEffect data fetching → Server Components" communicate intent far more efficiently than long prose.
Spelling out "what goes where" matters too. Without explicit rules about src/components/ui/ versus src/components/feature/, agents will scatter files in plausible-but-wrong locations.
Pinning versions is an easy win. Writing "React Native 0.76" or "Next.js 16" stops the agent from suggesting deprecated APIs (like componentWillMount) that exist in older docs.
For maintenance, the draft.md → GEMINI.md workflow described in How to Set Up GEMINI.md keeps the file from going stale. Drop quick notes into draft.md as you work, then once a month let Gemini CLI restructure them into the production GEMINI.md.
Wrapping up
How many GEMINI.md templates you have on hand directly shapes your productivity with Gemini CLI. Pick the one closest to your current project, spend 30 minutes adapting it, and you'll likely notice the agent making sharper suggestions on day one.
If you want to dig deeper into the surrounding tooling, the Gemini CLI complete guide and Gemini CLI Plan Mode walk through the broader agent workflow that GEMINI.md plugs into.