Context Files (GEMINI.md)

Fresh

Context files give the agent persistent knowledge about your project — stack, conventions, rules, and constraints.

File Locations & Scope

flowchart TD
    A["~/.gemini/GEMINI.md — Global, all projects"] --> B
    B["project-root/GEMINI.md — This project"] --> C
    C["subdirectory/GEMINI.md — This module"]
    note["More specific overrides more general"]

Location	Scope
~/.gemini/GEMINI.md	All projects on your machine
[project-root]/GEMINI.md	Entire project (detected by .git folder)
[subdir]/GEMINI.md	Specific module, feature, or component

Project root is identified by the nearest .git folder or your home directory.

Example Context File

# My Project Context

## Tech Stack
- React 19, TypeScript 5.5
- Supabase (PostgreSQL + Auth)
- Tailwind CSS 4
- Vitest for unit tests, Playwright for E2E

## Code Conventions
- Functional components only (no class components)
- Custom hooks for all reusable logic
- TanStack Query for all API data fetching
- Error boundaries required at route level

## File Structure
src/
  components/   # Reusable UI components
  features/     # Feature-based modules (co-located tests)
  hooks/        # Shared custom hooks
  lib/          # External service wrappers

## Testing Rules
- Unit tests in __tests__ beside source files
- Mock all external APIs in tests
- Min 80% coverage for business logic files

## Rules
- Never use 'any' or 'unknown' TypeScript types
- Never mutate state directly
- Always use service layer (never fetch() directly in components)
- All async functions must handle errors

IntelliJ: AGENT.md

JetBrains IDEs support either GEMINI.md or AGENT.md at project root.

Include files inline in your prompts:

@src/lib/auth.ts Can you add token refresh logic here?

What to Include

Keep context focused

Too much context dilutes the signal. Include things that differ from defaults or commonly trip up AI tools.

Good to include:

• Tech stack with specific versions
• Project-specific naming conventions
• Internal API patterns the agent should follow
• Things to NEVER do in this codebase
• File structure and where things live
• Testing approach

Skip:

• Generic best practices the model already knows
• Obvious things about the language/framework
• Content from public documentation