Contexto y personalización

Custom Instructions y prompt files reutilizables

GitHub Copilot permite personalizar su comportamiento mediante instrucciones específicas que se aplican automáticamente a todas las interacciones dentro de un proyecto. Esta funcionalidad resulta especialmente valiosa para equipos que necesitan mantener consistencia en el código generado y para proyectos con requisitos específicos de estilo o arquitectura.

Configuración de Custom Instructions

Las Custom Instructions se definen mediante un archivo especial ubicado en .github/copilot-instructions.md en la raíz del proyecto. Este archivo actúa como un contexto permanente que Copilot considera en cada sugerencia o respuesta que genera.

# Instrucciones para GitHub Copilot

## Estilo de código
- Utiliza TypeScript estricto con tipos explícitos
- Prefiere const sobre let cuando sea posible
- Usa nombres descriptivos para variables y funciones
- Implementa manejo de errores con try-catch

## Arquitectura del proyecto
- Sigue el patrón MVC para la estructura de carpetas
- Utiliza inyección de dependencias para servicios
- Implementa interfaces para todos los contratos públicos
- Separa la lógica de negocio de la presentación

## Convenciones específicas
- Los componentes React deben usar hooks funcionales
- Implementa validación de props con PropTypes
- Usa async/await en lugar de Promises encadenadas
- Prefiere composición sobre herencia

El archivo debe escribirse en formato Markdown y puede incluir secciones específicas según las necesidades del proyecto. Copilot procesará estas instrucciones automáticamente cuando genere código o responda preguntas dentro del workspace.

Creación de Prompt Files reutilizables

Los prompt files permiten crear plantillas de consultas reutilizables que el equipo puede utilizar de forma consistente. Estos archivos se almacenan en la carpeta .github/prompts/ y pueden invocarse mediante el comando @workspace en Copilot Chat.

Estructura básica de un prompt file:

---
title: Crear componente React
description: Genera un componente React funcional con TypeScript
---

Crea un componente React funcional que:
- Use TypeScript con tipos explícitos
- Implemente props interface
- Incluya manejo de estados con useState
- Tenga documentación JSDoc
- Siga las convenciones del proyecto

Nombre del componente: {{component_name}}
Props requeridas: {{props_list}}

Ejemplo de prompt file para testing:

---
title: Generar tests unitarios
description: Crea tests completos para funciones y componentes
---

Genera tests unitarios usando Jest y React Testing Library que incluyan:
- Tests de renderizado básico
- Tests de interacción con eventos
- Tests de props y estados
- Mocks para dependencias externas
- Casos edge y manejo de errores

Archivo a testear: {{file_path}}
Funcionalidades específicas: {{features}}

Organización de prompts por categorías

La carpeta .github/prompts/ puede organizarse en subcarpetas temáticas para facilitar la gestión y localización de prompts específicos:

.github/prompts/
├── components/
│   ├── react-component.md
│   ├── form-component.md
│   └── modal-component.md
├── testing/
│   ├── unit-tests.md
│   ├── integration-tests.md
│   └── e2e-tests.md
├── api/
│   ├── rest-endpoint.md
│   ├── graphql-resolver.md
│   └── middleware.md
└── documentation/
    ├── readme-section.md
    ├── api-docs.md
    └── changelog-entry.md

Uso de variables en prompt files

Los prompt files admiten variables dinámicas que se pueden sustituir durante la ejecución. Estas variables se definen usando la sintaxis {{variable_name}} y permiten crear prompts flexibles y reutilizables.

---
title: Crear servicio de API
description: Genera un servicio para consumir APIs REST
---

Crea un servicio TypeScript para la API {{api_name}} que:
- Implemente métodos CRUD básicos
- Use axios para las peticiones HTTP
- Incluya manejo de errores personalizado
- Tenga tipos TypeScript para requests/responses
- Implemente retry logic para fallos de red

Base URL: {{base_url}}
Endpoints requeridos: {{endpoints}}
Autenticación: {{auth_type}}

Mejores prácticas para instructions efectivas

Las instrucciones efectivas deben ser específicas, claras y orientadas a resultados concretos. Evita instrucciones demasiado genéricas que puedan interpretarse de múltiples formas.

Instrucciones específicas por tecnología:

## Framework específico - Next.js
- Usa App Router en lugar de Pages Router
- Implementa Server Components cuando sea posible
- Utiliza dynamic imports para code splitting
- Configura metadata para SEO en cada página

## Base de datos - Prisma
- Define modelos con relaciones explícitas
- Usa transacciones para operaciones complejas
- Implementa soft deletes con campos deletedAt
- Incluye índices para consultas frecuentes

Configuración de contexto por equipo:

## Estándares del equipo
- Commits en inglés siguiendo Conventional Commits
- Pull requests requieren al menos 2 revisiones
- Cobertura de tests mínima del 80%
- Documentación obligatoria para APIs públicas

## Herramientas del proyecto
- ESLint con configuración personalizada
- Prettier para formateo automático
- Husky para pre-commit hooks
- Jest para testing unitario

La efectividad de las instrucciones mejora cuando se combinan reglas generales con ejemplos específicos que ilustren el comportamiento esperado. Esto ayuda a Copilot a generar código más alineado con las expectativas del proyecto y reduce la necesidad de correcciones manuales posteriores.

Contexto histórico: de los system prompts a los archivos de instrucciones

Los primeros usuarios de modelos de lenguaje descubrieron rápidamente que la calidad de las respuestas dependía casi por completo de lo bien que estuviera redactada la instrucción inicial. Herramientas como ChatGPT introdujeron el concepto de system prompt, un mensaje invisible que condicionaba toda la conversación. GitHub tomó ese patrón y lo llevó al terreno del desarrollo con las Custom Instructions de Copilot: en lugar de repetir el contexto en cada mensaje, los equipos lo declaran una vez en un archivo versionado y el asistente lo respeta en cada sugerencia. Esta aproximación convierte las instrucciones en un activo más del repositorio, con historial Git y revisiones en pull requests.

Atajos de teclado y comandos relacionados

Varias combinaciones útiles para trabajar con Copilot y sus instrucciones:

• Ctrl + I: abre Copilot Inline Chat en el editor, donde puedes pedir modificaciones puntuales al código seleccionado.
• Ctrl + Alt + I: abre Copilot Chat en el panel lateral para conversaciones más largas.
• Ctrl + Shift + P y Copilot: Open Copilot Instructions: abre directamente el archivo .github/copilot-instructions.md.
• Ctrl + Shift + P y Copilot: Reload Instructions: recarga las instrucciones sin reiniciar el editor.
• @workspace en el chat: incluye el contexto completo del workspace en la consulta.
• #file: añade un archivo concreto como contexto adicional.

Ejemplo paso a paso: crear instrucciones para un proyecto Spring Boot

Imagina que lideras un equipo trabajando en una API Spring Boot con Java 17. El flujo sería:

1. Crea el archivo .github/copilot-instructions.md en la raíz.
2. Añade una sección Estilo con reglas como "Usa records en lugar de clases para DTOs" o "Prefiere constructores inyectados sobre @Autowired".
3. Añade una sección Arquitectura con la estructura de paquetes (controller, service, repository, domain).
4. Añade una sección Testing con "Usa JUnit 5 y AssertJ; escribe al menos un test por endpoint".
5. Haz commit del archivo y push al repositorio.
6. Abre el chat de Copilot con Ctrl + Alt + I y pide: "Genera un controlador REST para gestionar productos".
7. Observa cómo el código generado respeta las convenciones declaradas.
8. Ajusta las instrucciones según los resultados y vuelve a probar.

Tabla comparativa de mecanismos de personalización

| Mecanismo | Alcance | Reutilización | Versionado | Uso típico | |-----------|---------|---------------|-------------|-----------| | copilot-instructions.md | Repositorio completo | Alta | Sí | Reglas globales del proyecto | | Prompt files | Comandos específicos | Muy alta | Sí | Plantillas de consultas | | System prompts manuales | Conversación actual | Baja | No | Ajustes puntuales | | Custom chat modes | Todo el editor | Media | Parcial | Personas o roles especializados | | Settings JSON | Usuario o workspace | Media | Sí en workspace | Configuración fina |

Errores comunes al personalizar Copilot

Varios tropiezos habituales:

• Instrucciones demasiado largas: los modelos tienen un contexto limitado; si las instrucciones ocupan miles de palabras, parte del código enviado se truncará.
• Reglas contradictorias: decir "usa clases" en una sección y "usa records" en otra confundirá al modelo.
• No actualizar las instrucciones al cambiar de stack: cuando el proyecto migra de Java 11 a Java 21, las reglas deben reflejarlo.
• Subir secretos en las instrucciones: nunca incluyas API keys, contraseñas o tokens en estos archivos, ya que quedan en el historial de Git.
• Olvidar verificar el resultado: las instrucciones orientan al modelo, pero no garantizan perfección; siempre revisa el código generado.

Mejores prácticas en equipos

Para sacar el máximo partido en entornos colaborativos:

• Revisar las copilot-instructions.md como parte del ciclo normal de pull requests.
• Enlazar el archivo desde el README.md para que sea fácil de encontrar por los nuevos miembros.
• Mantener una carpeta .github/prompts/ con plantillas para tareas habituales (nuevo controlador, nuevo test, nuevo endpoint).
• Evaluar periódicamente la calidad del código generado y ajustar las instrucciones según los hallazgos.
• Documentar en el wiki interno los casos en los que Copilot ha funcionado especialmente bien y aquellos en los que no, para ir afinando las reglas con evidencia real.