Repository, projet, fichier, dossier, dépendance.

1Pourquoi ce chapitre est fondamental

Avant d’apprendre à demander à Claude Code ou Codex de modifier un logiciel, il faut comprendre ce qu’ils manipulent.

Un logiciel n’est pas “un site” ou “une application” de manière abstraite. Un logiciel est un ensemble organisé de fichiers, dossiers, configurations, dépendances, règles métier, tests, scripts et documents techniques. Si cette organisation est propre, le logiciel peut évoluer. Si elle est confuse, chaque modification devient risquée.

Un entrepreneur qui ne comprend pas cette structure dépend entièrement des développeurs ou de l’IA. Il peut demander une modification, mais il ne sait pas si l’IA a modifié le bon fichier, ajouté une dépendance inutile, touché à une configuration critique ou cassé une partie du projet.

Votre objectif n’est pas de devenir développeur manuel. Votre objectif est plus stratégique : devenir capable de piloter un logiciel comme un dirigeant produit-tech.

Cela commence par une compétence simple mais décisive : savoir lire la structure d’un projet.

Un dépôt bien organisé est un actif.
Un dépôt désordonné est une dette.
Un dépôt incompris est un risque.

4Repository local et repository distant

Un repository local est la version du projet présente sur votre ordinateur ou dans votre environnement de développement.

Un repository distant est la version stockée sur un service comme GitHub.

La relation entre les deux est essentielle.

Quand vous récupérez un projet depuis GitHub vers votre ordinateur, on dit que vous faites un clone.

Quand vous envoyez vos modifications locales vers GitHub, on dit que vous faites un push.

Quand vous récupérez les modifications faites ailleurs vers votre machine, on dit que vous faites un pull.

Même si vous ne tapez pas ces commandes vous-même, vous devez comprendre la logique.

Pour travailler proprement avec Claude Code ou Codex, vous devez toujours savoir :

sur quel repository on travaille ;

sur quelle branche on travaille ;

quels fichiers ont été modifiés ;

si les modifications sont seulement locales ou déjà envoyées sur GitHub ;

si une pull request existe ;

si les tests ont été exécutés ;

si la branche peut être fusionnée ;

si un rollback est possible.

Un dirigeant qui comprend cela contrôle beaucoup mieux ses projets.

5La racine du projet : le “root”

La racine du projet, souvent appelée root, est le dossier principal du projet.

C’est le niveau le plus haut du repository. C’est là qu’on trouve généralement les fichiers de configuration majeurs.

Exemple de structure simplifiée :

enytrack/
├── README.md
├── composer.json
├── package.json
├── .env.example
├── .gitignore
├── src/
├── config/
├── templates/
├── public/
├── assets/
├── migrations/
├── tests/
└── docs/

Ici, enytrack/ est la racine du projet.

Les fichiers directement à la racine sont souvent très importants. Ils servent à comprendre le projet rapidement.

Par exemple :

README.md explique le projet.

composer.json liste les dépendances PHP, souvent dans un projet Symfony ou Laravel.

package.json liste les dépendances JavaScript, souvent pour le front-end.

.env.example montre les variables d’environnement nécessaires.

.gitignore indique quels fichiers Git ne doit pas suivre.

docker-compose.yml décrit parfois les services nécessaires : base de données, serveur, cache, mailer, etc.

Dockerfile décrit comment construire l’environnement applicatif.

Un bon réflexe professionnel consiste toujours à commencer par la racine du projet. Avant de demander à Claude Code de modifier un module, il faut savoir quel type de projet vous avez sous les yeux.

Est-ce un projet Symfony ?
Un projet Laravel ?
Un projet Node ?
Un projet React ?
Un projet Next.js ?
Un projet Astro ?
Un projet WordPress ?
Un projet hybride ?
Un monolithe ?
Une API ?
Une PWA ?
Un simple site statique ?

La racine donne souvent la réponse.

8Chemin de fichier : path, chemin relatif, chemin absolu

Un fichier se trouve à un emplacement précis dans le projet. Cet emplacement s’appelle un chemin, ou path.

Exemple :

src/Controller/InvoiceController.php

Ce chemin signifie :

dans le dossier src,
puis dans le dossier Controller,
se trouve le fichier InvoiceController.php.

Un chemin relatif est un chemin exprimé depuis le dossier actuel ou depuis la racine du projet.

Exemple :

templates/invoice/show.html.twig

Un chemin absolu est un chemin complet depuis la racine du système de fichiers.

Exemple :

/Users/monsieur/Projects/enytrack/templates/invoice/show.html.twig

Dans vos échanges avec Claude Code ou Codex, il faut utiliser les chemins de fichiers quand vous voulez être précis.

Mauvaise instruction :

“Corrige la page facture.”

Bonne instruction :

“Analyse et corrige uniquement les fichiers liés à l’affichage facture, notamment src/Controller/InvoiceController.php et les templates dans templates/invoice/. Ne modifie pas le module paiement.”

Un bon vocabulaire réduit les erreurs de l’IA.

10Dépendance directe et dépendance transitive

Il existe deux types importants de dépendances.

Une dépendance directe est une dépendance que votre projet déclare explicitement.

Exemple : vous installez Stripe SDK. Stripe SDK est une dépendance directe.

Une dépendance transitive est une dépendance utilisée par une dépendance.

Exemple : Stripe SDK peut lui-même utiliser d’autres packages. Ces packages deviennent des dépendances transitives.

C’est important parce qu’un projet peut avoir 20 dépendances directes mais 500 dépendances transitives.

Vous ne les avez pas choisies directement, mais elles sont présentes dans le projet.

Cela crée un risque appelé supply chain risk, ou risque de chaîne d’approvisionnement logicielle. Cela signifie qu’une faille ou une compromission dans un package externe peut affecter votre projet.

Un entrepreneur SaaS n’a pas besoin d’être expert cybersécurité pour comprendre cela. Mais il doit savoir poser les bonnes questions :

cette dépendance est-elle connue ?

est-elle maintenue ?

a-t-elle beaucoup de dépendances transitives ?

est-elle nécessaire ?

peut-on faire plus simple ?

a-t-elle des failles connues ?

quelle licence utilise-t-elle ?

est-elle utilisée en production ou seulement en développement ?

11Gestionnaires de dépendances

Les dépendances sont généralement installées par des outils appelés gestionnaires de dépendances, ou package managers.

Quelques exemples :

Composer pour PHP.

npm, Yarn ou pnpm pour JavaScript/TypeScript.

pip ou Poetry pour Python.

Maven ou Gradle pour Java.

Cargo pour Rust.

Bundler pour Ruby.

Dans un projet Symfony, vous verrez souvent :

composer.json
composer.lock
vendor/

Dans un projet JavaScript ou React/Next/Astro, vous verrez souvent :

package.json
package-lock.json
node_modules/

Le fichier composer.json ou package.json déclare les dépendances souhaitées.

Le fichier composer.lock ou package-lock.json verrouille les versions exactes installées.

Le dossier vendor/ ou node_modules/ contient les dépendances installées.

Il faut comprendre le rôle des fichiers lock.

Un fichier lock est une preuve de stabilité. Il évite que deux machines installent des versions différentes des dépendances.

Sans fichier lock, un projet peut fonctionner sur l’ordinateur A et casser sur l’ordinateur B, simplement parce qu’une dépendance a changé de version.

Dans un projet professionnel, le fichier lock doit généralement être conservé dans Git. Il garantit que l’environnement est reproductible.

12Dépendance de production et dépendance de développement

Toutes les dépendances n’ont pas le même rôle.

Une dépendance de production est nécessaire pour faire fonctionner le logiciel en production.

Exemple : Stripe SDK si votre site encaisse des paiements.

Une dépendance de développement est utile seulement pour développer, tester, analyser ou compiler.

Exemple : un outil de test, un outil de formatage, un outil de linting.

Dans package.json, on distingue souvent :

dependencies : dépendances nécessaires au fonctionnement.

devDependencies : dépendances nécessaires au développement.

Cette différence est importante pour la performance, la sécurité et la simplicité.

Un projet trop chargé en dépendances inutiles devient plus lourd, plus fragile et plus difficile à maintenir.

Votre règle doit être :

Si personne n’est capable d’expliquer pourquoi une dépendance existe, elle doit être questionnée.

13Versioning des dépendances

Les dépendances ont des versions.

Exemple :

stripe/stripe-php: 16.0.0
symfony/framework-bundle: 7.2.0
react: 19.0.0

Une version suit souvent une convention appelée Semantic Versioning, ou SemVer.

Le format courant est :

MAJOR.MINOR.PATCH

Exemple :

3.7.4

3 est la version majeure.
7 est la version mineure.
4 est le patch.

En principe :

un changement de PATCH corrige un bug sans changer le comportement attendu ;

un changement de MINOR ajoute des fonctionnalités compatibles ;

un changement de MAJOR peut introduire des changements cassants.

Un changement cassant signifie qu’une ancienne manière d’utiliser la dépendance peut ne plus fonctionner.

Exemple simple :

Passer de version 2 à version 3 peut exiger des modifications dans votre code.

C’est pourquoi il ne faut jamais demander naïvement :

“Mets toutes les dépendances à jour.”

La bonne demande est :

“Analyse les dépendances obsolètes et vulnérables. Propose une mise à jour progressive, en distinguant patch, minor et major. Ne fais pas de major upgrade sans plan de migration, tests et rollback.”

14Les fichiers de configuration critiques

Un projet logiciel contient souvent des fichiers qui ne sont pas directement du code métier, mais qui contrôlent le comportement du projet.

Ces fichiers sont critiques.

Exemples :

.env : variables d’environnement réelles, souvent avec secrets.

.env.example : modèle sans secret.

.gitignore : fichiers à exclure de Git.

composer.json : dépendances PHP.

composer.lock : versions exactes PHP.

package.json : dépendances et scripts JavaScript.

package-lock.json : versions exactes JavaScript.

docker-compose.yml : services locaux ou de déploiement.

Dockerfile : construction d’un conteneur.

README.md : documentation principale.

phpunit.xml : configuration des tests PHP.

vite.config.js : configuration de build front-end.

tsconfig.json : configuration TypeScript.

.github/workflows/ : pipelines GitHub Actions.

Ces fichiers doivent être traités avec prudence. Une petite modification peut casser l’installation, la compilation, les tests ou la production.

Par exemple, modifier .env peut casser la connexion à la base de données.
Modifier package.json peut changer les scripts de build.
Modifier composer.json peut ajouter ou retirer une dépendance critique.
Modifier .github/workflows/deploy.yml peut casser le déploiement automatique.

Vous devez donc demander à Claude Code/Codex de signaler toute modification sur ces fichiers.

Instruction recommandée :

“Tout changement sur un fichier de configuration racine doit être explicitement listé et justifié dans le rapport final.”

15Les fichiers secrets : attention absolue

Un fichier secret contient des informations sensibles.

Exemples :

mot de passe base de données ;

clé API Stripe ;

clé Brevo ;

secret JWT ;

clé OpenAI ;

clé de chiffrement ;

token GitHub ;

identifiant SMTP ;

secret webhook.

Ces informations sont souvent stockées dans .env.

Un fichier .env réel ne doit pas être envoyé sur GitHub public. Il ne doit pas être partagé dans une conversation, un ticket ou une capture d’écran.

Le fichier .env.example, en revanche, peut être partagé. Il sert de modèle sans les vraies valeurs.

Exemple :

DATABASE_URL=
STRIPE_SECRET_KEY=
BREVO_API_KEY=
APP_SECRET=

Le principe est simple :

.env = secrets réels, privé.
.env.example = structure attendue, partageable.

Si Claude Code ou Codex vous demande de coller des clés API dans un prompt, il faut éviter. Il faut utiliser des variables d’environnement, jamais exposer les secrets dans le code.

Règle à apprendre par cœur :

Un secret écrit en dur est une faille.

16Structure propre contre structure confuse

Une structure propre permet de comprendre, maintenir, tester et faire évoluer.

Une structure confuse ralentit tout et augmente les risques.

Exemple de structure confuse :

project/
├── index.php
├── test.php
├── test2.php
├── functions.php
├── old/
├── new/
├── final/
├── final2/
├── assets2/
├── backup/
├── code/
├── real-code/
└── temp/

Cette structure inspire peu confiance. Elle montre une absence de méthode.

Exemple de structure plus professionnelle :

project/
├── README.md
├── composer.json
├── package.json
├── .env.example
├── src/
│   ├── Controller/
│   ├── Entity/
│   ├── Repository/
│   ├── Service/
│   └── Security/
├── config/
├── templates/
├── assets/
├── public/
├── migrations/
├── tests/
└── docs/

Ici, on comprend immédiatement les grandes zones du projet.

La structure n’est pas une décoration. C’est une architecture de travail.

Quand vous travaillez avec l’IA, une bonne structure augmente la qualité des résultats. L’IA comprend mieux où intervenir. Elle évite davantage les modifications hors périmètre. Elle peut produire des changements plus localisés.

Un projet désordonné rend l’IA moins fiable.

17Cohésion et couplage : deux notions de haut niveau

Pour progresser vers un niveau professionnel élevé, vous devez connaître deux notions : cohésion et couplage.

La cohésion mesure à quel point les éléments d’un fichier ou d’un dossier appartiennent au même sujet.

Un fichier très cohésif fait une chose claire.

Exemple :

InvoiceService.php contient la logique de facturation. C’est cohérent.

Un fichier peu cohésif fait trop de choses.

Exemple :

GlobalService.php contient factures, emails, paiements, utilisateurs, véhicules. C’est mauvais.

Le couplage mesure à quel point une partie du logiciel dépend d’une autre.

Un couplage faible est généralement préférable. Cela signifie qu’on peut modifier une partie sans casser tout le système.

Un couplage fort rend le logiciel fragile. Si modifier une page facture casse le paiement, le stock, les emails et le tableau de bord, le couplage est trop fort.

Dans un SaaS comme Enytrack, il faut rechercher :

forte cohésion dans chaque module ;

couplage maîtrisé entre modules ;

interfaces claires entre domaines ;

pas de logique métier dispersée partout.

C’est une notion d’architecture essentielle.

18Repository et intelligence artificielle : pourquoi l’organisation devient encore plus importante

Avec Claude Code et Codex, la vitesse de production augmente. Mais si la structure du repository est mauvaise, l’IA produit plus vite dans le désordre.

L’IA peut :

modifier trop de fichiers ;

ajouter une dépendance inutile ;

dupliquer une logique existante ;

créer une nouvelle structure parallèle ;

contourner une règle métier existante ;

casser des tests ;

modifier une configuration sensible ;

ajouter un fichier au mauvais endroit ;

inventer une architecture non alignée avec le projet.

Votre rôle est de donner un cadre.

Avant toute mission IA, vous devez demander :

1. Analyse la structure du repository.
2. Identifie la stack technique.
3. Liste les fichiers probablement concernés.
4. Ne modifie rien avant d’avoir proposé un plan.
5. Indique les fichiers à risque.
6. N’ajoute aucune dépendance sans justification.
7. Ne modifie pas les fichiers de configuration racine sans autorisation.
8. Travaille sur une branche dédiée.
9. Ajoute ou adapte les tests.
10. Fournis un rapport final avec les fichiers modifiés.

Ce cadre transforme l’IA en exécutant contrôlé.

Sans cadre, l’IA devient un accélérateur de chaos.

19Les dépendances comme décision stratégique

Un débutant voit une dépendance comme une solution rapide.
Un professionnel voit une dépendance comme un contrat de long terme.

Avant d’accepter une dépendance, il faut poser plusieurs questions.

La dépendance est-elle nécessaire ?
Peut-on faire plus simple avec le framework existant ?
Est-elle maintenue ?
Est-elle populaire ou reconnue ?
A-t-elle des failles connues ?
Sa licence est-elle compatible avec un usage commercial ?
Est-elle légère ?
Ajoute-t-elle beaucoup de dépendances transitives ?
Sera-t-elle encore maintenue dans deux ans ?
Peut-on la retirer facilement si besoin ?
Est-elle utilisée en production ?
Apporte-t-elle une vraie valeur métier ?

Exemple :

Pour générer un PDF fiscal ou un dossier de preuve, une dépendance PDF robuste peut être justifiée.

Pour afficher un simple bouton ou une petite animation, ajouter une grosse librairie front-end est souvent injustifié.

Dans votre logique d’entreprise, chaque dépendance doit être vue comme un coût de maintenance potentiel.

Règle :

20Ce qu’un repository professionnel doit contenir

Un repository professionnel doit idéalement contenir :

un README.md clair ;

un fichier d’exemple d’environnement ;

des dépendances déclarées proprement ;

un fichier lock ;

une structure cohérente ;

un dossier de tests ;

une documentation minimale ;

une configuration Git propre ;

des scripts d’installation et de test ;

une politique claire sur les secrets ;

des règles de contribution si plusieurs personnes ou IA travaillent dessus ;

des instructions projet pour les agents IA si vous utilisez Codex/Claude Code ;

des fichiers de CI/CD si le projet est industrialisé ;

un historique Git propre.

Dans vos projets ENYWERE, il faudra tendre vers ce standard.

Un repository qui ne peut pas être installé, compris, testé ou déployé proprement est un risque opérationnel.

21La méthode de lecture d’un repository en 10 étapes

Quand vous ouvrez un nouveau projet, suivez toujours cette méthode.

Étape 1 : regarder la racine du projet.

Étape 2 : ouvrir README.md.

Étape 3 : identifier la stack technique avec les fichiers racine.

Étape 4 : repérer les dépendances dans composer.json, package.json, ou équivalent.

Étape 5 : repérer les dossiers principaux : src, config, public, templates, tests.

Étape 6 : repérer les fichiers secrets ou modèles d’environnement.

Étape 7 : chercher s’il existe des tests.

Étape 8 : chercher s’il existe une documentation.

Étape 9 : chercher s’il existe une configuration de déploiement ou CI/CD.

Étape 10 : demander à l’IA un rapport de structure avant toute modification.

Prompt utile :

“Analyse la structure de ce repository sans modifier de fichier. Identifie la stack technique, les dossiers principaux, les fichiers critiques, les dépendances majeures, les scripts disponibles, les risques apparents et les zones à ne pas modifier sans validation. Réponds sous forme de rapport clair.”

Ce prompt doit devenir un réflexe.