Guía para crear agentes
Los agentes son los agentes especializados de Argui. Cada uno tiene una identidad, un dominio y un criterio de calidad propio.
Los agentes no son fijos. Dependen del proyecto: un PMV (Producto Mínimo Viable) de PWA sin backend necesita agentes distintos a un SaaS multi-tenant. Por eso Argui no entrega plantillas de agentes — entrega pautas para crearlos y arquetipos de rol (ver agentes/README.md). Crear los agentes es parte del trabajo de cada proyecto, no un copy-paste.
Formato
Los agentes son agentes nativos (los que aparecen en /agents). Se definen como archivo
.md en .claude/agents/ con front matter:
---
name: nombre-del-agente
description: Rol + límites del agente en una frase breve (ver abajo)
model: opus | sonnet | haiku
tools: lista de tools y skills permitidos
---
## Expertise
[Sección de identidad]
## Responsabilidades
[Qué hace]
## Reglas
[Lo que siempre/nunca hace — incluye cuándo NO invocarse y política de batch]
## Estándares específicos
[Extensión de los estándares base para su dominio]El campo model es obligatorio: cada agente declara el modelo más económico que ejecuta
bien su tarea (ver tabla en efficiency.md). Si un agente combina tareas de
juicio y tareas mecánicas, se divide en dos agentes antes de aceptar un modelo intermedio.
El campo description: rol + límites
La primera frase del description es lo único que se usa para desambiguar entre
agentes: el orquestador la carga para decidir a quién invocar. Por eso es rol + límites,
breve y sin ambigüedad — “implementa backend en apply; no revisa ni decide arquitectura”, no
un párrafo de cuándo invocarse.
Importa para tokens: las descripciones de los agentes se cargan en el contexto del orquestador
de forma permanente (en cada prompt donde decide routing). Un description largo se paga una
y otra vez. La lógica de cuándo invocar no va aquí — va en la skill que orquesta el ciclo
(ver “Dónde viven las decisiones de invocación” y efficiency.md).
La sección Expertise
Cada agente abre con una sección de expertise/rol que le da el contexto de identidad correcto — no solo qué hacer, sino desde qué perspectiva pensar. Esto mejora la calidad de las decisiones cuando el agente enfrenta ambigüedad. Define:
- El perfil técnico que debe adoptar: no “eres un desarrollador”, sino “eres un desarrollador backend senior con 10 años construyendo APIs (Application Programming Interface) de alto tráfico en fintech”
- Las tecnologías en las que es experto: específicas al stack del proyecto
- El criterio de calidad que aplica: qué considera inaceptable, qué prioriza ante trade-offs
Acelerador (opcional). Redactar bien la
Expertise, eldescriptiony losinstructionde los stages es trabajo de prompt-engineering. Un metaprompt (un comando que toma tu intención y la estructura con buenas prácticas, haciéndote las preguntas que faltan) ayuda a no improvisar esa redacción. Es genérico, no específico de Argui — ver el catálogo en templates/commands/ y dependencies.md.
Por qué la identidad importa
Un agente sin identidad responde con el promedio de todo lo que sabe. Un agente con identidad responde desde una perspectiva — y las perspectivas son las que detectan problemas.
El ejemplo más claro: si el mismo agente implementa y revisa, el sesgo de confirmación gana siempre. El agente revisor existe como agente separado precisamente porque su identidad es encontrar problemas, no justificar decisiones.
Roles arquetípicos
Todo proyecto Argui cubre al menos estos roles. Cómo se materializan (cuántos agentes, con qué especialización) depende del proyecto:
| Rol | Función | Se crea en |
|---|---|---|
| PRD (Product Requirements Document) | Ajustar, mejorar y mantener los PRDs | F2.2 — tras el primer borrador de PRD |
| UX/UI (experiencia / interfaz de usuario) | Construir e iterar el prototipo trazable | F3.1 |
| Arquitecto | Decisiones técnicas de alto nivel, árbitro de ambigüedad | F4.2 — antes del backlog |
| Backlog | Construir el backlog con dependencias claras | F4.3 |
| Implementador(es) | Escribir el código siguiendo estándares | F4.7 |
| Revisor(es) | Encontrar problemas en el código de otros | F4.7 |
| Tester(s) | Diseñar y validar pruebas, guiar la fase de QA (Quality Assurance) | F4.7 |
| Documentador / progreso | Mantener la documentación, el CLAUDE.md vivo y el diagrama de dependencias del backlog (regenerándolo desde los items en el paso de progreso) | F4.7 |
Según el proyecto pueden necesitarse implementadores separados por dominio (backend, frontend, infra) — la regla es que cada uno extienda los estándares base con los criterios de su dominio.
Dónde viven las decisiones de invocación
Las decisiones de cuándo invocar a un agente — el gate de impacto arquitectónico, batch vs. fanout, resolver con una skill desde el padre en vez de abrir un subagente, qué agentes corren en cada acción — no viven en los archivos de los agentes. Viven en las skills de OpenSpec que orquestan el ciclo (la personalización de apply/verify/qa/archive que se define en la fase 4 — ver workflow.md, F5.1).
Por qué: duplicar esa lógica en cada agente infla su frontmatter —que se carga en cada prompt de routing— y reparte en N archivos una decisión que es del orquestador. Centralizada en la skill, se carga solo cuando esa acción corre.
El archivo del agente declara entonces solo lo que es suyo:
- Identidad (sección Expertise): rol, tecnologías, criterio de calidad.
- Reglas de comportamiento: lo que siempre/nunca hace por su naturaleza (p. ej. el revisor nunca aprueba su propio trabajo; usar context7 antes de escribir contra una librería). No reglas de cuándo se le invoca.
- Modelo (qué tier usa) y las skills/MCPs (Model Context Protocol) que puede usar (ver siguiente sección).
Una skill bien aplicada por un agente económico frecuentemente supera a un agente caro sin skill — por eso el agente declara las suyas, aunque la decisión de invocarlo sea del orquestador.
Relación con skills y MCPs
Cada agente usa siempre los skills y MCPs disponibles en el proyecto que le correspondan. Esta instrucción debe ser explícita en la definición del agente, listando cuáles le aplican.
Ejemplo de un agente bien definido
---
name: implementer-backend
description: Implementa endpoints y lógica de backend en apply; no revisa ni decide arquitectura
model: sonnet
tools: Read, Edit, Write, Bash, context7
---
## Expertise
Eres un desarrollador backend senior especializado en Python y FastAPI con 8+ años
construyendo APIs para productos SaaS. Escribes código que otros pueden leer, mantener y
extender — no código que impresiona.
**Tecnologías**: Python 3.11+, FastAPI, SQLAlchemy, PostgreSQL, Docker
**Criterio de calidad**: en un PMV la velocidad importa pero la calidad no se negocia. Un
cambio es aceptable si: cumple la especificación, está cubierto por tests críticos, sigue
los estándares del proyecto y no deja deuda no documentada.
## Responsabilidades
1. Implementar los cambios del ciclo OpenSpec (acción apply)
2. Seguir los estándares base y los específicos de backend
3. Escalar al arquitecto las decisiones de diseño no especificadas (no las toma)
4. Dejar el cambio listo para verify: completo, con tests críticos, sin TODOs ocultos
## Reglas
- Nunca revisa ni aprueba su propio trabajo
- Escala al arquitecto las decisiones de diseño no especificadas (no las toma)
- Usa context7 antes de escribir código contra una librería externa
> El *cuándo* invocarlo —batch de archivos, no abrirlo para cambios triviales— vive en la
> skill de apply, no en este archivo.
## Estándares específicos
- Endpoints RESTful, versionado en header; respuestas `{ data, error, timestamp }`
- Errores: HTTP status estándar + código propio (`ERR_USER_NOT_FOUND`)
- Logging con structlog: `request_id`, `user_id`, `action`
- Tests en pytest; cobertura completa de funcionalidades críticas