08. Astuces pratiques

@diagram:lesson-contract
duration :: 14 min lecture
deliverable :: Sélection de 3 astuces adaptées à ton prochain objectif
outcome :: Disposer d'un répertoire de prompts réutilisables pour les situations courantes de développement assisté par agent

Une astuce, ici, c’est un prompt prêt à coller. Tu repères ta situation, tu copies le bloc, tu remplaces les crochets par ton contexte, tu envoies.

Astuce 1. Démarrer un prototype en 20 minutes

Tu pars de zéro et tu veux du concret à l’écran vite.

Je veux créer un prototype web local.
Avant de coder, pose-moi uniquement les 5 questions nécessaires pour cadrer : utilisateur, tâche, entrées, sorties, validation.
Ensuite, propose une V1 sans backend.

Validation : tu obtiens une V1 qui tient en une page.

Astuce 2. Transformer une idée vague en spec

Tu as une intuition de produit, pas encore de cap clair.

Transforme cette idée en SPEC.md : [colle l'idée].
Format : objectif, utilisateur, entrées, sorties, contraintes, critères de validation, hors périmètre.
Garde le document court.

Validation : tu peux supprimer tout ce qui n’est pas actionnable.

Astuce 3. Demander à un agent d’analyser un repo

Tu ouvres un projet existant et tu ne sais pas par où l’attraper.

Analyse ce dépôt.
Retour attendu :
1. rôle du projet
2. stack détectée
3. commandes d'installation/lancement
4. dossiers importants
5. risques ou points flous
Ne modifie aucun fichier.

Validation : tu sais lancer le projet ou tu sais ce qui bloque.

Astuce 4. Ajouter une fonctionnalité ciblée

Le projet tourne et tu veux greffer une brique sans tout casser.

Contexte : [résumé projet].
Contraintes : [ce qu'il ne faut pas changer].
Validation : [commande + comportement attendu].
Commence par proposer un plan, sans modifier les fichiers.

Validation : le plan modifie peu de fichiers et respecte la contrainte.

Astuce 5. Corriger une erreur frontend

La page casse et la console crache une erreur.

J'ai ce bug frontend.
Action faite : [ce que j'ai fait].
Résultat actuel : [ce que je vois].
Erreur console : [coller].
Résultat attendu : [ce que je veux].
Analyse la cause probable. Corrige uniquement le nécessaire.

Validation : page fonctionnelle et erreur disparue.

Astuce 6. Corriger une erreur terminal

Une commande échoue et tu ne lis qu’une stack trace.

Commande lancée : [commande].
Erreur complète :
[coller sortie]
Contexte : [installation / build / lancement].
Propose une cause probable et une correction minimale.
Ne supprime pas de fichiers.

Validation : la commande passe ou l’erreur change de manière compréhensible.

Astuce 7. Préparer une intégration API IA

Tu veux brancher une génération réelle sans exposer ta clé.

Je veux ajouter une génération IA à ce prototype.
Avant de coder, propose :
- architecture sûre pour ne pas exposer la clé
- variables d'environnement nécessaires
- endpoint minimal
- fallback si l'API échoue
- risques de coût

Validation : aucune clé secrète dans le front-end publié.

Astuce 8. Ajouter une base de données

localStorage ne suffit plus, tu veux un vrai stockage.

À partir de SPEC.md, propose un modèle de données minimal.
Retour attendu : tables, colonnes, relations, règles de sécurité simples.
Ne code pas encore l'intégration.

Validation : tu comprends ce qui sera stocké et pourquoi.

Astuce 9. Préparer un déploiement

Le prototype est prêt, tu veux le mettre en ligne proprement.

Prépare ce projet pour un déploiement.
Étapes attendues :
1. identifier la stack
2. vérifier la commande de build
3. lister les variables d'environnement
4. produire un README de déploiement
Ne pousse rien en ligne.

Validation : npm run build passe localement.

Astuce 10. Faire une revue anti-dérive

Tu sens que le projet s’éloigne de ce que tu avais prévu.

Compare le projet actuel avec SPEC.md.
Liste :
- ce qui respecte la spec
- ce qui manque
- ce qui dépasse le périmètre
- les 3 prochaines actions recommandées
Ne modifie rien.

Validation : tu peux décider quoi couper ou corriger.

Astuce 11. Créer une compétence réutilisable pour ton agent

Tu veux que l’agent garde tes règles d’un jour sur l’autre.

À partir de nos décisions dans NOTES.md, rédige une règle projet pour AGENTS.md.
Elle doit inclure : style de code, périmètre, validation, interdictions, format de retour.

Validation : tu peux relancer l’agent demain avec les mêmes règles.

Astuce 12. Arrêter une boucle d’échecs

L’agent enchaîne les patchs ratés et tu tournes en rond.

Stop modifications.
Résume les 3 dernières tentatives, pourquoi elles ont échoué, et propose une stratégie de diagnostic en 3 étapes.
Je veux comprendre avant de retenter une correction.

Validation : tu reviens à une hypothèse testable au lieu d’empiler les patchs.

Check-list de validation

@diagram:checklist
item-1 :: Tu choisis une astuce selon une situation précise.
item-2 :: Tu ajoutes ton contexte avant d'envoyer le prompt.
item-3 :: Tu demandes un plan pour les tâches longues.
item-4 :: Tu vérifies avec une commande ou un test manuel.
item-5 :: Tu notes les prompts utiles dans NOTES.md.

Pièges fréquents

• Copier une astuce sans contexte. Colle ton projet, ta stack et le résultat attendu avant d’envoyer.
• Lancer un agent sans limite. Dis-lui ce qu’il ne doit pas toucher.
• Oublier la vérification. Un prompt utile se juge au résultat vérifié.
• Garder toutes les astuces. Supprime ceux qui ne collent pas à ta pratique.

Conclusion de parcours. Ce que tu as construit

Le parcours se termine. Voici l’état final du projet fil rouge, le générateur de fiches produit pour la gourde inox 750 ml.

Arborescence du projet à la fin du parcours

fiche-produit-ia/
├── src/
│   ├── components/
│   │   ├── ProductForm.jsx         : formulaire avec les 5 champs
│   │   ├── ProductResult.jsx       : bloc de résultat avec bouton Copier
│   │   └── HistoryList.jsx         : historique des 5 dernières fiches
│   ├── lib/
│   │   ├── generateProductSheet.js : logique de génération locale
│   │   └── storage.js              : lecture/écriture localStorage
│   ├── App.jsx                     : assemblage principal
│   └── App.css                     : styles minimalistes
├── SPEC.md                         : spécification V1 verrouillée
├── NOTES.md                        : décisions, tests manuels, commandes utiles
├── AGENTS.md                       : règles projet pour l'agent
├── README.md                       : lancement + test + limites connues
└── package.json

Fiches produit générées pendant le parcours

Sur les 7 modules, tu as gardé le même cas de test : la gourde inox 750 ml. Tu as produit au minimum trois fiches.

• La fiche V1 (module 4, étape 6) : titre, description et 5 bullet points générés depuis le formulaire.
• La fiche avec historique (module 5) : la même fiche, cette fois sauvegardée dans localStorage et toujours visible après rechargement.
• Le test manuel documenté (module 6) : une recette dans NOTES.md qui liste 7 étapes de vérification.

Les astuces réutilisables que tu as constituées

Dans NOTES.md, tu as accumulé les éléments réutilisables du parcours.

1. Le brief de départ (module 1) : le template pour cadrer une nouvelle idée.
2. Le SPEC.md de référence (module 2) : objectif, utilisateur, entrées, sorties, contraintes, critères.
3. Les règles agent dans AGENTS.md (module 3) : ce que l’agent ne doit jamais faire sans demander.
4. Les prompts de délégation en 6 éléments (module 5) : contexte, objectif, fichiers, contraintes, validation, retour.
5. La boucle de debug (module 6) : reproduire, capturer, formuler, corriger petit, relancer, committer.
6. Les conventions de structure (module 7) : components/, lib/, README opérationnel, commits atomiques.
7. Les 12 astuces (ce module) : des recettes prêtes à l’emploi pour les situations courantes.

Ce que tu peux faire ensuite

Le prototype tourne en local avec une génération simulée. Tu peux maintenant l’ouvrir sur quatre pistes.

• Brancher une vraie API IA (Astuce 7) : OpenAI, Claude ou autre, avec la clé côté serveur.
• Persister sur une base de données (Astuce 8) : Supabase ou SQLite, quand localStorage ne suffit plus.
• Déployer (Astuce 9) : Vercel, Netlify ou ton propre VPS, avec npm run build en premier.
• Adapter la méthode à un autre projet : le SPEC.md, les règles agent et la boucle de debug tiennent sur n’importe quel prototype.

La règle du parcours reste valable : tu cadres, l’agent exécute, tu vérifies.