Cápsulas y Agentes de IA en Desarrollo de Productos

Cápsulas en Acción: Integrando Agentes de IA para la Automatización del Desarrollo

Los agentes de IA en el desarrollo de productos requieren una estructura de contexto estricta. Las cápsulas proporcionan conocimiento experto en un formato minimalista con herramientas listas para usar, garantizando una generación predecible de código y artefactos arquitectónicos. Esto elimina la evolución caótica de la arquitectura durante tareas secuenciales.

Modos de Agente y el Papel de la Estructura

Los agentes se utilizan en la creación de prototipos y el desarrollo de productos. En la creación de prototipos, el enfoque está en resultados rápidos sin restricciones. En los productos, los requisitos no funcionales son obligatorios: mantenibilidad, legibilidad, escalabilidad.

Sin estructura, un agente toma decisiones arbitrarias, perdiendo uniformidad en el servicio. Una cápsula resuelve esto mediante tres componentes:

• Conocimiento Experto: Experiencia empaquetada sin conjeturas.
• Minimalismo: La esencia sin información extra para la ventana de contexto.
• Herramienta Lista para Usar: Métodos, habilidades, interfaces para agentes.

El contexto adicional del proyecto se almacena en AGENTS.md y CLAUDE.md — guías de estilo, formatos de commit.

Transferencia de Conocimiento mediante Servidor MCP

El conocimiento experto se transfiere al agente mediante un servidor MCP con dos herramientas:

• Documentación del Framework: Principios, estructura de servicio, patrones BaseMethod, contenedor DI, eventos.
• Documentación de archland.json: Formato, reglas de llenado, generación de diagramas C4.

La separación ahorra tokens: el agente solicita la herramienta relevante. Los documentos están orientados al agente — estilo imperativo, reglas, algoritmos.

Ejemplo de la documentación del framework nsc-toolkit:

# Framework nsc-toolkit: Guía de Generación de Código

Este documento está estructurado como un conjunto de reglas y plantillas
para la generación automática de código correcto.

## Núcleo del Framework: Clase Método (BaseMethod)

Reglas de implementación:
- Declarar una propiedad estática settings,
  copiada de service.schema.json.
- La lógica principal se implementa en el método handler.
- Inyectar dependencias vía constructor con decorador @inject.
- Usar this.logger para registro.
- Usar this.emitter para generación de eventos.

REGLAS: Crear un método para cada llamada RPC de service.schema.json.
REGLAS: Solo las dependencias actuales y usadas deben vincularse al contenedor.

Algoritmo para archland.json:

Algoritmo de generación para cada servicio:

Paso 1. Información básica:
  - Leer service.schema.json → nombre, descripción
  - Escribir rutas: describePath, folderPath

Paso 2. Análisis del contenedor DI:
  - Leer service.ts
  - Para cada container.bind() crear un objeto Dependency
  - Analizar etiquetas para tipo y externo

Paso 3. Análisis de métodos:
  - Para cada clase en methods/:
    leer service.schema.json para descripción
    analizar código para llamadas de dependencia y generación de eventos

Paso 4. Análisis de suscripciones:
  - Para cada clase en processing/:
    determinar clave DI desde inversion.types.ts
    analizar método start() para determinar servicio fuente

Paso 5. Recolectar todos los datos en un único objeto archland.json

Práctica: Añadiendo un Método ListOrders

Escenario: Un método para listar los pedidos del usuario en el servicio @services/order con exposición a la API HTTP.

El desarrollador describe el formato de datos. El agente genera el esquema en service.schema.json:

"ListOrders": {
  "action": "ListOrders",
  "description": "Recuperación de una lista de pedidos del usuario",
  "request": {
    "type": "object",
    "properties": {
      "credentials": {
        "type": "object",
        "properties": {
          "user_id":  { "type": "string" },
          "space_id": { "type": "string" }
        },
        "required": ["user_id", "space_id"]
      }
    },
    "required": ["credentials"]
  },
  "response": {
    "type": "object",
    "properties": {
      "result": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "order_id":   { "type": "string" },
                "product_id": { "type": "string" },
                "quantity":   { "type": "number" },
                "created_at": { "type": "string" }
              },
              "required": ["order_id", "product_id", "quantity", "created_at"]
            }
          }
        }
      }
    },
    "required": ["result"]
  }
}

Prompt para el agente:

Crea un nuevo método ListOrders en el servicio @services/order.
El método acepta: user_id desde credentials.
Devuelve: una lista de pedidos, cada uno con campos order_id, product_id, quantity, created_at.
Expón el método en @services/gate en el conjunto de endpoints @services/gate/routes/orders.ts.

Secuencia de acciones del agente:

• Lee CLAUDE.md → solicita documentación MCP.
• Añade esquema a service.schema.json.
• Ejecuta generación de código usando plantillas.
• Implementa lógica de negocio con @inject, puertos.
• Añade endpoint HTTP siguiendo el patrón.
• Forma un commit según las reglas.

Tiempo: 10 minutos. La plantilla es reproducible para tareas similares.

Generando un Álbum Arquitectónico

Prompt: Genera archland.json y el álbum arquitectónico del proyecto.

El agente recupera documentación de MCP, recorre servicios, analiza esquemas, DI, métodos, suscripciones. Recolecta datos en archland.json con diagramas C4 de áreas problemáticas. El proceso es determinista basado en el algoritmo de la documentación.

Conclusiones Clave

• Las cápsulas proporcionan estructura para agentes en desarrollo de productos.
• El servidor MCP transfiere conocimiento experto mediante herramientas minimalistas.
• La documentación es imperativa: reglas, algoritmos, plantillas para agentes.
• Automatización de tareas: generación de código, endpoints HTTP, álbumes de arquitectura en 10 min.
• Predictibilidad: arquitectura uniforme sin cambios caóticos.

— Editorial Team