Aggrega ファイルのオーサリング
Aggrega でのオーサリングは、短く繰り返し可能なループです。開発者の Aggregate、アーキテクトの Component、運用の Recipe、オペレーターの Release のいずれのエンティティを書く場合でも、同じ 5 つの手順で空のファイルから検証済みのファイルへ進めます。
- 自分のロールが所有するエンティティを選びます。
- JSON Schema とリファレンスページからその形を学びます。
- 空のファイルではなくスケルトンから始めます。
- 自分のロールが所有するフィールドを埋め、残りはその所有者に任せます。
- 検証し、その後コンパイルします。
このページでは、手作業でオーサリングする人と、Model Context Protocol サーバーを通じてオーサリングする AI アシスタントの両方について、このループを一通り説明します。2 つの経路は、同じリファレンスを対象とする同じループです。どちらにも aggrega バイナリが必要です。バイナリのインストールでは 1 つのコマンドでインストールできます。
1. 自分のロールが所有するエンティティを選ぶ
Aggrega は、オーサリングを協調する 4 つのロール、すなわち開発者のインテント、プラットフォームカタログ、インフラストラクチャのレシピ、デプロイメントの配線に分けます。各ロールは通常、特定のエンティティ種別の集合を所有します。自分のロールがすでにわかっている場合は必要なエンティティに進んでください。わからない場合は、4 つのロールについては Personas を、種別とロールの対応表全体については Entities by Role を参照してください。
この分離は指針であり、コンパイラが強制する規則ではありません。1 人の作成者がすべての役割を兼ね、すべてのエンティティを一度に書いてもかまいません。コンパイラは、スキーマ検証に通るどのようなオーサリングパターンも受け入れます。ロールは関心事を明確に保つためにあり、書けるものを制限するためのものではありません。
2. その形を学ぶ
すべてのエンティティ種別には、正規の JSON Schema とフィールドごとのリファレンスページがあります。書く前に両方を読んでください。
- スキーマは正確な構造、つまり必須フィールド、許可される値、入れ子を示します。コマンドラインでは
aggrega get-schema <kind>がスキーマを出力し、aggrega get-schema --listが取得可能なすべての種別を列挙します。アシスタントは同じバイト列をschema://<kind>リソースから読み取ります。aggrega get-schemaのリファレンスを参照してください。 - リファレンスページは、各フィールドが何を意味するかと、フィールド同士の関係を説明します。エンティティのページは
language-reference/entities/の下にあります。たとえば component や aggregate です。アシスタントは同じページをlangref://entities/<kind>リソースから読み取ります。
スキーマは何が構造的に有効かを示し、リファレンスは何が妥当かを示します。検証時の拒否を避けるためにスキーマを読み、意図どおりに動作するものを書くためにリファレンスを読んでください。
3. スケルトンから始める
スケルトンから始めるほうが、空のファイルから始めるよりも速く、誤りも少なくなります。MCP サーバーに接続したアシスタントは、種別と名前を指定して scaffold ツールを呼び出し、その種別が必要とするすべてのフィールドを含み、まだ値が未定の箇所にはプレースホルダーを置いた最小限の出発点を取得します。手作業でオーサリングする場合は、aggrega scaffold <kind> <name> が同じ出発点を標準出力に出力するので、ファイルにリダイレクトします。または、最も近い実例をコピーし、必要なものだけに絞り込みます。
いずれの場合も、スケルトンには必須のトップレベルフィールド(apiVersion、kind、metadata.name)が正しい形ですでに含まれているため、定型部分ではなく自分のロールが所有するフィールドに注意を向けられます。
4. 自分のロールが所有するフィールドを埋める
自分のロールが責任を持つピラーだけを埋め、それ以外はその所有者に任せます。開発者はアプリケーションのインテントと値を提供します。アーキテクトはコントラクト、つまり開発者が提供できる値、component が提供する出力、公開するソケットを宣言します。運用担当は、開発者向けの面を変えずにそのコントラクトを特定の provider に対応付けます。オペレーターはデプロイメントを配線します。どのピラーがどのロールに属するかは、種別ごとに Entities by Role で詳しく説明しています。
各値をその所有者が管理するピラーに置くことで、開発者のファイルを変えずに、同じ開発者のインテントを環境ごとに異なるインフラストラクチャに向けられます。これが、そもそもオーサリングの面が分割されている理由です。
説明は短い段落をいくつか程度に収めてください。 エンティティの metadata.description は、読み手がそのエンティティを選ぶ前に目にする文章です。エンティティとともに検索可能な説明として公開され、aggrega search はクエリをこれと照合します。その場面に向けて、短い段落で書いてください(折り畳み形式の description: > ブロックでは、空行が新しい段落を始めます)。エンティティが何であるか、読み手がどう使うか、どこで実現され、何をしないかを述べます。読み手がエンティティを選ぶ前に知っておくべき制限も、簡潔にそこに記載します。それ以外のこと、たとえばデフォルトがなぜその値なのか、ある設定が特定のターゲットでどう動作するか、各実現の下で値が何を意味するかは、説明対象のフィールドやブロックの横に YAML コメントとして書きます。そうすれば、そのフィールドを扱う人がそれを読みます。コンパイラには説明の長さを制限したり内容に基づいて動作したりするものは何もないため、短く保つのは読み手のためです。
5. 検証し、その後コンパイルする
ファイルに頼る前に確認してください。
- アシスタントは
validateツールを呼び出します。このツールはスキーマと参照のエラーをその場で報告するため、アシスタントはドラフトを返す前に修正できます。 - 手作業の場合、
aggrega validate <file>は 1 つの Component、Feature、Recipe、FeatureRecipe、Workload、または Plugin のファイルをチェックし、aggrega validate --release <release>は Release が到達するすべてを、その Aggregate と Manifest も含めてチェックします。aggrega lintはカタログエンティティに対して公開規律のルールを実行し、aggrega inspectは解決を行ってコンパイラが見ている内容を表示します。トポロジー全体の準備ができたら、aggrega pull --release <release>が依存関係を解決してロックファイルを書き込み、続いてaggrega build --release <release>が Release を境界ごとの成果物にコンパイルします。ビルドが失敗した場合は、修正すべき箇所が正確に示されます。
早い段階での検証は、後になってのビルド失敗よりも低コストです。オーサリングし、検証し、修正し、その後にはじめてコンパイルしてください。
AI アシスタントによるオーサリング
aggrega mcp コマンドは Model Context Protocol サーバーを実行し、MCP に対応した任意のクライアントを Aggrega を理解するオーサリングアシスタントにします。接続すると、アシスタントは次のことができます。
- 組み込みのオーサリングプロンプトを通じてロールを担います。プロンプトはペルソナ(開発者、アーキテクト、運用)ごとに 1 つずつと、エンティティごとに特化したテンプレートがあります。各プロンプトはロールを設定し、アシスタントにスキーマ、リファレンスページ、およびこのガイドを参照させるため、その提案はロールが所有するピラーの範囲内にとどまります。
- リソースを通じてリファレンスを読みます。種別の JSON Schema には
schema://<kind>、任意のリファレンスページにはlangref://<path>、このガイドにはauthoring://<topic>を使います。 - ツールを通じてワークスペースに対して操作します。正しいスケルトンを始めるには
scaffold、ドラフトを確認するにはvalidate、カタログエンティティを調べるにはdescribe、種別ごとにスキーマを取得するにはget-schemaを使います。
アシスタントが読むものはすべて手元のマシンから提供されます。スキーマはバイナリに組み込まれており、ガイドとリファレンスのページはマシンのキャッシュに保持されたドキュメントバンドルから提供されます。サーバーは起動時にキャッシュにコピーが見つからなければ、レジストリからバンドルを取得します。ページの読み取り、スキャフォールド、検証ではネットワークにアクセスしません。バンドルを取得できない場合、スキーマは引き続き提供されますが、ページは提供されません。クライアントを接続するには MCP サーバーの接続に従ってください。アシスタントが利用できるその他のものについてはアシスタントが Aggrega でできることで説明しています。コマンド自体については aggrega mcp のリファレンスを参照してください。
次のステップ
- Personas — エンティティを選ぶ前に 4 つのロールを理解します。
- Entities by Role — 種別とロールの対応表全体です。
- インストール — バイナリをインストールします。アシスタントは MCP サーバーの接続に従って接続します。
- AI アシスタントで Aggrega をセットアップする — アシスタント自身に Aggrega をインストールして接続させる 1 つのプロンプト。
- CLI の概要 — すべての
aggregaサブコマンドです。