Programar con un agente de IA bajo reglas escritas en CLAUDE.md y AGENTS.md

Si dejas que un agente de IA toque tu base de datos de producción, tarde o temprano se equivocará. Yo no podía evitarlo. Durante la reescritura de libelium.com e iris360 trabajé con un agente que editaba código y escribía en el servidor real, y decidí que mi trabajo era limitar lo que cada error podía romper. Para eso puse las reglas por escrito y dentro del repositorio.

Reglas que viajan con el código

Una instrucción dada en el chat se esfuma con la sesión. Una regla en el repositorio llega en un commit, se revisa en un diff y la lee cualquier sesión nueva sin que yo la repita. Por eso dos ficheros, CLAUDE.md y AGENTS.md, viven en la raíz del monorepo y el agente los carga al empezar. Su estructura sigue la de un system promptGlosarioSystem PromptInstrucción de nivel superior proporcionada a un modelo de inteligencia artificial antes de procesar las peticiones del usuario. Establece las reglas de comportamiento, restricciones de estilo, contexto arquitectónico y contratos de diseño (como archivos AGENTS.md o CLAUDE.md) que el agente debe respetar estrictamente durante toda la sesión de interacción.Ver término completo →, versionado junto al código.

El primero recoge el modo de operar. Pone mis peticiones por delante, obliga a consultar la hora con date en lugar de inventarla y exige que las comprobaciones pasen en los dos sitios antes de entregar. El segundo fija el reparto del monorepo y ocho reglas. Una sola copia de cada paquete compartido. Lo que cambia entre marcas cuelga de una opción y nunca de dos copias de un fichero. Ningún secreto en git. Y nada de tocar servidores ni hacer push sin petición expresa, con una etiqueta de seguridad antes de cualquier fase destructiva.

Varias nacieron de decisiones que ya conté, como el monorepo en lugar de multisite o la retirada del generador de landings. No llevo la cuenta de cuántas veces una regla frenó un error. No existe un registro y cualquier cifra sería inventada.

El patrón antes de escribir en producción

Las reglas generales no bastan cuando el agente va a modificar fichas de producto en la base de datos. Repetí el mismo patrón en cada una. El script se ejecuta primero en simulación y no escribe nada. Se fuerza una copia de contenido antes de tocar. Se aplica una sola vez, porque los scripts que insertan secciones duplican el resultado si se repiten. Después se vacía la caché completa de la página, que tiene variantes por navegador, de modo que curl puede ver la página nueva mientras el navegador enseña la antigua. Y se borra el autosave de Elementor, o el editor muestra una versión distinta de la publicada.

# simulación, no escribe
docker exec <contenedor-wp> wp --allow-root eval-file /tmp/script.php
 
# aplicación, una sola vez
docker exec -e APPLY=1 <contenedor-wp> wp --allow-root eval-file /tmp/script.php

Una regla más nació de un día de trabajo. Yo editaba el diseño en Elementor después de cada paso del agente. Cuando él reconstruía una ficha desde un script, pisaba mis cambios. Desde entonces vuelca el árbol actual de la página, localiza los widgets por su ID y los sustituye en su sitio. Nunca reconstruye una ficha que yo ya había tocado.

Tres errores reales

El 7 de octubre, al aplicar la ficha de Smart Spot, el script buscó la tecnología LoRaWAN por título e insignia. Coincidió con la de Libelium One y la sobrescribió. La restauré y creé una propia para Smart Spot con título único. La lección es que una búsqueda por título puede devolver el registro de otro producto, así que cada título debe ser único. El episodio aparece también en el post sobre la regla de verdad de los datos de producto.

Esa misma jornada la copia de contenido empezó a responder "Ya hay una copia en curso", con toda probabilidad por un bloqueo huérfano tras un reinicio de la base de datos. Waspmote se aplicó con una copia reciente. Las otras tres fichas se aplicaron apoyándose en esa, porque no se habían tocado desde entonces. Fue una desviación de mi propio patrón y la dejé registrada como incidencia. No encuentro anotado cómo se liberó el bloqueo.

El 4 de octubre el contenedor de tareas programadas, con 256 MiB de límite, mataba por falta de memoria a WP-CLI al procesar imágenes. La marca OOMKilled=true aparecía sin ningún error en la salida del comando. Desde entonces los comandos pesados pasan por el contenedor de WordPress, que dispone de 2 GiB.

Un cuarto fallo, en el entorno de pruebas del 22 de septiembre. El script de despliegue solo subía ficheros ya rastreados por git, y un PHP nuevo quedó sin subir mientras el require_once que lo cargaba sí se desplegó. El sitio estuvo caído unos dos minutos hasta que subí el fichero a mano.

Cuando la herramienta dice que no

Claude Code incorpora en su modo automático un clasificador que decide qué acciones puede ejecutar el agente sin preguntar. A veces bloquea escrituras en producción. Cuando ocurre, el agente me entrega la lista de comandos y yo los lanzo desde mi terminal con el prefijo !. Dejé escrito que no debe crear envoltorios para esquivar el bloqueo, porque eso es una elusión del modo automático.

Las reglas también cambian cuando cambio de criterio. El traspaso mandaba verificar con Playwright. Después escribí que no lo usara y que verificaría yo de forma visual. El agente recibe el cambio en la siguiente sesión.

Lo que me llevo

No he medido si las reglas reducen los errores frente a trabajar sin ellas, porque no tengo un caso de comparación. Los errores ocurrieron con el patrón en uso, y el patrón acotó su alcance sin impedirlos. Las copias de contenido se hacen cada dos horas con retención de 14 días. Que restaurar una copia devuelva una huella idéntica consta en un changelog del 2 de octubre, sin que se probara en producción.

Lo transferible a otro proyecto cabe en tres ideas. Escribe las reglas donde viaje el código, para que cada sesión las herede. Diseña cada escritura para que se pueda ensayar y deshacer. Y asume que el agente fallará, porque lo que importa es que el fallo cueste poco. El principio general, sin los datos de este caso, está en la lección Agente de IA con reglas escritas y escritura segura.