Bien organiser son projet avec Claude Code

Commencer ici : à quoi sert ce guide

Une nouvelle session IA oublie vos conventions et répète les erreurs de la veille. Ce guide organise instructions courtes, historique utile et format de réponse. Vous obtenez un dépôt compréhensible : règles actuelles dans CLAUDE.md, décisions dans l’historique convenu et passage de relais avec preuves. Ce n’est pas une mémoire automatique illimitée.

Un exemple concret

La réponse ci-dessous illustre le format attendu ; elle ne prétend pas auditer votre application. Elle permet de reconnaître une réponse utile. Suivez les étapes détaillées puis comparez fichiers, tests ou sorties réels à cet objectif. Si l’assistant répond seulement « terminé », demandez le livrable modifié, les preuves et ce qui reste à vérifier.

Read: CLAUDE.md and the latest handoff.
Task understood: fix the selected issue within the stated scope.
Report: changed files, actual checks, assumptions and next action.

Vous ouvrez Claude, expliquez votre projet, avancez… puis recommencez les mêmes explications à la session suivante. Un peu d’organisation permet de reprendre le travail beaucoup plus facilement.

Ce guide concerne Claude Code, l’outil de développement lancé dans votre projet. Ces fichiers et commandes ne configurent pas automatiquement une conversation classique sur claude.ai.

1. Donner une place à chaque information

Commencez par cette petite structure. Le dossier docs/ai/ est notre convention proposée, pas un dossier spécial reconnu automatiquement par Claude Code.

mon-projet/
├── CLAUDE.md                 # Consignes durables du projet
├── README.md                 # Présentation du projet
├── docs/
│   └── ai/
│       ├── handoff.md         # État actuel et prochaine étape
│       └── decisions.md       # Choix importants et raisons
└── src/                      # Code de l’application

Placez le fichier principal CLAUDE.md à la racine du projet. Vos préférences communes à tous les projets peuvent aller dans ~/.claude/CLAUDE.md. Sur un gros projet, un module peut avoir son propre CLAUDE.md pour ses conventions locales.

Commencez petit : un fichier à la racine et une note de reprise suffisent. Séparez davantage seulement si cela aide réellement.

2. Écrire un CLAUDE.md utile

Décrivez le produit, les commandes réelles du projet, vos règles de travail et la forme des réponses attendues. Gardez ce fichier concis : il ne doit pas devenir la copie complète de vos conversations.

Voici un modèle original. Remplacez les éléments entre crochets par des informations vérifiées. Les commandes sont des exemples pour un projet JavaScript : vérifiez-les ou adaptez-les avant utilisation.

# Projet
Produit : [ce que fait l’application et pour qui]
Stack : [langages, framework et base de données utilisés]
Dossiers importants : [où se trouve le code concerné]

# Commandes — à vérifier dans ce dépôt
- Développement : npm run dev
- Tests : npm test
- Build : npm run build

# Méthode de travail
- Agis comme un développeur senior pragmatique de cette stack.
- Lis les fichiers concernés avant de proposer une modification.
- Pour un bug, reproduis-le et explique d’abord la cause probable.
- Garde les changements ciblés et respecte les conventions existantes.
- Pose une question si une information manquante change la solution.
- Demande confirmation avant un déploiement en production
  ou une modification destructive des données.
- Ne stocke aucun mot de passe, jeton ou donnée personnelle ici.

# Continuité
- Pour reprendre une tâche, lis docs/ai/handoff.md.
- Note les choix importants et leurs raisons dans docs/ai/decisions.md.
- Avant de terminer, actualise la note avec des faits vérifiés.

# Réponses
- Réponds en français, clairement et sans longueur inutile.
- Commence par le résultat ou la prochaine décision utile.
- Indique les fichiers modifiés et pourquoi.
- Précise les vérifications réellement exécutées et leurs résultats.
- Signale les incertitudes et le travail restant.

Dans Claude Code, /init aide à créer une première version des consignes. Relisez le résultat. /context permet d’examiner le contexte chargé et /memory les fichiers de mémoire.

3. Donner un rôle, un objectif et une forme de réponse

« Tu es un expert » ne précise pas le travail attendu. Une bonne demande indique quoi examiner, ce qui constitue une réussite et ce que Claude doit expliquer ensuite.

Gardez le rôle durable dans CLAUDE.md et la tâche du moment dans votre message. Par exemple :

Rôle : Développeur senior sur cette application existante.
Contexte : La liste des projets a déjà des catégories et une recherche.
Objectif : Faire fonctionner ensemble catégorie et recherche.
Contraintes : Réutiliser le design actuel, sans nouvelle dépendance.
D’abord : Lire CLAUDE.md, docs/ai/handoff.md et les fichiers concernés.
Vérification : Tester catégorie seule, recherche seule, puis les deux.
Réponse : Résultat, fichiers modifiés, vérifications et points restants.
Si un besoin est ambigu, pose une question ciblée avant de coder.

Sur une partie inconnue du projet, ajoutez « Explique ton approche avant de modifier les fichiers ». Pour apprendre, ajoutez « Explique la raison de chaque étape importante ». Le rôle donne une perspective ; les critères concrets permettent de juger le résultat.

4. Distinguer les trois historiques

Il existe plusieurs formes de continuité. Chacune a son utilité.

• Les conversations : retrouvez un échange avec les commandes de session de Claude Code. Par défaut, les transcriptions sont dans ~/.claude/projects/<project>/<session-id>.jsonl. Laissez l’outil les gérer ; utilisez /export pour obtenir une copie lisible.
• La mémoire automatique : lorsqu’elle est activée, Claude conserve certains apprentissages dans un dossier local, normalement ~/.claude/projects/<project>/memory/. Ce n’est ni une transcription complète ni une note partagée avec l’équipe. Consultez-la avec /memory.
• La note de reprise du projet : un fichier court, par exemple docs/ai/handoff.md, que vous demandez explicitement à Claude de lire et de mettre à jour. Il peut être relu avec le code par vos collègues.

Une décision importante ne doit pas exister uniquement dans une ancienne conversation ou dans la mémoire automatique. Notez-la dans le projet avec sa raison.

5. Garder une note de reprise courte et exacte

Cette note doit expliquer ce qui est vrai maintenant. Actualisez l’état courant au lieu d’ajouter indéfiniment chaque échange. Distinguez ce qui est terminé de ce qui a seulement été envisagé.

# Tâche actuelle
Faire fonctionner ensemble la catégorie et la recherche.

## Terminé
- Logique de filtrage et composants concernés repérés.
- Choix confirmé : limiter aussi la recherche à la catégorie active.

## Vérifié
- Les tests existants passent avant modification.
- Le filtrage combiné n’a pas encore été testé.

## En cours
- Implémentation non terminée.

## Prochaine étape
Ajouter le cas combiné, l’implémenter et vérifier l’interface.

## Références
- Fichiers concernés : [chemins réels du dépôt]
- Décisions : docs/ai/decisions.md

Dans decisions.md, notez une date, le choix et sa raison. Exemple : « 2026-10-24 — Réutiliser la recherche existante pour que catégorie et mots-clés suivent une règle cohérente. »

La note sert uniquement si Claude la lit. Référencez-la dans les consignes et dans votre message de reprise. Mettre un fichier Markdown dans docs/ ne le charge pas automatiquement.

6. Reprendre la bonne conversation

Depuis le dossier du projet, cette commande de terminal reprend la conversation la plus récente :

claude --continue

Utilisez claude --resume pour choisir une conversation enregistrée. Dans une session Claude Code, /resume ouvre également le sélecteur. Les conversations disponibles dépendent de celles conservées dans votre environnement.

• /compact résume la conversation actuelle pour libérer du contexte. Le résumé peut perdre des détails : conservez les décisions importantes dans les fichiers du projet.
• /clear repart avec un nouveau contexte de conversation. Cela ne remplace pas une note de reprise et ne supprime pas vos consignes de projet.
• /memory permet d’examiner la mémoire au lieu de supposer ce que Claude a retenu.

Pour une reprise propre, envoyez : « Lis CLAUDE.md et docs/ai/handoff.md. Résume l’état actuel, indique ce qui doit être revérifié, puis poursuis la prochaine étape. »

7. Bien terminer chaque session

Avant de vous arrêter, donnez cette demande à Claude.

Actualise docs/ai/handoff.md avec l’objectif, le travail terminé,
les vérifications effectuées, ce qui reste et la prochaine action.
Note les décisions importantes et leurs raisons dans docs/ai/decisions.md.
Ne copie pas toute la conversation et n’inclus aucun secret.
Ne déclare pas une vérification réussie sans l’avoir exécutée.
Donne-moi ensuite un court message pour reprendre la prochaine session.

Cette dernière phrase transforme « On en était où ? » en prochaine action concrète. Relisez vous-même la note avant de vous y fier.

8. Votre mise en place en cinq minutes

1. Ajoutez un CLAUDE.md court à la racine du projet.
2. Remplacez les commandes d’exemple par celles vérifiées pour ce projet.
3. Créez les notes de reprise et de décisions si elles sont utiles.
4. Commencez une petite tâche avec objectif, contraintes et vérification.
5. Vérifiez le résultat, actualisez la note et relisez les modifications.

Télécharger le kit de départ avec CLAUDE.md, les deux modèles de notes et un README. Le kit est en anglais. Décompressez-le d’abord dans un dossier temporaire et fusionnez les fichiers avec vos consignes existantes.

Références officielles

Vérifiées le 24 octobre 2026. Les exemples et le dossier docs/ai/ constituent notre méthode proposée ; ces liens expliquent les fonctions intégrées de Claude Code.

• Consignes de projet et mémoire
• Gérer et reprendre les sessions
• Commandes du terminal
• Bonnes pratiques de travail
• Contexte et formulation des demandes

Read this tutorial as reference material:
https://nethanelfitoussi.com/article/claude-md-project-organization?lang=en

Goal: apply the documented workflow to my development project.
Read the existing project instructions, inspect the relevant files and explain the smallest useful setup.

Available starter files:
https://nethanelfitoussi.com/tutorials/claude-project-starter.zip
Download and inspect these files in a temporary folder before using them. Do not overwrite existing project instructions.

If I have not supplied a project folder, ask which development project to use. Do not invent a repository URL.

Adapt example paths, commands and acceptance criteria to this repository rather than assuming they match.

Give me a short plan, then make the agreed local changes and run the relevant checks. Report actual results and anything not verified. Stop before credentials, paid services, production changes, push, merge or deployment.