🚀 Custom Agents en VS Code: tutorial completo para construir más rápido y con menos retrabajo

¿Qué pasaría si pudieras describir la aplicación web que quieres construir y el asistente te devolviera los agentes que necesitas más el plan de implementación completo, con fases, dependencias y criterios de validación? Eso es exactamente lo que muestra este tutorial.

En este tutorial aprenderás a:

• entender cómo el asistente genera tus agentes automáticamente a partir de un Plan,
• invocarlos desde VS Code para cada fase del desarrollo,
• usar Plan como primer paso para diseñar tanto la web como el propio sistema de agentes,
• y encadenar agentes en un flujo que funciona de verdad.

Seguiremos una progresión de cero a web completa — con un gestor de tareas en equipo como ejemplo real, stack React + FastAPI + PostgreSQL, y capturas de cada paso.

Prerrequisitos

Antes de empezar, asegúrate de tener:

• VS Code 1.99 o superior — verifica en Ayuda > Acerca de (o Help > About).
• Suscripción activa de GitHub Copilot — Individual, Business o Enterprise.
• Extensión GitHub Copilot Chat instalada — busca “GitHub Copilot” en el marketplace (Ctrl+Shift+X).
• Repositorio git inicializado — los agentes viven en .claude/agents/, que requiere la carpeta .claude/.

Si todavía no tienes repositorio, ejecuta git init en la raíz de tu proyecto antes de seguir.

¿Por qué custom agents y no un asistente genérico?

Con un único asistente genérico suele ocurrir esto en proyectos de desarrollo web:

• mezcla schema de base de datos, rutas de API y componentes React en la misma conversación,
• no mantiene el contexto del stack entre sesiones,
• y no sabe cuándo revisar seguridad frente a cuándo implementar.

Con custom agents separas responsabilidades en roles definidos. El Database Agent solo piensa en el schema. El Frontend UI Agent solo piensa en componentes. El Auth & Security Agent solo piensa en autenticación y vulnerabilidades. Cada agente tiene instrucciones concretas, herramientas acotadas y un output esperado. El resultado es menos ruido, menos retrabajo y decisiones más trazables.

Paso 1: la carpeta de agentes en tu proyecto

Los custom agents viven en la ruta .claude/agents/ dentro del repositorio. El asistente detecta automáticamente cualquier archivo con extensión .md que exista ahí.

El asistente crea esta carpeta y los archivos de agentes automáticamente al ejecutar el plan — lo verás en el Paso 5. Si prefieres crearla manualmente antes, ejecuta en el terminal integrado (Ctrl+ `):

mkdir -p .claude/agents

Cuando el plan haya terminado, el explorador mostrará algo así:

.claude/
└── agents/
    ├── auth-security-agent.md
    ├── backend-api-agent.md
    ├── database-agent.md
    ├── devops-config-agent.md
    ├── frontend-ui-agent.md
    └── testing-agent.md

Paso 2: qué genera el asistente para cada agente — estructura del archivo

Un agente es un archivo Markdown con frontmatter YAML. El asistente los genera todos en la misma sesión de Plan, pero conviene entender qué hay dentro de cada uno para saber cómo invocarlos después.

El primero que genera Plan para cualquier proyecto web es database-agent, porque todo lo demás — API, backend y frontend — depende del schema. Este es su contenido:

---
description: "Use when: modelos SQLAlchemy, migraciones Alembic, queries, índices, diseño de esquema, relaciones entre tablas, optimización de base de datos"
name: "Database Agent"
tools: [read, search, edit]
argument-hint: "Describe el modelo, migración o consulta que necesitas"
---

You are a database architect specialized in PostgreSQL with SQLAlchemy 2.0 and Alembic.

## Responsibilities

- Design normalized schemas with clear entity relationships.
- Generate Alembic migrations with rollback support.
- Optimize indexes and query performance.
- Ensure referential integrity and constraints are explicit.

## Output format

For each schema design:
- Entity diagram (text-based)
- SQLAlchemy model code
- Alembic migration file
- Index recommendations

Desglose de los campos del frontmatter:

Campo	Tipo	Descripción
description	string	Triggers que el asistente usa para sugerir el agente. Usa el patrón "Use when: ..."
name	string	Nombre visible en el chat y el selector de agentes
tools	array	Herramientas disponibles: read, search, edit, run
argument-hint	string	Placeholder visible cuando invocas el agente en el chat

La regla de herramientas más simple: si el agente solo analiza, usa [read, search]. Si necesita modificar archivos, añade edit. Si necesita ejecutar comandos, añade run.

Paso 3: el sistema completo de agentes que el asistente genera

Junto con database-agent, el asistente genera otros cinco agentes en la misma ejecución del plan, cubriendo el ciclo completo de desarrollo.

Nota: ninguno de estos archivos se escribe a mano. Todos son el resultado de ejecutar el Plan con el prompt que verás en el Paso 5.

backend-api-agent.md — Routers y servicios FastAPI

---
description: "Use when: crear o modificar routers FastAPI, schemas Pydantic, servicios, lógica de negocio, endpoints REST, dependencies de autorización"
name: "Backend API Agent"
tools: [read, search, edit]
argument-hint: "Describe el endpoint, router o servicio que quieres implementar"
---

You are a backend developer specialized in FastAPI with Python 3.12.

Always follow the existing project structure. The routers never make queries directly —
delegate all database access to the services layer. Never introduce:
- Raw SQL when SQLAlchemy models exist.
- Hardcoded credentials or secrets.
- Missing error handling on external service calls.

frontend-ui-agent.md — Componentes React y estado

---
description: "Use when: componentes React, hooks, TanStack Query, Tailwind, páginas, formularios react-hook-form, estado Zustand, drag & drop"
name: "Frontend UI Agent"
tools: [read, search, edit]
argument-hint: "Describe el componente, página o interacción de usuario que quieres construir"
---

You are a frontend developer specialized in React 18 with Vite and Tailwind CSS v4.

Before writing any component:
1. Check existing components in `src/components/` for reuse.
2. Follow the project's Tailwind design tokens.
3. Handle loading, error, and empty states explicitly.
4. Use TanStack Query for server state and Zustand only for client-only state.

auth-security-agent.md — Autenticación y seguridad

---
description: "Use when: JWT, bcrypt, CORS, refresh tokens, ProtectedRoute, RBAC, auditoría de seguridad, autenticación, autorización por rol"
name: "Auth & Security Agent"
tools: [read, search, edit]
argument-hint: "Describe el flujo de autenticación o el aspecto de seguridad que quieres revisar o implementar"
---

You are a security specialist for web applications.

JWT strategy in this project:
- access_token: in memory (Zustand), never in localStorage → mitigates XSS.
- refresh_token: httpOnly cookie → browser manages it automatically.
- On 401: interceptor calls /api/auth/refresh, retries once; on failure, redirects to /login.

Review against: OWASP Top 10, JWT best practices, input sanitization, CORS misconfiguration.

testing-agent.md — Tests backend y frontend

---
description: "Use when: tests backend y frontend, fixtures, factories, cobertura, pytest, Vitest, MSW, React Testing Library, factory_boy"
name: "Testing Agent"
tools: [read, search, edit, run]
argument-hint: "Indica qué módulo, función o componente necesita tests"
---

You are a test engineer for full-stack applications.

For backend: use pytest with httpx for async FastAPI tests. DB: SQLite in-memory for unit tests,
PostgreSQL real for integration. Use factory_boy for fixtures.
For frontend: use Vitest with React Testing Library. Mock API calls with MSW.

Always test: happy path, validation errors, auth boundary, and edge cases.
Coverage target: ≥80% in services/ and routers/.

devops-config-agent.md — Infraestructura y despliegue

---
description: "Use when: Docker, docker-compose, nginx, CI/CD, linters, pre-commit, configuración de entorno, despliegue, Dockerfile multi-stage"
name: "DevOps & Config Agent"
tools: [read, search, edit, run]
argument-hint: "Describe la configuración, pipeline o entorno que necesitas"
---

You are a DevOps engineer specialized in containerized Python and Node.js applications.

Project uses multi-stage Dockerfiles: backend CMD applies `alembic upgrade head` before starting.
Frontend: Vite builder + nginx with SPA fallback and /api proxy to backend.
Always include health checks in docker-compose services.

database-agent.md — ya generado en el Paso 2.

Paso 4: invocar el agente desde el chat

1. Abre el panel de chat con Ctrl+Alt+I (Windows/Linux) o Cmd+Alt+I (Mac).
2. En la barra inferior del input del chat, localiza el selector de modo.
3. Haz clic en ese selector — verás tus agentes personalizados listados en una sección separada.
4. Selecciona el agente que quieras usar y escribe tu solicitud.

Ejemplo de invocación tras seleccionar Database Agent:

Necesito modelar las entidades User, Project, ProjectMember y Task para un gestor de tareas.
Un usuario puede pertenecer a varios proyectos con rol owner/member/viewer.
Una tarea pertenece a un proyecto y puede asignarse a un usuario, con status todo/in-progress/done.
Genera los modelos SQLAlchemy y la migración Alembic correspondiente.

Consejo: el campo argument-hint como guía

El texto de argument-hint que aparece en el frontmatter se muestra como placeholder en el input del chat cuando el agente está seleccionado. Hazlo descriptivo: en lugar de "Escribe tu solicitud", usa algo como "Describe el modelo, migración o consulta que necesitas".

Paso 5: usar Plan antes de ejecutar — la práctica más valiosa

Plan es un modo especial que genera un plan de ejecución detallado antes de modificar ningún archivo. La diferencia con ejecutar directamente:

Sin Plan	Con Plan
Empieza a editar inmediatamente	Propone pasos antes de actuar
Cambios difíciles de revertir si algo falla	Tienes control en cada decisión
Dependencias ocultas aparecen tarde	Las dependencias se detectan antes

Caso real: el prompt que generó este sistema

Antes de crear un solo archivo de agente, usé Plan con este prompt:

Quiero construir un gestor de tareas en equipo desde cero.

Stack:
- Frontend: React con Vite y Tailwind CSS
- Backend: FastAPI con Python
- Base de datos: PostgreSQL con SQLAlchemy y Alembic
- Autenticación: JWT

Antes de crear ningún archivo, dame un plan completo que incluya:
1. Los agentes custom que necesito crear para gestionar este proyecto:
   nombre, descripción para el campo "description", herramientas (tools)
   y argument-hint de cada uno.
2. La estructura de carpetas del proyecto.
3. El orden de implementación con las dependencias entre fases.
4. Los criterios de validación antes de pasar de una fase a la siguiente.

Plan respondió con:

• 6 agentes con sus campos completos: database-agent, backend-api-agent, frontend-ui-agent, auth-security-agent, testing-agent, devops-config-agent.
• Árbol de carpetas completo para backend y frontend.
• 5 fases de implementación con dependencias estrictas entre ellas:

Fase 1 — Infraestructura
    └── Fase 2 — Autenticación
            └── Fase 3 — Modelos core + API REST
                    └── Fase 4 — Frontend completo
                            └── Fase 5 — Tests + Producción

• Criterios de validación por fase — por ejemplo, para pasar de Fase 1 a Fase 2: curl http://localhost:8000/health debe devolver {"status":"ok"} y alembic current no debe dar errores.

Al aprobar el plan, el asistente ejecuta cada paso: crea la carpeta .claude/agents/, genera los 6 archivos de agente y scaffoldea la estructura inicial del proyecto. Todo en la misma sesión, sin intervención manual.

Punto clave: Plan no solo organiza tareas de código — diseña y construye el sistema de agentes entero.

Cómo activar Plan

1. En el selector de modo del chat, selecciona Plan.
2. Describe la tarea completa que quieres ejecutar.
3. El asistente responderá con un plan estructurado. Lee el plan antes de aprobarlo.
4. Una vez aprobado, el asistente ejecuta los pasos en orden — incluyendo crear los archivos de agente si el plan los contempla.

La respuesta de Plan incluirá:

• Lista de archivos que se van a crear o modificar.
• Orden de los cambios (dependencias entre pasos).
• Criterios de verificación al finalizar.

Una vez aprobado, el asistente convierte el plan en una lista de TODOs y los ejecuta uno a uno. Aquí puedes ver el proceso a mitad de ejecución:

Regla práctica: cuándo usar Plan

Usa Plan si se cumple alguna de estas condiciones:

• La tarea afecta más de dos archivos.
• Hay pasos que dependen de otros en un orden concreto.
• La tarea tiene efectos colaterales poco obvios (cambios de schema, migraciones, breaking changes en la API).

Si el cambio está bien localizado en un único archivo, Plan añade más fricción que valor. Úsalo cuando el riesgo de desorden sea real.

Plan en acción: vídeo completo

Este es el flujo completo grabado en tiempo real — desde el prompt inicial hasta los 6 agentes creados y la estructura del proyecto scaffoldeada:

Paso 6: orquestar el flujo completo

Con los agentes creados y Plan entendido, el flujo para construir o extender la aplicación sigue las 5 fases del plan original, cada una con su agente principal:

Fase	Agente principal	Responsabilidad
1 — Infraestructura	DevOps & Config Agent	Docker, variables de entorno, health endpoint
2 — Autenticación	Auth & Security Agent	JWT, refresh token, ProtectedRoute
3 — Modelos + API	Database Agent + Backend API Agent	Schema, migraciones, CRUD con autorización por rol
4 — Frontend	Frontend UI Agent	Kanban DnD, TanStack Query, optimistic updates
5 — Tests + Prod	Testing Agent + DevOps & Config Agent	Suite ≥80% cobertura, Dockerfiles multi-stage

Cada fase es estrictamente secuencial: no empezar la siguiente hasta que pasen todos los criterios de validación de la actual.

No es obligatorio usar el flujo completo en cada tarea. Adáptalos según la complejidad:

Complejidad	Pasos recomendados
Nuevo endpoint puntual	Backend API Agent directamente
Nueva feature con cambio de schema	Database Agent → Backend API Agent → Frontend UI Agent
Release con validación	Ciclo completo de las 5 fases

La orquestación no busca más pasos. Busca mejores transiciones entre diseño, implementación y validación.

⏱️ Comparativa realista: web completa sin IA vs con Plan + agentes

Si hablamos de una web completa como la de este tutorial (React + FastAPI + PostgreSQL + JWT + tests + Docker), una estimación de 120 min sin IA no es realista.

Para una persona sola, rangos más creíbles son estos:

Escenario	Tiempo total	Resultado
Sin IA (flujo manual)	160-320 h	Más idas y vueltas, más retrabajo, validación tardía
Con Plan + agentes orquestados	50-140 h	Mejor secuencia, menos retrabajo, más tiempo para calidad

Desglose orientativo por fase

Fase	Sin IA	Con Plan + agentes
Infraestructura y setup	12-30 h	4-10 h
Autenticación y seguridad	20-50 h	8-20 h
Modelado BD + migraciones + API	50-100 h	18-45 h
Frontend completo + integración	45-90 h	15-40 h
Tests + estabilización + despliegue	30-60 h	10-25 h
Total	160-320 h	50-140 h

No es magia: el recorte viene de reducir fricción en decisiones y transición entre fases.

Dónde está el ahorro real

• Menos retrabajo por dependencias mal ordenadas (schema/API/UI).
• Menos cambios rotos al validar en cada fase, no al final.
• Menos contexto perdido entre sesiones gracias a agentes especializados.
• Más tiempo neto para calidad: tests, manejo de errores, hardening de seguridad y revisión final.

Traducción práctica: no solo entregas antes; también entregas mejor.

📋 Por qué Plan es la práctica más rentable

Si tuviera que elegir solo una práctica de todo esto, sería usar Plan antes de tocar archivos.

Plan aporta cuatro ventajas concretas:

1. Secuencia lógica. Convierte una solicitud amplia en pasos accionables con un orden definido.
2. Dependencias explícitas. Evita empezar por un paso que depende de otro aún sin resolver.
3. Criterios de verificación. Define cómo validar la calidad antes de finalizar — no después.
4. Comunicación clara. El plan se convierte en un documento de alineación cuando trabajas con más personas.

Regla práctica: si una tarea tiene más de tres dependencias o afecta varios archivos, usar Plan deja de ser opcional.

✅ Por dónde empezar hoy

1. Inicializa un repositorio git en tu proyecto si no lo tienes ya.
2. Abre el chat, activa Plan mode y usa el prompt del Paso 5 adaptado a tu stack.
3. Aprueba el plan — el asistente crea los agentes y la estructura del proyecto.
4. Invoca auth-security-agent en tu primera sesión: solo lee, no modifica archivos, valor inmediato.
5. Mide el tiempo en cinco tareas consecutivas y compara con tu línea base.

Empieza con un prompt a Plan. Un sistema de seis agentes generado en una sesión supera con creces construir un agente manual cada vez que lo necesitas.

🧩 Conclusión

Los custom agents en VS Code no son una moda de productividad. Son una forma práctica de convertir trabajo complejo en un proceso repetible y trazable.

Cuando combinas especialización de roles, orquestación y Plan, el beneficio es claro: entregas más rápido, con menos retrabajo y con más control sobre la calidad.

Los 6 agentes de este proyecto no se diseñaron uno a uno. Nacieron de un único prompt a Plan — con fases, dependencias y criterios de validación incluidos. El sistema funciona porque tiene una lógica de diseño, no porque sea una colección de prompts acumulados.

Si hoy tu cuello de botella es el caos entre schema, API, frontend y revisión de calidad, empieza por ahí: usa Plan para diseñar y generar el sistema, y deja que cada agente haga su parte.

📚 Referencias

• MCP Server explicado para no técnicos

• IA y Navidad: compras inteligentes con multiagentes

• Inteligencia Artificial en Dynamics 365: Copilot

• GitHub Copilot en Visual Studio Code

• Custom instructions y agents en VS Code

• Model Context Protocol (MCP)