GitHub Copilot

Un asistente de IA sin contexto repite las mismas preguntas y sugiere código que no encaja con tus convenciones. GitHub Copilot resuelve esto leyendo, en cada sesión, un archivo de instrucciones que vive en .github/. Vos escribís una vez las convenciones del proyecto y Copilot las usa como contexto adicional siempre, sin que tengas que repetirlas.

copilot-instructions.md a nivel de repositorio

El archivo de instrucciones personalizadas para todo el repositorio se llama copilot-instructions.md y se ubica en la carpeta .github/ en la raíz del repo. Es un archivo Markdown en lenguaje natural: no hay sintaxis especial ni frontmatter obligatorio, escribís prosa y listas.

Copilot Chat y el coding agent lo leen automáticamente y lo suman al contexto de cada interacción. Qué conviene poner:

• Convenciones del proyecto (estilo de código, nombres, estructura de carpetas).
• Comandos exactos de build, test y lint.
• Notas de arquitectura y decisiones importantes.
• Qué evitar (dependencias prohibidas, patrones deprecados).

<!-- .github/copilot-instructions.md -->
# Instrucciones para Copilot

Este proyecto es una API en Node.js con TypeScript.

## Comandos
- Instalar: `bun install`
- Tests: `bun test`
- Lint: `bun run lint`

## Convenciones
- Arquitectura hexagonal: la lógica de dominio no importa nada de infraestructura.
- Preferí funciones pequeñas y puras.
- Los errores de dominio son clases propias, no strings.

Nota: instrucciones concisas y accionables funcionan mejor que descripciones vagas. “Usá bun test para correr los tests” es útil; “escribí buen código” no aporta nada.

Instrucciones específicas por path

Un solo archivo global no siempre alcanza: las reglas del frontend no son las del backend ni las de los tests. Para eso existen archivos .github/instructions/NOMBRE.instructions.md, cada uno con un frontmatter que incluye la clave applyTo: — un patrón glob que limita a qué archivos aplica esa instrucción.

---
applyTo: "**/*.test.ts"
---

En los tests:
- Usá `describe`/`it` con nombres en español que describan el comportamiento.
- No mockees el sistema de archivos; usá un directorio temporal real.

Con applyTo: "**/*.test.ts", esas reglas solo se aplican cuando Copilot trabaja sobre archivos de test. Podés tener otro archivo con applyTo: "src/frontend/**" para reglas de UI, y así separar contextos dentro del mismo repo.

flowchart TD
    ORG["Instrucciones de organización<br/>(todos los repos de la org)"] --> REPO
    REPO["copilot-instructions.md<br/>(todo el repositorio)"] --> PATH
    PATH["*.instructions.md con applyTo<br/>(solo archivos que matchean el glob)"]

Instrucciones a nivel de organización

Por encima del repo, los administradores de una organización pueden definir instrucciones custom por defecto que se aplican a todos los repos de la org. Es una capa superior útil para políticas transversales (por ejemplo, “siempre incluir tests en los PRs”). No reemplaza a las del repo: se suma a ellas.

Buenas prácticas

• Concisas y accionables: comandos exactos, no descripciones genéricas.
• Sin contradicciones: evitá que las instrucciones choquen con la config de otras herramientas del repo (linter, formatter). Si el linter ya impone algo, no lo repitas contradiciéndolo.
• Al día: cuando cambian las convenciones, actualizá el archivo. Instrucciones viejas guían mal.

Vale trazar un paralelismo: copilot-instructions.md es, en esencia, contexto persistente para un agente de IA — la misma idea detrás de los archivos de instrucciones que usan otras herramientas de asistencia. Un lugar fijo, versionado junto al código, donde el proyecto le cuenta al asistente cómo se trabaja acá.

---

Anterior → Capítulo 13: Automatización de repo · Siguiente → Capítulo 15: Proyecto integrador