Ir al contenido
AggregaAggrega
Seleccionar idioma: Español
Esta página se tradujo automáticamente. Lee el original en inglés.

Escribir archivos de Aggrega

Redactar en Aggrega es un ciclo corto y repetible. Sea cual sea la entidad que escribas — el Aggregate de un desarrollador, el Component de un arquitecto, una Recipe de operaciones o la Release de un operador —, los mismos cinco pasos te llevan de un archivo vacío a uno validado:

  1. Elige la entidad de la que es responsable tu rol.
  2. Aprende su estructura a partir del JSON Schema y de la página de referencia.
  3. Parte de un esqueleto en lugar de un archivo vacío.
  4. Completa los campos de los que es responsable tu rol, dejando el resto a sus responsables.
  5. Valida y después compila.

Esta página recorre el ciclo una vez, tanto para una persona que redacta a mano como para un asistente de IA que redacta a través del servidor Model Context Protocol. Los dos caminos son el mismo ciclo sobre las mismas fuentes de referencia. Ambos necesitan el binario aggrega: Instalar el binario lo instala con un solo comando.

1. Elige la entidad de la que es responsable tu rol

Aggrega divide la redacción en cuatro roles que colaboran — la intención del desarrollador, el catálogo de la plataforma, las recetas de infraestructura y el cableado del despliegue. Cada rol suele ser responsable de un conjunto específico de tipos de entidad. Si ya conoces tu rol, ve directamente a la entidad que necesitas; si no, lee Personas para conocer los cuatro roles y Entidades por rol para la correspondencia completa entre tipos y roles.

La separación es una orientación, no una regla que el compilador imponga. Un autor que trabaja solo es libre de asumir todos los roles y escribir todas las entidades de una sola vez; el compilador acepta cualquier forma de redactar que supere la validación del esquema. Los roles existen para mantener claras las responsabilidades, no para limitar lo que puedes escribir.

2. Aprende su estructura

Cada tipo de entidad tiene un JSON Schema canónico y una página de referencia campo por campo. Lee ambos antes de escribir:

  • El esquema es la estructura exacta: campos obligatorios, valores permitidos y anidamiento. Desde la línea de comandos, aggrega get-schema <kind> lo imprime; aggrega get-schema --list nombra cada tipo que puedes solicitar. Un asistente lee los mismos bytes desde el recurso schema://<kind>. Consulta la referencia de aggrega get-schema.
  • La página de referencia explica qué significa cada campo y cómo se relacionan los campos. Las páginas de entidades se encuentran en language-reference/entities/ — por ejemplo component o aggregate. Un asistente lee la misma página desde el recurso langref://entities/<kind>.

El esquema te dice qué es estructuralmente válido; la referencia te dice qué es sensato. Lee el esquema para evitar un rechazo en la validación y la referencia para redactar algo que haga lo que pretendes.

3. Parte de un esqueleto

Partir de un esqueleto es más rápido y menos propenso a errores que un archivo vacío. Un asistente conectado al servidor MCP llama a la herramienta scaffold con un tipo y un nombre para obtener un punto de partida mínimo que contiene cada campo que el tipo exige, con un marcador de posición donde aún falte un valor. Si redactas a mano, aggrega scaffold <kind> <name> imprime el mismo punto de partida en la salida estándar, así que redirígelo a un archivo; o copia el ejemplo desarrollado más cercano y redúcelo a lo que necesites.

En ambos casos, el esqueleto ya contiene los campos de nivel superior obligatorios (apiVersion, kind, metadata.name) con la forma correcta, de modo que dedicas tu atención a los campos de los que es responsable tu rol y no al código repetitivo.

4. Completa los campos de los que es responsable tu rol

Completa solo los pilares de los que es responsable tu rol y deja los demás a sus responsables. Un desarrollador aporta la intención de la aplicación y los valores; un arquitecto declara el contrato — los valores que un desarrollador puede aportar, las salidas que proporciona un componente, los sockets que expone —; operaciones asigna ese contrato a un provider específico sin cambiar la superficie orientada al desarrollador; un operador cablea el despliegue. Entidades por rol detalla qué pilares pertenecen a qué rol para cada tipo.

Mantener cada valor en el pilar que controla su responsable es lo que permite que la misma intención del desarrollador apunte a infraestructuras distintas en cada entorno sin que cambie el archivo del desarrollador. Es la razón misma por la que la superficie de redacción está dividida.

Limita la descripción a unos pocos párrafos breves. El metadata.description de una entidad es el texto que un lector encuentra antes de elegirla: se publica con la entidad como su descripción consultable, y aggrega search compara una consulta con él. Escríbelo para ese momento, en párrafos breves — en un bloque plegado description: >, una línea en blanco inicia uno nuevo —, diciendo qué es la entidad, cómo la usa un lector, dónde se realiza y qué no hace. Un límite que un lector debe conocer antes de elegir la entidad también va ahí, expresado brevemente. Todo lo demás — por qué un valor predeterminado es el que es, cómo se comporta una configuración en un destino, qué significa un valor en cada realización — va en comentarios YAML junto al campo o bloque que explica, donde lo leerá quien trabaje con ese campo. Nada en el compilador limita la longitud de una descripción ni actúa según lo que dice, así que mantenerla breve es por el bien del lector.

5. Valida y después compila

Comprueba el archivo antes de confiar en él:

  • Un asistente llama a la herramienta validate, que informa directamente de los errores de esquema y de referencia para que pueda corregir el borrador antes de devolverlo.
  • A mano, aggrega validate <file> comprueba un solo archivo de Component, Feature, Recipe, FeatureRecipe, Workload o Plugin, y aggrega validate --release <release> comprueba todo lo que alcanza una Release, incluidos su Aggregate y su Manifest. aggrega lint aplica las reglas de la disciplina de publicación a una entidad del catálogo, y aggrega inspect resuelve y muestra lo que ve el compilador. Cuando toda la topología está lista, aggrega pull --release <release> resuelve sus dependencias y escribe su lockfile, y aggrega build --release <release> compila después la Release en artefactos por frontera — una compilación fallida indica exactamente qué corregir.

Validar pronto es más barato que una compilación fallida tarde. Redacta, valida, corrige y solo entonces compila.

Redactar con un asistente de IA

El comando aggrega mcp ejecuta un servidor Model Context Protocol que convierte cualquier cliente compatible con MCP en un asistente de redacción que conoce Aggrega. Una vez conectado, el asistente puede:

  • Adoptar un rol mediante los prompts de redacción integrados — uno por persona (desarrollador, arquitecto, operaciones) más una plantilla específica por entidad. Cada prompt enmarca el rol y dirige al asistente al esquema, a la página de referencia y a esta guía, para que sus sugerencias se mantengan dentro de los pilares de los que es responsable el rol.
  • Leer la referencia mediante recursos: schema://<kind> para el JSON Schema de un tipo, langref://<path> para cualquier página de referencia y authoring://<topic> para esta guía.
  • Actuar sobre tu workspace mediante herramientas: scaffold para iniciar un esqueleto correcto, validate para comprobar un borrador, describe para inspeccionar una entidad del catálogo y get-schema para obtener un esquema por tipo.

Todo lo que lee el asistente se sirve desde tu máquina: los esquemas están integrados en el binario, y las páginas de la guía y de la referencia proceden del paquete de documentación guardado en la caché de tu máquina, que el servidor descarga del registro cuando se inicia y no encuentra allí ninguna copia. Leer una página, generar un esqueleto y validar no acceden a la red; donde el paquete no se puede descargar, los esquemas se siguen sirviendo y las páginas no. Para conectar un cliente, sigue Conecta el servidor MCP; Qué puede hacer tu asistente con Aggrega cubre el resto de lo que alcanza. Para el comando en sí, consulta la referencia de aggrega mcp.

Próximos pasos