Agentes personalizados y prompt files

Instrucciones por tipo de fichero

Estrategia de contexto por rol: Angular, Laravel, tests

Agentes Planner, Coder y Reviewer

Tres agentes con herramientas restringidas y handoffs

Mentalidad de contexto

De preguntar a instruir, delimitar y validar

Prompt files propios

Slash commands reutilizables para tareas del equipo

Conceptos clave

Instrucciones por tipo de fichero — el “contexto por rol”

La semana pasada creamos el copilot-instructions.md global y path-specific instructions básicos. Ahora vamos un paso más allá: crear una estrategia de contexto por rol.

La idea: el copilot-instructions.md global aplica a todo, pero los ficheros *.instructions.md con applyTo se activan solo cuando el agente trabaja en ese tipo de fichero.

Directory.github/
- Directoryinstructions/
  - angular.instructions.md applyTo: src/**/*.ts
  - laravel.instructions.md applyTo: app/**/*.php
  - testing.instructions.md applyTo: **/*.spec.ts

El agente que trabaja en app/Http/Controllers/UserController.php recibe instrucciones Laravel, no Angular. Sin que el dev piense en cuál activar.

Adicionalmente, cada dev puede tener instrucciones personales en su VS Code (nivel usuario) que se suman a las del repo — útil para preferencias individuales que no deben forzarse a todo el equipo.

Cómo referenciar el proyecto en el chat

@workspace ya no existe (fue eliminado). Lo que hay ahora es mejor.

Por defecto, el agente ya indexa automáticamente el workspace: busca los ficheros relevantes sin que el dev haga nada. Para casos donde no está encontrando lo correcto:

Referencia	Qué hace	Cuándo usarla
`#codebase`	Equivalente explícito del antiguo `@workspace` — mira todo el proyecto a fondo	En modo Ask cuando la IA responde de forma demasiado genérica
`#nombre-fichero`	Referencia directa a un fichero (también se puede arrastrar desde el Explorer)	En modo Ask para centrar al agente en algo concreto
`#símbolo`	Referencia a una clase o función por nombre	Cuando quieres que el agente trabaje sobre un símbolo específico

En modo Plan/Agent el agente rara vez necesita ayuda para encontrar ficheros — ya lo hace solo.

Mentalidad de contexto vs mentalidad de chat

El cambio mental más importante de todo el programa. En chat preguntas; con el agente instruyes, delimitas y validas.

La calidad del output es directamente proporcional a la calidad del contexto dado.

Prompt malo
Prompt con contexto

“Crea un componente de usuario”

El agente no sabe qué tipo de componente, dónde ubicarlo, qué patrones seguir, ni qué datos mostrar.

“Crea un componente Angular standalone UserProfileComponent en src/app/features/users/. Usa Signals para el estado. El componente recibe un userId como input signal, llama a UserService.getById() y muestra nombre, email y rol. Sigue el patrón de los componentes existentes en src/app/features/products/.”

El agente tiene todo lo que necesita para producir código correcto a la primera.

Agente Planner — descomponer features

Agente en .github/agents/planner.agent.md especializado en descomponer features. Herramientas restringidas a lectura del repo y escritura de markdown — no puede editar código.

Dado un requisito en lenguaje natural produce:

Lista de tareas técnicas
Acceptance criteria
Ficheros afectados
Posibles riesgos

Complementa el modo Plan nativo: Plan mode es genérico, el Planner personalizado conoce las convenciones del proyecto.

Ejemplo de .github/agents/planner.agent.md:

---
name: Planner
description: Descompone features en tareas técnicas sin tocar código
tools:
  - read_file
  - grep_search
  - file_search
  - semantic_search
  - list_dir
  - create_file
handoffs:
  - agent: Coder
    label: Empezar implementación
---
Eres el Planner del proyecto. Tu trabajo es analizar requisitos y producir
planes de implementación detallados.

Antes de planificar, lee el copilot-instructions.md y las instrucciones
relevantes del directorio .github/instructions/.

Produce siempre:
1. Lista de tareas técnicas ordenadas por dependencia
2. Ficheros que se crearán o modificarán
3. Acceptance criteria para cada tarea
4. Riesgos o preguntas abiertas

NO implementes código. Solo planifica.

Agente Coder — implementar

Agente especializado en implementación. Conoce Angular Signals (no NgRx), Karma+Jasmine, PHPUnit y las convenciones del proyecto. Tiene acceso a edición de ficheros. No hace review ni decide arquitectura.

---
name: Coder
description: Implementa código siguiendo las convenciones del proyecto
tools:
  - read_file
  - replace_string_in_file
  - create_file
  - run_in_terminal
  - grep_search
  - file_search
  - semantic_search
handoffs:
  - agent: Reviewer
    label: Revisar código
---
Eres el Coder del proyecto. Implementas código siguiendo estrictamente
las convenciones definidas en copilot-instructions.md y las instrucciones
path-specific.

Antes de implementar, lee las instrucciones relevantes.
Sigue los patrones del código existente.
Crea tests para lo que implementes (Karma+Jasmine para Angular, PHPUnit para Laravel).

Agente Reviewer — pre-review

Agente especializado en pre-review antes de que el código llegue a un humano.

Revisa: naming, separación de responsabilidades, OWASP básico, cobertura de tests, deuda técnica introducida. Genera un informe en markdown. No modifica código.

---
name: Reviewer
description: Pre-review de código antes del MR humano
tools:
  - read_file
  - grep_search
  - file_search
  - semantic_search
  - list_dir
---
Eres el Reviewer del proyecto. Tu trabajo es revisar código y producir
un informe de calidad antes del review humano.

Revisa:
- Naming y convenciones del proyecto
- Separación de responsabilidades
- Vulnerabilidades OWASP básicas (inyección, XSS, exposición de datos)
- Cobertura de tests
- Deuda técnica introducida

Produce un informe estructurado en markdown. NO modifiques código.

Restricción de tools por agente

El frontmatter tools define exactamente qué puede hacer cada agente:

El Planner no puede editar código
El Reviewer no puede crear ficheros
El Coder no puede ejecutar comandos de despliegue

El equipo confía más en un agente cuando sabe exactamente qué puede y qué no puede hacer.

Handoffs — el flujo Planner → Coder → Reviewer

Los agentes custom tienen handoffs en su frontmatter: botones que aparecen al terminar la respuesta para pasar al siguiente agente con contexto preload.

El flujo completo:

El Planner termina y aparece el botón “Empezar implementación” → abre el Coder con el plan
El Coder termina y aparece “Revisar código” → abre el Reviewer
El Reviewer genera el informe de pre-review

Prompt files — slash commands propios

Ficheros .prompt.md en .github/prompts/. Se invocan con /nombre-del-prompt en el chat. El frontmatter permite especificar el agente, el modelo y las tools disponibles.

Se pueden generar con /create-prompt.

Ejemplo — .github/prompts/nuevo-componente.prompt.md:

---
mode: agent
agent: Coder
description: Genera un componente Angular con Signals
---
Crea un componente Angular standalone con las siguientes especificaciones:
  - Nombre: {{ nombre }}
  - Ubicación: src/app/features/{{ modulo }}/
  - Usa Signals para estado reactivo
  - Incluye los tests en Karma+Jasmine
  - Sigue los patrones de los componentes existentes en el proyecto

Ejemplo — .github/prompts/revisar-mr.prompt.md:

---
mode: agent
agent: Reviewer
description: Pre-review del código modificado
---
Revisa todos los ficheros modificados en el working tree (git diff).
Genera un informe de review siguiendo los criterios del Reviewer.

Tarea individual (entre sesiones)

Crear .github/agents/planner.agent.md con tools de solo lectura y handoff al Coder
Crear .github/agents/coder.agent.md con tools de edición y handoff al Reviewer
Crear .github/agents/reviewer.agent.md con tools de solo lectura, sin handoff
Ajustar los 3 agentes con las convenciones reales del proyecto (nombres de directorios, patrones, restricciones)
Crear .github/prompts/nuevo-componente.prompt.md para generar componentes Angular con Signals
Crear .github/prompts/nuevo-endpoint.prompt.md para generar endpoints Laravel (Form Request + Policy + JsonResource)
Crear .github/prompts/revisar-mr.prompt.md que ejecute el Reviewer sobre el git diff
Probar el flujo completo Planner → Coder → Reviewer con una feature del sprint actual
Anotar: ¿dónde acertó el agente? ¿dónde se equivocó? ¿qué instrucciones faltaron? — traer las notas a la siguiente sesión