GitHub Copilot Instructions: cómo configurar reglas permanentes para tus proyectos
Aprende a personalizar
GitHub Copilot
mediante instrucciones permanentes:
.github/copilot-instructions.md,
reglas específicas por archivo
con .instructions.md,
AGENTS.md,
instrucciones personales,
reglas para monorepos,
Copilot CLI,
Agent Mode,
Cloud Agent
y Code Review.
¿Qué son las instrucciones personalizadas de GitHub Copilot?
Las GitHub Copilot custom instructions son reglas y contexto que Copilot incorpora automáticamente a sus solicitudes. Sirven para indicarle qué tecnologías utiliza el proyecto, qué arquitectura debe respetar, cómo ejecutar tests, qué convenciones seguir, qué prácticas de seguridad aplicar y qué comportamientos evitar, sin repetir esas reglas en cada prompt.
Qué tipo de instrucciones deberías utilizar
Repository-wide
Reglas generales para todo el repositorio.
.github/copilot-instructions.md
Path-specific
Reglas que solo aplican a determinados archivos.
.github/instructions/
Agent instructions
Contexto portable para agentes de programación.
AGENTS.md
Del prompt repetitivo a un repositorio preparado para agentes
Tecnología
PHP, JavaScript, frameworks y versiones.
Reglas
Arquitectura, seguridad y convenciones.
Verificación
Tests, lint, typecheck y build.
Ejecución
Copilot recibe estas reglas automáticamente.
Por qué no deberías explicar tu proyecto en cada prompt
Contexto repetido
Cada conversación necesita volver a explicar arquitectura, tests y convenciones.
Contexto persistente
Copilot conoce las reglas desde el comienzo de la tarea.
Esto reduce correcciones repetidas y ayuda a que Chat, Agent Mode, CLI, Cloud Agent y Code Review produzcan resultados más consistentes.
Cómo crear .github/copilot-instructions.md
Crea el siguiente archivo en la raíz del repositorio:
mi-proyecto/
│
├── .github/
│ └── copilot-instructions.md
│
├── src/
├── tests/
└── README.mdLas instrucciones se escriben en Markdown utilizando lenguaje natural.
Plantilla de copilot-instructions.md
# Project
This project uses:
- PHP 8.2+
- MySQL
- Vanilla JavaScript
- Composer
- PHPUnit
# Architecture
Follow the existing architecture.
Before creating a new abstraction,
search for an existing implementation.
Avoid unrelated refactors.
# Compatibility
Preserve:
- public APIs
- database schema compatibility
- existing hooks
- backwards compatibility
# Security
For untrusted input:
- validate
- sanitize
- escape output
Use prepared SQL statements.
Never expose or commit secrets.
# Testing
Before finishing:
1. run relevant tests
2. run lint
3. run typecheck if available
4. inspect git diff
# Final response
Report:
- files changed
- tests executed
- result
- anything not verifiedQué deberías guardar en las instrucciones generales
Stack
Lenguajes, frameworks y versiones.
Arquitectura
Patrones y límites importantes.
Convenciones
Reglas no obvias del equipo.
Seguridad
Controles mínimos obligatorios.
Tests
Cómo verificar una modificación.
Restricciones
Qué no debe cambiar el agente.
No conviertas copilot-instructions.md en una enciclopedia
Las instrucciones se incorporan al contexto de la IA. Si añades demasiada información, aumentas ruido y consumo de contexto.
| Evita | Prefiere |
|---|---|
| Documentar todo el proyecto | Reglas que cambian decisiones |
| Explicar sintaxis básica | Convenciones propias |
| Copiar todo el README | Referenciar documentación útil |
| Reglas cosméticas ya cubiertas por lint | Restricciones arquitectónicas |
| Instrucciones ambiguas | Reglas observables |
“Escribe código bueno” aporta poco. “No introduzcas una segunda capa ORM porque el proyecto utiliza PDO directamente” cambia una decisión real.
Crear instrucciones diferentes según el tipo de archivo
Guarda estos archivos dentro de:
.github/
└── instructions/
├── php.instructions.md
├── javascript.instructions.md
├── tests.instructions.md
└── docs.instructions.mdAplicar reglas mediante patrones glob
El frontmatter
puede utilizar
applyTo
para indicar
qué archivos
activan
la instrucción.
---
name: PHP Standards
description: Rules for PHP files
applyTo: "**/*.php"
---
# PHP rules
- Target PHP 8.2+
- Use strict comparisons
- Validate external input
- Use prepared SQL
- Preserve public hooks
- Run PHP syntax checksAplicar una regla a múltiples extensiones
---
applyTo: "**/*.js,**/*.ts,**/*.tsx"
---
# JavaScript / TypeScript
- Prefer existing utilities
- Avoid global state
- Preserve public interfaces
- Validate API responses
- Add tests for behavioral changesAun puede adjuntarse manualmente en clientes compatibles.
Ejemplo de instrucciones específicas para pruebas
---
name: Test Standards
applyTo: "**/tests/**,**/*Test.php"
---
When adding tests:
- reproduce the bug first
- prefer behavior-oriented assertions
- avoid testing private implementation details
- cover the regression
- keep fixtures minimal
- reuse existing factories
After modifying tests:
run the smallest relevant test suite first.Usar instrucciones portables para múltiples agentes
GitHub Copilot
también reconoce
AGENTS.md
como fuente
de instrucciones
para agentes.
project/
│
├── AGENTS.md
├── .github/
│ └── copilot-instructions.md
│
├── backend/
└── frontend/AGENTS.md es especialmente útil cuando utilizas varios agentes de programación sobre el mismo repositorio. Puedes mantener reglas generales de ingeniería en un formato que no esté ligado exclusivamente a GitHub Copilot.
AGENTS.md vs copilot-instructions.md
| Característica | copilot-instructions.md | AGENTS.md |
|---|---|---|
| GitHub Copilot | Sí | Sí |
| Repository-wide | Sí | Sí |
| Orientado específicamente a Copilot | Sí | No exclusivamente |
| Portable entre agentes compatibles | Menos | Sí |
| Anidamiento por directorio | No | Sí, según cliente |
Puedes mantener
reglas Copilot-specific
en
.github/copilot-instructions.md
y reglas
generales
para agentes
en
AGENTS.md.
Evita duplicar
o contradecir
las mismas reglas.
Utilizar varios AGENTS.md según directorio
monorepo/
│
├── AGENTS.md
│
├── apps/
│ └── web/
│ └── AGENTS.md
│
└── services/
└── api/
└── AGENTS.mdEsto permite mantener reglas generales en la raíz y añadir instrucciones más específicas para determinadas partes del repositorio.
La configuración
chat.useNestedAgentsMdFiles
controla
actualmente
su detección
en subdirectorios
y está desactivada
por defecto.
Cómo administra VS Code las instrucciones
El VS Code actual dispone de un Agent Customizations editor desde donde puedes descubrir, crear y administrar:
Instructions.
Agent Skills.
Custom Agents.
Hooks.
Desde la Command Palette puedes abrir:
Chat: Open CustomizationsCrear instrucciones con ayuda de Copilot
VS Code puede analizar el proyecto y generar instrucciones iniciales mediante:
/initPara una regla más específica:
/create-instructions
Create instructions
for PHP files.
Follow the security,
architecture
and testing conventions
already used
in this repository.Revisa que reflejen el proyecto real y elimina supuestos inventados por el modelo.
Las Custom Instructions no controlan directamente el autocompletado inline
En VS Code, las instrucciones personalizadas se utilizan para Chat y workflows agentic, pero no se aplican directamente a las sugerencias inline que aparecen mientras escribes código.
Si necesitas reglas estrictas sobre formato, utiliza también:
Linters.
Formatters.
Tests.
CI/CD.
Qué instrucciones carga GitHub Copilot CLI
Copilot CLI puede combinar instrucciones procedentes de varias fuentes:
AGENTS.md
CLAUDE.md
GEMINI.md
.github/copilot-instructions.md
.github/instructions/**/*.instructions.md
~/.copilot/copilot-instructions.md
~/.copilot/instructions/**/*.instructions.mdNo existe una regla universal de precedencia para resolver contradicciones entre todas estas fuentes. La mejor práctica es evitar instrucciones incompatibles.
Crear reglas personales para todos tus proyectos en Copilot CLI
Utiliza:
~/.copilot/copilot-instructions.mdEjemplo:
# Personal preferences
- Explain the root cause before editing
- Prefer minimal changes
- Never hide failing tests
- Do not claim verification without running it
- Report commands executed
- Report remaining uncertaintyLas reglas del repositorio deberían pertenecer al repositorio. Las preferencias sobre cómo quieres trabajar deberían vivir en tu configuración personal.
Comprobar qué instrucciones cargó Copilot CLI
/instructionsTambién puedes usar:
copilot instruction list
copilot instruction list --jsonEsto resulta especialmente útil cuando una regla parece no estar aplicándose.
Importar otras instrucciones mediante @path
En Copilot CLI, algunos archivos de instrucciones permiten incluir contenido de otros archivos.
# AGENTS.md
@docs/architecture.md
@docs/testing.md
# Agent rules
- preserve public APIs
- run relevant tests
- report unverified behaviorCopilot CLI resuelve estas referencias de forma recursiva con límites de profundidad y tamaño.
El soporte de importación depende del tipo de archivo y del cliente utilizado.
Compartir instrucciones entre varios repositorios
Las organizaciones con planes compatibles pueden definir instrucciones a nivel organizacional.
Organization
│
├── Security rules
├── Review standards
├── Library preferences
└── Compliance requirements
↓
Repository A
Repository B
Repository CSon útiles para políticas que deberían aplicarse en muchos proyectos.
Úsalas para estándares compartidos y deja arquitectura, build y particularidades dentro de cada proyecto.
Qué ocurre cuando existen varias instrucciones
Aquí conviene distinguir el cliente.
| Entorno | Comportamiento |
|---|---|
| VS Code | Combina instrucciones aplicables y dispone de prioridades entre scopes |
| Copilot CLI | Combina múltiples fuentes y no define una precedencia general entre todos los archivos |
| AGENTS.md | Los archivos cercanos al área de trabajo pueden aportar reglas más específicas según cliente |
No dependas de conflictos para expresar excepciones. Diseña las instrucciones para que cada archivo tenga una responsabilidad clara y las reglas se complementen.
Prioridad de scopes en VS Code
Cuando varias instrucciones de distintos scopes entran en conflicto, la documentación actual de VS Code establece:
Personal instructions
Mayor prioridad.
Repository instructions
Reglas del proyecto.
Organization instructions
Menor prioridad entre estos scopes.
La prioridad es una protección ante conflictos, no una arquitectura recomendada para mantener excepciones complejas.
Diseñar instrucciones para un monorepo
monorepo/
│
├── .github/
│ ├── copilot-instructions.md
│ │
│ └── instructions/
│ ├── frontend.instructions.md
│ ├── backend.instructions.md
│ └── tests.instructions.md
│
├── apps/
│ └── web/
│
└── services/
└── api/
Usa
el archivo general
para reglas
verdaderamente comunes
y divide
las particularidades
mediante
applyTo.
El ajuste
chat.useCustomizationsInParentRepositories
permite
buscar instrucciones,
Skills,
agents
y otras
personalizaciones
hasta la raíz Git.
Usar instrucciones para mejorar Copilot Code Review
Puedes definir qué tipo de problemas debería priorizar Copilot durante una revisión.
# Code review
Prioritize:
- functional bugs
- regressions
- authorization issues
- injection vulnerabilities
- data loss
- API contract changes
- race conditions
- missing regression tests
Do not report
purely cosmetic preferences
already enforced
by automated formatting.Las instrucciones son aún más importantes para agentes remotos
Cuando Copilot trabaja sin ti en segundo plano, necesita entender de antemano:
Cómo instalar y construir.
Cómo verificar.
Qué arquitectura respetar.
Qué controles de seguridad aplicar.
Qué no debe modificar.
copilot-instructions.md para un proyecto WordPress
# WordPress project
This repository contains
a custom WordPress plugin.
## Compatibility
- PHP 8.1+
- current supported WordPress versions
- WooCommerce where applicable
Preserve:
- action names
- filter names
- shortcode names
- REST endpoint contracts
- database compatibility
## Security
For state-changing actions:
- check capabilities
- verify nonces where applicable
- validate ownership
For user-controlled data:
- validate before processing
- sanitize before storage
- escape on output
For SQL:
- prefer WordPress APIs
- use $wpdb->prepare()
- never concatenate untrusted input
## AJAX
Every AJAX handler must:
1. authenticate when required
2. verify nonce
3. check capabilities or ownership
4. validate input
5. return structured JSON
## REST API
Every state-changing route must have
a meaningful permission_callback.
## WooCommerce
Use public WooCommerce APIs.
Do not depend
on undocumented internal properties.
## Changes
Avoid unrelated refactors.
Preserve existing behavior
unless the task explicitly
requires changing it.
## Verification
Before finishing:
- run PHP syntax checks
- run available tests
- inspect git diff
- check security-sensitive paths
- report anything not verifiedSeparar reglas PHP, JavaScript y tests
.github/
│
├── copilot-instructions.md
│
└── instructions/
├── php-security.instructions.md
├── ajax.instructions.md
├── javascript.instructions.md
├── woocommerce.instructions.md
└── tests.instructions.mdEste enfoque evita cargar reglas de WooCommerce cuando el agente está editando únicamente CSS o documentación.
php-security.instructions.md
---
name: WordPress PHP Security
applyTo: "**/*.php"
---
For PHP changes:
- never trust request data
- validate expected types
- sanitize before storage
- escape at output
- verify capabilities
- verify ownership where relevant
- use nonces for CSRF protection
- use $wpdb->prepare() for dynamic SQL
Never remove
a security check
to make a failing test pass.Instructions vs Skills
| Instructions | Skills |
|---|---|
| Reglas y contexto | Procedimientos reutilizables |
| Se aplican automáticamente | Se cargan cuando son relevantes |
| “Cómo trabajamos” | “Cómo ejecutar esta tarea” |
| Arquitectura y estándares | Workflow especializado |
| Contexto persistente | Instrucciones + scripts + recursos |
“Usa
$wpdb->prepare()
para SQL dinámico”
pertenece
a Instructions.
“Ejecuta
nuestro procedimiento
completo
de auditoría
de seguridad WordPress”
probablemente
pertenece
a una Skill.
Instructions vs Custom Agents
Reglas
Contexto que acompaña las tareas.
Rol + herramientas
Configura una especialización completa del agente.
Un Custom Agent puede limitar tools, definir un rol específico y utilizar instrucciones propias.
Una instrucción no es una barrera técnica
Las instrucciones orientan al modelo, pero no garantizan matemáticamente que Copilot vaya a cumplir cada regla en cada ejecución.
Para reglas críticas, complementa las instrucciones con:
Linters.
Tests.
Static analysis.
Hooks.
CI/CD.
Code Review humano.
Cómo escribir buenas instrucciones para Copilot
Sé específico
Describe decisiones concretas.
Sé breve
Evita contexto que no cambia el resultado.
Explica el motivo
Ayuda al agente con casos límite.
Incluye ejemplos
Muestra el patrón esperado.
Modulariza
Usa path-specific instructions.
Verifica
Comprueba qué instrucciones se cargan.
Instrucción débil vs instrucción útil
“Escribe código seguro”
No define qué controles se esperan.
Regla verificable
Para endpoints que modifican datos, comprobar autenticación, autorización y ownership.
For every endpoint
that changes user-owned data:
1. require authentication
2. verify capability or ownership
3. validate resource existence
4. reject unauthorized access
5. add a negative authorization testQué hacer si Copilot ignora tus instrucciones
| Problema | Qué comprobar |
|---|---|
| copilot-instructions.md no carga | Debe estar dentro de .github en la raíz correcta |
| .instructions.md no se aplica | Revisar applyTo |
| AGENTS.md no aparece | Revisar cliente y configuración |
| Monorepo no hereda reglas | Revisar workspace y parent repository discovery |
| Reglas inconsistentes | Buscar instrucciones contradictorias |
| CLI usa reglas inesperadas | Ejecutar /instructions |
| Copilot sigue violando una regla crítica | Enforce mediante lint, test, hooks o CI |
Comprobar qué personalizaciones utiliza la sesión
VS Code dispone de herramientas de diagnóstico para identificar:
Origen de la instrucción.
Errores de configuración.
Patrones applyTo.
Archivos cargados.
Esto ayuda a confirmar qué archivos de instrucciones participaron realmente en una petición.
Cómo organizar las personalizaciones de un proyecto serio
project/
│
├── AGENTS.md
│
├── .github/
│ │
│ ├── copilot-instructions.md
│ │
│ ├── instructions/
│ │ ├── php.instructions.md
│ │ ├── frontend.instructions.md
│ │ ├── tests.instructions.md
│ │ └── security.instructions.md
│ │
│ ├── skills/
│ │ ├── security-review/
│ │ └── release-check/
│ │
│ └── agents/
│ ├── reviewer.agent.md
│ └── planner.agent.md
│
├── src/
└── tests/Instructions definen reglas. AGENTS.md entrega contexto portable. Skills contienen procedimientos. Custom Agents definen roles y herramientas.
Guías relacionadas
Documentación sobre Copilot Instructions
Repository Instructions
Instrucciones globales, path-specific y AGENTS.md.
Ver documentación →Instruction Support
Compatibilidad según cliente y función.
Ver compatibilidad →Custom Instructions
applyTo, AGENTS.md, monorepos y diagnóstico.
Ver VS Code →CLI Instructions
Instrucciones personales, repositorio e imports.
Ver CLI →FAQ sobre GitHub Copilot Instructions
Son reglas y contexto persistente que GitHub Copilot puede incorporar automáticamente a sus solicitudes para adaptar las respuestas al proyecto, arquitectura, tecnologías y convenciones del equipo.
El archivo de instrucciones generales del repositorio se guarda normalmente como .github/copilot-instructions.md desde la raíz del proyecto.
Son archivos de instrucciones modulares que permiten aplicar reglas únicamente a determinados archivos, carpetas o tipos de código mediante patrones como applyTo.
applyTo utiliza patrones glob para definir qué archivos activan automáticamente una instrucción específica. Por ejemplo, **/*.php puede aplicarse a archivos PHP.
Sí. GitHub Copilot puede utilizar AGENTS.md como instrucciones para agentes. Su compatibilidad exacta depende de la superficie de Copilot utilizada.
copilot-instructions.md está diseñado específicamente como instrucciones de repositorio para GitHub Copilot. AGENTS.md es un formato de instrucciones para agentes que puede resultar más portable entre distintas herramientas compatibles.
Sí, algunos clientes permiten instrucciones AGENTS.md en distintos niveles del repositorio. En VS Code, el soporte de AGENTS.md anidados sigue siendo experimental y está desactivado por defecto.
Sí. Copilot CLI puede combinar .github/copilot-instructions.md, instrucciones específicas por ruta, AGENTS.md, CLAUDE.md, GEMINI.md e instrucciones personales.
Puedes crear ~/.copilot/copilot-instructions.md para reglas personales que se apliquen entre distintos proyectos, además de archivos modulares dentro de ~/.copilot/instructions/.
Dentro de Copilot CLI puedes utilizar /instructions. También existen comandos de terminal para listar las instrucciones detectadas.
En VS Code, las custom instructions están orientadas a Chat y workflows agentic. No se utilizan directamente para las sugerencias inline que aparecen mientras escribes.
No. Las instrucciones orientan el comportamiento del modelo, pero la IA sigue siendo no determinista. Las reglas críticas deberían reforzarse mediante tests, linters, análisis estático, hooks o CI.
Las Instructions definen reglas y contexto que deberían acompañar las tareas. Las Skills empaquetan procedimientos reutilizables que pueden incluir instrucciones, scripts y recursos especializados.
Sí. Puedes mantener instrucciones generales en la raíz y reglas específicas mediante .instructions.md con patrones applyTo. VS Code también dispone de configuración para descubrir personalizaciones en repositorios padre.
Sí. Son especialmente útiles para guardar reglas sobre PHP, WordPress APIs, WooCommerce, nonces, capabilities, sanitización, escaping, SQL y procedimientos de testing.
GitHub Copilot Skills: crea workflows reutilizables para tus agentes
Las Instructions indican cómo debe trabajar Copilot. El siguiente paso es aprender a empaquetar procedimientos completos mediante Agent Skills, SKILL.md, scripts, referencias y recursos que Copilot puede cargar cuando una tarea los necesita.
Aprender GitHub Copilot Skills →