Blog Maguyva

Konteks yang ikut bepergian dengan Anda

Mon, 07 Sep 2026 00:00:00 GMT

Indexer Cursor sangat baik di dalam Cursor. Pelengkapan tab, penyuntingan inline, chat, dan agen di jendela itu sudah bertumpu pada indeks proyek yang dioperasikan Cursor untuk workspace yang terbuka. Jika Cursor adalah satu-satunya permukaan tempat Anda menulis kode, dan indeks itu sudah menemukan file yang tepat, tetaplah di sana. Itu adalah kasus jujur ‘tetap di tempat Anda’, dan sepantasnya menjadi kalimat pertama halaman ini.

Tulisan ini tentang separuh lain dari minggu biasa. Repo yang sama juga dibuka di Claude Code, ditanyai dari Codex CLI, ditinjau di mesin kedua, atau ditanyai oleh agen yang berjalan di CI. Pertanyaannya bukan ‘indexer mana yang lebih baik’. Pertanyaannya adalah apakah peta yang dipercaya agen di satu jendela sama dengan peta yang dipercayainya di jendela berikutnya.

Maguyva adalah peta yang ikut bepergian dengan Anda itu. Ini adalah lapisan konteks codebase MCP jarak jauh. Agen menanyakannya dengan cara yang sama seperti menanyakan alat MCP lainnya. Hasilnya kembali sebagai jalur berperingkat dengan nomor baris. Cursor tetap menjadi editor. Konteks-lah yang berpindah.

Untuk apa indexer Cursor

Pengindeksan bawaan Cursor ada agar chat, agen, dan pencarian di dalam editor bisa mengambil kode yang relevan, alih-alih hanya mengandalkan apa yang muat di jendela konteks mentah model. Itu desain yang tepat untuk sebuah IDE. Indeks ini native untuk Cursor. Ini bukan server MCP dan tidak dapat dijangkau dari klien lain mana pun.

Beginilah cara kerjanya, seperti dijelaskan dalam dokumentasi publik Cursor dan penjelasan Cursor sendiri pada saat penulisan ini: jalur pencarian utama bukan lagi indeks embedding di cloud. Tim Cursor menyatakan di forum komunitas mereka bahwa pencarian semantik/berbasis embedding yang khusus sedang dikurangi demi pengambilan berbasis grep, karena model saat ini sudah cukup baik menjelajahi pohon yang hidup dengan sendirinya. Sebagai gantinya ada Instant Grep, indeks pencarian lokal yang dibangun dari n-gram, daftar terbalik, dan filter Bloom, disimpan dalam tabel pencarian yang dipetakan ke memori, sehingga kueri diselesaikan di mesin developer sendiri, bukan di server.

Indeksnya sendiri hidup di dalam direktori .git/cursor/ milik repo itu sendiri, dikaitkan pada commit git tertentu; perubahan sejak commit itu ditumpuk di atasnya alih-alih memicu pemindaian baru, dan indeksnya hanya dibangun ulang saat kondisi lokal sudah menyimpang jauh dari apa yang menjadi dasar pembangunannya. Karena berada di dalam .git, ia tidak pernah dilacak dan tidak pernah di-push — hapus foldernya, dan indeksnya hilang. .gitignore dihormati karena konstruksinya, karena hanya konten yang dilacak git yang memenuhi syarat, dan .cursorignore diberlakukan di jalur baca. Tidak ada lagi langkah embedding di sisi server atau basis data vektor jarak jauh di jalur itu. Dokumentasi sebelumnya menjelaskan desain berbantuan cloud — enkripsi chunk, sinkronisasi lewat Merkle tree, penggunaan ulang indeks antar anggota tim — dan tim Cursor sendiri sejak itu mengatakan bahwa desain itu sedang dikurangi, jadi tulisan ini tidak lagi menjelaskannya sebagai kondisi terkini.

Keunggulan yang menonjol di dalam editor adalah subagen Explore milik Cursor. Ia bisa menjalankan beberapa pencarian paralel di jendela konteksnya sendiri pada model yang lebih cepat dan hanya mengembalikan temuan yang relevan, sehingga percakapan utama tidak membengkak oleh hasil pencarian. Itu kekuatan sejati di dalam editor. Pertahankan itu.

Workspace multi-root didukung: konteks setiap folder yang dibuka tersedia untuk Agent. Beberapa fitur yang bergantung pada git, seperti worktree, dinonaktifkan dalam pengaturan multi-root, dan Cloud Agents sama sekali tidak mendukung workspace multi-root.

Tidak satu pun dari ini menjadi alasan untuk meninggalkan Cursor. Ini adalah deskripsi tepat tentang peta yang sangat baik di tempat ia hidup.

Apa arti sebenarnya ‘ikut bepergian dengan Anda’

Sebuah peta ikut bepergian dengan Anda ketika pertanyaan yang sama mengembalikan jenis jawaban yang sama, dengan kutipan yang bisa Anda buka, dari lebih dari satu klien.

Di Cursor: ‘Di mana parseConfig didefinisikan, dan siapa yang memanggilnya?’
Di Claude Code, di repo yang sama: pertanyaan yang sama.
Di Codex CLI, di mesin peninjau yang tidak pernah membuka jendela Cursor: pertanyaan yang sama.
Di agen CI yang berbicara MCP: pertanyaan yang sama, terhadap snapshot yang dihosting sama.

Jika setiap permukaan membangun indeks privatnya sendiri, Anda tidak punya satu peta. Anda punya beberapa cache yang saling menyimpang. Indeks editor mungkin terkini untuk pohon di disk. Sesi CLI mungkin tertinggal sehari. Pekerjaan CI mungkin melihat checkout yang berbeda. Dan agen akan tetap terdengar percaya diri.

Indexer Cursor tidak dimaksudkan untuk menyelesaikan itu. Karena hidup di dalam editor, konteks yang dibangunnya adalah untuk editor itu. Pembaca yang juga butuh CLI, pipeline CI, atau editor berbeda, butuh alat terpisah untuk permukaan-permukaan itu. Itu fakta cakupan, bukan cacat. Maguyva adalah alat terpisah itu.

Jumlah bahasa yang dipublikasikan untuk indexer Cursor tidak dicantumkan dalam materi yang boleh digunakan tulisan ini. Maguyva mempublikasikan dukungan untuk lebih dari 279 bahasa dan teknologi berbasis teks. Harga Cursor juga tidak disalin di sini; lihat halaman harga mereka. Maguyva menagih per workspace, bukan per kursi, dengan paket yang dipublikasikan $0, $19, $49, dan $149 tergantung cakupan yang diindeks dan ukuran workspace.

Satu peta yang dihosting, setiap klien MCP

Maguyva adalah server MCP jarak jauh. Anda menghubungkan GitHub, memilih repo, dan pipeline cloud membangun simbol, tepi graf, dan peta berperingkat. Anda menambahkan kunci API ke konfigurasi MCP klien yang sudah Anda gunakan. Maguyva punya panduan pengaturan untuk 24 klien MCP yang terdokumentasi — termasuk Cursor — dan bisa terhubung ke klien kompatibel MCP lainnya yang mendukung konfigurasi standar.

Halaman pengaturan Cursor adalah jalur khusus editor jika di situlah Anda bekerja. Server yang sama menjawab Claude Code, VS Code, Windsurf, Codex CLI, dan lainnya. Anda tidak berganti editor. Anda memberi setiap agen permukaan alat yang sama: 11 alat MCP yang menghadap klien di seluruh pencarian, simbol, analisis dependensi, pengambilan file, konteks repo, dan alur kerja alat bantu deterministik. Pencarian semantik, struktural, graf, dan teks digabung menjadi hasil berperingkat.

Itulah keuntungan portabilitas. Kutipan yang Anda periksa di Cursor pagi ini punya bentuk yang sama dengan kutipan yang akan dikembalikan Codex CLI malam ini. Jalur file dan nomor baris. Buka. Jika salah, Anda akan melihatnya. Jika benar, perubahan berikutnya punya tempat untuk mendarat. Klaim yang disetujui adalah lebih sedikit perubahan yang berhalusinasi, bukan janji bahwa setiap perubahan itu benar.

Kesegaran dipublikasikan. Snapshot diberi timestamp, sehingga agen tahu versi pohon mana yang sedang dibacanya. Kecepatan pembangunan ulang harian di paket gratis dan setiap jam di paket berbayar. Batasan yang jujur adalah pekerjaan lokal yang belum disinkronkan: perubahan yang hanya ada di working tree belum ada di peta yang dihosting. Batasan ini sama tidak peduli klien mana yang Anda gunakan untuk bertanya, dan itulah intinya. Perbedaan antar klien bukan lagi batasan tersembunyi kedua.

Dokumentasi memberikan loop aktivasi yang berlaku untuk setiap klien: indeks satu repo yang sudah Anda kenal, hubungkan klien, ajukan satu pertanyaan yang bisa Anda verifikasi. Lakukan itu sekali di Cursor. Lakukan lagi dari CLI yang benar-benar Anda gunakan pada hari peninjauan. Jika kedua jawaban mengutip handler yang sama, peta itu benar-benar ikut bepergian dengan Anda.

Bagaimana kedua peta hidup berdampingan

Gunakan keduanya. Keduanya bukan alternatif dalam arti halaman perbandingan.

Biarkan indexer Cursor tetap aktif untuk proyek di disk. Biarkan Explore, Instant Grep, dan agen di dalam editor menggunakannya. Loop itu native dan cepat.
Tambahkan Maguyva sebagai server MCP di Cursor agar sesi yang sama juga bisa menanyakan peta workspace yang dihosting. Cursor adalah klien Maguyva yang terdokumentasi. Anda tidak memilih satu indeks lalu menghapus yang lain.
Tambahkan server Maguyva yang sama ke Claude Code, Codex CLI, atau klien MCP lain mana pun yang menyentuh repo. Satu bentuk kunci API. Satu workspace.
Jika agen CI kompatibel MCP, arahkan ke server yang sama. Ia akan membaca snapshot bertimestamp yang sama seperti yang dibaca laptop.

Indeks editor tetap menjadi alat terbaik untuk ‘apa yang ada di disk di jendela ini, saat ini juga’. Peta yang dihosting adalah alat terbaik untuk ‘seperti apa workspace ini bagi setiap agen yang menyentuhnya hari ini’. Kalimat-kalimat itu tidak saling bersaing.

Kuota workspace dipublikasikan di halaman harga: repo, baris yang diindeks, dan pengguna, ditagih per workspace. Agen dan manusia berbagi hitungan pengguna yang sama. Mulai gratis dengan repo yang sudah bisa Anda nilai. Naikkan workspace hanya setelah kutipan bertahan dari kontak dengan pohon.

Apa yang tidak diklaim halaman ini

Halaman ini tidak mengklaim bahwa indexer Cursor lemah, tidak lengkap, atau alasan untuk berganti editor. Kalimat pertama tulisan ini mengatakan sebaliknya.

Halaman ini tidak mengklaim bahwa Maguyva menggantikan Instant Grep atau subagen Explore. Itu fitur Cursor. Semuanya tetap berada di Cursor.

Halaman ini tidak mengarang jumlah bahasa, angka latensi, atau penghematan token untuk kedua produk mana pun. Angka yang tidak diketahui tetap tidak dipublikasikan.

Halaman ini tidak berpura-pura bahwa pekerjaan lokal yang belum di-push ada di peta yang dihosting. Snapshot bertimestamp membuat batasan itu terlihat. Mereka tidak menghilangkannya.

Tesnya biasa saja. Indeks satu repo yang sudah Anda kenal. Ajukan satu pertanyaan yang bisa Anda verifikasi, pertama di Cursor, lalu di klien MCP kedua. Konteks yang ikut bepergian dengan Anda adalah kutipan yang sama di kedua tempat.

// same map, wherever you opened it.

Peta dulu, review kemudian

Mon, 07 Sep 2026 00:00:00 GMT

Dua pekerjaan berbeda duduk di kedua sisi pull request. Sebelum agen menulis, ia membutuhkan peta pohon yang akan diubahnya. Setelah agen membuka PR, sesuatu harus membaca perubahan itu terhadap sisa sistem dan meninggalkan komentar yang bisa ditindaklanjuti manusia.

Pekerjaan-pekerjaan ini terlihat mirip dari kejauhan karena keduanya melibatkan ‘memahami codebase’. Keduanya bukan produk yang sama. Yang satu menjawab ‘di mana perubahan ini seharusnya mendarat?’. Yang lain menjawab ‘apa yang dirusak diff ini yang akan terlewatkan linter baris demi baris?’. Mencampurkan keduanya menghasilkan draf pertama yang lebih buruk dan review yang lebih berisik.

Tulisan ini adalah panduan alur kerja gabungan. Maguyva adalah peta yang ditanyakan agen terlebih dahulu. Greptile adalah agen review yang mengomentari PR setelahnya. Pasangan ini saling melengkapi karena konstruksinya: Maguyva tidak me-review pull request, dan Greptile tidak menggantikan lapisan konteks yang digunakan agen untuk menulisnya.

Mengapa pembagian ini berguna

Agen coding yang berangkat dari prior pelatihan ditambah beberapa file yang ditempel akan mengarang jalur yang masuk akal dan mengeditnya. Itu kegagalan ‘file yang salah’, dan itu masalah pengambilan. Maguyva adalah lapisan konteks codebase MCP jarak jauh: pengambilan semantik, struktural (AST), graf/dependensi, dan teks digabung menjadi hasil berperingkat, ditambah pencarian simbol dan pengambilan file. Jawaban yang berdasar kembali sebagai path/file.ext:line, sehingga Anda bisa menolak yang salah sebelum patch ada. Klaimnya tetap sederhana: lebih sedikit perubahan yang berhalusinasi. Model masih bisa menebak. Hanya saja langkah pertama berhenti menjadi tebakan.

Greptile adalah agen review kode bertenaga AI. Dengan kata-kata mereka sendiri, ia secara otomatis me-review setiap pull request dengan pemahaman penuh tentang codebase, dan memposisikannya melawan linter tradisional yang memeriksa file secara terpisah alih-alih seluruh sistem. Pengaturannya terdiri dari menginstal aplikasi GitHub atau GitLab dan memilih repo. Tidak ada indeks lokal yang harus Anda operasikan. Hosting-nya adalah Greptile Cloud (mereka menyatakan kepatuhan SOC 2 Type II, dengan laporan tersedia atas permintaan), dengan opsi self-hosted yang ditawarkan untuk perusahaan.

Alur bernomor mereka sendiri adalah: hubungkan dan bangun graf dependensi setiap fungsi, kelas, dan dependensi; pada setiap pull request, analisis perubahan menggunakan graf repo penuh itu dan publikasikan temuan sebagai komentar PR dengan perbaikan yang disarankan, dalam waktu sekitar tiga menit; setiap komentar bisa menyerahkan masalah ke agen coding yang sudah digunakan tim. Mereka juga menyatakan membaca komentar PR manusia sebelumnya seiring waktu untuk mempelajari standar kode tim dan mengurangi saran yang berisik. Sistem pembelajaran mereka, menurut pernyataan mereka, membutuhkan 2-3 minggu untuk beradaptasi.

Itu adalah review, bukan penyusunan draf. Keunggulan Greptile adalah konteks graf repo penuh pada perubahan yang sudah mendarat di PR, diikuti loop tertutup yang mengirim temuan ke Claude Code, Codex, Conductor, Cursor, atau Devin. Keunggulan Maguyva adalah peta berperingkat yang ditanyakan agen sebelum perubahan itu ditulis. Gunakan keduanya. Jangan minta salah satu melakukan pekerjaan yang lain.

Integrasi produk pihak pertama antara Maguyva dan Greptile tidak dinyatakan. Anda juga tidak membutuhkannya. Maguyva berbicara dengan agen lewat MCP. Greptile berbicara dengan GitHub atau GitLab lewat aplikasi mereka sendiri. Mereka bertemu di pull request. Tidak ada skrip perekat, tidak ada cron yang menyalurkan satu alat ke alat lain. Pasangan ini tidak butuh bash karena setiap produk sudah duduk di permukaan yang menjadi miliknya.

Apa yang bukan ini

Ini bukan pembongkaran Greptile. Ini bukan halaman ‘ganti reviewer Anda’. Greptile diluncurkan di Hacker News pada 5 Maret 2024 sebagai perusahaan Y Combinator W24, dan thread itulah cara banyak orang pertama kali mengenal produk itu. Jika begitulah cara Anda menemukan mereka, tetap gunakan mereka. Halaman ini adalah separuh depan yang hilang dari loop itu: melandasi agen terlebih dahulu agar PR yang dilihat Greptile sudah membidik file yang tepat.

Materi pemasaran Greptile memimpin dengan klaim kecepatan review dan penangkapan bug. Perlakukan itu sebagai klaim Greptile sendiri, bukan angka yang diverifikasi secara independen. Tulisan ini tidak mengulanginya sebagai fakta.

Cakupan bahasa adalah jenis kejujuran yang sama. Greptile membingkai dukungan sebagai mencakup semua bahasa pemrograman alih-alih daftar yang diberi nomor; angka pastinya tidak dinyatakan. Maguyva mempublikasikan dukungan untuk lebih dari 279 bahasa dan teknologi berbasis teks, dengan pembagian teknis (AST yang didukung parser versus hanya teks) di situs saat pertanyaannya teknis. Ini adalah produk berbeda yang membuat klaim berbeda. Jangan mencampurnya.

Harga Greptile tidak dinyatakan dalam materi yang boleh digunakan tulisan ini. Paket berbayar ada; lihat halaman harga mereka. Maguyva menagih per workspace, bukan per kursi. Paket dimulai gratis. Halaman harga mencantumkan tingkatan yang dipublikasikan jika Anda butuh angka workspace.

Alur kerja

Tiga tahap bernama. Jalankan dalam urutan ini. Jangan lewati satu pun saat pertama kali mencoba pasangan ini.

1. Konteks Maguyva

Indeks satu repo yang sudah Anda kenal. Hubungkan klien MCP tempat Anda sudah menulis — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, atau klien kompatibel MCP lain. Maguyva punya panduan pengaturan untuk 24 klien MCP terdokumentasi dan bisa terhubung ke klien lain yang mendukung konfigurasi MCP standar.

Ajukan pertanyaan yang bisa Anda nilai sebelum siapa pun menulis satu baris. ‘Di mana kedaluwarsa sesi ditangani, dan apa yang memanggilnya?’ adalah langkah pertama yang lebih baik daripada ‘perbaiki auth’. Tuntut kutipan. Buka hasil file.ext:line. Ikuti simbolnya. Konfirmasikan dependensi yang akan Anda sentuh.

Maguyva mengekspos 11 alat MCP yang menghadap klien di seluruh pencarian, simbol, analisis dependensi, pengambilan file, konteks repo, dan alur kerja alat bantu deterministik. Empat mode pengambilan digabung menjadi hasil berperingkat; find_symbol adalah alat terpisah saat Anda sudah tahu namanya. Dokumentasi menjelaskan jalur terpendek: mulai gratis, indeks repo yang sudah Anda kenal, hubungkan klien, lalu ajukan satu pertanyaan yang bisa Anda verifikasi.

Snapshot diberi timestamp, sehingga agen bisa mengetahui versi pohon mana yang dibacanya. Batasan jujurnya adalah pekerjaan lokal yang belum disinkronkan. Jika perubahan hanya ada di working tree dan belum di-push, peta yang dihosting belum memuatnya. File instruksi (CLAUDE.md, AGENTS.md) masih punya tempat di sini, untuk konvensi dan apa yang tidak boleh disentuh. Itu bukan peta yang hidup. Gunakan untuk perilaku. Gunakan Maguyva untuk fakta.

Jangan biarkan agen membuka PR sebelum kutipan bertahan dari kontak dengan repo. Gerbang itu adalah keseluruhan inti tahap ini.

2. PR agen

Agen yang sama sekarang menulis perubahan di klien yang sudah Anda bayar. Maguyva bukan editor dan bukan reviewer. Agen tetap menghasilkan diff. Anda tetap membuka pull request di GitHub atau GitLab seperti yang sudah Anda lakukan.

Yang seharusnya berbeda adalah file pertama. PR seharusnya menyebutkan handler yang benar-benar mengimplementasikan perilaku, pemanggil yang akan rusak, dan tes yang akan gagal jika perubahan itu salah. Jika tahap 1 dilewati, tahap 3 akan menghabiskan komentarnya pada perubahan yang mendarat di paket yang salah. Greptile masih bisa menemukan masalah sistemik. Ia seharusnya tidak juga harus pulih dari jalur yang berhalusinasi.

Jaga PR tetap terbatas. File pertama yang berdasar bukan lisensi untuk menulis ulang modul. Pasangan yang saling melengkapi ini bekerja saat agen melakukan satu pekerjaan dengan peta, lalu meminta reviewer melakukan pekerjaan lain pada diff yang dibatasi.

3. Review Greptile

Greptile sudah terhubung ke repo lewat aplikasi GitHub atau GitLab. Pada pull request baru, ia menganalisis perubahan menggunakan graf repo penuh yang dibangunnya, dan mempublikasikan temuan sebagai komentar dengan perbaikan yang disarankan. Materi mereka sendiri menempatkan proses ini sekitar tiga menit.

Baca komentar seperti Anda membaca rekan tim yang teliti: buka lokasi yang dikutip, putuskan apakah temuannya nyata, lalu bertindak. Di mana Greptile menawarkan ‘Fix with your Agent’, ia mengirim masalah — jalur file, nomor baris, kode yang disarankan — ke Claude Code, Codex, Conductor, Cursor, atau Devin. ‘Fix All’ mengirim semua masalah dalam review sekaligus. Mereka juga menyediakan Greptile MCP dan plugin Claude Code untuk serah terima itu. Maguyva tidak ada di daftar target bernama itu; ketidakhadiran itu bukan masalah. Maguyva sudah melakukan pekerjaannya di tahap 1. Agen coding yang menulis PR adalah yang seharusnya menerima payload perbaikan.

Harapkan gangguan pada 2-3 minggu pertama saat sistem pembelajaran Greptile beradaptasi dengan komentar yang benar-benar ditinggalkan tim Anda. Itu jadwal yang mereka nyatakan, bukan cacat pada pasangan ini. Review manusia tetap ada dalam loop. Greptile adalah proses pertama yang otomatis, bukan tombol merge.

Jika komentar Greptile menunjuk ke file yang tidak pernah ditanyakan agen di tahap 1, itu sinyal yang berguna. Entah peta melewatkan pemanggil, atau agen melewatkan kutipan. Perbaiki draf sesuai komentar itu. Jangan nonaktifkan reviewer.

Cara menjaga pelengkap ini tetap jujur

Maguyva selalu pertama. Review PR dengan file salah tetap saja review file yang salah.
Greptile selalu setelahnya. Draf yang dikutip dengan baik tetap membutuhkan pembacaan diff pada tingkat seluruh sistem.
Jangan minta Maguyva mempublikasikan komentar PR. Ia tidak melakukannya.
Jangan minta Greptile menjadi lapisan pengambilan pertama agen saat agen masih memilih jalur. Itu bukan pekerjaan yang dirancang untuk aplikasi GitHub atau GitLab mereka.
Jangan mengarang pipeline bash yang ‘menyinkronkan’ keduanya. PR adalah antarmukanya.
Verifikasi kedua sisi secara independen. Indeks satu repo yang sudah Anda kenal. Ajukan satu pertanyaan yang bisa Anda verifikasi. Lalu buka PR kecil dan baca apa yang sebenarnya dikomentari Greptile.

Loop ini biasa saja begitu diberi nama. Peta dulu. PR agen. Review kemudian. Setiap produk tetap di sisi pull request yang menjadi keahliannya.

// map first. review second. in that order.

Memberi agen AI konteks repo besar tanpa indexer lokal

Fri, 14 Aug 2026 00:00:00 GMT

Repo besar tidak muat di jendela konteks, dan jika Anda pernah mengarahkan indexer laptop ke monorepo sungguhan, Anda tahu itu juga tidak muat dengan nyaman di sana — RAM melonjak, indeksasi pertama butuh satu jam, dan agen Anda tetap memulai sesi berikutnya dengan menebak file mana yang penting.

Jawaban yang biasa adalah menjalankan indexer di samping editor, dan untuk repo yang muat dengan nyaman di satu mesin, itu jawaban yang baik. Jika monorepo Anda sudah terindeks cepat di Cursor dan itu satu-satunya tempat Anda membutuhkan peta, tulisan ini tidak punya apa-apa untuk ditambahkan — lewati saja.

Tulisan ini tentang kasus lain — ketika agen membutuhkan peta repo besar yang bisa ditanyakan, dan Anda tidak ingin menjalankan indexer lokal untuk mendapatkannya.

Kapan indexer lokal adalah alat yang salah

Indeks lokal mengasumsikan kode hidup di mesin yang menanyakannya, dan pada skala monorepo sungguhan, asumsi itu meregang bahkan di dalam satu editor. Repo itu sekadar lebih besar daripada yang ingin Anda jaga tetap ‘hangat’ di laptop: Anda bekerja di satu paket sementara cakupan dampak berada tiga direktori lebih jauh, dan indeksasi dingin pertama untuk pohon dua juta baris bukan sesuatu yang ingin Anda alami dua kali — baik di mesin Anda sendiri, maupun di CI runner yang tidak pernah meng-clone pohon itu sebelumnya. Atau seorang rekan tim seharusnya bisa menanyakan peta yang sama dengan Anda, tanpa menunggu mesin mereka sendiri berjuang melalui indeks yang sama.

Tidak satu pun dari ini menjadi alasan untuk membuang indexer editor yang bagus. Ini alasan untuk juga punya peta yang dihosting yang bisa ditanyakan oleh agen mana pun milik Anda lewat MCP.

Dan masalah skala berjalan lebih dalam daripada ‘terlalu banyak file untuk ditempel’. Pada pohon besar, pertanyaan yang menarik hampir tidak pernah ‘tunjukkan file ini kepada saya’ — melainkan file mana, simbol mana, pemanggil mana, tes mana. Agen yang mulai dengan mendaftar src/ dan membaca tiga hasil pertama akan dengan riang melewatkan handler di apps/api dan klien yang dihasilkan di packages/sdk. Yang Anda butuhkan adalah pengambilan yang dibangun dari seluruh pohon, lalu diperingkat, lalu dikutip.

Apa arti sebenarnya ‘konteks repo besar’

Menumpahkan file ke prompt bukanlah konteks — itu salinan pohon yang lebih kecil dan lebih buruk. Yang benar-benar dibutuhkan agen Anda adalah mengajukan pertanyaan dan mendapatkan jawaban yang dikutip kembali: di mana simbol ini didefinisikan dan siapa yang memanggilnya, apa yang bergantung pada modul yang akan saya ubah, file tes mana yang mencakup perilaku ini, dan seperti apa pohon itu sekarang, bukan kuartal lalu.

Jawaban-jawaban itu harus berasal dari indeks yang dibangun dari repo Anda, bukan dari ingatan model tentang repo orang lain, dan indeksnya harus hidup di suatu tempat di luar jendela konteks agen. Untuk masalah ini, seharusnya juga hidup di suatu tempat di luar laptop Anda.

Satu hal lagi yang tidak bisa dilakukan file instruksi untuk Anda: CLAUDE.md dan AGENTS.md adalah tempat yang tepat untuk konvensi dan perilaku, tetapi bukan peta yang hidup, berperingkat, dan bisa ditanyakan dari pohon dua juta baris. Gunakan aturan untuk perilaku; gunakan kecerdasan repo untuk fakta.

Kami membangun peta di cloud, Anda menanyakannya dari klien mana pun

Maguyva adalah lapisan konteks codebase MCP jarak jauh. Anda menghubungkan GitHub, memilih repo Anda, dan bisa pergi begitu saja sementara pipeline cloud mengurai pohon, membangun simbol dan tepi graf, dan memelihara peta berperingkat — tanpa indexer lokal, sama sekali tidak pernah.

Saat Anda push kode, file yang berubah diurai secara bertahap, dan lapisan graf serta peringkat dibangun ulang sesuai jadwal: harian di paket gratis, setiap jam di paket berbayar. Setiap snapshot diberi timestamp, sehingga agen Anda bisa mengetahui versi pohon mana yang dibacanya. Batasan jujur di sini adalah pekerjaan lokal yang belum disinkronkan — perubahan yang hanya ada di working tree Anda, tidak pernah di-push, belum ada di peta yang dihosting.

Lalu Anda menghubungkan klien apa pun yang sudah Anda gunakan dengan menambahkan kunci API ke konfigurasi MCP-nya. Ada panduan pengaturan untuk 24 klien MCP terdokumentasi, dan klien kompatibel MCP lain mana pun yang mendukung konfigurasi standar juga bisa terhubung. Jika Cursor tempat Anda tinggal, halaman Cursor menempuh jalur itu; server yang sama menjawab Claude Code, VS Code, Windsurf, Codex CLI, dan lainnya.

Anda tidak berganti editor. Anda memberi agen Anda permukaan alat — 11 alat MCP di seluruh pencarian, simbol, analisis dependensi, pengambilan file, dan konteks repo — dengan cakupan lebih dari 279 bahasa dan teknologi berbasis teks, yang berarti lebih dari yang Anda kira pada monorepo yang berhenti menjadi satu bahasa bertahun-tahun lalu.

Jawaban kembali dengan dasar yang kuat, sebagai jalur file dengan nomor baris. Pencarian semantik, struktural, graf, dan teks digabung menjadi hasil berperingkat, sehingga pertanyaan seperti ‘apa yang bergantung pada parseConfig’ tidak memberi Anda tumpukan grep atau satu potongan semantik, melainkan segelintir tempat yang benar-benar penting.

Panduan konkret

Jangan mulai dengan mengindeks seluruh perusahaan. Ini jalur yang berhasil:

Pilih satu repo yang sudah Anda kenal baik — paket yang bisa Anda nilai dengan tangan lebih berharga daripada pohon terbesar yang Anda miliki.
Mulai gratis: 3 repo, 50 ribu baris terindeks, semua 11 alat, tanpa kuota query bulanan. Jika repo representatif Anda lebih besar, halaman harga mencantumkan tingkatan workspace ($0, $19, $49, $149) berdasarkan cakupan yang diindeks — bukan berdasarkan jumlah kursi.
Hubungkan GitHub dan tunggu indeksasi pertama selesai. Anda tidak mengompilasi apa pun secara lokal.
Hubungkan klien MCP — beberapa baris konfigurasi. Maguyva adalah server MCP jarak jauh, jadi tidak ada plugin, tidak ada ekstensi, dan tidak ada editor kedua yang harus diadopsi.
Ajukan satu pertanyaan yang bisa Anda verifikasi. ‘Apa yang bergantung pada parseConfig?’ atau ‘Di mana kedaluwarsa sesi login ditangani?’ Lalu buka hasil file.ext:line yang dikutip dan periksa terhadap pohon di depan Anda.
Hanya setelah kutipan itu bertahan dari kontak itu, Anda membiarkan agen mengedit.

Jika repo pertama cocok dengan baik dan pohon Anda besar, naikkan workspace agar sesuai dengan baris terindeks Anda dan kecepatan pembangunan ulang. Manusia dan agen berbagi hitungan pengguna yang sama — Maguyva menagih per workspace, bukan per kursi — jadi menambahkan agen ketiga ke dalam loop tidak membebani Anda apa pun.

Tes aktivasi sama dengan yang direkomendasikan dokumentasi untuk setiap jalankan pertama: indeks satu repo yang sudah Anda kenal, ajukan satu pertanyaan yang bisa Anda verifikasi. Repo besar tidak mengubah tesnya; itu hanya membuat file pertama yang salah menjadi lebih mahal.

Yang perlu diperhatikan setelah terhubung

Perhatikan tiga hal. Kesegaran: paket berbayar dibangun ulang setiap jam, paket gratis harian, dan pekerjaan lokal yang belum di-push tidak akan ada di peta — itulah kompromi yang Anda terima. Cakupan: indeks kumpulan repo yang representatif, bukan setiap fork yang diarsipkan; tingkat gratis sengaja diukur untuk mengetahui apakah jawabannya layak dipertahankan. Dan verifikasi: peta repo besar yang tidak bisa mengutip jalur dan nomor baris hanyalah mesin tebakan yang lebih lambat, jadi buat agen Anda menunjukkan lokasi sebelum mengirimkan patch.

Lalu jalankan tes yang sama seperti yang akan Anda jalankan pada repo kecil. Indeks satu repo yang sudah Anda kenal. Ajukan satu pertanyaan yang bisa Anda verifikasi. Jika peta itu nyata, agen Anda berhenti memulai dari pohon yang dingin.

// no laptop got hot building this map.

Mengapa agen coding AI berhalusinasi jalur file

Fri, 14 Aug 2026 00:00:00 GMT

Tandanya bukan badan fungsi yang salah. Itu adalah perubahan yang percaya diri pada file yang tidak ada, atau file yang ada tetapi bukan yang mengimplementasikan perilaku itu.

Anda meminta perbaikan kedaluwarsa sesi. Agen membuka src/auth/session.ts. Jalur itu masuk akal. Itu juga salah. Handler sebenarnya hidup di apps/api/src/middleware/expiry.ts, diganti namanya dua refactor lalu. Agen tidak berbohong kepada Anda. Ia menyelesaikan string berbentuk jalur dari prior pelatihan ditambah apa pun yang sudah ada di jendela konteks.

Ini adalah pola kegagalan umum pada repo sungguhan. Model bisa menulis kode. Kesalahannya ada pada memilih tempat yang salah untuk menulisnya.

Mengapa agen mengarang jalur

Agen coding adalah model prediksi token berikutnya dengan alat-alat. Saat Anda bilang ‘perbaiki kedaluwarsa sesi’, ia harus menyebutkan file sebelum bisa membaca atau menambal apa pun. Jika belum punya peta yang berdasar, ia membangun jalur dari:

Konvensi penamaan yang pernah dilihatnya di repo lain. src/auth/session.ts adalah bentuk yang sering muncul.
File yang sudah ada dalam percakapan, yang mungkin adalah yang Anda tempel minggu lalu, bukan yang penting sekarang.
Daftar direktori yang kebetulan dijalankannya, tidak lengkap pada pohon yang besar.
File instruksi. CLAUDE.md dan AGENTS.md memberi tahu agen cara berperilaku. Itu bukan indeks yang hidup dari simbol, pemanggil, atau jalur terkini.

Tidak satu pun dari sumber ini adalah peta repo ini, hari ini. Model mengisi kekosongan dengan cara yang sama seperti mengisi kekosongan mana pun: dengan kelanjutan berprobabilitas tinggi. Kelanjutan itu sering terlihat seperti jalur sungguhan. Kadang filenya ada dan terletak di sebelah yang benar. Kadang ia pernah ada di branch yang di-merge bulan lalu. Kadang ia tidak pernah ada.

Grep tidak menyelamatkan Anda di sini jika agen tidak pernah mencari string yang benar. Agen menebak jalur, lalu membaca apa yang dikembalikan jalur itu, lalu mengeditnya. Langkah pertama yang salah adalah jalurnya, bukan patch-nya.

Membaca file juga bukan hal yang sama dengan menemukan yang benar. Claude Code, Cursor, Codex, dan alat serupa bisa membuka apa pun yang Anda arahkan. Pertanyaannya adalah apakah mereka secara andal menemukan file yang tepat, simbol yang penting, dependensi, tes, dan cakupan dampak sebelum mengedit. Akses file tanpa peta tetap dimulai dengan tebakan.

Mengedit file yang salah adalah masalah pengambilan

Perlakukan jalur yang dikarang sebagai kegagalan pengambilan, bukan sebagai cacat karakter.

Jika agen harus mengembalikan path/file.ext:line sebelum diizinkan mengedit, dua hal akan terjadi. Pertama, Anda bisa membuka kutipan itu dan menolak pekerjaan dalam sepuluh detik. Kedua, agen harus menanyakan sesuatu yang benar-benar mengenal pohon itu.

Itu adalah pekerjaan lapisan konteks codebase. Pencarian semantik saja tidak cukup. Sepotong yang ‘terdengar seperti kedaluwarsa sesi’ tetap bisa mendarat di paket yang sudah usang. Anda juga butuh teks yang tepat saat Anda tahu stringnya, pencarian simbol saat Anda tahu namanya, pencarian struktural saat Anda tahu bentuknya, dan graf dependensi saat Anda butuh pemanggil dan cakupan dampak.

Maguyva adalah lapisan itu untuk agen coding yang kompatibel MCP. Ini bukan editor. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, dan klien MCP lainnya tetap di tempatnya. Agen menanyakan peta berperingkat sebelum menyentuh satu baris.

Klaimnya sengaja sederhana: lebih sedikit perubahan yang berhalusinasi. Maguyva tidak menghilangkan kemampuan model untuk menebak. Ia mengubah langkah pertama default dari ‘karang jalur yang masuk akal’ menjadi ‘minta lokasi berperingkat, terkutip’.

Seperti apa jawaban yang berdasar

Jawaban yang berguna untuk ‘di mana kedaluwarsa sesi ditangani’ bukanlah sebuah paragraf. Ini daftar singkat lokasi:

apps/api/src/middleware/expiry.ts:48 - handler-nya
apps/web/src/lib/auth-client.ts:112 - pemanggilnya
apps/api/tests/expiry.test.ts:20 - tes yang akan gagal jika perubahan itu salah

Anda bisa membuka baris-baris ini. Jika salah, Anda berhenti. Jika benar, agen boleh mengedit. Verifikasi adalah intinya, bukan slogan.

Maguyva mengekspos 11 alat MCP yang menghadap klien di seluruh pencarian, simbol, analisis dependensi, pengambilan file, konteks repo, dan alur kerja alat bantu deterministik. Empat mode pengambilan (semantik, struktural, graf/dependensi, dan teks) digabung menjadi hasil berperingkat; pencarian simbol adalah alat MCP terpisah (find_symbol). Jawaban yang berdasar kembali dengan jalur file dan nomor baris, sehingga Anda bisa menilainya terhadap pohon di depan Anda.

Dokumentasi menjelaskan jalur terpendek: mulai gratis, indeks repo yang sudah Anda kenal, hubungkan klien, lalu ajukan satu pertanyaan yang bisa Anda verifikasi.

Loop yang mengubah perubahan pertama

Anda tidak butuh agama alur kerja baru. Anda butuh satu langkah ekstra sebelum tulisan pertama.

Ajukan pertanyaan yang sudah bisa Anda nilai. ‘Kode mana yang menangani login dan kedaluwarsa sesi?’ lebih baik daripada ‘perbaiki auth’.
Tuntut kutipan. Jalur file dan nomor baris, bukan ringkasan ‘modul auth’.
Buka file yang dikutip. Ikuti simbolnya. Konfirmasikan dependensi yang akan Anda sentuh.
Baru setelah itu biarkan agen menambal.

Jika langkah 2 tidak mengembalikan apa pun yang berguna, agen tidak punya hak untuk mengimprovisasi jalur. Ia mencari lagi, atau Anda menunjukkannya. Justru satu gerbang inilah yang menghasilkan lebih sedikit perubahan yang berhalusinasi. Modelnya adalah model yang sama. Yang berubah adalah petanya.

File instruksi masih penting. Simpan itu. Gunakan untuk konvensi, aturan review, dan apa yang tidak boleh disentuh. Jangan minta mereka menjadi indeks. CLAUDE.md yang mendaftar tiga direktori penting akan basi seminggu setelah pemecahan paket. Peta yang bisa ditanyakan diperbarui saat repo diperbarui.

Kegagalan terkait adalah file yang hampir benar: agen membuka auth.ts padahal perilakunya hidup di auth-client.ts, atau menambal file yang dihasilkan alih-alih sumbernya, atau mengedit salinan di packages/legacy karena namanya cocok. Kutipan tidak membuat kesalahan-kesalahan ini mustahil. Kutipan membuatnya terlihat sebelum diff mendarat.

Apa yang tidak akan diperbaiki peta untuk Anda

Bersikaplah realistis tentang apa yang Anda dapatkan. Peta yang berdasar tidak akan membuat setiap perubahan benar — agen Anda tetap bisa menulis patch yang buruk di file yang persis benar. Jika codebase Anda bersandar pada dispatch dinamis, refleksi, atau monkey-patching, beberapa pencarian simbol akan kembali lebih tipis daripada yang Anda inginkan, karena itulah yang dilakukan indireksi runtime pada indeks statis mana pun. Dan jika Anda mengharapkan persentase — ‘jalur yang berhalusinasi berkurang X%’ — Anda tidak akan menemukannya di sini, karena tidak ada yang bisa secara jujur mengukur angka itu untuk repo Anda selain diri Anda sendiri.

Yang bisa Anda harapkan lebih sempit dan lebih berguna: agen berhenti memulai perubahannya dengan jalur yang ditebak. Langkah pertama itu menjadi berdasar pada peta sungguhan, dan dari situlah lebih sedikit perubahan yang berhalusinasi berasal. Semua yang setelah kutipan — membaca diff, menilai patch — tetap menjadi pekerjaan Anda, seperti selalu.

Tes ini hampir tidak membebani Anda apa pun: indeks satu repo yang sudah Anda kenal dan ajukan satu pertanyaan yang bisa Anda verifikasi. Mulai dengan jalur yang pernah membuat Anda kapok. Jika kutipannya salah, Anda akan langsung melihatnya. Jika benar, perubahan berikutnya dari agen Anda punya tempat yang lebih baik untuk mendarat.

// it doesn't know the file. it knows how to find it.

Mengapa Kami Meningkatkan Pencarian Kode ke voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Angka benchmark dalam tulisan ini mencerminkan papan peringkat RTEB pada saat publikasi (Juni 2026). Papan peringkat bergerak; anggap peringkatnya sebagai potret sesaat, bukan fakta permanen.

Pencarian semantik hanya sebaik embedding yang mendasarinya.

Ketika seorang agen bertanya kepada Maguyva “di mana kita menangani retry,” ia tidak sedang meng-grep kata “retry.” Ia sedang menanyakan makna — loop backoff, circuit breaker, hal yang membungkus sebuah panggilan yang tidak stabil. Pertanyaan itu dijawab oleh sebuah model vektor yang mengubah kode menjadi sebuah titik dalam ruang dan menemukan tetangganya. Pilih model yang lebih baik, dan setiap kueri semantik di produk ini diam-diam menjadi lebih tajam.

Jadi kami mengubah milik kami. Per Juni 2026, embedding kode Maguyva berjalan di atas voyage-4-large, menggantikan voyage-code-3.

Benchmark-nya

Kami tidak membuat keputusan ini berdasarkan feeling. Retrieval Embedding Benchmark (RTEB) publik memeringkat model embedding pada task retrieval sungguhan, dan pada papan peringkat Code-nya, voyage-4-large berada di #1 secara keseluruhan (90,86) — mengungguli gemini-embedding-2-preview (90,26) dan, yang patut dicatat, mengungguli model yang sebelumnya kami pakai, voyage-code-3 (89,73, #3).

Itu selisih absolut yang kecil. Tetapi itu selisih ke arah yang benar, pada benchmark publik, pada task persis yang kami pedulikan: mengambil kode berdasarkan makna.

Trade-off yang Kami Terima: Kuantisasi Biner

Inilah bagian yang sering dilewatkan kebanyakan tulisan “kami meningkatkan model kami.”

Maguyva tidak menyimpan vektor presisi penuh. Kami menyimpan embedding yang terkuantisasi biner: setiap vektor 2048 dimensi dipadatkan menjadi sebuah signature 2048-bit — 256 byte per vektor. Signature-signature itu dicari dengan Hamming distance, diindeks dan dipartisi per tenant.

Itu trade-off yang disengaja. Kuantisasi biner melepas sebagian presisi retrieval demi penyimpanan yang jauh lebih kecil dan perhitungan jarak yang cepat dan murah tanpa perlu database vektor terpisah untuk dioperasikan. Untuk sebuah produk yang mengindeks seluruh repositori per workspace, ekonomi itu lebih penting daripada mengejar pecahan poin terakhir dari sebuah benchmark.

voyage-4-large cocok dengan desain ini tanpa memaksa migrasi lapisan penyimpanan: ia menghasilkan output 2048 dimensi, sama seperti voyage-code-3, sehingga kolom bit(2048) kami dan jalur pencarian Hamming kami tidak berubah. Modelnya membaik; skemanya tetap sama.

Kode Hanyalah Permulaan

Maguyva adalah tool code-intelligence. Tetapi kami juga customer zero, dan kami mengarahkannya ke sesuatu yang lain: markdown yang hidup di repo kami bersebelahan dengan kode. Architecture decision record, runbook, kontrak, dokumen finance dan policy — semuanya version-controlled di Git, semuanya di balik server MCP yang sama, sebuah indeks semantik atas dokumen, bukan hanya source code.

Itulah persisnya mengapa keluasan voyage-4-large itu penting. Pada keluarga papan peringkat RTEB yang sama, ia #1 di finance, #1 di healthcare, dan #1 di retrieval teks keseluruhan — mengungguli Gemini Embedding milik Google, Embed v4 milik Cohere, dan text-embedding-3-large milik OpenAI. (Voyage adalah salah satu pencipta RTEB, jadi kami membacanya sebagai sinyal publik yang kuat, bukan wasit yang sepenuhnya netral — tetapi ia di-benchmark head-to-head dengan setiap model komersial besar, pada hold-out set privat.) Indeks yang sama yang menemukan fungsi yang tepat untuk seorang agen juga menemukan klausul yang tepat dalam sebuah kontrak atau baris yang tepat dalam sebuah policy — dan pada domain-domain itu, voyage-4-large bukan sebuah kompromi, ia sang pemimpin.

Mengapa Kami Membayar untuk Embedding Premium

Ada cara yang lebih murah untuk melakukan pencarian, dan sebagian besarnya gratis. Pencarian leksikal — BM25 dan sejenisnya — mencocokkan kata kunci, berjalan lokal, dan tidak berbiaya apa pun. Model embedding open-source seperti BGE, Nomic, dan embeddinggemma memberikan retrieval semantik yang sungguh-sungguh lumayan, dan Anda bisa meng-self-host mereka dengan harga sebuah GPU. Maguyva juga menggunakan sisi gratis itu: setiap kueri memfusikan pencarian teks, AST, graf, dan semantik. Yang tidak kami irit adalah lapisan semantiknya.

Kami membayar per token untuk embedding premium — voyage-4-large — alih-alih meng-self-host model gratis, karena dua alasan. Pertama, pencarian kata kunci saja tidak bisa menjawab “di mana kita menangani retry” ketika kodenya berkata backoff dan circuit breaker dan tidak pernah menyebut kata “retry” — makna adalah keseluruhan inti dari embedding, dan pada domain-domain yang kami layani, model open source tertinggal dari model premium: beberapa poin di belakang pada teks umum, dan lebih jauh tertinggal di niche seperti kode, kontrak, dan finance. Kedua, dalam pengalaman kami, kualitas retrieval membentuk jawaban akhir lebih daripada model di sisi lainnya — seorang agen yang kuat tetapi diberi konteks yang salah tetap menjawab salah, dan ia tidak pernah melihat dokumen yang tidak pernah diberikan kepadanya.

Jadi embedding premium adalah tagihan per token yang berskala dengan setiap repo dan dokumen yang kami indeks — dan kami membayarnya dengan sengaja. Untuk hasil yang didapat pengguna kami, fungsi yang tepat atau klausul yang tepat, kami rasa trade-off itu sepadan.

Bagian yang Jujur

Dokumentasi Voyage sendiri masih melabeli voyage-code-3 sebagai model yang dioptimalkan untuk kode. Jadi mengapa berpindah?

Karena kami membaca benchmark publiknya, bukan sekadar tabel model milik vendor, dan benchmark itu menempatkan voyage-4-large di puncak untuk retrieval kode. Ini adalah keputusan yang menatap ke depan: mengambil model yang lebih baru dan secara umum lebih kuat, lalu memvalidasinya terhadap sebuah papan peringkat publik pada task-task yang penting. Kami nyaman membuat taruhan itu karena buktinya luas — voyage-4-large tidak hanya menang di kode, ia juga memimpin di finance, healthcare, dan retrieval keseluruhan.

Fondasi di Balik Layar

Setiap tool yang kami ekspos — pencarian semantik, pengumpulan task-context, tanya jawab grounded — bermuara pada retrieval. Ketika retriever-nya membaik, agen di sisi lainnya mendapat bukti yang lebih baik, lebih jarang mengambil keputusan yang keliru, dan menambatkan jawabannya pada kode yang tepat — atau klausul yang tepat, atau policy yang tepat. Sebuah model embedding yang lebih tajam bukan fitur yang mencolok. Ia adalah fondasi bagi semua kemampuan lainnya, dan kami baru saja meningkatkan kualitasnya. Anda tidak akan menyadarinya. Itulah intinya.

Peningkatan Mandiri Rekursif untuk Dukungan Bahasa: Menyempurnakan Kecerdasan Kode di ~280 Bahasa

Tue, 26 May 2026 00:00:00 GMT

Angka dalam tulisan ini mencerminkan sistem pada saat publikasi (Mei 2026). Lihat halaman tim kami untuk angka terkini.

Maguyva mengekstraksi simbol, referensi, dan graf dependensi dari kode sumber di sekitar 280 bahasa. Setiap bahasa punya handler tree-sitter khusus — query, heuristik, edge case — dan setiap handler bisa salah dengan caranya masing-masing yang halus. Sebuah panggilan method yang tercatat sebagai pembacaan. Sebuah fungsi yang teratribusi ke scope pembungkus yang salah. Sebuah relasi yang sebenarnya tidak ada.

Anda tidak bisa mengaudit itu secara manual. Tidak ada tim yang bisa membaca output ekstraksi lintas 280 grammar dan menemukan edge yang salah. Jadi pertanyaan yang menarik bukan “apakah ekstraksi kami benar” — melainkan “bagaimana Anda menemukan bahwa itu salah, pada skala seluas ini, tanpa manusia di setiap loop.” Jawaban kami adalah peningkatan mandiri rekursif untuk dukungan bahasa: sebuah loop kualitas yang digerakkan oleh agen bahasa, sebuah LLM yang bertindak sebagai judge, dan satu aturan yang terus kami pelajari ulang: hijau tidak sama dengan benar.

Hijau bukan berarti benar

Setiap bahasa punya suite fixture, dan sebuah release gate menilainya di lima dimensi — akurasi, integritas struktural, kelengkapan, kualitas, dan performa. Sebuah bahasa baru menjadi GREEN hanya ketika, pada fixture-nya, presisi ≥ 0,95, recall ≥ 0,99, dan F1 ≥ 0,97, dengan minimal 20 edge yang diharapkan untuk keyakinan statistik. Di bawah itu, statusnya YELLOW atau RED, dan tidak akan dirilis.

Gate itu perlu tetapi tidak cukup. Fixture divalidasi terhadap fixture yang kami tulis sendiri. Fixture mengenkode kasus-kasus yang sudah kami pikirkan sebelumnya. Sebuah handler bisa sempurna pada fixture-nya tetapi tetap mengacaukan sebuah pola yang hanya muncul di kode dunia nyata — sebuah idiom macro, sebuah method dengan batasan tipe generic, sebuah fitur bahasa yang tidak pernah ditulis fixture-nya oleh siapa pun. GREEN berarti fixture-nya lulus. Itu tidak berarti sebuah repositori sungguhan terekstraksi dengan bersih. Jadi loop ini harus meninggalkan fixture dan memeriksa kode dunia nyata.

Loop dalam: spot-check, judge, perbaiki, buktikan

Loop inti berjalan satu bahasa dalam satu waktu:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

Beberapa hal membuat ini berjalan alih-alih hanya berputar-putar tanpa hasil.

Judge-nya adalah agen itu sendiri, bukan sekadar panggilan API. Ketika kami bilang “LLM-as-judge,” maksud kami agen bahasa itu sendiri mencocokkan setiap edge yang disampel dengan kode sumber sungguhan dan mengklasifikasikannya dengan rubrik lima kategori yang tetap: apakah edge ini benar, sebuah false positive, relasi yang tepat dengan tipe yang salah, terpasang pada scope yang salah, atau membawa metadata yang salah? Rubrik itulah keseluruhan permainannya — “tingkat kesalahan 23%” tidak berarti apa-apa sampai Anda tahu apakah itu cacat sungguhan atau judge yang salah hitung.

Perbaiki satu hal, lalu buktikan. Setiap iterasi mengubah tepat satu aset yang bisa diedit, lalu dijalankan ulang terhadap harness yang tetap dan mempertahankan perubahan itu hanya jika F1 membaik dan reklasifikasinya terlihat lebih baik. Jika tidak, perubahan itu dibatalkan. Tidak ada batch edit spekulatif, tidak ada “seharusnya lebih baik.” Sebuah perubahan mendapatkan tempatnya, atau hilang. Dan ketika sebuah perbaikan bertahan, perbaikan itu dipromosikan ke dalam suite fixture — sehingga bug yang diperbaikinya tidak akan pernah diam-diam kembali. Langkah promosi itulah yang membuat loop ini rekursif, bukan sekadar berulang: setiap putaran memperkuat oracle yang menjadi acuan validasi putaran berikutnya.

Pelajaran yang terus kami pelajari ulang: metrik terlalu banyak melaporkan

Inilah jebakannya, dan kami langsung terjerumus ke dalamnya. Metrik korpus sekunder — seberapa sering sebuah target hasil ekstraksi tidak punya simbol yang bisa diresolusi, berapa banyak simbol yang terlihat “yatim,” dan seterusnya — secara masif melaporkan masalah yang terlalu banyak. Kebanyakan itu adalah artefak paradigma, bukan bug.

Contoh paling jelas: llvm pernah menunjukkan tingkat “source-without-symbol” sebesar 73% dan langsung dicap bencana. Kami menggalinya lebih dalam. Akurasi sesungguhnya adalah 98,5%. “Simbol yang hilang” itu hampir semuanya adalah referensi eksternal yang sah — panggilan ke pustaka standar, ke framework, ke kode yang hidup di luar repositori. Metrik itu mengukur properti dari bahasanya, bukan cacat pada handler-nya. Bahasa seperti Zig, COBOL, dan Odin menunjukkan tingkat “yatim” sebesar 65–70% dan sepenuhnya benar; COBOL bahkan tidak punya satu pun kesalahan sungguhan.

Jika kami membiarkan angka-angka itu mengendalikan pekerjaan, kami akan menghabiskan berminggu-minggu “memperbaiki” handler yang sebenarnya sudah benar dan mengabaikan bahasa-bahasa dengan bug sungguhan yang diam-diam bersembunyi. Kesimpulannya blak-blakan: metrik agregat paling banter hanya sinyal triase kasar. Sinyal kualitas sesungguhnya adalah spot-check dengan klasifikasi edge — melihat edge sungguhan di repositori sungguhan dan menilainya satu per satu. Data mengalahkan intuisi, tapi hanya setelah Anda tahu data mana yang berkata jujur.

Loop luar: sepasukan, bukan maraton

Satu bahasa dalam satu waktu akan memakan waktu selamanya di seluruh 280 bahasa, jadi loop dalam dibungkus dalam loop luar yang menjalankan banyak bahasa secara paralel.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

Setiap agen bekerja di worktree sekali pakai sehingga mereka tidak bisa saling menabrak. Orchestrator mengintegrasikan perbaikan mereka satu per satu, masing-masing di balik pemeriksaan regresi full-manifest: sebuah perubahan yang membantu bahasanya sendiri tetapi diam-diam merusak tiga bahasa lain tidak akan mendarat. Integrasi melewati pemeriksaan dan konfirmasi sebelum perubahan apa pun di-push — gate regresi memutuskan apa yang aman, manusia tetap yang memutuskan apa yang dirilis. Lalu pool berputar ke set bahasa berikutnya dan seluruh proses berjalan lagi.

Apa yang masih belum sempurna

Judge-nya bisa saja salah, dan kesalahan itu punya arah: sebuah agen yang berjalan dengan konteks terlalu sedikit melaporkan berlebihan. Dalam satu batch, delapan bahasa ditandai dengan tingkat kesalahan 5–20%; setelah diperiksa, bug sungguhan hanya ditemukan pada satu bahasa — sisanya adalah kesalahan judge karena melewatkan semantik bahasa itu sendiri (satu baris sumber yang secara valid menghasilkan beberapa edge, binding parameter yang dimodelkan sebagai assignment, bahasa dengan reference-per-identifier). Itulah sebabnya kami menyampel dengan dua seed dan melakukan cross-check, dan mengapa ketidaksepakatan antara judge dan fixture diperlakukan sebagai sinyal paling menarik, bukan verdict final — kadang fixture-lah yang justru salah.

Kami juga jujur soal targetnya. Tujuannya adalah nol kesalahan sungguhan, titik — tetapi “nol” adalah arah yang terus kami upayakan, bahasa demi bahasa, bukan kotak centang yang sudah selesai. Selalu ada repo lain dengan idiom lain.

Dibuktikan Lewat Kerja, Bukan Sekadar Diklaim

Semua yang dilakukan Maguyva untuk seorang agen — menemukan sebuah simbol, menelusuri sebuah dependensi, menjawab sebuah pertanyaan dengan kode yang dikutip — bertumpu pada ekstraksi di baliknya yang benar. Di 280 bahasa, “benar” tidak bisa sekadar diklaim; itu harus terus-menerus dibuktikan dengan kode sungguhan. Loop inilah cara kami membuktikannya: sebuah siklus otonom spot-check-dan-perbaiki yang memperlakukan metriknya sendiri dengan curiga, membuktikan setiap perubahan, dan mengubah setiap perbaikan menjadi penjaga terhadap regresi berikutnya. Ini tidak glamor. Inilah kerja yang memungkinkan kami berkata “kami mendukung bahasa Anda” dan sungguh-sungguh memaksudkannya. Hijau itu mudah. Kebenaran harus dibuktikan lewat kerja.

Multi-Modal Fusion Search: Memilih Retriever yang Tepat untuk Setiap Kueri

Wed, 15 Apr 2026 00:00:00 GMT

Catatan desain historis: artikel April 2026 ini menjelaskan desain perutean pada saat itu, bukan perilaku bawaan saat ini. Koreksi September di bawah hanya membahas klaim pengukuran. Untuk perutean, preset, dan kontrol modalitas eksplisit saat ini, lihat Cara Kerja.

Tidak semua kueri pencarian membutuhkan hal yang sama.

“di mana parseConfig didefinisikan” menginginkan sebuah simbol persis — satu lokasi yang tepat, cepat. “bagaimana autentikasi bekerja” menginginkan makna — sebaran kode terkait yang menjelaskan sebuah konsep. “apa yang rusak jika saya mengubah fungsi ini” menginginkan graf dependensi. “cari string ECONNREFUSED” menginginkan kecocokan literal, tidak lebih.

Grep sangat baik untuk kecocokan literal dan berguna untuk sebagian pencarian referensi, tetapi ia bukan graf dependensi dan tidak memahami makna. Embedding mencakup sisi semantik, tetapi mereka adalah tool yang salah untuk string persis dan analisis dampak. Sebagian besar tool pencarian kode memilih satu engine dan memaksa setiap kueri hidup dengan pilihan itu. Maguyva tidak memilih. Ia mencari tahu jenis pertanyaan apa yang Anda ajukan, lalu memadukan empat retriever dalam proporsi yang layak untuk pertanyaan itu.

Empat modalitas

Di baliknya ada empat cara independen untuk menemukan kode:

semantik — pencarian vektor atas Voyage binary embedding; menemukan kode berdasarkan makna.
teks — pencocokan trigram; menemukan literal, string error, identifier persis.
struktural — kueri AST; menemukan definisi, signature, dan konstruk bahasa.
graf — graf dependensi; menemukan pemanggil, yang dipanggil, dan cakupan dampak.

Masing-masing kuat pada kelas pertanyaan yang berbeda. Triknya adalah memutuskan seberapa besar mempercayai masing-masing untuk kueri yang ada di depan Anda.

Klasifikasi intent

Sebelum retrieval apa pun berjalan, sebuah classifier ringan mengelompokkan kueri ke dalam salah satu dari enam intent, dengan skor keyakinan. Ini sengaja dibuat murah — heuristik berurutan, kecocokan pertama menang — karena berjalan di hot path dan hanya menambah satu-dua milidetik:

dimulai dengan def , class , func , import … → find_definition (kepercayaan 0,95)
“who calls”, “usages of”, “references to” (menanyakan pemanggil, penggunaan, atau referensi) → find_references (0,90)
“impact”, “blast radius”, “what depends on” (menanyakan dampak atau ketergantungan) → impact_analysis (0,90)
sebuah "string" berkutip atau token error seperti traceback → exact_match (0,85–0,90)
sebuah identifier CamelCase atau snake_case → find_definition (0,60–0,80)
“how”, “why”, “explain”, “architecture” (menanyakan cara kerja, alasan, penjelasan, atau arsitektur) → understand_code (0,75)
tidak ada yang cocok → understand_code, kepercayaan rendah (0,40)

Setiap intent membawa profil bobot di seluruh empat modalitas. Berikut angka-angka sesungguhnya:

Intent	semantik	teks	struktural (AST)	graf
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

Jadi “di mana parseConfig didefinisikan” sangat mengandalkan AST (0,6). “bagaimana auth bekerja” bersandar pada vektor semantik (0,5). “apa yang bergantung pada ini” hampir sepenuhnya graf (0,7). “cari ECONNREFUSED” hampir sepenuhnya trigram (0,9), dengan model embedding dimatikan sepenuhnya — karena kemiripan semantik justru tool yang salah untuk sebuah string persis.

Jalur cepat, dan jalur terfusi

Ketika classifier percaya diri — skor ≥ 0,85 — dan kuerinya normal, Maguyva melewati fusi sepenuhnya dan langsung merutekan ke satu modalitas dominan. “di mana X didefinisikan” tidak butuh empat retriever; ia butuh indeks AST, sekarang juga. Jalur langsung itu dilaporkan kembali sebagai fusion_strategy: "direct".

Semua yang ambigu melewati fusi. Empat (atau tiga, pada preset default) modalitas berjalan paralel, masing-masing mengembalikan daftar peringkatnya sendiri, dan kami menggabungkannya.

Weighted Reciprocal Rank Fusion

Memfusikan retriever yang heterogen lebih sulit dari kedengarannya: sebuah cosine similarity 0,82 dan sebuah skor trigram 137 dan sebuah graph centrality 0,004 tidak berada pada skala yang sama, jadi Anda tidak bisa sekadar menjumlahkannya. Reciprocal Rank Fusion menghindari masalah ini dengan membuang skor mentah dan hanya mempertahankan rank yang diberikan setiap engine. Kontribusi sebuah hasil dari satu modalitas adalah:

contribution = weight × 1 / (k + rank + 1)

di mana rank adalah posisinya dalam daftar modalitas tersebut dan k adalah konstanta smoothing. Kontribusi dijumlahkan lintas modalitas untuk hasil apa pun yang ditemukan oleh lebih dari satu engine — hasil yang disepakati antar retriever secara alami naik ke peringkat teratas. Kami menggunakan k = 40 pada preset default dan 60 pada thorough (quick berjalan semantic-only, sehingga fusi tidak pernah aktif di sana). Karya RRF asli mendarat pada k = 60 untuk retrieval umum; kami menggunakan default yang sedikit lebih menekankan posisi teratas, sehingga hasil yang mendapat peringkat tinggi di beberapa modalitas diberi bobot sedikit lebih besar — dan kami tidak menganjurkan menyetelnya secara manual.

Di atas itu, hasil membawa boost graph-importance. Sebuah hub — sebuah fungsi yang menjadi sandaran seluruh basis kode — seharusnya mengungguli sebuah leaf yang jarang disentuh bahkan pada relevansi tekstual yang sama, jadi kami mengalikan setiap kontribusi dengan:

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

Centrality berasal dari metrik PageRank/degree yang telah dihitung sebelumnya oleh pipeline, dan boost-nya dibatasi pada 1,5× sehingga sebuah fungsi populer tidak bisa sepenuhnya mengubur fungsi yang lebih relevan tapi jarang disentuh. Terakhir kami menurunkan peringkat hasil dari path vendor, build, dan archive, lalu melakukan dedup ke chunk terbaik per file.

Apa yang masih belum sempurna

Pengklasifikasi intent adalah sekumpulan regex, bukan model terlatih. Ia menangani bentuk kueri umum dengan heuristik, dan kueri yang ambigu kembali ke understand_code serta campuran yang condong ke semantik. Versi sebelumnya dari tulisan ini menyebut penurunan tingkat tanpa hasil dari sekitar 15% menjadi di bawah 5% sebagai hasil yang telah dicapai. Proposal Desember 2025 sebenarnya mencantumkan perkiraan kondisi awal dan sebuah target; tidak ada kumpulan kueri pendukung atau catatan pengukuran yang disediakan. Kami menarik klaim bahwa perbaikan itu telah tercapai; lihat bukti sumber dan koreksi. Kami belum mengganti pengklasifikasi dengan model terlatih karena versi murah ini cepat dan cukup baik untuk peran perutean yang dituju, dan karena pengklasifikasi yang salah tetapi percaya diri lebih buruk daripada fallback yang jujur. Bobotnya sendiri adalah prior yang dipilih secara manual, bukan dipelajari dari data klik yang tidak kami kumpulkan.

Ajukan Pertanyaan Tanpa Harus Memilih Tool

Seorang agen seharusnya tidak perlu tahu apakah harus meraih grep atau embedding atau call graph — ia seharusnya mengajukan pertanyaannya dengan bahasa sederhana dan mendapat jawaban yang tepat. Multi-modal fusion adalah yang memungkinkan find_symbol, pencarian semantik, dan analisis dependensi berada di balik satu antarmuka kueri: sistem membaca bentuk pertanyaannya dan diam-diam merakit retriever yang tepat untuknya. Model yang menilai embedding itu penting, tetapi begitu juga mengetahui kapan tidak menggunakannya. Memilih tool yang tepat untuk setiap kueri adalah jenis kualitasnya sendiri, dan itu jenis yang lebih kami pilih untuk kami tangani sendiri ketimbang dilemparkan ke pemanggil.

// you bring the question. it brings the tools.

Observabilitas Agen: Hooks, Alloy, dan Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Sistem agen gagal dengan cara-cara yang aneh.

Kadang modelnya yang bermasalah. Kadang toolnya yang bermasalah. Kadang server MCP Anda baik-baik saja, tetapi agen memilih spesialis yang salah, atau menghabiskan separuh sesi melakukan pekerjaan shell yang tidak Anda duga, atau diam-diam menghabiskan anggaran dalam sebuah loop yang dari luar terlihat produktif.

Jika Anda tidak bisa melihat perbedaannya, Anda sebenarnya tidak sedang mengoperasikan sistem agen. Anda sedang menebak-nebak.

Jadi kami membangun stack observabilitas untuk alur kerja kami sendiri: Claude Code, Codex, event hook Claude, event notify Codex, OpenTelemetry native, Grafana Alloy, dan Grafana Cloud di sisi lainnya.

Bagian yang menarik bukan “kami membuat dashboard.” Bagian yang menarik adalah kami harus memecah telemetri menjadi dua stream berbeda karena tidak ada satu pun feed tunggal yang memberi kami gambaran utuh.

Masalahnya: Telemetri Agen Itu Terfragmentasi

Agen coding modern sudah menghasilkan sebagian telemetri. Itu membantu, tetapi tidak cukup.

OTEL native andal menjawab pertanyaan seperti:

Berapa banyak request yang kami buat?
Berapa biaya sebuah sesi?
Di mana span dan trace-nya?
Apakah latensi melonjak?

OTEL native jauh lebih buruk menjawab pertanyaan seperti:

Server MCP mana yang paling diandalkan agen?
Apakah kegagalan ini terjadi di Bash, tool file bawaan, atau panggilan MCP?
Skill mana yang benar-benar aktif?
Tipe subagen mana yang dikirim?
Apakah sesi ini sedang melakukan pekerjaan yang berguna, atau sekadar mondar-mandir tanpa hasil?

Kelas pertanyaan kedua itu lebih dekat ke hooks ketimbang trace.

Tetapi kebalikannya juga benar: beberapa pertanyaan performa terpenting justru lebih dekat ke trace ketimbang hooks.

Jika Anda ingin tahu di mana latensi sebenarnya menumpuk, span mana yang lambat, atau apakah sesi menghabiskan waktu pada panggilan model versus eksekusi tool, Anda butuh data trace, bukan hanya event semantik.

Arsitektur yang Kami Bangun

Kami menjalankan dua jalur telemetri berdampingan.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

Pemisahan itu disengaja.

Ini juga asimetris. Claude Code memberi kami antarmuka hook lifecycle yang jauh lebih kaya. Codex memberi kami OTEL native plus antarmuka notify, sehingga kami menormalkan event penyelesaian turn yang kurang terperinci ke dalam skema log yang sama, alih-alih berpura-pura kedua runtime menyediakan kontrol yang identik.

OTEL native memberi kami stream dasar: log dan trace dari runtime itu sendiri, ditambah metrik di mana runtime benar-benar menghasilkannya.

Event hook dan notify memberi kami lapisan semantik: hal-hal seperti PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, dan metadata terklasifikasi yang benar-benar kami pedulikan saat men-debug perilaku agen. Claude Code menyumbang stream event yang lebih kaya di sini. Codex menyumbang stream ternormalisasi yang kurang terperinci tetapi tetap berguna.

Mengapa Hooks Ada Sama Sekali

Pipeline hook kami memperkaya event sebelum mencapai Loki.

Alih-alih hanya berkata “sebuah tool berjalan,” kami mengklasifikasikan event tersebut ke dalam field seperti:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: backend MCP mana yang menangani panggilan
bash_cli: keluarga perintah shell
subagent_type: jenis spesialis apa yang dikirim
agent_tool: apakah sumbernya Claude Code atau Codex

Itu berarti kami bisa mengajukan pertanyaan yang penting secara operasional:

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

Field-field itu bukan sekadar pemanis. Itulah perbedaan antara “agennya terasa lambat” dan “agen menghabiskan sepuluh menit terakhir dalam operasi git yang sarat shell dengan tingkat kegagalan tool yang tinggi.”

Satu detail implementasi yang terlihat lebih aneh dari kenyataannya: stream Loki bersama masih menggunakan service_name="claude-code-hooks" sebagai label bahkan saat event berasal dari Codex. Pemisahan sesungguhnya antara runtime terjadi di agent_tool.

Mengapa Alloy Berada di Tengah

Grafana Alloy bukan sekadar forwarder dalam setup ini. Ia adalah titik penerapan kebijakan.

Kami mengarahkan stream OTEL native dari Claude Code dan Codex ke proxy Alloy lokal di localhost:4318, lalu membiarkan Alloy membersihkan payload sebelum meneruskannya ke Grafana Cloud.

Itu penting karena telemetri agen mentah penuh dengan field berkardinalitas tinggi yang berguna untuk analisis tetapi buruk sebagai label yang diindeks:

session_id
prompt_id
jumlah token
durasi
blob parameter tool

Jika Anda mengindeks segalanya, Anda akan mendapat ledakan label dan hari yang buruk.

Jadi Alloy melakukan tiga hal untuk kami:

Menjaga sekumpulan kecil label berkardinalitas rendah tetap terindeks.
Memindahkan field yang berisik tetapi berguna ke metadata terstruktur.
Membuang noise murni sepenuhnya.

Idenya sederhana: amati lebih banyak, indeks lebih sedikit.

Mengapa Stream Hook Tidak Melalui Alloy

Stream hook sudah dibentuk untuk Loki.

Saat send_event.py mengirim sebuah event, kami sudah memutuskan field mana yang layak diberi perlakuan label dan mana yang masuk ke body JSON terstruktur. Stream itu langsung menuju gateway OTLP Grafana Cloud tanpa melewati Alloy lagi.

Jadi sistem ini punya pembagian tugas yang jelas:

Alloy menjinakkan stream OTEL native yang mentah.
Pengayaan hook membuat event semantik bisa di-query.

Itu membuat arsitekturnya lebih sederhana daripada memaksa semuanya lewat satu jalur.

Apa yang Sebenarnya Ditampilkan Dashboard

Tangkapan layar di bawah ini berasal dari salah satu dashboard observabilitas di balik alur kerja agen kami. Ini bukan benchmark, dan angka-angkanya hanyalah irisan pada satu titik waktu. Intinya adalah bentuk datanya: activity feed, panggilan tool, kegagalan, prompt, dan pemecahan berdasarkan agen, tool bawaan, penggunaan MCP, perintah shell, dan skill.

Bagian yang berguna adalah dashboard ini hidup di stack Grafana yang sama dengan telemetri agen lainnya. Kami bisa menyaring berdasarkan agen sumber dan keluarga tool, lalu melihat lintas runtime tanpa perlu menciptakan cerita observabilitas yang berbeda untuk setiap sistem.

Salah satu dashboard langsung di balik alur kerja agen kami. Tangkapan layar ini hanyalah satu irisan dari stack Grafana bersama yang juga menerima telemetri dari runtime dan sistem agen kami yang lain. Klik gambar untuk versi resolusi penuh.

Mengapa Trace Lebih Penting Daripada Kelihatannya

Log memberi tahu kami kategori pekerjaan apa yang terjadi. Trace memberi tahu kami bagaimana pekerjaan itu berlangsung seiring waktu.

Perbedaan itu penting dalam sistem agen karena kata “lambat” terlalu umum untuk membantu.

Sebuah trace bisa memberi tahu kami apakah masalahnya berasal dari:

latensi model
waktu eksekusi tool
retry yang berulang
satu interaksi MCP yang sangat mahal
rangkaian panjang operasi-operasi kecil yang terlihat tak berbahaya jika dilihat sendiri-sendiri

Dalam praktiknya kami menggunakan stream hook dan trace Tempo secara bersamaan.

Log hook menjawab: jenis hal apa yang terjadi?
Trace menjawab: ke mana waktunya pergi?

Kombinasi itulah yang mengubah observabilitas dari sekadar dashboard menjadi sebuah penjelasan.

Di Mana Posisi Codex

Codex adalah bagian dari stack yang sama, tetapi tidak identik dengan Claude Code.

Untuk Codex kami menyambungkan dua bagian:

OTEL native dari Codex ke Alloy
Webhook notify ke codex_notify.py, yang memetakan penyelesaian turn ke skema Loki yang sama dengan yang kami gunakan untuk event hook

Itu memberi kami filter terpadu seperti agent_tool="codex-cli" di dalam stream log yang sama.

Catatan jujurnya: payload notify Codex saat ini kurang terperinci daripada payload hook Claude Code karena bukan jenis antarmuka integrasi yang sama. Dalam setup kami hari ini, penyelesaian turn Codex bisa dinormalkan ke skema bersama, tetapi ekstraksi tool-per-tool yang kaya masih lebih baik di stream OTEL native ketimbang di bridge notify.

Itu bukan alasan untuk menghindari tulisan ini. Itulah justru intinya. Sistem observabilitas sungguhan dirakit dari sinyal-sinyal yang tidak sempurna.

Grafana Lewat MCP Mengubah Permainan

Pergeseran yang lebih besar adalah Grafana bukan lagi hanya tempat manusia berkunjung lewat browser.

Dalam repo ini kami juga mengekspos Grafana lewat MCP. Artinya, seorang agen bisa meng-query Loki, Prometheus, dan Tempo secara langsung tanpa perlu menunggu manusia memeriksa dashboard secara manual terlebih dahulu.

Itu mengubah observabilitas menjadi input aktif bagi alur kerja.

Seorang agen bisa bertanya:

Keluarga tool mana yang paling banyak gagal dalam satu jam terakhir?
Server MCP mana yang mendominasi sebuah sesi?
Apakah perubahan terbaru mengurangi kegagalan tool, atau hanya memindahkan pekerjaan ke jalur yang lebih sarat shell dengan kesalahan yang sama?
Trace mana yang menunjukkan latensi tertinggi atau retry berulang?

Setelah Anda punya itu, Anda sudah sangat dekat dengan loop peningkatan diri.

Dari Dashboard Menuju Feedback Loop

Inilah bagian yang paling kami anggap menarik.

Setelah stack observabilitas bisa di-query dari lapisan agen, telemetri berhenti menjadi sarana pelaporan yang pasif dan berubah menjadi sinyal kendali.

Loop-nya terlihat seperti ini:

Aktivitas agen menghasilkan trace, metrik, dan log hook yang telah diperkaya.
Grafana menyimpan bukti tersebut di Loki, Tempo, dan Prometheus tempat metrik itu ada.
Agen meng-query bukti itu lewat Grafana MCP.
Sistem mengidentifikasi bauran tool yang buruk, skill yang rapuh, perutean yang lemah, atau alur kerja sarat shell yang terus menghasilkan kesalahan yang seharusnya bisa dihindari.
Agen atau operator menyesuaikan prompt, config agen, deskripsi skill, aturan perutean, atau akses tool.
Sesi berikutnya menghasilkan bentuk telemetri baru, dan siklus itu berulang.

Itulah cara Anda berpindah dari “dashboard yang menarik” menjadi “sistem peningkatan yang terukur.”

Tujuannya bukan memaksimalkan satu kategori tool. Tujuannya adalah menemukan bauran CLI, tool bawaan, panggilan MCP, dan skill yang tepat untuk pekerjaan yang sesungguhnya sedang dilakukan.

Apa yang Bisa Kami Jawab dengan Ini

Setelah kedua runtime mendarat di stack Grafana yang sama, kami bisa menjawab pertanyaan operasional jauh lebih cepat:

Apakah kegagalan terkonsentrasi pada satu keluarga tool?
Apakah alur kerja yang sarat shell menciptakan kesalahan yang seharusnya bisa dihindari, padahal seharusnya ada tool level-lebih-tinggi?
Server MCP mana yang menanggung beban kerja terbesar?
Apakah kami membayar untuk aktivitas agen yang tidak menghasilkan kemajuan yang berarti?
Apakah sebuah sesi tidak sehat karena modelnya, tool-nya, atau lapisan orkestrasinya?

Ini sangat berguna dalam alur kerja multi-agen, tempat “agennya sibuk” hampir tidak memberi tahu apa-apa.

Jika satu spesialis terus dikirim dan menghasilkan tingkat kegagalan yang tinggi, itu masalah perutean atau pembentukan prompt.

Jika satu server MCP mendominasi semua panggilan, itu bisa berarti arsitektur yang baik atau tanda bahwa semua yang lain hanya menambah beban.

Jika kegagalan tool melonjak sementara biaya tetap tinggi, Anda punya masalah operasional, bukan masalah kualitas.

Jika pekerjaan shell terus gagal dengan cara yang bisa diprediksi dan seharusnya bisa dihindari, padahal seharusnya ada tool level-lebih-tinggi, itu sinyal produk.

Jika satu skill terus aktif tetapi tidak memperbaiki hasil, itu sinyal prompt atau perutean.

Pelajaran Sesungguhnya

Pelajaran yang lebih dalam di sini adalah observabilitas agen membutuhkan telemetri runtime sekaligus telemetri alur kerja.

Telemetri runtime memberi tahu Anda apa yang dilakukan sistem.

Telemetri alur kerja memberi tahu Anda apa yang dikira agen sedang ia lakukan.

Kami butuh keduanya.

Jika Anda hanya menyimpan trace dan counter, Anda kehilangan lapisan semantik. Jika Anda hanya menyimpan event hook, Anda kehilangan latensi, span, dan gambaran runtime yang lebih luas.

Dan jika Anda menyimpan keduanya tetapi tidak pernah memasukkannya kembali ke lapisan agen, Anda punya monitoring, bukan adaptasi.

Kombinasi itulah yang membuat sistem cukup bisa dijelaskan untuk dioperasikan dan cukup bisa disetel untuk ditingkatkan.

Apa yang Masih Belum Sempurna

Masih ada sisi-sisi yang kasar.

Tidak semua event hook menyertakan data durasi dan token seperti yang kami inginkan.
Sebagian tampilan timing terbaik masih berasal dari trace Tempo, bukan log hook.
Codex hari ini masih kurang kaya secara semantik dibandingkan Claude Code dalam stream event yang diperkaya.
Tangkapan layar dashboard adalah tampilan operasional yang sungguhan, bukan artefak pemasaran yang dipoles.

Poin terakhir itu disengaja. Kami lebih memilih menunjukkan panel instrumen yang sesungguhnya daripada berpura-pura sistem agen secara ajaib menjelaskan dirinya sendiri.

Mengapa Ini Penting Bagi Maguyva

Maguyva soal memberi agen kecerdasan kode yang lebih baik. Tetapi begitu agen benar-benar melakukan pekerjaan yang berguna, sebuah kebutuhan baru segera muncul: Anda perlu melihat bagaimana perilaku mereka.

Kualitas pencarian, kualitas perutean, pemilihan tool, dan efisiensi konteks semuanya berubah menjadi masalah yang bisa diobservasi.

Itulah sebabnya kami rasa ini layak ditulis. Stack agen masa depan bukan sekadar prompt dan tool. Ia adalah prompt, tool, dan lapisan instrumentasi yang memberi tahu Anda apakah keseluruhannya berjalan dengan baik.

Jika Anda membangun alur kerja agen yang serius, observabilitas bukan infrastruktur opsional. Ia adalah bagian dari produk.

Menambang Pengetahuan dari Riwayat Perubahan: Bagaimana Perubahan Menjadi Memori Institusional

Tue, 03 Feb 2026 00:00:00 GMT

Angka dalam tulisan ini mencerminkan sistem pada saat publikasi (Februari 2026). Lihat halaman tim kami untuk angka terkini.

Setiap tim engineering menghadapi tantangan yang sama: perubahan terjadi terus-menerus, tetapi alasan di balik perubahan itu menghilang. Enam bulan kemudian, seseorang bertanya “kenapa kita memakai DuckDB untuk stage pipeline?” dan jawabannya hanya hidup di kepala siapa pun yang membuat keputusan itu — jika orang itu masih ada.

Kami membangun sebuah mining workflow yang menutup loop ini. Perubahan mengalir lewat commit git, diproses oleh pipeline mining kami, menjadi entri changelog terstruktur dan catatan keputusan arsitektural, lalu mengalir kembali ke agen AI kami lewat query CLI. Hasilnya: memori institusional yang bisa diakses baik oleh manusia maupun AI.

Masalahnya: Keputusan Menguap

Bayangkan skenario yang umum. Seorang developer melakukan commit:

feat(canonical): add DuckDB runtime for pipeline stages

Commit ini merepresentasikan sebuah pilihan arsitektural yang signifikan. Tim mengevaluasi opsi, mempertimbangkan trade-off, dan akhirnya memilih DuckDB karena alasan-alasan spesifik. Tetapi seluruh konteks itu hanya hidup di:

Sebuah thread Slack (mungkin sudah terhapus)
Ingatan seseorang (pasti memudar)
Sebuah komentar di kode (mungkin, kalau Anda beruntung)

Tiga bulan kemudian, anggota tim baru bertanya: “Haruskah saya pakai DuckDB atau SQLite untuk stage baru ini?” Tanpa memori institusional, mereka akan mengulang pekerjaan dari nol atau membuat pilihan yang tidak konsisten.

Loop-nya: Dari Commit ke Konteks

Mining workflow kami mengubah histori git menjadi pengetahuan yang bisa di-query:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

Wawasan kuncinya: baik changelog maupun architectural decision mengalir dari histori git yang sama, diproses lewat satu pipeline terpadu. Ini memastikan tidak ada yang lolos begitu saja.

Bagaimana Mining Bekerja

Langkah 1: Sinkronkan Indeks

uv run orkestra mine sync

Perintah ini memindai histori git dan membangun indeks dari semua commit. Ia mengekstraksi sinyal terstruktur dari setiap commit:

Tipe commit menurut Conventional Commits (feat, fix, chore, docs)
Scope (package atau area mana)
Penanda breaking change
File yang tersentuh dan metrik kompleksitas

Langkah 2: Periksa Status Cakupan

uv run orkestra mine status

Beginilah status kami saat ini:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15.637 commit diproses. 476 menjadi architectural decision. 6.799 menjadi entri changelog. Setiap commit terklasifikasi.

Langkah 3: Ambil Kandidat untuk Ditinjau

uv run orkestra mine candidates --limit 50 --full

Ini memunculkan commit yang belum diproses, lengkap dengan konteks untuk klasifikasi:

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

Sinyal-sinyal ini membantu memandu klasifikasi: is_releasable_type: true menunjukkan ini seharusnya muncul di changelog. Jumlah insertion yang besar dan file infrastruktur menunjukkan ini mungkin juga sebuah architectural decision.

Langkah 4: Klasifikasikan Commit

Dua jalur bercabang di sini: entri changelog dan architectural decision.

Untuk entri changelog:

uv run orkestra mine classify abc123 --changelog added

Ini mencatat bahwa commit abc123 seharusnya muncul di changelog di kategori “Added.”

Untuk architectural decision:

Pertama, dapatkan ID decision yang sungguhan:

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Lalu klasifikasikan dengan ID decision tersebut:

uv run orkestra mine classify abc123 --decision DEC-PL-143

Ini menautkan commit ke sebuah decision record yang akan dibuat atau diperbarui.

Untuk pemrosesan batch (apa yang sebenarnya kami lakukan):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

Format JSONL mendukung kedua domain dalam satu proses:

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Langkah 5: Render Output

uv run orkestra registry changelog render --package <pkg>

Ini menghasilkan file CHANGELOG.md per package dari ledger. Changelog adalah artefak turunan — hapus saja, dan mereka akan terbangun ulang secara sempurna dari ledger sumbernya.

Struktur Decision Record

Decision hasil ekstraksi menjadi file YAML dengan metadata yang kaya:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Setiap decision menaut kembali ke commit sumbernya. Setiap decision menyebutkan file mana yang terpengaruh. Relasi antar decision bersifat eksplisit.

Integrasi CLI: Meng-query Memori Institusional

Di sinilah loop-nya menutup. Agen bisa meng-query decision lewat CLI:

# Search by topic
uv run orkestra registry decisions search --query "retry"

Mengembalikan decision tentang logika retry, error handling, pola pemulihan.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

Mengembalikan decision record lengkap dengan konteks, rationale, dan dampaknya.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

Menunjukkan pilihan arsitektural apa yang baru-baru ini dibuat.

Bagaimana Agen Menggunakan Ini

Instruksi baseline orchestrator kami mencakup:

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

Ketika seorang agen diminta mengimplementasikan sesuatu yang berkaitan dengan DuckDB, ia bisa memeriksa terlebih dahulu:

uv run orkestra registry decisions search --query "DuckDB"

Dan menemukan DEC-PL-142, mempelajari:

Mengapa kami memilih DuckDB (konteks)
Bagaimana menggunakannya dengan benar (agent_guidance)
File apa yang perlu dilihat (files)
Decision terkait apa yang ada (related)

Agen tidak mengulang pekerjaan dari nol. Ia membangun di atas pola yang sudah mapan.

Uji Tiga Pertanyaan

Tidak setiap commit layak mendapat decision record. Kami menggunakan Uji Tiga Pertanyaan untuk menyaring:

Apakah ini sulit dibuat? Apakah butuh analisis signifikan, evaluasi trade-off, atau perdebatan?
Apakah mahal untuk diubah? Akankah membalikkan keputusan ini membutuhkan rework yang signifikan?
Apakah berdampak lintas sistem? Apakah ini memengaruhi banyak package atau menetapkan pola yang akan diikuti orang lain?

Jika sebuah commit menjawab “ya” untuk setidaknya satu dari pertanyaan ini, commit itu menjadi kandidat untuk ekstraksi decision. Tingkat khas kami: 1-4 decision per 100 commit (sekitar 1-4%).

Untuk entri changelog, batasnya lebih rendah: setiap perubahan yang terlihat pengguna (fitur, perbaikan, peningkatan) akan dicatat. Chore internal, pembaruan dokumentasi, dan refactor biasanya dilewati. Tingkat khas kami: 30-50 entri changelog per 100 commit.

Penyimpanan Data: Ledger Append-Only

Sistem mining menggunakan ledger JSONL append-only untuk operasi multi-agen yang bebas konflik:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

Format JSONL dengan merge=union dalam .gitattributes berarti beberapa agen bisa mengklasifikasikan commit secara bersamaan tanpa merge conflict. Setiap baris berdiri sendiri.

Validation Gate

Sebelum sesi mining apa pun, kami menjalankan validasi:

uv run orkestra mine validate --quick

Ini memeriksa:

Validitas format SHA
Kepatuhan format ID decision
Tidak ada entri duplikat untuk SHA yang sama
Decision yang dirujuk benar-benar ada

Setelah klasifikasi, kami memvalidasi lagi sebelum melakukan commit perubahan.

Mengapa Ini Penting

Feedback loop yang kami bangun memecahkan beberapa masalah:

Untuk anggota tim baru: Alih-alih bertanya “kenapa kita melakukan X?”, mereka bisa mencari di registry decision. Konteksnya terjaga.

Untuk agen AI: Mereka tidak beroperasi dalam ruang hampa. Mereka bisa meng-query pengetahuan institusional sebelum membuat rekomendasi. Ketika diminta menambahkan stage pipeline baru, mereka bisa menemukan pola DuckDB dan mengikutinya.

Untuk konsistensi arsitektural: Decision bersifat eksplisit dan bisa dicari. Ketika seseorang mengusulkan pendekatan yang bertentangan dengan decision yang sudah ada, sistem bisa memunculkan konfliknya.

Untuk pembuatan changelog: Release note bukan lagi kepanikan menit terakhir. Mereka adalah produk sampingan dari klasifikasi berkelanjutan selama pengembangan.

Untuk onboarding: Agen baru mewarisi seluruh konteks basis kode. Mereka tidak sekadar melihat kode — mereka melihat decision yang membentuknya.

Keadaan Saat Ini

Per hari ini:

15.637 commit diproses lewat pipeline
476 architectural decision diekstraksi dan didokumentasikan
6.799 entri changelog tercatat
Cakupan 100% di kedua domain

Setiap commit sejak kami mulai sudah terklasifikasi. Memori institusionalnya lengkap dan bisa di-query.

Memulai

Jika Anda ingin mengimplementasikan sesuatu yang serupa:

Mulai dengan format Conventional Commits. Pipeline mining bekerja paling baik ketika commit punya prefix terstruktur (feat:, fix:, chore:).
Definisikan domain Anda. Kami menggunakan domain seperti pipeline, agent-design, observability, data-modeling. Ini mengorganisasi decision berdasarkan area.
Bangun kebiasaan klasifikasi. Mining berjalan baik ketika tim secara rutin mengklasifikasikan commit. Pemrosesan batch dengan bantuan LLM membantu penskalaan.
Buat decision bisa di-query. Nilainya berlipat ganda ketika agen bisa mencari decision lewat CLI. Susun output Anda agar dapat diproses mesin.
Tutup loop-nya. Decision seharusnya memengaruhi pekerjaan mendatang. Sertakan referensi decision dalam instruksi agen dan checklist code review.

Tujuannya bukan dokumentasi yang sempurna. Ini soal membuat alasan di balik perubahan bisa diakses oleh manusia maupun AI, hari ini dan enam bulan dari sekarang. Ketika perubahan menjadi memori institusional, tim membangun di atas pola yang sudah mapan, bukan menciptakannya ulang.

Mining workflow adalah bagian dari orchestration engine kami, khususnya modul context engine dalam package orchestration kami.

Skill Mining: Dari 3.500 Kandidat Menjadi 466 Kapabilitas

Tue, 27 Jan 2026 00:00:00 GMT

Angka dalam tulisan ini mencerminkan sistem pada saat publikasi (Januari 2026). Lihat halaman tim kami untuk angka terkini.

Masalah 3.500 Skill

Ketika kami mulai membangun sistem orkestrasi agen, kami menghadapi tantangan yang menarik: ada ribuan calon skill yang bertebaran di seluruh ekosistem AI. Repositori GitHub, dokumentasi vendor, proyek komunitas, pola internal — skill ada di mana-mana. Tetapi yang mana yang penting? Yang mana yang benar-benar berhasil? Dan bagaimana Anda memelihara sebuah pustaka skill yang koheren yang benar-benar bisa digunakan agen?

Jawaban kami: sebuah loop mining dan ingestion yang sistematis.

Angka-angka Hari Ini

Hanya sedikit lebih dari tiga bulan setelah Anthropic meluncurkan Agent Skills pada 16 Oktober 2025, inilah posisi kami saat tulisan ini dipublikasikan pada 27 Januari 2026:

Metrik	Jumlah
Kandidat teridentifikasi	3.500+
Skill teradopsi	466
Skill vendor	373
Skill internal	93
Vendor aktif	25+
Rata-rata token per skill	2.834
Tool yang dirujuk	89
Tag unik	635

Kami telah meninjau lebih dari 3.500 kandidat skill. Kami telah mengadopsi 466. Itu tingkat adopsi 13% — dan selektivitas itu memang disengaja.

Sistem Tier Pengetahuan

Tidak semua skill diciptakan setara. Kami mengorganisasikannya ke dalam lima lapisan pengetahuan (K0-K4), masing-masing merepresentasikan cakupan penerapan yang berbeda:

K0: Foundations (Universal)

Skill yang harus dimiliki setiap agen. Ini merepresentasikan kapabilitas “pemikir yang baik” yang berlaku di mana saja.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

Skill K0 bisa dibawa ke proyek mana pun, domain mana pun, stack mana pun. Mereka mengenkode pola kognitif yang universal.

K1: Identities (Bidang Keahlian)

Skill “engineer yang baik” atau “peneliti yang baik” yang berlaku lintas proyek dalam satu bidang keahlian.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Domains (Keahlian Bidang)

Skill “pakar database yang baik” atau “security engineer yang baik” yang bisa dibawa dalam sebuah bidang.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Stacks (Teknologi)

Skill “pengguna Supabase yang baik” atau “developer Cloudflare yang baik” untuk stack teknologi spesifik.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Project (Organisasi)

Skill yang spesifik untuk organisasi dan alur kerja kami.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

Loop Mining-nya

Fase 1: Discovery

Skill datang dari mana-mana:

Repositori Vendor: AWS, Anthropic, Cloudflare, Supabase, dan kontributor komunitas mempublikasikan koleksi skill. Kami melacak 25+ direktori sumber vendor.

Proyek Komunitas: GitHub penuh dengan template Claude Code, pola agen, dan definisi alur kerja.

Pola Internal: Seiring tim kami memecahkan masalah, pola-pola muncul. Ini diformalkan menjadi skill.

Mining Dokumentasi: Dokumentasi teknis sering mengandung skill implisit — prosedur, checklist, pohon keputusan.

Discovery berjalan terus-menerus. Kami menggunakan sebuah backlog skill untuk melacak kandidat sebelum evaluasi formal.

Fase 2: Evaluasi

Setiap kandidat melewati rubrik yang sama:

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

Kelima kriteria produk harus terpenuhi. Inilah sebabnya 87% kandidat ditolak.

Lalu setiap kandidat melewati tinjauan trust yang terpisah. Kami tidak memperlakukan sebuah repositori vendor resmi, seorang maintainer komunitas yang terkenal, dan sebuah repo GitHub acak sebagai sumber kebenaran yang setara.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

Vendor tepercaya mendapat tinjauan provenance yang lebih ringan, tetapi bukan jaminan lolos begitu saja. Sumber yang tidak tepercaya atau tidak dikenal mendapat audit manual yang lebih dalam, dan kami tidak menjalankan script bawaan sampai script itu sudah dibaca, ditetapkan batas penggunaannya, dan diklasifikasikan sebagai aman.

Analisis Gap: Sebelum mengadopsi, kami mencari di registry kami:

uv run orkestra skills search "<capability>"

Jika kami sudah punya, kami tidak butuh itu. Jika kami punya sesuatu yang mirip, kami mungkin menggabungkan alih-alih mengadopsi.

Penilaian Kedalaman dan Standar: Kami juga menilai seberapa penuh sebuah kandidat menggunakan model agent-skill. Sebuah SKILL.md tunggal masih bisa berguna, tetapi skill yang lebih dalam lebih bernilai ketika mereka memisahkan instruksi dari referensi, script, dan asset dengan cara yang dianjurkan agentskills.io.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

Bintang GitHub bisa sedikit mengangkat skor kredibilitas, tetapi mereka tidak pernah menyelamatkan skill yang dangkal atau tidak aman. Sebuah repo berbintang tinggi dengan satu SKILL.md yang samar dan script yang opak mendapat skor lebih rendah daripada repo yang lebih kecil dengan deskripsi yang presisi, materi referensi terkurasi dalam references/, dan helper atomik yang benar-benar memanfaatkan kapabilitas skill secara penuh.

Analisis Struktural: Kami memeriksa kualitas skill:

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

Jika sebuah kandidat menyertakan script, tinjauan itu menjadi lebih ketat. Sebuah skill yang baik bukan sekadar berguna; ia harus mudah dipahami, memiliki batas yang jelas, dan aman untuk diserahkan ke agen. Filter keamanan itu saja mendiskualifikasi sebagian kandidat yang sebenarnya menarik.

Fase 3: Ingestion

Ketika sebuah skill lulus evaluasi, ia masuk ke registry. Tetapi skill tidak pernah diadopsi tanpa perubahan. Mereka dimodifikasi agar cocok dengan sistem kami.

Modifikasi saat Adopsi:

Normalisasi Metadata: Setiap skill mendapat skema frontmatter kami
Penetapan K-Tier: Skill ditempatkan di lapisan pengetahuan yang sesuai
Pengayaan Tag: Tag ditambahkan untuk discovery
Deklarasi Tool: Tool yang diizinkan dideklarasikan secara eksplisit
Penyelarasan Section: Konten distruktur ulang agar sesuai dengan template kami

Sebuah YAML skill tipikal setelah ingestion:

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

Fase 4: Penetapan Scope

Skill ditetapkan ke scope — kategori yang menentukan agen mana yang memuat skill mana:

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

Agen mendeklarasikan scope mereka, dan skill ditetapkan secara otomatis:

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

Fase 5: Materialisasi

Skill tidak hidup sebagai YAML di produksi. Mereka di-render menjadi file SKILL.md yang bisa dimuat Claude Code:

uv run orkestra sync

Perintah ini:

Membaca semua definisi YAML skill
Merender lewat template Jinja
Menulis file SKILL.md ke .claude/skills/
Mengorganisasi berdasarkan K-tier (foundations/, identities/, domains/, stacks/, project/)

Struktur output akhirnya:

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

Pola Dormant Scope

Salah satu pola kami yang paling ampuh adalah skill “teradopsi-tapi-tidak-dimuat.” Kami menyebutnya dormant scope.

Pertimbangkan skill scientific computing dari repositori k-dense-scientific. Kami telah mengadopsi 120+ skill yang mencakup bioinformatika, kimia, quantum computing, dan clinical informatics. Tetapi sebagian besar agen kami tidak butuh molecular docking atau analisis ekspresi gen.

Alih-alih memuat semua 120 skill ke setiap agen (yang akan membengkakkan jendela konteks), kami:

Mengadopsi skill dengan scope tertentu (misalnya, bioinformatics)
Membiarkannya tetap dormant — terdaftar tapi tidak dimuat
Mengaktifkan hanya ketika sebuah agen mendeklarasikan scope itu

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

Pola ini memungkinkan kami memiliki 466 skill di registry sementara agen tipikal hanya memuat 40-60 yang relevan.

Tipe Skill

Skill hadir dalam tiga pola kognitif:

Workflow

Langkah prosedural yang berurutan: “1. Lakukan X, 2. Lalu Y, 3. Terakhir Z”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

Discipline

Guardrail perilaku: “Selalu X”, “Jangan pernah Y”, “Utamakan Z”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

Checklist

Kriteria verifikasi: “Konfirmasi X”, “Verifikasi Y”, “Periksa Z”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

Quality Gate

Setiap skill harus lulus validasi sebelum dirilis:

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

Deskripsi harus 50-400 karakter dengan frase trigger (“Gunakan saat…”, “Ketika Anda butuh…”) sehingga Claude Code tahu kapan harus menyarankannya.

Kami memvalidasi secara berkelanjutan:

uv run orkestra validate --show-warnings

Ekosistem Vendor

373 skill vendor kami berasal dari:

Provider	Skill	Domain
AWS Agent	19	Layanan cloud
Anthropic	12	Generasi dokumen
Cloudflare	8	Edge computing
Supabase	5	Database
k-dense	100+	Scientific computing
silvainfm	4	Data science
Java Developer Kit	45+	Spring/Java
Vercel	1	Otomasi browser

Setiap direktori sumber vendor dideklarasikan dalam metadata.yaml:

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

Ketika orkestra sync berjalan, skill vendor di-symlink ke .claude/skills/vendor/ dengan namespace provider mereka.

Apa yang Telah Kami Pelajari

Selektivitas terbayar. Tergoda untuk mengadopsi semua yang terlihat berguna. Tetapi setiap skill punya biaya token. Dengan rata-rata 2.834 token per skill, konteks cepat membengkak. Tingkat adopsi 13% kami menjaga agen tetap ramping.

Struktur memungkinkan discovery. Sistem K-tier bukan sekadar organisasi — ini soal portabilitas. Skill K0 bisa digunakan ulang di mana saja. Skill K4 sengaja dibuat spesifik proyek. Kejelasan ini membantu baik manusia maupun agen menemukan apa yang mereka butuhkan.

Dormant scope bisa berskala. Anda bisa mengadopsi ratusan skill tanpa memuat semuanya. Scope memungkinkan Anda membangun registry yang komprehensif sembari menjaga jendela konteks masing-masing agen tetap terkendali.

Modifikasi saat adopsi itu esensial. Skill vendor mentah jarang cocok dengan sistem Anda. Proses ingestion — menambahkan metadata, menetapkan tier, memperkaya tag — membuat skill eksternal bisa bekerja secara internal.

Mining berjalan terus-menerus. Angka 3.500 itu terus bertambah. Repo vendor baru muncul. Pola komunitas bermunculan. Alur kerja internal semakin mapan. Loop-nya tidak pernah berhenti.

Apa Selanjutnya

Kami sedang mengerjakan beberapa peningkatan:

Deteksi gap otomatis: Peringatkan ketika kegagalan agen yang umum bisa diatasi oleh sebuah skill yang belum diadopsi
Alur kerja deprecation skill: Proses formal untuk mempensiunkan skill yang sudah digantikan atau tidak terpakai
Dependensi antar-skill: Deklarasi eksplisit dari prasyarat skill
Analitik penggunaan: Lacak skill mana yang benar-benar dipanggil agen versus sekadar dimuat

Loop mining skill ini adalah infrastruktur. Ini tidak glamor. Tetapi inilah yang membuat 41 agen bekerja secara koheren dengan 466 kapabilitas sembari tetap berada dalam batas konteks.

Itulah kisah bagaimana 3.500 menjadi 466. Bukan dengan mengabaikan 3.000 — tetapi dengan mengevaluasinya secara sistematis dan hanya mengadopsi yang benar-benar berhasil.

Ingin melihat sistem skill ini beraksi? Lihat uv run orkestra skills list untuk menjelajahi registry kami saat ini.

Progressive Disclosure: Jendela CLI ke Dalam Sistem Agen

Tue, 20 Jan 2026 00:00:00 GMT

Angka dalam tulisan ini mencerminkan sistem pada saat publikasi (Januari 2026). Lihat halaman tim kami untuk angka terkini.

Desain sistem agen membuat cara kerjanya sulit diamati. Mereka membuat keputusan, memanggil tool, dan mengoordinasikan pekerjaan lintas puluhan spesialis. Tetapi ketika sesuatu berjalan salah — atau ketika Anda sekadar ingin memahami apa yang terjadi — ke mana Anda harus melihat?

Jawabannya adalah progressive disclosure: sebuah interface berlapis yang mengungkap kompleksitas tepat sebanyak yang Anda butuhkan, tepat pada saat Anda membutuhkannya.

Masalah Kurangnya Keterlihatan

Sebuah sistem orkestrasi agen modern mungkin punya:

40+ agen spesialis, masing-masing dengan kapabilitas yang berbeda
700+ skill yang merentang dari otomasi internal hingga integrasi vendor
470+ architectural decision yang membentuk perilaku
Lusinan server tool MCP yang menyediakan kapabilitas eksternal

Kompleksitas ini disengaja. Agen butuh akses ke konteks yang kaya — pengetahuan domain, kecerdasan kode, skema database — untuk membuat keputusan yang baik. Tetapi kekayaan yang sama itu menciptakan masalah visibilitas.

Bagaimana Anda tahu agen mana yang menangani migrasi database? Decision apa yang membentuk perilaku peringkat sistem pencarian? Tool apa yang bisa diakses oleh architecture advisor?

Tanpa akses yang terstruktur, Anda hanya bisa membaca kode sumber atau berharap dokumentasinya masih relevan.

Progressive Disclosure sebagai Arsitektur

Progressive disclosure bukan sekadar pola UI. Ini prinsip arsitektural: organisasikan informasi dalam lapisan-lapisan, masing-masing lebih dalam dari sebelumnya, sehingga pengguna bisa berhenti pada level yang menjawab pertanyaan mereka.

Untuk sistem agen, ini diterjemahkan menjadi perintah CLI dengan kedalaman yang meningkat:

Level	Perintah	Pertanyaan yang Dijawab
1	`orkestra system status`	Apakah semuanya sehat?
2	`orkestra agents list`	Agen apa saja yang ada?
3	`orkestra agents info <name>`	Apa yang dilakukan agen ini?
4	`orkestra decisions search`	Mengapa ia bekerja dengan cara ini?
5	Tool MCP Maguyva	Tunjukkan kodenya kepada saya.

Setiap level menjawab pertanyaan lanjutan yang alami. Anda jarang perlu langsung melompat ke level 5.

Level 1: Kesehatan Sistem

Pertanyaan pertama selalu: apakah semuanya bekerja?

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Satu perintah. Empat angka. Cukup untuk tahu sistemnya terkonfigurasi dan registry-nya terisi.

Jika jumlah agen tiba-tiba turun atau skill gagal dimuat, Anda melihatnya di sini terlebih dahulu. Tidak perlu menyelami log.

Level 2: Inventaris Agen

Setelah Anda tahu sistemnya sehat, pertanyaan berikutnya adalah: apa saja yang tersedia?

$ orkestra agents list

Ini mengembalikan data terstruktur — nama agen, deskripsi, preferensi model, cakupan domain. Output-nya JSON secara default, sehingga mudah di-pipe ke jq untuk penyaringan:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Ingin agen yang menangani pekerjaan database? Perintah pencariannya mempersempit itu:

$ orkestra agents search "database"

Ini memindai nama, deskripsi, dan kapabilitas. Anda menemukan spesialis yang tepat tanpa membaca 40 definisi agen.

Level 3: Menyelami Agen Secara Mendalam

Menemukan agen yang terlihat relevan? Perintah info mengungkap segalanya:

$ orkestra agents info architecture-advisor

Output-nya mencakup:

Metadata: Nama, kategori, preferensi model, deskripsi
Domain: Area pengetahuan mana yang dicakup agen ini
Identity: Sifat karakter (architect, strategist, knowledge-architect)
Tool guide: Dokumentasi tool mana yang disuntikkan ke dalam konteks
Tool: Daftar lengkap tool MCP yang tersedia untuk agen ini

Berikut contoh apa yang Anda lihat:

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

Ini memberi tahu Anda persis apa yang bisa dilakukan agennya. Tidak perlu kode sumber.

Level 4: Arkeologi Decision

Agen berperilaku sesuai decision yang terdokumentasi. Ketika Anda perlu memahami mengapa sesuatu bekerja dengan cara tertentu, registry decision adalah sumber kebenarannya.

$ orkestra decisions search "agent"

Ini mengembalikan architectural decision yang cocok:

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Setiap decision punya provenance lengkap — kapan dibuat, mengapa, trade-off apa yang dipertimbangkan, commit mana yang mengimplementasikannya:

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

Ini adalah dokumentasi arsitektural yang tetap relevan karena ditambang dari commit, bukan dipelihara secara manual.

Level 5: Kecerdasan Kode Langsung

Ketika Anda perlu melihat implementasi sesungguhnya — bukan metadata tentangnya — tool MCP Maguyva menyediakan akses langsung.

Dari dalam sebuah sesi agen:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Ini secara otomatis merutekan lintas pencarian semantik, teks, dan AST untuk menemukan kode yang relevan. Untuk simbol spesifik:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Untuk analisis dependensi:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Ini bukan sekadar pengganti grep. Tool-tool ini mempertimbangkan struktur graf, terindeks secara semantik, dan terintegrasi dengan kecerdasan kode yang sama yang menggerakkan agen-agen itu sendiri.

Pencarian Terpadu Lintas Registry

Kadang Anda tidak tahu registry mana yang menyimpan jawabannya. Pencarian terpadu merentang ke segalanya:

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 kecocokan di lima registry. Ringkasannya memberi tahu Anda ke mana harus menyelam lebih dalam. Hapus --summary untuk hasil detail, atau tambahkan --limit 5 untuk menjaga output tetap ringkas.

Mengapa Ini Penting

Progressive disclosure bukan sekadar soal kenyamanan. Ini mengubah bagaimana Anda berinteraksi dengan sistem yang kompleks.

Debugging menjadi bisa dikelola. Ketika sebuah agen membuat keputusan yang tidak terduga, Anda tidak meng-grep lewat log. Anda memeriksa tool apa yang bisa diaksesnya (agents info), decision apa yang membentuk perilakunya (decisions search), dan menelusuri implementasinya jika perlu (intelligent_search).

Onboarding jadi lebih cepat. Anggota tim baru tidak perlu membaca seluruh basis kode. Mereka mulai dengan system status, menjelajah dengan agents list, dan menyelam lebih dalam hanya ketika mereka menjumpai sesuatu yang tidak mereka pahami.

Dokumentasi tetap relevan. Karena CLI-nya membaca dari registry yang sama yang mengonfigurasi agen-agennya, output-nya selalu akurat. Tidak ada kesenjangan antara apa yang dikatakan dokumentasi dan apa yang dilakukan sistemnya.

CLI sebagai Interface

Kami bisa saja membangun dashboard web. Kami bisa saja menulis dokumentasi yang panjang. Sebagai gantinya, kami membangun sebuah CLI yang membaca dari sumber kebenarannya.

CLI-nya punya beberapa keunggulan:

Composable: Pipe output-nya lewat jq, integrasikan dengan script
Scriptable: Otomasikan pemeriksaan, hasilkan laporan
Cepat: Tidak ada page load, tidak ada alur autentikasi
Akurat: Membaca konfigurasi sesungguhnya, bukan representasi yang di-cache

Untuk sistem tempat ketepatan hasil lebih penting daripada estetika, CLI menang.

Membangun Progressive Disclosure Anda Sendiri

Jika Anda membangun sistem agen, pertimbangkan bagaimana pengguna akan memeriksanya:

Mulai dengan pemeriksaan kesehatan. Satu perintah yang memberi tahu Anda apakah semuanya bekerja.
Sediakan tampilan inventaris. Daftarkan apa yang ada sebelum menjelaskan fungsinya.
Aktifkan kueri yang ditargetkan. Pencarian mengalahkan penjelajahan pada skala besar.
Ekspos provenance. Biarkan pengguna menelusuri decision hingga ke asalnya.
Sambungkan ke kecerdasan kode. Pada akhirnya, pengguna perlu melihat implementasinya.

Setiap lapisan menjawab pertanyaan lanjutan. Susun lapisan-lapisan tersebut berdasarkan frekuensi penggunaannya — sebagian besar pengguna berhenti di layer 2 atau 3. Hanya power user yang mencapai layer 5.

Tujuannya bukan mengekspos segalanya. Ini soal mengekspos tepat apa yang dibutuhkan, tepat ketika dibutuhkan. Itulah progressive disclosure yang diterapkan pada arsitektur agen.

Ground Truths: Menambatkan Agen AI ke Realitas

Tue, 13 Jan 2026 00:00:00 GMT

Angka dalam tulisan ini mencerminkan sistem pada saat publikasi (Januari 2026). Lihat halaman tim kami untuk angka terkini.

Agen AI sangat kapabel. Mereka bisa bernalar, mensintesis, dan menghasilkan. Tetapi mereka punya kelemahan mendasar: mereka mengarang-ngarang. Bukan dengan niat jahat, tetapi dengan percaya diri. Seorang agen bisa saja mengarang parameter API yang tidak ada, merujuk konfigurasi yang tidak pernah didefinisikan, atau menerapkan pola dari data pelatihannya yang bertentangan dengan arsitektur Anda yang sebenarnya.

Mitigasi standarnya adalah “beri agen lebih banyak konteks.” Tetapi konteks bisa saling bertentangan. Dokumentasi melenceng dari implementasi. Komentar bisa berbohong. Bahkan kode pun bisa menyesatkan jika dibaca tanpa memahami maksudnya.

Kami butuh sesuatu yang lebih eksplisit. Sesuatu yang tidak bisa diabaikan atau disalahtafsirkan. Sesuatu yang menambatkan agen ke realitas yang bisa diverifikasi.

Kami menyebutnya Ground Truths.

Apa itu Ground Truth?

Sebuah ground truth adalah pernyataan fakta yang eksplisit dan terversi yang harus dihormati oleh agen. Ini bukan dokumentasi. Ini bukan komentar. Ini adalah entitas kelas satu dalam sistem dengan:

Sebuah identifier unik (seperti GT-MAG-015 atau GT-MAG-036)
Sebuah status lifecycle (current, tentative, atau deprecated)
Sebuah scope (platform-wide, package-specific, atau domain-bound)
Bukti (path file, URL, atau referensi yang membuktikan pernyataan tersebut)
Panduan agen (instruksi do/avoid yang eksplisit)

Berikut contoh dari platform kecerdasan kode Maguyva kami:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

Ini bukan prosa. Ini kontrak. Ketika seorang agen menjumpai ground truth ini, ia tahu:

Default-nya deterministik (hasil kosong, bukan tebakan yang samar)
Ada parameter spesifik (find_similar, exact_match) dengan perilaku yang terdefinisi
Bukti ada di file-file spesifik yang bisa diverifikasi
Pernyataan ini diverifikasi pada tanggal tertentu

Anatomi Registry Ground Truth

Ground truth hidup dalam registry YAML di bawah ai_assets/reference/ground_truths.yaml. Setiap package atau domain bisa punya registry-nya sendiri. Strukturnya adalah:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

Registry mencakup metadata tentang koleksinya sendiri, konfigurasi render untuk generasi dokumentasi, dan pernyataan-pernyataannya sendiri. Setiap pernyataan mengikuti skema ketat yang divalidasi oleh model Pydantic:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

Bagaimana Agen Mengakses Ground Truth

Ground truth diekspos lewat beberapa jalur:

1. Dokumentasi Ter-render

Perintah orkestra sync mengubah registry YAML menjadi markdown yang bisa dibaca:

uv run orkestra sync

Ini menghasilkan file GROUND_TRUTHS.md yang disertakan dalam konteks agen. Output ter-render mengelompokkan pernyataan berdasarkan status dan kategori:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. Pencarian CLI

Agen dengan akses shell bisa mencari ground truth secara terprogram:

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

Fungsi pencarian menilai kecocokan di berbagai field dengan relevansi berbobot:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. Komposisi Konteks

Ketika agen di-render dari definisi YAML, konteks mereka bisa merujuk ke registry ground truth:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

Ini memastikan ground truth yang relevan dimuat sebelum agen mulai bekerja.

Kategori Ground Truth

Melihat ke seluruh registry kami, ground truth mengelompok ke dalam beberapa pola:

Prinsip Produk

Batasan tentang apa yang menjadi dan bukan produk ini:

“Maguyva bersifat read-only terhadap repositori pengguna; satu-satunya aset yang tidak bisa dibangun ulang adalah cache embedding berbayar.” (GT-MAG-001)

Batas Arsitektur

Di mana tanggung jawab berada dan mengapa:

“Batas antara pipeline dan Maguyva itu disengaja: pipeline dapat digunakan ulang, Maguyva memegang logika spesifik-kode, dan CQRS memisahkan operasi penulisan oleh stage pipeline dari operasi pembacaan oleh server.” (GT-MAG-006)

Aturan Anti-Halusinasi

Mandat eksplisit yang menjaga kontrak tool tetap deterministik, bukan hasil inferensi:

“Pencocokan simbol fuzzy bersifat opt-in lewat find_similar=true. Perilaku default mengembalikan hasil kosong untuk simbol yang tidak ada; exact_match=true menegakkan pencocokan ketat dan menonaktifkan semua fallback fuzzy.” (GT-MAG-015)

Quality Gate

Standar yang harus dipertahankan:

“Perubahan pada infrastruktur bersama (post_filters.py, ekstraktor relasi, handler bersama) HARUS divalidasi terhadap SEMUA bahasa yang didukung lewat generasi full manifest sebelum commit. Validasi satu bahasa saja tidak cukup untuk kode bersama.” (GT-MAG-036)

Pola Kode

Persyaratan implementasi:

“Gunakan asyncio.to_thread() untuk pekerjaan CPU-bound dalam konteks async; pola loop.run_in_executor() yang sudah usang tidak boleh dipakai di kode baru.” (GT-MAG-018)

Siklus Hidup Sebuah Ground Truth

Ground truth tidak statis. Mereka berevolusi lewat siklus hidup yang terdefinisi:

Tentative

Sebuah truth yang diusulkan dan sedang dievaluasi. Pernyataannya tercatat tetapi bisa berubah:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Current

Sebuah truth terverifikasi yang harus dihormati agen. Buktinya sudah divalidasi:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Deprecated

Sebuah truth yang tidak berlaku lagi. Disimpan untuk referensi historis dengan penunjuk ke apa yang menggantikannya:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

Mengapa Bukan Sekadar Dokumentasi?

Dokumentasi punya tujuan yang berbeda. Ia menjelaskan. Ia mengajarkan. Ia boleh samar, boleh memakai kata seperti “umumnya” atau “biasanya.”

Ground truth tidak boleh samar. Mereka adalah pernyataan tegas. Mereka berlaku atau tidak berlaku, titik.

Pertimbangkan perbedaannya:

Dokumentasi: “API umumnya mengembalikan hasil kosong ketika sebuah simbol tidak ditemukan, meski pencocokan fuzzy bisa diaktifkan pada beberapa konfigurasi.”

Ground Truth: “Perilaku default mengembalikan hasil kosong untuk simbol yang tidak ada; exact_match=true menegakkan pencocokan ketat dan menonaktifkan semua fallback fuzzy.”

Yang pertama membantu manusia mempelajari sistem. Yang kedua bisa langsung ditindaklanjuti oleh agen yang mengambil keputusan.

Panduan Agen: Do dan Avoid

Beberapa ground truth menyertakan panduan agen yang eksplisit:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

Ini menghilangkan ambiguitas. Seorang agen yang membaca ini tahu bukan hanya apa yang benar, tetapi juga tindakan apa yang tersirat dari kebenaran itu.

Verifikasi dan Pemeliharaan

Ground truth membutuhkan pemeliharaan. Kami melacak:

last_verified: Kapan seseorang mengonfirmasi pernyataan ini masih berlaku
evidence: File-file yang membuktikan pernyataan tersebut (bisa diperiksa keberadaannya)
source: Dari mana truth ini berasal (inspeksi CLI, tinjauan arsitektur, pembelajaran pasca-insiden)

Sebuah ground truth dengan tanggal verifikasi yang basi atau tautan bukti yang rusak adalah sinyal untuk diselidiki. Entah truth-nya masih valid dan butuh verifikasi ulang, atau realitasnya sudah berubah dan truth-nya perlu diperbarui.

Contoh Nyata dari Produksi

Batas Keamanan

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

Ground truth ini mencegah sekelompok “perbaikan keamanan” yang keliru arah yang justru akan merusak produk.

Akurasi Saat Ekstraksi

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

Ini lahir dari pengalaman yang menyakitkan. Agen pernah menambal language pack yang gagal dengan menambahkan filter yang hanya berlaku di validator, yang membuat test harness terlihat lebih hijau, sementara Maguyva extractor yang sesungguhnya di produksi tetap menghasilkan edge yang salah. Aturan ini memaksa perbaikan kembali ke jalur sungguhan: config YAML, query, atau handler.

Filtering Multi-Tier

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

Ini mencegah agen menambahkan filter di tempat yang salah, sebuah kesalahan umum yang menyebabkan regresi akurasi.

Integrasi dengan Sistem Orkestrasi

Ground truth adalah satu lapisan dari sistem konteks yang lebih luas:

Keputusan Arsitektur (ADR) - Mencatat mengapa kami memilih pendekatan A daripada B
Ground Truths - Menyatakan apa yang secara definitif benar saat ini
Domain Patterns - Menjelaskan bagaimana melakukan sesuatu dengan benar
Anti-Patterns - Menjelaskan apa yang harus dihindari dan mengapa

Seorang agen yang bekerja dalam sistem punya akses ke keempatnya. Ground truth menyediakan jangkar faktual, sementara decision menjelaskan sejarah, pattern memandu implementasi, dan anti-pattern memperingatkan jebakan.

Mengukur Dampak

Sejak memperkenalkan ground truth, kami telah mengamati:

Lebih sedikit siklus “perbaiki perbaikan yang berhalusinasi”
Pengambilan keputusan agen yang lebih percaya diri ketika fakta sudah jelas
Tinjauan PR yang lebih baik karena ekspektasinya eksplisit
Waktu onboarding yang lebih singkat untuk agen baru (dan manusia baru)

Investasi dalam memelihara ground truth terbayar lewat debugging yang berkurang dan batas sistem yang lebih jelas.

Memulai

Untuk menambahkan sebuah ground truth ke sistem Anda:

Buat sebuah ground_truths.yaml di direktori ai_assets/reference/ milik package Anda
Definisikan metadata dan konfigurasi render
Tambahkan pernyataan yang mengikuti skema
Jalankan uv run orkestra sync untuk menghasilkan dokumentasi
Sertakan registry-nya dalam komposisi konteks agen

Mulailah dari fakta-fakta yang paling sering menimbulkan kebingungan atau batasan yang paling sering dilanggar. Itulah ground truth Anda yang paling bernilai.

Kesimpulan

Agen AI akan berhalusinasi. Itu sudah sifat dasarnya. Tetapi kita bisa menciptakan lingkungan tempat halusinasi itu dibatasi, tempat fakta-fakta tertentu tidak bisa dinegosiasikan, tempat agen bisa memeriksa asumsi mereka terhadap realitas yang terverifikasi.

Ground truth bukan solusi yang lengkap. Mereka butuh pemeliharaan. Mereka bisa menjadi basi. Mereka menambah overhead pada proses pengembangan.

Tetapi mereka menyediakan sesuatu yang berharga: sebuah kosakata fakta bersama yang bisa dipercaya baik oleh manusia maupun agen. Di dunia tempat agen semakin banyak berpartisipasi dalam pengembangan perangkat lunak, fondasi bersama itu menjadi esensial.

Alternatifnya adalah siklus tanpa akhir dari agen yang membuat kesalahan dengan percaya diri dan manusia yang mengoreksinya. Ground truth memutus siklus itu dengan membuat koreksi-koreksi itu eksplisit dan bertahan lama.

Agen Anda berhak tahu apa yang benar. Beri tahu mereka.

Orkestra: Mengorkestrasi Agen AI dalam Skala Besar

Tue, 06 Jan 2026 00:00:00 GMT

Angka dalam tulisan ini mencerminkan sistem pada saat publikasi (Januari 2026). Lihat halaman tim kami untuk angka terkini.

Ketika kami mulai membangun dengan Claude Code, kami menemui sebuah masalah yang akhirnya dihadapi setiap tim yang menggunakan asisten coding AI: satu agen tidak bisa melakukan segalanya dengan baik.

Anda bisa mem-prompt sebuah agen menjadi spesialis database. Atau auditor keamanan. Atau engineer frontend. Tetapi begitu Anda memintanya menjadi ketiganya sekaligus, kualitasnya menurun. Konteksnya terdilusi. Instruksinya saling bertentangan. Agennya menjadi generalis yang biasa-biasa saja di segalanya.

Jadi kami membangun Orkestra.

Apa itu Orkestra?

Orkestra adalah sistem orkestrasi agen untuk Claude Code dan tool coding AI serupa. Ia mengoordinasikan banyak agen terspesialisasi, masing-masing dengan keahlian yang berbeda, di bawah satu orchestrator yang merutekan pekerjaan ke spesialis yang tepat.

Bayangkan ini seperti agensi staffing untuk agen AI. Orchestrator menerima sebuah task, mengidentifikasi spesialis mana yang seharusnya menanganinya, dan mendelegasikannya dengan konteks yang tepat. Ketika pekerjaannya selesai, hasilnya mengalir kembali ke orchestrator untuk disintesis.

Angka-angkanya bercerita banyak:

Komponen	Jumlah
Agen spesialis	46
Skill yang dapat digunakan ulang	466
Arketipe identitas	27
Mindset	11
Gaya komunikasi	10
Domain pengetahuan	21

Sistem Karakter: D&D untuk Agen

Wawasan inti di balik Orkestra adalah bahwa perilaku agen muncul dari tiga primitif yang bisa digabungkan:

Identity mendefinisikan apa agen ini. Seorang architect mendesain struktur sistem. Seorang debugger menelusuri kegagalan hingga akar penyebabnya. Seorang guardian menegakkan kepatuhan dan batas keamanan. Kami punya 27 arketipe identitas yang bisa dicampur.

Mindset mendefinisikan bagaimana agen berpikir. Sebuah mindset analitis menambatkan pernyataan pada bukti dan mengukur ketidakpastian. Sebuah mindset skeptis mempertanyakan asumsi dan mencari bukti yang membantah asumsi tersebut. Sebuah mindset eksploratif merangkul ambiguitas dan mencoba banyak pendekatan.

Style mendefinisikan bagaimana agen berkomunikasi. Gaya teknis menyertakan nilai persis dan merujuk file spesifik. Gaya ringkas memangkas basa-basi dan langsung ke jawaban. Gaya diplomatis menyeimbangkan kejujuran dengan kehalusan.

Sebuah agen menggabungkan primitif-primitif ini:

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

Komposisi ini menciptakan sebuah agen yang mendesain sistem (architect), menghubungkan pengetahuan lintas domain (knowledge-architect), menetapkan arah strategis (strategist), berpikir dalam bukti dan data (analytical), dan berkomunikasi tanpa basa-basi (concise).

Kekuatannya ada pada ledakan kombinatorial. 27 identity dikali 11 mindset dikali 10 style menghasilkan hampir 3.000 kepribadian agen yang mungkin. Tetapi Anda hanya mendefinisikan kombinasi yang penting untuk pekerjaan Anda.

Skill: Modul Kapabilitas yang Dapat Digunakan Ulang

Skill adalah pengetahuan dan alur kerja yang bisa dipanggil oleh agen. Mereka mengikuti sistem bertingkat berdasarkan cakupan:

Tier	Nama	Cakupan	Contoh
K0	Foundations	Metodologi universal	Disiplin test-first, penyelesaian berbasis bukti
K1	Identities	Alur kerja berbasis peran	Standar interface CLI, playbook performa
K2	Domains	Pengetahuan spesifik domain	Pola migrasi database, validasi autentikasi
K3	Stacks	Spesifik teknologi	Deployment Cloudflare, operasi Supabase
K4	Project	Hanya basis kode ini	Alur kerja dan konvensi khusus proyek

Skill dimuat secara lazy. Sebuah agen melihat nama dan deskripsi skill saat startup, tetapi konten skill lengkap baru dimuat saat dipicu. Ini menjaga konteks tetap ramping sembari membuat ratusan skill tetap bisa ditemukan.

Setiap skill mencakup:

Kondisi trigger yang jelas (“Gunakan saat memigrasikan skema database”)
Panduan langkah demi langkah
Tool yang diizinkan untuk alur kerja tersebut
Kriteria sukses dan jalur pemulihan kegagalan

466 skill dalam registry kami mencakup segalanya, dari isolasi git worktree hingga alur kerja riset web hingga validasi kesehatan deployment.

Mengapa Orkestrasi Itu Penting

Arsitektur agen tunggal cepat menabrak tembok:

Dilusi konteks. Jendela konteks 200 ribu token terdengar besar sampai Anda memuat skema database, dokumentasi API, fixture test, dan pengetahuan domain. Spesialis bisa bekerja dengan konteks yang ditargetkan.

Konflik instruksi. Meminta sebuah agen “teliti tapi cepat” dan “verifikasi segalanya tapi jangan over-engineer” menciptakan ketegangan. Spesialis menyelesaikan ini dengan memiliki cakupan yang jelas.

Kedalaman keahlian. Sebuah agen generalis tahu sedikit tentang segalanya. Sebuah agen spesialis, yang digabungkan dengan identity dan skill yang tepat, memahami domainnya secara mendalam.

Orkestra mengimplementasikan orkestrasi flat: satu orchestrator mengoordinasikan banyak spesialis. Spesialis tidak bisa menciptakan sub-spesialis. Ini mencegah ledakan kompleksitas sembari memungkinkan pekerjaan paralel.

Orchestrator punya akses ke 2,2 juta token kapasitas efektif: jendelanya sendiri 200 ribu ditambah 10 subagen konkuren dengan 200 ribu masing-masing. Pekerjaan yang akan menghabiskan kapasitas konteks satu agen berjalan dengan nyaman di seluruh armada.

Pipeline Rendering

Definisi agen hidup dalam YAML. Claude Code membaca Markdown. Orkestra menjembatani celah ini dengan pipeline rendering yang deterministik:

YAML Registries → Jinja Templates → .claude/agents/*.md

Operator mengedit sumber YAML. Jalankan orkestra sync. Markdown ter-render muncul di .claude/agents/. Claude Code mengambil perubahannya.

Pemisahan ini melayani audiens yang berbeda:

Sumber YAML mencakup metadata lifecycle, tag, aturan validasi, dan catatan deprecation untuk tooling
Markdown ter-render hanya mencakup apa yang dibutuhkan model: deskripsi, tool, skill, dan panduan perilaku

Pipeline-nya menggabungkan identity, mindset, style, dan skill menjadi satu prompt sistem yang koheren. Sebuah agen architect-analytical-concise mendapat prompt sistem yang sangat berbeda dari agen debugger-skeptical-technical, bahkan jika mereka berbagi beberapa skill dasar yang sama.

Pengetahuan Domain: Pola Empat File

Setiap domain pengetahuan mengikuti struktur yang konsisten:

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

Struktur ini melayani pemuatan konteks agen. Sebuah agen yang bekerja pada autentikasi memuat authentication/patterns.md untuk panduan dan authentication/anti-patterns.md untuk menghindari jebakan yang sudah diketahui. Panjang file disesuaikan agar konteks dapat dimuat secara efisien: cukup fokus untuk berguna, cukup komprehensif untuk otoritatif.

Kami memelihara 21 domain tingkat-atas termasuk analitik, autentikasi, data science, infrastruktur, machine learning, performa, keamanan, dan lainnya. Setiap domain bisa punya sub-domain untuk granularitas yang lebih halus.

Values: Sistem Operasi

Semua agen berbagi lapisan values dasar yang mendefinisikan bagaimana mereka beroperasi:

Kesederhanaan lebih dulu. Gunakan solusi paling sederhana yang berhasil. Tambahkan kompleksitas hanya jika ada alasan yang jelas.

Perbaiki akar masalah. Jangan sekadar mengakali kegagalan tanpa memperbaiki penyebabnya. Jika sebuah pipeline gagal, debug pipeline-nya. Jika sebuah test gagal, perbaiki kodenya atau test-nya.

Evidence-based. Berilah label pada klaim sebagai “terverifikasi” (dengan benchmark) atau “estimasi” (dengan asumsi). Pola terdeteksi tidak sama dengan masalah terkonfirmasi.

Context economics. Tool MCP menghabiskan 0,1% konteks. Pembacaan file menghabiskan 2% masing-masing. Terapkan keahlian domain sebelum menjelajahi kode.

Values ini merambat ke setiap spesialis lewat pipeline rendering. Sebuah agen tidak bisa melewatinya lewat komposisi.

CLI: Bidang Kendali

Orkestra dilengkapi CLI untuk mengelola ekosistem agen:

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

CLI ini adalah sumber kebenaran untuk agen apa yang ada, skill apa yang mereka miliki, dan apakah sistemnya sehat. Ia menjalankan validasi sebelum sync untuk menangkap masalah lebih awal.

Pertimbangan Open Source

Kami membangun Orkestra untuk memecahkan masalah kami sendiri: mengoordinasikan agen AI dalam skala besar untuk sebuah basis kode yang kompleks. Pola-pola yang kami temukan tidak spesifik untuk domain kami.

Sistem komposisi karakter (identity + mindset + style) berlaku untuk tim mana pun yang mendefinisikan kepribadian agen.

Sistem tier skill (K0-K4) menyediakan model mental untuk mengorganisasi kapabilitas yang bisa digunakan ulang berdasarkan cakupan.

Pola pipeline rendering (sumber YAML + template + artefak hasil generate) memisahkan kebutuhan tooling dari kebutuhan model.

Model orkestrasi flat (satu koordinator, banyak spesialis) menghindari kompleksitas sembari memungkinkan paralelisme.

Apakah Orkestra akan menjadi open source bergantung pada apakah pola-pola ini bernilai bagi orang lain yang membangun dengan Claude Code. Jika Anda menabrak tembok yang kami jelaskan, arsitektur ini mungkin bisa membantu.

Apa yang Kami Pelajari

Membangun Orkestra mengajarkan kami bahwa orkestrasi bukan soal membuat agen lebih pintar. Ini soal membuat mereka lebih fokus.

Satu agen dengan instruksi sempurna tetap kehabisan konteks. Satu agen dengan semua skill tetap kebingungan soal mana yang harus diterapkan. Satu agen yang mencoba menjadi segalanya menghasilkan hasil yang biasa-biasa saja di mana-mana.

Empat puluh spesialis, masing-masing unggul di domainnya, dikoordinasikan oleh sebuah orchestrator yang tahu kapan harus mendelegasikan: begitulah cara kami mengirimkan produk.

Angka-angkanya kurang penting dibandingkan arsitekturnya. Anda mungkin butuh lima agen atau lima puluh. Prinsipnya tetap sama: komposisi mengalahkan kapabilitas, spesialisasi mengalahkan generalisasi, koordinasi mengalahkan kepahlawanan individual.

Orkestra menggerakkan ekosistem agen di balik Maguyva, platform kecerdasan kode kami. Ingin tahu lebih lanjut? Hubungi tim kami.