Skip to content

Bonnes pratiques — Travailler efficacement avec un coding agent

Document de référence personnel pour démarrer un nouveau projet en collaboration avec Claude Code (ou tout autre coding agent). Synthèse de retours d'expérience et de patterns qui réduisent significativement la consommation de tokens et améliorent la qualité des livrables.

1. Principes fondamentaux

1.1 Le coût caché : la redécouverte

À chaque nouvelle conversation, un coding agent arrive avec zéro contexte sur ton projet. Sans préparation, il va : - Scanner ton arborescence - Lire des fichiers au hasard pour comprendre le stack - Re-déduire les conventions de code à partir d'exemples - Poser des questions auxquelles tu as déjà répondu 10 fois

Chacune de ces actions consomme des tokens. Sur la durée d'un projet, c'est le premier poste de gaspillage.

La règle d'or : ce qui est documenté à l'avance n'a pas besoin d'être redécouvert.

1.2 Le bon découpage : une session = une unité de travail

  • Trop court (un prompt = un fichier) : tu perds en cohérence, les sessions ne voient pas la vision globale
  • Trop long (une session = une phase entière) : le contexte gonfle, l'agent perd le focus, et un échec en milieu de phase pollue tout le reste
  • Bon équilibre : une session = une story / une PR raisonnable. ~2-8 heures de travail humain équivalent.

1.3 La documentation comme code

Traiter la documentation projet avec la même rigueur que le code : - Versionnée dans le repo (Git) - Maintenue à jour au fil des livraisons - Avec une distinction claire entre vivant (source de vérité) et historique (archivé)

2. Structure de projet recommandée

mon-projet/
├── CLAUDE.md                      # Instructions pour le coding agent (racine)
├── README.md                      # Documentation humaine standard
├── docs/
│   ├── architecture/              # Specs vivantes
│   │   ├── overview.md
│   │   ├── data-model.md
│   │   └── ...
│   ├── decisions/                 # ADRs (Architecture Decision Records)
│   │   ├── 001-choix-stack.md
│   │   ├── 002-pattern-X.md
│   │   └── ...
│   ├── progress.md                # Journal des livraisons
│   ├── <phase-en-cours>/          # Tickets/specs de la phase active
│   └── archive/                   # Specs historiques des phases livrées
│       └── <phase-livrée>/
└── src/
    └── ...

3. Le fichier CLAUDE.md

C'est le fichier qui fait la différence. Claude Code le lit automatiquement au démarrage de chaque session.

3.1 Sections recommandées

# <Nom du projet>

## Vision

Une à deux phrases qui décrivent ce qu'est le projet et pour qui.

## Stack technique

- Langage / framework principal et version
- Base de données
- Outils de build / déploiement
- Choix techniques structurants (ex : monorepo, microservices, monolithe modulaire)

## Structure du repo

- `src/<projet-A>/` — description courte
- `src/<projet-B>/` — description courte
- `tests/` — où vivent les tests
- `docs/` — où vivent les specs

> Utilise des `Read` ciblés. Inutile de lister les dossiers en premier.

## Documentation

- Specs vivantes : `docs/architecture/`
- Décisions : `docs/decisions/`
- Progrès : `docs/progress.md`
- Phase active : `docs/<phase-name>/`
- ⚠️ `docs/archive/` contient des specs historiques, à ne PAS utiliser comme référence

## Conventions de code

- Style (ex : EditorConfig, Prettier, conventions de nommage)
- Patterns à respecter (ex : Repository, MediatR, ADR-driven)
- Patterns à éviter (ex : pas de logique métier dans les controllers)
- Politique de tests (couverture, types de tests obligatoires)

## Commandes courantes

```bash
# Build
<commande>

# Tests
<commande>

# Lancement local
<commande>

# Migration DB
<commande>

État du projet

Phases livrées : - ✅ Phase A : - ✅ Phase B : - 🚧 Phase C : - ⏳ Phase D : à venir

Pièges connus

  • Toujours vérifier les versions des paquets au moment de l'ajout

Workflow de travail

  1. Lis le ticket cible dans docs/<phase-active>/
  2. Lis progress.md pour les écarts récents
  3. Propose un plan avant d'implémenter
  4. Implémente, teste, valide les critères d'acceptation
  5. Propose une mise à jour de progress.md à la fin

### 3.2 Ce qu'il NE faut PAS mettre

- Tout le détail des stories (elles sont dans `docs/`)
- L'historique du projet (il est dans `progress.md`)
- Des choses qui changent souvent (la liste des contributeurs, les versions exactes des paquets)

Le `CLAUDE.md` doit rester **stable et synthétique**. Si tu le modifies plus d'une fois par phase, c'est qu'il déborde.

---

## 4. Les ADRs (Architecture Decision Records)

### 4.1 Format minimal recommandé

```markdown
# ADR-XXX — <Titre court de la décision>

**Date** : YYYY-MM-DD  
**Statut** : Accepté | Remplacé par ADR-YYY | Obsolète

## Contexte

2-4 phrases qui expliquent le problème à résoudre et pourquoi
il fallait choisir.

## Décision

La décision prise, en 1-3 phrases. Affirmative et claire.

## Conséquences

- Conséquence positive 1
- Conséquence positive 2
- Trade-off ou conséquence négative acceptée
- Ce que ça empêche / contraint pour la suite

4.2 Quand créer un ADR

À chaque fois que tu prends une décision qui : - Sera difficile à inverser plus tard - Va susciter des "pourquoi a-t-on fait ça ?" dans 3 mois - Touche un choix structurel (architecture, stockage, pattern, sécurité)

Pas pour : les choix de détail (nom de variable, structure de dossier intra-projet, micro-décisions).

4.3 Numérotation et fichiers

  • 001-, 002-, 003- ... append-only (jamais réutiliser un numéro)
  • Si une décision en remplace une autre : nouveau ADR avec statut "Accepté", l'ancien passe à "Remplacé par ADR-XXX"
  • Garder les ADRs obsolètes en place — ils racontent l'évolution du raisonnement

5. Le journal progress.md

5.1 Pourquoi

C'est le pont entre l'intention (tickets) et la réalité (code). Sans lui, l'agent doit deviner les écarts en lisant le code, ce qui consomme énormément de tokens et reste imparfait.

5.2 Format

Append-only, une entrée par phase ou jalon livré :

## Phase X — <Titre> — Terminée le YYYY-MM-DD

Stories livrées : X-01, X-02, X-03.

### Décisions d'implémentation

- <Décision concrète prise pendant l'implémentation, non triviale>
- <Autre décision>

### Écarts vs tickets

- Story X-02 : <ce qui a été fait différemment et pourquoi>
- <Autre écart>

### Fichiers clés créés ou modifiés

- `src/path/to/important-file.cs`
- `docs/decisions/00X-decision.md` (nouveau ADR créé)

### Notes pour la suite

- <Point d'attention pour la phase suivante>
- <Dette technique consciente, à traiter plus tard>

5.3 Discipline

À mettre à jour à la fin de chaque session productive, pas une fois tous les 36 du mois. C'est ce qui permet à la session suivante de démarrer en 50 tokens au lieu de 5000.

6. Découpage du travail en phases et tickets

6.1 Granularité d'une phase

Une phase = un livrable qui apporte de la valeur testable de bout en bout.

Mauvais exemple : "Phase 1 : modèle de données" (pas testable seul).
Bon exemple : "Phase 1 : Squelette de communication agent ↔ serveur" (on peut valider que la mécanique fonctionne, même sans logique métier).

Estimation cible : 1 à 3 semaines de travail part-time. Au-delà, redécouper.

6.2 Granularité d'une story

Une story = une PR raisonnable. Quelques heures à un jour de travail effectif.

Tests d'une bonne granularité : - Tu peux la décrire en 1 phrase - Elle a 3-7 critères d'acceptation - Elle bloque ou est bloquée par 0 à 3 autres stories - Elle ne mélange pas plusieurs préoccupations (ex : "Implémenter X et son UI" → 2 stories)

6.3 Format de ticket pour coding agent

# Story X-NN — <Titre>

| Champ | Valeur |
|---|---|
| Type | Story |
| Phase | <lettre> |
| Estimate | <points> |

## Description

Contexte court : pourquoi cette story existe.

## Tâches

Liste ordonnée et concrète. Pas de "réfléchir à", uniquement des actions vérifiables.

- Créer le fichier X
- Implémenter la méthode Y avec la signature Z
- Ajouter les tests T1, T2, T3

## Critères d'acceptation

- ✅ <Critère vérifiable de manière objective>
- ✅ <Autre critère>

## Dépendances

- Bloqué par : X-NN
- Bloque : X-MM

## Points de vigilance

Ce qui peut mal se passer ou ce qui est facile à oublier.

L'agent peut implémenter directement sans poser 10 questions de clarification.

7. Workflow de session

7.1 Démarrage d'une session

Prompt minimal recommandé :

Story à implémenter : `docs/<phase>/<story>.md`

État : phases A, B, C livrées (voir progress.md). Story en cours : <X-NN>.

Procède : lis le ticket, propose ton plan d'attaque, implémente, lance les tests.

C'est tout. Le CLAUDE.md fait le reste.

7.2 Pendant la session

  • Laisse l'agent travailler par lots, mais valide les choix architecturaux significatifs avant qu'il code 500 lignes dans la mauvaise direction
  • Si tu fais un écart vs le ticket, dis-le explicitement ("On va faire X au lieu de Y, parce que Z") pour que ce soit ajouté à progress.md
  • Refuse les sessions qui dérivent : si à mi-chemin tu réalises que la story n'est pas la bonne, arrête, redécoupe, recommence proprement

7.3 Fin de session

Demander explicitement à l'agent :

Avant de terminer :
1. Récapitule ce qui a été fait
2. Liste les écarts vs le ticket (s'il y en a)
3. Propose une mise à jour de progress.md
4. Liste les éventuels nouveaux ADRs à créer

Tu valides, tu commits, tu fermes la session.

8. Cycle de vie de la documentation

8.1 Pendant une phase active

docs/
├── architecture/         # vivant
├── decisions/            # vivant, append-only
├── progress.md           # vivant
└── <phase-active>/       # vivant, c'est le workspace
    ├── README.md
    ├── epic-*.md
    └── *-story-*.md

8.2 À la livraison d'une phase

Étape 1 — Promotion

Avant d'archiver, extraire ce qui mérite de vivre : - Schémas de données → docs/architecture/data-model.md - Diagrammes d'architecture → docs/architecture/ - Décisions structurelles → nouveaux ADRs dans docs/decisions/ - Contrats d'API → docs/architecture/api-contract.md ou pointeur vers le fichier source

Étape 2 — Archivage

docs/
├── archive/
│   └── <phase-livrée>/
│       ├── README.md   ← warning : "ne pas utiliser comme spec courante"
│       └── (anciens tickets)

Étape 3 — Mise à jour CLAUDE.md

  • Section "État du projet" : marquer la phase comme livrée
  • Pointeur vers la nouvelle phase active
  • Vérifier que le warning sur docs/archive/ est toujours présent

8.3 À la fin du projet

Soit : - Tout est en production stable → docs/archive/ peut tout absorber, docs/architecture/ reste comme référence - Le projet est abandonné → garder l'archive complète pour valeur historique

Ne jamais supprimer purement et simplement les anciennes specs. Elles ne coûtent rien en stockage et peuvent rendre service.

9. Optimisations spécifiques à Claude Code

9.1 Préempter les exploration coûteuses

Dans CLAUDE.md, lister explicitement la structure du repo évite que l'agent fasse tree ou find au démarrage. Économie typique : quelques milliers de tokens par session.

9.2 Référencer, ne pas copier

Au lieu de copier le contenu d'un ticket dans le prompt :

❌ Voici le ticket : [paste de 800 lignes]
✅ Implémente la story 'docs/phase-c/C-02.md'

L'agent lit le fichier lui-même. Tu économises les tokens du copy-paste, et l'agent voit le ticket dans son contexte naturel (à côté des autres tickets, qu'il peut consulter si besoin).

9.3 Sessions courtes et ciblées

Une nouvelle conversation est gratuite (pas de token consommé pour démarrer). Ce qui coûte, c'est le contexte accumulé. Donc : - Démarre une nouvelle session pour chaque story - Ne crains pas de "perdre" le contexte — il est dans CLAUDE.md et progress.md - Une session qui dérive ou qui bug : tue-la, relance proprement

9.4 Demander des plans avant l'implémentation

Pour les stories complexes :

Lis le ticket. Avant d'écrire le moindre code, propose-moi :
1. Les fichiers que tu vas créer/modifier
2. Les choix d'implémentation principaux
3. Les éventuelles ambiguïtés du ticket à lever

J'attends ton plan avant que tu commences à coder.

Coût : faible (l'agent réfléchit, mais c'est court). Bénéfice : tu évites une implémentation à jeter.

9.5 Capacités natives à exploiter

  • Read ciblé sur les bons fichiers (le CLAUDE.md aide à pointer vers les bons fichiers)
  • Grep plutôt que lecture intégrale quand on cherche un pattern
  • Edit plutôt que Write quand on modifie un fichier existant
  • Lancement de tests par l'agent lui-même pour valider avant de rendre

Si tu vois l'agent lire 15 fichiers pour rien, ton CLAUDE.md ou tes specs ont un trou. C'est un signal.

10. Checklist de démarrage d'un nouveau projet

À faire avant d'écrire la première ligne de code avec un coding agent :

  • [ ] Créer le repo Git
  • [ ] Rédiger un CLAUDE.md initial (sections : vision, stack, structure prévue, conventions, commandes, workflow)
  • [ ] Créer la structure docs/ : architecture/, decisions/, progress.md
  • [ ] Rédiger un plan macro du projet (phases, jalons, vision long terme) dans docs/architecture/overview.md
  • [ ] Identifier la première phase, créer son dossier docs/<phase-1>/
  • [ ] Découper la première phase en stories avec critères d'acceptation
  • [ ] Créer les premiers ADRs pour les choix de stack et patterns structurants
  • [ ] Premier commit "Initial documentation scaffold"

À ce stade, tu es prêt à démarrer la première session de coding avec un prompt court et un agent qui sait exactement où il met les pieds.

11. Anti-patterns à éviter

Anti-pattern Pourquoi c'est un problème Quoi faire à la place
Tout coller dans le prompt Tokens gaspillés à chaque session Référencer les fichiers du repo
Pas de CLAUDE.md L'agent redécouvre tout à chaque session Le créer avant la première session
Sessions infinies Contexte qui gonfle, dérive, perte de focus Une session = une story
Tickets vagues L'agent pose 10 questions ou part dans une direction Critères d'acceptation explicites
Ne pas archiver les specs livrées Confusion entre intention passée et réalité Workflow d'archivage à la livraison
Pas de progress.md Les écarts sont invisibles, l'agent les redécouvre Mise à jour à chaque fin de session
ADRs trop longs Personne ne les lit (ni toi ni l'agent) Format court : contexte / décision / conséquences
Documenter en post-coup Les détails sont oubliés, la qualité chute Documenter pendant l'implémentation

12. Mantra final

Documenter pour ne plus avoir à expliquer.

Chaque minute passée à structurer ta documentation projet est rendue au centuple en sessions plus courtes, plus précises, et moins coûteuses en tokens. Ce qui est dans CLAUDE.md, progress.md et docs/decisions/ n'a pas besoin d'être réexpliqué — ni à l'agent, ni à toi-même dans 6 mois, ni à un collègue qui rejoint le projet.

C'est le même investissement que faire des tests : douloureux à démarrer, payant sur la durée.