Architecture d’un projet

Architecture d’un projet

03 indispensables

Les fichiers à avoir dans chaque projet pour que l’agent comprenne le code et que les secrets restent secrets.

L’arborescence

  • mon-projet/
  • AGENTS.md1CommittéLes consignes lues par l’agent à chaque conversation
  • CLAUDE.md1OptionnelUne seule ligne, @AGENTS.md, pour Claude Code
  • .agents/
  • skills/2CommittéLes skills du projet, un dossier par skill
  • supabase-audit-rls/2Un skill installé avec npx skills add
  • SKILL.md2Le mode d’emploi du skill
  • verifier-formulaires/2Un skill écrit pour ton projet
  • SKILL.md2
  • scripts/2OptionnelLes scripts que le skill peut lancer
  • .claude/
  • skills/2Les mêmes skills, vus par Claude Code
  • .env.example3CommittéLes noms des variables, sans les valeurs
  • .env.local3Jamais committéLes vraies valeurs, sur ta machine uniquement
  • .gitignore3CommittéEmpêche d’envoyer .env.local sur GitHub
  • README.mdCommittéPour les humains : installer et lancer
  • package.jsonCommittéLes dépendances et les commandes
  • src/Le code de l’application

Le fichier AGENTS.md

Partie 1

AGENTS.md · CLAUDE.md

Le fichier que l’agent lit avant chaque demande. Il présente le projet, les commandes à lancer et les règles à respecter. Sans lui, l’agent redécouvre le projet à chaque conversation et devine tes conventions.

Ce qu’on y met

  • Le projet en deux lignes et la stack utilisée.
  • Les commandes : lancer, tester, vérifier les types.
  • Où se trouve quoi dans les dossiers.
  • Les règles : ce qu’il doit toujours faire, ce qu’il ne doit jamais toucher.

Les règles

  • À la racine du projet, committé avec le code.
  • Court : une page suffit. Ce qui est long va dans un skill.
  • Codex, Cursor et T3 lisent AGENTS.md ; Claude Code lit CLAUDE.md, qui renvoie vers AGENTS.md.
  • Quand l’agent répète une erreur, ajoute une règle.

AGENTS.md

Markdown
# AGENTS.md

## Projet
Application de réservation pour salles de sport.
Stack : Next.js (App Router), TypeScript, Supabase, Tailwind.

## Commandes
- `npm run dev` : lancer en local (http://localhost:3000)
- `npm run typecheck` : vérifier les types
- `npm run test` : lancer les tests

## Organisation
- `src/app/` : les pages
- `src/components/` : les composants réutilisables
- `src/lib/` : l’accès à Supabase et la logique métier

## Règles
- Toujours lancer `npm run typecheck` avant de terminer.
- Ne jamais lire ni modifier `.env.local`.
- Toute nouvelle variable d’environnement va aussi dans `.env.example`.
- Pas de nouvelle dépendance sans le signaler.

CLAUDE.md

Markdown
@AGENTS.md

Les skills

Partie 2

.agents/skills/ · .claude/skills/

Voir la banque de skills

Un skill est un dossier avec un fichier SKILL.md : une méthode que l’agent charge seulement quand la tâche le demande. Rangés dans le projet, ils sont versionnés avec le code et toute l’équipe utilise les mêmes.

Ce qu’on y met

  • Un dossier par skill, au nom du skill.
  • Un SKILL.md avec un name et une description en tête de fichier.
  • Les étapes à suivre, écrites comme une checklist.
  • Si besoin, des scripts ou des documents de référence à côté.

Les règles

  • La description dit quand utiliser le skill : c’est elle que l’agent lit pour choisir.
  • npx skills add installe le skill dans le projet, pour chaque agent.
  • Un skill par tâche répétée : audit, revue, formulaire, migration…
  • Commit les skills avec le code, comme AGENTS.md.

Installer un skill existant

Terminal
npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices

.agents/skills/verifier-formulaires/SKILL.md

Markdown
---
name: verifier-formulaires
description: Vérifie qu’un formulaire valide ses champs côté serveur et affiche des erreurs claires. À utiliser quand on crée ou modifie un formulaire.
---

# Vérifier un formulaire

1. Repérer le schéma de validation du formulaire.
2. Vérifier que la même validation tourne côté serveur.
3. Tester un envoi vide, un email invalide et un texte trop long.
4. Lister les problèmes avec le fichier et la ligne concernés.

Les variables d’environnement

Partie 3

.env.example · .env.local · .gitignore

Les clés d’API, les adresses de base de données et les secrets ne s’écrivent jamais dans le code. Ils vivent dans des variables d’environnement : un fichier local sur ta machine, et les réglages de l’hébergeur en production.

Ce qu’on y met

  • .env.example : la liste des variables, valeurs vides. Committé, il sert de mode d’emploi.
  • .env.local : les vraies valeurs. Il reste sur ta machine.
  • .gitignore : ignore tous les .env sauf .env.example.
  • En production : les mêmes noms, renseignés dans Vercel, Netlify ou ton hébergeur.

Les règles

  • Préfixe NEXT_PUBLIC_ ou VITE_ : la valeur part dans le navigateur, donc visible par tous. Seulement des clés publiques.
  • Sans préfixe : la valeur reste côté serveur. C’est là que vont les secrets.
  • Une clé envoyée sur GitHub par erreur se régénère : la supprimer du code ne suffit pas, elle reste dans l’historique.
  • Après un changement en production, redéploie pour que la valeur soit prise en compte.

.env.example

Fichier env
# Publiques : envoyées au navigateur
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
NEXT_PUBLIC_POSTHOG_KEY=

# Secrètes : côté serveur uniquement
SUPABASE_SECRET_KEY=
STRIPE_SECRET_KEY=
OPENAI_API_KEY=

Créer ton fichier local

Terminal
cp .env.example .env.local

.gitignore

Fichier gitignore
# Variables d’environnement
.env*
!.env.example