Runbook de première tâche Claude Code : prompts sûrs, diff et revue avant commit

La première tâche décide si Claude Code inspire confiance

Juste après l’installation de Claude Code, il est tentant de demander une fonctionnalité complète, une grosse refactorisation ou “corrige tout ce dépôt”. C’est souvent là que la première session se dégrade. Le problème n’est généralement pas que Claude Code ne peut pas aider. Le problème est que le périmètre, la vérification, les permissions et le contexte projet ne sont pas encore partagés.

Ce runbook concerne la première tâche pratique dans un vrai dépôt. Un runbook est une checklist d’opération réutilisable. Ici, la première tâche n’est pas “construis la fonctionnalité”. C’est un petit flux : bien formuler la demande, confirmer le plan, faire un changement limité, relire le diff et laisser une note de handoff.

Si les bases sont encore nouvelles, commence par le guide de démarrage Claude Code. Pour capturer les règles du projet, combine-le avec les modèles CLAUDE.md pour Claude Code. Pour les références officielles, consulte Claude Code overview, memory et CLAUDE.md, permission modes, common workflows et la CLI reference.

flowchart LR
  A["Lire le dépôt"] --> B["Proposer 3 options sûres"]
  B --> C["Choisir 1 tâche"]
  C --> D["Relire le plan d'abord"]
  D --> E["Créer le plus petit diff"]
  E --> F["Vérifier tests et diff"]
  F --> G["Écrire une note de handoff"]

Ce qui fait une bonne première tâche

La première tâche ne se mesure pas surtout à la taille du résultat. Elle sert à savoir si le flux peut rester fiable. Les meilleures premières tâches ont cinq qualités.

Qualité	Sens simple	Bon exemple
Locale	Pas de production, données client ni effet externe	Vérifier les commandes du README ou ajouter une assertion
Bornée	Les fichiers et le point d’arrêt sont visibles	Un composant, un test, un document
Vérifiable	Une commande, page ou diff prouve le succès	`npm.cmd run test`, `git diff --check`
Réversible	Un mauvais résultat peut être jeté vite	Fichiers source normaux, pas exports générés
Explicable	Un humain comprend pourquoi le changement existe	Raison, risque et incertitude sont écrits

Des demandes comme “refais l’authentification”, “modernise tout le code” ou “corrige CI et déploie” sont de mauvaises premières tâches. Elles mélangent contexte manquant, prompts de permission, tests faibles et diffs difficiles à relire.

Pour l’onboarding d’une équipe, choisis dans ce menu avant d’inventer une tâche.

Tâche	Utilité	Condition de succès
Cartographier le dépôt	Tester la compréhension avant édition	Entry points, commandes et zones risquées sont identifiés
Résumer un test en échec	Voir la granularité de debug	Point d’échec, hypothèse et prochaine action sont clairs
Corriger une commande README obsolète	Essayer une vraie édition peu risquée	La commande tourne et le diff reste petit
Ajouter une assertion à un test existant	Évaluer l’intention et le jugement test	L’assertion protège un comportement clair
Modifier une phrase d’UI	Vérifier recherche et édition minimale	Seul le composant ciblé change
Corriger un warning lint	Mesurer la discipline de changement local	Un warning disparaît sans changement de comportement
Créer un `CLAUDE.md` minimal	Améliorer les prochaines sessions	Commandes, limites et revue sont écrites brièvement

Le point clé est “petit mais réel”. La tâche doit se connecter à l’onboarding, au diagnostic de bug, à la documentation, aux tests ou à la qualité de revue.

Prompts prêts à copier

Commence par demander à Claude Code de lire et proposer, pas d’éditer.

Lis ce dépôt et n'édite pas encore.

Retourne :
1. les principaux entry points
2. les commandes habituelles de build/test/lint
3. les répertoires risqués ou fichiers générés
4. 3 options sûres pour une première tâche de 30 minutes
5. comment vérifier et revenir en arrière pour chaque option

Après les options, choisis-en une et exige un plan.

Continue uniquement avec l'option 2. N'édite pas encore.
Écris d'abord les fichiers que tu toucherais, la raison du changement, le diff attendu,
la commande de vérification et les risques. Si le périmètre grandit, propose une option plus petite.

Autorise ensuite seulement l’édition.

Suis le plan approuvé et produis le plus petit diff possible.
Ne touche pas aux fichiers hors demande.
Après l'édition, résume les commandes de vérification exécutées, les checks échoués ou sautés,
et les risques restants.

Utilise un prompt séparé pour la revue avant commit.

Fais une revue avant commit.

1. Lis git diff et cherche les changements hors demande
2. Repère les tests manquants ou la vérification faible
3. Vérifie les risques sécurité, perte de données et configuration
4. Trouve les fichiers qui ne doivent pas être commités
5. Identifie les décisions qui demandent encore un humain

Termine par un seul verdict : "prêt pour commit", "corriger d'abord" ou "stop".

Flux de 30 minutes

Consacre les cinq premières minutes à figer l’état courant avant de déléguer. Sous Windows PowerShell :

Get-Location
git status --short
git branch --show-current
rg --files | Select-Object -First 40

Sous macOS ou Linux :

pwd
git status --short
git branch --show-current
rg --files | head -n 40

Si le worktree est déjà sale, indique quels changements appartiennent à l’humain et ne doivent pas être touchés. Sinon, le diff final devient difficile à juger.

Utilise les dix minutes suivantes pour choisir une tâche. Bons choix : une commande README obsolète, une assertion de test, ou le résumé d’un test en échec. Évite les nouvelles fonctionnalités pour la première session.

Vers la vingtième minute, privilégie la preuve plutôt que plus d’éditions. Un changement correct et expliqué vaut mieux que trois changements non vérifiés.

git diff --stat
git diff --check
git diff
git status --short

Garde les cinq dernières minutes pour une note de handoff. C’est une courte note pour la prochaine personne ou la prochaine session Claude Code. Elle compte parce que les longues conversations peuvent perdre les limites initiales, et la session suivante a besoin d’un point de départ propre.

Quatre cas d’usage concrets

Cas 1 : onboarding d’un nouveau développeur

Ne donne pas un gros ticket le premier jour. Demande à Claude Code une carte du dépôt, les commandes clés, les répertoires dangereux et les premiers fichiers à lire.

Prompt : “Crée une note d’onboarding pour un nouveau développeur. Sépare faits et hypothèses. Inclus la sortie des commandes quand c’est possible.” Le succès signifie que la note ajoute du contexte pratique au-delà du README : fichiers générés, réglages locaux, différences CI/local.

Cas 2 : note de reproduction pour un bug visible

Si le bug est “ça casse parfois”, ne commence pas par le correctif. Demande les conditions, le résultat attendu, le résultat réel, les fichiers pertinents et les logs manquants. Cela fonctionne bien avec le modèle de bug report Claude Code.

Le succès n’est pas un patch. C’est une note qu’un humain peut vérifier. Si le bug ne se reproduit pas, la sortie doit le dire et lister les logs ou données nécessaires.

Cas 3 : documentation ou texte d’interface

Sites marketing, outils admin et dashboards internes sont souvent adaptés à une première session, car un changement de texte est visible et réversible. Reste précis : un CTA, une explication de paramètres ou un paragraphe.

Le succès signifie que seuls les fichiers ciblés changent, que le sens reste intact et que le résultat peut être vérifié localement. Sur un site multilingue, vérifie aussi que tu n’as pas mis à jour une seule langue en laissant les autres incohérentes.

Cas 4 : petite amélioration de test

Si le projet a déjà des tests, ajouter une assertion est plus sûr qu’ajouter une fonctionnalité. Ajoute un cas limite, une attente de message d’erreur ou un cas de liste vide.

Des tests verts ne suffisent pas. Claude Code doit expliquer le comportement protégé par l’assertion. Une assertion impossible à expliquer devient du bruit de maintenance.

Revue du diff avant commit

Après les éditions de Claude Code, reviens à la revue humaine. Pour la première tâche, évite les commits et pushes automatiques. Les permission modes échangent confort contre supervision ; commence donc par une revue normale ou le plan mode. Évite les modes puissants comme bypass permissions sauf environnement isolé.

Checklist avant commit

[ ] Seuls les fichiers demandés ont changé
[ ] Aucun fichier généré, secret ou réglage local n'est entré
[ ] Un test ou une vérification de remplacement est enregistré
[ ] Les checks échoués ou sautés sont déclarés
[ ] Aucun diff inexpliqué ne reste
[ ] La note de handoff contient le prochain TODO

Commence par git diff --stat pour voir l’étendue. Lance git diff --check pour les espaces et l’hygiène du patch. Puis lis le diff pour repérer refactors surprises, renommages ou changements de comportement sans tests.

Échecs fréquents

Le premier échec est le périmètre trop large. Dis “vérifie le message d’erreur de login avec un test”, pas “corrige login”. Donne plus d’autonomie après des tâches petites et réussies.

Le deuxième échec est d’accepter “terminé” sans preuve. S’il n’y a pas de tests, définis une preuve de substitution : page rendue, type check, git diff --check, comparaison de logs ou commande du README.

Le troisième échec est d’approuver les permissions trop vite. Quand un prompt apparaît, demande quelle commande s’exécute, quels chemins elle touche et si elle inclut réseau ou suppression. Si les prompts sont pénibles, approuve seulement des commandes étroites au lieu d’ouvrir tout.

Le quatrième échec est la perte de contexte. Les longues conversations floutent la limite de départ. Garde la limite, les commandes exécutées et le risque restant dans la note de handoff. Ne mélange pas règles permanentes de CLAUDE.md et notes d’une session.

Le cinquième échec est d’abîmer du travail non commité. Dans un dépôt partagé, une autre personne ou un autre agent peut déjà avoir des changements. Commence par git status --short et protège explicitement les changements non liés.

Modèle de handoff

Colle ceci à la fin de la première tâche.

## Handoff note

- Task:
- Changed files:
- Verification run:
- Verification not run:
- Important diff points:
- Remaining risks:
- Do not touch next time:
- Suggested next smallest task:

Cette note est plus large qu’un message de commit. Avant commit, elle sert de brouillon de PR. Sans commit, elle devient le point de départ de la session suivante.

Prochaines étapes et offres payantes

Après une première tâche réussie, construis la répétabilité. En solo, transforme les règles récurrentes en modèles CLAUDE.md. Si approvals et sandbox restent flous, lis le guide approval et sandbox de Claude Code.

Pour des modèles, checklists et supports d’onboarding prêts à l’emploi, consulte /products/. Pour un déploiement d’équipe, un onboarding adapté au dépôt, la conception des permissions et les workflows de revue, utilise /training/. Une première tâche sûre peut être gérée avec cet article. Un rollout d’équipe demande règles, preuves et formation avant d’élargir l’usage.

Dans l’essai réel de Masa, le schéma le plus stable était : lire le dépôt d’abord, éditer un seul fichier, relire git diff ensemble et laisser une note de handoff. Les sessions qui commençaient par une grande demande créaient plus de revue qu’elles n’en économisaient. Celles qui réussissaient une tâche de 30 minutes rendaient la deuxième tâche plus facile à cadrer et à expliquer à l’équipe.