Que es AiAgentArchitect?
El Problema
Disenar sistemas agenticos es dificil: requisitos vagos, sin estructura estandar, y cada implementacion luce diferente. Sabes que Claude Code puede construir sistemas multi-agente — pero por donde empiezas? Como estructuras los archivos? Como sabes si elegiste los tipos de entidad correctos?
La mayoria de los equipos terminan con uno de dos resultados:
- Todo en CLAUDE.md — un solo archivo que crece a miles de lineas, se carga en cada sesion y se vuelve imposible de mantener
- Agentes sin estructura — archivos sin convenciones de nombrado, sin limites claros y sin forma de saber que va donde
Ambos funcionan para casos simples. Ambos colapsan cuando la complejidad crece.
La Solucion
AiAgentArchitect es un framework open-source que resuelve esto con un pipeline guiado — desde la idea en bruto hasta archivos .md listos para produccion — usando una arquitectura estricta basada en entidades y scoring de QA integrado.
No es un wrapper sobre Claude Code. Es un sistema de diseno que produce los archivos que Claude Code lee. Piensa en el como un arquitecto que disena el edificio, donde Claude Code es la obra de construccion.
| Sin AiAgentArchitect | Con AiAgentArchitect | |
|---|---|---|
| Punto de partida | CLAUDE.md en blanco + intuicion | Entrevista estructurada que descubre los requisitos reales |
| Arquitectura | Ad hoc — decides la estructura de archivos sobre la marcha | Blueprint con tipos de entidad, responsabilidades y convenciones de nombrado |
| Seleccion de entidades | Prueba y error | Arbol de decision: 8 preguntas → el tipo de entidad correcto |
| Calidad | Revision manual | QA Layer automatizado: Auditor + Evaluator + Optimizer |
| Evolucion | Editar archivos directamente, esperando que nada se rompa | Modos de iteracion estructurados: PATCH, REFACTOR, EVOLVE |
El Pipeline de 3 Pasos
AiAgentArchitect opera a traves de tres pasos estructurados:
| Paso | Que ocurre | Output |
|---|---|---|
| 1. Descubrimiento | Un agente especialista te entrevista usando tecnicas de BPM/BPA. Hace ingenieria inversa sobre solicitudes vagas, detecta complejidad oculta y valida tus requisitos. | Diagrama AS-IS + JSON de handoff estructurado |
| 2. Arquitectura | Un agente de arquitectura traduce el proceso en un Blueprint: las entidades correctas, responsabilidades definidas, niveles de complejidad asignados. | Blueprint + diagrama de arquitectura |
| 3. Implementacion | Un entity builder materializa el Blueprint en archivos .md correctamente formateados, ubicados en los directorios correctos y listos para usar. | Estructura .claude/ completa |
Cada paso tiene un checkpoint donde apruebas, ajustas o regeneras antes de continuar. Nada se genera sin tu aprobacion explicita.
Arquitectura de Entidades
10 Tipos de Entidad
Cada sistema construido por AiAgentArchitect usa exactamente 10 tipos de entidad. Esto no es arbitrario — cada tipo existe porque resuelve un problema de diseno especifico que ningun otro tipo puede resolver.
| Entidad | Prefijo | Rol |
|---|---|---|
| Workflow | wor- | Orquestador — coordina agentes y pasos |
| Agent Specialist | age-spe- | Ejecuta un dominio especifico de responsabilidad |
| Agent Supervisor | age-sup- | Revisa o valida el output de otros agentes |
| Skill | ski- | Paquete de capacidad reutilizable (herramienta, API, protocolo) |
| Command | com- | Accion directa o procedimiento guardado para tareas frecuentes |
| Rule | rul- | Restriccion que garantiza calidad y consistencia |
| Knowledge Base | kno- | Contexto estatico consultado bajo demanda |
| Resource | res- | Documento de soporte que extiende otras entidades |
| Script | scp- | Procedimiento automatizado ejecutable (validacion, deploy) |
| Hook | hok- | Trigger basado en eventos para acciones automaticas |
Convenciones de Nombrado
Cada archivo de entidad sigue reglas de nombrado estrictas que hacen los sistemas auto-documentados:
- Prefijo — identifica el tipo de entidad de un vistazo (
age-spe-,wor-,rul-, etc.) - Kebab-case — sin espacios, sin mayusculas:
age-spe-email-classifier.md - Limite de nombre — maximo 64 caracteres en el campo
namedel frontmatter - Limite de descripcion — maximo 250 caracteres, siguiendo el patron "que + cuando"
El patron de descripcion "que + cuando" asegura que los agentes sean descubribles:
| Debil | Fuerte ("que + cuando") |
|---|---|
| "Gestiona tickets de soporte." | "Clasifica emails de soporte entrantes por departamento y urgencia. Usar cuando llega un email no estructurado y necesita ser enrutado antes de crear un ticket." |
Mapeo con Claude Code
Esta es la seccion mas importante para entender esta guia. Los 10 tipos de entidad de AiAgentArchitect se mapean a la estructura de directorios de Claude Code — pero el mapeo no siempre es 1:1. Entender donde aterrizan las entidades y por que previene confusiones.
Estructura Nativa de Claude Code
De fabrica, Claude Code reconoce esta estructura:
.claude/
├── commands/ ← slash commands (/name)
├── agents/ ← subagent definitions
├── skills/ ← reusable capability packages
└── settings.json ← hooks, permissionsEso es todo. Claude Code conoce nativamente commands, agents, skills y settings. No tiene un concepto integrado de "Workflows", "archivos de Rules", "Knowledge Bases", "Resources", "Scripts" ni "Hooks como archivos .md".
Mapeo de AiAgentArchitect
AiAgentArchitect extiende esta estructura ubicando sus 10 tipos de entidad en los directorios que Claude Code puede leer:
.claude/
├── commands/ ← wor-*.md (workflows) + com-*.md (commands)
├── agents/ ← age-spe-*.md (specialists) + age-sup-*.md (supervisors)
├── skills/ ← ski-*/SKILL.md
├── rules/ ← rul-*.md (standalone rule files)
├── knowledge-base/ ← kno-*.md (reference material)
├── resources/ ← res-*.md (support documents)
├── scripts/ ← scp-*.sh / scp-*.py (executables)
├── hooks/ ← hok-*.md (hook documentation)
├── settings.json ← hook config + permissions
└── settings.local.json ← CC-exclusive permission overridesEl mapeo completo de entidades
| Tipo de Entidad | Directorio en Claude Code | Patron de Archivo | Adaptacion Clave |
|---|---|---|---|
| Workflow | commands/ | wor-*.md | Los Workflows van en commands/ — CC los trata como slash commands, el prefijo los distingue |
| Agent Specialist | agents/ | age-spe-*.md | Agentes estandar de CC — el prefijo anade claridad de tipo |
| Agent Supervisor | agents/ | age-sup-*.md | Mismo directorio que Specialists — el prefijo distingue el rol |
| Skill | skills/ | ski-*/SKILL.md | Skills estandar de CC — prefijo en el nombre del directorio |
| Command | commands/ | com-*.md | Commands estandar de CC — el prefijo los distingue de los Workflows |
| Rule | rules/ | rul-*.md | No nativo de CC — Claude los lee cuando son referenciados desde CLAUDE.md o instrucciones de agentes |
| Knowledge Base | knowledge-base/ | kno-*.md | No nativo de CC — los agentes los leen bajo demanda via la herramienta Read |
| Resource | resources/ | res-*.md | No nativo de CC — cargados condicionalmente por agentes que necesitan mas detalle |
| Script | scripts/ | scp-*.sh/.py | No nativo de CC — ejecutados via la herramienta Bash por agentes o hooks |
| Hook | hooks/ + settings.json | hok-*.md | La config vive en settings.json (nativo de CC). La documentacion en hok-*.md (no nativo) |
Por Que Este Mapeo?
Tres decisiones de diseno merecen explicacion:
1. Por que los Workflows viven en commands/?
Claude Code no tiene un concepto nativo de "workflow". El mecanismo mas cercano es un command — un archivo en .claude/commands/ que se convierte en un slash command. AiAgentArchitect usa este mecanismo para hacer los Workflows invocables: escribes /wor-content-pipeline y la orquestacion comienza. El prefijo wor- es lo que distingue un workflow de un command simple (com-) — no el directorio.
2. Por que Rules, KBs, Resources, etc. tienen sus propios directorios?
Claude Code no requiere estos directorios. Pero Claude puede leer cualquier archivo en disco con la herramienta Read. Al organizar contenido de referencia en directorios tipados (rules/, knowledge-base/, resources/), los agentes saben exactamente donde buscar — y los humanos pueden navegar el sistema de un vistazo. La convencion es la configuracion.
3. Por que prefijos en lugar de solo directorios?
Porque algunos tipos de entidad comparten directorios. En commands/, encontraras tanto wor-* como com-*. En agents/, encontraras tanto age-spe-* como age-sup-*. El prefijo es lo que te dice — y le dice al sistema — que rol juega cada archivo. Sin prefijos, un listado de archivos en commands/ seria ambiguo.
Beneficios
Que Obtienes
Cada sistema generado por AiAgentArchitect incluye:
| Componente | Que te aporta |
|---|---|
Estructura .claude/ completa | Todos los archivos de entidad en los directorios correctos, con frontmatter, nombrado y referencias cruzadas correctos |
| CLAUDE.md | Contexto a nivel raiz con registro de agentes, reglas activas y logica de orquestacion — ligero y bajo 5KB |
| process-overview.md | Documentacion completa del sistema: que hace, como funciona, inventario de entidades |
| qa-report.md | Registro de auditoria del QA Layer — cada fase puntuada y revisada |
| Persistencia entre sesiones | context-ledger/ para trazabilidad completa + memory/ para reanudacion rapida |
| Control de versiones | Archivo VERSION con versionado semantico, listo para iteracion |
QA Integrado
Cada sesion ejecuta un ciclo de calidad con tres roles automaticamente:
- Auditor — verifica el cumplimiento de reglas despues de cada checkpoint aprobado. Lee las reglas desde disco. Nunca modifica nada.
- Evaluator — puntua cada fase en cuatro dimensiones: Completitud (30%), Calidad (30%), Cumplimiento (25%), Eficiencia (15%).
- Optimizer — lee el historial completo de auditorias, detecta patrones y genera propuestas de mejora priorizadas. Nunca las aplica automaticamente.
El output de QA se anade a qa-report.md — solo en modo append, nunca se sobreescribe. El ciclo es no-bloqueante: acumula evidencia sin detener la ejecucion.
Modos de Iteracion
Una vez que un sistema es exportado, itera sin empezar de cero:
| Modo | Cuando | Que ocurre |
|---|---|---|
| PATCH | Corregir o actualizar entidades especificas | El entity builder edita in situ → incremento de version patch |
| REFACTOR | Reorganizar la arquitectura | El disenador de arquitectura produce un blueprint delta → incremento minor |
| EVOLVE | Anadir nuevas capacidades | Mini-descubrimiento → arquitectura → implementacion → incremento minor/major |
Cada iteracion crea una rama git (ej. iter/0.2.0-add-email-skill). Cuando esta lista, merge a main y etiqueta la version. Reversibilidad total, cero riesgo para el sistema en funcionamiento.