Guía Maestra de Arquitectura Agentic

Documento para diseñar, evaluar y evolucionar proyectos que usan AGENTS.md, Agent Skills y agentes/sub-agentes con runtimes como GitHub Copilot, Claude (Anthropic), OpenCode o Codex.

Este documento no describe un proyecto concreto. Sirve como marco de referencia para mejorar procesos y arquitectura en proyectos reales.

0. Cómo leer este documento

Si eres humano: úsalo como manual de diseño y auditoría.
Si eres IA: úsalo como modelo de responsabilidades (qué vive en el repo, qué vive en el runtime).

Regla general: el repo declara (reglas + capacidades). El runtime interpreta y ejecuta.

1. Mapa mental global

┌──────────────────────────────────────────────┐
│                 AGENTS.md                   │
│      (contrato global del repositorio)       │
└──────────────────────────────────────────────┘
                    │
                    │ define reglas y límites
                    ▼
┌──────────────────────────────────────────────┐
│              AGENT RUNTIME                   │
│  (Copilot / Claude / OpenCode / Codex)       │
└──────────────────────────────────────────────┘
        │                    │
        │                    ├─ orquesta SUB-AGENTS (roles)
        │                    │
        │                    ├─ descubre y carga AGENT SKILLS
        │                    │   cuando son relevantes
        │                    │
        ▼                    ▼
┌──────────────────┐   ┌──────────────────────┐
│     AGENTES      │   │     AGENT SKILLS     │
│ (roles cognitivos│   │ (procedimientos      │
│  analysis, impl…)│   │  reutilizables)      │
└──────────────────┘   └──────────────────────┘
                            │
                            ├─ templates
                            ├─ scripts
                            ├─ ejemplos
                            └─ checklists

Principios clave

El repo no ejecuta ni orquesta.
El repo describe y enseña.
El runtime decide qué agente y qué skill usar.

2. Glosario mínimo (para humanos e IA)

Término	Definición corta
Runtime (host/orquestador)	Sistema que interpreta la tarea, carga contexto, decide roles (sub-agentes) y ejecuta acciones.
AGENTS.md	Contrato estable del repo: reglas, límites, arquitectura, Definition of Done.
Agente	Unidad de trabajo explícita con responsabilidad declarada (p. ej. implementar, testear).
Sub-agente	Fase cognitiva interna del runtime (planner, reviewer…), no invocable ni persistente.
Skill (Agent Skill)	Procedimiento reusable cargable bajo demanda (SKILL.md + recursos).
Template	Esqueleto que reduce ambigüedad (código/markdown/checklists/contratos).
Script	Automatización ejecutable (verificaciones, scaffolding, checks).
Example	Referencia válida del patrón correcto (no es tutorial).
Checklist	Lista de verificación para reducir fallos y asegurar DoD.

3. Componentes del sistema (orden correcto)

3.1 Runtime (host/orquestador)

Qué es

El runtime es el “cerebro operativo” que:
- entiende la tarea
- decide estrategia
- carga contexto
- ejecuta tools/scripts
- valida resultados

Qué NO es

No es el repositorio.
No es un archivo de instrucciones.

Qué lugar ocupa en el flujo

Vive entre la petición del usuario y los cambios en el repo.
Es quien conecta AGENTS.md + agentes + skills.

3.2 AGENTS.md (ideal)

Qué es

AGENTS.md es el punto de entrada cognitivo de un repositorio para cualquier sistema agentic. No es un prompt puntual, sino un contrato estable y persistente que define cómo debe comportarse una IA dentro de este código base.

Desde el punto de vista de un humano:

Es la constitución del proyecto.
Marca límites, prioridades y reglas no negociables.

Desde el punto de vista de una IA:

Es el marco de referencia que condiciona todas las decisiones posteriores.
Actúa como filtro: qué está permitido, qué está prohibido y qué se considera correcto.

Qué lugar ocupa en el flujo

AGENTS.md se lee antes de cualquier decisión:

Antes de analizar
Antes de planificar
Antes de ejecutar

No participa en la ejecución, pero condiciona todo lo que ocurre después.

Qué NO debe hacer

No definir pasos detallados.
No describir procedimientos completos.
No referenciar sub-agentes.
No orquestar ni invocar skills.

Qué SÍ debe contener (plantilla canónica)

# AGENTS.md

## Purpose

Este repositorio implementa <dominio>. Los agentes deben priorizar
consistencia, seguridad y cambios mínimos.

## Allowed scope

- Se permite modificar: src/**, tests/**
- Prohibido modificar: infra/, legacy/, scripts/prod/

## Workflow constraints

- Siempre analizar antes de ejecutar
- No modificar código sin aprobación explícita
- Commits atómicos y descriptivos

## Architecture

- Arquitectura hexagonal / limpia
- Controllers delgados
- Dominio sin dependencias externas

## Quality gates

- Tests obligatorios
- Lint sin errores
- Coverage mínima definida por módulo

## Definition of Done

- Código compila
- Tests pasan
- Cambio documentado

Pregunta a la que responde AGENTS.md

“¿Cuáles son las reglas del juego en este repositorio?”

3.3 Agentes

Qué es un agente

Un agente es una unidad de trabajo explícita, con una responsabilidad clara y un propósito reconocible por el runtime.

Desde el punto de vista humano:

Representa un tipo de trabajo completo (implementar, testear, documentar).
Puede pensarse como un perfil o rol autónomo.

Desde el punto de vista de una IA:

Es una configuración estable de objetivos, límites y expectativas.
Sirve para ejecutar tareas de forma consistente dentro de un marco de reglas (AGENTS.md) y capacidades (Agent Skills).

Qué NO es un agente

No es un script.
No es una función.
No es una fase interna (eso serían sub-agentes).

Qué lugar ocupa en el flujo

El agente se selecciona después de entender la tarea y antes de ejecutar acciones. Es la “envoltura” dentro de la cual el runtime activará sub-agentes y skills.

Portabilidad (importante)

Un agente puede ser reutilizable entre tareas y proyectos, pero no es obligatorio. En la práctica existen tres niveles válidos:

Global: reutilizable en muchos repos (ej. Implementation Agent, Testing Agent).
De familia/plataforma: reutilizable en repos similares (mismo stack/arquitectura).
De proyecto: diseñado para un repositorio concreto (dominio, legacy, restricciones propias).

La regla es simple: lo importante no es que sea portable, sino que su responsabilidad, límites y entradas/salidas estén declarados con claridad.

Un agente es una unidad de responsabilidad declarada, pensada para ser:

descubierta por el runtime
seleccionada explícita o implícitamente
global, de familia o de proyecto (según convenga)

Los agentes sí pueden documentarse como artefactos formales.

Plantilla canónica de agente (artefacto)

Incluye name y description, compatible con OpenCode, GitHub Copilot y Claude.

---
name: Example Implementation Agent
description: Implementa cambios de código siguiendo AGENTS.md y Agent Skills disponibles.
---

# Rol

Agente responsable de implementar cambios en el código de producción.

# Alcance

- Puede modificar src/\*\*
- No puede modificar infra/ ni legacy/

# Responsabilidades

- Traducir análisis aprobado en código
- Usar templates y skills existentes

# Entradas esperadas

- Análisis aprobado
- Requisitos claros

# Salidas esperadas

- Código compilable
- Commits atómicos

# Reglas

- No introducir lógica fuera del dominio
- No duplicar patrones existentes

3.4 Sub-agentes

Qué es un sub-agente

Un sub-agente es una fase cognitiva interna que el runtime activa para resolver una parte concreta del problema.

Desde el punto de vista humano:

Son etapas mentales: pensar, hacer, revisar.

Desde el punto de vista de una IA:

Son modos internos de razonamiento y acción.
No tienen identidad persistente.

Qué NO es un sub-agente

No es seleccionable
No es reutilizable entre proyectos como artefacto
No vive en el repositorio

Qué lugar ocupa en el flujo

Los sub-agentes actúan dentro de un agente, encadenándose según la complejidad de la tarea:

primero planificación
luego ejecución
finalmente validación

Diferencia fundamental

Agentes	Sub-agentes
Son seleccionables	Son internos
Tienen identidad (`name`, `description`)	No tienen identidad propia persistente
Pueden invocarse explícitamente	Se activan implícitamente
Pueden vivir como artefactos documentables	Viven solo en el runtime

Un agente es una unidad de trabajo completa. Un sub-agente es una fase cognitiva dentro de un agente.

Mapa conceptual correcto de sub-agentes

Agente seleccionado
 │
 ├─ Planner
 │   • Entiende la tarea
 │   • Divide en pasos
 │   • Identifica skills relevantes
 │
 ├─ Implementer
 │   • Aplica templates
 │   • Escribe o modifica artefactos
 │   • Ejecuta scripts si existen
 │
 ├─ Reviewer
 │   • Verifica reglas de AGENTS.md
 │   • Detecta riesgos y desviaciones
 │   • Sugiere correcciones
 │
 └─ Validator / Tester
     • Ejecuta checks
     • Verifica outputs
     • Confirma Definition of Done

Mapa mental específico de sub-agentes (vista ampliada)

Tarea del usuario
      │
      ▼
Agente seleccionado (ej: Implementation Agent)
      │
      ├─ Sub-agente: Planner
      │   • Interpreta la petición
      │   • Identifica restricciones (AGENTS.md)
      │   • Detecta skills relevantes
      │
      ├─ Sub-agente: Context Builder
      │   • Carga archivos relevantes
      │   • Aplica scope permitido
      │   • Reduce ruido
      │
      ├─ Sub-agente: Implementer
      │   • Aplica templates
      │   • Modifica artefactos
      │   • Ejecuta scripts (si existen)
      │
      ├─ Sub-agente: Reviewer
      │   • Verifica reglas
      │   • Detecta desviaciones
      │   • Señala riesgos
      │
      └─ Sub-agente: Validator
          • Ejecuta checks
          • Valida Definition of Done
          • Confirma outputs

Documentación recomendada de sub-agentes (en el repo, solo referencia)

Aunque los sub-agentes no se definen en el repositorio (son mecánica interna del runtime), sí es útil mantener un documento “reference only” para humanos e IAs que explique el flujo cognitivo típico.

Ubicación recomendada:

<repo>/
└── context/
    ├── runtime-model.md          # Explica Planner/Implementer/Reviewer/Validator
    └── subagents-reference.md    # “Reference only”, no invocable

Ejemplo de context/runtime-model.md:

# Runtime model (Sub-agents) — Reference only

Los sub-agentes NO son configurables desde el repo.
Este documento solo describe el flujo cognitivo típico.

## Sub-agent: Planner

- Entiende la petición
- Identifica restricciones (AGENTS.md)
- Sugiere skills a cargar
- Define checks de validación

## Sub-agent: Context Builder

- Carga archivos relevantes
- Aplica scope permitido
- Reduce ruido

## Sub-agent: Implementer

- Aplica templates
- Modifica artefactos
- Ejecuta scripts (si existen)

## Sub-agent: Reviewer

- Verifica reglas y estructura
- Detecta riesgos y desviaciones

## Sub-agent: Validator

- Ejecuta checks/tests
- Confirma Definition of Done

Clave importante

Ningún sub-agente existe fuera de esta ejecución.
Ningún sub-agente es invocable directamente.
El runtime puede omitir, repetir o reordenar sub-agentes.

Ejemplo narrativo de sub-agentes en acción

Petición del usuario

“Añade un endpoint GET para recuperar pedidos”

Planner: propone plan + skills (ej. create-endpoint)
Context Builder: carga módulos, reglas y ejemplos relevantes
Implementer: aplica templates y cambia artefactos
Reviewer: verifica reglas de AGENTS.md y estructura
Validator: ejecuta checks/tests y confirma DoD

El usuario solo ve el resultado. El repo no sabe qué sub-agentes se activaron.

Sub-agente como artefacto (opcional y no estándar)

Esto es un artefacto documental (o configuración interna si tu runtime lo permite). No es un estándar universal.

Opción 1: Documento MD (para humanos + IA)

---
name: SubAgent Planner (Reference)
description: Fase cognitiva interna para descomponer tareas, detectar skills relevantes y planificar validaciones.
---

# Qué es

Sub-agente interno. No debe ser invocado por el usuario.

# Qué hace

- Traduce la petición en un plan de pasos
- Identifica restricciones de AGENTS.md
- Propone skills a cargar
- Define criterios de validación

# Qué NO hace

- No modifica código
- No ejecuta scripts

# Entradas

- Petición del usuario
- AGENTS.md
- Contexto del repo

# Salidas

- Plan en pasos
- Lista de archivos a tocar
- Skills sugeridas
- Checks recomendados

Opción 2: Config interna (pseudo-código)

# runtime/subagents/planner.yaml (ejemplo conceptual)
name: planner
enabled: true
responsibilities:
  - plan
  - skill_selection
  - risk_identification
constraints:
  - must_read: AGENTS.md
  - must_propose_validation: true
outputs:
  - plan_steps
  - suggested_skills
  - validation_checks

Regla de oro

Agentes = contratos explícitos Sub-agentes = mecánica interna del runtime

3.5 Agent Skills (modelo unificado)

Qué es una Agent Skill

Una Agent Skill es una capacidad reutilizable, autocontenida y cargable bajo demanda que enseña al agente cómo hacer algo concreto dentro de un ecosistema.

Ejemplos:

Crear endpoints
Ejecutar y arreglar tests
Crear PRs
Sincronizar documentación

Qué NO es una skill

No es un agente
No decide cuándo se usa
No conoce otros skills
No orquesta flujos completos

Qué lugar ocupa en el flujo

Se carga cuando el runtime detecta relevancia.
Actúa como “manual operativo” + “pack de recursos” para una tarea concreta.

Estructura ideal de una skill

skills/
└── create-endpoint/
    ├── SKILL.md
    ├── templates/
    │   ├── Controller.template
    │   ├── UseCase.template
    │   └── Repository.template
    ├── scripts/
    │   └── verify.sh
    ├── examples/
    │   └── basic-get.md
    └── checklist.md

SKILL.md (plantilla canónica)

# Skill: create-endpoint

## When to use

Cuando se necesita exponer una nueva API pública.

## Preconditions

- Análisis aprobado
- Contrato HTTP definido

## Conceptual steps

1. Seleccionar template adecuado
2. Adaptar nombres y contratos
3. Conectar con el dominio
4. Validar integración

## Output

- Endpoint funcional
- Controller sin lógica

## Anti-patterns

- Lógica en controller
- Copiar código sin adaptar

3.6 Templates / Scripts / Examples / Checklists

Templates (diseño ideal)

Qué es un template Un template es un artefacto reutilizable que reduce ambigüedad y decisiones. No tiene por qué ser código: puede ser código, markdown, checklist, contratos, prompts estructurados o esqueletos de análisis.

Tipos recomendados:

Templates de código (imponen estructura técnica)

public class ${ENTITY}Controller {

  // NO añadir lógica aquí

  private final ${USE_CASE} useCase;

  public Response execute(${REQUEST} request) {
    return useCase.execute(request);
  }
}

Templates de análisis (markdown)

# Analysis Template

## Context

## Decision

## Constraints

## Risks

## Open questions

Templates de checklist

- [ ] Análisis aprobado
- [ ] Tests definidos
- [ ] Impacto documentado
- [ ] Riesgos identificados

Templates de contrato / input esperado

## Required inputs

- Endpoint / feature
- Scope permitido
- Restricciones técnicas
- Resultado esperado

Templates de salida

## Output

- Archivos creados/modificados
- Commits realizados
- Tests ejecutados
- Pendientes

Scripts

Qué son:

automatizaciones ejecutables (validación, scaffolding, checks)

Ejemplo:

#!/usr/bin/env bash
set -e
pnpm lint
pnpm test

Examples

Los ejemplos:

No son tutoriales
Son referencias válidas
Muestran el patrón correcto

# Example: GET /orders/{id}

- Pattern: Query
- Auth: Required
- Errors: 404, 403

Checklists

Las checklists sirven para convertir “buenas prácticas” en verificaciones repetibles.

4. Portabilidad y dónde vive cada cosa

4.1 Mini-tabla: global / familia / proyecto

Se recomienda revisar la documentación oficial de Claude, Opencode... esto es sólo una oreintación

Artefacto	Qué es	Nivel típico	Dónde vive (recomendado)	Ejemplos
AGENTS.md	Contrato del repo (reglas, límites, DoD)	Proyecto	Raíz del repo	`AGENTS.md`
Agente	Unidad de trabajo explícita (rol completo)	Global / Familia / Proyecto	`agents/` (si lo soportas) o biblioteca compartida	`implementation-agent.md`
Sub-agente	Fase cognitiva interna del runtime	Runtime-interno	(No vive en el repo)	planner, reviewer
Skill	Procedimiento reusable cargable bajo demanda	Global / Familia / Proyecto	`skills/` o `.github/skills/` o `.claude/skills/`	`run-tests/`, `create-pr/`
Template	Esqueleto (código/MD/checklist)	Proyecto o Familia	Dentro de la skill: `templates/`	`Controller.template`
Script	Automatización ejecutable (checks, scaffolding)	Proyecto o Familia	Dentro de la skill: `scripts/`	`verify.sh`
Example	Referencia válida (patrón correcto)	Proyecto o Familia	Dentro de la skill: `examples/`	`basic-get.md`

Regla práctica: si al copiarlo a otro repo puede inducir errores por rutas/dominio/legacy, es de proyecto.

4.2 Skills globales / personales y de plataforma

Estas skills no son del proyecto: son tu biblioteca reutilizable.

Global: útil en casi cualquier repo.
Familia/plataforma: útil en repos similares (mismo stack/arquitectura).

Ubicaciones típicas (según runtime):

~/.copilot/skills/        # Skills personales (Copilot)
~/.claude/skills/         # Skills personales (Claude / Claude Code)
~/.opencode/skills/       # Skills personales (OpenCode) (si se adopta este patrón)

5. Estructura de carpetas (implementación)

Idea central: los sub-agentes no son artefactos del repo.
En una arquitectura agentic declarativa, los sub-agentes (planner/reviewer/validator…) viven dentro del runtime y aparecen/desaparecen durante la ejecución.
Por tanto, no existe una carpeta canónica tipo subagents/ para configurarlos.

Si quieres reflejarlos en el repo, hazlo como documentación de referencia, por ejemplo en context/runtime-model.md (ver sección 3.4 Sub-agentes).

5.1 Estructura canónica dentro del repo (agnóstica)

<repo>/
├── AGENTS.md
├── agents/                       # Opcional: agentes formales del proyecto
│   ├── implementation-agent.md
│   ├── testing-agent.md
│   └── docs-agent.md
├── skills/                       # Skills del proyecto
│   ├── create-endpoint/
│   │   ├── SKILL.md
│   │   ├── templates/
│   │   ├── scripts/
│   │   └── examples/
│   ├── run-tests/
│   └── create-pr/
└── context/                      # Opcional: ADRs, guías, decisiones
    ├── adr/
    └── ...

5.2 Variantes por runtime (misma idea, distinta ruta)

A) GitHub Copilot (repo)

<repo>/
├── AGENTS.md
└── .github/
    └── skills/
        ├── create-endpoint/
        │   ├── SKILL.md
        │   ├── templates/
        │   └── scripts/
        └── run-tests/
            └── SKILL.md

B) Claude (repo)

<repo>/
├── AGENTS.md
└── .claude/
    └── skills/
        ├── create-endpoint/
        │   ├── SKILL.md
        │   ├── templates/
        │   └── scripts/
        └── run-tests/
            └── SKILL.md

C) OpenCode (repo)

<repo>/
├── AGENTS.md
└── skills/
    ├── create-endpoint/
    │   ├── SKILL.md
    │   ├── templates/
    │   └── examples/
    └── run-tests/
        └── SKILL.md

5.3 Anti-patrón (a evitar)

<repo>/
└── subagents/
    ├── planner.md
    ├── reviewer.md
    └── validator.md

Por qué es un anti-patrón: hace creer que los sub-agentes son artefactos estándar del repo y portables entre runtimes.
Si quieres comportamiento repetible, ponlo en skills, templates, scripts o políticas (AGENTS.md).

6. Ejemplos end-to-end (cómo se ve en la práctica)

6.1 Ejemplo: “crear un endpoint”

Agente típico: Implementation Agent
Sub-agentes internos: Planner → Context Builder → Implementer → Reviewer → Validator
Skills típicas: create-endpoint + run-tests
Artefactos: controller/usecase/repository + tests + docs/PR

6.2 Ejemplo: “crear tests”

Agente típico: Testing Agent
Skills: run-tests, write-tests, coverage-check

6.3 Ejemplo: “crear PR / release”

Agente típico: Docs/Release Agent
Skills: create-pr, write-changelog, tag-release

7. Anti-patrones (errores comunes)

Usar AGENTS.md como si fuera un script paso-a-paso.
Meter lógica de negocio en templates “por conveniencia”.
Convertir sub-agentes en artefactos estándar del repo.
Crear skills globales que dependen de rutas concretas del proyecto.
Duplicar conocimiento: la misma regla en AGENTS.md + en cada skill.

8. Reglas de oro y checklist final

Reglas de oro

AGENTS.md = constitución
Skills = procedimientos
Templates = guardarraíles
Agentes = roles explícitos
Sub-agentes = mecánica interna
Runtime = orquestación y ejecución

Checklist rápida

AGENTS.md define scope, arquitectura y DoD
Las skills son autocontenidas (SKILL.md + recursos)
Los templates tienen variables claras y zonas de edición
No hay “sub-agentes” modelados como artefactos obligatorios
Está claro qué es global/familia/proyecto y dónde vive

AlexAlonsoMontero/guia.md

Guía Maestra de Arquitectura Agentic

0. Cómo leer este documento

1. Mapa mental global

2. Glosario mínimo (para humanos e IA)

3. Componentes del sistema (orden correcto)

3.1 Runtime (host/orquestador)

3.2 AGENTS.md (ideal)

Qué es

Qué NO debe hacer

Qué SÍ debe contener (plantilla canónica)

3.3 Agentes

Plantilla canónica de agente (artefacto)

3.4 Sub-agentes

Diferencia fundamental

Mapa conceptual correcto de sub-agentes

Mapa mental específico de sub-agentes (vista ampliada)

Documentación recomendada de sub-agentes (en el repo, solo referencia)

Ejemplo narrativo de sub-agentes en acción

Sub-agente como artefacto (opcional y no estándar)

Regla de oro

3.5 Agent Skills (modelo unificado)

Estructura ideal de una skill

SKILL.md (plantilla canónica)

3.6 Templates / Scripts / Examples / Checklists

Templates (diseño ideal)

Scripts

Examples

Checklists

4. Portabilidad y dónde vive cada cosa

4.1 Mini-tabla: global / familia / proyecto

4.2 Skills globales / personales y de plataforma

5. Estructura de carpetas (implementación)

5.1 Estructura canónica dentro del repo (agnóstica)

5.2 Variantes por runtime (misma idea, distinta ruta)

5.3 Anti-patrón (a evitar)

6. Ejemplos end-to-end (cómo se ve en la práctica)

6.1 Ejemplo: “crear un endpoint”

6.2 Ejemplo: “crear tests”

6.3 Ejemplo: “crear PR / release”

7. Anti-patrones (errores comunes)

8. Reglas de oro y checklist final