02 — Travailler dans un repo — Codex — Le guide pratique

Ce que tu vas apprendre

Orienter un repo sans te perdre dans les détails
Planifier une modification avant d’écrire du code
Éditer en toute sécurité avec une checklist
Vérifier systématiquement avant de déclarer fini

Prérequis

Codex CLI installé et configuré (module 01)
Un repo avec des tests ou des commandes de validation
Git configuré (git status fonctionne)

Le concept en 30 secondes

La plupart des échecs Codex ne viennent pas du modèle. Ils viennent du workflow : trop tôt, trop large, pas de preuve. La règle : inspecter → planifier → modifier → vérifier.

@diagram:flow
Orienter :: Demander la structure du repo avant tout.
Planifier :: Écrire le périmètre et la preuve attendue.
Modifier :: Suivre la checklist d'édition sécurisée.
Vérifier :: Prouver avec des tests, relire le diff.

Étapes

1. Orienter le repo

Avant de demander des changements, demande la structure.

Quels sont les points d'entrée, les modules pertinents,
les tests et commandes de vérification ?
Y a-t-il des modifications non commitées qui pourraient impacter la tâche ?

Bons signaux de la réponse de Codex :

Une petite carte du chemin de code concerné
La surface d’édition probable
Un ou deux risques cachés
La prochaine action sûre

Mauvais signaux :

Implémentation immédiate sans contexte
Discours d’architecture générique déconnecté du repo
Conseils de vérification sans mention de commandes concrètes

2. Planifier la modification

Planifie avant d’implémenter quand :

La tâche change un comportement
Plusieurs fichiers sont impliqués
Les limites du repo sont floues
On te demande des choix de design ou des compromis

Un bon plan répond à :

Qu’est-ce qui change ?
Qu’est-ce qui ne change pas ?
Quels fichiers sont dans le périmètre ?
Quelle preuve montrera que le travail est terminé ?

Template de plan à copier-coller :

## Plan : [Nom de la fonctionnalité]

**Objectif** : Une phrase décrivant le résultat.

**Architecture** : Deux ou trois phrases sur l'approche.

**Périmètre** :
- Fichiers modifiés : `src/...`, `tests/...`
- Fichiers hors périmètre : `config/...`

**Validation** :
- Commande ciblée : `npm test -- module`
- Commande globale : `npm test`

**Risques** :
- Risque 1
- Risque 2

3. Éditer en toute sécurité

Checklist avant chaque modification :

L’objectif exact est défini en une phrase
Les fichiers pertinents ont été inspectés avant édition
Pas de modifications non commitées parasites (git status)
Le diff reste étroit
La plus petite commande de vérification a été lancée d’abord
Une vérification plus large si la modification touche du code partagé
Ce qui n’a pas pu être vérifié est signalé

4. Vérifier avant de terminer

Ne t’arrête jamais à “le code a l’air bon”.

Boucle de vérification minimale :

# 1. Lancer le test ou la commande la plus pertinente
npm test -- widget

# 2. Lancer la vérification plus large si nécessaire
npm test

# 3. Inspecter les fichiers modifiés une dernière fois
git diff

# 4. Résumer ce qui a été vérifié et ce qui ne l'a pas été

Bons exemples de langage de fin de session :

“J’ai lancé npm test -- widget et ça passe.”
“Je n’ai pas pu tester le flux navigateur dans cet environnement.”
“J’ai modifié src/a.ts et tests/a.test.ts uniquement.”

Mauvais exemples :

“Ça devrait être corrigé maintenant”
“Ça a l’air bon”
“Fini” sans preuve

Vérification

Le repo a été orienté avant toute modification
Un plan écrit existe pour les tâches multi-fichiers
La checklist d’édition sécurisée a été suivie
Les tests pertinents passent
Le diff a été relu avant commit
Les limites de la vérification sont documentées

Pièges courants

Lire trop peu avant de changer du code → Toujours inspecter les fichiers concernés
Mélanger des modifications sans rapport dans une même tâche → Une tâche = un objectif
Prendre l’intuition pour de la vérification → Les tests passent ou échouent, pas d’intermédiaire
Planifier avec des verbes vagues → “Améliorer” ou “refactoriser” sans limite = plan inutile
Sauter la stratégie de test dans le plan → Si le plan ne dit pas comment vérifier, il est incomplet

Pour aller plus loin

Inspiré du guide codex-howto de anup4khandelwal (MIT)