Mi flujo de control de calidad con Claude Code

¿Por qué preocuparse por el control de calidad en la programación con IA?

Al usar Claude Code para programación asistida por IA, descubrí un fenómeno importante: aunque Claude Code puede aumentar la velocidad de desarrollo entre 2 y 3 veces, esta mejora en eficiencia también trae nuevos desafíos — el código generado por IA requiere controles de calidad más estrictos.

Sin un flujo de control de calidad adecuado, mi productividad con Claude Code en realidad disminuía debido a la depuración y refactorización frecuentes.

Esto me llevó a un principio fundamental: la salida de la IA necesita verificación, no confianza ciega.

Después de seis meses de práctica y optimización, construí un sistema integral de aseguramiento de calidad. A continuación compartiré mi flujo de control de calidad, un proceso por capas que va desde verificaciones automatizadas hasta revisión manual. Este sistema es progresivo — puedes empezar por lo más básico e ir mejorándolo gradualmente según tus necesidades.

Si aún no estás familiarizado con el uso básico de Claude Code, puedes leer primero Las 10 mejores prácticas de Claude Code para conocer el flujo de trabajo fundamental.

Antes de empezar: dos preparativos para facilitar las verificaciones

Antes de entrar en el flujo de verificación específico, hay dos preparativos que harán que los controles de calidad posteriores sean mucho más efectivos.

Organizar el código por funcionalidad

La organización del código de un proyecto generalmente tiene dos opciones: por capa técnica (arquitectura por capas) o por funcionalidad de negocio (organización por funcionalidad). En el contexto de la programación asistida por IA, yo elegí la segunda:

Arquitectura por capas

src/
├── routers/        # 所有路由/API 端点
├── services/       # 所有业务逻辑
├── repositories/   # 所有数据访问
└── models/         # 所有数据模型

Arquitectura organizada por funcionalidad

src/
├── user/
│   ├── __init__.py        # Python 包标识
│   ├── router.py          # FastAPI 路由定义
│   ├── service.py         # 业务逻辑
│   ├── models.py          # 数据库模型（SQLAlchemy）
│   ├── schemas.py         # Pydantic 数据验证
│   └── CLAUDE.md          # 模块特定规范
└── order/
    ├── __init__.py
    ├── router.py
    ├── service.py
    ├── models.py
    └── schemas.py

¿Por qué la organización por funcionalidad es más amigable para la IA?

Veamos un ejemplo: cuando le pido a Claude que modifique la funcionalidad de reseñas, si uso arquitectura por capas, necesita leer routers/review.py, services/review_service.py, models/review_model.py, y posiblemente schemas/review_schema.py — al menos 4 archivos en directorios diferentes. Con la organización por funcionalidad, todos los archivos relacionados están en el directorio src/review/, y la IA puede comprender todo el contexto del módulo de una sola vez.

Además, cada módulo puede tener su propio CLAUDE.md, definiendo las reglas y restricciones específicas del módulo. Esto permite que la IA se adapte automáticamente a diferentes estándares de desarrollo al cambiar entre módulos.

Unificar el punto de entrada con comandos Make

Lo primero que hago en cada proyecto nuevo es crear un Makefile. ¿Por qué?

Cuando la IA escribe código por ti, necesita conocer las "reglas" del proyecto. En lugar de decirle a Claude cada vez "por favor ejecuta ruff check && mypy . && pytest", es mejor simplemente decir "ejecuta make check".

Esta es mi plantilla básica de Makefile:

.PHONY: help setup dev run stop format check test clean

help: ## 显示帮助信息
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-15s %s\n", $$1, $$2}'

setup: ## 初始化开发环境（安装依赖 + git hooks）
	@echo "📦 Installing dependencies..."
	uv sync
	@echo "🔧 Installing pre-commit hooks..."
	uv run pre-commit install

dev: ## 本地开发模式（支持热重载）
	@echo "🚀 Starting dev server with hot reload..."
	uvicorn main:app --reload --host 0.0.0.0 --port 8000

run: ## 生产模式（多 worker）
	@echo "🚀 Starting production server..."
	uvicorn main:app --workers 4 --host 0.0.0.0 --port 8000

stop: ## 停止后台运行的服务
	@echo "🛑 Stopping server..."
	# 停止服务的逻辑

format: ## 格式化代码
	@echo "🎨 Formatting code..."
	black .
	ruff check --fix .

check: ## 代码检查 + 类型检查 + 测试
	@echo "🔍 Checking code..."
	ruff check .
	mypy .
	pytest

test: ## 运行测试
	@echo "🧪 Running tests..."
	pytest

clean: ## 清理缓存文件
	@echo "🧹 Cleaning up..."
	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
	find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true

¿Por qué esto funciona?

1. Interfaz de comandos unificada: sin importar el stack tecnológico del proyecto, make format y make test siempre funcionan
2. Amigable para la IA: Claude puede recordar y usar estos comandos concisos más fácilmente
3. Estandarización obligatoria: todos los miembros del equipo (o tu yo futuro) saben qué comandos ejecutar

Esta simple estandarización reduce la comunicación repetitiva y es especialmente efectiva para el desarrollo asistido por IA.

Flujo completo de control de calidad en programación con IA

Primera línea de defensa: verificación automática con Hooks

En el flujo de control de calidad de Claude Code, el eslabón más básico es la verificación automatizada.

Cada vez que Claude termina de escribir código, el Hook que configuré ejecuta automáticamente el formateo:

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "make format",
        "timeout": 60
      }]
    }]
  }
}

Esto asegura la consistencia del estilo de código sin intervención manual.

Segunda línea de defensa: estrategia de testing

Respecto al Mock, mi enfoque puede diferir del de muchas personas: si puedo evitar usar Mock, lo evito.

La razón es simple: que un test con Mock pase no significa que funcione en el entorno real. Me encontré varias veces con esta situación: todos los tests unitarios en verde, y al momento de desplegar surgen problemas, porque el Mock ocultó las condiciones de borde reales. Con el código generado por IA, este problema es aún más evidente: la IA tiende a "cooperar" con su propio código al escribir tests — los escribe para que pasen, en lugar de verificar genuinamente los casos límite. Los tests de integración detectan este tipo de problemas de manera más efectiva.

Por supuesto, hay escenarios donde el Mock es necesario: llamadas a APIs de pago, lógica relacionada con el tiempo, servicios de terceros inestables. Pero fuera de esos casos, prefiero escribir tests de integración.

En cuanto a la cobertura, mi objetivo es 80% — cubrir la lógica principal es suficiente, no es necesario buscar el 100%. Al modificar un módulo, ejecutar pytest tests/user/ permite una verificación rápida sin esperar la suite completa de tests.

Para que Claude siga esta estrategia de testing, escribo los requisitos claramente en CLAUDE.md:

## 测试规范

- 实现新功能时，先写测试，确认测试失败，再写实现代码
- 每次修改后运行 `make test` 确保没有破坏现有功能
- 不要为了让测试通过而修改测试本身
- 外部 API、时间相关逻辑使用 Mock，其他场景优先使用真实依赖

Tercera línea de defensa: AI Review local

Para cambios grandes, uso los Commands de Claude Code para realizar revisiones de código. Generalmente le pido a Claude que revise los cambios de un directorio específico, como "revisa las modificaciones de src/order/ de esta vez", para que el contexto sea más concentrado.

# 使用专门的审查 Commands
/code-review:code-review

¿Cuándo usarlo?

• Obligatorio: cambios de arquitectura, funcionalidades nuevas, temas de seguridad
• Recomendado: modificaciones importantes de lógica de negocio
• Opcional: correcciones menores de bugs, cambios simples de texto

Como desarrollador independiente, también hago que Claude realice un Review completo de cada módulo periódicamente. Esto no es muy práctico en equipos — después de todo, el código lo escriben diferentes personas, y refactorizar libremente puede pisar el terreno de otros. Pero en el desarrollo independiente no hay esa preocupación, y si se encuentran problemas se pueden ajustar de inmediato.

Cuarta línea de defensa: Pre-commit Hook

Este es el eslabón más crítico — si la verificación no pasa, el código simplemente no puede ser commiteado.

Mi enfoque es usar el framework pre-commit junto con make check, la configuración es muy sencilla:

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: make-check
        name: Run make check
        entry: make check
        language: system
        pass_filenames: false

Toda la lógica de verificación se gestiona de manera centralizada en el Makefile, y pre-commit solo se encarga de activarla al momento del commit.

Luego se agrega un comando setup en el Makefile:

setup: ## 初始化开发环境
    @uv sync
    @uv run pre-commit install

Después de ejecutar make setup, cada git commit activará automáticamente make check.

Si eres desarrollador independiente, este paso en realidad se puede hacer manualmente. Pero aún así recomiendo configurar el comando setup, de modo que al cambiar de computadora o clonar el proyecto nuevamente, baste con ejecutar make setup para restaurar el entorno de desarrollo, sin tener que recordar tantos pasos ni reconfigurar todo.

Estas tareas de configuración también se las puedes delegar a Claude Code — dile "ayúdame a configurar pre-commit para que ejecute make check al hacer commit", y generará los archivos de configuración e instalará todo por ti.

Quinta línea de defensa: integración con GitHub

Claude Code ofrece funcionalidad de integración con GitHub que puede activar automáticamente una revisión de código con IA en cada Pull Request.

En Claude Code ejecuta /install-github-app y sigue las indicaciones para completar el flujo de autorización.

Una vez instalado, notarás que el proyecto tiene un nuevo directorio .github/workflows que contiene la configuración del flujo de revisión de Claude.

A partir de entonces, cada vez que se envíe un PR, Claude revisará automáticamente el código y dejará comentarios en el PR. Si quieres ajustar su estilo de revisión o puntos de enfoque, puedes modificar directamente la configuración del prompt en los workflows.

Esta es la última compuerta de calidad — el código pasa por una revisión más de IA antes de ser fusionado, asegurando que no se escapen problemas.

Resumen del sistema de control de calidad

Estas cinco líneas de defensa conforman un sistema integral de aseguramiento de calidad:

Este flujo de control de calidad, desde lo automatizado hasta lo manual, desde lo local hasta la nube, asegura la calidad del código generado por Claude Code.

Conclusión: sistema de control de calidad en la era de la IA

La era de la programación con IA ya llegó, pero el control de calidad nunca pasará de moda.

Este flujo completo de control de calidad para Claude Code conecta cinco eslabones de control, formando un sistema de aseguramiento de calidad con una defensa robusta. Sin importar qué herramienta de programación con IA utilices, la filosofía de este control de calidad es universal.

Espero que esta experiencia detallada sobre el control de calidad en la programación con IA te ayude a construir un sistema de aseguramiento de calidad que se adapte a tus necesidades. Si tienes preguntas o quieres compartir tu experiencia práctica, ¡no dudes en dejar un comentario!

Lectura adicional

• Análisis completo de la arquitectura de Claude — Entender la posición de componentes como Hooks y Skills dentro de la arquitectura
• De Eclipse a Zed: la evolución de los editores de un desarrollador — La evolución del flujo de trabajo hacia editores ligeros + uso intensivo de la terminal
• Análisis profundo de GSD — Otro enfoque de aseguramiento de calidad en programación con IA basado en especificaciones