Avant d'écrire une seule ligne de code — mettre en place un projet Python axé sur la qualité avec Claude Code

Quand Claude Code écrit votre projet, votre rôle change. Vous n'êtes pas un dactylographe. Vous êtes un architecte et un relecteur. Le code arrive vite — parfois plus vite que vous ne pouvez le lire. Des outils de qualité constituent votre infrastructure de revue. Ils détectent ce que vous manquez.

Ceci est la Partie 1 d'une série en trois parties sur la mise en place de la qualité d'un projet Python quand Claude Code est votre développeur. Nous couvrons ici les fondations : les fichiers et la configuration qui doivent exister avant toute ligne de code applicatif.

Le schéma pour chaque recommandation : ce que fait l'outil, un prompt à coller dans Claude Code, et ce qu'il faut vérifier ensuite.

pyproject.toml — la constitution du projet

Chaque outil Python lit pyproject.toml. Ruff, pytest, mypy, les build backends — tous y cherchent leur configuration. Un seul fichier, une seule source de vérité.

Point encore plus important pour le développement assisté par IA : Claude Code le lit aussi. Quand votre projet dispose d'un pyproject.toml bien configuré, Claude comprend vos conventions. Longueur de ligne, règles de linting, chemins de tests — il les détecte automatiquement et génère du code conforme.

Le prompt :

Create a pyproject.toml for a Python 3.11 project. Configure ruff
(line-length 120, select E/F/W/I/UP/B/SIM rules) and pytest
(testpaths = tests, quiet output with short tracebacks).

Ce qu'il faut vérifier : Le fichier existe à la racine du projet. ruff check . s'exécute sans erreur de configuration. pytest --co trouve le répertoire de tests.

Le fichier généré devrait ressembler approximativement à ceci :

[project]
name = "my-project"
version = "0.1.0"
requires-python = ">=3.11"

[tool.ruff]
line-length = 120

[tool.ruff.lint]
select = ["E", "F", "W", "I", "UP", "B", "SIM"]

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-q --tb=short"

Structure de répertoires avec des imports propres

L'organisation du projet détermine si les imports fonctionnent ou cassent. Faites-le correctement une fois et oubliez-le.

La répartition : src/ pour le code applicatif, tests/ pour les tests, scripts/ pour les scripts opérationnels qui ne font pas partie du package. Un conftest.py dans le répertoire de tests gère la configuration du chemin d'import pour que les tests trouvent votre code source.

Le prompt :

Set up the project directory structure: src/ for application code
with __init__.py, tests/ with a conftest.py that adds src/ to
sys.path, scripts/ for operational scripts, and docs/ for
documentation.

Ce qu'il faut vérifier : python -c "import src" fonctionne depuis la racine du projet. Les tests peuvent importer les modules applicatifs sans hacks sys.path dispersés dans chaque fichier de test.

.gitignore — complet dès le départ

Claude Code génère des fichiers. Ruff crée un cache. Pytest écrit des données de couverture. Les environnements virtuels contiennent des milliers de fichiers. Aucun d'entre eux n'a sa place dans le contrôle de version.

Configurez .gitignore avant tout le reste, car nettoyer un dépôt qui a déjà suivi des fichiers générés est fastidieux.

Le prompt :

Create a .gitignore for a Python project. Include __pycache__,
.venv, .env, dist, build, .ruff_cache, .mypy_cache, htmlcov,
.coverage, .DS_Store, *.egg-info, and .pytest_cache.

Ce qu'il faut vérifier : Exécutez git status après avoir créé et activé un environnement virtuel. Aucun fichier .venv/ n'apparaît.

.editorconfig — cohérence entre les outils

Différents éditeurs, différents paramètres par défaut. Claude Code génère du code avec un style d'indentation, votre éditeur le reformate avec un autre, le diff n'est que du bruit.

.editorconfig standardise les règles d'espacement dans tous les outils qui touchent à vos fichiers. La plupart des éditeurs le respectent nativement ou via un plugin.

Le prompt :

Create an .editorconfig: UTF-8, LF line endings, 4-space indent
for Python, tab indent for Makefile, 2-space for YAML. Trim
trailing whitespace.

Ce qu'il faut vérifier : Le fichier existe à la racine du projet. Ouvrez un fichier Python dans votre éditeur — l'indentation doit être de 4 espaces.

Ruff — linter et formatter avant la première ligne

Ruff remplace flake8, isort, pyupgrade et Black en un seul outil. Il est assez rapide pour s'exécuter à chaque sauvegarde sans que vous le remarquiez.

Pourquoi c'est encore plus important avec du code généré par IA : Claude produit parfois des imports inutilisés, un formatage incohérent ou des variables masquées. Ce ne sont pas des bugs — c'est du bruit qui s'accumule. Ruff les détecte automatiquement, gardant la base de code propre quel que soit l'auteur (humain ou machine) du code.

Le prompt :

Install ruff and run it on the project. Fix any issues automatically.
Show me the results.

Ce qu'il faut vérifier : ruff check . ne retourne aucun résultat. ruff format --check . ne signale aucune modification nécessaire.

Exécuter ruff après chaque passe de génération de Claude Code devient un réflexe. Voyez-le comme un correcteur orthographique pour le style de code.

Makefile — votre palette de commandes

Un Makefile donne à chaque opération courante un nom court et facile à retenir. Au lieu de mémoriser python -m pytest tests/ -q --tb=short, vous tapez make test.

C'est important pour le développement assisté par IA car vous pouvez dire à Claude Code « exécute make check » et il lance exactement la même séquence lint-puis-test que celle que vous exécutez localement. Commandes cohérentes, résultats cohérents.

Le prompt :

Create a Makefile with these targets: install (pip install -r
requirements.txt), test (pytest), lint (ruff check), fmt (ruff
format + ruff check --fix), check (lint then test). All targets
should be .PHONY.

Ce qu'il faut vérifier : make check exécute le lint suivi des tests. Les deux passent.

Le Makefile généré :

.PHONY: install test lint fmt check

install:
    pip install -r requirements.txt

test:
    pytest

lint:
    ruff check .

fmt:
    ruff format .
    ruff check --fix .

check: lint test

requirements.txt — suivre les dépendances dès le départ

Deux fichiers : requirements.txt pour les dépendances de production, requirements-dev.txt pour les outils de développement. Le fichier dev inclut le fichier de production pour éviter de maintenir la même liste deux fois.

Des pins de version minimale (ex. requests>=2.31) empêchent les cassures silencieuses quand une dépendance publie une nouvelle version majeure. Pinez tôt — ajouter rétroactivement des pins dans un projet avec 30 dépendances non verrouillées est un après-midi que vous ne savourerez pas.

Le prompt :

Create requirements.txt for production dependencies and
requirements-dev.txt that includes -r requirements.txt plus
pytest, pytest-cov, and ruff.

Ce qu'il faut vérifier : pip install -r requirements-dev.txt réussit dans un environnement virtuel vierge. pytest --version et ruff --version fonctionnent tous les deux.

La checklist du jour un

Sept fichiers, sept prompts, zéro ligne de code applicatif :

1. pyproject.toml — configuration des outils, métadonnées du projet
2. src/__init__.py + tests/conftest.py — structure de répertoires propre
3. .gitignore — garder les fichiers générés hors du contrôle de version
4. .editorconfig — espacement cohérent entre les outils
5. Ruff configuré et validé — linter et formatter actifs
6. Makefile — interface de commandes standard
7. requirements.txt + requirements-dev.txt — dépendances suivies

Chaque fichier ici sert le même objectif : vous donner confiance dans du code que vous n'avez pas écrit à la main. Quand Claude Code génère un module demain, ruff le lintera, pytest le testera, et make check vérifiera que l'ensemble du projet fonctionne toujours.

Dans la Partie 2, nous ajoutons le filet de sécurité : tests, CI, pre-commit hooks et détection de secrets.

Où exécuter tout cela

Chaque projet a besoin d'une machine pour exécuter la CI et héberger les environnements de staging. Hetzner vous offre un CX22 à 4,85 €/mois avec 10 € de crédit de départ — largement suffisant pour des runners GitHub Actions auto-hébergés, un serveur de staging, ou les deux.

Si Claude Code construit votre projet et que vous souhaitez que la couche d'agent IA soit gérée pour vous, xCloud fait tourner OpenClaw en hébergé — pour que vous puissiez vous concentrer sur les prompts et le code plutôt que sur l'infrastructure.

(Liens affiliés — nous percevons une petite commission si vous vous inscrivez, sans aucun coût pour vous.)

Si vous utilisez un assistant IA pour mettre en place un projet comme celui-ci, collez l'URL de cet article dans la conversation. Il reprendra les choix d'outils et les patterns de prompts pour les appliquer à votre configuration spécifique.