Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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:

  1. Escolha a entidade pela qual sua função é responsável.
  2. Aprenda sua estrutura a partir do JSON Schema e da página de referência.
  3. Comece de um esqueleto em vez de um arquivo vazio.
  4. Preencha os campos pelos quais sua função é responsável, deixando o restante para os respectivos responsáveis.
  5. 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 --list lista cada tipo que você pode solicitar. Um assistente lê os mesmos bytes do recurso schema://<kind>. Consulte a referência de aggrega 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 recurso langref://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, e aggrega validate --release <release> verifica tudo o que uma Release alcança, incluindo seu Aggregate e seu Manifest. aggrega lint aplica as regras da disciplina de publicação a uma entidade do catálogo, e aggrega inspect resolve 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, e aggrega 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 e authoring://<topic> para este guia.
  • Agir no seu workspace por meio de ferramentas: scaffold para iniciar um esqueleto correto, validate para verificar um rascunho, describe para inspecionar uma entidade do catálogo e get-schema para 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