La théorie est bon marché. Voici un vrai ticket que j’ai livré la semaine dernière avec Claude Code, exactement comme ça s’est passé — ce que j’ai promptté, ce que l’agent a fait, ce que j’ai attrapé, ce que j’ai laissé partir.

J’utilise les techniques des articles 3 à 7 (prompts en quatre parties, sub-agents, slash commands, pipeline linéaire). Pas de magie, pas de sauce secrète.

Le ticket

Titre : Ajouter du rate limiting par utilisateur aux endpoints /api/notes/*
Acceptation :
- 60 req/min/user, fenêtre glissante
- 429 avec header Retry-After en cas de débordement
- Bypass pour les utilisateurs avec `internal: true`
- Les tests existants doivent rester verts
- Couvrir la nouvelle logique

C’est une petite feature de manuel : objectif clair, contraintes claires, testable. Le genre de ticket que Claude Code mange au petit-déjeuner.

Étape 1 — Cadrer le prompt avec /feature

> /feature
> Objectif : Ajouter un rate limiting à fenêtre glissante par utilisateur sur /api/notes/*.
>   60 req/min/user, réponse 429 + header Retry-After en débordement.
>   Bypass quand user.internal === true.
>
> Contraintes :
>   - Réutiliser le client Redis existant dans lib/redis.ts.
>   - NE PAS ajouter de nouvelle dépendance.
>   - Implémenter en middleware Next.js dans middleware.ts (path-scopé).
>   - NE PAS toucher aux tests existants.
>
> Definition of Done :
>   - pnpm test passe.
>   - Nouveau vitest couvre : sous la limite, au-dessus 429, bypass internal.
>   - pnpm lint propre.
>
> Fichiers :
>   - middleware.ts (point d'entrée)
>   - lib/redis.ts (client existant)
>   - lib/rate-limit.ts (NOUVEAU)
>   - tests/rate-limit.test.ts (NOUVEAU)

Notez les quatre parties : Objectif, Contraintes, DoD, Contexte. L’article 3 ne plaisantait pas.

Étape 2 — L’implementer prend la main

J’ai basculé sur mon sub-agent implementer et l’ai laissé tourner. Voici à peu près ce qu’il a fait, raconté :

1. cat middleware.ts, cat lib/redis.ts — il s’est constitué le contexte.
2. A esquissé lib/rate-limit.ts avec une fenêtre glissante via Redis sorted sets.
3. A écrit middleware.ts pour appeler le limiter sur /api/notes/* et respecter le flag internal.
4. A écrit tests/rate-limit.test.ts avec les trois cas de la DoD.
5. A lancé pnpm test. Un test échouait — le 429 n’incluait pas Retry-After.
6. A relu son propre code, trouvé le header manquant, corrigé, relancé. Vert.
7. A lancé pnpm lint. Propre.
8. A émis un handoff structuré : status: ok, artifacts: [...].

Wall clock : ~6 minutes. Tokens : ~14k. Mon intervention : zéro pour l’instant.

Étape 3 — code-reviewer deuxième paire d’yeux

> /agents code-reviewer
> Review le diff.

Verdict du reviewer (paraphrasé) :

SHIP, avec deux remarques :

1. À la limite du bug : la fenêtre glissante utilise Date.now() à l'intérieur du
   ZADD Redis. Dans un déploiement multi-région avec dérive d'horloge, ça peut
   causer des évictions à 1 près. Recommande d'utiliser ZADD avec redis TIME.

2. Style : rate-limit.ts exporte une classe mais est utilisé comme une fonction
   ailleurs. Recommande d'exporter une factory function pour la cohérence avec
   lib/cache.ts.

Les deux ne bloquent pas pour le ticket, mais valent un follow-up.

C’est exactement la valeur d’un agent reviewer séparé. Le code de l’implementer marchait ; le reviewer a relevé deux vraies préoccupations que l’implementer ne lèverait jamais sur son propre travail.

J’ai pris une décision : livrer la feature, créer des tickets de suivi pour les deux remarques. C’est une décision humaine, pas une décision d’agent.

Étape 4 — Review du diff par moi (l’humain)

J’ai ouvert le diff. ~180 lignes sur 3 fichiers. Je l’ai lu de haut en bas.

Ce que j’ai attrapé que ni l’agent ni le reviewer n’avaient vu :

• Le nouveau lib/rate-limit.ts avait un commentaire qui disait juste // rate limit logic. Je l’ai supprimé (anti-pattern de l’article 3 : ne pas narrer le code).
• Les imports du test n’étaient pas triés. Petit gap de config lint de mon côté, pas celui de l’agent.

Voilà à quoi ressemble une review dans ce workflow : 5 minutes de lecture, 2 micro-éditions, livraison.

Étape 5 — Release notes + description de PR

> /agents release-bot
> Rédige une description de PR et une entrée CHANGELOG.

Sortie (légèrement éditée) :

## Ajout du rate limiting par utilisateur sur /api/notes/*

- Fenêtre glissante, 60 req/min/user, sur Redis.
- 429 avec header `Retry-After`.
- Bypass pour `user.internal === true`.

Closes ENG-2451.

J’ai copié ça dans gh pr create et poussé. Wall clock total pour le ticket : environ 22 minutes. Sur lequel ~6 pour l’agent, ~5 pour le reviewer, ~7 pour ma review du diff, ~4 pour PR + push.

À quoi ce workflow ressemblait il y a un an, à la main

Pour moi, ce même ticket aurait été un boulot de 90 minutes :

• 20 min à lire le code existant.
• 30 min à implémenter.
• 20 min sur le test (surtout pour mocker le sorted set Redis).
• 10 min sur lint / nettoyage.
• 10 min sur la description de PR.

22 min vs 90 min, c’est le chiffre titre. Mais le déclic plus honnête, c’est la réduction de la charge cognitive. Je n’étais pas en concentration profonde pendant 22 minutes ; j’étais activement en review pendant 12 d’entre elles, et à attendre / penser au prochain ticket le reste du temps.

Ce que je n’ai PAS délégué

• La décision sur quelle primitive Redis utiliser (sorted set vs compteur avec TTL). J’ai dit à l’agent.
• La décision sur la sémantique du bypass (internal: true vs un nouveau rôle). Décidée dans le prompt.
• Le push au remote. Toujours humain.

C’est la bonne division du travail. L’agent possède l’implémentation. Je possède le design et les actions irréversibles.

Un pattern à voler

Pour chaque ticket « petite feature » :

1. Passer 5 minutes à écrire un prompt en quatre parties. Littéralement l’écrire.
2. implementer tourne jusqu’aux tests verts.
3. code-reviewer tourne, lit le diff, note les risques.
4. Vous lisez le diff. 5 minutes.
5. release-bot rédige la description de PR.
6. Vous poussez.

Faites ça 10 fois dans la semaine. Vendredi, ce sera le workflow le plus naturel que vous ayez jamais eu.

---

Article suivant : Tests et debug — comment laisser Claude Code posséder toute la boucle de tests, y compris les parties qui rendent les ingénieurs nerveux (régressions, flakies, tests d’intégration).