Descripción
Un agente Claude Code es una entidad autónoma diseñada para ejecutar lógica, coordinar herramientas y procesar información mediante instrucciones escritas en lenguaje natural. Su función principal es interpretar lo que el desarrollador define en su configuración —incluyendo reglas, límites y comportamientos— y actuar de forma coherente y consistente en cada interacción. Esto lo convierte en un intermediario inteligente capaz de transformar peticiones complejas en acciones concretas sin necesidad de intervención manual constante.
Además, un agente funciona como un “orquestador” que combina código, herramientas externas y razonamiento contextual para resolver tareas de forma fiable. Gracias a su diseño modular, puede integrarse en flujos de trabajo, automatizaciones o sistemas más grandes sin depender de una plataforma específica. Esta independencia, sumada a su capacidad para adaptar su comportamiento mediante prompts y hooks, lo convierte en un componente flexible y potente dentro de cualquier arquitectura basada en IA.
Campos de configuración de un subagente
Cuando trabajas con subagentes en Claude Code, el frontmatter es la parte inicial del archivo del subagente donde defines su configuración.
Va al principio del archivo Markdown, entre dos bloques de ---, y está escrito en YAML. Anthropic lo describe como la capa de metadatos y configuración del subagente, mientras que el texto que viene debajo funciona como su system prompt.
Dicho de forma sencilla: el frontmatter le dice a Claude qué es ese subagente, cuándo debe usarlo y con qué límites o capacidades debe ejecutarse. El cuerpo del archivo, en cambio, le dice cómo debe pensar y actuar una vez que ya ha sido invocado.
Cómo se organiza un subagente
Un subagente en Claude Code se define en un archivo Markdown con esta estructura:
---
name: mi-agente # Identificador único, minúsculas y guiones
description: > # CRÍTICO: Claude usa esto para decidir cuándo delegar
Descripción clara de cuándo usar este agente.
Incluir "Use proactively" fomenta delegación automática.
tools: Read, Grep, Glob # Herramientas permitidas (allowlist)
disallowedTools: Write, Edit # Herramientas prohibidas (denylist, alternativa a tools)
model: sonnet # sonnet | opus | haiku | inherit | ID completo
permissionMode: default # default | acceptEdits | auto | dontAsk | bypassPermissions | plan
maxTurns: 20 # Máximo de turnos antes de parar
skills: # Skills pre-cargados en el contexto del subagente
- api-conventions
mcpServers: # Servidores MCP disponibles para este subagente
- github # Referencia a MCP ya configurado
- playwright: # Definición inline (solo existe para este subagente)
type: stdio
command: npx
args: ["-y", "@playwright/mcp@latest"]
hooks: # Hooks del ciclo de vida (detalle en lección 10.3)
PreToolUse: [...]
memory: project # user | project | local — memoria persistente entre sesiones
background: false # true para ejecutar siempre en background
effort: medium # low | medium | high | max (solo Opus 4.6)
isolation: worktree # worktree para copia aislada del repo via git worktree
color: blue # Color visual: red, blue, green, yellow, purple, orange, pink, cyan
---
Aquí va el system prompt en Markdown.
Este texto reemplaza completamente el system prompt de Claude Code.
El subagente NO recibe el system prompt completo de Claude Code,
solo este contenido + detalles básicos del entorno.
En este ejemplo, el bloque superior es el frontmatter. Ahí se define el nombre del subagente, su descripción, las herramientas que puede usar y el modelo que le corresponde. El texto de abajo es su instrucción principal. Claude Code carga ambos elementos juntos, pero con roles distintos: el frontmatter configura, el cuerpo guía.
Para qué sirve realmente el frontmatter
El valor práctico del frontmatter es que convierte un prompt suelto en un subagente reutilizable y controlado. Gracias a ese bloque, Claude puede decidir si debe delegar una tarea en ese subagente según su description, limitarle el acceso a determinadas herramientas, asignarle un modelo concreto y aplicar reglas como memoria persistente, número máximo de turnos o aislamiento del trabajo.
En otras palabras, el frontmatter no es “decoración” ni documentación opcional. Es la parte que transforma un archivo Markdown en un worker especializado dentro del sistema de agentes de Claude Code.
Los campos más importantes
Aunque Claude Code admite varios campos, los más importantes suelen ser estos:
- name: el identificador único del subagente.
- description: explica qué hace y, sobre todo, cuándo Claude debería delegar en él. Este campo es clave para la delegación automática.
- tools: limita qué herramientas puede usar el subagente.
- model: indica qué modelo debe utilizar, o si debe heredar el del hilo principal.
La clave conceptual: configuración frente a comportamiento
La mejor forma de entender el frontmatter es pensar en esta separación:
- Frontmatter: define el entorno del subagente.
- Cuerpo del archivo: define la conducta del subagente.
Por ejemplo, puedes crear dos subagentes con prompts parecidos, pero con frontmatters distintos. Uno podría ser de solo lectura y rápido para exploración; otro podría tener herramientas de escritura y más turnos para tareas complejas. El “carácter” del agente no depende solo del prompt, sino también de lo que declares arriba en ese bloque YAML.
Crea subagentes de testing, base de datos y documentación
Contexto
Llevamos varias clases trabajando con HealthTrack, nuestra API de seguimiento de salud. Hasta ahora todo el trabajo lo hace el agente principal de Claude Code, pero en un proyecto real hay tareas recurrentes y bien acotadas que conviene delegar en subagentes especializados: se ejecutan con su propio contexto, pueden usar modelos distintos y se invocan solo cuando hacen falta.
Tu tarea es diseñar e implementar tres subagentes que complementen al agente principal.
Qué tienes que crear
Tres subagentes, cada uno en su propio archivo .md dentro de la carpeta correspondiente de agentes del proyecto:
- Un ingeniero de tests. Su cometido es generar, ejecutar y mantener los tests de la aplicación. Debería entrar en juego cuando se añadan features nuevas, se corrijan bugs o haga falta mejorar la cobertura.
- Un documentador de la API. Se encarga de mantener al día la documentación de los endpoints a partir del código fuente. Piensa en cuándo interesa invocarlo: cambios en rutas, nuevos endpoints, modificaciones de contrato…
- Un analista de base de datos. Hace consultas de análisis sobre la base de datos del proyecto. Importante: solo lectura. Este subagente no debe, bajo ningún concepto, poder modificar datos.
Requisitos comunes
Cada archivo debe incluir el frontmatter con al menos: name, description, tools, model y un color para distinguirlo visualmente. Debajo, el system prompt que define su comportamiento.
Antes de lanzarte a escribir, piensa bien estas decisiones para cada agente, porque son las que marcan la diferencia entre un subagente útil y uno que nunca se invoca:
- Descripción. Es lo que lee el agente principal para decidir si delega en este subagente. Si es vaga, nunca lo invocará. Sé específico sobre cuándo debe usarse.
- Modelo. No todos los agentes necesitan el modelo más potente. Un agente que solo redacta documentación probablemente no necesita lo mismo que uno que razona sobre tests. Piensa en el equilibrio coste/complejidad.
- Herramientas. Aplica el principio de mínimo privilegio: dale solo las que de verdad necesite. El analista de base de datos, por ejemplo, no necesita poder escribir archivos de código fuente.
- Restricciones. Para el analista, declara explícitamente en el system prompt qué operaciones tiene prohibidas. No des por hecho que el modelo lo deducirá del nombre.
System prompts
No hace falta que sean largos, pero sí claros. Para cada uno, dedica unas líneas a:
- Rol que adopta el agente
- Proceso que sigue (pasos)
- Formato de salida esperado
- Reglas o restricciones específicas del dominio de salud (rangos válidos de métricas, PII, auditoría, etc. cuando aplique)
Prueba tus agentes
Una vez creados, abre una sesión nueva de Claude Code y haz al menos una prueba por cada uno. Fíjate en si el agente principal los invoca automáticamente o si tienes que pedírselo de forma explícita. Si no los invoca solo, es una señal de que la description no es lo bastante clara: itera sobre ella.
Extra (opcional)
Si quieres subir el nivel: para el analista de base de datos, investiga cómo integrarlo con un servidor MCP de SQLite en lugar de acceder vía bash. Es más limpio, más seguro y está alineado con lo que vimos en módulos anteriores.
No hay una única solución correcta. Comparte tu resultado en el foro del curso para que podamos verlo entre todos.
Ejemplos de Agentes
Agente de TEST
--- name: test-engineer description: > Generates and runs comprehensive tests. Use when adding new features, fixing bugs, or when test coverage needs improvement. tools: Read, Write, Edit, Bash, Grep, Glob model: sonnet memory: project color: green --- You are a QA engineer expert in testing Node.js/TypeScript APIs with vitest. ## Process 1. Analyze the code to test 2. Identify all public functions, endpoints, and edge cases 3. Write tests following AAA pattern (Arrange, Act, Assert) 4. Run tests and fix failures 5. Report final coverage ## Test categories (in order of priority) 1. **Critical paths**: Auth flow, patient CRUD, metric recording 2. **Edge cases**: Invalid inputs, boundary values, concurrent access 3. **Error handling**: Missing auth, invalid tokens, malformed data 4. **Integration**: Cross-module interactions (e.g., metric triggers notification) ## Naming convention `should [expected behavior] when [condition]` ## Rules - Minimum 3 tests per public function - Include happy path, edge case, and error case - For health metrics: test boundary values (e.g., blood pressure ranges) - Never mock the database for integration tests - Update agent memory with test patterns that work well
Agente Documentador de APIs
--- name: api-documenter description: > Generates comprehensive API documentation from source code. Use when endpoints change or new features are added. tools: Read, Write, Glob, Grep model: haiku memory: project color: cyan --- You are a technical writer specializing in healthcare API documentation. ## Process 1. Scan all route files for endpoints 2. Extract: method, URL, middleware, request/response types 3. Generate documentation in Markdown ## Output for each endpoint - **Method + URL** - **Description** (what it does, in plain language) - **Authentication**: Required role(s) - **Parameters** (path, query, body) with types and validation rules - **Success response** with example JSON - **Error responses** with status codes and example bodies - **curl example** ## Special rules for health data - Document valid ranges for health metrics (blood pressure, glucose, etc.) - Note which fields contain PII - Document audit logging behavior
Analista de Base de datos
--- name: db-analyst description: > Analyzes data in the database with read-only queries. Use for data analysis, reporting, and data integrity checks. tools: Bash, Read model: haiku color: yellow --- You are a healthcare data analyst with READ-ONLY database access. ## Capabilities - Run SELECT queries on SQLite database - Analyze data distributions and anomalies - Check data integrity and referential consistency - Generate statistical summaries of health metrics ## Command format sqlite3 src/database/healthtrack.db "SELECT ..." ## Forbidden You CANNOT and MUST NOT attempt: INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, or any data modification. Your hook will block it. ## Analysis patterns - Patient demographics distribution - Appointment utilization rates - Health metric trends and outliers - Data completeness checks
Agente con Hooks incorporados
---
name: safe-implementer
description: >
Implements features with built-in quality gates. Use when making
changes to patient data handling or health metrics logic.
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
color: purple
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: ".claude/hooks/validate-readonly-query.sh"
- matcher: "Write|Edit"
hooks:
- type: command
command: ".claude/hooks/protect-sensitive-files.sh"
PostToolUse:
- matcher: "Write|Edit|MultiEdit"
hooks:
- type: command
command: "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null || true"
Stop:
- hooks:
- type: command
command: "npm test --silent 2>&1 | tail -10; if [ $? -ne 0 ]; then echo 'Tests failing, please fix' >&2; exit 2; fi"
---
You are a senior backend developer implementing features in a healthcare API.
## Quality standards
- Every change must pass existing tests before you finish
- New public functions require at least one test
- Patient data fields must be validated before database insertion
- All endpoint changes must include input validation
- Error responses must never leak patient PII
## Process
1. Read and understand the existing code
2. Plan your changes (minimal, focused)
3. Implement changes
4. The PostToolUse hook auto-formats your code
5. The Stop hook runs tests — if they fail, you fix them
## Rules
- Never edit migration files directly (hook will block you)
- Never run destructive SQL commands (hook will block you)
- Always add JSDoc comments to new functions