Instrucciones personalizadas para Copilot

Instrucciones globales del proyecto

GitHub Copilot permite definir instrucciones personalizadas que condicionan el comportamiento de la IA para que siga las convenciones, el estilo de código y las reglas específicas del proyecto. Estas instrucciones se aplican automáticamente a todas las interacciones con Copilot, tanto en el completado de código como en las respuestas del chat.

La forma principal de definir instrucciones de proyecto es mediante el archivo .github/copilot-instructions.md en la raíz del repositorio. Copilot lee este archivo y lo utiliza como contexto adicional en cada consulta.

<!-- .github/copilot-instructions.md -->

# Instrucciones del proyecto

- Usa TypeScript estricto con tipos explícitos, nunca `any`.
- Sigue el patrón Repository para acceso a datos.
- Los nombres de variables y funciones deben estar en camelCase.
- Los componentes React deben ser funcionales, nunca de clase.
- Usa Tailwind CSS para estilos, no CSS en línea ni módulos CSS.
- Los tests se escriben con Vitest, no con Jest.
- Todas las funciones asíncronas deben manejar errores con try/catch.

Cuando se pide a Copilot que genere código o responda una pregunta técnica, estas instrucciones influyen en el resultado. Si las instrucciones indican usar TypeScript estricto, Copilot evitará sugerir any y añadirá tipos explícitos en sus propuestas.

El archivo copilot-instructions.md se incluye en el control de versiones del proyecto. Esto garantiza que todos los miembros del equipo compartan las mismas instrucciones y que Copilot se comporte de forma consistente en todos los entornos.

Buenas prácticas para las instrucciones

Las instrucciones deben ser concisas y específicas. Copilot procesa mejor las indicaciones directas que los párrafos extensos:

• Usar listas con viñetas, una instrucción por línea
• Indicar tecnologías y versiones concretas
• Especificar patrones de diseño preferidos
• Mencionar convenciones de nombrado y formato
• Listar herramientas y bibliotecas aprobadas

Instrucciones demasiado vagas como "escribe buen código" no aportan valor. En cambio, "utiliza el patrón Result para manejo de errores en lugar de excepciones" es una instrucción que Copilot puede aplicar de forma concreta.

Instrucciones desde settings de VS Code

Instrucciones para el chat

Además del archivo de proyecto, se pueden definir instrucciones en la configuración de usuario de VS Code que afectan a las respuestas del chat de Copilot. Estas instrucciones son personales y no se comparten con el equipo:

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "Siempre incluye comentarios JSDoc en las funciones públicas."
    },
    {
      "text": "Prefiere funciones puras sobre funciones con efectos secundarios."
    }
  ]
}

Las instrucciones de settings se combinan con las del archivo .github/copilot-instructions.md. Si ambas existen, Copilot tiene en cuenta las dos fuentes.

Instrucciones para completado de código

Las instrucciones que afectan al completado inline (las sugerencias grises que aparecen mientras se escribe) se configuran con otra clave:

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "Usa async/await en lugar de .then() para promesas."
    }
  ]
}

Estas instrucciones se aplican de forma transparente cada vez que Copilot sugiere código, sin necesidad de interactuar con el chat.

Archivos de prompt reutilizables

Crear prompt files (.prompt.md)

Los prompt files son archivos Markdown con extensión .prompt.md que definen tareas reutilizables para Copilot. A diferencia de las instrucciones globales, los prompt files se invocan manualmente cuando se necesitan y permiten definir flujos de trabajo específicos.

Los archivos se almacenan en la carpeta .github/prompts/ del proyecto:

<!-- .github/prompts/crear-componente.prompt.md -->

Crea un componente React funcional con las siguientes características:
- Usa TypeScript con props tipadas en una interfaz separada
- Incluye un archivo de test con Vitest
- Exporta el componente como named export
- Aplica estilos con Tailwind CSS
- Incluye JSDoc con descripción y parámetros

Para usar un prompt file, se abre el chat de Copilot y se referencia con la sintaxis #:

#crear-componente UserProfile con props name, email y avatar

Copilot combina las instrucciones del prompt file con el contexto adicional que se proporciona en el mensaje.

Referenciar archivos de contexto

Los prompt files admiten variables que referencian archivos del proyecto como contexto adicional. Esto permite que Copilot analice archivos existentes antes de generar código:

<!-- .github/prompts/nuevo-endpoint.prompt.md -->

Crea un nuevo endpoint REST siguiendo el patrón establecido en:
- #file:src/controllers/userController.ts
- #file:src/services/userService.ts
- #file:src/routes/userRoutes.ts

El nuevo endpoint debe seguir exactamente la misma estructura, 
convenciones de nombrado y manejo de errores.

Al invocar este prompt, Copilot lee los archivos referenciados y usa su contenido para generar código coherente con el patrón existente.

Los prompt files transforman instrucciones que habitualmente se escriben a mano en el chat en plantillas compartidas que todo el equipo puede usar de forma consistente.

Organización de prompt files

Un proyecto puede contener múltiples prompt files organizados por tipo de tarea:

.github/
  copilot-instructions.md
  prompts/
    crear-componente.prompt.md
    crear-test.prompt.md
    crear-endpoint.prompt.md
    revisar-codigo.prompt.md
    documentar-funcion.prompt.md

Cada archivo define una tarea concreta, lo que permite estandarizar las peticiones al asistente de IA y obtener resultados más predecibles y alineados con las convenciones del proyecto.

Prioridad de las instrucciones

Cuando existen instrucciones en múltiples ubicaciones, Copilot las combina siguiendo un orden de prioridad. Las instrucciones del archivo .github/copilot-instructions.md se aplican como contexto base. Las instrucciones de los settings de VS Code se añaden como capa adicional. Y las instrucciones proporcionadas directamente en el mensaje del chat tienen la mayor prioridad, pudiendo sobrescribir las anteriores para una consulta concreta.