Cómo configurar instrucciones personalizadas de repositorio en GitHub Copilot para estandarizar código y arquitectura en equipos de ingeniería

Cuando los equipos de desarrollo adoptan GitHub Copilot a gran escala, suelen enfrentarse a un desafío recurrente: la falta de coherencia en el código generado. Sin directrices compartidas, el modelo de IA responde basándose únicamente en su entrenamiento general y en los archivos abiertos recientemente en el editor. Como resultado, un desarrollador recibe sintaxis anticuada de JavaScript en un proyecto de TypeScript, otro vulnera la arquitectura en capas y un tercero introduce dependencias no homologadas en un Pull Request (PR).

GitHub Copilot soluciona este problema mediante las instrucciones personalizadas de repositorio (Repository Custom Instructions). Al añadir archivos Markdown versionados bajo control de Git —principalmente .github/copilot-instructions.md y archivos modulares bajo .github/instructions/**/*.instructions.md—, los equipos pueden inyectar límites arquitectónicos, convenciones de tipado, patrones de pruebas y requisitos de seguridad directamente en las consultas de Copilot y en las revisiones de código de toda la organización.

En esta guía se detalla cómo funcionan las instrucciones de repositorio, su orden de precedencia, cómo configurarlas a nivel global y por rutas, cómo integrarlas en las revisiones automáticas de PR y las mejores prácticas para no saturar la ventana de contexto de los modelos.

Dónde se aplican las instrucciones personalizadas (y dónde no)

Antes de redactar reglas, los equipos deben entender con precisión qué superficies de Copilot consumen estos archivos.

Las instrucciones de repositorio se anteponen de forma automática en el contexto del prompt enviado a los LLM durante flujos de trabajo de razonamiento e interacción:

• Copilot Chat en IDEs: VS Code, Visual Studio, la suite de JetBrains (IntelliJ IDEA, PyCharm, WebStorm, etc.), Xcode y Eclipse.
• Entornos en GitHub.com: Chat web en repositorios, tareas autónomas del agente de desarrollo en la nube (Cloud Agent) y generación asistida de PRs.
• Copilot Code Review: Revisiones automatizadas de pull requests en GitHub.com, donde el agente evalúa los cambios frente a los estándares del repositorio.
• Copilot CLI: Asistencia mediante línea de comandos en la terminal.

La distinción con el autocompletado en línea (Ghost Text)

Las instrucciones personalizadas de repositorio no controlan de forma determinista el texto fantasma (ghost text) que aparece en tiempo real mientras el desarrollador escribe en el editor. El autocompletado en línea está optimizado para responder con latencias de pocos milisegundos y basa su contexto inmediato en tokens adyacentes y pestañas abiertas. Por tanto, las instrucciones personalizadas deben concebirse como directrices para el chat, la refactorización (/fix, /explain), los agentes y las revisiones de PR. Para garantizar el formato sintáctico estricto (espacios, punto y coma, comillas), combine Copilot con herramientas de análisis estático como ESLint, Biome o Prettier.

Jerarquía de precedencia de instrucciones

Cuando coexisten múltiples fuentes de instrucciones, GitHub Copilot las combina aplicando el siguiente orden de prioridad (de mayor a menor):

1. Instrucciones personales (Personal instructions): Preferencias individuales del desarrollador configuradas en su cuenta de Copilot.
2. Instrucciones específicas por ruta (Path-specific instructions): Archivos .github/instructions/**/*.instructions.md que coinciden mediante patrones glob con el archivo editado.
3. Instrucciones globales de repositorio (Repository-wide instructions): El archivo .github/copilot-instructions.md en la raíz.
4. Instrucciones de agente: Archivos como AGENTS.md, CLAUDE.md o GEMINI.md.
5. Instrucciones de organización (Organization instructions): Políticas configuradas por administradores a nivel de organización en GitHub.

Paso 1: Crear las instrucciones globales del repositorio (.github/copilot-instructions.md)

El archivo base de configuración se ubica en el directorio .github en la raíz del repositorio:

mkdir -p .github
touch .github/copilot-instructions.md

Para optimizar la adherencia del modelo, redacte el documento con encabezados Markdown bien estructurados, listas concisas y directrices expresadas en positivo.

Secciones clave recomendadas

1. Visión general y límites de arquitectura: Descripción del proyecto, patrón arquitectónico (Clean Architecture, monolito modular, arquitectura hexagonal) y prohibiciones de acoplamiento (ej.: "La capa de dominio nunca debe importar dependencias de base de datos ni componentes UI").
2. Versiones de lenguaje y herramientas clave: Versiones exactas del runtime y librerías (ej.: Node.js 22 LTS, TypeScript 5.5, Next.js 15 App Router).
3. Convenciones de código y patrones: Estilo de nomenclatura, tratamiento de errores (ej.: "Utilizar el tipo Result en lugar de lanzar excepciones no controladas").
4. Directrices de pruebas (Testing): Framework de pruebas (Vitest, Jest), patrón de estructuración (AAA: Arrange-Act-Assert) y cobertura requerida para lógica de negocio.
5. Seguridad y validación de entrada: Esquemas de validación obligatorios (Zod, Pydantic), consultas SQL parametrizadas y prohibición de credenciales en código.

Plantilla de producción (Servicio en TypeScript y Next.js)

# Arquitectura y estándares de desarrollo del repositorio

## Descripción del proyecto
Este repositorio contiene el servicio central de facturación (Core Billing Service), desarrollado con Next.js y Node.js, conectado a PostgreSQL y Stripe.

## Límites arquitectónicos
- Separación estricta de capas: Componentes UI (`/app`, `/components`) -> Servicios de aplicación (`/src/services`) -> Modelos de dominio (`/src/domain`) -> Repositorios de datos (`/src/infrastructure`).
- La capa de dominio debe ser agnóstica al framework. Queda prohibido importar módulos de `next/*` o clientes de base de datos en `/src/domain`.
- Toda interacción con la base de datos debe canalizarse a través de los repositorios de Prisma en `/src/infrastructure/repositories`. Se prohíbe el uso de SQL directo fuera de las migraciones.

## Estándares de TypeScript
- TypeScript 5.x en modo strict. Queda prohibido el uso de `any`; utilice `unknown` con refinamiento de tipos o esquemas Zod.
- Prefiera alias `type` para objetos y uniones; reserve `interface` para contratos extensibles.
- Gestione errores asíncronos mediante tipos `Result<T, E>` o clases de error estructuradas; evite Promise rejections no capturadas.
- Aplique cláusulas de guarda (guard clauses) y retornos tempranos para evitar anidamientos de condicionales.

## Gestión de estado y llamadas de red
- Las peticiones en el cliente deben utilizar TanStack Query (`@tanstack/react-query`). No utilice hooks `useEffect` sin memoizar para llamar a APIs.
- Las Server Actions deben validar las cargas útiles entrantes con esquemas Zod antes de invocar los servicios de dominio.

## Estándares de pruebas
- Ejecutor de pruebas: Vitest con React Testing Library.
- Las pruebas unitarias deben ubicarse junto al código fuente correspondiente (`*.spec.ts` o `*.spec.tsx`).
- Estructura obligatoria: Arrange-Act-Assert (AAA) en cada suite.
- Simule llamadas de red mediante Mock Service Worker (MSW); no cree mocks de utilidades internas del lenguaje.

## Comandos de referencia
- Ejecutar pruebas: `pnpm test`
- Verificación de tipos: `pnpm typecheck`
- Linter y formato: `pnpm lint`

Paso 2: Configurar instrucciones por ruta (.github/instructions/)

En monorrepositorios o proyectos full-stack, colocar todas las directrices en un único archivo global satura el contexto y dispersa la atención del LLM. Por ejemplo, quien modifica un microservicio en Go no necesita reglas de componentes React o Tailwind CSS.

Las instrucciones específicas por ruta resuelven esto aplicando reglas únicamente cuando se interactúa con archivos que coinciden con patrones glob.

Estructura de carpetas

Organice los archivos modulares dentro de .github/instructions/:

.github/
  ├── copilot-instructions.md
  └── instructions/
      ├── frontend.instructions.md
      ├── backend.instructions.md
      └── migrations.instructions.md

Sintaxis con Frontmatter

Cada archivo debe terminar en .instructions.md y comenzar con un bloque YAML Frontmatter que defina el atributo applyTo:

---
applyTo: "apps/web/**/*.{ts,tsx}"
---

# Estándares de componentes Frontend

- Los componentes deben ser funciones con exportaciones con nombre (Named Exports).
- Emplee clases de utilidad de Tailwind CSS; evite objetos CSS en línea.
- Todo elemento interactivo debe incluir atributos `aria-*` y compatibilidad total con teclado.
- Los iconos deben importarse exclusivamente desde `lucide-react`.

Patrones Glob habituales

• **/*.py: Aplica a todos los archivos Python en cualquier profundidad.
• services/billing/**/*.go: Aplica exclusivamente al código Go del servicio de facturación.
• **/*.test.ts,**/*.spec.ts: Coincide con ambos tipos de archivos de prueba mediante separación por coma.

Exclusión de agentes específicos (excludeAgent)

Si un conjunto de instrucciones está pensado únicamente para el agente de construcción y no debe dispararse durante la revisión de código de un PR, utilice excludeAgent:

---
applyTo: "**"
excludeAgent: "code-review"
---

# Guía para el agente de construcción autónomo
- Ejecute `pnpm db:migrate` antes de iniciar las suites de pruebas de integración.
- Al añadir nuevas variables de configuración, actualice el archivo `.env.example`.

Paso 3: Activar las instrucciones en las revisiones de código de Pull Requests

Las instrucciones personalizadas no solo asisten al desarrollador mientras programa, sino que también actúan como criterio evaluador en GitHub Pull Requests.

Pasos para habilitar la revisión automatizada

1. En GitHub.com, acceda a su repositorio.
2. Haga clic en la pestaña Settings (Configuración).
3. En la barra lateral izquierda, navegue hasta Code, planning, and automation -> Copilot -> Code review.
4. Active la opción Use custom instructions when reviewing pull requests.

Evaluación desde la rama origen (Head Branch)

Durante la revisión de un PR, Copilot lee el archivo .github/copilot-instructions.md y las instrucciones asociadas desde la rama de origen del PR (head branch), y no desde la rama base (main).

Esto aporta una ventaja operativa fundamental: cuando el equipo técnico decida actualizar los estándares de desarrollo, puede crear un PR que incluya tanto las nuevas instrucciones como el código adaptado a ellas. Copilot evaluará el PR con base en las directrices actualizadas de inmediato, permitiendo validar las reglas antes de fusionarlas en main.

Paso 4: Verificar la carga de instrucciones en el entorno local

Para comprobar que las herramientas locales reconocen correctamente los archivos de instrucciones:

1. Configuración en el IDE:
   • En VS Code, abra Configuración (Ctrl+, o Cmd+,), busque instruction file y confirme que Code Generation: Use Instruction Files esté activado (activado por defecto).
   • En JetBrains, dentro del panel de Copilot Chat, haga clic en el icono de engranaje y seleccione Customizations para visualizar las instrucciones del espacio de trabajo.
2. Inspeccionar la lista de referencias (References):
   • Realice una consulta técnica en Copilot Chat (por ejemplo: "Diseña un servicio de autenticación").
   • Despliegue el apartado References en la parte superior de la respuesta.
   • Si la configuración es correcta, aparecerá listado .github/copilot-instructions.md (y el archivo .instructions.md correspondiente), confirmando que la IA utilizó las directrices de su equipo.

Buenas prácticas y errores frecuentes

Uso complementario de Prompt Files (.github/prompts/*.prompt.md)

Mientras que las instrucciones personalizadas de repositorio definen restricciones permanentes, los equipos suelen repetir flujos específicos: crear nuevos endpoints, generar migraciones o estructurar matrices de pruebas unitarias.

Para estas tareas, combine las instrucciones con los archivos de prompts (.github/prompts/*.prompt.md). Los archivos de prompt permiten invocar plantillas reutilizables desde Copilot Chat, mientras que .github/copilot-instructions.md garantiza en segundo plano que el código generado respete la arquitectura del proyecto.

Lista de verificación para líderes técnicos

1. Crear .github/copilot-instructions.md en la raíz con la arquitectura general, dependencias fijadas y estándares obligatorios.
2. Añadir reglas en .github/instructions/ con filtros applyTo para directorios o lenguajes específicos.
3. Habilitar "Use custom instructions when reviewing pull requests" en la configuración del repositorio en GitHub.
4. Validar en Copilot Chat que los archivos aparezcan en la sección References de las respuestas.
5. Actualizar los archivos de instrucciones de forma continua a medida que la arquitectura evolucione.

Referencias

• Adding repository custom instructions for GitHub Copilot - GitHub Docs
• Adding repository custom instructions for GitHub Copilot in your IDE - GitHub Docs
• Support for different types of custom instructions - GitHub Docs
• About customizing GitHub Copilot responses - GitHub Docs
• 5 tips for writing better custom instructions for Copilot - The GitHub Blog