CLAUDE.md pour une API Python (FastAPI, pytest)

# CLAUDE.md — API Python
 
<!-- Adaptez les commandes à votre outillage (uv, pip + venv, poetry…).
     Supprimez les lignes qui ne s'appliquent pas à votre projet. -->
 
## Aperçu
 
API HTTP en Python (FastAPI ou framework équivalent), typée, testée avec pytest.
 
## Environnement et commandes
 
- Installer les dépendances : `uv sync` (ou `pip install -r requirements.txt`
  dans un environnement virtuel activé)
- Lancer l'API en local : `uv run uvicorn app.main:app --reload`
- Tests : `uv run pytest` ; un seul test : `uv run pytest tests/test_users.py::test_create`
- Lint et format : `uv run ruff check .` et `uv run ruff format .`
- Typage : `uv run mypy app`
 
Toujours lancer les tests du module modifié avant de conclure.
 
## Arborescence
 
- `app/main.py` : création de l'application et montage des routeurs
- `app/routers/` : un fichier par ressource (endpoints uniquement)
- `app/services/` : logique métier, sans dépendance au framework HTTP
- `app/schemas/` : modèles de validation des entrées et sorties
- `app/db/` : accès aux données et migrations
- `tests/` : miroir de `app/`, fixtures partagées dans `tests/conftest.py`
 
## Conventions
 
- Annotations de type obligatoires sur les fonctions publiques.
- Les routeurs valident et délèguent ; aucune requête SQL dans un routeur.
- Erreurs métier : exceptions dédiées, converties en réponses HTTP à un seul endroit.
- Tout nouvel endpoint s'accompagne d'au moins un test de succès et un test d'erreur.
- Configuration lue depuis les variables d'environnement, jamais codée en dur.
 
## À ne pas faire
 
- Ne pas modifier les migrations déjà appliquées : en créer une nouvelle.
- Ne pas lire ni afficher le contenu de `.env`.
- Ne pas désactiver un test qui échoue pour « faire passer » la suite.
- Ne pas ajouter de dépendance sans l'indiquer explicitement dans la réponse.

Ce modèle de CLAUDE.md s'adresse aux projets d'API écrits en Python, qu'ils reposent sur FastAPI ou sur un framework comparable. Il est volontairement générique : les commandes sont données avec uv, mais un commentaire rappelle l'équivalent pip et chaque ligne peut être remplacée par l'outillage que vous utilisez déjà.

Ce que contient le modèle

• Environnement et commandes : installation des dépendances, lancement du serveur local, tests (suite complète et test unitaire isolé), lint, formatage et vérification des types. La possibilité de lancer un seul test est précieuse : Claude peut valider une correction sans attendre toute la suite.
• Arborescence : séparation entre routeurs, services métier, schémas de validation et accès aux données. Ce découpage évite que la logique métier finisse dans les endpoints.
• Conventions : annotations de type, gestion centralisée des erreurs, configuration par variables d'environnement, et un test de succès plus un test d'erreur pour chaque nouvel endpoint.
• Interdits : ne pas réécrire une migration déjà appliquée, ne pas lire le fichier .env, ne pas désactiver un test en échec.

Comment l'adapter

1. Outillage : remplacez uv run par poetry run, python -m ou rien du tout selon votre projet. Vérifiez chaque commande dans un terminal avant de la publier dans le fichier.
2. Arborescence : décrivez vos vrais dossiers. Si votre API suit une organisation par fonctionnalité plutôt que par couche, dites-le simplement.
3. Outils de qualité : si vous n'utilisez ni ruff ni mypy, supprimez ces lignes plutôt que de laisser des commandes qui échouent.
4. Base de données : précisez l'outil de migration utilisé et la commande pour créer une nouvelle migration.

Pièges fréquents

• Des commandes qui ne marchent pas : une commande périmée fait perdre plus de temps qu'une commande absente, car Claude tente de l'exécuter puis cherche à contourner l'erreur.
• Compter sur le fichier pour protéger les secrets : la consigne « ne pas lire .env » est utile, mais seule une règle deny du type Read(./.env) dans settings.json bloque effectivement la lecture. Le modèle de settings.json d'équipe proposé parmi ces ressources en donne un exemple.
• Mélanger préférences personnelles et règles d'équipe : ce fichier est versionné et partagé. Vos habitudes individuelles vont dans ~/.claude/CLAUDE.md ou dans un CLAUDE.local.md non versionné.

Vous pouvez aussi lancer /init dans un projet existant : Claude Code analyse le dépôt et propose un premier CLAUDE.md, que vous compléterez avec les éléments de ce modèle.

La leçon Le fichier CLAUDE.md explique où placer ce fichier et comment il se combine avec les autres niveaux de mémoire.