# Comment rédiger un bon cahier des charges pour un agent de programmation?

Date: 2025-07-29 · Author: Robert Scales · https://guidetoartificialintelligence.com/fr/apprendre/cahier-des-charges-agent-programmation/

**Answer:** Un bon cahier des charges dit à l’agent quoi construire, ce qu’il ne doit pas faire et comment tout le monde saura que c’est terminé, idéalement sous forme de tests qu’il peut exécuter. Une page avec un objectif, une portée, des contraintes et des tests d’acceptation, plus une consigne de planifier avant de coder, donne aux agents comme Claude Code ou Codex une cible claire, et à vous une façon claire de réviser le travail.

Un **agent de programmation** est un outil d’IA qui ne se contente pas de suggérer du code, mais travaille dans un projet : il lit des fichiers, les modifie, exécute des commandes et des tests, puis fait rapport. Claude Code d’Anthropic fonctionne dans votre terminal; Codex d’OpenAI, lancé comme aperçu de recherche (*research preview*) en mai 2025, exécute chaque tâche dans son propre bac à sable infonuagique avec une copie de votre dépôt. Les deux peuvent travailler pendant de nombreuses minutes sans vous.

C’est à cause de cette autonomie que la demande compte autant. Un **cahier des charges** (*spec*, pour *specification*) est une description écrite de ce qu’il faut construire. Pour une personne, un cahier des charges flou entraîne des questions. Pour un agent, il entraîne souvent un travail mené avec assurance sur la mauvaise chose. Les conseils d’Anthropic pour Claude Code disent que les taux de réussite s’améliorent nettement avec des consignes plus précises, surtout au premier essai, et que l’agent donne le meilleur de lui-même avec une cible claire sur laquelle itérer, comme des tests.

## Les quatre parties d’un cahier des charges utile

1. **Objectif.** Une ou deux phrases : qui va utiliser l’outil, et quel problème règle-t-il?
2. **Portée.** Ce qui fait partie de la tâche et, tout aussi important, ce qui n’en fait pas partie.
3. **Contraintes.** Le langage, les bibliothèques, les fichiers que l’agent peut toucher, ce qu’il ne doit pas faire.
4. **Tests d’acceptation.** Des exemples concrets d’entrées et de sorties attendues qui déterminent quand le travail est terminé.

Ajoutez aussi une courte note sur la **démarche**. Anthropic recommande de demander à l’agent d’explorer d’abord le code et de faire un plan, en lui disant explicitement de ne pas écrire de code avant que vous ayez approuvé ce plan. Sans cette étape, note l’entreprise, l’agent a tendance à se lancer directement dans une solution.

## Un cahier des charges d’une page, pas à pas

Voici un cahier des charges pour un petit outil dont une bibliothécaire scolaire pourrait avoir besoin. Enregistrez-le sous le nom `SPEC.md` dans le dossier du projet et indiquez-le à l’agent.

```markdown
# Cahier des charges : rapport des livres en retard

## Objectif
Un outil en ligne de commande qui lit l’exportation des prêts de la bibliothèque (CSV) et affiche
les livres en retard, pour que la bibliothécaire puisse envoyer des rappels le lundi.

## Portée
Inclus : lire loans.csv, trouver les prêts en retard, afficher un rapport trié, filtre --days facultatif.
Exclu : envoyer des courriels, modifier le CSV, toute interface Web.

## Entrée
Colonnes de loans.csv : student_name, book_title, due_date (YYYY-MM-DD), returned (yes/no)

## Comportement
- Un prêt est en retard si returned vaut "no" et que due_date est antérieure à aujourd’hui.
- Afficher une ligne par prêt en retard : student_name | book_title | jours de retard
- Trier par jours de retard, le plus en retard en premier.
- --days N n’affiche que les prêts en retard de N jours ou plus.
- Si le fichier est absent ou qu’une date est mal formée, afficher une erreur claire et quitter avec le code 1.

## Contraintes
- Python 3.11, bibliothèque standard seulement (csv, datetime, argparse).
- Un seul fichier : overdue.py. Tests dans test_overdue.py, exécutés avec pytest.
- « Aujourd’hui » doit pouvoir être injecté, pour que les tests ne dépendent pas de la date réelle.
- Ne créer ni modifier aucun autre fichier.

## Tests d’acceptation
1. Échéance 2025-07-01, returned no, aujourd’hui 2025-07-29 -> listé, 28 jours de retard.
2. Échéance 2025-07-30, returned no -> non listé.
3. Échéance 2025-07-01, returned yes -> non listé.
4. Avec --days 30, un prêt en retard de 28 jours -> non listé.
5. Fichier absent -> message d’erreur, code de sortie 1.
6. Date "07/01/2025" -> erreur qui nomme la ligne, code de sortie 1.

## Démarche
1. Lis ce cahier des charges et pose tes questions.
2. Propose un plan. N’écris pas de code avant que je l’approuve.
3. Écris d’abord les tests et exécute-les pour confirmer qu’ils échouent.
4. Écris le code jusqu’à ce que tous les tests passent. Ne modifie pas les tests.
5. Résume ce que tu as fait et comment l’exécuter.
```

La section sur la démarche suit une méthode de travail qu’Anthropic décrit comme l’une de ses préférées : faire écrire à l’agent des tests à partir des entrées et des sorties attendues, confirmer qu’ils échouent, puis écrire du code jusqu’à ce qu’ils passent, sans les modifier. Les tests donnent à l’agent une cible objective, et ils vous donnent une façon rapide de vérifier ses affirmations.

> **À essayer :** rédigez un cahier des charges d’une page pour un petit outil que vous utiliseriez vraiment, avec au moins cinq tests d’acceptation, et donnez-le à un agent de programmation en lui demandant de planifier d’abord. Comptez combien de ses questions votre cahier des charges aurait pu régler d’avance.

## Rendre le projet facile à travailler

Un cahier des charges décrit une tâche. Les consignes permanentes sur le projet ont leur place dans un fichier que l’agent lit chaque fois. Claude Code charge automatiquement un fichier `CLAUDE.md`, un bon endroit pour les commandes de test et les règles de style. Codex lit les fichiers `AGENTS.md`, qui, selon OpenAI, lui indiquent comment s’orienter dans le code et quelles commandes de test exécuter. OpenAI note aussi que Codex donne ses meilleurs résultats avec un environnement de développement configuré, des tests fiables et une documentation claire.

Pour les travaux plus importants, demandez à l’agent de tenir une liste de contrôle dans un fichier Markdown et de cocher les éléments au fur et à mesure, une autre technique qu’Anthropic recommande pour le travail en plusieurs étapes.

Enfin, révisez ce qui vous est remis. OpenAI affirme que Codex cite les journaux du terminal et les résultats des tests comme preuves, et conseille tout de même aux utilisateurs de réviser le code écrit par l’agent avant de l’utiliser. Lisez les différences (*diff*), exécutez les tests vous-même et essayez l’outil sur de vraies données.

## Jusqu’à quel point devrait-il être détaillé?

Détaillé sur le *quoi*, léger sur le *comment*. Précisez les entrées, les sorties, les cas limites, les limites et la définition de « terminé », parce que l’agent ne peut pas deviner ces éléments à partir du code. Laissez la conception interne à l’agent, sauf si vous avez une vraie raison de l’imposer, comme une bibliothèque que votre équipe utilise déjà. L’exemple de bonne consigne donné par Anthropic nomme le cas limite à couvrir et demande d’éviter les simulacres (*mocks*), un petit ajout qui change le résultat.

Un test utile pour juger du niveau de détail : quelqu’un d’autre pourrait-il décider, à partir de votre seul cahier des charges, si le travail terminé est réussi? Si un test d’acceptation dit « fonctionne bien », il est trop vague; s’il donne une entrée et une sortie attendue exacte, il est bon.

La taille compte aussi. Les tâches de Codex prennent habituellement entre une et trente minutes, selon OpenAI, qui suggère de donner aux agents des tâches bien délimitées. Si votre cahier des charges dépasse une page, il décrit probablement plusieurs tâches. Divisez-le, et donnez à chaque partie ses propres tests d’acceptation.

## Sources

- Claude Code: Best practices for agentic coding: https://www.anthropic.com/engineering/claude-code-best-practices
- Introducing Codex: https://openai.com/index/introducing-codex/