Prompt engineering avance pour Claude Code et Codex : concevoir des briefs de tâche fiables
Concevez des prompts Claude Code/Codex avec brief, critères d'acceptation, vérification et boucle sûre.
Quand Claude Code ou Codex produit des résultats irréguliers, le problème n’est pas toujours le modèle. Très souvent, c’est la manière dont la tâche est transmise. Le prompt engineering avancé n’est pas une formule magique. C’est une conception de flux de travail : objectif, périmètre, contexte, contraintes, critères d’acceptation, vérification et passage de relais.
Ce guide explique comment construire un “paquet de prompt” réutilisable pour Claude Code et Codex. Un débutant peut copier les modèles, mais le niveau de conception convient aussi aux équipes, aux dépôts réels, aux travaux parallèles, au code de production et aux articles publiés. Pour les bases, lisez d’abord 5 conseils pour de meilleurs prompts et les bonnes pratiques CLAUDE.md.
Les comportements des outils changent. Les affirmations sur les fonctionnalités doivent donc venir des sources officielles. Pour Claude Code, commencez par Claude Code overview, Memory et prompt engineering overview. Pour Codex, utilisez OpenAI Codex docs et AGENTS.md guidance.
Avance veut dire contrat de travail
Un mauvais prompt n’est pas seulement court. Il n’a pas de règles de décision, ne dit pas quels fichiers sont interdits, ne définit pas la fin du travail et ne demande pas de preuve. Avec ces trous, l’agent devine.
Un prompt pratique doit fonctionner comme un petit contrat.
| Partie | Ce qu’il faut écrire | Risque si absent |
|---|---|---|
| Goal | Résultat attendu | La réponse semble correcte mais résout autre chose |
| Scope | Ce qui peut ou ne peut pas changer | Des refactorings inutiles apparaissent |
| Context | Docs, code similaire, références officielles | L’agent copie un ancien modèle ou invente |
| Constraints | Règles et changements interdits | Dépendances, API ou ton changent sans accord |
| Acceptance criteria | Comment juger la fin | La revue devient subjective |
| Verification | Commandes et contrôles manuels | Le travail se termine sans preuve |
La vue d’ensemble du prompt engineering chez Anthropic part des critères de succès et des tests empiriques. Pour des agents de code, ce principe est encore plus important, car Claude Code et Codex peuvent lire des fichiers, les modifier et lancer des commandes avant que le résultat soit vraiment validé.
Mettez le paquet de prompt dans un fichier
Taper une longue consigne dans le chat à chaque fois est difficile à relire et à réutiliser. Un fichier prompt-packet.md rend la tâche stable. Le script Bash suivant crée un paquet minimal.
cat > prompt-packet.md <<'EOF'
# Goal
Improve one published article so it is practical, accurate, and ready for review.
# Scope
May edit:
- site/src/content/blog/example-article.mdx
Do not edit:
- heroImage
- slug
- unrelated articles
- package or deployment files
# Context to read
- AGENTS.md
- site/src/content/blog/claude-md-best-practices.mdx
- Official docs relevant to the article topic
# Constraints
- Preserve existing frontmatter keys unless this task explicitly changes them.
- Use copy-pasteable examples, not pseudocode.
- Avoid unsupported claims. Link to official docs for tool behavior.
- Keep paragraphs short enough for mobile reading.
# Acceptance criteria
- updatedDate is 2026-06-02.
- The article has at least three concrete use cases.
- The article names specific pitfalls and how to avoid them.
- The article includes an internal link, an official external link, and a natural CTA.
- The final section explains what was actually verified.
# Verification
- node scripts/check-code-fences.mjs
- node scripts/check-updated-article-quality.mjs
- Read the diff once as a critical reviewer.
# Return format
- Changed files
- Key improvements
- Checks run
- Residual risks
EOF
Donnez ensuite une consigne courte : “Lis d’abord prompt-packet.md, inspecte le fichier cible et le contexte listé, puis travaille uniquement dans le Scope.” Ce n’est pas de la bureaucratie. Cela évite que l’agent modifie une page voisine, une image, un fichier de configuration ou du code hors sujet.
Vérifiez le prompt avant de l’utiliser
Un prompt reste du texte naturel, donc sa qualité dérive facilement. Un petit validateur attrape les oublis de structure. Enregistrez ceci dans check-prompt-packet.cjs.
// save as check-prompt-packet.cjs
const fs = require("node:fs");
const file = process.argv[2] || "prompt-packet.md";
const text = fs.readFileSync(file, "utf8");
const required = [
"# Goal",
"# Scope",
"# Context to read",
"# Acceptance criteria",
"# Verification",
"# Return format",
];
const missing = required.filter((heading) => !text.includes(heading));
const hasDoNotTouch = /do not (edit|change|touch)/i.test(text);
const hasCommand = /npm run|npm test|pnpm |yarn |node scripts\//i.test(text);
if (missing.length || !hasDoNotTouch || !hasCommand) {
console.error("Prompt packet is not ready.");
if (missing.length) console.error("Missing headings: " + missing.join(", "));
if (!hasDoNotTouch) console.error("Add an explicit do-not-touch boundary.");
if (!hasCommand) console.error("Add at least one verification command.");
process.exit(1);
}
console.log("Prompt packet looks actionable.");
Lancez-le ainsi :
node check-prompt-packet.cjs prompt-packet.md
Le contrôle est volontairement simple. Dans les opérations éditoriales de Masa, les erreurs les plus fréquentes venaient d’une limite “ne pas toucher” absente ou d’une preuve finale oubliée. Le même problème existe dans le code produit : sans définition de fin, la revue devient une question de goût.
Transformez les objectifs vagues en critères d’acceptation
“Améliore cet article”, “rends-le meilleur pour le SEO” et “prépare pour la production” sont des intentions utiles, mais elles ne se vérifient pas. Transformez-les en critères qui passent ou échouent.
Mauvais prompt :
Améliore cet article et renforce le SEO.
Prompt utilisable :
Réécris l'article comme un guide pratique pour développeurs qui débutent avec Claude Code.
Acceptance criteria:
- Le titre contient "Claude Code" et "prompt engineering".
- La description fait moins de 120 caractères.
- Le corps contient au moins trois cas d'usage concrets.
- Il y a au moins deux mauvais exemples de prompt et deux versions améliorées.
- L'article contient un lien vers la documentation officielle et des liens internes.
- La dernière section dit ce qui a réellement été vérifié.
- Exécute le contrôle des code fences après édition et rapporte le résultat.
Pour une implémentation, les critères doivent être techniques.
Acceptance criteria:
- Ne pas changer le type de l'API publique.
- Ajouter une validation et des erreurs visibles par l'utilisateur.
- Ajouter ou mettre à jour au moins un test de chemin d'échec.
- Exécuter npm test et npm run build, puis rapporter les résultats.
- Expliquer les fichiers modifiés et les fichiers pertinents inspectés sans changement.
Ces critères ne servent pas à microgérer l’agent. Ils servent à partager la norme de revue avant le travail.
Gérez le budget de contexte
La documentation Memory de Claude Code explique que CLAUDE.md et auto memory sont chargés comme contexte, pas comme configuration forcée. Plus long ne veut pas dire mieux suivi. Un gros contexte peut cacher la règle essentielle.
Découpez le contexte en trois couches.
| Couche | Exemples | Emplacement |
|---|---|---|
| Toujours nécessaire | Commandes de build, conventions, zones interdites | CLAUDE.md ou AGENTS.md |
| Propre à la tâche | Fichier cible, exemple proche, barre qualité | prompt-packet.md |
| À lire si besoin | Specs longues, vieux comptes rendus, logs bruts | Mentionner le fichier seulement |
Le piège classique est de tout coller dans le prompt. Si vous mélangez notes anciennes, journal de réunion, logs et demande actuelle, l’agent doit deviner la priorité. Écrivez plutôt l’ordre de lecture.
Context to read in order:
1. AGENTS.md for project rules.
2. The target article.
3. One similar high-quality article for tone and structure.
4. Official docs only for tool behavior.
Ignore:
- Old brainstorming notes unless they contradict the current implementation.
- Unrelated product pages.
- Generated files and build output.
Cette consigne réduit l’exploration inutile. Elle protège aussi les travaux parallèles, car l’agent ne doit pas interpréter tous les fichiers visibles comme modifiables.
Séparez exemples et contraintes
Un exemple montre la forme à imiter. Une contrainte définit la limite. Les mélanger produit des demandes floues.
Mauvais prompt :
Fais cette page comme l'article sur la productivité.
Meilleur prompt :
Reference style:
- Use site/src/content/blog-fr/claude-code-productivity-tips.mdx only for section density and CTA placement.
- Do not copy its examples or claims.
Constraints:
- Keep this article focused on prompt engineering.
- Do not introduce pricing claims.
- Preserve heroImage and slug.
Ne vous arrêtez pas à “ne casse rien”. Donnez aussi le périmètre positif. “N’ajoute pas de bibliothèque” devient “utilise uniquement les dépendances existantes”. “Ne change pas trop” devient “modifie seulement le fichier listé et conserve l’API publique”.
Demandez une boucle d’itération sûre
Pour un travail sérieux, une consigne géante est moins fiable qu’une boucle.
- Lire la cible, les règles et l’exemple le plus proche.
- Résumer brièvement le plan.
- Modifier uniquement dans le périmètre.
- Vérifier avec commandes et contrôles manuels.
- Rapporter changements, preuves et risques.
Vous pouvez l’écrire directement.
Workflow:
- First inspect the target file and the nearest quality reference.
- If the change is larger than two files, explain the plan before editing.
- Edit only the files listed in Scope.
- After editing, run the Verification commands if feasible.
- End with a verification receipt, not a general summary.
Une verification receipt est le reçu du travail. Le modèle complet est dans le guide des verification receipts, mais la forme minimale suffit au quotidien.
Verification receipt:
- Changed files:
- Commands run:
- Results:
- Manual checks:
- Could not verify:
- Residual risks:
Quatre cas d’usage concrets
Le premier cas est la correction de bug. Donnez le symptôme, les étapes de reproduction, le comportement attendu, les logs et les fichiers autorisés. Demandez à l’agent d’expliquer la cause probable avant d’éditer, puis de corriger avec le plus petit diff et d’ajouter un test de chemin d’échec.
Le deuxième cas est une petite fonctionnalité. Décrivez le changement visible, les limites API ou base de données, le modèle UI à suivre et les tests attendus. Pour ajouter une catégorie à un formulaire de contact, incluez les options, la validation, le payload, l’événement analytics et la localisation.
Le troisième cas est la réécriture d’article. Donnez le lecteur, l’intention de recherche, la longueur cible, les exemples obligatoires, les pièges, les liens internes, le CTA et les sources officielles. Chez ClaudeCodeLab, cela évite de transformer un article faible en simple résumé plus fluide.
Le quatrième cas est la revue de code. Un prompt de revue a surtout besoin d’un format. Demandez gravité, fichier et ligne, condition de reproduction, direction de correction et tests manquants. Au lieu de “revue générale”, priorisez sécurité, perte de données, API publique et chemins d’erreur non testés.
Échecs fréquents
Échec 1 : mélanger les objectifs. “Refactorise, accélère, améliore le SEO et change le CTA” regroupe plusieurs tâches. Gardez un objectif par paquet.
Échec 2 : n’écrire que des interdictions. “Ne casse rien” ne dit pas ce qui est permis. Associez zone interdite et zone autorisée.
Échec 3 : traiter un savoir ancien comme comportement officiel. Claude Code, Codex, memory, settings et AGENTS.md peuvent changer. Citez les documents officiels et n’affirmez pas plus que ce qu’ils disent.
Échec 4 : rendre la vérification optionnelle. Si une commande ne peut pas tourner, l’agent doit le dire. Un trou déclaré vaut mieux qu’un silence.
Échec 5 : laisser les bons prompts dans le chat. Déplacez les instructions qui fonctionnent vers prompt-packet.md, CLAUDE.md ou une checklist de revue. Pour les équipes, ajoutez les règles de passation.
CTA : standardiser avant d’étendre
Vous n’avez pas besoin de réécrire ce paquet chaque jour. Commencez avec la fiche gratuite pour les contrôles quotidiens, comparez les modèles réutilisables sur produits et templates, puis utilisez formation ou consultation Claude Code si votre équipe doit adapter CLAUDE.md, permissions, revue, verification receipts et qualité éditoriale à un dépôt réel.
Ce que j’ai vérifié
Pour cet article, j’ai vérifié dans l’overview officiel que Claude Code peut lire un codebase, modifier des fichiers et exécuter des commandes. J’ai vérifié dans Memory la distinction entre CLAUDE.md, auto memory et configuration imposée. J’ai aussi confirmé dans le prompt engineering overview d’Anthropic qu’il faut définir critères de succès et méthodes de test avant d’optimiser un prompt, puis j’ai aligné la partie Codex sur OpenAI Codex docs et AGENTS.md guidance. La conclusion pratique : traiter le prompt comme un contrat de travail relisible, pas comme un simple message de chat.
PDF gratuit: cheatsheet Claude Code
Saisissez votre email et téléchargez une page avec commandes, habitudes de review et workflow sûr.
Nous protégeons vos données et n'envoyons pas de spam.
À propos de l'auteur
Masa
Ingénieur spécialisé dans les workflows pratiques avec Claude Code.
Articles liés
Permission receipt Claude Code : portée, preuves et rollback
Modèle de permission receipt pour Claude Code : actions autorisées, limites d'approbation, commandes de preuve, rollback et CTAs revenus.
Agent Harness securise pour Claude Code et Codex : permissions, verification et rollback
Construisez un Agent Harness pratique pour Claude Code et Codex avec politiques, plan, verification et recuperation.
Sous-agents Claude Code : guide pratique pour déléguer sans perdre le contrôle
Guide pratique des sous-agents Claude Code pour répartir articles et code : règles, prompts, pièges et checklist.