Escrever arquivos do Aggrega
Criar em Aggrega é um ciclo curto e repetível. Qualquer que seja a entidade que você esteja escrevendo — o Aggregate de um desenvolvedor, o Component de um arquiteto, uma Recipe de operações ou a Release de um operador —, os mesmos cinco passos levam você de um arquivo vazio a um arquivo validado:
- Escolha a entidade pela qual sua função é responsável.
- Aprenda sua estrutura a partir do JSON Schema e da página de referência.
- Comece de um esqueleto em vez de um arquivo vazio.
- Preencha os campos pelos quais sua função é responsável, deixando o restante para os respectivos responsáveis.
- Valide e depois compile.
Esta página percorre o ciclo uma vez, tanto para uma pessoa que escreve à mão quanto para um assistente de IA que escreve por meio do servidor Model Context Protocol. Os dois caminhos são o mesmo ciclo sobre as mesmas fontes de referência. Ambos precisam do binário aggrega: Instalar o binário o instala com um único comando.
1. Escolha a entidade pela qual sua função é responsável
Aggrega divide a criação em quatro funções que colaboram — a intenção do desenvolvedor, o catálogo da plataforma, as receitas de infraestrutura e a conexão da implantação. Cada função normalmente é responsável por um conjunto específico de tipos de entidade. Se você já conhece sua função, vá direto para a entidade de que precisa; caso contrário, leia Personas para conhecer as quatro funções e Entidades por função para o mapa completo de tipo para função.
A separação é uma orientação, não uma regra que o compilador impõe. Um autor que trabalha sozinho é livre para assumir todas as funções e escrever todas as entidades de uma só vez; o compilador aceita qualquer forma de criação que passe na validação do esquema. As funções existem para manter as responsabilidades claras, não para restringir o que você pode escrever.
2. Aprenda sua estrutura
Cada tipo de entidade tem um JSON Schema canônico e uma página de referência campo a campo. Leia ambos antes de escrever:
- O esquema é a estrutura exata: campos obrigatórios, valores permitidos e aninhamento. Na linha de comando,
aggrega get-schema <kind>o imprime;aggrega get-schema --listlista cada tipo que você pode solicitar. Um assistente lê os mesmos bytes do recursoschema://<kind>. Consulte a referência deaggrega get-schema. - A página de referência explica o que cada campo significa e como os campos se relacionam. As páginas de entidades ficam em
language-reference/entities/— por exemplo component ou aggregate. Um assistente lê a mesma página do recursolangref://entities/<kind>.
O esquema diz o que é estruturalmente válido; a referência diz o que é sensato. Leia o esquema para evitar uma rejeição na validação e a referência para criar algo que faça o que você pretende.
3. Comece de um esqueleto
Começar de um esqueleto é mais rápido e menos sujeito a erros do que um arquivo vazio. Um assistente conectado ao servidor MCP chama a ferramenta scaffold com um tipo e um nome para obter um ponto de partida mínimo que contém cada campo exigido pelo tipo, com um marcador de posição onde ainda falta um valor. Escrevendo à mão, aggrega scaffold <kind> <name> imprime o mesmo ponto de partida na saída padrão, então redirecione-o para um arquivo; ou copie o exemplo completo mais próximo e reduza-o ao que você precisa.
De qualquer forma, o esqueleto já contém os campos de nível superior obrigatórios (apiVersion, kind, metadata.name) no formato correto, de modo que você dedica sua atenção aos campos pelos quais sua função é responsável, e não a código repetitivo.
4. Preencha os campos pelos quais sua função é responsável
Preencha apenas os pilares pelos quais sua função é responsável e deixe os outros para os respectivos responsáveis. Um desenvolvedor fornece a intenção da aplicação e os valores; um arquiteto declara o contrato — os valores que um desenvolvedor pode fornecer, as saídas que um componente fornece, os sockets que ele expõe; operações mapeia esse contrato para um provider específico sem alterar a superfície voltada ao desenvolvedor; um operador conecta a implantação. Entidades por função detalha quais pilares pertencem a qual função para cada tipo.
Manter cada valor no pilar controlado pelo seu responsável é o que permite que a mesma intenção do desenvolvedor aponte para infraestruturas diferentes em cada ambiente sem que o arquivo do desenvolvedor mude. É o próprio motivo de a superfície de criação ser dividida.
Mantenha a descrição em poucos parágrafos curtos. O metadata.description de uma entidade é o texto que um leitor encontra antes de escolhê-la: ele é publicado com a entidade como sua descrição pesquisável, e aggrega search compara uma consulta com ele. Escreva-o para esse momento, em parágrafos curtos — em um bloco dobrado description: >, uma linha em branco inicia um novo —, dizendo o que a entidade é, como um leitor a usa, onde ela é realizada e o que ela não faz. Um limite que um leitor precisa conhecer antes de escolher a entidade também fica ali, declarado brevemente. Todo o resto — por que um padrão é o que é, como uma configuração se comporta em um destino, o que um valor significa em cada realização — vai em comentários YAML ao lado do campo ou bloco que explica, onde a pessoa que trabalha com esse campo vai lê-lo. Nada no compilador limita o tamanho de uma descrição nem age com base no que ela diz, então mantê-la curta é para o bem do leitor.
5. Valide e depois compile
Verifique o arquivo antes de confiar nele:
- Um assistente chama a ferramenta
validate, que informa diretamente os erros de esquema e de referência para que ele possa corrigir o rascunho antes de devolvê-lo. - À mão,
aggrega validate <file>verifica um único arquivo de Component, Feature, Recipe, FeatureRecipe, Workload ou Plugin, eaggrega validate --release <release>verifica tudo o que uma Release alcança, incluindo seu Aggregate e seu Manifest.aggrega lintaplica as regras da disciplina de publicação a uma entidade do catálogo, eaggrega inspectresolve e mostra o que o compilador vê. Quando toda a topologia estiver pronta,aggrega pull --release <release>resolve suas dependências e escreve seu lockfile, eaggrega build --release <release>então compila a Release em artefatos por fronteira — um build com falha indica exatamente o que corrigir.
Validar cedo é mais barato do que um build com falha tarde. Crie, valide, corrija e só então compile.
Criar com um assistente de IA
O comando aggrega mcp executa um servidor Model Context Protocol que transforma qualquer cliente compatível com MCP em um assistente de criação que conhece Aggrega. Depois de conectado, o assistente pode:
- Assumir uma função por meio dos prompts de criação integrados — um por persona (desenvolvedor, arquiteto, operações) mais um modelo específico por entidade. Cada prompt enquadra a função e direciona o assistente ao esquema, à página de referência e a este guia, para que suas sugestões fiquem dentro dos pilares pelos quais a função é responsável.
- Ler a referência por meio de recursos:
schema://<kind>para o JSON Schema de um tipo,langref://<path>para qualquer página de referência eauthoring://<topic>para este guia. - Agir no seu workspace por meio de ferramentas:
scaffoldpara iniciar um esqueleto correto,validatepara verificar um rascunho,describepara inspecionar uma entidade do catálogo eget-schemapara obter um esquema por tipo.
Tudo o que o assistente lê é servido a partir da sua máquina: os esquemas são embutidos no binário, e as páginas do guia e da referência vêm do pacote de documentação mantido no cache da sua máquina, que o servidor baixa do registry quando inicia e não encontra nenhuma cópia ali. Ler uma página, gerar um esqueleto e validar não acessam a rede; onde o pacote não pode ser baixado, os esquemas continuam sendo servidos e as páginas não. Para conectar um cliente, siga Conecte o servidor MCP; O que o seu assistente pode fazer com o Aggrega cobre o restante do que ele alcança. Para o comando em si, consulte a referência do aggrega mcp.
Próximos passos
- Personas — entenda as quatro funções antes de escolher uma entidade.
- Entidades por função — o mapa completo de tipo para função.
- Instalação — instale o binário; Conecte o servidor MCP conecta o seu assistente.
- Configure o Aggrega com o seu assistente de IA — um único prompt que faz o seu assistente instalar e conectar o Aggrega sozinho.
- Visão geral da CLI — cada subcomando de
aggrega.