Hacer que un agente de codificación con IA siga las reglas de ramas y commits sin romper lanzamientos

## Mantener un solo archivo de instrucciones del agente y comprobar qué parte del repositorio cambiar - Mantén un único archivo canónico de instrucciones para el agente. Cuando un harness espera un nombre de archivo distinto, apúntalo al archivo canónico mediante un enlace simbólico en lugar de duplicar el contenido: un segundo archivo real diverge con el tiempo y puede romper los validadores que tratan la ruta alternativa como un tipo de artefacto diferente. Conserva el enlace simbólico; no dejes que se materialice de nuevo como un archivo normal. - Un mismo cambio puede afectar a varias superficies a la vez: contenido de producto ya publicado, metadatos de catálogo o configuración, y código de compilación o de CLI. No des por hecho que un cambio es «solo código» o «solo documentación» sin comprobar qué superficie es responsable de cada archivo modificado, y edita la superficie que realmente controla el comportamiento en lugar de una adyacente. - Trata los propios archivos de instrucciones del repositorio como contexto de redacción para el repositorio. Cualquier regla que deba afectar a un artefacto publicado en tiempo de ejecución pertenece a ese artefacto, no al archivo de instrucciones del repositorio, porque los usuarios finales ejecutan el artefacto con sus propias instrucciones. ## Trabajar en una rama de funcionalidad y fusionar solo mediante pull requests - Crea una rama de funcionalidad para cualquier cambio no trivial. Si ya estás en la rama correcta para la tarea, sigue usándola; no generes ramas o árboles de trabajo adicionales a menos que se te pida explícitamente. - Encauza todo cambio a la rama predeterminada mediante una solicitud de extracción (pull request). Los push o merges directos se saltan las validaciones y las verificaciones de lanzamiento, y provocan una desviación de versión que después exige una recuperación de varios pasos; confía en la protección de ramas para hacer cumplir esto en lugar de eludirla. - Deja los lanzamientos en manos de la automatización de lanzamientos. No incrementes manualmente los números de versión que pertenecen al proceso de lanzamiento ni redactes a mano las notas de la versión en el trabajo rutinario, y usa títulos de commit convencionales para que la automatización pueda clasificar la intención del cambio. ## Ejecutar todas las pruebas y separar las pruebas automáticas de las evaluaciones - Ejecuta la suite de pruebas completa después de cualquier cambio que afecte al análisis sintáctico, la conversión, la salida o las convenciones mecánicas. La suite local es la misma que ejecuta la integración continua (CI); no existe un carril exclusivamente local que puedas saltarte. - Divide las verificaciones según su naturaleza. Los invariantes deterministas —esquema y frontmatter, seguridad de rutas, forma de la salida, contratos localizables con grep— viven en la suite automatizada y deben pasar en la CI. El comportamiento no determinista, como el criterio y la mesura, se valida mediante evaluación, no se simula con una prueba de cadena de texto frágil. - Cuando un revisor encuentra un invariante localizable con grep que la suite pasó por alto, prefiere reforzar una protección existente antes que añadir una suite nueva, y fija la unidad falsable más pequeña posible —un token, una ruta o un fixture que hubiera fallado con el cambio regresivo— en lugar de tomar una instantánea de todo el cuerpo del archivo. ## Decidir dónde van los archivos temporales y guardar planes y documentos en el repositorio - Envía por defecto los archivos temporales desechables al directorio temporal del sistema operativo: un directorio temporal por ejecución que el sistema operativo recupera, para archivos que se consumen una sola vez y se descartan. - Para los archivos temporales que deben sobrevivir entre invocaciones, usa un prefijo estable propiedad del usuario actual en lugar de un directorio temporal aleatorio, de modo que ejecuciones posteriores puedan encontrarlo. Crea la raíz de forma privada (solo para el propietario), recházala si es un enlace simbólico o pertenece a otro usuario, y mantén un directorio por ejecución, salvo que ejecuciones posteriores enumeren intencionadamente artefactos finales hermanos. - Vincula los archivos temporales al repositorio de trabajo solo cuando el artefacto sea realmente inseparable de este repositorio o rama, esté pensado para que el usuario lo cure directamente, o cuando una ruta relativa al repositorio sea en sí misma esencial para la salida. - Las salidas duraderas —planes, especificaciones, documentación, entregables finales— pertenecen a una ubicación rastreada por el repositorio, nunca a ninguno de los dos niveles temporales. ## Usar solo ASCII en los nombres y separar las tablas Markdown con barras verticales - Mantén los identificadores —nombres de archivo, de comando y de agente— exclusivamente en ASCII, porque los conversores y los patrones de expresiones regulares dependen de ello. - Escribe las tablas de Markdown como filas delimitadas por barras verticales, nunca con caracteres de dibujo de cajas. - Unicode está bien en la prosa; dentro de bloques de código y ejemplos de terminal, prefiere flechas ASCII (-> y <-) para que los comandos copiados sigan siendo portables. ## Elegir el prefijo de commit fix o feature según lo que hace el cambio - Elige el prefijo convencional según lo que hace el cambio, no según el tipo de archivo. El contenido que vive en un directorio de documentación o de skills puede seguir siendo código de producto; reserva el prefijo docs para archivos cuyo único propósito sea la documentación. - Cuando tanto el prefijo fix como el feature parezcan encajar, opta por defecto por fix: remediar un comportamiento roto o ausente es una corrección incluso cuando se implementa añadiendo código. Reserva el prefijo feature para una capacidad que el usuario no podía lograr antes y en la que nada estaba roto. Heurística: si una prueba de regresión escrita hoy hubiera fallado antes del cambio, es un fix. - Incluye el alcance de componente útil más estrecho posible —el nombre de la skill, el módulo o el área— y nunca delimites un commit al proyecto entero. Nunca añadas un marcador de cambio disruptivo (breaking change) sin confirmación explícita del usuario, ya que desencadena un incremento automático de versión mayor que el usuario podría no querer. ## Usar rutas relativas para que cada unidad distribuida funcione en cualquier herramienta de IA - Mantén cada unidad distribuible autocontenida: haz referencia únicamente a archivos dentro de su propio árbol de directorios, usando rutas relativas. Nunca accedas a una unidad hermana ni codifiques de forma fija una ruta de instalación absoluta —las ubicaciones de instalación están versionadas y son impredecibles, y el empaquetado copia cada unidad de forma aislada—. Duplica un archivo compartido en cada unidad en lugar de depender de otros directorios. - No dependas de variables específicas del host —sustituciones como skill-directory, session-id o plugin-root— sin una alternativa (fallback) que funcione cuando el valor esté vacío o sin resolver; varias de ellas solo se completan en un harness concreto y quedan silenciosamente vacías en los demás. - Para un comando de shell ejecutado que corre un script incluido, haz que la resolución sea determinista: define un directorio base absoluto en línea dentro del mismo comando (el estado del shell no persiste entre llamadas) y haz referencia al script a partir de él, en lugar de usar una ruta relativa desnuda que se resuelve contra el directorio del proyecto del usuario en vez del de la unidad. ## Escribir solo reglas comprobables en las instrucciones y clasificar los comentarios de revisión antes de editar - Admite una línea solo cuando establece una restricción falsable, contrarresta una tendencia por defecto conocida o un atajo observado, o aporta conocimiento de dominio que cambia una decisión. Elimina el lenguaje vago sobre esfuerzo o calidad, como «sé minucioso»; sustitúyelo por una regla observable o descártalo. No añadas una justificación motivacional a una directiva que ya se sostiene por sí sola. - Repite una instrucción solo en un punto de desviación demostrado, donde su ubicación cambia si llega a activarse, y protege un duplicado genuinamente necesario con una prueba de paridad. - Trata la aplicación de comentarios de revisión como una revisión sustancial: clasifica cada elemento como Cambiar, Verificar o Considerar, y edita solo los elementos de Cambiar; corrige cada uno en la capa que le corresponde con el mecanismo más pequeño posible; después vuelve a leer el bloque y elimina el texto que el cambio haya dejado duplicado u obsoleto. La redacción del revisor es una hipótesis sobre la corrección, no una autoridad sobre ella. ## Buscar las convenciones del proyecto en el contexto ya cargado, sin nombrar archivos de instrucciones - Cuando una unidad necesite descubrir una convención del proyecto —el sistema de seguimiento de incidencias, el formato de commit, el comando de lint, los límites de alcance—, describe qué buscar en el contexto que el agente ya tiene cargado, no qué archivo abrir. En la ruta de lectura, no nombres archivos de instrucciones ocultos (dotfiles): el host ya inyecta el archivo de instrucciones raíz, su nombre de archivo varía según el harness, y decirle a un agente que abra archivos de instrucciones con nombre específico es exactamente el patrón que las defensas contra inyección de prompts detectan. - Nombra un archivo concreto únicamente cuando una referencia de contexto no pueda expresar la necesidad: al escribir una convención de vuelta en un destino, o al leer contenido que un subagente recién creado genuinamente no hereda. - Describe una capacidad por categoría («el sistema de seguimiento de incidencias del proyecto, por ejemplo GitHub Issues, Linear o Jira» y «cualquier interfaz que exponga»), y nunca trates la ausencia de un binario, una variable de entorno o un conector como prueba de que la capacidad no está disponible. ## Comparar el contenido, no la versión, para saber si la sesión tiene tu última edición - Después de editar contenido que una sesión de larga duración cargó al iniciarse, asume que la sesión sigue ejecutando la copia previa a la edición. Las cachés capturan el estado en el momento de la carga, y las ediciones dentro de un mismo lanzamiento no cambian el número de versión, así que una versión coincidente solo demuestra que la caché proviene de ese lanzamiento, no que capturó tu edición más reciente. - Confirma qué copia está activa comparando el contenido del archivo cargado con tu copia de trabajo, no leyendo la cadena de versión. Si son idénticos, la copia en ejecución está actualizada y es confiable; si difieren, reinicia o usa una ruta de carga fresca antes de confiar en una prueba de comportamiento. - Las rutas de código mecánicas —scripts, analizadores sintácticos, cualquier cosa que ejerza la suite de pruebas— siempre ejecutan el código fuente actual. Solo la capa de instrucciones y prosa cargada al inicio arrastra este desfase.