Rédiger des fichiers Aggrega
Dans Aggrega, la rédaction est une boucle courte et reproductible. Quelle que soit l’entité que vous écrivez — l’Aggregate d’un développeur, le Component d’un architecte, une Recipe des opérations ou la Release d’un opérateur —, les mêmes cinq étapes vous mènent d’un fichier vide à un fichier validé :
- Choisissez l’entité dont votre rôle est responsable.
- Apprenez sa structure à partir du JSON Schema et de la page de référence.
- Partez d’un squelette plutôt que d’un fichier vide.
- Remplissez les champs dont votre rôle est responsable, en laissant le reste à leurs responsables.
- Validez, puis compilez.
Cette page parcourt la boucle une fois, à la fois pour une personne qui rédige à la main et pour un assistant IA qui rédige via le serveur Model Context Protocol. Les deux parcours sont la même boucle sur les mêmes sources de référence. Tous deux ont besoin du binaire aggrega : Installer le binaire l’installe en une seule commande.
1. Choisir l’entité dont votre rôle est responsable
Aggrega répartit la rédaction entre quatre rôles qui collaborent — l’intention du développeur, le catalogue de la plateforme, les recettes d’infrastructure et le câblage du déploiement. Chaque rôle est en général responsable d’un ensemble précis de types d’entités. Si vous connaissez déjà votre rôle, passez directement à l’entité dont vous avez besoin ; sinon, lisez Personas pour les quatre rôles et Entités par rôle pour la correspondance complète entre types et rôles.
Cette séparation est une orientation, non une règle que le compilateur impose. Un auteur seul est libre de porter toutes les casquettes et d’écrire toutes les entités en une seule fois ; le compilateur accepte toute manière de rédiger qui passe la validation du schéma. Les rôles existent pour garder les responsabilités claires, non pour restreindre ce que vous pouvez écrire.
2. Apprendre sa structure
Chaque type d’entité possède un JSON Schema canonique et une page de référence champ par champ. Lisez les deux avant d’écrire :
- Le schéma est la structure exacte : champs obligatoires, valeurs autorisées et imbrication. En ligne de commande,
aggrega get-schema <kind>l’affiche ;aggrega get-schema --listnomme chaque type que vous pouvez demander. Un assistant lit les mêmes octets depuis la ressourceschema://<kind>. Voir la référence deaggrega get-schema. - La page de référence explique ce que chaque champ signifie et comment les champs sont liés. Les pages des entités se trouvent sous
language-reference/entities/— par exemple component ou aggregate. Un assistant lit la même page depuis la ressourcelangref://entities/<kind>.
Le schéma vous dit ce qui est structurellement valide ; la référence vous dit ce qui est judicieux. Lisez le schéma pour éviter un rejet lors de la validation, et la référence pour rédiger quelque chose qui fait ce que vous voulez.
3. Partir d’un squelette
Partir d’un squelette est plus rapide et moins sujet aux erreurs qu’un fichier vide. Un assistant connecté au serveur MCP appelle l’outil scaffold avec un type et un nom pour obtenir un point de départ minimal contenant chaque champ que le type exige, avec un espace réservé partout où une valeur reste due. Si vous rédigez à la main, aggrega scaffold <kind> <name> affiche le même point de départ sur la sortie standard, redirigez-le donc vers un fichier ; ou copiez l’exemple détaillé le plus proche et réduisez-le à ce dont vous avez besoin.
Dans les deux cas, le squelette contient déjà les champs de premier niveau obligatoires (apiVersion, kind, metadata.name) sous la bonne forme, de sorte que vous consacrez votre attention aux champs dont votre rôle est responsable plutôt qu’au code passe-partout.
4. Remplir les champs dont votre rôle est responsable
Remplissez uniquement les piliers dont votre rôle est responsable et laissez les autres à leurs responsables. Un développeur fournit l’intention applicative et les valeurs ; un architecte déclare le contrat — les valeurs qu’un développeur peut fournir, les sorties qu’un composant fournit, les sockets qu’il expose ; les opérations font correspondre ce contrat à un provider précis sans modifier la surface destinée au développeur ; un opérateur câble le déploiement. Entités par rôle détaille quels piliers appartiennent à quel rôle pour chaque type.
Garder chaque valeur dans le pilier que contrôle son responsable est ce qui permet à la même intention du développeur de cibler des infrastructures différentes d’un environnement à l’autre sans que le fichier du développeur change. C’est la raison même pour laquelle la surface de rédaction est divisée.
Limitez la description à quelques paragraphes courts. Le metadata.description d’une entité est le texte qu’un lecteur rencontre avant de la choisir : il est publié avec l’entité comme description consultable par recherche, et aggrega search compare une requête à ce texte. Rédigez-le pour ce moment, en paragraphes courts — dans un bloc replié description: >, une ligne vide en commence un nouveau —, en disant ce qu’est l’entité, comment un lecteur l’utilise, où elle est réalisée et ce qu’elle ne fait pas. Une limite qu’un lecteur doit connaître avant de choisir l’entité y a aussi sa place, énoncée brièvement. Tout le reste — pourquoi une valeur par défaut est ce qu’elle est, comment un paramètre se comporte sur une cible, ce que signifie une valeur dans chaque réalisation — va dans des commentaires YAML à côté du champ ou du bloc qu’il explique, là où la personne qui travaille avec ce champ le lira. Rien dans le compilateur ne limite la longueur d’une description ni n’agit selon ce qu’elle dit ; la garder courte est donc pour le bien du lecteur.
5. Valider, puis compiler
Vérifiez le fichier avant de vous y fier :
- Un assistant appelle l’outil
validate, qui signale directement les erreurs de schéma et de référence afin qu’il puisse corriger le brouillon avant de le rendre. - À la main,
aggrega validate <file>vérifie un seul fichier de Component, de Feature, de Recipe, de FeatureRecipe, de Workload ou de Plugin, etaggrega validate --release <release>vérifie tout ce qu’une Release atteint, y compris son Aggregate et son Manifest.aggrega lintapplique les règles de la discipline de publication à une entité du catalogue, etaggrega inspectrésout et affiche ce que voit le compilateur. Lorsque toute la topologie est prête,aggrega pull --release <release>résout ses dépendances et écrit son lockfile, puisaggrega build --release <release>compile la Release en artefacts par frontière — un build en échec indique exactement ce qu’il faut corriger.
Valider tôt coûte moins cher qu’un build en échec tardif. Rédigez, validez, corrigez, et seulement ensuite compilez.
Rédiger avec un assistant IA
La commande aggrega mcp exécute un serveur Model Context Protocol qui transforme tout client compatible MCP en assistant de rédaction connaissant Aggrega. Une fois connecté, l’assistant peut :
- Adopter un rôle grâce aux prompts de rédaction intégrés — un par persona (développeur, architecte, opérations) plus un modèle ciblé par entité. Chaque prompt cadre le rôle et oriente l’assistant vers le schéma, la page de référence et ce guide, afin que ses suggestions restent dans les piliers dont le rôle est responsable.
- Lire la référence grâce aux ressources :
schema://<kind>pour le JSON Schema d’un type,langref://<path>pour toute page de référence etauthoring://<topic>pour ce guide. - Agir sur votre workspace grâce aux outils :
scaffoldpour démarrer un squelette correct,validatepour vérifier un brouillon,describepour inspecter une entité du catalogue etget-schemapour récupérer un schéma par type.
Tout ce que l’assistant lit est servi depuis votre machine : les schémas sont intégrés au binaire, et les pages du guide et de la référence proviennent du paquet de documentation conservé dans le cache de votre machine, que le serveur récupère depuis le registre lorsqu’il démarre et n’y trouve aucune copie. Lire une page, générer un squelette et valider n’accèdent pas au réseau ; là où le paquet ne peut pas être récupéré, les schémas sont toujours servis et les pages ne le sont pas. Pour connecter un client, suivez Connecter le serveur MCP ; Ce que votre assistant peut faire avec Aggrega couvre le reste de ce qu’il atteint. Pour la commande elle-même, voir la référence aggrega mcp.
Pour aller plus loin
- Personas — comprenez les quatre rôles avant de choisir une entité.
- Entités par rôle — la correspondance complète entre types et rôles.
- Installation — installer le binaire ; Connecter le serveur MCP connecte votre assistant.
- Configurer Aggrega avec votre assistant IA — une seule invite qui fait installer et connecter Aggrega par votre assistant lui-même.
- Vue d’ensemble de la CLI — chaque sous-commande d’
aggrega.