GitHub Copilot: un archivo en el repo rinde más que cualquier prompt
GitHub Copilot lee un archivo de instrucciones en el repositorio en cada petición. Bien escrito, rinde más que cualquier truco de redacción de prompts.
Lo que se repite sobre cómo sacar mejor código de GitHub Copilot suele ser consejo de redacción: sé específico, dale contexto, pídele que razone paso a paso. Se agota pronto, y por una razón estructural: una frase mejor redactada solo pide al modelo que se esfuerce más, no le cuenta nada nuevo. Lo que mueve la aguja es un archivo versionado en el repositorio.
Se llama .github/copilot-instructions.md. La ruta importa: va dentro del directorio .github, no en la raíz. Markdown plano, sin frontmatter. Esa es toda la instalación, y se lee en cada petición.
Qué hace que una regla funcione
Compara dos formas de decir lo mismo. Una: "usa un manejo de errores adecuado". Otra: "el dinero es Decimal, nunca float; redondeo al alza a dos decimales solo en el límite de la respuesta, jamás a mitad de cálculo". La primera cuesta contexto en cada petición y no cambia nada, porque el modelo ya está de acuerdo con ella, y estar de acuerdo no es saber qué querías decir. La segunda cambia la salida porque contiene un dato que el modelo no tenía.
Una regla útil cumple tres propiedades. Duradera: sigue siendo cierta el mes que viene; lo que tiene forma de tarea va en el prompt, no aquí. Específica: datetime.utcnow() devuelve un datetime naive, no "gestiona bien las zonas horarias". Comprobable: alguien mira un diff y dice si se cumplió.
Las prohibiciones se siguen mejor que las aspiraciones. "No uses datetime.utcnow(); devuelve un naive y este código compara contra aware" se cumple. "Usa datetimes con zona horaria" se acepta y luego no se hace. La primera nombra lo concreto que hay que evitar y por qué, y con el motivo la regla sobrevive a una situación que no anticipaste.
Y corto gana a exhaustivo. Ocho reglas que se siguen valen más que cuarenta que se diluyen: el archivo se antepone a cada petición, así que 400 líneas son un impuesto en cada interacción. Si solo conservas cinco, quédate con las no obvias y borra lo que ya vigila una herramienta. Si el linter rompe el build por el orden de los imports, no gastes una línea en el orden de los imports.
También para infraestructura
El patrón funciona fuera del código de aplicación, y en infraestructura rinde más porque los errores salen caros. En Terraform: for_each para colecciones y count solo para condicionales, porque count es posicional y borrar el segundo de tres elementos destruye el tercero. En Kubernetes: requests y limits en todos los contenedores, tres sondas apuntando a endpoints distintos, e imágenes fijadas por digest.
En GitHub Actions: no interpolar nada de github.event dentro de un bloque run:, pasarlo por env:, y fijar las acciones de terceros a un SHA de commit completo. Cada una tapa una clase de defecto que la revisión no ve, porque la versión incorrecta es idéntica a la correcta a simple vista.
Queda el detalle que casi nadie menciona: el archivo se commitea y se revisa como código, lo que convierte una preferencia personal en algo que el equipo aprobó, con historial y cambios por pull request.
Para empezar no hace falta más: escribe tres reglas sobre tu repositorio que un recién llegado competente incumpliría en su primera semana, ni estilo ni nada que pille el linter. Las instrucciones completas, con archivos por ruta y el orden de precedencia cuando aplican varios, están en la documentación de instrucciones personalizadas de Copilot.
