GitHub Copilot + Archivos de Instrucciones: La forma profesional de automatizar commits en VS Code

Problema

Las configuraciones inline en JSON se vuelven largas, difíciles de mantener, poco compartibles y limitadas en formato.

Solución

Usar archivos de instrucciones Markdown externos y referenciarlos desde la configuración de VS Code. Esta función permite definir reglas de generación de mensajes y versionarlas junto al código.

Implementación

1) Apunta VS Code a tu archivo de instrucciones

Edita .vscode/settings.json:

{
  "github.copilot.chat.commitMessageGeneration.instructions": [
    { "file": ".github/instructions/commit-messages.instructions.md" }
  ]
}

Esta clave carga instrucciones desde archivo y las adjunta al prompt que Copilot usa para generar el commit.

2) Crea el archivo .github/instructions/commit-messages.instructions.md

Usa frontmatter applyTo para controlar el ámbito. Ejemplo global:

---
applyTo: '**'
---

# Git Commit Message Generator

Generate a conventional commit message in English following this exact format:

```
type(scope): message

Detailed description of changes made, including context,
reason for changes, and any important implementation details.
This can be multiple lines and much more comprehensive.

Files modified:
- path/to/file1.ext
- path/to/file2.ext
- path/to/file3.ext
```

## Requirements:
- **Types**: feat, fix, docs, style, refactor, perf, test, chore
- **Scopes**: core, operations, shared
- **Message**: imperative mood, lowercase, no period, **max 48 chars**
- **Description**: detailed explanation of changes, context, and reasoning
- **Files**: bulleted list of modified files with relative paths
- **Language**: English only

## Examples:
```
feat(core): add user authentication

Implemented JWT-based authentication system with login,
logout, and token refresh functionality. Added middleware
for route protection and user session management.

Files modified:
- apps/core/src/auth/auth.service.ts
- apps/core/src/auth/auth.controller.ts
- apps/core/src/middleware/auth.middleware.ts
```
```
fix(operations): resolve invoice calculation bug

Fixed rounding error in tax calculation that caused
discrepancies in invoice totals. Updated calculation
logic to use proper decimal precision.

Files modified:
- apps/operations/src/invoices/invoice.service.ts
- apps/operations/src/invoices/invoice.test.ts
```
Analyze the staged changes and generate ONE commit message following these rules exactly.

3) Estructura recomendada

.github/
└── instructions/
    ├── commit-messages.instructions.md
    ├── pr-review.instructions.md
    └── code-review.instructions.md
.vscode/
└── settings.json

---

Uso en el flujo de trabajo

Desde Source Control (UI): en el campo del mensaje, pulsa el ícono ✨ Generate Commit Message with Copilot.

Desde la paleta de comandos: ejecuta “Generate Commit Message with Copilot”.

Para crear un atajo de teclado, añade en keybindings.json:

[
  {
    "key": "ctrl+alt+m",
    "command": "github.copilot.git.generateCommitMessage",
    "when": "scmProvider == 'git'"
  }
]

---

Ejemplo

Cambios:

• Ajustes en autenticación JWT
• Actualización de tests
• Documentación

Commit generado:

feat(auth): implement JWT token refresh

Added automatic token refresh mechanism to prevent
session expiration. Implemented refresh token rotation
and secure storage. Updated authentication middleware
to handle token refresh transparently.

Files modified:
- apps/core/src/auth/auth.service.ts
- apps/core/src/auth/jwt.middleware.ts
- apps/core/src/auth/auth.test.ts
- docs/authentication.md

---

Integración con control de calidad

Commitlint

// commitlint.config.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'scope-enum': [2, 'always', ['core', 'operations', 'shared']],
    'subject-max-length': [2, 'always', 48]
  }
};

Husky (hook commit-msg)

# husky v9
npm i -D @commitlint/cli @commitlint/config-conventional husky
npx husky init
echo "npx --no -- commitlint --edit \\$1" > .husky/commit-msg
chmod +x .husky/commit-msg

---

Buenas prácticas

• Versiona y revisa los .instructions.md por PR.
• Mantén ejemplos mínimos y reales.
• Si el resultado es inconsistente, endurece las reglas y añade ejemplos concretos.

---

Troubleshooting

• No aplica instrucciones: confirma la ruta del archivo en settings.json y que Copilot Chat esté actualizado.
• No aparece/genera el mensaje: usa el botón ✨ en Source Control o la paleta; comprueba que hay cambios staged.
• Comportamientos erráticos: revisa issues abiertos del repositorio de la extensión de Copilot en VS Code.

---

Recursos

• Prompt files de VS Code: https://code.visualstudio.com/docs/copilot/customization/prompt-files
• Smart Actions (generar commit y PR): https://code.visualstudio.com/docs/copilot/copilot-smart-actions#_generate-a-commit-message-and-pr-information
• Conventional Commits: https://www.conventionalcommits.org/
• Commitlint: https://commitlint.js.org/#/reference-rules