Un agente de programación edita ficheros, lanza comandos y, con los permisos adecuados, escribe en bases de datos reales. Se equivoca con una frecuencia que no se puede fijar de antemano, y esa frecuencia importa menos que el tamaño de cada error. El método que sigue no intenta que el agente acierte siempre. Intenta que cada fallo sea pequeño, visible y reversible.
Descansa en dos mecanismos. Unas reglas escritas dentro del repositorio fijan qué puede tocar el agente. Un patrón de escritura fija cómo cambia un dato real, paso a paso, con una copia previa a cada aplicación.
Definición operativa
Una regla escrita es una frase que un agente puede obedecer y una persona puede comprobar en un diff. Cumple tres condiciones. Vive en un fichero versionado que el agente carga al empezar cada sesión. Tiene un identificador estable, de modo que una conversación o un commit puedan citarla. Y nombra una acción concreta, como "no hacer push" o "no escribir secretos en git", que se pueda contrastar con lo que el agente hizo.
Una instrucción dada en el chat no cumple ninguna de las tres. Desaparece con la sesión, nadie la revisa y la siguiente sesión parte sin ella. Los ficheros de contrato como AGENTS.md o CLAUDE.md existen para eso, y su lógica es 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 → que se versiona con el código. La guía de diseño guiado para agentes aplica la misma idea a la interfaz.
La escritura segura es el patrón que se ejecuta cada vez que el agente modifica algo que no vive en git. Datos de una base, contenido de un CMS, ficheros de un servidor. Todo lo que el repositorio no puede deshacer con un revert.
Qué cubren las reglas
Un conjunto de reglas útil responde a cinco preguntas, y cada una se redacta como una prohibición o una obligación observable.
| Pregunta | Ejemplo de regla |
|---|---|
| Qué puede tocar | El agente no accede a servidores ni hace commit o push salvo petición expresa. |
| Qué no puede escribir nunca | Ningún secreto, clave ni volcado de datos entra en git. |
| Con qué remoto trabaja | Un único remoto oficial. Los demás no se toman como referencia. |
| Qué exige antes de acciones destructivas | Una etiqueta de seguridad previa a cualquier fase que borre o reescriba. |
| Qué comprueba antes de entregar | Los verificadores del proyecto pasan para todos los entornos. |
Cada fila acota un tipo de daño. Un secreto en git no se deshace con un revert, porque ya está en la historia. Un push a un remoto equivocado publica código que nadie revisó. Una fase destructiva sin etiqueta no tiene punto de retorno. Las reglas atacan primero lo que no se puede deshacer.
Conviene separar dos ficheros con funciones distintas. Uno recoge el modo de operar, con prioridades, comandos y comprobaciones. Otro recoge el reparto del repositorio y las reglas con identificador. Mezclarlos produce un documento largo en el que la regla que importa queda enterrada.
Método paso a paso para escribir en datos reales
El patrón se aplica sin excepciones, aunque el cambio parezca trivial. Cada paso existe por un fallo concreto que evita.
- Script en lugar de comando suelto. La modificación se escribe como un script que se puede leer, revisar y repetir. Un comando improvisado no deja rastro.
- Simulación por defecto. El script, lanzado sin parámetros, solo informa de lo que haría. Escribir exige activar una variable explícita. Así el error habitual, ejecutarlo sin pensar, resulta inocuo.
- Copia previa. Antes de aplicar se fuerza una copia del contenido afectado, con una huella que permita comprobar después que la restauración devuelve el mismo estado.
- Una sola aplicación. Se ejecuta una vez. Un script que inserta secciones las duplica si se repite, y un agente que reintenta sin leer la salida lo repetirá.
- Verificación del consumidor final. Se comprueba el resultado donde lo ve quien lo usa, no solo en la base de datos. Una página, un marcado estructurado, una respuesta de API.
- Limpieza de caché y de borradores. La caché completa y los autoguardados del editor se vacían. Si no, una herramienta muestra el dato nuevo y otra el antiguo, y se pierde tiempo persiguiendo un fallo que no existe.
La idempotencia merece un comentario aparte. Un script idempotente da el mismo resultado si se ejecuta dos veces, y eso reduce el riesgo del cuarto paso. No sustituye la regla de una sola aplicación, porque pocos scripts nacen idempotentes y comprobarlo cuesta más que ejecutarlos una vez. Los que insertan, añaden o concatenan nunca lo son sin trabajo extra.
Un detalle de ejecución separa los scripts que funcionan de los que causan incidentes. Si una persona edita el mismo recurso en paralelo, el script no debe reconstruirlo desde cero. Debe leer el estado actual y sustituir solo lo que le corresponde, localizando cada elemento por su identificador.
Errores típicos y cómo reaccionar
Los fallos de un agente siguen patrones reconocibles. Ninguno exige desconfiar del agente por sistema, y todos piden una respuesta distinta.
| Fallo del agente | Qué lo provoca | Respuesta |
|---|---|---|
| Sobrescribe un registro ajeno | Busca por un campo que no es único y encuentra uno que coincide | Restaurar desde la copia. Exigir claves únicas y buscar por ellas. |
| Duplica contenido | Reintenta un script que no era idempotente | Revertir la copia. Añadir la regla de una sola aplicación. |
| Pisa trabajo manual | Reconstruye un recurso que alguien editó después | Leer el estado vivo y sustituir por identificador. |
| Hace commit de lo que ya rastreaba y olvida lo nuevo | Su script de despliegue solo ve ficheros existentes | Listar los ficheros nuevos antes de desplegar. |
| Se bloquea o muere sin error visible | Un límite de recursos del contenedor lo mata en silencio | Revisar el estado del proceso, no solo su salida. Ejecutar lo pesado donde hay memoria. |
| Intenta saltarse una barrera | Una restricción de la herramienta le impide avanzar | No construir envoltorios. Entregar la lista de comandos a la persona. |
Hay una regla general para la reacción. Primero se restaura, después se diagnostica, y solo entonces se escribe la regla que habría evitado el fallo. Escribirla antes de restaurar deja el sistema roto mientras se redacta. Cada incidente aporta una regla o un paso al patrón.
La última fila toca un límite. Muchas herramientas de agente incluyen un sistema de permisos que decide qué acciones se ejecutan sin preguntar. Esa frontera entre lo que decide la máquina y lo que decide la persona pertenece a la herramienta, y las reglas del repositorio la complementan sin sustituirla. Cuando el sistema bloquea una escritura, la persona la lanza con sus propios permisos. Sortear el bloqueo con un script intermedio anula el control que se pretendía conservar.
Criterio de decisión
No todo cambio exige el patrón completo. La tabla ordena los casos por reversibilidad.
| Tipo de cambio | Reversible con git | Patrón aplicable |
|---|---|---|
| Edición de código en una rama | Sí | Reglas generales y revisión del diff. |
| Cambio de configuración versionada | Sí | Reglas, verificadores y revisión. |
| Escritura en un entorno de pruebas | No, pero el daño se acota | Simulación y una aplicación. Copia opcional. |
| Escritura en datos reales | No | Patrón completo con copia previa. |
| Operación destructiva o masiva | No | Patrón completo, etiqueta de seguridad y revisión humana de la simulación. |
| Cambio de credenciales o de infraestructura | No | Lo ejecuta una persona. El agente prepara y no aplica. |
Cuándo aplicarlo
Compensa desde el primer día en cualquier proyecto en el que el agente toque algo que no vive en git. Compensa también cuando varias personas o varias sesiones trabajan sobre el mismo repositorio, porque las reglas escritas evitan que cada una enseñe al agente lo suyo. No compensa en un experimento desechable cuya única copia es la que se está probando.
Las reglas necesitan mantenimiento. Un fichero que nadie actualiza acaba describiendo un proyecto que ya no existe. Si cambia el criterio, por ejemplo la forma de verificar, se cambia el fichero y la siguiente sesión lo recibe. El reparto entre lo que el agente decide y lo que valida una persona se revisa igual, y el método para fijar qué dato manda cuando las fuentes discrepan está en la regla de verdad entre fuentes de datos.
Del caso al principio
El método se aplicó a un proyecto que combinaba un monorepo, un agente con escritura en la base de datos de producción y una persona que editaba el mismo contenido en paralelo. Los incidentes del proyecto de referencia no eran exóticos. Un registro sobrescrito, una copia bloqueada, un contenedor sin memoria. Ninguno rompió nada de forma irrecuperable porque cada uno ocurrió dentro del patrón, y cada uno añadió una línea a las reglas.
La síntesis es que el control del agente se construye sobre reversibilidad y no sobre confianza. Las reglas dicen qué no se toca, el patrón dice cómo se cambia lo que sí, y la copia previa convierte el error en un episodio de restauración. El detalle del caso, con sus incidentes y lo que quedó sin medir, está en programar con un agente de IA bajo reglas escritas.