GEMINI.md : donner du contexte projet à Gemini CLI

Un GEMINI.md est le fichier de contexte que Gemini CLI lit automatiquement au démarrage. Vous y décrivez votre projet une fois (stack, commandes, conventions), et l'agent en tient compte à chaque demande, sans que vous ayez à le répéter. C'est l'équivalent du CLAUDE.md de Claude Code. Ce guide vous montre comment générer un GEMINI.md avec /init, quoi y mettre, et comment fonctionne la hiérarchie entre fichier global, fichier de projet et sous-dossiers. Il s'adresse à toute personne qui veut des réponses adaptées à son dépôt plutôt que génériques.

Ce que vous allez apprendre

• Ce qu'est un GEMINI.md et pourquoi il change la qualité des réponses
• Générer un GEMINI.md adapté à votre projet avec /init
• Quoi écrire dedans (et ce qu'il vaut mieux éviter)
• La hiérarchie global / projet / sous-dossiers et comment l'inspecter
• Vérifier que votre contexte est bien chargé

Prérequis

• Gemini CLI installé et une première session réussie. Voir Installer Gemini CLI et Prise en main du REPL.
• Un projet (même petit) ouvert dans votre terminal.

GEMINI.md, c'est quoi ?

C'est un simple fichier Markdown, placé à la racine de votre projet, que Gemini CLI charge automatiquement au lancement. Son contenu rejoint le contexte de l'agent : vos conventions, vos commandes de test, l'architecture du projet deviennent des informations qu'il connaît d'emblée.

L'effet est concret. Sans contexte, l'agent devine. Avec un GEMINI.md, il applique vos règles. Lors de la validation de ce guide, un GEMINI.md contenant la consigne « commence ta réponse par [DEMO-INVENTAIRE] » a bien été respecté dès le premier prompt, et l'agent décrivait correctement le projet sans qu'on le lui explique :

> En une phrase, que fait ce projet ?
[DEMO-INVENTAIRE] Ce projet est un script Python permettant de lister les
serveurs enregistrés dans une base de données SQLite.

L'équivalent du CLAUDE.md

Si vous venez de Claude Code, GEMINI.md joue exactement le rôle du CLAUDE.md : un mémo de projet versionné, lu à chaque session. La logique est la même, seul le nom de fichier change.

Générer un GEMINI.md avec /init

Le plus simple est de laisser l'agent l'écrire à partir de votre code. Dans le REPL, lancez :

> /init

D'après l'aide intégrée, /init « analyse le projet et crée un GEMINI.md sur mesure ». L'agent lit vos fichiers clés (README, gestionnaire de dépendances, code source) et génère un fichier structuré. Sur un petit projet Flask de test, la génération a produit un fichier complet et exploitable :

# GEMINI.md - Init Demo

## 1. Description du Projet
Init Demo est une application web minimale développée en Python avec Flask...

## 2. Stack Technique
- Langage : Python 3.x
- Framework Web : Flask 3.1.0 (défini dans requirements.txt)
- Structure : src/app.py (point d'entrée), requirements.txt

## 3. Commandes Utiles
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
flask --app src.app run --debug
curl http://127.0.0.1:5000/health

## 4. Conventions de Code
- PEP 8, imports ordonnés, formatage via black ou ruff
- Dépendances épinglées dans requirements.txt
- API : réponses JSON, gestion d'erreurs avec codes HTTP appropriés

Traitez ce fichier généré comme un brouillon : relisez-le, corrigez ce qui est faux ou inventé, ajoutez ce que l'agent ne pouvait pas deviner.

Repartez du généré, ne gardez pas tout

/init est rapide mais générique. Le GEMINI.md qui vous fera gagner du temps contient surtout ce qui ne se lit pas dans le code : pourquoi telle bibliothèque, quelles zones à ne pas toucher, la commande de test exacte, vos règles d'équipe.

Quoi écrire dans un GEMINI.md

Un bon fichier reste court et actionnable. Les rubriques qui rapportent le plus :

• Description : ce que fait le projet, en deux ou trois phrases.
• Stack et structure : langages, frameworks, où se trouve quoi.
• Commandes réelles : installer, lancer, tester, linter. L'agent les réutilisera telles quelles, donnez les vraies.
• Conventions : style de code, nommage, façon de gérer les erreurs.
• Garde-fous : ce qu'il ne faut pas modifier (migrations, fichiers générés, secrets).

Épingler les versions, jamais de secrets

Indiquez les versions exactes de vos dépendances dans le GEMINI.md comme dans votre code (flask==3.1.0, image Docker par digest) : l'agent propose alors des commandes reproductibles. À l'inverse, aucun secret dans ce fichier : il est versionné dans Git et lu à chaque session.

La hiérarchie : global, projet, sous-dossiers

Gemini CLI ne lit pas un seul GEMINI.md, il combine plusieurs niveaux :

Niveau	Emplacement	Usage
Global	~/.gemini/GEMINI.md	Vos préférences pour tous vos projets
Projet	./GEMINI.md (et dossiers parents)	Le contexte du dépôt courant
Sous-dossier	GEMINI.md dans un sous-répertoire	Contexte local à un module

Glissez pour voir

Le troisième niveau se découvre au fil de l'eau : un GEMINI.md rangé dans un sous-répertoire n'est pas chargé au démarrage, mais quand l'agent accède à un fichier de ce répertoire. C'est la même logique que la hiérarchie de projet, appliquée à la demande plutôt qu'en une seule passe initiale.

Les contenus s'additionnent, du plus général au plus spécifique. Le sous-menu /memory permet d'inspecter ce qui est réellement chargé :

Commande	Rôle
/memory list	Lister les chemins des GEMINI.md en cours d'utilisation
/memory show	Afficher le contenu mémoire combiné
/memory reload	Recharger après une modification
/memory refresh	Le même rechargement, sous son autre nom

Glissez pour voir

La quatrième ligne évite une perte de temps : refresh et reload sont la même commande, la première étant un alias de la seconde. Vous croiserez les deux noms dans la documentation amont, y compris sur des pages qui se contredisent en apparence.

Seuls les fichiers réellement présents sont chargés. Dans un projet qui n'a qu'un GEMINI.md à sa racine, /memory list confirme un seul fichier, et /memory show l'affiche sous une section Project avec son chemin absolu :

> /memory list
ℹ There are 1 GEMINI.md file(s) in use:

> /memory show
ℹ Current memory content from 1 file(s):
  --- Project ---
  --- Context from: /home/bob/Projets/.../gemini-md-demo/GEMINI.md ---
  # Contexte projet - demo-inventaire
  ...
  --- End of Context ---

Ajoutez un ~/.gemini/GEMINI.md et il apparaîtra en plus, dans une section globale : les niveaux se cumulent, du global au plus local.

Modifié ? Rechargez

Si vous éditez un GEMINI.md pendant une session, lancez /memory reload pour que l'agent prenne en compte la nouvelle version sans redémarrer.

Découper un GEMINI.md trop gros avec les imports

Un fichier de contexte qui grossit finit par poser le problème qu'il devait résoudre : il est lu en entier à chaque requête, y compris les trois quarts qui ne servent pas. La parade tient dans les imports, avec la syntaxe @chemin/vers/fichier.md posée directement dans le corps du GEMINI.md :

# Contexte projet

Stack : FastAPI, PostgreSQL, pytest.

@./docs/conventions-api.md
@../partage/guide-de-style.md

Le chemin est relatif au fichier qui contient l'import, et les contenus importés sont insérés à l'endroit de l'appel. Vous gagnez deux choses : des fichiers thématiques qu'on relit sans faire défiler, et la possibilité de partager un même bloc de conventions entre plusieurs dépôts sans le recopier.

Changer le nom du fichier de contexte

GEMINI.md est un nom par défaut, pas une obligation. Le réglage context.fileName de settings.json accepte un nom, ou une liste de noms tous reconnus :

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

L'intérêt est concret dans un dépôt où plusieurs agents se croisent : plutôt que d'entretenir un fichier de contexte par outil, avec le risque habituel qu'ils divergent, vous déclarez le fichier commun que votre équipe utilise déjà.

Vérifier que le contexte est bien chargé

Deux réflexes simples :

1. Lister et afficher ce qui est chargé avec /memory list (le nombre de fichiers) puis /memory show : vous devez y voir le chemin de votre GEMINI.md de projet, sous la section Project.

2. Tester une règle : ajoutez une consigne facile à vérifier, par exemple un préfixe imposé dans les réponses, lancez /memory reload, puis posez une question. Si la règle est appliquée, le contexte est bien pris en compte.

À retenir

1. GEMINI.md est un fichier Markdown chargé automatiquement : il donne à l'agent le contexte de votre projet, comme le CLAUDE.md de Claude Code.
2. /init génère un premier GEMINI.md à partir de votre code ; relisez et corrigez le résultat.
3. Mettez-y surtout ce qui ne se lit pas dans le code : commandes réelles, garde-fous, conventions d'équipe.
4. Épinglez les versions, ne mettez jamais de secret (le fichier est versionné).
5. La hiérarchie global / projet / sous-dossier se combine ; inspectez-la avec /memory list et /memory show, rechargez avec /memory reload, que vous verrez aussi sous le nom /memory refresh.
6. Un fichier devenu trop gros se découpe par imports (@fichier.md), et son nom se change par context.fileName si votre équipe utilise déjà un autre fichier de contexte.

Prochaines étapes

Prise en main du REPL Les commandes /, les fichiers @ et le mode shell ! au quotidien.

Gemini CLI : le hub complet Le pilier de la formation et tous les guides par phase.

Claude Code : le hub L'autre grand agent CLI et son fichier de contexte CLAUDE.md.

Installer Gemini CLI Revenir à l'installation et à l'authentification.

×

📖 Voir la documentation →