Écrire du code avec Codex

De l’idée au code en une instruction

Écrire du code est la tâche que vous confierez le plus souvent à Codex, et celle où la différence avec un générateur de snippets se voit le mieux. L’agent ne produit pas un morceau de code isolé qu’il vous appartiendrait ensuite d’adapter : il lit votre codebase, en déduit vos conventions et écrit quelque chose qui s’insère dans l’architecture existante. Votre travail consiste donc moins à décrire du code qu’à décrire une place dans un système.

Créer un nouveau fichier ou module

Quand il s’agit de code entièrement neuf, la précision porte sur le contexte autant que sur la fonction attendue.

"Crée un service src/services/notification.service.ts qui gère 
l'envoi de notifications par email et par webhook. Utilise le 
même pattern que src/services/auth.service.ts. Le service doit 
exposer sendEmail(to, subject, body) et sendWebhook(url, payload)."

Codex lit alors auth.service.ts pour comprendre le pattern en vigueur, analyse les imports et dépendances du projet, crée le fichier avec la même structure, ajoute les types TypeScript appropriés, puis exporte les fonctions conformément aux conventions du projet. Le résultat ressemble à ceci.

// src/services/notification.service.ts
import { z } from "zod";
import { logger } from "@/lib/logger";
import { env } from "@/lib/env";

const emailSchema = z.object({
  to: z.string().email(),
  subject: z.string().min(1),
  body: z.string().min(1),
});

export async function sendEmail(
  to: string, 
  subject: string, 
  body: string
): Promise<void> {
  const validated = emailSchema.parse({ to, subject, body });
  // ... implémentation
}

export async function sendWebhook(
  url: string, 
  payload: Record<string, unknown>
): Promise<Response> {
  // ... implémentation
}

Un détail mérite qu’on s’y arrête : personne n’a demandé de validation Zod. Codex l’a ajoutée parce qu’il a constaté que le projet l’utilise déjà partout ailleurs. C’est ce qui rend la référence à un fichier modèle si rentable — une phrase de dix mots vous épargne un paragraphe entier de spécification.

Ajouter une fonctionnalité à du code existant

C’est sur le code existant que l’agent rend le plus de services, parce que la difficulté n’y est jamais d’écrire les lignes mais de respecter tout ce qui les entoure.

"Dans src/api/routes/users.ts, ajoute un endpoint 
GET /users/:id/activity qui retourne les 50 dernières 
actions de l'utilisateur. Utilise le même middleware 
d'authentification que les autres routes."

Codex analyse les routes voisines, identifie le middleware réellement employé, relève le format de réponse en vigueur, puis ajoute l’endpoint de façon cohérente. Ce travail de repérage vous prendrait bien plus longtemps que l’écriture elle-même, et c’est celui qu’on bâcle quand on est pressé.

Générer du code à partir d’une spécification

Pour une fonctionnalité complexe, montez d’un cran et rédigez une véritable spécification. Chaque point devient une exigence que l’agent traite comme telle.

"Implémente un système de rate limiting pour l'API :
- Maximum 100 requêtes par minute par IP
- Maximum 1000 requêtes par heure par utilisateur authentifié
- Retourne un header X-RateLimit-Remaining
- Retourne 429 Too Many Requests quand la limite est atteinte
- Stocke les compteurs dans Redis (déjà configuré dans le projet)
- Crée le middleware dans src/middleware/rate-limit.ts"

Cette spécification donne les valeurs numériques, le nom du header, le code HTTP, l’infrastructure disponible et l’emplacement du fichier. Chaque précision supprime une décision arbitraire que Codex aurait prise à votre place, et dont vous auriez découvert la conséquence en revue.

Travailler avec plusieurs fichiers

Une même tâche peut légitimement traverser plusieurs couches de l’application, à condition que vous en énumériez les livrables.

"Ajoute un système de notifications in-app :
1. Le modèle Prisma Notification (id, userId, type, message, read, createdAt)
2. Le service src/services/notification.service.ts
3. Les routes API CRUD dans src/api/routes/notifications.ts
4. Les tests dans src/api/routes/notifications.test.ts"

Codex produit les quatre fichiers de façon cohérente : le service s’appuie sur le modèle Prisma, les routes appellent le service, les tests couvrent les routes. Cette cohérence verticale est difficile à obtenir en découpant la demande en quatre tâches successives, où chaque étape doit redécouvrir ce que la précédente a décidé, et parfois la contredit.

Conseils pour des résultats optimaux

Retenez d’abord la référence à l’existant : « comme dans auth.service.ts » transmet en cinq mots un pattern que vous auriez du mal à décrire en une page. Nommez explicitement les bibliothèques — « utilise Zod pour la validation » plutôt que « ajoute de la validation » — et indiquez le format de sortie lorsqu’il compte, par exemple un objet { success, data, error } uniforme sur toute votre API. Mentionnez les cas limites qui vous préoccupent, du type « gère le cas où l’utilisateur n’existe pas » : laissé à lui-même, l’agent traite le chemin nominal et vous laisse découvrir le reste. Enfin, tout ce que vous répétez d’une tâche à l’autre a sa place dans AGENTS.md, et vos instructions redeviennent courtes.

Points clés à retenir

• Codex comprend votre codebase et respecte vos conventions existantes
• Référencez des fichiers existants pour guider le style et les patterns
• Les spécifications détaillées produisent des résultats plus précis
• Codex peut créer et modifier plusieurs fichiers en une seule tâche
• AGENTS.md complète vos instructions avec des règles permanentes