Un desarrollador de Python doma a Claude Code: una configuración abierta contra las regresiones

Un desarrollador de CREATMAN dedicó varias semanas a estudiar la documentación, los debates de Reddit y las configuraciones de otros para armar una configuración de Claude Code con protección real contra regresiones. El resultado es un repositorio abierto con archivos listos para usar de inmediato.

Un problema que todos conocen

Claude Code es potente, pero sin la configuración adecuada actúa con demasiada autonomía. Un cuadro típico para un desarrollador en solitario:

• Le pides que añada autenticación y el agente reescribe la mitad del proyecto
• Le pides que corrija una función y obtienes tests eliminados y una dependencia que nadie pidió
• Montas un prototipo funcional en una hora y pasas tres desenredando las «mejoras» del agente

Para quien trabaja solo, esto es doblemente crítico. No hay un ingeniero de QA que detecte las regresiones tras cada prompt. No hay un revisor que note los tests borrados. Cada cambio no planificado cuesta tiempo dedicado a descifrar decisiones ajenas en lugar de trabajar en el producto.

El autor dirige CREATMAN sin equipo y se topó justo con eso: la IA ayuda a construir rápido, pero sin control genera problemas nuevos igual de rápido.

De qué consta la configuración

Tras varias semanas leyendo documentación, debates en foros y analizando configuraciones ajenas, el autor identificó cinco componentes clave. Todos están en el repositorio claude-code-antiregression-setup y listos para usar:

• CLAUDE.md: el archivo-contrato principal, con el alcance de la tarea, prohibiciones explícitas de tomar decisiones por cuenta propia y la exigencia de describir los cambios previstos antes de ejecutarlos
• Reglas por directorio: restricciones a nivel de carpeta para que el agente no toque nada que no se le haya pedido de forma explícita
• Lista de comprobación obligatoria: antes de cualquier cambio, el agente describe su plan y el desarrollador lo aprueba o lo rechaza
• Hooks: scripts automáticos que se ejecutan tras cada acción del agente y comprueban que se ajusta a la tarea
• Plantillas de prompts: formatos de petición listos para usar que eliminan la ambigüedad y reducen el margen de interpretación

Lo importante es que todo está documentado. El repositorio no está pensado para estudiarlo, sino para integrarlo rápido: clónalo, adáptalo a tu proyecto y úsalo.

Por qué un contrato funciona mejor que una prohibición

La idea clave es darle al agente reglas claras en lugar de limitarse a restringirlo. Claude Code lee CLAUDE.md al inicio de cada sesión. Si ahí se indica de forma explícita «no toques los tests sin que se te pida», «haz cambios solo dentro de los archivos indicados» o «avisa antes de añadir una dependencia», el agente lo cumple.

«Necesito que el agente de IA me ayude a publicar más rápido, no que

cree problemas nuevos», explica el autor.

Los hooks añaden un segundo nivel. Pequeños scripts se ejecutan tras los cambios y comprueban si el agente se ha salido de los límites. Si es así, los cambios se marcan para revisión en lugar de colarse en silencio en la base de código.

Las plantillas de prompts resuelven otro problema. Una petición vaga le da al agente demasiado margen de interpretación, y ahí empieza la iniciativa propia. Los formatos predefinidos, que especifican alcance, archivos y resultado esperado, reducen ese margen de forma drástica.

CLAUDE.md no es solo un README para el agente, sino un documento vivo del proyecto. En él se registran las decisiones de arquitectura, los módulos críticos y las convenciones de nombres. El agente usa este archivo como contexto en cada petición, lo que hace que entienda mejor el proyecto y que las «mejoras» aleatorias sean menos probables.

La configuración no está atada a un stack concreto. El autor trabaja con un backend en Python, pero los principios valen para cualquier proyecto en el que haya que mantener al agente dentro de los límites de la tarea encomendada.

Qué significa

La imprevisibilidad es una de las principales barreras para incorporar agentes de IA al desarrollo en solitario. Configuraciones abiertas como esta reducen el umbral de entrada: tomas la estructura, la adaptas a tu proyecto y obtienes una herramienta controlable en lugar de un asistente caótico. Cuantas más configuraciones así estén disponibles en abierto, más práctico será usar agentes de IA sin un equipo de apoyo.