Incorpora la IA a un código nuevo como a un humano
No dejes que tu IA escriba código en un repositorio que todavía no ha leído. Un compañero nuevo no hace push a main el primer día: lee los manifiestos, explora los puntos de entrada, corre las pruebas y sigue un request real a través del sistema. Tu agente de código necesita exactamente el mismo onboarding, en un orden fijo, porque un agente que adivina tus convenciones produce código que compila pero que no encaja.
Por qué adivinar rompe las convenciones
Un modelo que no ha leído tu repositorio recurre a la respuesta estadísticamente popular: el idioma más común del framework, la estructura de carpetas más común, el estilo de pruebas más común. Si tu proyecto se desvía en algo — un tipo de error propio, un esquema de nombres de la casa, un wrapper sobre el cliente HTTP — el primer borrador del agente pelea contra eso. La guía de Anthropic lo dice sin rodeos: dejar que el agente salte directo a programar "puede producir código que resuelve el problema equivocado", y por eso el flujo recomendado es explorar primero, luego planificar y después implementar. El onboarding es el paso de "explorar" hecho sistema.
El orden fijo de reconocimiento
Ejecuta estas cinco lecturas en secuencia, primero la señal más barata. Cada paso reduce lo que el siguiente tiene que explicar.
| Paso | Lee | Qué le dice al agente |
|---|---|---|
| 1 | Manifiestos de paquetes (package.json, pyproject.toml, go.mod, …) | Stack exacto, versiones, scripts, dependencias de dev vs. prod |
| 2 | Configuración del framework (archivos del framework, lockfile, config de build) | Qué convenciones son estructurales y cuáles opcionales |
| 3 | Puntos de entrada (main, bootstrap del servidor, registro de rutas) | Dónde arranca la ejecución y cómo se conectan los módulos |
| 4 | Estructura de pruebas (directorios de tests, fixtures, cómo se invoca el runner) | Cómo se define lo correcto aquí y qué significa "terminado" |
| 5 | Build y CI (Makefile, workflows de CI) | Los chequeos que un cambio debe superar antes del merge |
El orden importa. Manifiestos antes que framework, porque el manifiesto nombra al framework. Puntos de entrada antes que pruebas, porque las pruebas referencian los módulos que los puntos de entrada exponen. CI al final, porque es el resumen de todo lo que el equipo hace cumplir.
Después, rastrea un request real
El reconocimiento le da al agente un mapa; el rastreo le da el terreno. Elige una ruta de código en producción — un login, un checkout, una llamada a la API — y haz que el agente la siga desde el punto de entrada, pasando por middleware, lógica de negocio y base de datos, y de vuelta como respuesta. Esa única ruta ancla todo lo demás: muestra el estilo de manejo de errores, la forma de los logs, los límites de las transacciones y las reglas de capas que ningún README declara en voz alta. El código nuevo que se escribe después se integra, porque el agente ya vio cómo se ve "integrado".
Nivel avanzado: escribe el onboarding una sola vez
Hacer onboarding del agente en cada sesión desperdicia tokens y tiempo. Persiste el resultado:
AGENTS.md— un formato abierto y agnóstico de herramienta, un "README para agentes" (comandos de build/test, estilo de código, descripción del proyecto), soportado por Codex, Gemini CLI, Cursor, Copilot y decenas de herramientas más.CLAUDE.md— el archivo de memoria por proyecto de Claude Code, cargado al inicio de cada sesión. No leeAGENTS.mddirectamente, pero un import de una línea@AGENTS.md(o un symlink) hace que ambas herramientas compartan una sola fuente de verdad..github/copilot-instructions.md— las instrucciones personalizadas de repositorio de GitHub Copilot; GitHub recomienda el mismo contenido que este reconocimiento produce: pasos de build, comandos de pruebas, pipeline de validación, estructura del proyecto.
Mantenlo corto — Anthropic recomienda no pasar de unas 200 líneas y GitHub limita su guía a unas dos páginas — e incluye solo lo que el agente no puede deducir leyendo el código: comandos, trampas conocidas y convenciones que difieren de los valores por defecto. El orden de reconocimiento de arriba es exactamente la lista para llenarlo: ejecútalo una vez, guarda las respuestas, y cada sesión futura arranca ya incorporada.
Recursos
- How Claude remembers your project — archivos de memoria CLAUDE.md
- Claude Code best practices — explorar, planificar y luego programar
- AGENTS.md — el formato abierto para guiar agentes de código
- Adding repository custom instructions for GitHub Copilot
¿Construyendo una funcionalidad con IA? Yeda AI diseña, audita y entrega sistemas LLM de producción.