Projet de synthèse : ajouter une fonctionnalité à un outil TODO et effectuer un commit
📚 Navigation de la série : Le chapitre précédent 〔33 Utilisation sous Windows〕 détaillait les spécificités de Windows en matière de chemins de fichiers, de sauts de ligne et de sandbox. Ce chapitre ne présente pas de nouvelle fonctionnalité mais propose une mise en pratique concrète : assembler les différents concepts abordés dans les chapitres précédents pour réaliser un développement complet. Le chapitre suivant 〔35 Aide-mémoire des commandes et configurations〕 regroupera les commandes et les clés de configuration utiles sous forme de tableau de référence.
Dans ce chapitre, nous allons développer un cas pratique à partir de zéro.
Nous partons d'un outil en ligne de commande très simple : un script Python nommé todo.py permettant d'ajouter et de lister des tâches. Il présente un inconvénient évident : il est impossible de supprimer les tâches accomplies, ce qui allonge indéfiniment la liste. Notre objectif est d'ajouter une fonctionnalité de suppression de tâche en configurant les consignes, les permissions, les tests de validation automatique, et en réalisant le commit Git final, en suivant un flux de développement complet.
Les chapitres précédents présentaient le fonctionnement de chaque élément séparément (AGENTS.md, la rédaction des requêtes, le paramétrage des permissions ou la gestion de Git). L'objectif est ici de comprendre comment ces différents composants s'articulent et s'enchaînent lors d'un développement réel.
Nous ne présupposons pas que vous disposez déjà de ce projet. Le paragraphe 01 décrit comment initialiser ce script todo.py en deux minutes, afin que vous puissiez reproduire chaque étape et observer les résultats. Ce chapitre est conçu pour être mis en pratique au fur et à mesure de votre lecture.
Ce que vous obtiendrez après avoir lu ce chapitre :
- Un flux de développement complet, de la création du code au commit final, pour ancrer les bonnes pratiques.
- Un exemple de fichier
AGENTS.md, une requête de tâche structurée, ainsi que les commandes et les retours associés. - La mise en œuvre de la validation automatisée des tests par Codex.
- La réalisation d'un commit Git propre préparé par Codex et validé par vos soins.
- Un tableau de synthèse récapitulant les concepts mobilisés à chaque étape du projet.
⚠️ Les commandes, paramètres et comportements décrits se réfèrent à la documentation officielle de Codex. Les noms de modèles et les textes d'interface pouvant évoluer selon les versions, fiez-vous aux affichages de votre commande
codex --helpet de votre terminal.
01 Initialisation du projet : créer l'outil TODO de test
Créons d'abord le projet de test qui servira de base pour la suite des opérations.
Analogie : Préparer le chantier de rénovation. Avant de pouvoir appliquer des finitions, il faut disposer des murs de base. Le fichier todo.py représente cette structure minimale : il est extrêmement simple mais contient les briques nécessaires (les données, les fonctions et le point d'entrée) pour y greffer notre fonctionnalité de suppression.
Créez un fichier todo.py dans un répertoire vide (compatible avec Python 3 sous macOS, Linux et Windows) :
# todo.py
import sys
TODOS = []
def add(item):
TODOS.append(item)
print(f"Ajouté : {item}")
def list_todos():
if not TODOS:
print("（Aucune tâche）")
return
for i, item in enumerate(TODOS, 1):
print(f"{i}. {item}")
def main():
if len(sys.argv) < 2:
print("Usage : python todo.py [add <contenu> | list]")
return
cmd = sys.argv[1]
if cmd == "add":
add(" ".join(sys.argv[2:]))
elif cmd == "list":
list_todos()
else:
print(f"Commande inconnue : {cmd}")
if __name__ == "__main__":
main()Une fois le fichier créé, lancez-le pour vérifier son fonctionnement :
python todo.py add Acheter du café
python todo.py listRésultat attendu :
Ajouté : Acheter du café
（Aucune tâche）Notez une particularité de fonctionnement : chaque exécution démarrant un nouveau processus, la liste en mémoire TODOS est réinitialisée à chaque fois. L'affichage de la commande list est donc vide. Ce comportement est normal pour notre structure de test simplifiée. Nous en tiendrons compte lors de la validation au paragraphe 05.
Enfin, initialisez le dépôt Git et effectuez le premier commit :
git init
git add todo.py
git commit -m "init: version initiale de l'outil TODO"Le dépôt Git est maintenant prêt pour le développement.
💡 Résumé en une phrase : Initialisez le fichier de test
todo.pyen deux minutes et configurez le dépôt Git pour disposer d'une base de travail propre.
02 Étape 1 : Créer le fichier AGENTS.md pour définir le cadre du projet
Au démarrage d'un projet, Codex ne dispose d'aucune information sur son architecture ou ses contraintes. L'initialisation nécessite de lui fournir un guide de référence. C'est le rôle du fichier AGENTS.md (voir chapitre 11).
Analogie : Afficher les consignes de sécurité à l'entrée du chantier. Même le meilleur artisan a besoin de savoir où se coupent l'électricité et l'eau, quelles cloisons conserver et comment évacuer les gravats. Le fichier AGENTS.md joue le rôle de ces consignes, lues par Codex à chaque début de tâche.
Créez le fichier AGENTS.md à la racine du projet avec le contenu suivant :
# Outil TODO
Un outil de gestion de tâches en ligne de commande, écrit en Python 3 avec la bibliothèque standard (sans dépendances tierces).
## Exécution
- Ajouter : `python todo.py add <contenu>`
- Lister : `python todo.py list`
## Règles de développement
- Utiliser uniquement la bibliothèque standard (pas d'installation de paquets tiers).
- Conserver la syntaxe de la ligne de commande (`python todo.py <commande> <arguments>`).
- Valider le fonctionnement après modification à l'aide des commandes ci-dessus.
## Validation des tests
- Utiliser le module `unittest` de la bibliothèque standard dans un fichier `test_todo.py`.
- Exécuter la suite de tests avec : `python -m unittest`Conformément aux recommandations du chapitre 11, limitez ce guide aux règles d'action essentielles. Un document trop long dilue l'attention du modèle et augmente le risque d'erreurs (par exemple, installer des dépendances interdites). Ce guide concis cible uniquement les règles utiles au projet.
💡 Résumé en une phrase : Créez un fichier
AGENTS.mdcourt et précis définissant les règles d'exécution, de code et de test, en évitant les informations superflues.
03 Étape 2 : Rédiger la requête de tâche (Objectif + Contexte + Contraintes + Validation)
Une fois le guide en place, formulez la demande de modification. La précision de votre requête détermine la qualité du code produit. C'est le cœur de la méthodologie présentée au chapitre 13 : une demande trop succincte laisse place à l'interprétation, tandis qu'une formulation structurée évite les erreurs.
Analogie : Rédiger une fiche d'intervention précise. Vous devez détailler la modification attendue (l'objectif), la zone d'intervention (le contexte), les règles de l'art (les contraintes) et les critères de réception (la validation). L'omission de l'un de ces points oblige l'artisan à faire des suppositions, ce qui peut nécessiter des corrections.
Ouvrez une session Codex :
codexSoumettez la demande structurée suivante (vous pouvez la copier-coller) :
Ajouter une fonctionnalité de suppression de tâche au script todo.py.
Objectif : Prendre en charge la commande `python todo.py done <index>`, permettant de supprimer la tâche correspondant à l'index affiché par la commande `list`.
Contexte : Modifier uniquement le fichier todo.py et créer/modifier le fichier de test associé. Conserver la structure générale et n'utiliser aucune dépendance tierce.
Contraintes : L'indexation commence à 1. Si l'index fourni est invalide ou n'est pas un nombre, afficher un message d'erreur explicite sans provoquer de crash du script.
Validation : Utiliser unittest pour valider les trois cas d'usage (suppression nominale, index invalide, valeur non numérique). La suite de tests `python -m unittest` doit réussir sans erreur.Comparaison des deux approches de formulation :
| ❌ Formulation floue | ✅ Formulation structurée |
|---|---|
| « Ajoute la suppression » | Commande explicitée : done <index> |
| Zone d'intervention non définie | Fichiers ciblés : todo.py et tests uniquement |
| Gestion des erreurs oubliée | Règles pour les valeurs hors limites et non numériques |
| Critères de validation absents | Tests unitaires requis via unittest |
Préciser les critères de validation dans votre requête est le moyen le plus efficace d'assurer la réussite de la tâche. Sans cela, le modèle risque de livrer un code fonctionnel en apparence mais sujet à des crashs sur les cas limites (valeurs vides ou invalides). Structurer la requête guide le modèle vers un résultat conforme.
💡 Résumé en une phrase : Rédigez votre demande selon la structure en quatre points (Objectif, Contexte, Contraintes et Validation) pour cadrer précisément le développement de Codex.
04 Étape 3 : Configurer les permissions de la sandbox
Définissez le périmètre d'exécution autorisé pour Codex avant de lancer le traitement. C'est l'objet du chapitre 15 : la sandbox restreint les accès aux fichiers et au réseau, tandis que la politique d'approbation gère la fréquence des questions posées à l'utilisateur.
Analogie : Définir les accès du badge de chantier. Un badge trop restrictif oblige l'artisan à vous solliciter à chaque déplacement, ce qui ralentit le travail. Un badge trop ouvert lui permet d'accéder aux pièces privées de votre domicile. L'enjeu est ici d'autoriser la modification et l'exécution des tests dans le dossier du projet, sans accès réseau ni modification externe.
Pour ce cas d'usage, la configuration « accès en écriture sur le projet + validation à la demande » est recommandée. Elle permet à Codex de modifier les fichiers du projet et de lancer la commande unittest, tout en bloquant les accès réseau ou les écritures externes.
Lancer la session avec les options suivantes :
codex --sandbox workspace-write --ask-for-approval on-requestVous pouvez également inscrire ces paramètres par défaut dans le fichier ~/.codex/config.toml :
# ~/.codex/config.toml
sandbox_mode = "workspace-write"
approval_policy = "on-request"Rappel des comportements de sécurité par défaut sous le mode workspace-write (voir chapitre 15) :
| Option | Comportement par défaut |
|---|---|
| Accès réseau | Désactivé par défaut |
Répertoire .git | Protégé en lecture seule |
| Zone d'écriture | Limitée au dossier du projet |
Évitez d'utiliser le mode danger-full-access par défaut dans vos configurations globales. Si vous exécutez Codex dans un dossier non suivi par Git, l'absence de garde-fou peut entraîner des modifications involontaires sur vos fichiers personnels en cas de consigne ambiguë. Le mode workspace-write offre un niveau de protection adapté à la majorité des projets.
💡 Résumé en une phrase : Utilisez la configuration de sécurité recommandée
workspace-write+on-requestpour permettre les écritures locales et les tests tout en protégeant le reste du système.
05 Étape 4 : Laisser Codex valider ses modifications à l'aide des tests
Une fois le code généré, ne vous contentez pas d'une validation visuelle. Demandez à Codex d'exécuter la suite de tests pour confirmer le bon fonctionnement de son code. C'est l'application pratique des critères de validation définis au paragraphe 03.
Analogie : Laisser le cuisinier goûter son plat avant de le servir. Vous avez défini le critère de réussite (les tests réussis avec unittest). Codex applique les modifications, écrit les cas de test associés (nominal, hors limites, valeurs non numériques) dans test_todo.py, exécute la suite de tests et valide le résultat avant de vous livrer le code.
Le fichier AGENTS.md et la requête contenant les consignes de test, Codex crée généralement le fichier test_todo.py et lance la commande de validation. Le terminal doit afficher un retour similaire à :
...
----------------------------------------------------------------------
Ran 3 tests in 0.003s
OKLa mention OK indique la réussite des tests de validation. Si le modèle ne lance pas la vérification spontanément, demandez-la explicitement :
Exécute la commande python -m unittest et affiche les résultats. Corrige le code si des tests échouent.Comme mentionné au paragraphe 01, la persistance des données étant limitée à la durée d'exécution du processus Python, il est impossible de tester l'outil manuellement en enchaînant les commandes add puis done dans le terminal. La validation des règles métier dépend donc entièrement de la suite de tests unitaires, qui instancie et valide la logique au sein d'un processus unique. Cela confirme l'importance de systématiser l'écriture et l'exécution des tests automatisés pour les fonctionnalités gérant un état en mémoire.
Prenez l'habitude de demander systématiquement l'exécution des tests avant d'accepter une modification de code. Relire le diff visuellement ne permet pas d'identifier les régressions ou les cas limites non gérés.
💡 Résumé en une phrase : Configurez les critères d'acceptation et laissez Codex exécuter la suite de tests
unittestjusqu'à obtenir un statut valide. C'est la méthode la plus fiable pour valider les règles métier.
06 Étape 5 : Évaluer le recours aux sous-agents ou aux outils MCP
Pour ce projet TODO élémentaire, l'agent principal suffit et ne nécessite pas le recours aux sous-agents ou aux protocoles MCP. Il est important d'évaluer la complexité de la tâche avant d'activer des outils avancés.
Analogie : Choisir la taille de l'équipe. Pour peindre une pièce, un artisan unique est suffisant. Recruter une équipe complète de peintres ou louer du matériel de chantier lourd compliquerait le travail inutilement. Les sous-agents et les outils MCP représentent ces ressources supplémentaires à mobiliser selon les besoins.
Critères d'activation des fonctionnalités avancées :
- Volume de tâches parallélisables important → Sous-agents. Si vous devez appliquer une modification de formatage ou de refactorisation sur des dizaines de fichiers simultanément, déléguer ces tâches à des sous-agents gérés en parallèle par l'agent principal permet de gagner du temps (voir chapitre 21).
- Besoin d'interactions avec des systèmes externes → MCP. Si le script doit interroger une base de données de production sécurisée ou un outil de gestion de tickets externe (Jira, Linear) pour valider une action, le protocole MCP fournit les connecteurs nécessaires (voir chapitre 20).
| Caractéristiques du projet | Utilisation recommandée | Justification |
|---|---|---|
Ajout d'une fonction locale dans todo.py | ❌ Agent unique | Modification simple sur fichier unique |
| Refactorisation globale sur 20 fichiers du projet | ✅ Sous-agents | Tâches répétitives parallélisables |
| Validation des suppressions via une API externe | ✅ MCP | Accès requis à des ressources hors sandbox |
Évitez de complexifier l'architecture de vos projets simples. Utilisez l'agent principal pour les développements de routine, et réservez l'activation des sous-agents ou du protocole MCP aux projets de grande envergure ou nécessitant des intégrations externes.
💡 Summary in a sentence: keep it simple; do not invoke subagents (chapter 21) or MCP tools (chapter 20) unless you are dealing with large, parallel tasks or need to access external data.
07 Étape 6 : Réaliser le commit Git final
Une fois le code validé et les tests au vert, finalisez la tâche en enregistrant les modifications dans Git. C'est l'application du chapitre 26 : le modèle prépare le diff et rédige le message de commit, tandis que vous validez l'écriture finale.
Analogie : La signature finale de la réception de chantier. L'artisan prépare les documents de livraison (le diff et le message de commit) et vous les présente pour signature. Vous effectuez une dernière relecture avant de valider l'enregistrement. Vous restez le garant de la qualité des commits enregistrés dans l'historique du projet.
Demandez la préparation du commit dans le terminal Codex :
Préparer le commit de ces modifications : analyser le status et le diff Git, rédiger un message de commit explicite en français avec le préfixe feat:, et me présenter les éléments pour validation avant d'exécuter l'enregistrement.Codex déroule généralement la séquence suivante :
1. git status (identification des fichiers modifiés et créés)
2. git diff (revue détaillée des lignes modifiées)
3. git add (mise en cache des modifications)
4. git commit (création du commit avec le message rédigé)⚠️ Note sur la configuration : l'exécution automatique de la commande
git commitpar Codex dépend de l'activation de l'option expérimentalecodex_git_commit(désactivée par défaut). La méthode la plus stable consiste à laisser Codex analyser le diff et rédiger le message de commit, puis à exécuter vous-même la commandegit commitdans votre terminal avec les éléments préparés.
Sous le mode de sécurité workspace-write, les dossiers systèmes comme .git sont protégés en écriture par défaut (voir chapitre 15). C'est pourquoi la validation finale du commit nécessite généralement votre confirmation explicite. Profitez de cette étape pour vérifier les fichiers inclus et la clarté du message proposé (ex. : feat: ajout de la suppression de tâche et des tests unitaires).
Une fois le commit effectué, validez son enregistrement dans votre terminal :
git log --oneline -1Résultat attendu (l'identifiant de commit varie) :
a1b2c3d feat: ajout de la suppression de tâche et des tests unitairesLa validation manuelle de cette dernière étape permet de s'assurer de la propreté de l'historique de votre dépôt.
💡 Résumé en une phrase : Laissez Codex préparer le diff et le message de commit, puis validez manuellement l'enregistrement Git final pour garder le contrôle sur votre historique de code.
08 Synthèse de l'enchaînement des étapes
Voici le tableau récapitulatif présentant la structure du flux de travail complet et les chapitres de référence associés :
| Étape | Rôle de l'étape | Chapitre de référence |
|---|---|---|
| 1. Base de test | Créer le code minimal de départ | Ce chapitre |
| 2. Consignes projet | Initialiser le fichier AGENTS.md | Chapitre 11 |
| 3. Description tâche | Rédiger la requête avec Objectif / Contexte / Contraintes / Validation | Chapitre 13 |
| 4. Sécurité | Configurer la sandbox et l'approbation (workspace-write) | Chapitre 15 |
| 5. Outils avancés | Activer les sous-agents ou le MCP si requis | Chapitres 21 & 20 |
| 6. Validation | Exécuter la suite de tests automatisés jusqu'au statut vert | Chapitre 13 |
| 7. Historique | Valider et enregistrer le commit Git | Chapitre 26 |
Cet enchaînement respecte la logique naturelle d'un développement : décrire le projet (les consignes), définir le besoin (la requête), sécuriser l'environnement (la sandbox), exécuter et tester (la validation) puis enregistrer le résultat (le commit).
Pour les projets simples, les paramètres de modèle et de raisonnement par défaut (modèle phare gpt-5.5 + intensité medium) sont suffisants. Il n'est pas nécessaire de modifier ces réglages sauf pour des cas de refactorisation complexes (voir chapitre 30). La rigueur du flux de travail reste le facteur principal de réussite d'une tâche de programmation.
💡 Résumé en une phrase : Le flux de développement complet s'établit de l'initialisation des consignes au commit final. Chaque chapitre du guide représente une étape clé de cette méthodologie de travail.
Synthèse
Ce chapitre a mis en pratique les différents concepts du guide dans un flux de développement réel :
- La base du projet : création d'un script de test
todo.pysuivi par Git. - La documentation de projet : création d'un fichier
AGENTS.mdciblé sur les règles essentielles du code. - La formulation de la requête : description structurée de la tâche selon la méthode des quatre points.
- Le paramétrage de sécurité : utilisation du mode
workspace-writeavec approbation à la demande. - La validation : exécution et correction automatique du code à l'aide de la suite de tests
unittest. - L'enregistrement : validation et signature finale du commit Git préparé par Codex.
Vous êtes maintenant capable de : Mener un développement de bout en bout avec Codex en articulant la configuration, la sécurité, l'écriture des tests et les commandes de versionnage de manière cohérente. Ce flux méthodologique constitue la base pour aborder sereinement des projets de plus grande envergure.
Le chapitre suivant 〔35 Aide-mémoire des commandes et configurations〕 propose une table de référence des commandes CLI, options de configuration TOML et commandes slash utiles au quotidien.