# Contexto e instrucciones para agentes de programación: cómo preparar una tarea con IA

> Prepara contexto útil para agentes de programación: instrucciones del repositorio, criterios de aceptación, límites, evidencia y una plantilla para AGENTS.md.

Canonical: https://www.gilbertsahumada.com/blog/contexto-instrucciones-agentes-programacion/
Last updated: 2026-10-20

Programación con IA · Agentes · Contexto

Cuando una sesión de programación con IA se desvía, puede faltar información sobre el proyecto, el resultado esperado o las restricciones. Añadir más mensajes no siempre resuelve esa falta: conviene organizar qué necesita saber el agente y cómo vas a comprobar su trabajo.

Esta guía propone tres capas de contexto: las reglas estables del repositorio, la tarea concreta y la evidencia que aparece durante la ejecución. Separarlas facilita detectar qué hay que actualizar cuando algo cambia.

## Reglas estables del repositorio

Documenta cómo se instala y ejecuta el proyecto, cuáles son sus comprobaciones y qué convenciones importan. Incluye rutas cuando ayuden a localizar una parte del sistema. Evita repetir una descripción extensa de cada archivo: esa información puede quedar desactualizada y ocultar lo necesario.

[AGENTS.md](https://agents.md/) es un formato abierto para proporcionar instrucciones y contexto a agentes de programación. Su soporte y el alcance de cada archivo dependen de la herramienta. Revisa la documentación de tu asistente antes de asumir que leerá una regla o aplicará una prioridad determinada.

Otras herramientas admiten mecanismos propios. Por ejemplo, la [documentación de instrucciones de GitHub Copilot](https://docs.github.com/en/copilot/concepts/prompting-and-context/custom-instructions) distingue ámbitos personales, del repositorio y de la organización, y señala que el soporte varía según el cliente.

Para un repositorio que usa npm, un archivo inicial podría tener esta estructura. Sustituye los comandos por los que hayas comprobado en tu proyecto:

```md
# Trabajo en este repositorio

## Puesta en marcha
- Instala dependencias con el gestor y lockfile del proyecto.
- Revisa los scripts de package.json antes de ejecutar comandos.
- Usa datos locales de prueba; no dependas de producción.

## Cambios
- Explica el comportamiento que vas a modificar.
- Reutiliza componentes y patrones existentes.
- Mantén el cambio limitado al requisito.
- No sobrescribas trabajo pendiente de otra tarea.

## Verificación
- Ejecuta las comprobaciones relevantes para el cambio.
- Informa resultados y limitaciones reales.
- No presentes una comprobación que no ejecutaste como aprobada.
```

Estas instrucciones no constituyen un control de acceso. Los permisos de las herramientas, las credenciales disponibles y las validaciones del servidor siguen necesitando su propia configuración.

## Contexto de la tarea concreta

Una tarea debe explicar el problema, el comportamiento esperado y sus límites. Si pides un filtro, aclara qué datos filtra, cómo se combina con la búsqueda y qué ocurre al cambiar de página.

Una plantilla útil es:

```text
Problema:
La lista de solicitudes no permite filtrar por estado.

Resultado:
Añadir las opciones Todos, Pendiente y Resuelta.
Conservar la búsqueda y el orden existentes.

Criterios:
- Todos muestra el conjunto permitido al usuario.
- Un filtro sin resultados muestra un estado vacío.
- La API rechaza estados desconocidos.
- No se amplía el acceso a solicitudes ajenas.

Límites:
Reutiliza los componentes y el stack existentes.
No cambies otras secciones ni añadas dependencias sin explicar su necesidad.

Verificación:
Indica cómo probar el caso normal, el estado vacío y el acceso rechazado.
```

No añadas rutas inventadas para dar una apariencia de precisión. Si no sabes dónde vive la funcionalidad, pide primero que la investigue y cite los archivos que haya leído.

## Da evidencia, no solo conclusiones

«El formulario no funciona» puede referirse a validación, red, permisos o almacenamiento. Un informe útil describe la acción realizada, el resultado observado y el resultado esperado.

Por ejemplo: «Con los campos completos, el botón muestra “Guardando”, la petición devuelve 403 y la pantalla no ofrece reintento». Añade el mensaje de error pertinente sin copiar tokens, contraseñas ni información de clientes.

Si compartes un log, distingue las líneas que pertenecen al intento actual. Si usas una captura, explica qué elemento estás señalando. El agente necesita relacionar esa evidencia con el recorrido del código, no asumir que toda la salida visible corresponde al mismo problema.

## Separa los datos encontrados de las instrucciones

Un agente puede leer documentación, incidencias, comentarios y respuestas de servicios externos. Ese contenido puede ayudar a resolver una tarea, pero no debería otorgar permisos nuevos por sí mismo.

Una instrucción encontrada en un archivo de terceros para subir credenciales o ejecutar un comando ajeno al objetivo requiere revisión. Mantén explícitos los límites de herramientas y destinos. El [catálogo de riesgos de IA generativa de OWASP](https://genai.owasp.org/llm-top-10/) incluye inyección de instrucciones y autonomía excesiva entre los temas que conviene considerar al integrar agentes.

En la práctica, proporciona secretos mediante los mecanismos del entorno, no dentro de un prompt o de un archivo de instrucciones versionado. Usa ejemplos sintéticos para explicar formatos y restringe las operaciones que no hagan falta.

## Cómo recuperar una sesión que se desvía

Detén el cambio y vuelve al criterio que se está incumpliendo. Resume qué está confirmado, qué salió mal y qué queda por investigar. A veces basta con retirar un supuesto equivocado; otras veces conviene empezar una sesión nueva con un resumen corto.

Puedes pedir:

> Antes de continuar, resume el estado actual. Separa hechos comprobados, supuestos y comprobaciones pendientes. Relaciona cada cambio propuesto con un criterio de aceptación. No edites archivos todavía.

Después revisa el diff. Si el asistente empezó una refactorización que no era necesaria, no la aceptes solo porque ya se escribió. Decide qué parte contribuye al objetivo y conserva únicamente los cambios que puedas justificar.

## Cuándo dividir el trabajo entre agentes

Distribuye tareas cuando puedan avanzar con límites claros y producir resultados verificables. Por ejemplo, una investigación puede localizar las validaciones y otra revisar los casos de prueba. Define quién integra y cómo resolverás contradicciones.

Evita que varios agentes editen simultáneamente los mismos archivos sin coordinación. También compara el coste de coordinar con el tamaño de la tarea: una corrección pequeña puede necesitar menos trabajo con un solo agente.

## Comprueba si tu contexto fue útil

Al terminar, observa si el cambio cumple el requisito, si se preservaron los límites y si la evidencia permite revisarlo. Un prompt largo que produce un diff difícil de entender no es necesariamente mejor que una instrucción corta con criterios precisos.

Practica con la [guía para programar con IA](https://www.gilbertsahumada.com/blog/programar-con-ia-guia-practica/) y termina con la [revisión del código generado](https://www.gilbertsahumada.com/blog/revisar-codigo-generado-por-ia/). Si quieres trabajar este método con ejercicios y revisión docente, consulta el [programa de la academia](https://academia.gilbertsahumada.com/).

## Related

* [¿De verdad me gustaba programar?](https://www.gilbertsahumada.com/blog/la-ia-el-codigo-y-quienes-somos-ahora/)
* [Cómo revisar código generado por IA antes de hacer merge](https://www.gilbertsahumada.com/blog/revisar-codigo-generado-por-ia/)
