¡Dale Superpoderes a Copilot! 5 Tips para Instrucciones Personalizadas Asombrosas

GitHub Copilot es una herramienta poderosa, pero como cualquier asistente, ¡necesita instrucciones claras! Si quieres sacarle el máximo provecho y evitar frustraciones, aprende a crear instrucciones personalizadas que le den el contexto necesario para entender tus proyectos. En este artículo, te traemos 5 tips esenciales (¡y un bonus!) para que tus instrucciones sean impecables.

¿Por qué son importantes las instrucciones personalizadas?

Imagina un nuevo miembro en tu equipo: no conoce los entresijos del proyecto, las convenciones de código ni la estructura del repositorio. Copilot es similar. Las instrucciones personalizadas, a través del archivo copilot-instructions.md, le proporcionan ese conocimiento esencial que necesita para ofrecerte sugerencias relevantes y precisas.

Antes de Empezar: No te Compliques Demasiado

El autor original del artículo recalca un punto clave: ¡no te paralices buscando la perfección! La IA generativa es probabilística, lo que significa que incluso con las mismas instrucciones, los resultados pueden variar. El objetivo es *orientar* a Copilot hacia la respuesta deseada la mayor parte del tiempo. Piensa en estas recomendaciones como un punto de partida, no como reglas inamovibles. Experimenta y adapta según tus proyectos y tu experiencia con Copilot.

Los 5 Tips Esenciales para Instrucciones de Copilot

1. Dale a GitHub Copilot una Visión General del Proyecto

Comienza por definir el _qué_. ¿Qué hace tu aplicación? ¿Quién es la audiencia? ¿Cuáles son las características clave? Un breve párrafo a modo de “elevator pitch” será suficiente. Por ejemplo:

# Contoso Companions

Este es un sitio web para apoyar a las agencias de adopción de mascotas. Las agencias se incorporan a la aplicación, donde pueden administrar sus ubicaciones, mascotas disponibles y publicitar eventos. Los posibles adoptantes pueden buscar mascotas disponibles en su área, descubrir agencias y enviar solicitudes de adopción.

2. Identifica la Pila Tecnológica que Estás Usando

Especifica el _cómo_. Enumera las tecnologías de backend y frontend, las APIs que utilizas y los frameworks de testing. No es necesario entrar en detalles exhaustivos, pero sí proporcionar una visión general clara. Por ejemplo:

## Pila tecnológica en uso

### Backend

- Flask se utiliza para la API
- Los datos se almacenan en Postgres, con SQLAlchemy como ORM
  - Hay bases de datos separadas para desarrollo, staging y producción
  - Para las pruebas end-to-end, se crea y rellena una nueva base de datos,
    y luego se elimina después de que se completan las pruebas

### Frontend

- Astro gestiona el sitio principal y el enrutamiento
- Svelte se utiliza para la interactividad
- TypeScript se utiliza para todo el código front-end

### Testing

- Unittest para Python
- Vitest para TypeScript
- Playwright para pruebas e2e

3. Detalla tus Guías de Estilo de Codificación

Define los _estándares_. ¿Usas punto y coma en JavaScript/TypeScript? ¿Type hints en Python? ¿Tabulaciones o espacios? Estas convenciones son cruciales para mantener la coherencia del código. Puedes incluir estas guías en la sección de la pila tecnológica o crear una sección separada. Por ejemplo:

## Guías de proyecto y código

- Siempre use sugerencias de tipo en cualquier idioma que las admita
- JavaScript/TypeScript debe usar punto y coma
- Se requieren pruebas unitarias y deben aprobarse antes de la PR
  - Las pruebas unitarias deben centrarse en la funcionalidad principal
- Se requieren pruebas de extremo a extremo
  - Las pruebas de extremo a extremo deben centrarse en la funcionalidad principal
  - Las pruebas de extremo a extremo deben validar la accesibilidad
- Siempre siga las buenas prácticas de seguridad
- Siga los principios de diseño de API RESTful
- Utilice scripts para realizar acciones cuando estén disponibles

4. Explica la Estructura de tu Proyecto

Describe la _organización_. Indica dónde se encuentra el código del backend, el frontend, los tests, etc. Esto ayudará a Copilot a navegar por el repositorio y a entender la relación entre los diferentes componentes. Por ejemplo:

## Estructura del proyecto

- server/ : Código backend de Flask
  - models/ : Modelos SQLAlchemy ORM
  - routes/ : Puntos finales de la API organizados por recurso
  - tests/ : Pruebas unitarias para la API
  - utils/ : Funciones de utilidad y helpers, incluidas las llamadas a la base de datos
- client/ : Código frontend de Astro/Svelte
  - src/components/ : Componentes Svelte reutilizables
  - src/layouts/ : Plantillas de diseño de Astro
  - src/pages/ : Páginas y rutas de Astro
  - src/styles/ : Hojas de estilo CSS
- scripts/ : Scripts de desarrollo, implementación y prueba
- docs/ : Documentación del proyecto que se mantendrá sincronizada en todo momento

5. Indica a GitHub Copilot los Recursos Disponibles

Muestra las _herramientas_. Enumera los scripts, las utilidades y otros recursos que pueden facilitar el desarrollo. Esto puede incluir scripts para configurar el entorno, ejecutar tests o generar código. Por ejemplo:

## Recursos

- scripts folder
  - start-app.sh : Instala todas las bibliotecas e inicia la aplicación
  - setup-env.sh : Instala todas las bibliotecas
  - test-project.sh : Instala todas las bibliotecas, ejecuta pruebas unitarias y e2e
- Servidores MCP
  - Playwright: Se utiliza para generar pruebas de Playwright o interactuar con el sitio
  - GitHub: Se utiliza para interactuar con el repositorio y el backlog

Bonus Tip: ¡Usa GitHub Copilot para Crear tus Instrucciones!

Si te sientes bloqueado, ¡pídele ayuda a Copilot! Puedes usar el modo agente en tu IDE o asignar un issue a Copilot en tu repositorio de GitHub para que genere el archivo copilot-instructions.md. Puedes usar el resultado tal cual o editarlo a tu gusto. Aquí tienes un ejemplo de *prompt* que puedes utilizar:

Tu tarea es "incorporar" este repositorio a un agente de codificación agregando un archivo .github/copilot-instructions.md. Debe contener información que describa cómo el agente, al ver el repositorio por primera vez, puede trabajar de manera más eficiente.

Realizará esta tarea solo una vez por repositorio, y hacer un buen trabajo puede MEJORAR SIGNIFICATIVAMENTE la calidad del trabajo del agente, así que tómese su tiempo, piense cuidadosamente y busque a fondo antes de escribir las instrucciones.

## Metas

- Documentar la estructura del proyecto y la pila tecnológica existentes.
- Asegurarse de que se sigan las prácticas establecidas.
- Minimizar los comandos bash y los fallos de compilación.

## Limitaciones
- Las instrucciones no deben tener más de 2 páginas.
- Las instrucciones deben ser ampliamente aplicables a todo el proyecto.

## Orientación

Asegúrese de incluir lo siguiente:

- Un resumen de lo que hace la aplicación.
- La pila tecnológica en uso
- Guías de codificación
- Estructura del proyecto
- Herramientas y recursos existentes

## Pasos a seguir

- Realice un inventario exhaustivo de la base de código. Buscar y ver:
  - README.md, CONTRIBUTING.md y todos los demás archivos de documentación.
  - Buscar en la base de código indicaciones de soluciones alternativas como 'HACK', 'TODO', etc.
- Todos los scripts, en particular los relacionados con la configuración de la compilación y el repositorio o el entorno.
- Todos los archivos del proyecto.
- Todos los archivos de configuración y linting.
- Documente cualquier otro paso o información que el agente pueda utilizar para reducir el tiempo dedicado a explorar o intentar y no ejecutar comandos bash.

## Validación

Utilice el archivo de instrucciones recién creado para implementar una característica de muestra. Utilice las enseñanzas de cualquier fallo o error en la construcción de la nueva característica para refinar aún más el archivo de instrucciones.

Conclusión: Instrucciones, la Clave para un Copilot Eficaz

Un buen archivo copilot-instructions.md es fundamental para obtener el máximo rendimiento de GitHub Copilot. No tiene que ser perfecto, pero sí claro, conciso y actualizado. Comienza con estos cinco elementos clave, y verás cómo Copilot se convierte en un asistente mucho más valioso: