Da al agente contexto útil del repositorio

Empieza por la copia de trabajo actual

El agente necesita saber qué repositorio y qué rama va a modificar. También necesita saber si el directorio de trabajo contiene cambios ajenos a la tarea. Estos datos afectan a lo que puede editar de forma segura y a cómo debe interpretarse el diff final.

Pídele que inspeccione las instrucciones del proyecto y la configuración de paquetes antes de implementar. Un comando recordado de otro repositorio puede ser incorrecto aquí. Conocer el nombre de un framework no demuestra qué versión está instalada ni cuáles son las convenciones del proyecto.

Para un cambio pequeño, proporciona el módulo pertinente, sus llamadores, las pruebas y la decisión de arquitectura. Añade información cuando la investigación revele una necesidad concreta.

Usa las instrucciones del repositorio para las reglas estables

Un archivo de instrucciones puede describir los comandos admitidos, los límites de los módulos, los requisitos de revisión y las acciones que necesitan una decisión del responsable. La convención AGENTS.md ofrece a las herramientas de programación un lugar reconocible para esta información. La compatibilidad y la prioridad de las instrucciones varían entre herramientas; comprueba cómo se comporta la tuya.

Mantén las reglas estables del proyecto en el repositorio. Mantén la tarea actual en sus instrucciones específicas. No conviertas el archivo de instrucciones en un historial de todas las conversaciones ni en una lista de planes temporales.

Una instrucción útil dice: «Ejecuta las pruebas de integración de autorización cuando una ruta cambie el comportamiento de acceso». Una instrucción vaga dice: «Ten siempre cuidado con la seguridad». La primera identifica una condición y una acción que quien revisa puede verificar.

Contrasta las instrucciones con el código

Las instrucciones quedan obsoletas cuando cambian los comandos, los directorios o la arquitectura. Si una guía menciona un script ausente, inspecciona la configuración de paquetes. Si un documento dice que un servicio es de solo lectura, inspecciona los permisos antes de fiarte de esa afirmación.

Registra el conflicto. Usa pruebas directas de la versión actual para comprender el comportamiento de la implementación. No descartes en silencio una política intencional porque el código antiguo la incumpla. La política y el comportamiento actual responden a preguntas distintas.

Por ejemplo, la guía puede prohibir escribir directamente en una rama compartida mientras un script antiguo sigue haciéndolo. La respuesta correcta es conservar la política y corregir el script. El código existente no da permiso para repetir una acción prohibida.

Mantén un contexto pertinente y seguro

Un repositorio completo puede contener credenciales, datos de prueba privados, exportaciones de clientes y logs antiguos de soporte. Tener acceso al repositorio no significa que todos los archivos sean adecuados para un servicio de modelos.

Usa herramientas autorizadas y cumple las reglas de tratamiento de datos. Excluye los secretos del contexto. Sustituye los ejemplos de clientes por datos inventados cuando sea posible. Comprueba las herramientas conectadas además de los archivos subidos: un conector de búsqueda puede recuperar información que nunca estuvo en el prompt inicial.

La instrucción «no leas secretos» es una orientación útil. No sustituye a limitar el acceso a los almacenes de secretos y los directorios sensibles.

Deja un registro útil para la siguiente persona

Al terminar, registra en la pull request el comportamiento modificado, la verificación y los límites sin resolver. Actualiza la documentación estable del proyecto cuando cambie el flujo de trabajo admitido. Evita copiar toda la transcripción del agente en el repositorio.

El registro debe permitir que quien mantenga el sistema repita el trabajo sin reconstruir una conversación larga. Enlaza a documentos canónicos y conserva una única descripción autorizada de cada regla estable.

Un buen contexto reduce la investigación repetida. También facilita detectar errores, porque hace explícitos el comportamiento esperado y los comandos que funcionan.