Aller au contenu principal
PraktikPraktikLe guide IA utile
S'abonner
Intermédiaire15 min

07 — Structurer un projet réutilisable

@diagram:lesson-contract
duration :: 15 min lecture
deliverable :: Projet refactoré avec structure lisible, README opérationnel et commits atomiques documentés
outcome :: Savoir organiser un projet pour qu'un agent puisse reprendre le contexte en moins de 5 minutes

Pourquoi structurer maintenant

Le prototype sert à apprendre. La structure sert à continuer.

Le déclencheur arrive vite : dès que tu ajoutes historique, API, base de données ou déploiement, le projet devient difficile à lire. Tu ne cherches pas une architecture parfaite. Tu cherches deux choses : éviter les fichiers fourre-tout, et permettre à l’agent de reprendre exactement là où tu t’es arrêté, même une semaine plus tard.

1. Nommer et organiser les fichiers d’un projet agent-friendly

La structure cible pour le générateur de fiches produit

Chaque fichier a un rôle, et l’agent en lit certains avant les autres. Voici la structure annotée, puis l’arborescence brute à recopier.

@diagram:project-structure
fiche-produit-ia/
├── src/
│   ├── components/
│   │   ├── ProductForm.jsx
│   │   ├── ProductResult.jsx
│   │   └── HistoryList.jsx
│   ├── lib/
│   │   ├── generateProductSheet.js
│   │   └── storage.js
│   ├── App.jsx
│   └── App.css
├── SPEC.md
├── NOTES.md
├── AGENTS.md (ou CLAUDE.md)
└── README.md

Rôle précis de chaque dossier :

  • components/ : composants d’affichage et d’interaction. Chaque fichier correspond à un bloc visible.
  • lib/ : logique réutilisable, sans dépendance à React, donc testable indépendamment.
  • SPEC.md : contrat de comportement de l’app, la référence que l’agent lit en premier.
  • NOTES.md : décisions prises, tests manuels, bugs connus, commandes utiles.
  • AGENTS.md ou CLAUDE.md : règles que l’agent doit respecter dans ce projet.
  • README.md : comment lancer, tester et modifier le projet, qu’on soit humain ou agent.

Conventions de nommage à respecter

Quelques règles qui font gagner du temps à l’agent :

  • Noms de composants en PascalCase : ProductForm.jsx, pas productform.jsx.
  • Fonctions utilitaires en camelCase : generateProductSheet, pas generate_product_sheet.
  • Variables d’environnement en SCREAMING_SNAKE_CASE : API_KEY, BASE_URL.
  • Fichiers de configuration à la racine du projet, pas dans src/.

Demande à l’agent de respecter ces conventions dès le début. Ajoute-les dans AGENTS.md :

# Conventions de nommage
- Composants React : PascalCase
- Fonctions utilitaires : camelCase
- Variables d'environnement : SCREAMING_SNAKE_CASE
- Un composant = un fichier, pas de mélanges

Le fichier README.agent.md

Pour les projets plus complexes ou les équipes, ajoute un fichier README.agent.md distinct du README.md humain. Ce fichier est pensé pour être lu par l’agent au démarrage de chaque session :

# README.agent.md — Contexte projet pour l'agent

## Ce que ce projet fait
Générateur de fiches produit en local. Formulaire → génération locale → copie.

## Stack
Vite + React, pas de backend, localStorage pour la persistance.

## Ce qui est verrouillé
- Pas de backend sans demande explicite.
- Pas de nouvelle dépendance sans validation.
- Le comportement de generateProductSheet() est stable.

## Ce qui peut évoluer
- L'intégration d'une API IA (voir SPEC.md V2).
- La persistance vers une base de données.

## Comment tester
npm run dev → ouvrir http://localhost:5173 → tester avec "Gourde inox 750 ml".

2. Gérer les contextes longs : quand compacter, quand repartir

Le problème du contexte long

Un agent coding a une fenêtre de contexte, c’est-à-dire la quantité de conversation qu’il garde en tête à un instant donné. Quand la conversation dépasse quelques dizaines d’échanges, ou quand le projet a beaucoup évolué, l’agent commence à « oublier » des décisions prises plus tôt. Tu le repères à un symptôme précis : il propose des solutions qui contredisent le SPEC.md, ou réintroduit une dépendance que tu avais refusée.

La règle : compacter avant de continuer

Quand une session de travail avec l’agent se termine, demande-lui de produire un résumé compact :

Résume cette session :
- fichiers modifiés et pourquoi
- décisions prises
- comportement actuel de l'app (ce qui marche)
- limites connues
- prochaines étapes recommandées

Copie ce résumé dans NOTES.md avec la date.

Quand repartir sur une nouvelle session

Repartir sur une nouvelle session vide est souvent plus efficace que de continuer une longue conversation. Pour le projet gourde inox 750 ml, quand tu reprends après une pause, commence par :

Lis SPEC.md, AGENTS.md et les 10 dernières lignes de NOTES.md.
Résume ce que tu comprends du projet avant de continuer.

Cette étape force l’agent à vérifier son contexte au lieu de travailler sur des hypothèses périmées.

Signaux qui indiquent que le contexte est trop long

  • L’agent propose une approche qu’il avait déjà abandonnée.
  • Il ignore une contrainte écrite dans SPEC.md.
  • Il renomme des fichiers que tu avais stabilisés.
  • Ses réponses deviennent imprécises ou contradictoires.

Quand tu vois ces signaux, ne continue pas. Ouvre une nouvelle conversation, donne SPEC.md et le résumé NOTES.md.

3. Versionner avec l’agent : commits atomiques et messages clairs

Le principe du commit atomique

Un commit atomique représente une seule intention, une unité de travail vérifiable. Évite les fourre-tout du genre « mise à jour de l’app » ou « fix + refactor + nouvelle feature » : si tu dois revenir en arrière, tu ne peux pas isoler ce qui a cassé.

Pour le projet gourde inox, ça donne des commits comme :

git commit -m "add localStorage history for last 5 product sheets"
git commit -m "add copy button to ProductResult component"
git commit -m "refactor generateProductSheet into lib/generateProductSheet.js"

Chaque message dit ce qui a changé et pourquoi, pas comment.

Demander à l’agent de co-écrire les messages de commit

L’agent est plus précis que toi sur ce qu’il a modifié. Après chaque tâche, demande :

Propose un message de commit court et précis pour ce changement.
Format : verbe à l'infinitif + objet + contexte si nécessaire.
Pas de "fix", "update" génériques. Describe the intent.

Gérer le diff avant de committer

Avant de committer, regarde toujours le diff :

git diff

Si le diff contient des changements non prévus dans ta demande, demande à l’agent d’expliquer ou de revenir en arrière sur ces lignes. Un diff propre te donne un historique Git lisible.

Stratégie de branches pour protéger la version stable

Quand tu expérimentes une fonctionnalité risquée (intégration API, refactor global), travaille sur une branche :

git checkout -b feat/api-integration

Si ça rate, tu reviens sur main sans effort. C’est l’équivalent du commit atomique pour les fonctionnalités qui prennent plusieurs sessions.

4. Préparer l’évolution : structurer pour que l’agent puisse reprendre

Le problème de la dette implicite

Un projet où la génération de fiches est mélangée avec le rendu React dans App.jsx est difficile à faire évoluer. Si tu demandes plus tard à l’agent de « brancher une API IA à la place de la génération locale », il devra refactorer d’abord, ce qui risque de casser l’existant.

Isoler la logique dans lib/generateProductSheet.js dès la V1 permet à l’agent de remplacer l’implémentation sans toucher aux composants.

Écrire le code pour la reprise, pas pour l’instant

Quelques principes pour le projet gourde inox qui s’appliquent à n’importe quel prototype :

Nommer les intentions, pas les détails.

// Mauvais : l'agent ne sait pas ce que cette fonction est censée faire évoluer
const process = (data) => { ... }

// Bon : l'agent comprend que cette fonction est le point d'extension pour l'API
const generateProductSheet = (input) => { ... }

Documenter les décisions temporaires dans NOTES.md.

## Décision 2024-01-15
La génération est locale (pas d'appel API) pour la V1.
Quand on brancher une API : modifier uniquement generateProductSheet.js.
Le reste de l'app ne doit pas changer.

Marquer les TODO dans le code.

// TODO V2 : remplacer par un appel API Claude ou OpenAI
// Voir SPEC.md §V2 pour les contraintes de sécurité
const generateProductSheet = (input) => {
  // génération locale
}

Ne traite pas ces TODO comme une promesse de livraison. Ils servent de signal pour l’agent lors de la prochaine reprise : voilà où l’évolution est attendue.

Préparer la V2 dans SPEC.md sans la coder

Avant de finir la V1, ajoute une section V2 dans SPEC.md :

## V2 — Évolutions prévues (non planifiées)

### V2.1 — Génération via API IA
- Ajouter un champ de configuration API via variable d'environnement.
- Garder une génération locale fallback si la clé manque.
- Ne jamais exposer la clé côté client.
- Documenter le coût estimé.

### V2.2 — Persistance sur base de données
- Remplacer localStorage par une table product_sheets.
- Champs : id, product_name, target_audience, benefits_json, generated_title, generated_description, generated_bullets_json, created_at.

Cette section V2 reste hors du périmètre actuel. Son rôle est d’empêcher l’agent d’inventer ses propres évolutions quand il n’a pas de travail immédiat.

Demander un refactor limité

Cadre la demande pour que l’agent restructure sans rien casser de visible :

Refactore le projet selon cette structure : components/ et lib/.
Contraintes : ne change pas le comportement visible, ne change pas la stack, pas de nouvelle dépendance.
Après modification, indique comment vérifier que le comportement est identique.

Tu dois vérifier avant de continuer.

Écrire un README utile

Demande :

Crée un README.md court avec :
- objectif du projet
- stack
- installation
- lancement
- test manuel (utilise le cas gourde inox 750 ml)
- limites connues

Un bon README permet à quelqu’un de reprendre le projet sans te demander « je lance quoi ? ».

Check-list de validation

@diagram:checklist
item-1 :: Les composants sont séparés de la logique dans lib/.
item-2 :: La génération est dans une fonction réutilisable generateProductSheet.
item-3 :: Le stockage local est isolé dans storage.js.
item-4 :: README.md explique comment lancer et tester le projet.
item-5 :: SPEC.md décrit la V1, les limites et les évolutions prévues.
item-6 :: Les messages de commit sont atomiques et descriptifs.
item-7 :: Le mot « gourde » apparaît dans NOTES.md comme cas de test de référence.
item-8 :: Git contient un commit stable après refactor.

Pièges fréquents

  • Refactor trop tôt. Structure après un comportement stable, pas en cours de construction.
  • Architecture trop lourde. Pas besoin de microservices pour un générateur local.
  • Clé API côté client. Risque de fuite immédiat si le projet est publié.
  • README décoratif. S’il n’aide pas à lancer, tester et modifier, il ne sert à rien.
  • NOTES.md vide. Sans trace des décisions, l’agent prend les siennes à ta place.

Suite conseillée

Le module 8 te donne les astuces réutilisables selon tes prochains besoins : prototype, debug, agent, spec, API, déploiement.