Uso de instrucciones personalizadas para desbloquear la eficacia de la revisión de código de Copilot

Obtenga información sobre cómo escribir instrucciones personalizadas eficaces que ayuden a GitHub Copilot a proporcionar revisiones de código más relevantes y accionables.

En este artículo

Introducción

GitHub Copilot la revisión de código puede personalizarse mediante archivos de instrucciones para adecuar la experiencia de revisión a las necesidades y estándares de codificación de su equipo. Sin embargo, escribir instrucciones personalizadas eficaces requiere comprender cómo Copilot procesa estas instrucciones y qué enfoques funcionan mejor.

En este tutorial, aprenderá a escribir instrucciones personalizadas claras y eficaces que ayuden a Copilot a proporcionar revisiones de código más relevantes. Descubrirá los procedimientos recomendados para estructurar las instrucciones, los problemas comunes que se deben evitar y las estrategias para organizar instrucciones en diferentes archivos.

Este tutorial trata sobre el uso de instrucciones personalizadas para Revisión del código de Copilot. Para obtener una introducción más general al uso de instrucciones personalizadas, consulte Configuración de instrucciones personalizadas para GitHub Copilot.

Temas que se abordarán

Al final de este tutorial, comprenderá lo siguiente:

  • Cómo escribir instrucciones personalizadas concisas y eficaces para la revisión de código.
  • Diferencia entre las instrucciones de todo el repositorio y específicas de una ruta de acceso.
  • Patrones comunes que funcionan bien con Revisión del código de Copilot.
  • Qué tipos de instrucciones no se admiten actualmente.
  • Cómo estructurar y organizar las instrucciones para obtener los mejores resultados.

Prerrequisitos

  • Acceso a Revisión del código de Copilot.
  • Un repositorio GitHub donde puede crear archivos de instrucciones personalizados.
  • Conocimientos básicos de la sintaxis de Markdown.

Descripción de cómo GitHub Copilot procesa instrucciones de revisión de código

Antes de escribir instrucciones personalizadas, resulta útil comprender cómo Revisión del código de Copilot los usa. Durante la revisión de una solicitud de incorporación de cambios, Copilot lee los archivos de instrucciones y los usa para guiar su análisis. Sin embargo, al igual que cualquier sistema de inteligencia artificial, tiene limitaciones:

  •         **Comportamiento no determinista**: Copilot puede no seguir todas las instrucciones perfectamente cada vez.

  •         **Límites de contexto**: los archivos de instrucciones muy largos pueden dar lugar a que se pasen por alto algunas instrucciones.

  •         **Cuestiones de especificidad**: las instrucciones claras y específicas funcionan mejor que las directivas vagas.

Tenga en cuenta estos factores a medida que escribe sus instrucciones: le ayudarán a establecer expectativas realistas y escribir instrucciones más eficaces.

Redacción de instrucciones personalizadas eficientes

La clave para obtener instrucciones personalizadas correctas es ser clara, concisa y específica. Estos son los principios básicos que se deben seguir:

Mantener las instrucciones cortas y centradas

Es más probable que los archivos de instrucciones más cortos sean procesados por Copilot. Comience con un conjunto mínimo de instrucciones y agregue más iterativamente en función de lo que funciona.

          **Procedimiento recomendado**: limite cualquier archivo de instrucción único a un máximo de aproximadamente 1000 líneas. Además de esto, la calidad de las respuestas puede deteriorarse.

Uso de una estructura y formato claros

Copilot se beneficia de instrucciones bien estructuradas con:

  •         **Distintos encabezados** que separan temas diferentes.

  •           **Viñetas** para facilitar la lectura y la referencia.

  •         **Directivas breves e imperativas** en lugar de párrafos narrativos largos.

Por ejemplo, en lugar de escribir:

When you're reviewing code, it would be good if you could try to look for
situations where developers might have accidentally left in sensitive
information like passwords or API keys, and also check for security issues.

Escritura:

## Security Critical Issues

- Check for hardcoded secrets, API keys, or credentials
- Look for SQL injection and XSS vulnerabilities
- Verify proper input validation and sanitization

Proporcionar ejemplos concretos

Al igual que cuando se explica un concepto a un compañero, los ejemplos ayudan a Copilot a comprender lo que quiere decir. Incluya fragmentos de código que muestren patrones correctos e incorrectos.

Por ejemplo:

## Naming Conventions

Use descriptive, intention-revealing names.

```javascript
// Avoid
const d = new Date();
const x = users.filter(u => u.active);

// Prefer
const currentDate = new Date();
const activeUsers = users.filter(user => user.isActive);
```

Organización de instrucciones entre archivos

Revisión del código de Copilot admite dos tipos de archivos de instrucción:

  1.        **
       `copilot-instructions.md`
       **: instrucciones para todo el repositorio que se aplican a todos los archivos.

  2.        **
       `*.instructions.md`
       **: instrucciones específicas de la ruta de acceso que se aplican a determinados archivos o directorios.

Use instrucciones específicas de la ruta para mantener Copilot centrado y evitar que aplique reglas específicas del lenguaje a los archivos incorrectos.

Cuándo usar instrucciones para todo el repositorio

Use copilot-instructions.md para:

  • Directrices y estándares generales del equipo

  • Requisitos de seguridad universal

  • Cuestiones transversales, como la filosofía de control de errores

  • Expectativas de documentación

            **Estructura de ejemplo para `copilot-instructions.md`**:
Markdown
# General Code Review Standards

## Code Quality Essentials

- Functions should be focused and appropriately sized
- Use clear, descriptive naming conventions
- Ensure proper error handling throughout

## Security Standards

- Never hardcode credentials or API keys
- Validate all user inputs
- Use parameterized queries to prevent SQL injection

## Documentation Expectations

- All public functions must include doc comments
- Complex algorithms should have explanatory comments
- README files must be kept up to date

Cuándo usar instrucciones específicas de ruta

Use los archivos *.instructions.md con la propiedad frontmatter applyTo para:

  • Estándares de codificación específicos del lenguaje

  • Patrones específicos del marco de trabajo

  • Problemas de seguridad específicos de la tecnología

  • Reglas diferentes para diferentes partes del código base

            **Ejemplo: instrucciones específicas de Python**

Cree un archivo llamado python.instructions.md en el .github/instructions directorio :

Text
---
applyTo: "**/*.py"
---

# Python Coding Conventions

## Naming Conventions

- Use snake_case for variables and functions
- Use PascalCase for class names
- Use UPPERCASE for constants

## Code Style

- Follow PEP 8 style guidelines
- Limit line length to 88 characters (Black formatter standard)
- Use type hints for function signatures

## Best Practices

- Use list comprehensions for simple transformations
- Prefer f-strings for string formatting
- Use context managers (with statements) for resource management

```python
# Avoid
file = open('data.txt')
content = file.read()
file.close()

# Prefer
with open('data.txt') as file:
    content = file.read()
```

          **Ejemplo: Instrucciones específicas del front-end**

Cree un archivo llamado frontend.instructions.md en el .github/instructions directorio :

Text
---
applyTo: "src/components/**/*.{tsx,jsx}"
---

# React Component Guidelines

## Component Structure

- Use functional components with hooks
- Keep components small and focused (under 200 lines)
- Extract reusable logic into custom hooks

## State Management

- Use useState for local component state
- Use useContext for shared state across components
- Avoid prop drilling beyond 2-3 levels

## Accessibility

- All interactive elements must be keyboard accessible
- Include appropriate ARIA labels
- Ensure color contrast meets WCAG AA standards

Separación de conjuntos de instrucciones complejas

Para repositorios de gran tamaño con muchos problemas, divida las instrucciones en varios archivos centrados:

.github/
  copilot-instructions.md          # General standards

.github/instructions/
  python.instructions.md           # Python-specific
  javascript.instructions.md       # JavaScript-specific
  security.instructions.md         # Security-specific
  api.instructions.md              # API-specific

Cada archivo debe tener un propósito claro y específico, y un "frontmatter" adecuado applyTo cuando sea necesario.

Basado en lo que funciona bien con Revisión del código de Copilot, a continuación se presenta una plantilla recomendada para estructurar las instrucciones:

Text
---
applyTo: "**/*.{js,ts}"  # If this is a path-specific file
---

# [Title: Technology or Domain Name] Guidelines

## Purpose

Brief statement of what this file covers and when these instructions apply.

## Naming Conventions

- Rule 1
- Rule 2
- Rule 3

## Code Style

- Style rule 1
- Style rule 2

```javascript
// Example showing correct pattern
```

## Error Handling

- How to handle errors
- What patterns to use
- What to avoid

## Security Considerations

- Security rule 1
- Security rule 2

## Testing Guidelines

- Testing expectation 1
- Testing expectation 2

## Performance

- Performance consideration 1
- Performance consideration 2

Adapte esta estructura a sus necesidades específicas, pero mantenga el formato de sección claro y con formato de viñetas.

Qué no incluir en las instrucciones personalizadas

Entender lo que Revisión del código de Copilot no admite actualmente le ayuda a evitar perder tiempo en instrucciones que no funcionarán.

Tipos de instrucciones no admitidos

Revisión del código de Copilot actualmente no admite instrucciones que intenten:

          **Cambie la experiencia del usuario o el formato**:

  • Use bold text for critical issues

  • Change the format of review comments

  • Add emoji to comments

            **Modifique el comentario de información general de la solicitud de incorporación de cambios**:

  • Include a summary of security issues in the PR overview

  • Add a testing checklist to the overview comment

            **Cambiar la función principal de GitHub Copilot**:

  • Block a PR from merging unless all Revisión del código de Copilot comments are addressed

  • Generate a changelog entry for every PR

            **Siga los vínculos externos**:

  • Review this code according to the standards at https://example.com/standards

    Solución alternativa: copie el contenido pertinente directamente en el archivo de instrucciones en su lugar.

            **Mejoras imprecisas de calidad**:

  • Be more accurate

  • Don't miss any issues

  • Be consistent in your feedback

Este tipo de instrucciones agrega ruido sin mejorar la eficacia de Copilot, ya que está optimizado para proporcionar revisiones precisas y coherentes.

Prueba e iteración en las instrucciones

El mejor enfoque para crear instrucciones personalizadas eficaces es iniciar pequeñas e iterar en función de los resultados.

Comience con un conjunto de instrucciones mínimo

Comience con 10 a 20 instrucciones específicas que aborden sus necesidades de revisión más comunes, luego pruebe si estas influyen en Revisión del código de Copilot de la manera prevista.

Prueba con solicitudes de incorporación de cambios reales

Después de crear las instrucciones:

  1. Abra una solicitud de incorporación de cambios en tu repositorio.
  2. Solicite una revisión de Copilot.
  3. Observe qué instrucciones sigue de forma eficaz.
  4. Tenga en cuenta las instrucciones que se omiten o malinterpretan de manera consistente.

Iteración basada en los resultados

Agregue instrucciones nuevas de uno a uno o en grupos pequeños:

  1. Identifique un patrón que Copilot podría revisar de manera más efectiva.
  2. Agregue una instrucción específica para ese patrón.
  3. Pruebe con una nueva solicitud de incorporación de cambios.
  4. Refinar la instrucción en función de los resultados.

Este enfoque iterativo le ayuda a comprender qué funciona y mantiene los archivos de instrucciones centrados.

Ejemplo: Completar instrucciones personalizadas para la revisión de código

Este es un ejemplo completo que incorpora todos los procedimientos recomendados de este tutorial:

          **Archivo: `.github/copilot-instructions.md`**
Markdown
# General Code Review Standards

## Purpose

These instructions guide Revisión del código de Copilot across all files in this repository.
Language-specific rules are in separate instruction files.

## Security Critical Issues

- Check for hardcoded secrets, API keys, or credentials
- Look for SQL injection and XSS vulnerabilities
- Verify proper input validation and sanitization
- Review authentication and authorization logic

## Performance Red Flags

- Identify N+1 database query problems
- Spot inefficient loops and algorithmic issues
- Check for memory leaks and resource cleanup
- Review caching opportunities for expensive operations

## Code Quality Essentials

- Functions should be focused and appropriately sized (under 50 lines)
- Use clear, descriptive naming conventions
- Ensure proper error handling throughout
- Remove dead code and unused imports

## Review Style

- Be specific and actionable in feedback
- Explain the "why" behind recommendations
- Acknowledge good patterns when you see them
- Ask clarifying questions when code intent is unclear

## Testing Standards

- New features require unit tests
- Tests should cover edge cases and error conditions
- Test names should clearly describe what they test

Always prioritize security vulnerabilities and performance issues that could impact users.

          **Archivo: `.github/instructions/typescript.instructions.md`**
Text
---
applyTo: "**/*.{ts,tsx}"
---

# TypeScript Development Standards

## Type Safety

- Avoid using `any` type—use `unknown` or specific types instead
- Use strict null checks (no `null` or `undefined` without explicit handling)
- Define interfaces for all object shapes

```typescript
// Avoid
function processData(data: any) {
    return data.value;
}

// Prefer
interface DataShape {
    value: string;
}

function processData(data: DataShape): string {
    return data.value;
}
```

## Naming Conventions

- Use PascalCase for types, interfaces, and classes
- Use camelCase for variables, functions, and methods
- Use UPPER_CASE for constants

## Modern TypeScript Patterns

- Use optional chaining (`?.`) and nullish coalescing (`??`)
- Prefer `const` over `let`; never use `var`
- Use arrow functions for callbacks and short functions

## React-Specific (for .tsx files)

- Use functional components with TypeScript props interfaces
- Type all props and state explicitly
- Use proper event types (e.g., `React.ChangeEvent<HTMLInputElement>`)

Solución de problemas habituales

Si Revisión del código de Copilot no sigue las instrucciones como se esperaba, pruebe estas soluciones:

Problema: Se omiten las instrucciones

          **Causas posibles**:

  • El archivo de instrucciones es demasiado largo (más de 1000 líneas).

  • Las instrucciones son vagas o ambiguas.

  • Las instrucciones entran en conflicto entre sí.

            **Soluciones**:

  • Acorte el archivo quitando instrucciones menos importantes.

  • Vuelva a escribir instrucciones vagas para ser más específicas y accionables.

  • Revise las instrucciones en conflicto y priorice las más importantes.

Problema: reglas específicas del idioma aplicadas a archivos incorrectos

          **Causas posibles**:

  • Falta o es incorrecto el frontmatter applyTo.

  • Reglas en un archivo a nivel del repositorio en lugar de un archivo específico de ruta.

            **Soluciones**:

  • Agregue frontmatter applyTo a archivos de instrucciones específicos de la ruta.

  • Mueva las reglas específicas del idioma de copilot-instructions.md a los archivos adecuados *.instructions.md .

Problema: Comportamiento incoherente entre revisiones

          **Causas posibles**:

  • Las instrucciones son demasiado numerosas.

  • Las instrucciones carecen de especificidad.

  • Variabilidad natural en las respuestas de IA.

            **Soluciones**:

  • Céntrese en sus instrucciones de prioridad más alta.

  • Agregue ejemplos concretos para aclarar la intención.

  • Acepte que cierta variabilidad es normal para los sistemas de inteligencia artificial.

Conclusión

Las instrucciones personalizadas eficaces ayudan a Revisión del código de Copilot a proporcionar comentarios más relevantes y accionables adaptados a los estándares de su equipo. Siguiendo los principios de este tutorial, manteniendo instrucciones concisas, proporcionando una estructura clara, usando ejemplos concretos y organizando varios archivos, puede mejorar significativamente la experiencia de revisión del código.

Recuerde que la creación de instrucciones eficaces es un proceso iterativo. Comience con un pequeño conjunto de instrucciones centradas, pruárelas con solicitudes de incorporación de cambios reales y expanda gradualmente en función de lo que funciona bien para su equipo.

Pasos siguientes