Antes de escribir una línea de código — configurando un proyecto Python con calidad ante todo usando Claude Code

Cuando Claude Code escribe tu proyecto, tu rol cambia. No eres un mecanógrafo. Eres un arquitecto y un revisor. El código llega rápido — a veces más rápido de lo que puedes leerlo. Las herramientas de calidad son tu infraestructura de revisión. Capturan lo que a ti se te escapa.

Esta es la Parte 1 de una serie de tres partes sobre cómo configurar la calidad de un proyecto Python cuando Claude Code es tu desarrollador. Aquí cubrimos los cimientos: los archivos y la configuración que deben existir antes de cualquier código de aplicación.

El patrón para cada recomendación: qué hace la herramienta, un prompt que puedes pegar en Claude Code, y qué verificar después.

pyproject.toml — la constitución del proyecto

Todas las herramientas de Python leen pyproject.toml. Ruff, pytest, mypy, build backends — todas buscan aquí su configuración. Un archivo, una única fuente de verdad.

Más importante aún para el desarrollo asistido por IA: Claude Code también lo lee. Cuando tu proyecto tiene un pyproject.toml bien configurado, Claude entiende tus convenciones. Longitud de línea, reglas de linting, rutas de tests — los detecta automáticamente y genera código que se ajusta a ellos.

El 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).

Qué verificar: El archivo existe en la raíz del proyecto. ruff check . se ejecuta sin errores de configuración. pytest --co encuentra el directorio de tests.

El archivo generado debería verse aproximadamente así:

[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"

Estructura de directorios con imports limpios

La estructura del proyecto determina si los imports funcionan o se rompen. Hazlo bien una vez y olvídate.

La división: src/ para el código de aplicación, tests/ para los tests, scripts/ para scripts operativos que no forman parte del paquete. Un conftest.py en el directorio de tests se encarga de configurar las rutas de importación para que los tests encuentren tu código fuente.

El 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.

Qué verificar: python -c "import src" funciona desde la raíz del proyecto. Los tests pueden importar módulos de la aplicación sin hacks de sys.path dispersos por cada archivo de test.

.gitignore — completo desde el principio

Claude Code genera archivos. Ruff crea una caché. Pytest escribe datos de cobertura. Los entornos virtuales contienen miles de archivos. Nada de esto pertenece al control de versiones.

Configura .gitignore antes que cualquier otra cosa, porque limpiar un repositorio que ya rastreaba archivos generados es tedioso.

El 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.

Qué verificar: Ejecuta git status después de crear y activar un entorno virtual. No aparecen archivos de .venv/.

.editorconfig — consistencia entre herramientas

Diferentes editores, diferentes valores por defecto. Claude Code genera código con un estilo de indentación, tu editor lo reformatea con otro, y el diff es puro ruido.

.editorconfig estandariza las reglas de espacios en blanco en todas las herramientas que tocan tus archivos. La mayoría de los editores lo respetan de forma nativa o mediante un plugin.

El 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.

Qué verificar: El archivo existe en la raíz del proyecto. Abre un archivo Python en tu editor — la indentación debería ser de 4 espacios.

Ruff — linter y formateador antes de la primera línea

Ruff reemplaza flake8, isort, pyupgrade y Black en una sola herramienta. Es lo suficientemente rápido como para ejecutarse en cada guardado sin que lo notes.

Por qué esto importa más con código generado por IA: Claude a veces produce imports no usados, formato inconsistente o variables solapadas. No son bugs — son ruido que se acumula. Ruff los detecta automáticamente, manteniendo el código limpio sin importar quién (o qué) lo escribió.

El prompt:

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

Qué verificar: ruff check . devuelve cero hallazgos. ruff format --check . reporta que no se necesitan cambios.

Ejecutar ruff después de cada pasada de generación de Claude Code se convierte en un hábito. Piensa en ello como un corrector ortográfico para el estilo de código.

Makefile — tu paleta de comandos

Un Makefile le da a cada operación común un nombre corto y fácil de recordar. En vez de recordar python -m pytest tests/ -q --tb=short, escribes make test.

Esto importa para el desarrollo asistido por IA porque puedes decirle a Claude Code "ejecuta make check" y ejecutará exactamente la misma secuencia de lint-luego-test que tú ejecutas localmente. Comandos consistentes, resultados consistentes.

El 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.

Qué verificar: make check ejecuta lint seguido de tests. Ambos pasan.

El Makefile generado:

.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 — rastrea las dependencias desde el principio

Dos archivos: requirements.txt para dependencias de producción, requirements-dev.txt para herramientas de desarrollo. El archivo de desarrollo incluye el de producción para que no mantengas la misma lista dos veces.

Los pins de versión mínima (por ejemplo, requests>=2.31) previenen roturas silenciosas cuando una dependencia lanza una nueva versión mayor. Fija las versiones pronto — retrofitear pins en un proyecto con 30 dependencias sin fijar es una tarde que no vas a disfrutar.

El prompt:

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

Qué verificar: pip install -r requirements-dev.txt se completa con éxito en un entorno virtual limpio. pytest --version y ruff --version funcionan correctamente.

La checklist del día uno

Siete archivos, siete prompts, cero código de aplicación:

1. pyproject.toml — configuración de herramientas, metadatos del proyecto
2. src/__init__.py + tests/conftest.py — estructura de directorios limpia
3. .gitignore — mantener archivos generados fuera del control de versiones
4. .editorconfig — espacios en blanco consistentes entre herramientas
5. Ruff configurado y pasando — linter y formateador activos
6. Makefile — interfaz de comandos estándar
7. requirements.txt + requirements-dev.txt — dependencias rastreadas

Cada archivo aquí cumple el mismo propósito: darte confianza en código que no escribiste a mano. Cuando Claude Code genere un módulo mañana, ruff lo linteará, pytest lo testeará, y make check verificará que todo el proyecto sigue funcionando.

En la Parte 2, añadimos la red de seguridad: tests, CI, pre-commit hooks y escaneo de secretos.

Dónde ejecutar esto

Todo proyecto necesita una máquina para ejecutar CI y alojar entornos de staging. Hetzner te da un CX22 a 4,85 €/mes con 10 € de crédito inicial — más que suficiente para runners self-hosted de GitHub Actions, un servidor de staging, o ambos.

Si Claude Code está construyendo tu proyecto y quieres que la capa de agente IA esté gestionada por ti, xCloud ejecuta OpenClaw hospedado — para que puedas centrarte en prompts y código en vez de infraestructura.

(Enlaces de afiliado — nos llevamos una pequeña comisión si te registras, sin coste para ti.)

Si estás usando un asistente de IA para configurar un proyecto como este, pega la URL de este post en la conversación. Detectará las elecciones de herramientas y los patrones de prompts y los aplicará a tu configuración específica.