English

Un Solo Archivo Para Dejar De Repetirte Con Copilot

Si alguna vez pegaste el mismo recordatorio de "usa tabs, no espacios" o "siempre agrega manejo de errores" en GitHub Copilot Chat por tercera vez en la semana, ya conoces el problema. Copilot no tiene memoria entre sesiones de chat — cada conversación nueva arranca desde cero, sin contexto sobre cómo escribe código tu equipo en realidad. La solución no es un mejor prompt. Es un archivo que Copilot lee automáticamente, antes de responder cualquier cosa.

El problema: contexto que se evapora

Copilot Chat no guarda estado entre sesiones. Cualesquiera convenciones que escribiste en la conversación de ayer — tu esquema de nombres, tu patrón preferido de manejo de errores, "nunca uses any en TypeScript" — desaparecen en el momento en que abres un chat nuevo. Multiplica eso por cada compañero que usa Copilot en el mismo repositorio y obtienes un equipo que se dispersa en silencio: cada persona vuelve a explicar una versión ligeramente distinta de "cómo hacemos las cosas aquí", y las sugerencias de Copilot varían según quién haya escrito qué en el chat ese día.

La solución: instrucciones personalizadas del repositorio

GitHub Copilot admite un archivo de instrucciones para todo el repositorio que carga automáticamente, en cada chat, para cada colaborador. Créalo en:

.github/copilot-instructions.md

El nombre del archivo y la ruta son exactos — Copilot busca este archivo específico, en esta ubicación específica, en formato Markdown. Todo lo que pongas ahí — convenciones de arquitectura, requisitos de pruebas, librerías preferidas, reglas de estilo — se integra al contexto de Copilot antes de que genere una respuesta. Sin copiar y pegar, sin volver a explicar, sin dispersión entre compañeros: todos los que heredan el mismo repositorio heredan las mismas reglas.

Según la documentación de GitHub, las instrucciones "no deben ser específicas de una tarea" y deberían mantenerse por debajo de aproximadamente dos páginas — este es un lugar para convenciones duraderas ("usamos inyección de dependencias para todos los servicios"), no para instrucciones puntuales de una tarea ("arregla el bug en checkout.js").

Cómo crearlo

Tienes dos caminos:

1. Escríbelo a mano. Crea .github/copilot-instructions.md en la raíz de tu repositorio y lista tus convenciones como viñetas o secciones de Markdown simple — no se requiere sintaxis especial para el archivo de todo el repositorio.
2. Deja que Copilot lo redacte por ti. En Copilot Chat, haz clic en el ícono del engranaje y elige "Generate agent instructions". Copilot escanea tu repositorio y redacta un archivo inicial, y es lo bastante astuto como para revisar si ya escribiste instrucciones para otras herramientas — busca un AGENTS.md, CLAUDE.md, GEMINI.md existente o un archivo de reglas de Windsurf e integra el contenido relevante en lugar de empezar de cero. Revisa y edita lo que genera; trátalo como un primer borrador, no como una respuesta final.

Acotar reglas a archivos específicos

No toda convención aplica en todas partes. Tus scripts de PowerShell necesitan reglas de formato distintas a las de tus archivos de pruebas, y ninguno debería contaminar el contexto del otro. Para eso, Copilot admite archivos de instrucciones específicos por ruta, guardados en .github/instructions/ y nombrados NAME.instructions.md. Cada uno abre con frontmatter YAML que declara a qué archivos aplica:

---
applyTo: "**/*.ps1"
---

El valor de applyTo es un patrón glob — **/*.ps1 coincide con archivos de PowerShell en cualquier lugar del repositorio, src/**/*.py lo acota a archivos de Python bajo src/. También puedes apuntar a varios patrones en un mismo archivo con una lista separada por comas, por ejemplo "**/*.ts,**/*.tsx". La documentación de GitHub también documenta una clave opcional excludeAgent para mantener un archivo de instrucciones dado fuera de herramientas específicas (por ejemplo, un agente de revisión de código o un agente en la nube), si necesitas instrucciones que no deberían aplicar universalmente.

Precedencia cuando las reglas entran en conflicto

Cuando un archivo específico por ruta y el archivo de todo el repositorio aplican al mismo archivo — digamos que estás editando un script .ps1 y tanto copilot-instructions.md como powershell.instructions.md están en alcance — Copilot usa ambos, y las instrucciones más específicas ganan en los conflictos. GitHub documenta el orden de prioridad más amplio como: instrucciones personales (las tuyas, si están configuradas) primero, luego las instrucciones del repositorio, y por último las instrucciones a nivel de organización. En la práctica, eso significa que tus archivos acotados .instructions.md son un lugar seguro para tallar excepciones a una regla global sin tener que reescribir el archivo global.

Trampas que evitar

• No vuelques toda tu guía de estilo. Cada línea en copilot-instructions.md consume contexto en cada interacción de chat. Un archivo inflado ahoga la pregunta específica que en realidad estás haciendo. Mantenlo en las convenciones que realmente cambian la salida de Copilot, no en sabiduría general de ingeniería.
• No lo hagas específico de una tarea. GitHub desaconseja explícitamente instrucciones como "cuando pida X, haz Y" en el archivo de todo el repositorio — eso pertenece a un prompt, no a instrucciones permanentes.
• Recuerda que es markdown, no magia. Copilot sigue estas instrucciones como una guía fuerte, no como una restricción rígida — aún querrás revisar las sugerencias, sobre todo al principio, mientras afinas el archivo.
• Mantén acotados los archivos específicos por ruta. Un patrón glob demasiado amplio (**/*) anula el propósito de acotar — terminas de vuelta en un solo archivo global, solo que repartido en varias ubicaciones.

Conclusión

Un archivo markdown, una ubicación, leído automáticamente por cada chat: ese es todo el mecanismo. Escribe .github/copilot-instructions.md a mano o genera un borrador con el menú del engranaje, y luego añade capas de archivos .github/instructions/*.instructions.md con globs applyTo para cualquier cosa que no deba aplicar en todo el repositorio. Hazlo una vez, y cada futura conversación de Copilot en ese repositorio empieza sabiendo ya cómo trabaja tu equipo.

Recursos

• GitHub Docs — Add repository custom instructions for GitHub Copilot