Bevor du eine Zeile Code schreibst — ein Quality-First-Python-Projekt mit Claude Code aufsetzen
Sieben Dateien, sieben Prompts, null Zeilen Anwendungscode. Wie du Linting, Formatierung, Testing und Projektstruktur einrichtest, bevor Claude Code dein erstes Feature schreibt.
Wenn Claude Code dein Projekt schreibt, ändert sich deine Rolle. Du bist kein Schreiber. Du bist Architekt und Reviewer. Der Code kommt schnell — manchmal schneller, als du ihn lesen kannst. Qualitätswerkzeuge sind deine Review-Infrastruktur. Sie fangen auf, was dir entgeht.
Dies ist Teil 1 einer dreiteiligen Serie über die Einrichtung von Python-Projektqualität, wenn Claude Code dein Entwickler ist. Hier behandeln wir das Fundament: die Dateien und Konfiguration, die existieren sollten, bevor eine einzige Zeile Anwendungscode geschrieben wird.
Das Muster für jede Empfehlung: was das Tool macht, ein Prompt, den du in Claude Code einfügen kannst, und was du danach überprüfen solltest.
pyproject.toml — die Verfassung des Projekts
Jedes Python-Tool liest pyproject.toml. Ruff, pytest, mypy, Build-Backends — sie alle suchen hier nach der Konfiguration. Eine Datei, eine einzige Quelle der Wahrheit.
Noch wichtiger für KI-gestützte Entwicklung: Claude Code liest sie ebenfalls. Wenn dein Projekt eine gut konfigurierte pyproject.toml hat, versteht Claude deine Konventionen. Zeilenlänge, Linting-Regeln, Testpfade — das wird automatisch erkannt und der generierte Code hält sich daran.
Der 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).Was du überprüfen solltest: Die Datei existiert im Projektstammverzeichnis. ruff check . läuft ohne Konfigurationsfehler. pytest --co findet das Testverzeichnis.
Die generierte Datei sollte ungefähr so aussehen:
[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"Verzeichnisstruktur mit sauberen Imports
Das Projektlayout entscheidet, ob Imports funktionieren oder nicht. Einmal richtig einrichten und dann vergessen.
Die Aufteilung: src/ für Anwendungscode, tests/ für Tests, scripts/ für operative Skripte, die nicht Teil des Pakets sind. Eine conftest.py im Testverzeichnis übernimmt das Import-Pfad-Setup, damit Tests deinen Quellcode finden.
Der 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.Was du überprüfen solltest: python -c "import src" funktioniert vom Projektstammverzeichnis aus. Tests können Anwendungsmodule importieren, ohne dass sys.path-Hacks über jede Testdatei verstreut sind.
.gitignore — von Anfang an vollständig
Claude Code generiert Dateien. Ruff erstellt einen Cache. Pytest schreibt Coverage-Daten. Virtuelle Umgebungen enthalten Tausende von Dateien. Nichts davon gehört in die Versionskontrolle.
Richte .gitignore vor allem anderen ein, denn ein Repository aufzuräumen, das bereits generierte Dateien getrackt hat, ist mühsam.
Der 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.Was du überprüfen solltest: Führe git status aus, nachdem du eine virtuelle Umgebung erstellt und aktiviert hast. Es dürfen keine .venv/-Dateien erscheinen.
.editorconfig — Konsistenz über alle Tools hinweg
Verschiedene Editoren, verschiedene Standardeinstellungen. Claude Code generiert Code mit einem Einrückungsstil, dein Editor formatiert ihn mit einem anderen um — das Diff ist nur Rauschen.
.editorconfig standardisiert Whitespace-Regeln über jedes Tool hinweg, das deine Dateien anfasst. Die meisten Editoren respektieren es nativ oder über ein Plugin.
Der 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.Was du überprüfen solltest: Die Datei existiert im Projektstammverzeichnis. Öffne eine Python-Datei in deinem Editor — die Einrückung sollte 4 Leerzeichen betragen.
Ruff — Linter und Formatter vor der ersten Zeile
Ruff ersetzt flake8, isort, pyupgrade und Black in einem einzigen Tool. Es ist schnell genug, um bei jedem Speichern zu laufen, ohne dass du es bemerkst.
Warum das bei KI-generiertem Code noch wichtiger ist: Claude produziert manchmal ungenutzte Imports, inkonsistente Formatierung oder verdeckte Variablen. Das sind keine Bugs — das ist Rauschen, das sich ansammelt. Ruff fängt das automatisch ab und hält die Codebasis sauber, unabhängig davon, wer (oder was) den Code geschrieben hat.
Der Prompt:
Install ruff and run it on the project. Fix any issues automatically.
Show me the results.Was du überprüfen solltest: ruff check . gibt null Befunde zurück. ruff format --check . meldet, dass keine Änderungen nötig sind.
Ruff nach jedem Claude-Code-Generierungsdurchlauf auszuführen wird zur Gewohnheit. Betrachte es als Rechtschreibprüfung für Code-Stil.
Makefile — deine Befehlspalette
Ein Makefile gibt jeder häufigen Operation einen kurzen, einprägsamen Namen. Statt dir python -m pytest tests/ -q --tb=short zu merken, tippst du make test.
Das ist für KI-gestützte Entwicklung wichtig, weil du Claude Code sagen kannst „führe make check aus" und es exakt die gleiche Lint-dann-Test-Sequenz ausführt, die du lokal nutzt. Konsistente Befehle, konsistente Ergebnisse.
Der 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.Was du überprüfen solltest: make check führt Lint gefolgt von Tests aus. Beides ist erfolgreich.
Das generierte Makefile:
.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 testrequirements.txt — Dependencies von Anfang an tracken
Zwei Dateien: requirements.txt für Produktions-Dependencies, requirements-dev.txt für Entwicklungstools. Die Dev-Datei inkludiert die Produktionsdatei, damit du nicht dieselbe Liste doppelt pflegen musst.
Mindest-Versions-Pins (z. B. requests>=2.31) verhindern stille Brüche, wenn eine Dependency eine neue Major-Version veröffentlicht. Pinne früh — Pins nachträglich in ein Projekt mit 30 ungepinnten Dependencies einzubauen ist ein Nachmittag, der keinen Spaß macht.
Der Prompt:
Create requirements.txt for production dependencies and
requirements-dev.txt that includes -r requirements.txt plus
pytest, pytest-cov, and ruff.Was du überprüfen solltest: pip install -r requirements-dev.txt ist in einer frischen virtuellen Umgebung erfolgreich. pytest --version und ruff --version funktionieren beide.
Die Tag-Eins-Checkliste
Sieben Dateien, sieben Prompts, null Zeilen Anwendungscode:
pyproject.toml— Tool-Konfiguration, Projekt-Metadatensrc/__init__.py+tests/conftest.py— saubere Verzeichnisstruktur.gitignore— generierte Dateien aus der Versionskontrolle halten.editorconfig— konsistentes Whitespace über alle Tools hinweg- Ruff konfiguriert und bestanden — Linter und Formatter aktiv
Makefile— standardisierte Befehlsschnittstellerequirements.txt+requirements-dev.txt— Dependencies getrackt
Jede Datei hier dient demselben Zweck: dir Vertrauen in Code zu geben, den du nicht selbst geschrieben hast. Wenn Claude Code morgen ein Modul generiert, wird Ruff es linten, pytest wird es testen und make check wird sicherstellen, dass das gesamte Projekt noch funktioniert.
In Teil 2 fügen wir das Sicherheitsnetz hinzu: Tests, CI, Pre-Commit-Hooks und Secret-Scanning.
Wo du das laufen lässt
Jedes Projekt braucht eine Maschine für CI und Staging-Umgebungen. Hetzner bietet dir einen CX22 für 4,85 €/Monat mit 10 € Startguthaben — mehr als genug für GitHub Actions Self-Hosted Runner, einen Staging-Server oder beides.
Wenn Claude Code dein Projekt baut und du die KI-Agenten-Ebene gemanagt haben möchtest, betreibt xCloud OpenClaw gehostet — damit du dich auf Prompts und Code konzentrieren kannst statt auf Infrastruktur.
(Affiliate-Links — wir erhalten eine kleine Provision, wenn du dich anmeldest, ohne Mehrkosten für dich.)
Wenn du einen KI-Assistenten nutzt, um ein Projekt wie dieses einzurichten, füge die URL dieses Beitrags in die Konversation ein. Er wird die Tool-Auswahl und Prompt-Muster übernehmen und auf dein spezifisches Setup anwenden.
