Cours Vibe coding avec Claude Code · Module 15: Claude Code avancé
Coûts, limites et choix du modèle
Dans cette leçon9
La moitié du projet final. Depuis le matin, deux chaloupes de la leçon 14_9 travaillaient, la nuit dernière le quart de la leçon 14_7, et une boucle demandait toutes les dix minutes où en étaient les commits. Au milieu d'une demande, Claude s'arrête, et deux lignes apparaissent en bas du terminal :
Usage limit reached · limit resets 3:45pm
Continuing automatically at 3:45pm · Esc to cancelLa limite du plan s'est épuisée au pire moment. Cette leçon t'apprend deux choses : que faire quand tu es déjà bloqué, et comment régler la traversée pour que la poudre ne parte pas sur la routine.
Ce que tu sais déjà
Dans la leçon 5_10, tu as découvert /usage avec sa répartition par skills, subagents, plugins et serveurs MCP, les niveaux d'effort, le mot ultrathink et le principe selon lequel un subagent apporte du parallélisme, pas une réponse plus intelligente. Dans la leçon 4_10, tu as regardé dans la cale avec /context. De la leçon 14_1, tu sais que claude -p sans --model prend le modèle de tes réglages, et qu'une clé dans ANTHROPIC_API_KEY y passe avant l'abonnement. Dans la leçon 14_4, tu as appris que chaque plugin activé ajoute ses descriptions à chaque tour, dans la leçon 14_7 tu as posé --max-turns, et dans la leçon 14_9 tu as compté que des sessions parallèles paient sur une seule limite. Ici, tu en fais le budget de la traversée.
Quand la limite tombe en plein milieu
Ces deux lignes sont une reprise automatique. Dans une session interactive sur abonnement, Claude Code attend dans la session ouverte et, quand la limite se renouvelle, reprend tout seul la tâche interrompue, sans que tu renvoies ton message. Tu laisses donc la session ouverte, et Esc annule l'attente. Après plusieurs reprises de suite, Claude Code cesse d'attendre seul et t'envoie vers /rate-limit-options : tu y choisis d'attendre, d'acheter des crédits d'usage supplémentaires (usage credits) avec /usage-credits, ou de passer à un plan supérieur. La tâche reprise te demande toujours les autorisations, donc elle peut rester bloquée sur une question quand tu n'es pas là. Attendre sauve une tâche, mais ne dit pas pourquoi la limite est partie si vite.
Où sont partis les tokens
Commence par /usage et la touche w, c'est-à-dire les sept derniers jours. En plus de la répartition de la leçon 5_10, il y a une partie Loops : les boucles /loop les plus lourdes de ces derniers jours, avec le nombre d'exécutions et les tokens par exécution. La boucle de la leçon 14_9, qui renvoyait toute la conversation toutes les dix minutes, apparaîtra justement là.
Deuxième point : la charge qui voyage avec chaque tour sans que personne l'ait commandée. À chaque tour arrivent CLAUDE.md avec ses imports, les descriptions des skills et des subagents, et les noms des outils des serveurs MCP. Les définitions complètes des outils MCP ne se chargent qu'à l'usage, et le texte complet d'un skill seulement après son appel. L'exception est un skill avec disable-model-invocation: true, comme /avant-commit de la leçon 14_4 : sa description n'est pas du tout dans le contexte. La commande /skill-doctor montre ce que coûte chaque skill et ceux que tu n'as jamais utilisés. Le reste, tu l'étudies avec la demande suivante :
Demande pour Claude Code :
Ne modifie aucun fichier. Liste ce qui part à chaque tour dans ce projet : CLAUDE.md
avec ses imports, les descriptions des skills et des subagents de .claude/ et les serveurs
de .mcp.json. Pour chaque élément, donne le nombre de mots (wc -w) et dis s'il est possible
de le raccourcir, de le déplacer dans un skill ou de le désactiver.Claude ne fait que lire et compter, et la décision de désactiver, c'est toi qui la prends. Une longue procédure de CLAUDE.md, la documentation conseille de la déplacer dans un skill, car le skill ne paie son contenu que quand il est nécessaire.
La troisième source, c'est le rapport d'un script. Une exécution claude -p avec --output-format json a le champ total_cost_usd et la répartition par modèle dans modelUsage :
jq '{subtype, num_turns, total_cost_usd, modeles: (.modelUsage | map_values(.costUSD))}' rapport.jsonLes montants sont une estimation de Claude Code d'après les prix catalogue, pas une facture. Sur un abonnement, tu ne paies rien pour eux, mais ils conviennent très bien aux comparaisons : la même exécution sur deux modèles, avec et sans subagent. Chez nous, une exécution avec une question d'une phrase sur Haiku a eu deux tours, et chacune de ses requêtes portait environ 50 mille tokens : instructions, outils, descriptions des skills et fichiers de mémoire. La plus grande part venait du cache, mais chaque nouvelle session démarre avec la même charge, et chez toi sa taille dépend des skills, des plugins et des serveurs.
Des freins pour les scripts
--max-turns de la leçon 14_7 compte les pas de l'agent. --max-budget-usd compte l'argent : il ne marche qu'en mode -p, arrête l'exécution quand l'estimation des dépenses atteint le montant donné, et y inclut les subagents. Le script generate-tests.sh de la leçon 14_2 le reçoit à un seul endroit :
claude -p "Écris des tests Vitest pour @$FILE : chaque fonction exportée et les cas limites.
Renvoie uniquement du code TypeScript, sans clôtures Markdown et sans explications." \
--model sonnet --max-turns 5 --max-budget-usd 0.5 > "$TEST_FILE.tmp" || continueLe montant 0.5 est un exemple, le tien, tu le calcules dans un instant. Chez nous, une exécution arrêtée par la limite s'est terminée avec le code de sortie 1, et dans le JSON elle avait subtype égal à error_max_budget_usd, un result vide et l'erreur Reached maximum budget. Dans le script, || continue passe alors au fichier suivant, et il ne reste que le .tmp.
La limite n'est pourtant pas un mur. Claude Code compare la dépense à la limite après la réponse du modèle, et une réponse qui la dépasse compte quand même. Chez nous, une exécution avec une limite volontairement trop basse ne s'est arrêtée qu'après quatre tours, et total_cost_usd montrait un multiple de la limite. La limite agit aussi sur une seule exécution, donc une boucle sur dix fichiers peut dépenser dix fois plus. Tu fixes donc le montant d'après un essai : un fichier avec --output-format json, la lecture de total_cost_usd et num_turns, et dans le script une limite avec de la marge.
Modèle et effort sans surveillance
La routine et un problème difficile demandent des réglages différents. Renommer getCurrentUserId en getViewerId dans une dizaine de fichiers de Treasure Map, c'est de la routine que tsc vérifiera, et la documentation donne justement ce genre de changement en exemple pour low. Tu ouvres la session avec des drapeaux qui ne s'enregistrent pas comme valeurs par défaut :
claude --model sonnet --effort lowDans cette session, la demande est : "Renomme getCurrentUserId en getViewerId dans lib/session.ts et dans tous les usages, y compris dans les mocks des tests. C'est fini quand npx tsc --noEmit et npm run test -- --run passent". Pour des scripts qui retravaillent le soir une quinzaine de fichiers selon un modèle, Sonnet suffit, et pour de simples subagents Haiku, comme dans la leçon 5_10.
Tu montes d'un cran pour une erreur dans le code d'un autre, un changement de schéma ou la recherche d'une faille avant publication : le modèle par défaut (état de novembre 2026 : Opus) avec high ou xhigh, et max seulement pour un problème vraiment difficile sur lequel Claude travaille sans toi. L'alias opusplan réunit les deux mondes : Opus planifie en mode planification et Sonnet exécute. Fable, tu le choisis à la main avec /model fable, et selon le plan il est parfois facturé sur les usage credits. Dans l'API, Fable coûte quatre fois plus par token que Sonnet (état de novembre 2026). En mode -p, personne ne verra la demande d'accord, donc Claude Code le facture sur les usage credits sans demander. --model fable dans une boucle est une décision financière, pas technique.
Abonnement ou clé API
Le mode -p utilise la clé chaque fois que la variable est définie. Une session interactive te la demande une fois et retient la réponse. Après approbation, tu paies chaque token sur le compte API, même si ton plan est payé. Tu changes ce choix avec l'interrupteur "Use custom API key" dans /config, visible seulement quand la variable est définie, et /status montre quelle connexion est active. La clé a du sens en CI avec --bare ou pour la facturation d'une équipe. Les tâches de /schedule et les sessions dans le cloud utilisent toujours l'abonnement.
Ce qui augmente le coût sans améliorer la réponse
- un subagent envoyé "chercher une réponse plus intelligente" : c'est le même modèle ou un plus petit, sur la même tâche ;
maxou Fable sur une routine quetscvérifiera de toute façon ;- une boucle
/loopoubliée dans une longue conversation ; - des skills, des plugins et des serveurs MCP que tu n'utilises pas et qui voyagent avec chaque tour ;
/compactdans une énorme session quand tu n'as pas besoin de l'historique :/clearne coûte rien.
La revue du capitaine
- Chaque
claude -pdes scripts a--model,--max-turnset--max-budget-usd. - Pas de vaisseau amiral sur la routine. Dans les scripts, il n'y a ni
--model fableni--effort max. - La connexion.
claude auth status --textmontre l'abonnement quand tu comptes dessus, etenv | grep ANTHROPIC_API_KEYn'affiche rien. - Les boucles. La partie Loops de
/usagene montre aucune boucle que tu as oubliée.
L'erreur typique de l'agent : tu demandes un renommage, et Claude propose /model fable et /effort max "pour que rien n'échappe", ou écrit ces drapeaux dans un script. Tu la reconnais au nom du modèle et au niveau dans la commande. Un renommage est vérifié par tsc, pas par une réflexion plus profonde, donc tu paies plus cher pour la même réponse.
Étape suivante
Fais un essai sur un seul fichier et demande : "Ajoute dans scripts/generate-tests.sh le drapeau --max-budget-usd avec le montant de l'exécution d'essai multiplié par deux, et dans un commentaire au-dessus de la boucle note d'où vient ce chiffre. Ne lance pas la boucle". Ensuite un commit, par exemple "Freins de coût dans les scripts". Dans l'éditeur à côté, tu saisiras les chiffres de ton essai, et le calculateur montrera combien paiera toute la boucle et si la limite n'est pas trop serrée.
N'oublie pas : la poudre se compte avant la bataille, et pour un quart de routine on n'envoie pas le vaisseau amiral.
Code de cette leçon : App.tsx
// Calculateur de boucle avec freins : ce que paiera un script avec claude -p, calculé d’après ton exécution d’essai
import { useState } from 'react';
export type Level = 'ok' | 'warn' | 'error';
export type Model = 'haiku' | 'sonnet' | 'opus' | 'fable';
export type Effort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
export type Kind = 'routine' | 'difficile';
export interface Finding {
level: Level;
text: string;
}
export interface Plan {
files: number;
testTurns: number;
testCost: string;
maxTurns: number;
budget: string;
model: Model;
effort: Effort;
kind: Kind;
smarterSubagent: boolean;
}
export interface Estimate {
expectedRuns: number;
worstRuns: number;
expectedUsd: number | null;
worstUsd: number | null;
suggestedBudget: number | null;
}
export function num(text: string): number | null {
const t = text.trim().replace(',', '.');
if (t === '') return null;
const n = Number(t);
return Number.isFinite(n) && n > 0 ? n : null;
}
// Unité : le coût de ton exécution d’essai sur un seul fichier. Le coût d’un tour est approché par la moyenne de l’essai.
export function estimate(p: Plan): Estimate {
const files = Math.max(0, Math.floor(p.files));
const turns = Math.max(1, p.testTurns);
const cost = num(p.testCost);
const budget = num(p.budget);
const perRunWorst = Math.max(1, p.maxTurns) / turns;
let worstPerRun = perRunWorst;
if (cost !== null && budget !== null) {
const capRuns = budget / cost + 1 / turns;
worstPerRun = Math.min(perRunWorst, capRuns);
}
return {
expectedRuns: files,
worstRuns: files * worstPerRun,
expectedUsd: cost === null ? null : files * cost,
worstUsd: cost === null ? null : files * worstPerRun * cost,
suggestedBudget: cost === null ? null : Math.ceil(cost * 2 * 100) / 100,
};
}
export function review(p: Plan): Finding[] {
const out: Finding[] = [];
const cost = num(p.testCost);
const budget = num(p.budget);
if (p.maxTurns < p.testTurns) {
out.push({ level: 'error', text: '--max-turns ' + p.maxTurns + ' est inférieur aux ' + p.testTurns + ' tours de l’essai : les exécutions se termineront sur error_max_turns.' });
}
if (budget === null) {
out.push({ level: 'warn', text: 'Sans --max-budget-usd, le seul frein est --max-turns.' });
} else if (cost === null) {
out.push({ level: 'warn', text: 'Saisis le total_cost_usd de l’essai pour juger la limite.' });
} else if (budget < cost) {
out.push({ level: 'error', text: 'Limite inférieure au coût de l’essai : la plupart des exécutions seront arrêtées par error_max_budget_usd et ne laisseront qu’un .tmp.' });
} else if (budget < cost * 1.5) {
out.push({ level: 'warn', text: 'Peu de marge. Un fichier plus difficile que l’essai atteindra la limite, et la réponse qui la dépasse compte quand même.' });
} else {
out.push({ level: 'ok', text: 'Limite avec de la marge : elle arrêtera une exécution qui tourne en rond, sans gêner les exécutions normales.' });
}
if (p.model === 'fable') {
out.push({ level: 'error', text: 'Fable en -p : selon le plan, il passe sur les usage credits, et personne ne verra la demande d’accord.' });
}
if (p.kind === 'routine') {
if (p.effort === 'max') out.push({ level: 'error', text: 'max sur de la routine réfléchit trop : tu paies plus cher une réponse pas meilleure qu’avec high.' });
else if (p.effort === 'xhigh' || p.effort === 'high') out.push({ level: 'warn', text: 'De toute façon, tsc ou les tests vérifieront la routine. Le medium par défaut suffit, et low pour un renommage.' });
if (p.model === 'opus') out.push({ level: 'warn', text: 'Pour des exécutions de routine, Sonnet suffit.' });
} else {
if (p.effort === 'low') out.push({ level: 'warn', text: 'Un problème difficile sur low : Claude donnera plus vite un point de départ, mais vérifiera moins. Envisage high ou xhigh.' });
if (p.model === 'haiku') out.push({ level: 'warn', text: 'Haiku est un modèle pour les tâches simples des subagents, pas pour un problème difficile.' });
}
if (p.smarterSubagent) {
out.push({ level: 'error', text: 'Un subagent pour une réponse plus intelligente, c’est le même modèle ou un plus petit sur la même tâche : plus de tokens, la même qualité.' });
}
return out;
}
export function command(p: Plan): string {
const parts = ['claude -p "Écris des tests Vitest pour @$FILE."', '--model ' + p.model];
if (p.effort !== 'medium') parts.push('--effort ' + p.effort);
parts.push('--max-turns ' + p.maxTurns);
const budget = num(p.budget);
if (budget !== null) parts.push('--max-budget-usd ' + budget);
parts.push('> "$TEST_FILE.tmp" || continue');
return parts.join(' ');
}
export function fmt(n: number): string {
return n.toFixed(2);
}
const START: Plan = {
files: 9,
testTurns: 4,
testCost: '',
maxTurns: 5,
budget: '',
model: 'sonnet',
effort: 'medium',
kind: 'routine',
smarterSubagent: false,
};
export const AGENT_MISTAKE: Plan = { ...START, model: 'fable', effort: 'max', maxTurns: 30 };
const LEVEL_CLASS: Record<Level, string> = {
ok: 'text-emerald-400',
warn: 'text-amber-400',
error: 'text-rose-400',
};
function Field(props: { label: string; value: string | number; onChange: (v: string) => void; hint?: string }) {
return (
<label className="flex flex-col gap-1 text-sm">
<span className="font-semibold">{props.label}</span>
<input className="rounded bg-slate-900 p-1 font-mono" value={props.value} onChange={(e) => props.onChange(e.target.value)} />
{props.hint ? <span className="text-xs text-slate-400">{props.hint}</span> : null}
</label>
);
}
export default function App() {
const [p, setP] = useState<Plan>(START);
const set = <K extends keyof Plan>(key: K, value: Plan[K]) => setP({ ...p, [key]: value });
const e = estimate(p);
const findings = review(p);
return (
<div className="min-h-screen space-y-4 bg-slate-950 p-4 text-slate-100">
<h1 className="text-xl font-bold">Combien paiera la boucle ?</h1>
<p className="text-sm text-slate-300">Les chiffres de l’essai, tu les saisis toi-même : un seul fichier, le même modèle, --output-format json, puis jq.</p>
<div className="flex flex-wrap gap-2 text-sm">
<button type="button" className="rounded bg-slate-800 px-2 py-1 hover:bg-slate-700" onClick={() => setP(START)}>La routine de la leçon</button>
<button type="button" className="rounded bg-slate-800 px-2 py-1 hover:bg-slate-700" onClick={() => setP(AGENT_MISTAKE)}>Erreur de l’agent : le vaisseau amiral sur la routine</button>
</div>
<div className="grid gap-3 md:grid-cols-3">
<Field label="Fichiers dans la boucle" value={p.files} onChange={(v) => set('files', Number(v) || 0)} />
<Field label="num_turns de l’essai" value={p.testTurns} onChange={(v) => set('testTurns', Number(v) || 1)} />
<Field label="total_cost_usd de l’essai" value={p.testCost} onChange={(v) => set('testCost', v)} hint="Ton estimation du rapport, vide = on compte en essais" />
<Field label="--max-turns" value={p.maxTurns} onChange={(v) => set('maxTurns', Number(v) || 1)} />
<Field label="--max-budget-usd" value={p.budget} onChange={(v) => set('budget', v)} hint="vide = sans limite" />
<label className="flex flex-col gap-1 text-sm">
<span className="font-semibold">Tâche</span>
<select className="rounded bg-slate-900 p-1" value={p.kind} onChange={(ev) => set('kind', ev.target.value as Kind)}>
<option value="routine">routine (renommage, tests selon un modèle)</option>
<option value="difficile">problème difficile (erreur d’un autre, faille)</option>
</select>
</label>
<label className="flex flex-col gap-1 text-sm">
<span className="font-semibold">--model</span>
<select className="rounded bg-slate-900 p-1 font-mono" value={p.model} onChange={(ev) => set('model', ev.target.value as Model)}>
{['haiku', 'sonnet', 'opus', 'fable'].map((m) => <option key={m} value={m}>{m}</option>)}
</select>
</label>
<label className="flex flex-col gap-1 text-sm">
<span className="font-semibold">--effort</span>
<select className="rounded bg-slate-900 p-1 font-mono" value={p.effort} onChange={(ev) => set('effort', ev.target.value as Effort)}>
{['low', 'medium', 'high', 'xhigh', 'max'].map((m) => <option key={m} value={m}>{m}</option>)}
</select>
</label>
<label className="flex items-center gap-2 text-sm">
<input type="checkbox" checked={p.smarterSubagent} onChange={(ev) => set('smarterSubagent', ev.target.checked)} />
demander à un subagent de vérifier la réponse, par prudence
</label>
</div>
<pre className="overflow-x-auto whitespace-pre-wrap rounded bg-slate-900 p-2 font-mono text-xs">{command(p)}</pre>
<section className="grid gap-2 text-sm md:grid-cols-2">
<p className="rounded border border-slate-700 p-2">
D’habitude : {fmt(e.expectedRuns)} x essai{e.expectedUsd !== null ? ' = ' + fmt(e.expectedUsd) + ' USD d’estimation' : ''}
</p>
<p className="rounded border border-slate-700 p-2">
Au pire (chaque exécution jusqu’à la limite) : {fmt(e.worstRuns)} x essai{e.worstUsd !== null ? ' = ' + fmt(e.worstUsd) + ' USD d’estimation' : ''}
</p>
</section>
{e.suggestedBudget !== null ? (
<p className="text-sm">Limite proposée : le coût de l’essai fois deux, soit --max-budget-usd {e.suggestedBudget}.</p>
) : null}
<p className="text-xs text-slate-400">Les montants sont une estimation de Claude Code d’après les prix catalogue, pas une facture. Changer de modèle ou d’effort, c’est un nouvel essai.</p>
<ul className="space-y-1 text-sm">
{findings.map((f) => (
<li key={f.text} className={LEVEL_CLASS[f.level]}>{f.level}: {f.text}</li>
))}
</ul>
</div>
);
}Tu as repéré une erreur dans cette leçon ?
Teste tes connaissances
Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.
1. La limite du plan disparaît au milieu de la semaine, alors que tu travailles comme d'habitude. Par quoi commences-tu ?
2. Qu'est-ce qui augmente le coût sans améliorer la réponse ?
Voici 2 des 3 questions de cette leçon. Réponds aux autres dans le jeu.
Tâches pratiques dans le jeu
- Tri vertical
Mets les étapes dans l'ordre avant de lancer generate-tests.sh avec --max-budget-usd sur tous les fichiers :