GitHub Copilot está redefiniendo la forma en que los desarrolladores escriben código, actuando como un agente de codificación inteligente directamente en tu editor. Ya sea que estés construyendo aplicaciones web ASP.NET, trabajando con C# o revisando código con tu equipo, Copilot puede automatizar tareas repetitivas, sugerir funciones completas y optimizar las revisiones de código. Esta guía explora consejos de productividad, ejemplos prácticos y mejores prácticas para configurar archivos de instrucción y archivos de prompt en Visual Studio, VS Code y GitHub.com, facilitando a los desarrolladores .NET el aprovechamiento de todo su potencial.
Archivos de Instrucción: Guiando a Copilot a Nivel de Repositorio
¿Te gustaría que Copilot conociera más sobre tu solución y tus preferencias de codificación? Los archivos de instrucción están diseñados para eso. Estos archivos, comúnmente llamados copilot-instructions.md, definen las reglas, estándares de codificación o directrices que Copilot debe seguir al generar código en tu repositorio o espacio de trabajo. Puedes crear un archivo genérico para todas las solicitudes o archivos específicos para ciertos escenarios (nombre.instructions.md) que se aplican solo a solicitudes relevantes.
¿Cuándo usar archivos de instrucción?
- Proyectos en equipo: Aseguran que el código sugerido por Copilot se alinee con los estándares y convenciones de nomenclatura de tu organización, manteniendo la coherencia.
- Repositorios de código abierto: Son ideales para que los colaboradores se adhieran automáticamente a las reglas específicas del proyecto, incluso si son nuevos en él.
¿Cómo usar archivos de instrucción?
Puedes escribir tu archivo de instrucciones desde cero, usar una plantilla de muestra o incluso con la ayuda del propio Copilot. El archivo copilot-instructions.md debe colocarse en la carpeta .github de tu espacio de trabajo. Si deseas instrucciones específicas para un tipo de archivo (como .cs o .razor), colócalas en la carpeta .github/instructions. Copilot incluirá automáticamente los archivos de instrucción apropiados con cada solicitud enviada a través del chat, asegurando que siempre opere bajo el contexto definido.
¿Qué incluir en los archivos de instrucción?
Para maximizar la utilidad de tus archivos de instrucción, es crucial incluir detalles precisos sobre tu proyecto y tus expectativas. Aquí te detallamos los elementos clave:
- Propósito y Alcance: Una breve declaración de una frase que describa el control del archivo (ej., “Guía a los asistentes automatizados sobre ediciones seguras del repositorio y convenciones para la interfaz de usuario Blazor”).
- Reglas de Ubicación y Alcance: Especifica dónde se aplica el archivo (rutas, lenguajes, file globs) y cualquier caso en el que NO se aplique. Esto ayuda a Copilot a entender su contexto operativo.
- Visión General del Proyecto: Una breve descripción de la intención del proyecto (audiencia, características principales, tiempo de ejecución/plataforma). Esto proporciona a Copilot una comprensión fundamental del dominio.
- Herramientas y Versiones: Detalla los comandos y versiones exactas de las herramientas (ej., .NET 8.0, ejemplos de comandos dotnet, Node, Python, SDKs) para asegurar la compatibilidad y el entorno de desarrollo correcto.
- Comandos de Construcción / Ejecución / Prueba: Proporciona comandos mínimos y copiables para desarrollo y CI (ejemplos amigables con PowerShell en Windows), vitales para que Copilot entienda cómo validar los cambios.
- Convenciones de Codificación y Linting: Define el formateador (ej., dotnet format, prettier), reglas de estilo, patrones de nomenclatura y la “Fuente Única de Verdad” para el estilo, garantizando la consistencia del código.
- Contratos API y de Datos: Incluye ejemplos de estructuras JSON, DTOs, esquemas de bases de datos o campos importantes (evitando secretos) para que Copilot comprenda la interacción de datos.
- Expectativas de Pruebas y E2E: Especifica qué pruebas deben pasar antes de que se acepten los cambios, crucial para mantener la calidad del código.
- Reglas de CI/CD y Lanzamiento: Describe el modelo de ramificación, verificaciones requeridas, política de versionado y restricciones de despliegue, guiando a Copilot en el ciclo de vida del software.
- Política de Seguridad y Secretos: Clarifica lo que nunca debe ser comprometido, la nomenclatura de variables de entorno y la orientación sobre el almacenamiento de secretos, fundamental para la seguridad.
- Ediciones Permitidas y Tolerancia al Riesgo: Define qué puede cambiar el asistente de forma autónoma (correcciones tipográficas, formato, pruebas) frente a lo que requiere revisión/PR (cambios de esquema, migraciones de DB, infraestructura), gestionando las expectativas.
- Formato de Salida y Diferencias: Establece cómo presentar los cambios de código (formato de parche, ediciones de archivo único vs. múltiples), estilo del mensaje de commit y plantilla de descripción de PR, estandarizando las contribuciones.
- Comportamiento y Tono: Indica la personalidad preferida del asistente (conciso, conservador, primero las pruebas), verbosidad y sobre qué preguntar al humano, personalizando la interacción.
- Fallos y Reversión: Instrucciones sobre cómo manejar fallos de compilación o pruebas, pasos para revertir y a quién notificar, para una gestión efectiva de errores.
- Ejemplos y Fragmentos: Proporciona buenos ejemplos de PRs pequeños aceptados y cambios no permitidos, ofreciendo una referencia clara.
- Notas de Mantenimiento: Indica dónde y con qué frecuencia actualizar esta documentación, asegurando que se mantenga relevante.
Para más ejemplos de archivos de instrucción, puedes consultar la gran cantidad de ejemplos enviados por la comunidad en awesome-copilot/instructions.
Archivos de Prompt: Contexto Específico para Sesiones de Codificación
¿Utilizas Copilot para realizar tareas similares en tu repositorio? ¿Deseas que Copilot sepa mejor qué se le permite cambiar y qué no? Los archivos de prompt son la solución. Estos archivos proporcionan un contexto detallado para Copilot en una sesión de codificación específica o para un archivo en particular. Se pueden añadir como contexto o como archivos de prompt dedicados para dirigir la salida de la IA para una tarea determinada, permitiendo una personalización granular del comportamiento de Copilot.
¿Cuándo usar archivos de prompt?
- Requisitos específicos: Son ideales cuando necesitas que Copilot genere código siguiendo requisitos muy específicos, como algoritmos personalizados, integraciones complejas o necesidades de cumplimiento normativo.
- Prototipado y documentación: Perfectos para fases de prototipado rápido, generación de documentación o para incorporar a nuevos miembros del equipo que necesitan una guía explícita y detallada en tareas particulares.
¿Cómo usar archivos de prompt?
Al igual que con los archivos de instrucción, puedes escribir el prompt desde cero, usando una muestra o con la asistencia de Copilot. Debes colocarlo en la carpeta .github/prompts de tu espacio de trabajo, siguiendo el formato de nombre de archivo [nombre_prompt].prompt.md (por ejemplo, CrearAnalizador.prompt.md). Para invocar un prompt, en VS Code, escribe /[nombre_prompt] en el chat, y en Visual Studio, usa #[nombre_prompt]. Por ejemplo, para crear un analizador que detecte técnicas de hashing débiles, podrías escribir “/CrearAnalizador detectar el uso de MD5.Create(), SHA1.Create(), RijndaelManaged con modos inseguros, new HMACSHA1(), o TripleDES y sugerir el uso de SHA256 o RandomNumberGenerator y apuntar a envoltorios de biblioteca”.
¿Qué incluir en los archivos de prompt?
Para que tus archivos de prompt sean lo más efectivos posible, considera la siguiente estructura:
- Encabezado / Metadatos: Incluye nombre, versión, última actualización y contacto del autor/mantenedor. También especifica los scope globs (qué rutas/lenguajes/componentes controla el prompt) para definir su aplicabilidad.
- Propósito / Resumen de una línea: Una declaración concisa de la intención del prompt (qué permite hacer al asistente), para una rápida comprensión.
- Persona y Tono: Define cómo debe comunicarse el asistente (conciso, conservador, haciendo preguntas aclaratorias), personalizando la experiencia.
- Acciones Autónomas Permitidas: Una lista precisa de lo que el asistente puede hacer sin intervención humana (correcciones tipográficas, actualizaciones de documentación, refactorizaciones de archivo único con pruebas, formato). Incluye límites (ej., número máximo de archivos cambiados, no cambios de infraestructura).
- Acciones No Permitidas / Requieren Revisión Humana: Enumera explícitamente los cambios que requieren revisión humana, como esquemas/migraciones de DB, secretos, configuración de producción, refactorizaciones grandes o actualizaciones importantes de dependencias.
- Comandos de Construcción / Ejecución / Prueba: Los comandos exactos y notas de entorno (ejemplos de PowerShell para espacios de trabajo de Windows). Incluye los comandos mínimos de smoke-check que el asistente debe ejecutar localmente antes de proponer un cambio.
- Comandos de Lint/Formato: Las herramientas y su invocación (ej., dotnet format, prettier –check), para asegurar la consistencia del estilo.
- Reglas de CI y Criterios de Aceptación de PR: Qué verificaciones deben pasar, etiquetas requeridas, pruebas a ejecutar y plantilla de título/cuerpo de PR, estandarizando el proceso de contribución.
- Excepciones de Archivos y Rutas: Una lista de archivos binarios, generados o de terceros que no deben ser modificados por el asistente.
- Formato de Salida y Convenciones de Parches: El formato de parche/PR, estilo del mensaje de commit y evidencia de pruebas a incluir, para mantener la coherencia.
- Manejo de Errores y Reversión: Qué hacer si las pruebas fallan, cómo revertir y a quién notificar, para una gestión robusta de problemas.
- Ejemplos: 2-3 ejemplos cortos de ediciones “buenas” y “malas” que el asistente podría realizar, proporcionando una guía práctica.
- Fragmento Mínimo Listo para Máquina (opcional): Un fragmento YAML o front-matter con apply-to globs, versiones de SDK para que la automatización pueda analizarlo.
- Notas de Mantenimiento: Quién actualiza este archivo y cuándo aumentar la versión, para asegurar su relevancia y precisión.
Para ejemplos de archivos de prompt, puedes consultar los muchos ejemplos enviados por la comunidad en awesome-copilot/prompts.
Eligiendo entre Archivos de Instrucción y Prompt
La elección entre archivos de instrucción y prompt depende del alcance y la especificidad que necesites:
- Archivos de Instrucción: Son ideales para una guía a nivel de repositorio y estándares a largo plazo que abarcan a múltiples colaboradores y proyectos. Establecen la base para la consistencia.
- Archivos de Prompt: Son mejores para una guía local, basada en sesiones, o para una funcionalidad específica dentro de un solo archivo o segmento de código. Permiten una dirección más puntual.
- Combinación Óptima: Para obtener los mejores resultados, utiliza archivos de instrucción para la guía general de tu proyecto y complétalos con archivos de prompt en áreas que requieran una claridad o especificidad adicional.
Mejores Prácticas: Escritura Efectiva de Prompts y Colaboración
Para maximizar la eficiencia de GitHub Copilot, considera las siguientes mejores prácticas:
- Sé específico: Tanto con los prompts como con las instrucciones; la claridad produce mejores sugerencias y resultados más precisos.
- Revisa el código generado: Siempre revisa todo el código generado por la IA para asegurar su precisión, seguridad y cumplimiento con los estándares del proyecto.
- Uso estratégico: Emplea archivos de instrucción para la consistencia general y archivos de prompt para una guía dirigida a tareas específicas.
- Consulta la documentación: Explora la documentación oficial en “Personaliza el chat a tu flujo de trabajo” para profundizar en las opciones de configuración.
- Colabora: Comparte las salidas de Copilot en las revisiones de código para fomentar la mejora colaborativa y aprender de las experiencias de otros.
Conclusión: Experimenta, Guía y Colabora con Copilot
GitHub Copilot tiene el potencial de impulsar tus proyectos .NET cuando se guía con instrucciones y prompts claros. Al explorar las múltiples formas en que Copilot puede ayudarte a lograr más, maximizarás tanto la productividad como la calidad del código. Te animamos a explorar, refinar y compartir tus experiencias con Copilot con la comunidad de desarrolladores. ¡El futuro del desarrollo .NET es más inteligente con Copilot a tu lado!
