Menulis file Aggrega
Menulis di Aggrega adalah siklus yang singkat dan dapat diulang. Entitas apa pun yang Anda tulis — Aggregate milik developer, Component milik arsitek, Recipe milik tim operasi, atau Release milik operator — lima langkah yang sama membawa Anda dari file kosong ke file yang tervalidasi:
- Pilih entitas yang menjadi tanggung jawab peran Anda.
- Pelajari bentuknya dari JSON Schema dan halaman referensi.
- Mulai dari kerangka, bukan dari file kosong.
- Isi field yang menjadi tanggung jawab peran Anda, dan serahkan sisanya kepada pemiliknya.
- Validasi, lalu kompilasi.
Halaman ini menelusuri siklus tersebut satu kali, baik untuk orang yang menulis secara manual maupun untuk asisten AI yang menulis melalui server Model Context Protocol. Kedua jalur adalah siklus yang sama atas sumber referensi yang sama. Keduanya memerlukan binary aggrega: Menginstal binary menginstalnya dengan satu perintah.
1. Pilih entitas yang menjadi tanggung jawab peran Anda
Aggrega memisahkan penulisan ke dalam empat peran yang bekerja sama — intensi developer, katalog platform, resep infrastruktur, dan penyambungan deployment. Setiap peran biasanya bertanggung jawab atas sekumpulan jenis entitas tertentu. Jika Anda sudah mengetahui peran Anda, langsung menuju entitas yang Anda perlukan; jika belum, baca Persona untuk keempat peran dan Entitas menurut peran untuk peta lengkap dari jenis ke peran.
Pemisahan ini adalah panduan, bukan aturan yang ditegakkan oleh compiler. Penulis tunggal bebas mengenakan semua topi dan menulis semua entitas sekaligus; compiler menerima pola penulisan apa pun yang lolos validasi skema. Peran-peran ini ada untuk menjaga kejelasan tanggung jawab, bukan untuk membatasi apa yang boleh Anda tulis.
2. Pelajari bentuknya
Setiap jenis entitas memiliki JSON Schema kanonis dan halaman referensi per field. Baca keduanya sebelum menulis:
- Skema adalah struktur yang persis: field wajib, nilai yang diizinkan, dan penyarangan. Dari baris perintah,
aggrega get-schema <kind>mencetaknya;aggrega get-schema --listmenyebutkan setiap jenis yang dapat Anda minta. Asisten membaca byte yang sama dari resourceschema://<kind>. Lihat referensiaggrega get-schema. - Halaman referensi menjelaskan apa arti setiap field dan bagaimana field-field saling berhubungan. Halaman entitas berada di bawah
language-reference/entities/— misalnya component atau aggregate. Asisten membaca halaman yang sama dari resourcelangref://entities/<kind>.
Skema memberi tahu Anda apa yang valid secara struktural; referensi memberi tahu Anda apa yang masuk akal. Baca skema untuk menghindari penolakan saat validasi, dan referensi untuk menulis sesuatu yang melakukan apa yang Anda maksudkan.
3. Mulai dari kerangka
Memulai dari kerangka lebih cepat dan lebih kecil kemungkinan salahnya daripada file kosong. Asisten yang terhubung ke server MCP memanggil tool scaffold dengan sebuah jenis dan nama untuk mendapatkan titik awal minimal yang memuat setiap field yang diwajibkan jenis tersebut, dengan placeholder di setiap tempat yang nilainya masih harus diisi. Jika menulis secara manual, aggrega scaffold <kind> <name> mencetak titik awal yang sama ke output standar, jadi alihkan ke sebuah file; atau salin contoh lengkap yang paling mirip dan pangkas hingga sesuai kebutuhan Anda.
Bagaimanapun caranya, kerangka sudah memuat field tingkat atas yang wajib (apiVersion, kind, metadata.name) dalam bentuk yang benar, sehingga Anda dapat mencurahkan perhatian pada field yang menjadi tanggung jawab peran Anda, bukan pada boilerplate.
4. Isi field yang menjadi tanggung jawab peran Anda
Isi hanya pilar yang menjadi tanggung jawab peran Anda, dan serahkan pilar lainnya kepada pemiliknya. Developer menyediakan intensi aplikasi dan nilai; arsitek mendeklarasikan kontrak — nilai yang boleh diberikan developer, output yang disediakan komponen, socket yang diekspos komponen; tim operasi memetakan kontrak tersebut ke provider tertentu tanpa mengubah permukaan yang dihadapi developer; operator menyambungkan deployment. Entitas menurut peran menjabarkan pilar mana milik peran mana untuk setiap jenis.
Menjaga setiap nilai berada di pilar yang dikendalikan pemiliknya adalah hal yang memungkinkan intensi developer yang sama menargetkan infrastruktur berbeda di berbagai lingkungan tanpa file developer berubah. Itulah alasan permukaan penulisan dipisah sama sekali.
Batasi deskripsi pada beberapa paragraf pendek. metadata.description sebuah entitas adalah teks yang dijumpai pembaca sebelum memilihnya: teks ini dipublikasikan bersama entitas sebagai deskripsi yang dapat dicari, dan aggrega search mencocokkan kueri dengannya. Tulislah untuk momen itu, dalam paragraf pendek — dalam blok terlipat description: >, baris kosong memulai paragraf baru — yang menyatakan apa entitas itu, bagaimana pembaca menggunakannya, di mana entitas itu direalisasikan, dan apa yang tidak dilakukannya. Batasan yang harus diketahui pembaca sebelum memilih entitas juga dituliskan di sana, secara singkat. Segala hal lain — mengapa suatu default bernilai seperti itu, bagaimana suatu pengaturan berperilaku pada satu target, apa arti suatu nilai di setiap realisasi — ditulis dalam komentar YAML di samping field atau blok yang dijelaskannya, tempat orang yang bekerja dengan field itu akan membacanya. Tidak ada apa pun di compiler yang membatasi panjang deskripsi atau bertindak berdasarkan isinya, jadi menjaganya tetap singkat adalah demi pembaca.
5. Validasi, lalu kompilasi
Periksa file sebelum Anda mengandalkannya:
- Asisten memanggil tool
validate, yang melaporkan kesalahan skema dan referensi secara langsung sehingga asisten dapat memperbaiki draf sebelum mengembalikannya. - Secara manual,
aggrega validate <file>memeriksa satu file Component, Feature, Recipe, FeatureRecipe, Workload, atau Plugin, danaggrega validate --release <release>memeriksa semua yang dijangkau sebuah Release, termasuk Aggregate dan Manifest-nya.aggrega lintmenjalankan aturan disiplin publikasi atas entitas katalog, danaggrega inspectme-resolve dan menampilkan apa yang dilihat compiler. Ketika seluruh topologi siap,aggrega pull --release <release>me-resolve dependensinya dan menulis lockfile-nya, laluaggrega build --release <release>mengompilasi Release menjadi artefak per batas — build yang gagal menyebutkan dengan tepat apa yang harus diperbaiki.
Validasi lebih awal lebih murah daripada build yang gagal belakangan. Tulis, validasi, perbaiki, dan baru kemudian kompilasi.
Menulis dengan asisten AI
Perintah aggrega mcp menjalankan server Model Context Protocol yang mengubah klien apa pun yang mendukung MCP menjadi asisten penulisan yang memahami Aggrega. Setelah terhubung, asisten dapat:
- Mengambil peran melalui prompt penulisan bawaan — satu per persona (developer, arsitek, operasi) ditambah templat terfokus per entitas. Setiap prompt membingkai peran tersebut dan mengarahkan asisten ke skema, halaman referensi, dan panduan ini, sehingga sarannya tetap berada dalam pilar yang menjadi tanggung jawab peran tersebut.
- Membaca referensi melalui resource:
schema://<kind>untuk JSON Schema suatu jenis,langref://<path>untuk halaman referensi mana pun, danauthoring://<topic>untuk panduan ini. - Bertindak pada workspace Anda melalui tool:
scaffolduntuk memulai kerangka yang benar,validateuntuk memeriksa draf,describeuntuk memeriksa entitas katalog, danget-schemauntuk mengambil skema menurut jenis.
Semua yang dibaca asisten disajikan dari mesin Anda: skema tertanam di dalam binary, sedangkan halaman panduan dan referensi berasal dari bundel dokumentasi yang disimpan di cache mesin Anda, yang diambil server dari registry ketika saat dimulai tidak menemukan salinannya di sana. Membaca halaman, membuat kerangka, dan memvalidasi tidak mengakses jaringan; jika bundel tidak dapat diambil, skema tetap disajikan sedangkan halaman tidak. Untuk menghubungkan klien, ikuti Menghubungkan server MCP; Apa yang dapat dilakukan asisten Anda dengan Aggrega membahas hal lain yang dapat dijangkau asisten. Untuk perintah itu sendiri, lihat referensi aggrega mcp.
Langkah selanjutnya
- Persona — pahami keempat peran sebelum Anda memilih entitas.
- Entitas menurut peran — peta lengkap dari jenis ke peran.
- Instalasi — instal binary; Menghubungkan server MCP menghubungkan asisten Anda.
- Menyiapkan Aggrega dengan asisten AI Anda — satu prompt yang membuat asisten Anda memasang dan menghubungkan Aggrega sendiri.
- Ikhtisar CLI — setiap subperintah
aggrega.