Blog ng Maguyva

Konteksto na sumasama sa iyo

Mon, 07 Sep 2026 00:00:00 GMT

Napakahusay ng indexer ng Cursor sa loob ng Cursor. Ang tab completion, inline editing, chat, at ang agent sa loob ng window na iyon ay umaasa na sa project index na pinapatakbo ng Cursor para sa nakabukas na workspace. Kung ang Cursor lang ang tanging surface kung saan ka nagsusulat, at natatagpuan na ng index na iyon ang tamang mga file, manatili doon. Iyon ay isang tapat na kaso ng ‘manatili kung saan ka na’, at karapat-dapat itong maging unang pangungusap ng pahinang ito.

Ang artikulong ito ay tungkol sa kabilang kalahati ng karaniwang linggo. Ang parehong repository ay bukas din sa Claude Code, tinatanong mula sa Codex CLI, sinusuri sa ikalawang makina, o tinatanong ng isang agent na tumatakbo sa CI. Ang tanong ay hindi ‘aling indexer ang mas mahusay’. Ang tanong ay kung ang map na pinagkakatiwalaan ng agent sa isang window ay iyon ding map na pinagkakatiwalaan nito sa susunod na window.

Ang Maguyva ang mapang sumasama sa iyo. Ito ay isang remote MCP codebase context layer. Tinatanong ito ng agent sa parehong paraan na tinatanong nito ang alinmang MCP tool. Ang mga resulta ay bumabalik bilang mga cited path na may line number. Ang Cursor ay nananatiling editor. Ang konteksto ang gumagalaw.

Para saan ang indexer ng Cursor

Umiiral ang built-in na indexing ng Cursor para maipuwedeng kunin ng chat, agent, at search sa loob ng editor ang kaugnay na code sa halip na umasa lamang sa kung ano ang kasya sa raw context window ng modelo. Iyon ang tamang disenyo para sa isang IDE. Ang index na ito ay native sa Cursor. Hindi ito MCP server at hindi ito ma-access ng ibang client.

Ganito ito gumagana, ayon sa inilarawan sa pampublikong dokumentasyon ng Cursor at sa mga paliwanag ng Cursor mismo sa oras ng pagsulat nito: ang pangunahing search path ay hindi na cloud embedding index. Sinabi ng Cursor team sa kanilang community forum na ang dedikadong semantic/embedding-based search ay pinapababa ang gamit pabor sa grep-based retrieval, dahil sapat na ang kasalukuyang mga modelo para maeksplora ang buhay na tree sa kanilang sarili. Sa halip mayroong Instant Grep, isang local search index na binuo mula sa n-grams, inverted lists, at Bloom filters, na naka-imbak sa memory-mapped lookup tables, para maresolba ang mga query sa mismong makina ng developer sa halip na sa server.

Ang index mismo ay naninirahan sa sariling .git/cursor/ directory ng repository, naka-anchor sa isang partikular na git commit; ang mga pagbabago mula noong commit na iyon ay naka-layer sa ibabaw nito sa halip na magdulot ng bagong scan, at ang index ay muling bubuuin lamang kapag lubos na lumihis ang local na estado mula sa kung ano ang binuo nito. Dahil naninirahan ito sa loob ng .git, hindi ito kailanman naitrack at hindi kailanman naipush — burahin ang folder na iyon, at mawawala ang index. Ginagalang ang .gitignore sa pagbuo nito, dahil ang natrack na content lamang ang kwalipikado, at ang .cursorignore ay ipinapatupad sa read path. Wala nang server-side embedding step o remote vector database sa path na iyon. Inilarawan ng mas lumang dokumentasyon ang cloud-assisted na disenyo — chunk encryption, syncing sa pamamagitan ng Merkle trees, pag-reuse ng index sa pagitan ng mga miyembro ng team — at sinabi na mismo ng Cursor team simula noon na ang disenyong iyon ay pinapababa ang gamit, kaya’t hindi na ito inilalarawan ng artikulong ito bilang kasalukuyan.

Ang namumukod-tangi sa loob ng editor ay ang Explore subagent ng Cursor. Maaari itong maglunsad ng maramihang parallel search sa sarili nitong context window sa isang mas mabilis na modelo, at ibalik lamang ang mga nauugnay na natuklasan, para hindi bumigat ang pangunahing usapan ng mga resulta ng search. Iyon ay isang tunay na lakas sa loob ng editor. Panatilihin ito.

Suportado ang multi-root workspaces: ang konteksto ng bawat nakabukas na folder ay available sa Agent. Ang ilang git-dependent na feature, tulad ng worktrees, ay hindi pinagagana sa multi-root setups, at hindi sumusuporta ang Cloud Agents sa multi-root workspaces nang buo.

Walang alinman dito ang dahilan para iwanan ang Cursor. Ito ay tumpak na paglalarawan ng isang napakagandang mapa sa lugar na tinitirhan nito.

Ano talaga ang ibig sabihin ng ‘sumasama sa iyo’

Sumasama ang mapa sa iyo kapag ang parehong tanong ay nagbabalik ng parehong uri ng sagot, na may mga cited na maaari mong buksan, mula sa higit sa isang client.

Sa Cursor: ‘Saan tinukoy ang parseConfig, at sino ang tumatawag dito?’
Sa Claude Code, sa parehong repo: parehong tanong.
Sa Codex CLI, sa isang review machine na hindi kailanman nagbukas ng Cursor window: parehong tanong.
Sa isang CI agent na nakikipag-usap sa MCP: parehong tanong, laban sa parehong hosted snapshot.

Kung ang bawat surface ay bumubuo ng sarili nitong pribadong index, hindi ka nagkakaroon ng isang mapa. Mayroon kang maraming cache na lumilihis sa isa’t isa. Ang index ng editor ay maaaring pinaka-updated para sa tree na nasa disk. Ang CLI session ay maaaring isang araw na huli. Ang CI job ay maaaring makakita ng ibang checkout. At ang agent ay mananatiling magiging kumpiyansa pa rin ang tunog.

Hindi dinisenyo ang indexer ng Cursor para lutasin iyan. Dahil naninirahan ito sa loob ng editor, ang konteksto na binuo nito ay para sa editor na iyon. Ang mga reader na nangangailangan din ng CLI, CI pipeline, o ibang editor ay nangangailangan ng hiwalay na tool para sa mga surface na iyon. Iyan ay katotohanan tungkol sa saklaw, hindi kapintasan. Ang Maguyva ang hiwalay na tool na iyon.

Ang bilang ng mga wikang na-publish para sa indexer ng Cursor ay hindi nakasaad sa napagagamit na content ng artikulong ito. Ang Maguyva ay nag-publish ng suporta para sa mahigit 279 wika at teknolohiyang text-based. Hindi rin inuulit dito ang presyo ng Cursor; tingnan ang kanilang pricing page. Ang Maguyva ay singil bawat workspace, hindi bawat seat, na may mga na-publish na plano sa $0, $19, $49, at $149 depende sa naka-index na coverage at laki ng workspace.

Isang hosted map, bawat MCP client

Ang Maguyva ay isang remote MCP server. Ikonekta mo ang GitHub, pumili ng repository, at bubuo ang cloud pipeline ng mga symbol, graph edge, at cited map. Magdadagdag ka ng API key sa MCP config ng client na ginagamit mo na. May mga setup guide ang Maguyva para sa 24 dokumentadong MCP client — kasama ang Cursor — at maaari itong makipag-usap sa alinmang ibang MCP-compatible client na sumusuporta sa standard na configuration.

Ang pahina ng setup ng Cursor ang editor-specific na daan kung doon ka nagtatrabaho. Ang parehong server ay sumasagot sa Claude Code, VS Code, Windsurf, Codex CLI, at iba pa. Hindi ka nagpapalit ng editor. Binibigyan mo ang bawat agent ng parehong tool surface: 11 customer-facing MCP tool sa search, symbol, dependency analysis, file retrieval, repository context, at deterministic utility-tool workflow. Ang semantic, structural, graph, at text search ay nagsasama sa isang ranked na resulta.

Iyan ang benepisyo ng portability. Ang cited na sinusuri mo sa Cursor ngayong umaga ay may parehong hugis ng ibabalik ng Codex CLI mamayang gabi. File path at line number. Buksan ito. Kung mali, makikita mo. Kung tama, mayroong lugar na madadapuan ang susunod na pagbabago. Ang inaangkin ay mas kaunting hallucinated na pagbabago, hindi pangako na tama ang bawat pagbabago.

Na-publish ang freshness. May timestamp ang mga snapshot, para malaman ng agent kung aling bersyon ng tree ang binabasa nito. Ang rebuild rate ay araw-araw sa libreng plano at bawat oras sa mga bayad na plano. Ang tapat na limitasyon ay ang unsynced na local work: ang mga pagbabagong umiiral lamang sa working tree ay wala pa sa hosted map. Ang limitasyong ito ay independiyente sa client na ginagamit mo para magtanong, at iyan ang tunay na punto. Ang drift sa pagitan ng mga client ay hindi na pangalawang nakatagong limitasyon.

Ibinibigay ng dokumentasyon ang parehong activation loop para sa bawat client: i-index ang isang repo na kilala mo na, ikonekta ang client, magtanong ng isang tanong na kaya mong ma-verify. Gawin iyon nang isang beses sa Cursor. Gawin itong muli mula sa CLI na tunay mong ginagamit sa araw ng review. Kung parehong sagot ay sumipi sa parehong handler, tunay na sumama sa iyo ang mapa.

Paano magkasama ang dalawang mapa

Gamitin ang pareho. Hindi ito alternatibo sa kahulugan ng comparison page.

Panatilihing naka-on ang indexer ng Cursor para sa proyektong nasa disk. Hayaang gamitin ito ng Explore, Instant Grep, at ang agent sa loob ng editor. Ang loop na iyon ay native at mabilis.
Idagdag ang Maguyva bilang MCP server sa Cursor para ang parehong session ay maaari ring magtanong sa hosted workspace map. Ang Cursor ay isang dokumentadong Maguyva client. Hindi ka pumipili ng isang index at binuburahin ang iba.
Idagdag ang parehong Maguyva server sa Claude Code, Codex CLI, o alinmang ibang MCP client na humihipo sa repo. Isang porma ng API key. Isang workspace.
Kung MCP-compatible ang CI agent, ituro ito sa parehong server. Babasahin nito ang parehong may-timestamp na snapshot na binabasa ng laptop.

Nananatiling pinakamahusay na tool ang index ng editor para sa ‘ano ang nasa disk sa window na ito, ngayon’. Ang hosted map ang pinakamahusay na tool para sa ‘ano ang hitsura ng workspace na ito para sa bawat agent na hihipo dito ngayon’. Hindi nagkakaagawan ang mga pangungusap na iyon.

Na-publish ang workspace quota sa pricing page: repo, naka-index na linya, at user, sinisingil bawat workspace. Nagbabahagi ang mga agent at tao ng parehong bilang ng user. Magsimula nang libre gamit ang repo na kaya mo nang husgahan. I-upgrade ang workspace lamang matapos manatili ang mga cited sa paglapat sa tree na iyon.

Ano ang hindi inaangkin ng pahinang ito

Hindi nito inaangkin na mahina, hindi kumpleto, o dahilan para magpalit ng editor ang indexer ng Cursor. Sinasabi ng unang pangungusap ng artikulong ito ang kabaligtaran.

Hindi nito inaangkin na pinapalitan ng Maguyva ang Instant Grep o ang Explore subagent. Mga feature iyon ng Cursor. Nananatili ito sa Cursor.

Hindi ito gumagawa-gawa ng bilang ng wika, numero ng latency, o pagtitipid sa token para sa alinmang produkto. Ang mga hindi alam na numero ay nananatiling hindi na-publish.

Hindi ito nagpapanggap na ang unpushed na local work ay nasa hosted map. Ginagawang nakikita ng may-timestamp na snapshot ang limitasyong iyon. Hindi nito ito inaalis.

Simple ang pagsubok. I-index ang isang repo na kilala mo na. Magtanong ng isang tanong na kaya mong ma-verify, una sa Cursor at pagkatapos sa ikalawang MCP client. Ang konteksto na sumasama sa iyo ay ang parehong cited sa parehong lugar.

// same map, wherever you opened it.

Mapa muna, review pagkatapos

Mon, 07 Sep 2026 00:00:00 GMT

May dalawang magkaibang gawain sa magkabilang panig ng pull request. Bago magsulat ang agent, kailangan nito ng mapa ng tree na papalitan nito. Matapos magbukas ng PR ang agent, kailangang may bumasa ng pagbabagong iyon laban sa natitirang sistema at mag-iwan ng komentong maaaring pagbatayan ng tao.

Mukhang magkatulad ang mga gawaing ito mula sa malayo dahil pareho itong may kinalaman sa ‘pag-unawa sa codebase’. Hindi ito parehong produkto. Sinasagot ng isa ang ‘saan dapat dumapo ang pagbabagong ito?’. Sinasagot ng isa ang ‘ano ang sinisira ng diff na ito na makakaligtaan ng isang line-by-line na linter?’. Ang paghahalo sa dalawa ay nagbubunga ng mas masamang unang draft at mas maingay na review.

Gabay ito sa paired workflow. Ang Maguyva ang mapang itinatanong ng agent muna. Si Greptile ang review agent na nagkokomento sa PR pagkatapos. Magkatuwang ang pares na ito ayon sa disenyo: hindi sinusuri ng Maguyva ang pull request, at hindi pinapalitan ni Greptile ang context layer na ginagamit ng agent para sulatin ito.

Bakit kapaki-pakinabang ang paghahati na ito

Ang coding agent na nagsisimula sa training bias kasama ang ilang na-paste na file ay gagawa-gawa ng isang plausible na path at ie-edit ito. Iyan ay isang pagkabigo sa ‘maling file’, at problema ito sa retrieval. Ang Maguyva ay isang remote MCP codebase context layer: ang semantic, structural (AST), graph/dependency, at text retrieval ay nagsasama sa isang ranked na resulta, kasama ang symbol search at file retrieval. Ang mga naka-ground na sagot ay bumabalik bilang path/file.ext:line, para matanggihan mo ang pagkakamali bago magkaroon ng patch. Ang inaangkin ay sadyang katamtaman: mas kaunting hallucinated na pagbabago. Maaari pa ring maghula ang modelo. Hindi na lang tsismis ang unang hakbang.

Si Greptile ay isang AI-powered code review agent. Sa kanilang sariling salita, awtomatiko nitong sinusuri ang bawat pull request nang may buong pag-unawa sa codebase, at pinopwesto ang sarili laban sa tradisyonal na mga linter na sumusuri ng mga file nang paisa-isa sa halip na buong sistema. Binubuo ang setup ng pag-install ng isang GitHub o GitLab app at pagpili ng repository. Walang local index na kailangan mong patakbuhin. Ang hosting ay sa Greptile Cloud (sinasabi nilang sumusunod sa SOC 2 Type II, na may report na available kapag hiniling), na may opsyong self-host na inaalok para sa mga enterprise.

Ang kanilang sariling na-numerong daloy ay: kumonekta at bumuo ng dependency graph ng bawat function, class, at dependency; sa bawat pull request, suriin ang pagbabago gamit ang buong repo graph na iyon at i-publish ang mga natuklasan bilang komento sa PR na may mga mungkahing ayos, sa loob ng humigit-kumulang tatlong minuto; maaaring i-hand off ng bawat komento ang isyu sa coding agent na ginagamit na ng team. Sinasabi rin nilang binabasa nila ang nakaraang mga komento ng tao sa PR sa paglipas ng panahon para matutunan ang mga pamantayang code ng isang team at mabawasan ang mga maingay na mungkahi. Ang kanilang learning system, ayon sa kanila mismo, ay tumatagal ng 2-3 linggo para umangkop.

Iyan ay review, hindi drafting. Ang lakas ni Greptile ay ang buong repo graph context laban sa pagbabagong dumapo na sa isang PR, sinusundan ng closed loop na nagpapadala ng mga natuklasan sa Claude Code, Codex, Conductor, Cursor, o Devin. Ang lakas ng Maguyva ay ang ranked na mapa na itinatanong ng agent bago sulatin ang pagbabago. Gamitin ang pareho. Huwag hilingin sa isa na gawin ang gawain ng iba.

Walang nakasaad na first-party product integration sa pagitan ng Maguyva at Greptile. Hindi mo rin ito kailangan. Nakikipag-usap ang Maguyva sa mga agent sa pamamagitan ng MCP. Nakikipag-usap si Greptile sa GitHub o GitLab sa pamamagitan ng kanilang sariling app. Nagtatagpo sila sa pull request. Walang glue script, walang cron na nagpapakain ng isang tool sa isa pa. Hindi kailangan ng pares na ito ng bash dahil ang bawat produkto ay nasa surface na na sa kanila mismo.

Ano ang hindi ito

Hindi ito paninira kay Greptile. Hindi ito ‘palitan ang reviewer mo’ na pahina. Naglunsad si Greptile sa Hacker News noong Marso 5, 2024 bilang isang Y Combinator W24 na kumpanya, at ang thread na iyon ang paraan ng maraming tao para unang makilala ang produktong ito. Kung ganoon mo sila natuklasan, magpatuloy sa paggamit sa kanila. Ang pahinang ito ang nawawalang ikalawang kalahati ng loop na iyon: ang pag-ground muna sa agent para ang PR na nakikita ni Greptile ay naka-target na sa tamang mga file.

Ang marketing material ni Greptile ay nangungunahan ng mga claim sa bilis ng review at pagtuklas ng bug. Ituring iyan bilang sariling claim ni Greptile, hindi isang independiyenteng na-verify na numero. Hindi ito inuulit ng artikulong ito bilang katotohanan.

Ang coverage sa wika ay parehong uri ng katapatan. Binabalangkas ni Greptile ang suporta bilang sumasaklaw sa lahat ng programming language sa halip na isang nakalistang listahan; hindi nakasaad ang eksaktong numero. Nag-publish ang Maguyva ng suporta para sa mahigit 279 wika at teknolohiyang text-based, na may teknikal na paghahati (AST na suportado ng parser laban sa text-only) sa website kapag teknikal ang tanong. Magkaibang produkto ito na gumagawa ng magkaibang claim. Huwag pagsamahin ang mga ito.

Hindi nakasaad ang pricing ni Greptile sa napagagamit na content ng artikulong ito. May mga bayad na plano; tingnan ang kanilang pricing page. Ang Maguyva ay singil bawat workspace, hindi bawat seat. Ang mga plano ay nagsisimula nang libre. Inilista ng pricing page ang mga na-publish na tier kung kailangan mo ng mga numero ng workspace.

Ang workflow

Tatlong pinangalanang stage. Isagawa ang mga ito sa pagkakasunod-sunod na ito. Huwag laktawan ang alinman sa mga ito sa unang beses na susubukan mo ang pares na ito.

1. Konteksto ng Maguyva

I-index ang isang repository na kilala mo na. Ikonekta ang MCP client kung saan ka na nagsusulat — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, o ibang MCP-compatible na client. May mga setup guide ang Maguyva para sa 24 dokumentadong MCP client at maaari itong makipag-usap sa ibang mga client na sumusuporta sa standard na MCP configuration.

Magtanong ng isang tanong na kaya mong husgahan bago magsulat ang sinuman ng isang linya. ‘Saan hinahawakan ang session expiry, at sino ang tumatawag dito?’ ay isang mas mahusay na unang hakbang kaysa ‘ayusin ang auth’. Humingi ng mga cited. Buksan ang file.ext:line na resulta. Sundan ang symbol. I-verify ang mga dependency na gagalawin mo.

Inilalantad ng Maguyva ang 11 customer-facing MCP tool sa search, symbol, dependency analysis, file retrieval, repository context, at deterministic utility-tool workflow. Ang apat na retrieval mode ay nagsasama sa isang ranked na resulta; ang find_symbol ay hiwalay na tool kapag alam mo na ang pangalan. Inilalarawan ng dokumentasyon ang pinakamaikling daan: magsimula nang libre, i-index ang repo na kilala mo na, ikonekta ang client, pagkatapos ay magtanong ng isang tanong na kaya mong ma-verify.

May timestamp ang mga snapshot, para masabi ng agent kung aling bersyon ng tree ang binabasa nito. Ang tapat na limitasyon ay ang unsynced na local work. Kung umiiral lamang ang pagbabago sa working tree at hindi pa naipush, wala pa ito sa hosted map. Ang mga instruction file (CLAUDE.md, AGENTS.md) ay mayroon pa ring lugar dito, para sa mga convention at kung ano ang hindi dapat galawin. Hindi ito buhay na mapa. Gamitin ito para sa asal. Gamitin ang Maguyva para sa mga katotohanan.

Huwag hayaang magbukas ng PR ang agent bago manatili ang cited sa paglapat sa repo. Ang gate na iyon ang buong layunin ng stage na ito.

2. PR ng agent

Sinusulat na ngayon ng parehong agent ang pagbabago sa client na binabayaran mo na. Ang Maguyva ay hindi editor ni reviewer man. Gumagawa pa rin ang agent ng diff. Nagbubukas ka pa rin ng pull request sa GitHub o GitLab gaya ng ginagawa mo na.

Ang dapat na magkaiba ay ang unang file. Dapat pangalanan ng PR ang tunay na handler na nagpapatupad sa asal na iyon, ang mga tumatawag na masisira, at ang mga test na mabibigo kung mali ang pagbabago. Kung nalaktawan ang stage 1, sasayangin ng stage 3 ang komento nito sa isang pagbabagong dumapo sa maling package. Maaari pa ring matuklasan ni Greptile ang mga sistemikong isyu. Hindi dapat kailangan nitong mag-recover din mula sa hallucinated na path.

Panatilihing maliit ang PR. Ang unang file na naka-ground ay hindi lisensya para muling isulat ang isang module. Gumagana ang magkatuwang na paring ito kapag isang gawain lang ang ginagawa ng agent gamit ang mapa, saka hinihiling sa reviewer na gawin ang ibang gawain sa isang limitadong diff.

3. Review ni Greptile

Nakakonekta na si Greptile sa repository sa pamamagitan ng GitHub o GitLab app. Sa bagong pull request, sinusuri nito ang pagbabago gamit ang buong repo graph na binuo nito, at ipinapublish ang mga natuklasan bilang komento na may mga mungkahing ayos. Inilalagay ng kanilang sariling material ang hakbang na ito sa humigit-kumulang tatlong minuto.

Basahin ang komento kung paano mo babasahin ang isang maingat na katrabaho: buksan ang cited na lokasyon, magpasya kung tama ang natuklasan, pagkatapos ay kumilos. Kung saan nag-aalok si Greptile ng ‘Fix with your Agent’, ipinapadala nito ang isyu — file path, line number, mungkahing code — sa Claude Code, Codex, Conductor, Cursor, o Devin. Ang ‘Fix All’ ay nagpapadala ng lahat ng isyu sa review na iyon nang sabay. Nagbibigay rin sila ng Greptile MCP at Claude Code plugin para sa hand-off na iyon. Wala sa nakalistang listahan ng target ang Maguyva; ang kawalang iyon ay hindi problema. Nagawa na ni Maguyva ang gawain nito sa stage 1. Ang coding agent na sumulat sa PR ang panig na dapat makatanggap ng fix payload.

Asahan ang ingay sa unang 2-3 linggo habang umaangkop ang learning system ni Greptile sa mga komento na aktwal na iniiwan ng team mo. Iyan ang timeline na sinasabi nila, hindi kapintasan ng pares. Nananatili ang human review sa loop na iyon. Si Greptile ay isang awtomatikong unang hakbang, hindi merge button.

Kung ang komento ni Greptile ay tumuturo sa isang file na hindi kailanman tinanong ng agent sa stage 1, iyan ay kapaki-pakinabang na signal. Alinman ay nakaligtaan ng mapa ang isang tumatawag, o nilaktawan ng agent ang isang cited. Ayusin ang draft ayon sa komento. Huwag i-disable ang reviewer.

Paano panatilihing tapat ang pagtutulungang ito

Maguyva palagi muna. Ang pagsusuri ng PR na may maling file ay pagsusuri pa rin ng maling file.
Si Greptile palagi pagkatapos. Ang draft na mahusay na na-cite ay nangangailangan pa rin ng pagbasa ng diff sa antas ng buong sistema.
Huwag hilingin sa Maguyva na mag-publish ng mga komento sa PR. Hindi nito ginagawa iyon.
Huwag hilingin kay Greptile na maging unang retrieval layer ng agent habang pumipili pa ito ng path. Hindi iyon gawaing dinisenyo para sa GitHub o GitLab app nila.
Huwag gumawa-gawa ng bash pipeline na ‘nagsi-sync’ sa dalawa. Ang PR ang interface na iyon.
I-verify ang parehong panig nang hiwalay. I-index ang repo na kilala mo na. Magtanong ng isang tanong na kaya mong ma-verify. Pagkatapos ay magbukas ng maliit na PR at basahin kung ano talaga ang kinokomento ni Greptile.

Nagiging karaniwan ang loop na ito kapag napangalanan na. Mapa muna. PR ng agent. Review pagkatapos. Nananatili ang bawat produkto sa panig ng pull request kung saan sila dalubhasa.

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

Pagbibigay sa AI coding agent ng konteksto ng malaking repo nang walang local indexer

Fri, 14 Aug 2026 00:00:00 GMT

Hindi kasya sa context window ang malalaking repository, at kung ituro mo na ang isang laptop-based na indexer sa isang tunay na monorepo, alam mong hindi rin ito kasya nang komportable doon — tumataas ang RAM, umaabot ng isang oras ang unang pag-index, at nagsisimula pa rin ang agent mo ng susunod na session sa pamamagitan ng pag-hula kung aling mga file ang mahalaga.

Ang karaniwang sagot ay magpatakbo ng indexer sa tabi ng editor, at para sa isang repo na komportableng kasya sa isang makina, magandang sagot iyan. Kung mabilis nang nag-i-index ang monorepo mo sa Cursor at doon lamang kailangan mo ng mapa, wala nang idadagdag ang artikulong ito — laktawan na lang.

Tungkol ang artikulong ito sa ibang kaso — kapag kailangan ng agent ng mapang maaaring i-cite ng isang malaking repo, at ayaw mong magpatakbo ng local indexer para makuha iyon.

Kailan nagiging maling tool ang local indexer

Ang local index ay ipinapalagay na naninirahan ang code sa parehong makina na nagtatanong dito, at sa sukat ng tunay na monorepo, humihigpit ang palagay na iyan kahit sa loob mismo ng isang editor. Ang repo ay simpleng mas malaki lang kaysa sa gusto mong panatilihing ‘mainit’ sa laptop: nagtatrabaho ka sa isang package habang ang saklaw ng epekto ay tatlong directory ang layo, at ang unang cold indexing ng isang two-million-line na tree ay hindi bagay na gustong daanan mo nang dalawang beses — makina mo man o sa isang CI runner na hindi pa kailanman nag-clone sa tree na iyon. O dapat kayang magtanong ng katrabaho sa parehong mapa gaya ng itinatanong mo, nang hindi hinihintay na hirapan ng sariling makina nila ang parehong index.

Walang alinman dito ang dahilan para itapon ang isang mahusay na editor indexer. Ito ay dahilan para magkaroon din ng hosted map na maaaring itanong ng alinmang agent mo sa pamamagitan ng MCP.

At ang problemang iyon sa sukat ay mas malalim kaysa sa ‘sobrang daming file para i-paste’. Sa isang malaking tree, ang kawili-wiling tanong ay halos hindi kailanman ‘ipakita mo sa akin ang file na ito’ — ito ay aling file, aling symbol, sino ang tumatawag, aling test. Ang agent na nagsisimula sa pag-list ng src/ at pagbasa ng unang tatlong resulta ay masayang makakaligtaan ang handler sa apps/api at ang na-generate na client sa packages/sdk. Ang kailangan mo ay retrieval na binuo mula sa buong tree, pagkatapos ay ranked, pagkatapos ay cited.

Ano talaga ang ibig sabihin ng ‘konteksto ng malaking repo’

Hindi konteksto ang pagbuhos ng mga file sa prompt — ito ay isang mas maliit at mas masamang kopya ng tree. Ang tunay na kailangan ng agent mo ay ang magtanong at makakuha ng cited na sagot pabalik: saan tinukoy ang symbol na ito at sino ang tumatawag dito, ano ang umaasa sa module na papalitan ko, aling test file ang sumasaklaw sa asal na ito, at ano ang hitsura ng tree na iyon ngayon, hindi noong nakaraang quarter.

Dapat manggaling ang mga sagot na iyon sa isang index na binuo mula sa repo mo, hindi sa alaala ng modelo tungkol sa repo ng iba, at dapat naninirahan ang index na iyon sa isang lugar sa labas ng context window ng agent. Para sa problemang ito, dapat din itong naninirahan sa isang lugar sa labas ng iyong laptop.

Isa pang bagay na hindi kayang gawin sa iyo ng mga instruction file: ang tamang lugar para sa mga convention at asal ay ang CLAUDE.md at AGENTS.md, ngunit hindi ito buhay, ranked, at itatanong na mapa ng two-million-line na tree. Gamitin ang mga panuntunan para sa asal; gamitin ang repo intelligence para sa mga katotohanan.

Binubuo namin ang mapa sa cloud, itinatanong mo ito mula sa alinmang client

Ang Maguyva ay isang remote MCP codebase context layer. Ikonekta mo ang GitHub, piliin ang repo mo, at maaari kang lumakad palayo habang pinapa-parse ng cloud pipeline ang tree, binubuo ang mga symbol at graph edge, at pinapanatili ang ranked na mapa — hindi kailanman kailangan ng local indexer.

Kapag nag-push ka ng code, ang mga nagbagong file ay incrementally pa-parse, at ang graph at ranking layer ay muling binubuo ayon sa iskedyul: araw-araw sa libreng plano, bawat oras sa mga bayad na plano. May timestamp ang bawat snapshot, para malaman ng agent mo kung aling bersyon ng tree ang binabasa nito. Ang tapat na limitasyon dito ay ang unsynced na local work — ang mga pagbabagong umiiral lamang sa working tree mo, hindi kailanman naipush, ay wala pa sa hosted map.

Pagkatapos, ikonekta mo ang alinmang client na ginagamit mo na sa pamamagitan ng pagdadagdag ng API key sa MCP config nito. May mga setup guide para sa 24 dokumentadong MCP client, at maaari ring kumonekta ang alinmang ibang MCP-compatible client na sumusuporta sa standard na configuration. Kung Cursor ang tinitirhan mo, ang Cursor page ang nagmamapa ng daanang iyon; ang parehong server ay sumasagot sa Claude Code, VS Code, Windsurf, Codex CLI, at iba pa.

Hindi ka nagpapalit ng editor. Binibigyan mo ang agent mo ng tool surface — 11 MCP tool sa search, symbol, dependency analysis, file retrieval, at repository context — na may coverage na mahigit 279 wika at teknolohiyang text-based, na ibig sabihin ay higit pa sa akala mo para sa isang monorepo na matagal nang hindi na isang wika lamang.

Bumabalik ang mga sagot na naka-ground, bilang mga file path na may line number. Ang semantic, structural, graph, at text search ay nagsasama sa isang ranked na resulta, para ang tanong tulad ng ‘ano ang umaasa sa parseConfig’ ay hindi lang nagbibigay sa iyo ng tambak ng grep o iisang semantic cited, kundi ang ilang lugar na tunay na mahalaga.

Isang konkretong gabay

Huwag simulan ang buong kumpanya. Ito ang daan na gumagana:

Pumili ng isang repository na kilala mo nang mabuti — ang isang package na kaya mong husgahan nang manu-mano ay mas mahalaga kaysa sa pinakamalaking tree na mayroon ka.
Magsimula nang libre: 3 repo, 50 libong naka-index na linya, lahat ng 11 tool, walang buwanang query quota. Kung mas malaki ang kinatawang repo mo, inilista ng pricing page ang mga workspace tier ($0, $19, $49, $149) ayon sa naka-index na coverage — hindi ayon sa bilang ng seat.
Ikonekta ang GitHub at hintayin matapos ang unang pag-index. Hindi ka nag-co-compile ng anuman nang local.
Ikonekta ang MCP client mo — ilang linya ng config. Ang Maguyva ay isang remote MCP server, kaya walang plugin, walang extension, at walang ikalawang editor na aampunin.
Magtanong ng isang tanong na kaya mong ma-verify. ‘Ano ang umaasa sa parseConfig?’ o ‘Saan hinahawakan ang login session expiry?’ Pagkatapos buksan ang cited na resulta ng file.ext:line at i-check laban sa tree na nasa harap mo.
Pagkatapos lang na manatili ang cited sa paglapat sa tree na iyon, pahihintulutan mo ang agent na mag-edit.

Kung mahusay na kumasya ang unang repo at malaki ang tree mo, i-upgrade ang workspace para tumugma sa naka-index mong linya at rebuild rate. Nagbabahagi ang tao at agent ng parehong bilang ng user — ang Maguyva ay singil bawat workspace, hindi bawat seat — kaya ang pagdaragdag ng ikatlong agent sa loop ay hindi ka nagkakahalaga ng dagdag na anuman.

Ang activation test ay pareho sa inirerekomenda ng dokumentasyon para sa alinmang unang pagpapatakbo: i-index ang repo na kilala mo na, magtanong ng isang tanong na kaya mong ma-verify. Hindi binabago ng malaking repo ang pagsubok na iyon; pinapamahal lang nito ang unang maling file.

Ano ang dapat panoorin matapos kumonekta

Panoorin ang tatlong bagay. Freshness: nire-rebuild bawat oras ang mga bayad na plano, araw-araw ang libreng plano, at ang unpushed na local work ay hindi mapapasama sa mapa — iyan ang trade-off na tinatanggap mo. Saklaw: i-index ang isang kinatawang set ng mga repo, hindi bawat archived na fork; ang libreng tier ay sadyang ginawang maliit para malaman kung sulit itago ang mga sagot. At pag-verify: ang mapa ng malaking repo na hindi kayang mag-cite ng path at line number ay isang mas mabagal na guessing engine lamang, kaya patunayan ng agent mo ang mga lokasyon bago magpadala ng patch.

Pagkatapos patakbuhin ang parehong pagsubok na papatakbuhin mo sa isang maliit na repo. I-index ang repo na kilala mo na. Magtanong ng isang tanong na kaya mong ma-verify. Kung tama ang mapa, hihinto ang agent mo sa pagsisimula mula sa isang malamig na tree.

// no laptop got hot building this map.

Bakit nagha-hallucinate ng mga file path ang AI coding agent mo

Fri, 14 Aug 2026 00:00:00 GMT

Hindi ang maling function body ang senyales. Ito ay isang kumpiyanteng pagbabago sa isang file na hindi umiiral, o sa isang file na umiiral ngunit hindi ang file na nagpapatupad sa asal na iyon.

Hiningi mo ang pag-aayos ng session expiry. Binubuksan ng agent ang src/auth/session.ts. Plausible ang path. Mali rin ito. Ang tunay na handler ay naninirahan sa apps/api/src/middleware/expiry.ts, na binago ang pangalan dalawang refactor na ang nakalipas. Hindi nagsisinungaling sa iyo ang agent. Kinukumpleto nito ang isang path-shaped na string batay sa training bias kasama ang anumang nasa context window na.

Ito ay karaniwang failure pattern sa mga tunay na repository. Kayang magsulat ng code ang modelo. Ang pagkakamali nito ay ang pagpili ng maling lugar para isulat ito.

Bakit gumagawa-gawa ng path ang mga agent

Ang mga coding agent ay mga next-token prediction model na may sangkap na mga tool. Kapag sinabi mong ‘ayusin ang session expiry’, kailangan nitong pangalanan ang isang file bago ito makabasa o makapag-patch ng anuman. Kung wala pa itong naka-ground na mapa, bumubuo ito ng path mula sa:

Naming convention na nakita nito sa ibang repository. Ang src/auth/session.ts ay isang karaniwang anyo.
Mga file na nasa usapan na, na maaaring iyong file na na-paste mo noong nakaraang linggo, hindi ang mahalaga ngayon.
Directory listing na natakbo nito nang aksidente, hindi kumpleto sa isang malaking tree.
Instruction file. Sinasabi ng CLAUDE.md at AGENTS.md sa agent kung paano kumilos. Hindi ito buhay na index ng mga symbol, tumatawag, o kasalukuyang path.

Wala sa mga pinagmulang ito ang mapa ng repo na ito, ngayon. Pinupunan ng modelo ang puwang sa parehong paraan na pinupunan nito ang alinmang puwang: gamit ang high-probability na continuation. Madalas mukhang tunay na path ang continuation na iyon. Minsan umiiral ang file at nasa tamang neighborhood ito. Minsan umiiral ito sa isang branch na na-merge noong nakaraang buwan. Minsan hindi ito kailanman umiral.

Hindi ka mase-save ng grep dito kung hindi man naghanap ang agent ng tamang string mula sa simula. Nagha-hula ang agent ng path, saka binabasa kung ano ang ibinabalik ng path na iyon, saka ie-edit ito. Ang unang maling hakbang ay ang path, hindi ang patch.

Hindi rin pareho ang pagbasa ng mga file sa paghahanap ng tama. Maaaring buksan ng Claude Code, Cursor, Codex, at kahalintulad na tool ang anumang itinuro mo dito. Ang tanong ay kung maaasahan nila mahanap ang tamang file, ang mahalagang symbol, mga dependency, test, at saklaw ng epekto bago mag-edit. Ang file access nang walang mapa ay nagsisimula pa rin sa panghuhula.

Ang pag-edit ng maling file ay problema sa retrieval

Isipin ang na-gawa-gawang path bilang isang pagkakamali sa retrieval, hindi kapintasan sa karakter.

Kung kailangang ibalik ng agent ang path/file.ext:line bago ito pahintulutang mag-edit, may mangyayaring dalawang bagay. Una, maaari mong buksan ang cited at tanggihan ang gawain sa loob ng sampung segundo. Ikalawa, kailangang magtanong ang agent ng isang bagay na tunay na kilala ang tree na iyon.

Iyan ang gawain ng codebase context layer. Hindi sapat ang semantic search lang. Isang cited na ‘parang session expiry’ ay maaari pa ring dumapo sa isang deprecated na package. Kailangan mo rin ng eksaktong text kapag alam mo ang string, symbol search kapag alam mo ang pangalan, structural search kapag alam mo ang hugis, at dependency graph kapag kailangan mo ng mga tumatawag at saklaw ng epekto.

Ang Maguyva ang layer na iyon para sa mga MCP-compatible na coding agent. Hindi ito editor. Nananatili sa kanilang mga lugar ang Claude Code, Cursor, Codex CLI, VS Code, Windsurf, at ibang MCP client. Itinatanong ng agent ang ranked na mapa bago galawin ang isang linya.

Ang inaangkin ay sadyang katamtaman: mas kaunting hallucinated na pagbabago. Hindi inaalis ng Maguyva ang kakayahang manghula ng modelo. Binabago nito ang default na unang hakbang mula sa ‘gumawa-gawa ng plausible na path’ patungo sa ‘humingi ng ranked, cited na lokasyon’.

Ano ang hitsura ng naka-ground na sagot

Hindi isang talata ang kapaki-pakinabang na sagot sa ‘saan hinahawakan ang session expiry’. Ito ay isang maikling listahan ng mga lokasyon:

apps/api/src/middleware/expiry.ts:48 - handler
apps/web/src/lib/auth-client.ts:112 - tumatawag
apps/api/tests/expiry.test.ts:20 - test na mabibigo kung mali ang pagbabago

Maaari mong buksan ang mga linyang ito. Kung mali, huminto ka. Kung tama, maaaring mag-edit ang agent. Ang pag-verify ang punto, hindi ang slogan.

Inilalantad ng Maguyva ang 11 customer-facing MCP tool sa search, symbol, dependency analysis, file retrieval, repository context, at deterministic utility-tool workflow. Ang apat na retrieval mode (semantic, structural, graph/dependency, at text) ay nagsasama sa isang ranked na resulta; ang symbol search ay hiwalay na MCP tool (find_symbol). Bumabalik ang mga naka-ground na sagot na may file path at line number, para mapa-evaluate mo ang mga ito laban sa tree na nasa harap mo.

Inilalarawan ng dokumentasyon ang pinakamaikling daan: magsimula nang libre, i-index ang repo na kilala mo na, ikonekta ang client, pagkatapos ay magtanong ng isang tanong na kaya mong ma-verify.

Ang loop na nagbabago sa unang pagbabago

Hindi mo kailangan ng bagong relihiyon sa workflow. Kailangan mo ng isang dagdag na hakbang bago ang unang pagsulat.

Magtanong ng isang tanong na kaya mo nang husgahan. Mas mahusay ang ‘aling code ang humahawak sa login at session expiry?’ kaysa ‘ayusin ang auth’.
Humingi ng mga cited. File path at line number, hindi buod ng ‘auth module’.
Buksan ang cited na file. Sundan ang symbol. I-verify ang mga dependency na gagalawin mo.
Pahintulutan lang mag-patch ang agent pagkatapos.

Kung walang ibinalik na kapaki-pakinabang ang hakbang 2, walang karapatan ang agent na mag-improvise ng path. Naghahanap ito ulit, o ipinapakita mo dito. Ang solong gate na iyon ang gumagawa ng mas kaunting hallucinated na pagbabago. Parehong modelo ang modelo. Ang mapa ang nagbabago.

Mahalaga pa rin ang mga instruction file. Panatilihin ang mga ito. Gamitin para sa mga convention, panuntunan sa review, at kung ano ang hindi dapat galawin. Huwag hilingin sa mga ito na maging index. Ang CLAUDE.md na naglilista ng tatlong mahahalagang directory ay lipas na sa loob ng isang linggo matapos ang paghahati ng package. Ang naitatanong na mapa ay nag-a-update kapag nag-update ang repo.

Ang may kaugnayang pagkabigo ay ang halos-tamang file: binubuksan ng agent ang auth.ts habang naninirahan ang asal sa auth-client.ts, o pina-patch ang isang na-generate na file sa halip na ang source, o ine-edit ang isang kopya sa packages/legacy dahil tumugma ang pangalan. Hindi ginagawang imposible ng cited ang mga pagkakamaling ito. Ginagawa nitong nakikita ang mga ito bago dumapo ang diff.

Ano ang hindi aayusin ng mapa para sa iyo

Maging tapat tungkol sa nakukuha mo. Hindi gagawing tama ng naka-ground na mapa ang bawat pagbabago — maaari pa ring sumulat ang agent mo ng masamang patch sa mismong tamang file. Kung umaasa ang codebase mo sa dynamic dispatch, reflection, o monkey-patching, magbabalik ng mas manipis na resulta ang ilang symbol search kaysa sa gusto mo, dahil iyan ang ginagawa ng runtime indirection sa anumang static index. At kung umaasa ka ng porsyento — ‘bumaba ang mga hallucinated path nang X%’ — hindi mo ito matatagpuan dito, dahil walang sinuman ang makasusukat ng numerong iyon nang tapat para sa repo mo maliban sa iyo mismo.

Ang maaasahan mo ay mas makitid at mas kapaki-pakinabang: hihinto ang agent sa pagsisimula ng pagbabago nito gamit ang isang hinulaang path. Ang unang hakbang na iyon ay nagiging naka-ground sa tunay na mapa, at mula doon nanggagaling ang mas kaunting hallucinated na pagbabago. Lahat ng bagay matapos ang cited — pagbasa ng diff, pag-evaluate ng patch — gawain mo pa rin, gaya ng dati.

Halos walang kabuluhan ang pagsubok na ito: i-index ang repo na kilala mo na at magtanong ng isang tanong na kaya mong ma-verify. Magsimula sa path na nakapaso na sa iyo dati. Kung mali ang cited, makikita mo agad. Kung tama, may mas mahusay na lugar dadapuan ang susunod na pagbabago ng agent mo.

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

Bakit Namin Ni-upgrade ang Code Search Papunta sa voyage-4-large

Tue, 09 Jun 2026 00:00:00 GMT

Ang mga numero sa benchmark sa post na ito ay sumasalamin sa RTEB leaderboards noong publication (Hunyo 2026). Gumagalaw ang mga leaderboard; ituring ang mga ranking bilang isang snapshot, hindi isang permanenteng katotohanan.

Ang kalidad ng semantic search ay nakasalalay sa embeddings na ginagamit nito.

Kapag nagtanong ang isang agent sa Maguyva ng “saan nakalagay ang retry logic,” hindi ito nagg-grep para sa salitang “retry.” Nagtatanong ito para sa kahulugan — ang backoff loop, ang circuit breaker, ang bagay na bumabalot sa isang flaky call. Sinasagot ang tanong na iyon ng isang vector model na nagpapalit ng code papunta sa isang punto sa espasyo at hinahanap ang mga kapitbahay nito. Pumili ng mas magandang model at tahimik na nagiging mas tumpak ang bawat semantic query sa produkto.

Kaya binago namin ang sa amin. Simula Hunyo 2026, tumatakbo ang code embeddings ng Maguyva sa voyage-4-large, na pumapalit sa voyage-code-3.

Ang Benchmark

Hindi namin ibinatay ang desisyong ito sa vibes lang. Ini-ranggo ng public Retrieval Embedding Benchmark (RTEB) ang mga embedding model batay sa totoong mga retrieval task, at sa Code leaderboard nito, ang voyage-4-large ay nasa #1 overall (90.86) — nangunguna kaysa sa gemini-embedding-2-preview (90.26) at, kapansin-pansin, nangunguna kaysa sa model na ginagamit na namin, ang voyage-code-3 (89.73, #3).

Maliit na absolute gap iyon. Pero isang gap ito sa tamang direksyon, sa isang public benchmark, sa eksaktong task na mahalaga sa amin: pagkuha ng code batay sa kahulugan.

Ang Trade na Tinatanggap Namin: Binary Quantization

Narito ang parteng inaalis ng karamihan sa mga post na “ni-upgrade namin ang model namin.”

Hindi nag-iimbak ng full-precision na mga vector ang Maguyva. Iniimbak namin ang binary-quantized na embeddings: nagko-collapse ang bawat 2048-dimensional na vector papunta sa isang 2048-bit na signature — 256 bytes bawat vector. Sinisiyasat ang mga signature na iyon gamit ang Hamming distance, indexed at partitioned kada tenant.

Isang sinadyang trade iyon. Isinasakripisyo ng binary quantization ang kaunting retrieval precision kapalit ng dramatikong mas maliit na storage at mabilis, murang distance math na walang hiwalay na vector database na pagpapatakbuhin. Para sa isang produktong nag-i-index ng buong repositories kada workspace, mas mahalaga ang economics na iyon kaysa sa pagpiga ng huling piraso ng benchmark point.

Umaangkop ang voyage-4-large sa design na ito nang hindi pinipilit ang migration ng storage layer: gumagawa ito ng 2048-dimensional na output, kapareho ng voyage-code-3, kaya hindi nagbago ang mga column naming bit(2048) at ang Hamming search path. Umangat ang model; nanatili ang schema.

Ang Code, Simula Lang

Isang code-intelligence tool ang Maguyva. Pero customer zero rin kami, at itinuturo namin ito sa ibang bagay: ang markdown na nakatira sa mga repo namin kasabay ng code. Architecture decision records, runbooks, contracts, finance at policy docs — lahat version-controlled sa Git, lahat nasa likod ng parehong MCP server, isang semantic index sa ibabaw ng mga dokumento, hindi lang ng source.

Iyan mismo ang dahilan kung bakit mahalaga ang lawak ng voyage-4-large. Sa parehong RTEB family ng leaderboards, ito ang #1 sa finance, #1 sa healthcare, at #1 sa overall text retrieval — nangunguna kaysa sa Gemini Embedding ng Google, Embed v4 ng Cohere, at text-embedding-3-large ng OpenAI. (Co-creator ng RTEB ang Voyage, kaya binabasa namin ito bilang isang malakas na public signal sa halip na isang perpektong neutral na referee — pero na-benchmark ito nang head-to-head laban sa bawat major na commercial model, sa private hold-out sets.) Ang parehong index na nakakahanap ng tamang function para sa isang agent, nakakahanap din ng tamang clause sa isang contract o ng tamang linya sa isang policy — at sa mga domain na iyon, hindi compromise ang voyage-4-large, ito ang leader.

Bakit Kami Nagbabayad para sa Premium Embeddings

May mas murang paraan para mag-search, at karamihan dito, libre. Tumutugma sa keywords ang lexical search — BM25 at katulad nito — tumatakbo nang local, at walang binabayaran. Nagbibigay ng tunay na decent na semantic retrieval ang mga open-source na embedding model tulad ng BGE, Nomic, at embeddinggemma, at puwede mong i-self-host ang mga ito sa halaga lang ng isang GPU. Ginagamit din ng Maguyva ang libreng bahagi: pinagsasama ng bawat query ang text, AST, graph, at semantic search. Ang hindi namin kinukuripot, ang semantic layer.

Nagbabayad kami kada token para sa premium embeddings — voyage-4-large — sa halip na mag-self-host ng libreng model, dahil sa dalawang dahilan. Una, hindi masasagot ng keyword search lang ang “saan nakalagay ang retry logic” kapag ang code ay sinasabing backoff at circuit breaker at hindi kailanman sinasabi ang salitang “retry” — kahulugan ang buong punto ng embedding, at sa mga domain na aming pinaglilingkuran, nahuhuli ang mga open model sa mga premium: ilang puntos ang layo sa general text, at mas malayo pa sa mga niche tulad ng code, contracts, at finance. Ikalawa, sa karanasan namin, mas humuhubog ang retrieval quality sa huling sagot kaysa sa model sa kabilang dulo — sumasagot pa ring mali ang isang malakas na agent na binigyan ng maling context, at hindi nito nakikita ang dokumentong hindi naman binigay sa kanya.

Kaya isang per-token na bill na lumalaki kasabay ng bawat repo at dokumentong ini-index namin ang premium embeddings — at binabayaran namin ito nang sinasadya. Para sa resulta na nakukuha ng mga user namin, ang tamang function o ang tamang clause, sa tingin namin, sulit ang trade na iyon.

Ang Tapat na Bahagi

Itinuturing pa rin ng sariling documentation ng Voyage ang voyage-code-3 bilang code-optimized na model. Kaya bakit lumipat?

Dahil binasa namin ang public benchmark, hindi lang ang model table ng vendor, at inilagay ng benchmark ang voyage-4-large sa tuktok para sa code retrieval. Isang forward-looking na desisyon ito: kunin ang mas bago, karaniwang mas malakas na model at i-validate ito laban sa isang public leaderboard sa mga task na mahalaga. Komportable kami sa pagtaya na ito dahil malawak ang ebidensya — hindi lang nananalo ang voyage-4-large sa code, nangunguna rin ito sa finance, healthcare, at overall retrieval.

Ang Tahimik na Pundasyon

Sa retrieval nakasalalay ang bawat tool na ini-expose namin — semantic search, task-context gathering, grounded Q&A. Kapag umangat ang retriever, mas magandang ebidensya ang nakukuha ng agent sa kabilang dulo, mas kaunting maling liko ang ginagawa, at ini-anchor ang mga sagot nito sa tamang code — o sa tamang clause, o sa tamang policy. Hindi isang flashy na feature ang isang mas matalas na embedding model. Ito ang pundasyon ng lahat ng iba pa, at pinataas lang namin ang kalidad nito. Hindi mo ito mapapansin. Iyon nga ang punto.

Recursive na Pagpapahusay sa Wika: Pag-grind ng Code Intelligence sa Humigit-Kumulang 280 Wika

Tue, 26 May 2026 00:00:00 GMT

Ang mga numero sa post na ito ay sumasalamin sa system noong publication (Mayo 2026). Tingnan ang aming team page para sa kasalukuyang mga figure.

Kinukuha ng Maguyva ang mga symbol, reference, at dependency graph mula sa source code sa halos 280 wika. Bawat wika ay may sariling custom na tree-sitter handler — mga query, heuristic, edge case — at bawat handler ay puwedeng mali sa sarili nitong subtle na paraan. Isang method call na naitala bilang read. Isang function na na-attribute sa maling enclosing scope. Isang relationship na wala talaga.

Hindi mo iyan kayang hand-audit. Walang team na kayang basahin ang extraction output sa 280 grammar at makita ang mga maling edge. Kaya ang interesting na tanong, hindi “tama ba ang extraction namin” — kundi “paano mo malalaman na mali ito, sa ganitong lawak, nang walang tao sa bawat loop.” Ang sagot namin: recursive na pagpapahusay sa wika — isang quality loop na pinapatakbo ng mga language agent, isang LLM na kumikilos bilang judge, at isang tuntunin na paulit-ulit naming natututunan ulit: hindi pareho ang green at tama.

Hindi Pareho ang Green at Tama

Bawat wika ay may fixture suite, at may release gate na nagsu-score nito sa limang dimensyon — accuracy, structural integrity, completeness, quality, at performance. Nagiging GREEN lang ang isang wika kapag, sa mga fixture nito, ang precision ≥ 0.95, recall ≥ 0.99, at F1 ≥ 0.97, na may kahit 20 expected edges para sa statistical confidence. Kung mas mababa diyan, YELLOW o RED ito, at hindi ito nagshi-ship.

Kailangan ang gate na iyon pero hindi ito sapat. Ang mga fixture, sinusubukan laban sa mga fixture na sinulat namin. In-encode nila ang mga kaso na naisip na namin dati. Puwedeng flawless ang isang handler sa mga fixture nito pero puwede pa ring sirain nito ang isang pattern na lumalabas lang sa totoong code — isang macro idiom, isang generic-bound method, isang language feature na walang gumawang fixture. Ang ibig sabihin ng GREEN, pumasa ang mga fixture. Hindi ito nangangahulugang malinis na naeextract ang isang totoong repository. Kaya kailangan ng loop na iwan ang mga fixture at suriin ang aktwal na code sa mga totoong repository.

Ang panloob na loop: suriin, husgahan, ayusin, patunayan

Isang wika lang ang tinatrabaho ng core loop sa isang pagkakataon:

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  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) ──┘

May ilang bagay na nagpapagana nito sa halip na magkagulo lang.

Ang judge ay ang agent, hindi isang API call. Kapag sinabi naming “LLM-as-judge,” ang ibig naming sabihin, binabasa mismo ng language agent ang bawat sampled edge kasama ng totoong source at inuuri ito gamit ang fixed na limang-kategoryang rubric: tama ba ang edge na ito, isang false positive, ang tamang relationship pero may maling type, naka-attach sa maling scope, o may maling metadata? Ang rubric na iyon ang buong laro — walang kahulugan ang “23% error rate” hangga’t hindi mo alam kung totoong depekto ba ang mga iyon o mali lang ang bilang ng judge.

Ayusin ang isang bagay, tapos patunayan ito. Bawat iteration, isang editable asset lang ang binabago, tapos tinatakbo ulit laban sa isang fixed harness at pinapanatili lang ang pagbabago kung umangat ang F1 at mas maganda ang re-classification. Kung hindi, ire-revert ito. Walang batch ng speculative edits, walang “dapat mas maganda.” Kailangang patunayan ng isang pagbabago na karapat-dapat itong manatili; kung hindi, aalisin ito. At kapag kumapit ang isang fix, ipo-promote ito papunta sa fixture suite — para hindi na tahimik na makabalik ang bug na na-fix nito. Ang promotion step na iyon ang gumagawa sa loop na recursive sa halip na pag-uulit lang: pinapatibay ng bawat pass ang oracle na pagbabatayan ng validation sa susunod na pass.

Ang Aral na Paulit-ulit Naming Natututunan: Nag-o-over-report ang Metrics

Narito ang bitag, at diretso kaming pumasok dito. Ang mga secondary corpus metric — kung gaano kadalas walang resolvable symbol ang isang extracted target, ilang symbol ang mukhang “orphaned,” at iba pa — nag-o-over-report nang malaki sa mga problema. Karamihan sa mga ito, paradigm artifact lang, hindi bugs.

Ang pinakamalinaw na halimbawa: dati, nagpakita ang llvm ng 73% na “source-without-symbol” rate at na-brand na catastrophic. Sinuri namin ito. Ang tunay na accuracy, 98.5%. Ang “nawawalang symbols” ay halos lahat legitimate external reference — mga tawag papunta sa standard library, papunta sa frameworks, papunta sa code na nasa labas ng repo. Sinusukat ng metric ang isang katangian ng wika, hindi isang depekto sa handler. May mga wika tulad ng Zig, COBOL, at Odin na nagpapakita ng 65–70% na “orphan” rate at ganap namang tama; walang tunay na error ang COBOL.

Kung hinayaan naming pamunuan ng mga numerong iyon ang trabaho, gumugol sana kami ng linggo sa “pag-aayos” ng mga handler na tama na pala at hindi na binigyan ng pansin ang mga wikang may tahimik, tunay na bugs. Diretso ang konklusyon: ang aggregate metrics, pansamantalang gabay lang sa triage sa pinakamainam na kaso. Ang tunay na quality signal ay ang spot-check na may edge classification — pagtingin sa aktwal na mga edge sa aktwal na mga repository at pagsuri sa mga ito isa-isa. Data bago intuition — pero dapat alam mo muna kung aling data ang mapagkakatiwalaan.

Ang Outer Loop: Isang Fleet, Hindi Isang Marathon

Isang wika lang sa isang pagkakataon, aabutin ito ng napakatagal kung 280 lahat, kaya ang panloob na loop ay nakabalot sa panlabas na loop na nagpapatakbo ng marami nang sabay.

   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

Ang bawat agent ay nagtatrabaho sa isang throwaway worktree para hindi sila magkakatapakan. Ini-integrate ng orchestrator ang mga fix nila isa-isa, bawat isa naka-gate sa likod ng isang full-manifest regression check: hindi papasok ang isang pagbabago na tumutulong sa sariling wika nito pero tahimik namang sumisira sa tatlo pa. Naka-gate at kumpirmado muna ang integration bago may itulak — ang regression gate ang nagdedesisyon kung ano ang safe, isang tao pa rin ang nagdedesisyon kung ano ang nagshi-ship. Tapos umiikot ang pool papunta sa susunod na set ng mga wika at umuulit ang buong bagay.

Ano ang Hindi Pa Perpekto

Puwedeng magkamali ang judge, at may direksyon ang pagkakamali: ang isang agent na tumatakbo nang may kaunting context lang, nag-o-over-report. Sa isang batch, walong wika ang na-flag sa 5–20% na error; sa inspeksyon, isa lang ang totoong per-language bug — ang natitira, mga pagkakamali ng judge dahil hindi naunawaan ang sariling semantics ng wika (isang source line na legitimately nagla-labas ng maraming edge, parameter bindings na na-model bilang assignments, mga wikang reference-per-identifier). Kaya naman kami nag-sample gamit ang dalawang seed at nagcross-check, at kaya naman ang hindi pagkakasundo sa pagitan ng judge at ng mga fixture, tinuturing na pinaka-interesting na signal, hindi tapos nang desisyon — minsan, ang fixture ang mismong mali.

Tapat din kami tungkol sa target. Ang layunin, zero real errors, tapos. Pero layunin ang “zero” na patuloy naming pinagsisikapang maabot, wika kada wika, hindi isang kahong nachecheck lang. Palaging may isa pang repo na may isa pang idiom.

Pinatunayan, Hindi Basta Sinabi

Lahat ng ginagawa ng Maguyva para sa isang agent — paghahanap ng symbol, pagsubaybay ng dependency, pagsagot ng tanong na may cited code — nakasalalay sa katumpakan ng extraction sa ilalim nito. Sa 280 wika, hindi puwedeng basta sabihin na “tama” ito; kailangan itong patuloy na patunayan gamit ang totoong code. Ang loop ang paraan namin para patunayan ito: isang autonomous na siklo ng mabilisang pagsusuri at pag-aayos na pinaghihinalaan ang sarili nitong metrics, pinapatunayan ang bawat pagbabago, at ginagawang guard ang bawat fix laban sa susunod na regression. Hindi ito kaakit-akit. Ito ang trabaho na nagbibigay-daan sa aming sabihing “sinusuportahan namin ang wika mo” at mapanindigan iyon. Madali ang green. Pinaghihirapan ang pagiging tama.

Multi-Modal Fusion Search: Pagpili ng Tamang Retriever Para sa Bawat Query

Wed, 15 Apr 2026 00:00:00 GMT

Tala tungkol sa dating disenyo: inilalarawan ng artikulong ito noong Abril 2026 ang disenyo ng routing noon, hindi ang kasalukuyang default na pag-uugali. Ang pagwawasto noong Setyembre sa ibaba ay tumutukoy lang sa isang pahayag tungkol sa pagsukat. Para sa kasalukuyang routing, mga preset, at tahasang pagpili ng modality, tingnan ang Paano ito gumagana.

Hindi iisang bagay ang isang search query.

Ang “saan na-define ang parseConfig” ay gustong makakuha ng eksaktong symbol — isang precise na lokasyon, mabilis. Ang “paano gumagana ang authentication” ay gustong makakuha ng kahulugan — ang kabuuan ng magkakaugnay na code na nagpapaliwanag ng isang konsepto. Ang “ano ang masisira kung babaguhin ko ang function na ito” ay gustong makakuha ng dependency graph. Ang “hanapin ang string na ECONNREFUSED” ay gustong makakuha ng literal na match, walang kalokohan.

Mahusay ang grep para sa mga literal na match at kapaki-pakinabang para sa ilang reference hunt, pero hindi ito isang dependency graph at hindi nito naiintindihan ang kahulugan. Sinasakop ng embeddings ang semantic side, pero mali itong tool para sa mga eksaktong string at impact analysis. Karamihan sa mga code search tool, pumipili ng isang engine at ipinipilit ang engine na iyon sa bawat query. Hindi pumipili ang Maguyva. Sinusuri nito kung anong klaseng tanong ang itinanong mo, tapos hinahalo ang apat na retriever sa proporsyong nararapat sa tanong na iyon.

Apat na Modalidad

Sa loob ng system, may apat na independent na paraan para makahanap ng code:

semantic — vector search sa Voyage binary embeddings; naghahanap ng code batay sa kahulugan.
text — trigram matching; naghahanap ng mga literal, error string, eksaktong identifier.
structural — AST queries; naghahanap ng mga definition, signature, at language construct.
graph — ang dependency graph; naghahanap ng mga caller, callee, at saklaw ng epekto.

Malakas ang bawat isa sa ibang klase ng tanong. Ang trick, magdesisyon kung gaano dapat pagkatiwalaan ang bawat isa para sa query na nasa harap mo.

Pag-uuri ng intent

Bago tumakbo ang anumang retrieval, inuuri ng isang lightweight classifier ang query papunta sa isa sa anim na intent, kasama ng confidence score. Sadyang mura ito — ordered heuristics, ang unang match ang mananalo — dahil tumatakbo ito sa hot path at nagdaragdag lang ng isa o dalawang millisecond:

nagsisimula sa def , class , func , import … → find_definition (confidence 0.95)
“who calls”, “usages of”, “references to” → find_references (0.90)
“impact”, “blast radius”, “what depends on” → impact_analysis (0.90)
isang quoted "string" o isang error token tulad ng traceback → exact_match (0.85–0.90)
isang CamelCase o snake_case identifier → find_definition (0.60–0.80)
“how”, “why”, “explain”, “architecture” → understand_code (0.75)
walang tumugma → understand_code, mababang confidence (0.40)

May weight profile ang bawat intent sa apat na modalidad. Ito ang mga totoong numero:

Intent	semantic	text	structural (AST)	graph
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

Kaya ang “saan na-define ang parseConfig” ay lubos na umaasa sa AST (0.6). Ang “paano gumagana ang auth” ay umaasa sa semantic vectors (0.5). Ang “ano ang umaasa dito” ay halos puro graph (0.7). Ang “hanapin ang ECONNREFUSED” ay halos puro trigram (0.9), na naka-off nang tuluyan ang embedding model — dahil eksaktong maling tool ang semantic similarity para sa isang eksaktong string.

Ang Mabilis na Path, at ang Fused na Path

Kapag confident ang classifier — score ≥ 0.85 — at karaniwan lang ang query, nilalaktawan ng Maguyva ang fusion nang tuluyan at diretsong ini-route papunta sa iisang dominanteng modalidad. Ang “saan na-define ang X” ay hindi kailangan ng apat na retriever; kailangan nito ang AST index, ngayon na. Iniuulat pabalik ang direktang path na iyon bilang fusion_strategy: "direct".

Dumadaan sa fusion ang lahat ng ambiguous. Tumatakbo nang parallel ang apat (o tatlo, sa default preset) na modalidad, bawat isa ay nagbabalik ng sariling ranked list, at pinagsasama namin ang mga ito.

Weighted Reciprocal Rank Fusion

Mas mahirap kaysa sa tunog nito ang pagsasama ng heterogeneous na mga retriever: hindi magkapareho ang scale ng isang cosine similarity na 0.82 at isang trigram score na 137 at isang graph centrality na 0.004, kaya hindi mo lang puwedeng idagdag ang mga ito. Iniiwasan ng Reciprocal Rank Fusion ang problema sa pamamagitan ng pagtapon sa raw scores at pagpapanatili lang ng rank na ibinigay ng bawat engine. Ganito ang kontribusyon ng isang resulta mula sa isang modalidad:

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

kung saan ang rank ay ang posisyon nito sa listahan ng modalidad na iyon at ang k ay isang smoothing constant. Sinusuma ang mga kontribusyon sa lahat ng modalidad para sa anumang resulta na nahanap ng mahigit isang engine — kusang umaangat sa ranking ang mga resultang pare-parehong nahanap ng mga retriever. Gumagamit kami ng k = 40 sa default preset at 60 sa thorough (tumatakbong semantic-only lang ang quick, kaya hindi na kumikilos ang fusion diyan). Napunta ang original na RRF work sa k = 60 para sa general-purpose retrieval; medyo mas matalim ang default namin, na nagbibigay ng kaunting dagdag na weight sa top-ranked na pagkakasundo sa pagitan ng mga modalidad — at hindi namin inirerekomenda ang hand-tuning nito.

Dagdag pa rito, may dalang boost mula sa kahalagahan ng graph ang mga resulta. Ang isang hub — isang function na inaasahan ng buong codebase — ay dapat mangibabaw sa isang obscure na leaf kahit magkapareho ang textual relevance, kaya minu-multiply namin ang bawat kontribusyon ng:

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

Nagmumula ang centrality sa precomputed PageRank/degree metrics ng pipeline, at naka-clamp ang boost sa 1.5× para hindi kayang lubusang ilibing ng isang popular na function ang isang mas relevant na obscure na function. Sa wakas, dine-demote namin ang mga resulta mula sa vendor, build, at archive paths, at dine-dedupe papunta sa pinakamagandang chunk kada file.

Ano ang Hindi Pa Perpekto

Ang intent classifier ay isang pangkat ng mga regex, hindi isang sinanay na modelo. Gumagamit ito ng mga heuristic para sa karaniwang anyo ng query, at ang malabong query ay bumabalik sa understand_code at sa timplang mas nakatuon sa semantic search. Inilarawan ng naunang bersyon ng post na ito na nakamit ang pagbaba ng proporsyon ng mga query na walang resulta mula sa humigit-kumulang 15% tungo sa mas mababa sa 5%. Ang panukala noong Disyembre 2025 ay talagang nagtala ng tinantiyang baseline at isang target; walang ibinigay na sumusuportang query set o tala ng pagsukat. Binabawi namin ang pahayag na nakamit ang pagbuting iyon; tingnan ang ebidensya mula sa source at pagwawasto. Hindi pa namin pinapalitan ang classifier ng sinanay na modelo dahil mabilis ang murang bersyon at sapat para sa nilalayong tungkulin nito sa routing, at dahil mas masama ang classifier na mali pero kumpiyansa kaysa sa tapat na fallback. Ang mga weight mismo ay mga paunang palagay na pinili nang mano-mano, hindi natutuhan mula sa click data na hindi naman namin kinokolekta.

Itanong ang Tanong, Hindi ang Tool

Hindi dapat kailanganin ng isang agent na malaman kung sasabak sa grep o embeddings o sa call graph — dapat itanong nito ang tanong sa simpleng termino at makakuha ng tamang sagot. Ang multi-modal fusion ang nagbibigay-daan sa find_symbol, semantic search, at dependency analysis na magamit sa iisang query surface: binabasa ng system ang hugis ng tanong at tahimik na binubuo ang tamang retriever para dito. Mahalaga ang model na nagsu-score sa embeddings, pero mahalaga rin ang pagkaalam kung kailan hindi ito gagamitin. Ang pagpili ng tamang tool para sa bawat query, sarili nitong klase ng kalidad, at mas gusto naming angkinin ito kaysa itulak papunta sa caller.

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

Agent Observability: Mga Hook, Alloy, at Grafana

Tue, 24 Mar 2026 00:00:00 GMT

Kakaiba ang paraan ng pagkasira ng agent systems.

Minsan ang model ang problema. Minsan ang tool ang problema. Minsan okay naman ang MCP server mo, pero mali ang specialist na pinili ng agent, o kalahati ng session ay ginugol sa shell work na hindi mo inaasahan, o tahimik na nag-burn ng cost sa isang loop na parang productive kung titingnan mula sa labas.

Kung hindi mo makita ang pagkakaiba, hindi mo talaga ino-operate ang agent system mo. Nanghuhula ka lang.

Kaya gumawa kami ng observability stack para sa sarili naming workflow: Claude Code, Codex, Claude hook events, Codex notify events, native OpenTelemetry, Grafana Alloy, at Grafana Cloud sa kabilang dulo.

Ang interesting na parte, hindi ang “gumawa kami ng dashboard.” Ang interesting na parte, kinailangan naming hatiin ang telemetry sa dalawang magkaibang stream dahil walang iisang feed na nagbigay sa amin ng buong larawan.

Ang Problema: Fragmented ang Agent Telemetry

Nag-e-emit na ng telemetry ang mga modernong coding agent. Nakakatulong iyon, pero hindi sapat.

Magaling ang native OTEL sa pagsagot ng mga tanong tulad ng:

Ilang request ba ang nagawa namin?
Magkano ang naging cost ng isang session?
Nasaan ang mga span at trace?
May latency spike ba?

Mas mahina ito sa pagsagot ng mga tanong tulad ng:

Aling MCP server ba ang ginamit ng agent?
Nasa Bash ba ang failure na ito, sa isang built-in file tool, o sa isang MCP call?
Aling skill ba ang talagang na-activate?
Aling subagent type ba ang na-dispatch?
Productive ba talaga ang ginawa ng session, o nagta-thrash lang?

Ang ikalawang klase ng tanong, mas malapit ang sagot sa hooks kaysa sa traces.

Pero totoo rin ang kabaligtaran: ang ilan sa pinakamahalagang performance na tanong, mas malapit ang sagot sa traces kaysa sa hooks.

Kung gusto mong malaman kung saan talaga na-accumulate ang latency, aling mga span ang mabagal, o kung nag-burn ba ng oras ang session sa model calls o sa tool execution, kailangan mo ng trace data bukod sa semantic events.

Ang Architecture na Naging Resulta

Dalawang telemetry path ang pinapatakbo namin nang sabay.

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

Sinadya ang paghahati na iyon.

Asymmetric din ito. Mas mayaman ang lifecycle hook surface na ibinibigay ng Claude Code sa amin. Nagbibigay naman ang Codex ng native OTEL kasama ng isang notify surface, kaya nino-normalize namin ang mas payat na turn-completion events papunta sa parehong log schema sa halip na magkunwaring pareho ang exposed controls ng dalawang runtime.

Ang Native OTEL ang nagbibigay sa amin ng baseline stream: logs at traces mula mismo sa runtime, dagdag pa ang metrics kung saan talagang nag-e-emit ang runtime nito.

Ang Hook at notify events naman ang nagbibigay ng semantic layer: mga bagay tulad ng PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated, at ang classified metadata na talagang mahalaga sa amin kapag nagde-debug ng agent behavior. Dito nag-a-ambag ang Claude Code ng mas mayamang event stream. Nag-a-ambag naman ang Codex ng mas payat pero kapaki-pakinabang pa ring normalized stream.

Bakit Kailangan Talaga ng Hooks

Pinayayaman ng hook pipeline namin ang mga event bago ito tumama sa Loki.

Sa halip na sabihin lang “may tumakbong tool,” inuuri namin ang event sa mga field tulad ng:

tool_type: builtin, mcp, skill, agent, bash
mcp_server: aling MCP backend ang humawak sa call
bash_cli: ang shell command family
subagent_type: anong klaseng specialist ang na-dispatch
agent_tool: kung ang pinagmulan ay Claude Code o Codex

Ibig sabihin, makapagtatanong kami ng mga bagay na importante sa operations:

{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"

Hindi vanity fields lang iyon. Iyon ang pagkakaiba sa pagitan ng “parang mabagal ang agent” at “ginugol ng agent ang huling sampung minuto sa shell-heavy git operations na may mataas na tool failure rate.”

May isang implementation detail na mas kakaiba ang itsura kaysa sa aktwal: ginagamit pa rin ng shared Loki stream ang service_name="claude-code-hooks" bilang label kahit galing pa ito sa Codex. Ang tunay na paghahati sa pagitan ng mga runtime nangyayari sa agent_tool.

Bakit Nasa Gitna ang Alloy

Hindi lang forwarder ang Grafana Alloy sa setup na ito. Ito ang policy boundary.

Itinuturo namin ang native OTEL stream mula sa Claude Code at Codex sa isang local Alloy proxy sa localhost:4318, tapos hinahayaan ang Alloy na linisin ang payload bago ito i-forward papunta sa Grafana Cloud.

Mahalaga iyon dahil puno ang raw agent telemetry ng high-cardinality na mga field na kapaki-pakinabang para sa analysis pero nakakatakot naman kung gagawing indexed labels:

session_id
prompt_id
token counts
durations
mga blob ng parameter ng tool

Kung ii-index mo lahat, magkakaroon ka ng label explosion at masamang araw.

Kaya tatlong bagay ang ginagawa ng Alloy para sa amin:

Pinapanatili ang napakaliit na set ng low-cardinality labels na naka-index.
Inililipat ang maiingay pero kapaki-pakinabang na mga field papunta sa structured metadata.
Tinatanggal ang purong ingay nang tuluyan.

Simple ang mahalagang ideya dito: mag-obserba nang mas marami, mag-index nang mas kaunti.

Bakit Nilalampasan ng Hook Stream ang Alloy

Naka-shape na ang hook stream para sa Loki.

Sa oras na mag-push ng event ang send_event.py, nadesisyunan na namin kung aling mga field ang dapat gawing label at alin ang dapat mapunta sa structured JSON body. Deretso na ang stream na iyon papunta sa OTLP gateway ng Grafana Cloud sa halip na dumaan pa ulit sa Alloy.

Kaya malinaw ang division of labor ng system:

Pinapaamo ng Alloy ang raw native OTEL stream.
Ginagawang queryable ng hook enrichment ang mga semantic event.

Mas pinapanatiling simple nito ang architecture kaysa sa sapilitang pagpasa ng lahat sa isang path.

Ang Talagang Ipinapakita ng Dashboard

Ang screenshot sa ibaba ay mula sa isa sa mga observability dashboard sa likod ng agent workflow namin. Hindi ito benchmark, at ang mga numero ay isang point-in-time slice lang. Ang punto ay ang hugis ng data: feed ng aktibidad, mga tawag sa tool, failure, prompt, at breakdown ayon sa agent, built-in na tool, MCP usage, shell command, at skills.

Ang kapaki-pakinabang na parte, nasa parehong Grafana stack ang dashboard na ito kasama ang natitirang agent telemetry. Puwede naming i-filter ayon sa source agent at tool family at tingnan ang lahat sa iba’t ibang runtime nang hindi na kailangang mag-imbento ng ibang observability story para sa bawat system.

Isa sa mga live dashboard sa likod ng agent workflow namin. Isang slice lang ito ng shared Grafana stack na tumatanggap din ng telemetry mula sa iba naming agent runtime at system. I-click ang larawan para sa full-resolution na bersyon.

Bakit Mas Mahalaga ang Traces Kaysa sa Unang Tingin

Sinasabi sa amin ng logs kung anong kategorya ng trabaho ang nangyari. Sinasabi naman sa amin ng traces kung paano umusad ang trabaho sa paglipas ng oras.

Mahalaga ang pagkakaibang iyon sa agent systems dahil masyadong malabo ang salitang “mabagal” para maging kapaki-pakinabang.

Puwedeng sabihin sa amin ng trace kung saan galing ang sakit ng ulo:

latency ng modelo
oras ng pagpapatakbo ng tool
paulit-ulit na retries
isang lalong mahal na MCP interaction
mahabang buntot ng maliliit na operations na parang wala namang epekto kung tingnan nang paisa-isa

Sa praktika, magkasabay naming ginagamit ang hook stream at ang Tempo traces.

Sinasagot ng Hook logs: anong klaseng bagay ang nangyari?
Sinasagot ng Traces: saan napunta ang oras?

Ang kombinasyon ng dalawa ang nagpapalit sa observability mula sa isang dashboard papunta sa isang paliwanag.

Kung Saan Pumapasok ang Codex

Bahagi ng parehong stack ang Codex, pero hindi ito kapareho ng Claude Code.

Para sa Codex, dalawang piraso ang ikinakabit namin:

Native OTEL mula sa Codex papunta sa Alloy
Isang notify webhook papunta sa codex_notify.py, na nagma-map ng turn completions papunta sa parehong Loki schema na ginagamit namin para sa hook events

Ibig sabihin, may unified filter kaming tulad ng agent_tool="codex-cli" sa loob ng parehong log stream.

Ang tapat na caveat: mas payat pa ngayon ang notify payload ng Codex kumpara sa hook payload ng Claude Code dahil hindi ito parehong klase ng integration surface. Sa setup namin ngayon, puwedeng i-normalize ang mga turn completion ng Codex papunta sa shared schema, pero mas maganda pa rin ang rich tool-by-tool extraction sa native OTEL stream kaysa sa notify bridge.

Hindi iyon dahilan para iwasan ang post na ito. Iyon mismo ang punto ng post na ito. Ang tunay na observability system, ginagawa mula sa mga imperfect na signal.

Binabago ng Grafana Over MCP ang Laro

Ang mas malaking shift, hindi na lang lugar ang Grafana na binibisita ng mga tao sa browser.

Sa repo na ito, ini-expose din namin ang Grafana sa MCP. Ibig sabihin, puwedeng direktang mag-query ng Loki, Prometheus, at Tempo ang isang agent sa halip na maghintay sa isang tao na manual na tingnan muna ang mga dashboard.

Ginagawa nito ang observability na isang active input sa workflow.

Puwedeng magtanong ang isang agent:

Aling tool families ang pinakamaraming nag-fail sa nakaraang oras?
Aling MCP server ang naging dominante sa isang session?
Binawasan ba ng mga kamakailang pagbabago ang tool failures, o inilipat lang nila ang trabaho papunta sa mas shell-heavy na mga path na may parehong mga pagkakamali?
Aling mga trace ang nagpapakita ng pinakamataas na latency o paulit-ulit na retries?

Kapag meron ka na niyan, malapit ka na sa isang self-improvement loop.

Mula sa Dashboard Papunta sa Feedback Loop

Ito ang parte na sa amin ang pinaka-interesting.

Sa oras na queryable na ang observability stack mula sa agent layer, hindi na lang passive reporting surface ang telemetry — nagiging control signal na ito.

Ganito ang hugis ng loop:

Naglalabas ang agent activity ng traces, metrics, at pinayamang hook logs.
Iniimbak ng Grafana ang ebidensya sa Loki, Tempo, at Prometheus kung saan mayroong metrics.
Nagqu-query ang mga agent ng ebidensyang iyon sa pamamagitan ng Grafana MCP.
Kinikilala ng system ang masamang tool mix, marupok na skills, mahinang routing, o shell-heavy na workflows na patuloy na gumagawa ng maiiwasang pagkakamali.
Nag-aadjust ang mga agent o operator ng prompts, agent configs, skill descriptions, routing rules, o tool access.
Nagbubunga ng bagong telemetry shape ang susunod na session, at umuulit ang cycle.

Ganoon ka aakyat mula sa “interesting dashboard” papunta sa “measurable improvement system.”

Hindi ang punto na i-maximize ang isang tool category. Ang punto, mahanap ang tamang timpla ng CLI, built-in tools, MCP calls, at skills para sa trabahong talagang ginagawa.

Ano ang Kaya Naming Sagutin Ngayon

Sa oras na parehong napunta sa iisang Grafana stack ang dalawang runtime, mas mabilis naming masasagot ang mga operational na tanong:

Nakakonsentra ba ang mga failure sa isang tool family?
Gumagawa ba ng maiiwasang pagkakamali ang mga shell-heavy na workflow kung saan dapat may mas mataas na antas na tool?
Aling mga MCP server ang may pinakamabigat na workload?
Nagbabayad ba kami para sa agent activity na hindi naman nagbubunga ng makabuluhang progreso?
Hindi ba malusog ang isang session dahil sa model, sa mga tool, o sa orchestration layer?

Lalo itong kapaki-pakinabang sa multi-agent workflows, kung saan wala talagang sinasabi ang “busy ang agent.”

Kung paulit-ulit na na-dispatch ang isang specialist at gumagawa ng mataas na failure rate, isyu iyon sa routing o sa prompt-shaping.

Kung isang MCP server ang dominante sa lahat ng calls, puwedeng magandang architecture iyon, o palatandaan na pabigat lang ang lahat ng iba pa.

Kung biglang tumataas ang tool failures habang mataas pa rin ang cost, isyu iyon sa operations, hindi sa quality.

Kung paulit-ulit na nabibigo ang shell work sa predictable at maiiwasang paraan kung saan dapat may mas mataas na antas na tool, isyu iyon sa produkto.

Kung palaging na-a-activate ang isang skill pero hindi naman umaangat ang outcomes, isyu iyon sa prompt o sa routing.

Ang Tunay na Aral

Ang mas malalim na aral dito, kailangan ng agent observability ng parehong telemetry ng runtime at telemetry ng workflow.

Sinasabi sa iyo ng telemetry ng runtime kung ano ang ginawa ng system.

Sinasabi sa iyo ng workflow telemetry kung ano sa tingin ng agent ang ginagawa nito.

Kailangan namin ng pareho.

Kung traces at counters lang ang panatilihin mo, mawawala sa iyo ang semantic layer. Kung hook events lang ang panatilihin mo, mawawala sa iyo ang latency, spans, at ang mas malawak na larawan ng runtime.

At kung panatilihin mo man ang pareho pero hindi mo ito ipinapakain pabalik sa agent layer, monitoring lang ang meron ka, hindi adaptation.

Ang kombinasyon ang gumagawa sa system na sapat na maipaliwanag para ma-operate at sapat na ma-tune para umangat.

Ano ang Hindi Pa Perpekto

May mga rough edge pa rin.

Hindi lahat ng hook event ay may kasamang duration at token data na gusto namin.
Ang ilan sa pinakamagandang timing view, galing pa rin sa Tempo traces, hindi sa hook logs.
Mas mababa pa ngayon ang semantic richness ng Codex kumpara sa Claude Code sa enriched event stream.
Ang dashboard screenshot ay isang live operations surface, hindi isang pinakintab na marketing artifact.

Sinadya ang huling punto na iyon. Mas gusto naming ipakita ang tunay na instrument panel kaysa magkunwaring self-explanatory na lang basta-basta ang agent systems.

Bakit Mahalaga Ito Para sa Maguyva

Ang layunin ng Maguyva, bigyan ang mga agent ng mas magandang code intelligence. Pero sa oras na talagang may kapaki-pakinabang na trabaho na ang mga agent, may bagong requirement na agad na lumilitaw: kailangan mong makita kung paano sila kumikilos.

Nagiging observable problems ang search quality, routing quality, tool selection, at context efficiency.

Kaya naman sa tingin namin, sulit itong isulat. Hindi lang prompts at tools ang future agent stack. Prompts, tools, at ang instrumentation layer na nagsasabi sa iyo kung gumagana ba talaga ang buong bagay.

Kung nagtatayo ka ng seryosong agent workflows, hindi optional infrastructure ang observability. Bahagi ito ng produkto.

Mining the Loop: Paano Nagiging Institutional Memory ang mga Pagbabago

Tue, 03 Feb 2026 00:00:00 GMT

Ang mga numero sa post na ito ay sumasalamin sa system noong publication (Pebrero 2026). Tingnan ang aming team page para sa kasalukuyang mga figure.

Parehong hamon ang hinaharap ng bawat engineering team: patuloy na nangyayari ang mga pagbabago, pero nawawala ang bakit sa likod ng mga pagbabagong iyon. Anim na buwan pagkatapos, may magtatanong ng “bakit namin pinili ang DuckDB para sa mga pipeline stage?” at ang sagot, nasa ulo lang ng taong gumawa ng desisyong iyon—kung nandiyan pa siya.

Gumawa kami ng mining workflow na nagsasara ng loop na ito. Dumadaloy ang mga pagbabago sa pamamagitan ng git commits, pino-proseso ng mining pipeline namin, nagiging structured changelog entries at architectural decision records, tapos pinapakain pabalik sa mga AI agent namin sa pamamagitan ng CLI queries. Ang resulta: institutional memory na puwedeng i-access ng parehong tao at AI.

Ang Problema: Nawawala ang mga Desisyon

Isipin ang isang karaniwang senaryo. May kina-commit ang isang developer:

feat(canonical): add DuckDB runtime for pipeline stages

Kumakatawan ang commit na ito sa isang makabuluhang architectural choice. Sinuri ng team ang mga opsyon, isinaalang-alang ang mga trade-off, at napunta sa DuckDB dahil sa mga specific na dahilan. Pero lahat ng context na iyon, nakatira sa:

Isang Slack thread (malamang burado na)
Alaala ng isang tao (siguradong nawawala na)
Isang comment sa code (baka, kung maswerte ka)

Tatlong buwan pagkatapos, may magtatanong na bagong miyembro ng team: “Dapat ba akong gumamit ng DuckDB o SQLite para sa bagong stage na ito?” Kung walang institutional memory, uulitin nila ang gawaing may solusyon na o gagawa ng hindi magkatugmang mga pagpili.

Ang Loop: Mula sa Commits Papunta sa Context

Ginagawang queryable knowledge ng mining workflow namin ang git history:

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)     │
      └───────────────┘

Ang key insight: parehong nagmumula ang changelogs at architectural decisions sa parehong git history, na pinoproseso sa pamamagitan ng iisang unified pipeline. Sinisiguro nito na walang malalampasan.

Paano Gumagana ang Mining

Hakbang 1: I-sync ang Index

uv run orkestra mine sync

Sini-scan ng command na ito ang git history at gumagawa ng index ng lahat ng commit. Kinukuha nito ang structured signals mula sa bawat commit:

Conventional commit type (feat, fix, chore, docs)
Scope (aling package o area)
Mga marker ng breaking change
Mga file na nagalaw at complexity metrics

Hakbang 2: I-check ang Coverage Status

uv run orkestra mine status

Ganito ang itsura ng kasalukuyang status namin:

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 commits ang naproseso. 476 ang naging architectural decisions. 6,799 ang naging changelog entries. Nauri ang bawat commit.

Hakbang 3: Kumuha ng mga Candidate para sa Review

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

Ito ang naglalabas ng mga commit na hindi pa naproseso, kasama ng buong context para sa classification:

{
  "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}
}

Tumutulong ang mga signal sa pag-guide ng classification: iminumungkahi ng is_releasable_type: true na dapat lumitaw ito sa changelog. Iminumungkahi naman ng malaking insertion count at mga infrastructure file na puwede rin itong maging architectural decision.

Hakbang 4: I-classify ang mga Commit

Dalawang landas ang nagkakahiwalay dito: changelog entries at architectural decisions.

Para sa changelog entries:

uv run orkestra mine classify abc123 --changelog added

Naitatala nito na dapat lumitaw ang commit na abc123 sa changelog sa ilalim ng kategoryang “Added.”

Para sa architectural decisions:

Una, kumuha ng tunay na decision ID:

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

Tapos i-classify gamit ang decision ID:

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

Nag-uugnay ito sa commit sa isang decision record na gagawin o iu-update.

Para sa batch processing (ang talagang ginagawa namin):

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

Sinusuportahan ng JSONL format ang parehong domain sa isang pass:

{"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"}

Hakbang 5: I-render ang mga Output

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

Nagbubunga ito ng mga per-package na file na CHANGELOG.md mula sa ledger. Ang mga changelog, derived artifacts—burahin mo sila at magre-regenerate sila nang perpekto mula sa source ledger.

Ang Structure ng Decision Record

Nagiging mga YAML file na may mayamang metadata ang mga na-extract na decision:

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

Bawat decision, may link pabalik sa source commits nito. Bawat decision, tinutukoy kung aling mga file ang naaapektuhan nito. Explicit ang mga relationship sa pagitan ng mga decision.

CLI Integration: Pagqu-query ng Institutional Memory

Dito nagsasara ang loop. Puwedeng mag-query ng mga decision ang mga agent sa pamamagitan ng CLI:

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

Nagbabalik ng mga decision tungkol sa retry logic, error handling, recovery patterns.

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

Nagbabalik ng kumpletong decision record na may context, rationale, at impact.

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

Ipinapakita kung anong mga architectural choice ang ginawa kamakailan.

Paano Ginagamit Ito ng mga Agent

Kasama sa baseline instructions ng orchestrator namin:

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

Kapag hiniling sa isang agent na mag-implement ng may kinalaman sa DuckDB, puwede muna itong mag-check:

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

At matuklasan ang DEC-PL-142, matutunan ang:

Bakit pinili ang DuckDB (context)
Paano ito gamitin nang tama (agent_guidance)
Aling mga file ang titingnan (files)
Anong mga related na decision ang umiiral (related)

Hindi na kailangang magsimula ulit sa wala ang agent. Bubuo ito sa itinatag nang mga pattern.

Ang Three Questions Test

Hindi karapat-dapat ang bawat commit sa isang decision record. Ginagamit namin ang Three Questions Test para i-filter:

Mahirap ba itong gawin? Nangailangan ba ito ng masusing analysis, trade-off evaluation, o debate?
Mahal bang baguhin? Kailangan ba ng makabuluhang rework para baligtarin ang desisyong ito?
May system-wide na epekto ba ito? Naaapektuhan ba nito ang maraming package o nagtatatag ba ito ng mga pattern na susundin ng iba?

Kung “oo” ang sagot ng isang commit sa kahit isa sa mga tanong na ito, isa itong candidate para sa decision extraction. Ang karaniwang rate namin: 1-4 na decision kada 100 commit (mga 1-4%).

Para sa changelog entries, mas mababa ang bar: naitatala ang anumang user-facing na pagbabago (features, fixes, improvements). Karaniwang nili-skip ang internal chores, documentation updates, at refactors. Ang karaniwang rate namin: 30-50 na changelog entry kada 100 commit.

Pag-imbak ng data: append-only na ledger

Gumagamit ang mining system ng append-only JSONL ledgers para sa conflict-free na multi-agent operation:

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
    └── ...

Ang JSONL format na may merge=union sa .gitattributes, ibig sabihin, puwedeng mag-classify ng mga commit ang maraming agent nang sabay-sabay nang walang merge conflicts. Independent ang bawat linya.

Mga gate ng validation

Bago ang anumang mining session, nagpapatakbo kami ng validation:

uv run orkestra mine validate --quick

Sini-check nito:

Bisa ng SHA format
Pagsunod sa decision ID format
Walang duplicate entries para sa parehong SHA
Talagang umiiral ang mga na-reference na decision

Pagkatapos ng classification, nagva-validate kami ulit bago mag-commit ng mga pagbabago.

Bakit Mahalaga Ito

Sinolusyunan ng feedback loop na ginawa namin ang ilang problema:

Para sa mga bagong miyembro ng team: Sa halip na magtanong ng “bakit namin ginawa ang X?”, puwede nilang i-search ang decisions registry. Napapanatili ang context.

Para sa mga AI agent: Hindi sila nagtatrabaho sa isang vacuum. Puwede nilang i-query ang institutional knowledge bago gumawa ng mga rekomendasyon. Kapag hiniling na magdagdag ng bagong pipeline stage, puwede nilang matuklasan ang DuckDB pattern at sundan ito.

Para sa architectural consistency: Explicit at searchable ang mga desisyon. Kapag may nagmumungkahi ng approach na sumasalungat sa umiiral nang desisyon, puwedeng ilabas ng system ang conflict.

Para sa changelog generation: Hindi last-minute na pagmamadali ang release notes. Byproduct sila ng patuloy na classification habang nagde-develop.

Para sa onboarding: Namamana ng mga bagong agent ang buong context ng codebase. Hindi lang nila nakikita ang code—nakikita rin nila ang mga desisyon na humubog dito.

Kasalukuyang Estado

Sa ngayon:

15,637 commits ang naproseso sa pipeline
476 na architectural decision ang na-extract at na-dokumento
6,799 changelog entries ang naitala
100% coverage sa parehong domain

Nauri ang bawat commit mula nang magsimula kami. Kumpleto at queryable ang institutional memory.

Pagsisimula

Kung gusto mong mag-implement ng katulad nito:

Magsimula sa conventional commits. Pinakamahusay gumana ang mining pipeline kapag may structured prefix ang mga commit (feat:, fix:, chore:).
I-define ang mga domain mo. Gumagamit kami ng mga domain tulad ng pipeline, agent-design, observability, data-modeling. Ino-organisa nito ang mga desisyon ayon sa area.
Bumuo ng classification habit. Gumagana ang mining kapag regular na nagki-classify ng mga commit ang mga team. Nakakatulong sa pag-scale ang batch processing na may LLM assistance.
Gawing queryable ang mga desisyon. Tumataas ang value kapag puwedeng i-search ng mga agent ang mga desisyon sa pamamagitan ng CLI. I-structure ang output mo para sa machine consumption.
Isara ang loop. Dapat maimpluwensyahan ng mga desisyon ang hinaharap na trabaho. Isama ang mga decision reference sa agent instructions at code review checklists.

Hindi perpektong documentation ang layunin. Ang gawing accessible sa parehong tao at AI ang bakit sa likod ng mga pagbabago, ngayon at anim na buwan mula ngayon. Kapag naging institutional memory na ang mga pagbabago, bumubuo ang mga team sa itinatag nang mga pattern sa halip na ulitin ang mga ito.

Bahagi ng orchestration engine namin ang mining workflow, mismong ang context engine module sa orchestration package namin.

Skill Mining: Mula sa 3,500 Kandidato Papunta sa 466 Kakayahan

Tue, 27 Jan 2026 00:00:00 GMT

Ang mga numero sa post na ito ay sumasalamin sa system noong publication (Enero 2026). Tingnan ang aming team page para sa kasalukuyang mga figure.

Ang Problema ng 3,500 Skill

Nang magsimula kaming bumuo ng agent orchestration system, hinarap namin ang isang interesting na hamon: may libo-libong potensyal na skill na nakakalat sa buong AI ecosystem. GitHub repositories, vendor documentation, community projects, internal patterns - kahit saan ay may mga skill. Pero alin ang mahalaga? Alin ang gumagana? At paano ka magpapanatili ng coherent na skill library na talagang magagamit ng mga agent?

Ang sagot namin: isang sistematikong mining at ingestion loop.

Ang mga Numero Ngayon

Tatlong buwan lamang matapos ilunsad ng Anthropic ang Agent Skills noong Oktubre 16, 2025, ganito ang aming kalagayan nang ma-publish ang post na ito noong Enero 27, 2026:

Metric	Bilang
Nakilalang candidates	3,500+
Mga na-adopt na skill	466
Mga skill mula sa vendor	373
Panloob na mga skill	93
Aktibong vendors	25+
Average na tokens bawat skill	2,834
Na-reference na tools	89
Natatanging tags	635

Sinuri namin ang mahigit 3,500 skill candidate. Nag-adopt kami ng 466. Iyon ay 13% na adoption rate - at sinadya ang selectivity na iyon.

Ang Knowledge Tier System

Hindi magkapareho ang lahat ng skill. Ino-organisa namin sila sa limang knowledge layer (K0-K4), bawat isa kumakatawan sa ibang scope ng applicability:

K0: Mga pundasyon (universal)

Mga skill na dapat meron ang bawat agent. Kumakatawan ang mga ito sa “good thinker” na capabilities na gumagana kahit saan.

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

Portable ang mga K0 skill sa anumang project, anumang domain, anumang stack. In-encode nila ang universal cognitive patterns.

K1: Mga identity (disiplina)

Mga “good engineer” o “good researcher” na skill na umaapply sa mga project sa loob ng isang discipline.

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

K2: Mga domain (dalubhasang kaalaman sa paksa)

Mga “good database expert” o “good security engineer” na skill na portable sa loob ng isang field.

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: Mga stack (teknolohiya)

Mga “good Supabase user” o “good Cloudflare developer” na skill para sa specific na technology stacks.

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

K4: Proyekto (organisasyon)

Mga skill na specific sa organisasyon at workflows namin.

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

Ang Mining Loop

Yugto 1: Pagtuklas

Galing kahit saan ang mga skill:

Vendor Repositories: Naglalathala ng skill collections ang AWS, Anthropic, Cloudflare, Supabase, at mga community contributor. Sinusubaybayan namin ang 25+ vendor root.

Mga community project: Puno ang GitHub ng mga Claude Code template, agent pattern, at workflow definition.

Internal Patterns: Habang nireresolba ng team namin ang mga problema, lumalabas ang mga pattern. Nagiging formalized ang mga ito papunta sa mga skill.

Documentation Mining: Madalas may implicit na skills ang technical documentation - mga procedure, checklist, decision tree.

Tuloy-tuloy ang pagtuklas. Gumagamit kami ng skill backlog para subaybayan ang mga candidate bago ang formal evaluation.

Yugto 2: Pagsusuri

Dumadaan ang bawat candidate sa parehong rubric:

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

Dapat pumasa ang lahat ng limang product criteria. Kaya naman 87% ng mga candidate ang tinatanggihan.

Tapos dumadaan ang bawat candidate sa hiwalay na trust review. Hindi namin itinuturing na katumbas na source of truth ang isang official vendor repository, isang kilalang community maintainer, at isang random na GitHub repo.

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

Nakakakuha ng mas magaan na provenance review ang mga trusted vendor, pero hindi ito free pass. Nakakakuha ng mas malalim na manual audit ang mga untrusted o unknown na source, at hindi namin pinapatakbo ang mga bundled script hangga’t hindi ito nababasa, na-scope, at na-classify na safe.

Pagsusuri ng gap: Bago mag-adopt, sini-search namin ang registry:

uv run orkestra skills search "<capability>"

Kung meron na kami niyan, hindi na namin kailangan. Kung may malapit kaming meron, baka mag-merge kami sa halip na mag-adopt.

Depth at Standards Scoring: Sini-score rin namin kung gaano kalubos ginagamit ng isang candidate ang agent-skill model. Puwede pa ring maging kapaki-pakinabang ang nag-iisang SKILL.md, pero mas mahalaga ang mas malalim na mga skill kapag hinihiwalay nila ang instructions mula sa references, scripts, at assets sa paraang hinihikayat ng 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

Puwedeng bahagyang umangat ang credibility score dahil sa GitHub stars, pero hindi nila kailanman naililigtas ang isang mababaw o hindi ligtas na skill. Ang isang repo na maraming star na may isang malabo na SKILL.md at opaque na scripts, mas mababa ang score kaysa sa isang mas maliit na repo na may precise na deskripsyon, curated na references/, at atomic na mga helper na talagang gumagamit ng buong kakayahan ng skill.

Structural Analysis: Chine-check namin ang kalidad ng skill:

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

Kung may kasamang scripts ang isang candidate, mas mahigpit ang review na iyon. Ang isang magandang skill, hindi lang kapaki-pakinabang; kailangan din itong legible, bounded, at ligtas na maiabot sa isang agent. Ang safety filter na iyon lang, nagdi-disqualify na ng makabuluhang bahagi ng kung hindi man ay interesting na candidates.

Yugto 3: Pag-ingest

Kapag pumasa sa evaluation ang isang skill, papasok ito sa registry. Pero hindi kailanman ina-adopt ang mga skill nang hindi binabago. Binabago sila para umangkop sa system namin.

Mga Pagbabago sa Adoption:

Metadata Normalization: Nakukuha ng bawat skill ang frontmatter schema namin
Pagtatalaga ng K-tier: Inilalagay ang mga skill sa naaangkop na knowledge layer
Pagpapayaman ng tag: Nagdaragdag ng tags para sa discovery
Deklarasyon ng tool: Explicit na na-declare ang mga allowed tool
Pag-align ng seksyon: Muling in-a-istruktura ang content para tumugma sa template namin

Isang karaniwang skill YAML pagkatapos ng 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

Yugto 4: Pagtatalaga ng saklaw

Ini-assign ang mga skill sa mga scope - mga kategorya na tumutukoy kung aling agent ang naglo-load ng aling skill:

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

Idine-declare ng mga agent ang scope nila, at automatic na ina-assign ang mga skill:

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

Yugto 5: Pag-materialize

Hindi nakatira bilang YAML ang mga skill sa production. Ini-render sila papunta sa mga SKILL.md file na puwedeng i-load ng Claude Code:

uv run orkestra sync

Ang command na ito:

Binabasa ang lahat ng skill YAML definition
Ini-render ang mga ito sa pamamagitan ng Jinja templates
Isinusulat ang mga SKILL.md file papunta sa .claude/skills/
Ino-organisa ayon sa K-tier (foundations/, identities/, domains/, stacks/, project/)

Ang huling output structure:

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

Ang Dormant Scope Pattern

Isa sa pinakamalakas naming pattern, ang “adopted-but-not-loaded” na mga skill. Tinatawag namin itong dormant scopes.

Isipin ang mga scientific computing skill mula sa k-dense-scientific repository. Nag-adopt kami ng 120+ na skill na sumasaklaw sa bioinformatics, chemistry, quantum computing, at clinical informatics. Pero karamihan sa mga agent namin, hindi kailangan ng molecular docking o gene expression analysis.

Sa halip na i-load ang lahat ng 120 skill sa bawat agent (na nagpapalaki sa context windows), kami ay:

Nag-a-adopt ng mga skill na may specific na scope (halimbawa, bioinformatics)
Pinapanatili silang dormant - registered pero hindi naka-load
Ina-enable lang sila kapag nag-declare ang isang agent ng scope na iyon

# 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

Dahil sa pattern na ito, kaya naming magkaroon ng 466 skill sa registry habang karaniwang 40-60 relevant na skill lang ang nilo-load ng mga typical na agent.

Mga Uri ng Skill

Dumarating ang mga skill sa tatlong cognitive pattern:

Workflow (daloy ng trabaho)

Ordered na procedural na mga hakbang: “1. Gawin ang X, 2. Tapos ang Y, 3. Sa wakas ang Z”

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

Discipline (disiplina)

Behavioral na mga guardrail: “Palaging X”, “Huwag kailanman Y”, “Mas piliin ang Z”

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

Checklist (listahan ng pagsusuri)

Mga verification criteria: “Kumpirmahin ang X”, “I-verify ang Y”, “I-check ang Z”

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

Mga gate ng kalidad

Kailangang pumasa ang bawat skill sa validation bago ito magship:

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

Kailangang 50-400 characters ang mga deskripsyon na may trigger phrases (“Gamitin kapag…”, “Kapag kailangan mo ng…”) para malaman ng Claude Code kung kailan sila imumungkahi.

Tuloy-tuloy naming vina-validate ito:

uv run orkestra validate --show-warnings

Ang Vendor Ecosystem

Ang 373 vendor skills namin, galing sa:

Provider	Skills	Domain
AWS Agent	19	Mga serbisyo sa cloud
Anthropic	12	Pagbuo ng dokumento
Cloudflare	8	Edge computing
Supabase	5	Database
k-dense	100+	Siyentipikong computing
silvainfm	4	Agham ng datos
Java Developer Kit	45+	Spring/Java
Vercel	1	Automation ng browser

Idine-declare ang bawat vendor root sa 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

Kapag pumapatakbo ang orkestra sync, sini-symlink ang mga vendor skill papunta sa .claude/skills/vendor/ kasama ang provider namespace nila.

Ano ang Natutunan Namin

May bunga ang selectivity. Nakakatukso na i-adopt ang lahat ng mukhang kapaki-pakinabang. Pero may halaga sa tokens ang bawat skill. Sa 2,834 average na token kada skill, mabilis na nagiging problema ang bloat. Pinapanatili ng 13% na adoption rate namin ang mga agent na lean.

Nagbibigay-daan ang structure sa discovery. Hindi lang organisasyon ang K-tier system - tungkol ito sa portability. Puwedeng magamit muli ang mga K0 skill kahit saan. Sinadyang project-specific ang mga K4 skill. Tinutulungan ng kalinawang ito ang parehong tao at agent na mahanap ang kailangan nila.

Nag-sscale ang dormant scopes. Puwede kang mag-adopt ng daan-daang skill nang hindi ini-load ang lahat ng ito. Hinahayaan ka ng scopes na bumuo ng comprehensive na registry habang pinapanatiling manageable ang context windows ng indibidwal na agent.

Mahalaga ang modification on adoption. Bihirang umangkop ang raw na vendor skills sa system mo. Ang ingestion process - pagdagdag ng metadata, pag-assign ng tiers, pagpapayaman ng tags - ang gumagawa sa external na skills na gumana internally.

Tuloy-tuloy ang mining. Patuloy na lumalaki ang numerong 3,500. May lumalabas na bagong vendor repos. Umuusbong ang community patterns. Lumalakas ang internal workflows. Hindi kailanman humihinto ang loop.

Ano ang Susunod

Nagtatrabaho kami sa ilang improvement:

Awtomatikong pagtuklas ng gap: Mag-alerto kapag puwedeng masolusyunan ng isang hindi pa na-adopt na skill ang mga karaniwang agent failure
Workflow para sa pag-deprecate ng skill: Formal na proseso para sa pagretiro ng mga skill na na-supersede o hindi na ginagamit
Dependency sa pagitan ng skill: Explicit na declaration ng mga skill prerequisite
Analytics ng paggamit: Subaybayan kung aling mga skill ang talagang tinatawag ng mga agent kumpara sa i-load lang

Infrastructure ang skill mining loop. Hindi ito kaakit-akit. Pero ito ang gumagawa sa 41 agent na gumana nang coherent kasama ang 466 capabilities habang nananatili sa loob ng context limits.

Iyon ang kwento kung paano naging 466 ang 3,500. Hindi sa pamamagitan ng pagbalewala sa 3,000 - sa pamamagitan ng sistematikong pagsuri sa kanila at pag-a-adopt lang ng gumagana.

Gustong makita ang skill system sa aksyon? Tingnan ang uv run orkestra skills list para i-explore ang kasalukuyang registry namin.

Progressive Disclosure: Mga Bintanang CLI Papasok sa Agent Systems

Tue, 20 Jan 2026 00:00:00 GMT

Ang mga numero sa post na ito ay sumasalamin sa system noong publication (Enero 2026). Tingnan ang aming team page para sa kasalukuyang mga figure.

Opaque by design ang agent systems. Gumagawa sila ng mga desisyon, tumatawag ng mga tool, at nagko-coordinate ng trabaho sa dose-dosenang specialist. Pero kapag may nasira—o kapag gusto mo lang maintindihan kung ano ang nangyayari—saan ka titingin?

Ang sagot, progressive disclosure: isang layered na interface na nagbubunyag lang ng eksaktong dami ng complexity na kailangan mo, sa eksaktong sandaling kailangan mo ito.

Ang Problema sa Opacity

Puwedeng magkaroon ang isang modernong agent orchestration system ng:

40+ specialist agent, bawat isa may natatanging capabilities
700+ skill na sumasaklaw sa internal automation at vendor integrations
470+ architectural decision na humuhubog sa behavior
Dose-dosenang MCP tool server na nagbibigay ng external capabilities

Sinadya ang complexity na ito. Kailangan ng mga agent ng access sa mayamang context—domain knowledge, code intelligence, database schemas—para gumawa ng magagandang desisyon. Pero ang parehong kayamanang iyon, gumagawa ng problema sa visibility.

Paano mo malalaman kung aling agent ang humahawak ng database migrations? Anong mga desisyon ang humubog sa ranking behavior ng search system? Aling mga tool ang puwedeng gamitin ng architecture advisor?

Kung walang structured na access, mababasa mo na lang ang source code o umaasang updated ang documentation.

Progressive Disclosure Bilang Architecture

Hindi lang isang UI pattern ang progressive disclosure. Isa itong architectural principle: i-organisa ang impormasyon sa mga layer, bawat isa ay mas detalyado kaysa sa nauna, para makapag-stop ang mga user sa level na sumasagot sa tanong nila.

Para sa agent systems, isinasalin ito sa mga CLI command sa tumataas na lalim:

Level	Command	Tanong na Nasasagot
1	`orkestra system status`	Malusog ba ang lahat?
2	`orkestra agents list`	Anong mga agent ang umiiral?
3	`orkestra agents info <name>`	Ano ang ginagawa ng agent na ito?
4	`orkestra decisions search`	Bakit ganito ito gumagana?
5	Mga MCP tool ng Maguyva	Ipakita mo sa akin ang code.

Sinasagot ng bawat level ang natural na follow-up na tanong. Bihira mong kailanganing tumalon deretso sa level 5.

Level 1: Kalusugan ng System

Ang unang tanong, palaging: gumagana ba ang lahat?

$ orkestra system status

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

Isang command. Apat na numero. Sapat na para malaman na naka-configure ang system at populated ang mga registry.

Kung biglang bumaba ang bilang ng agent o nabigo ang paglo-load ng skills, makikita mo ito rito muna. Walang kailangang log diving.

Level 2: Inventory ng Agent

Kapag alam mo nang malusog ang system, ang susunod na tanong: ano ang available?

$ orkestra agents list

Nagbabalik ito ng structured data—mga pangalan ng agent, descriptions, model preferences, domain coverage. JSON by default ang output, madaling i-pipe papunta sa jq para sa filtering:

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

Gusto mo ng mga agent na humahawak ng database work? Pinapaliit ito ng search command:

$ orkestra agents search "database"

Sini-scan nito ang mga pangalan, deskripsyon, at capabilities. Mahahanap mo ang tamang specialist nang hindi na kailangang basahin ang 40 agent definition.

Level 3: Deep Dive sa Agent

Nakahanap ng agent na mukhang relevant? Ibinubunyag ng command na info ang lahat:

$ orkestra agents info architecture-advisor

Kasama sa output:

Metadata: Pangalan, kategorya, model preference, deskripsyon
Domains: Aling mga knowledge area ang sinasaklaw ng agent na ito
Identity: Mga katangian ng karakter (architect, strategist, knowledge-architect)
Mga gabay sa tool: Aling tool documentation ang ini-inject sa context
Tools: Ang buong listahan ng MCP tool na available sa agent na ito

Narito ang sample ng makikita mo:

{
  "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",
      ...
    ]
  }
}

Sinasabi nito sa iyo nang eksakto kung ano ang kaya ng agent. Hindi na kailangan ng source code.

Antas 4: Arkeolohiya ng desisyon

Kumikilos ang mga agent ayon sa mga naitalang desisyon. Kapag kailangan mong maintindihan ang bakit gumagana ang isang bagay sa isang particular na paraan, ang decisions registry ang source of truth.

$ orkestra decisions search "agent"

Nagbabalik ito ng mga tumutugmang architectural decision:

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

Bawat desisyon, may buong provenance—kailan ito ginawa, bakit, anong mga trade-off ang isinaalang-alang, aling mga commit ang nag-implement nito:

$ 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..."
    }
  ]
}

Ito ang architectural documentation na nananatiling current dahil kinukuha ito mula sa mga commit, hindi manually maintained.

Level 5: Direktang Code Intelligence

Kapag kailangan mong makita ang aktwal na implementation—hindi metadata tungkol dito—nagbibigay ng direktang access ang mga MCP tool ng Maguyva.

Mula sa loob ng isang agent session:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Auto-routes ito sa semantic, text, at AST search para mahanap ang relevant na code. Para sa mga specific na symbol:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Para sa dependency analysis:

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

Hindi lang ito mga grep replacement. Graph-aware sila, semantically indexed, at integrated sa parehong code intelligence na nagpapatakbo sa mga agent mismo.

Unified Search Sa Lahat ng Registry

Minsan, hindi mo alam kung aling registry ang may hawak ng sagot. Sinasaklaw ng unified search ang lahat:

$ orkestra search "database" --summary

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

254 na tugma sa limang registry. Sinasabi sa iyo ng summary kung saan mag-drill down. Alisin ang --summary para sa detalyadong resulta, o idagdag ang --limit 5 para panatilihing manageable ang output.

Bakit Mahalaga Ito

Hindi lang tungkol sa convenience ang progressive disclosure. Binabago nito kung paano ka nakikipag-interact sa mga komplikadong system.

Nagiging tractable ang debugging. Kapag gumawa ang isang agent ng hindi inaasahang desisyon, hindi ka nagge-grep sa mga log. Chine-check mo kung aling mga tool ang maaari nitong i-access (agents info), anong mga desisyon ang humuhubog sa behavior nito (decisions search), at sinusubaybayan ang implementation kung kailangan (intelligent_search).

Mas mabilis ang onboarding. Hindi kailangang basahin ng mga bagong miyembro ng team ang buong codebase. Nagsisimula sila sa system status, nag-e-explore gamit ang agents list, at lumalalim lang kapag may nadatnan silang hindi nila maintindihan.

Nananatiling current ang documentation. Dahil binabasa ng CLI ang parehong mga registry na nag-configure sa mga agent, laging tumpak ang output. Walang drift sa pagitan ng sinasabi ng docs at ginagawa ng system.

Ang CLI Bilang Interface

Puwede kaming gumawa ng web dashboard. Puwede kaming sumulat ng masusing documentation. Sa halip, gumawa kami ng CLI na nagbabasa mula sa source of truth.

May mga bentahe ang CLI:

Composable: I-pipe ang output sa pamamagitan ng jq, i-integrate sa mga script
Scriptable: I-automate ang mga check, gumawa ng mga report
Mabilis: Walang page loads, walang authentication flows
Tumpak: Binabasa ang aktwal na configuration, hindi isang cached na representasyon

Para sa mga system kung saan mas mahalaga ang correctness kaysa aesthetics, panalo ang CLI.

Paggawa ng Sarili Mong Progressive Disclosure

Kung gumagawa ka ng agent systems, isaalang-alang kung paano sisiyasatin ito ng mga user:

Magsimula sa health checks. Isang command na nagsasabi sa iyo kung gumagana ang mga bagay.
Magbigay ng inventory views. Ilista kung ano ang umiiral bago ipaliwanag kung ano ang ginagawa nito.
Paganahin ang targeted na queries. Mas mahusay ang search kaysa sa pag-browse kapag malaking sukat.
Ibunyag ang provenance. Hayaan ang mga user na subaybayan ang mga desisyon pabalik sa pinagmulan nila.
Ikonekta sa code intelligence. Sa huli, kailangang makita ng mga user ang implementation.

Sinasagot ng bawat layer ang isang follow-up na tanong. Buuin ang mga ito ayon sa frequency—karamihan sa mga user, humihinto sa layer 2 o 3. Mga power user lang ang umaabot sa layer 5.

Hindi ang pagbubunyag ng lahat ang punto. Ang punto, ibunyag ang eksaktong kailangan, sa eksaktong sandaling kailangan ito. Iyon ang progressive disclosure na inilapat sa agent architecture.

Mga Batayang Katotohanan: Pag-anchor ng mga AI Agent sa Realidad

Tue, 13 Jan 2026 00:00:00 GMT

Ang mga numero sa post na ito ay sumasalamin sa system noong publication (Enero 2026). Tingnan ang aming team page para sa kasalukuyang mga figure.

Talagang mahusay ang mga AI agent. Kaya nilang mangatwiran, mag-synthesize, at gumawa. Pero may fundamental na kahinaan sila: gumagawa-gawa sila ng mga bagay. Hindi dahil may masamang intensyon, kundi confidenteng ginagawa nila ito. Puwedeng mag-imbento ang isang agent ng mga API parameter na wala talaga, mag-reference ng mga configuration na hindi naman na-define, o mag-apply ng mga pattern mula sa training data nito na sumasalungat sa totoong architecture mo.

Ang standard na solusyon, “bigyan ang agent ng mas maraming context.” Pero puwedeng magkasalungat ang context. Lumalayo ang documentation mula sa implementation. Nagsisinungaling ang mga comment. Kahit ang code, puwedeng makapagligaw kung babasahin nang walang pag-unawa sa intent.

Kailangan namin ng mas explicit na bagay. Isang bagay na hindi maaaring balewalain o maling maintindihan. Isang bagay na mag-a-anchor sa mga agent papunta sa napatunayang realidad.

Tinatawag namin itong mga batayang katotohanan.

Ano ang isang Ground Truth?

Ang isang ground truth ay isang explicit, versioned na pahayag ng katotohanan na dapat igalang ng mga agent. Hindi ito documentation. Hindi ito isang comment. Ito ay isang first-class entity sa system na may:

Isang unique identifier (tulad ng GT-MAG-015 o GT-MAG-036)
Isang lifecycle status (current, tentative, o deprecated)
Isang scope (platform-wide, package-specific, o domain-bound)
Evidence (mga file path, URL, o reference na nagpapatunay sa pahayag)
Agent guidance (explicit na do/avoid na mga instruction)

Narito ang isang halimbawa mula sa aming Maguyva code intelligence platform:

- 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

Hindi ito prose. Isa itong kontrata. Kapag nakita ng isang agent ang ground truth na ito, alam nito:

Deterministic ang default (walang laman na resulta, hindi fuzzy na hula)
May mga specific na parameter (find_similar, exact_match) na may defined na behavior
May ebidensyang nasa mga specific na file na puwedeng ma-verify
Na-verify ang pahayag sa isang specific na petsa

Ang Anatomiya ng isang Ground Truth Registry

Nakatira ang mga ground truth sa mga YAML registry sa ilalim ng ai_assets/reference/ground_truths.yaml. Bawat package o domain, puwedeng may sariling registry. Ganito ang structure:

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..."
    ...

Kasama sa registry ang metadata tungkol sa koleksyon mismo, render configuration para sa pagbuo ng documentation, at ang mga pahayag mismo. Bawat pahayag ay sumusunod sa isang mahigpit na schema na na-validate ng mga Pydantic model:

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

Paano nag-a-access ang mga agent sa mga batayang katotohanan

Ini-expose ang mga ground truth sa iba’t ibang channel:

1. Naka-render na Dokumentasyon

Ginagawa ng command na orkestra sync ang mga YAML registry papunta sa mababasang markdown:

uv run orkestra sync

Nagbubunga ito ng mga file na GROUND_TRUTHS.md na kasama sa agent context. Ini-group ng rendered output ang mga pahayag ayon sa status at kategorya:

## 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. Paghahanap sa CLI

Puwedeng mag-search ang mga agent na may shell access ng ground truths nang programmatic:

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

Nagbibigay ng score ang search function sa mga match sa iba’t ibang field gamit ang weighted relevance:

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. Komposisyon ng Konteksto

Kapag rendered ang mga agent mula sa mga YAML definition, puwedeng mag-reference ang context nila sa mga ground truth registry:

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

Sinisiguro nito na nakaload na ang mga relevant na ground truth bago magsimula ng trabaho ang agent.

Mga Kategorya ng mga batayang katotohanan

Kapag tiningnan ang aming mga registry, nag-cluster ang mga ground truth sa ilang pattern:

Mga prinsipyo ng produkto

Mga hangganan sa kung ano ang produkto at kung ano ito hindi:

“Read-only ang Maguyva pagdating sa mga repository ng user; ang tanging non-rebuildable na asset ay ang paid embeddings cache.” (GT-MAG-001)

Mga Hangganan ng Arkitektura

Saan nakatira ang mga responsibilidad at bakit:

“Sinadya ang mga hangganan ng pipeline at Maguyva: reusable ang pipeline, hawak ng Maguyva ang code-specific na logic, at ihinihiwalay ng CQRS ang stage writes mula sa server reads.” (GT-MAG-006)

Mga tuntunin laban sa hallucination

Explicit na mandato na nagpapanatiling deterministic sa halip na inferred ang mga tool contract:

“Opt-in ang fuzzy symbol matching sa pamamagitan ng find_similar=true. Nagbabalik ang default na behavior ng walang laman na resulta para sa mga hindi umiiral na symbol; pinapatupad ng exact_match=true ang strict matching at dini-disable ang lahat ng fuzzy fallback.” (GT-MAG-015)

Mga gate ng kalidad

Mga standard na kailangang mapanatili:

“Ang mga pagbabago sa shared infrastructure (post_filters.py, relationship extractors, shared handlers) AY DAPAT ma-validate laban sa LAHAT ng suportadong wika sa pamamagitan ng full manifest generation bago mag-commit. Hindi sapat ang single-language validation para sa shared code.” (GT-MAG-036)

Mga Pattern ng Code

Mga implementation requirement:

“Gamitin ang asyncio.to_thread() para sa CPU-bound na trabaho sa async contexts; hindi dapat gamitin ang deprecated na pattern na loop.run_in_executor() sa bagong code.” (GT-MAG-018)

Ang Lifecycle ng isang Ground Truth

Hindi static ang mga ground truth. Umuunlad sila sa pamamagitan ng isang defined na lifecycle:

Tentatibo

Isang iminumungkahing katotohanan na sinusuri pa. Naitala ang pahayag pero puwede pa itong magbago:

- 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.

Kasalukuyan

Isang na-verify na katotohanan na dapat igalang ng mga agent. Na-validate na ang ebidensya:

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

Deprecated (Hindi na Ginagamit)

Isang katotohanan na hindi na umaapply. Iniingatan para sa historical reference kasama ang pointer sa pumalit dito:

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

Bakit Hindi Documentation na Lang?

Ibang layunin ang pinaglilingkuran ng documentation. Nagpapaliwanag ito. Nagtuturo ito. Puwede itong maging vague, puwedeng gumamit ng mga qualifier tulad ng “generally” o “typically.”

Hindi puwedeng maging vague ang mga ground truth. Mga assertion sila. Umaapply sila o hindi.

Tingnan ang pagkakaiba:

Documentation: “Karaniwang nagbabalik ang API ng walang laman na resulta kapag hindi nahanap ang isang symbol, bagaman puwedeng naka-enable ang fuzzy matching sa ilang configuration.”

Ground Truth: “Nagbabalik ang default na behavior ng walang laman na resulta para sa mga hindi umiiral na symbol; pinapatupad ng exact_match=true ang strict matching at dini-disable ang lahat ng fuzzy fallback.”

Ang una, kapaki-pakinabang para sa mga taong natututo sa system. Ang ikalawa, actionable para sa mga agent na gumagawa ng desisyon.

Agent Guidance: Gawin at Iwasan

May kasamang explicit na agent guidance ang ilang ground truth:

- 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"

Tinatanggal nito ang ambiguity. Kapag binasa ito ng isang agent, alam nito hindi lang kung ano ang totoo, kundi pati kung anong aksyon ang ipinapahiwatig ng katotohanang iyon.

Verification at Maintenance

Kailangan ng maintenance ang mga ground truth. Sinusubaybayan namin:

last_verified: Kailan may nagkumpirma na may bisa pa rin ang pahayag
evidence: Mga file na nagpapatunay sa pahayag (puwedeng ma-check kung umiiral)
source: Saan nagmula ang katotohanan (CLI inspection, architecture review, post-incident learning)

Ang isang ground truth na may lumang verification date o sirang evidence link, isang senyales na dapat imbestigahan. Alinman, may bisa pa rin ang katotohanan at kailangan lang ng re-verification, o nagbago na ang realidad at kailangang i-update ang katotohanan.

Mga Tunay na Halimbawa Mula sa Production

Hangganan ng seguridad

- 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.

Pinipigilan ng ground truth na ito ang isang klase ng maling-akalang “security improvements” na sisira sa produkto.

Katumpakan sa oras ng extraction

- 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.

Nagmula ito sa masakit na karanasan. Nagta-tapal ang mga agent ng mga nabibigong language pack sa pamamagitan ng pagdagdag ng validator-only na filter na nagpapaganda lang sa itsura ng test harness, habang ang live Maguyva extractor ay tuloy pa ring naglalabas ng maling edges. Pinipilit ng tuntunin na ibalik ang mga fix sa totoong path: YAML config, queries, o handlers.

Multi-tier na pagsala

- 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).

Pinipigilan nito ang mga agent na magdagdag ng filter sa maling lugar, isang karaniwang pagkakamali na nagdulot ng accuracy regressions.

Integration sa Orchestration System

Isang layer lang ang ground truths sa mas malawak na context system:

Mga desisyon sa arkitektura (ADRs) - Naitatala kung bakit pinili ang approach A kaysa sa B
Mga batayang katotohanan - Sinasabi kung ano ang tiyak na totoo ngayon
Domain Patterns - Inilalarawan kung paano gawin nang tama ang mga bagay
Anti-Patterns - Inilalarawan kung ano ang iwasan at bakit

May access ang isang agent na nagtatrabaho sa system sa lahat ng apat. Ang ground truths ang nagbibigay ng factual anchor, habang ipinapaliwanag ng mga desisyon ang kasaysayan, ginagabayan ng mga pattern ang implementation, at binababalaan ng mga anti-pattern ang mga posibleng patibong.

Pagsukat ng Impact

Mula nang ipinakilala ang ground truths, naobserbahan namin:

Mas kaunting “ayusin ang hinallucinate na fix” na cycle
Mas confident na desisyon ng agent kapag malinaw ang mga katotohanan
Mas magandang PR review dahil explicit ang mga inaasahan
Mas maikling onboarding time para sa mga bagong agent (at mga tao)

May pakinabang ang investment sa pagpapanatili ng ground truths sa pamamagitan ng mas kaunting debugging at mas malinaw na system boundaries.

Pagsisimula

Para magdagdag ng ground truth sa system mo:

Gumawa ng ground_truths.yaml sa loob ng directory ng package mo na ai_assets/reference/
I-define ang metadata at render configuration
Magdagdag ng mga pahayag na sumusunod sa schema
Patakbuhin ang uv run orkestra sync para bumuo ng documentation
Isama ang registry sa agent context composition

Simulan sa mga katotohanan na nagdudulot ng pinakamaraming kalituhan o sa mga hangganan na pinakamadalas nilalabag. Iyon ang mga pinakamahalagang ground truth mo.

Konklusyon

Mag-hahallucinate ang mga AI agent. Iyon ang kalikasan nila. Pero puwede kaming gumawa ng mga environment kung saan pinaghihigpitan ang hallucination, kung saan hindi puwedeng balewalain ang ilang katotohanan, kung saan puwedeng i-check ng mga agent ang mga assumption nila laban sa napatunayang realidad.

Hindi kumpletong solusyon ang ground truths. Kailangan nila ng maintenance. Puwede silang maging luma. Nagdaragdag sila ng overhead sa development process.

Pero nagbibigay sila ng mahalagang bagay: isang shared vocabulary ng mga katotohanan na puwedeng pagkatiwalaan ng parehong tao at agent. Sa isang mundo kung saan lalo nang sumasali ang mga agent sa software development, nagiging mahalaga ang shared foundation na iyon.

Ang alternatibo, walang katapusang cycle ng mga agent na confidenteng nagkakamali at mga taong nagtatama nito. Sinisira ng ground truths ang cycle na iyon sa pamamagitan ng paggawang explicit at matatag sa mga pagwawasto.

Karapat-dapat malaman ng mga agent mo kung ano ang totoo. Sabihin mo sa kanila.

Orkestra: Pag-orchestrate ng mga AI Agent sa Malaking Sukat

Tue, 06 Jan 2026 00:00:00 GMT

Ang mga numero sa post na ito ay sumasalamin sa system noong publication (Enero 2026). Tingnan ang aming team page para sa kasalukuyang mga figure.

Nang magsimula kaming bumuo gamit ang Claude Code, nadatnan namin ang isang problema na kalaunan ay haharapin ng bawat team na gumagamit ng AI coding assistant: hindi kayang gawin nang mahusay ng isang solong agent ang lahat.

Puwede mong i-prompt ang isang agent na maging database specialist. O security auditor. O frontend engineer. Pero sa sandaling hilingin mong maging lahat ng tatlo nang sabay, humihina ang kalidad. Nadi-dilute ang context. Nagkakabanggaan ang mga instruction. Ang agent, nagiging isang generalist na katamtaman lang sa lahat.

Kaya gumawa kami ng Orkestra.

Ano ang Orkestra?

Ang Orkestra ay isang agent orchestration system para sa Claude Code at katulad na AI coding tools. Kino-coordinate nito ang maraming specialized na agent, bawat isa may natatanging expertise, sa ilalim ng iisang orchestrator na nag-ruruta ng trabaho papunta sa tamang specialist.

Isipin mo itong parang staffing agency para sa mga AI agent. Tumatanggap ang orchestrator ng isang task, kinikilala kung aling specialist ang dapat humawak nito, at ini-delegate ito nang may tamang context. Kapag tapos na ang trabaho, dumadaloy pabalik ang mga resulta sa orchestrator para sa synthesis.

Sinasabi ng mga numero ang kwento:

Bahagi	Bilang
Mga specialist agent	46
Reusable na mga skill	466
Mga identity archetype	27
Mga mindset	11
Mga estilo ng komunikasyon	10
Mga knowledge domain	21

Ang Character System: D&D para sa mga Agent

Ang core insight sa likod ng Orkestra, umuusbong ang agent behavior mula sa tatlong composable na primitive:

Tinutukoy ng Identity kung ano ang agent. Nagdi-disenyo ng system structures ang isang architect. Sinusubaybayan ng isang debugger ang mga kabiguan hanggang sa root cause nito. Ipinapatupad ng isang guardian ang compliance at security boundaries. May 27 kaming identity archetype na puwedeng pagsamahin.

Tinutukoy ng Mindset kung paano nag-iisip ang agent. Ini-anchor ng isang analytical na mindset ang mga assertion sa ebidensya at kinukwantipika nito ang uncertainty. Kinukwestyon ng isang skeptical na mindset ang mga assumption at naghahanap ng disconfirming na ebidensya. Yakap ng isang exploratory na mindset ang ambiguity at sinusubukan ang maraming approach.

Tinutukoy ng Style kung paano nakikipag-usap ang agent. May kasamang eksaktong values at nag-re-reference ng specific na mga file ang isang technical na style. Inaalis ng concise na style ang paligoy-ligoy at inuuna ang sagot. Tinitimbang ng isang diplomatic na style ang katapatan kasama ng tact.

Pinagsasama ng isang agent ang mga primitive na ito:

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

Gumagawa ang composition na ito ng isang agent na nagdi-disenyo ng systems (architect), nag-uugnay ng kaalaman sa iba’t ibang domain (knowledge-architect), nagtatakda ng strategic direction (strategist), nag-iisip sa ebidensya at data (analytical), at nakikipag-usap nang walang fluff (concise).

Nasa combinatorial explosion ang lakas. Ang 27 identity beses 11 mindset beses 10 style, nagbubunga ng halos 3,000 posibleng agent personality. Pero ang mga combination lang na mahalaga sa trabaho mo ang ide-define mo.

Skills: Reusable na mga Capability Module

Ang skills ang kaalaman at workflow na puwedeng gamitin ng mga agent. Sumusunod sila sa isang tiered system batay sa scope:

Tier	Pangalan	Scope	Halimbawa
K0	Mga pundasyon	Universal na methodology	Disiplinang test-first, pagkumpleto batay sa ebidensya
K1	Mga identity	Role-based na workflow	CLI interface standard, performance playbook
K2	Mga domain	Domain-specific na kaalaman	Pattern ng database migration, validation ng authentication
K3	Mga stack	Specific sa teknolohiya	Cloudflare deployment, operasyon sa Supabase
K4	Proyekto	Ang codebase na ito lang	Workflow at convention na specific sa proyekto

Lazy-loaded ang mga skill. Nakikita ng isang agent ang mga pangalan at deskripsyon ng skill sa startup, pero nagloload lang ang buong laman ng skill kapag na-trigger. Pinapanatili nitong lean ang context habang ginagawang discoverable ang daan-daang skill.

Kasama sa bawat skill:

Malinaw na trigger conditions (“Gamitin kapag nag-mimigrate ng database schema”)
Step-by-step na gabay
Mga allowed tool para sa workflow
Success criteria at failure recovery paths

Sinasaklaw ng 466 skill sa registry namin ang lahat mula sa git worktree isolation hanggang sa web research workflows hanggang sa deployment health validation.

Bakit Mahalaga ang Orchestration

Mabilis na tumatama sa pader ang single-agent architectures:

Context dilution. Mukhang malaki ang isang 200k token context window hangga’t hindi mo na-load ang mga database schema, API docs, test fixtures, at domain knowledge. Puwedeng magtrabaho ang mga specialist gamit ang targeted na context.

Salungatan sa instruction. Ang pagsabi sa isang agent na “maging thorough pero mabilis” at “i-verify ang lahat pero huwag mag-over-engineer” ay gumagawa ng tension. Sinosolusyunan ito ng mga specialist sa pamamagitan ng pagkakaroon ng malinaw na scope.

Lalim ng expertise. Kaunti lang ang alam ng isang generalist agent tungkol sa lahat. Malalim naman ang alam ng isang specialist agent, na naka-compose gamit ang tamang identity at skills, tungkol sa domain nito.

Nagpapatupad ang Orkestra ng flat orchestration: isang orchestrator ang nagko-coordinate ng maraming specialist. Hindi puwedeng gumawa ng sub-specialist ang mga specialist. Pinipigilan nito ang complexity explosion habang binibigyang-daan ang parallel na trabaho.

May access ang orchestrator sa 2.2 milyong token ng effective capacity: ang sarili nitong 200k window dagdag pa ang 10 concurrent na subagent na may 200k bawat isa. Komportableng tumatakbo sa buong fleet ang trabahong magpapaubos sa isang solong agent.

Ang Rendering Pipeline

Nakatira sa YAML ang mga agent definition. Binabasa ng Claude Code ang Markdown. Ini-bridge ng Orkestra ang puwang na ito gamit ang isang deterministic na rendering pipeline:

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

Ini-edit ng mga operator ang YAML source. Patakbuhin ang orkestra sync. Lumalabas ang rendered Markdown sa .claude/agents/. Kinukuha ng Claude Code ang mga pagbabago.

Ang paghihiwalay na ito, naglilingkod sa iba’t ibang audience:

Kasama sa YAML source ang lifecycle metadata, tags, validation rules, at deprecation notes para sa tooling
Kasama lang sa Rendered Markdown ang kailangan ng model: description, tools, skills, at behavioral guidance

Kino-compose ng pipeline ang mga identity, mindset, style, at skills papunta sa iisang coherent na prompt. Napakaiba ang system prompt ng isang architect-analytical-concise na agent kumpara sa isang debugger-skeptical-technical na agent, kahit magkapareho sila ng ilang underlying na skills.

Domain Knowledge: Ang Four-File Pattern

Sumusunod ang bawat knowledge domain sa isang consistent na structure:

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

Naglilingkod ang structure na ito sa agent context loading. Nagloload ang isang agent na nagtatrabaho sa authentication ng authentication/patterns.md para sa gabay at authentication/anti-patterns.md para maiwasan ang mga kilalang patibong. Ang mga file, sinukat para sa efficient na context loading: focused nang sapat para maging kapaki-pakinabang, comprehensive nang sapat para maging authoritative.

Pinapanatili namin ang 21 top-level na domain kasama ang analytics, authentication, agham ng datos, infrastructure, machine learning, performance, security, at marami pang iba. Puwedeng magkaroon ng sub-domain ang bawat domain para sa mas mainam na granularity.

Values: Ang Operating System

Nagbabahagi ang lahat ng agent ng isang base layer ng values na tumutukoy kung paano sila gumagana:

Unahin ang pagiging simple. Gamitin ang pinakasimpleng solusyon na gumagana. Magdagdag ng complexity lang kapag may dahilan.

Ayusin ang ugat ng problema. Huwag basta takpan ng pansamantalang solusyon ang mga problema. Kung nabigo ang isang pipeline, i-debug ang pipeline. Kung nabigo ang isang test, ayusin ang code o ang test.

Evidence-based. I-label ang mga claim bilang “verified” (may benchmarks) o “estimated” (may assumptions). Hindi katumbas ng nakumpirmang problema ang isang na-detect na pattern.

Context economics. 0.1% ng context ang halaga ng mga MCP tool. 2% bawat isa ang halaga ng file reads. Ilapat ang domain expertise bago mag-explore ng code.

Kumakalat ang mga values na ito sa bawat specialist sa pamamagitan ng rendering pipeline. Hindi ito puwedeng balewalain ng isang agent sa pamamagitan ng composition.

CLI: Ang Control Plane

Dumarating ang Orkestra kasama ng isang CLI para sa pamamahala ng agent ecosystem:

# 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"

Ang CLI ang source of truth kung anong mga agent ang umiiral, anong mga skill ang meron sila, at kung malusog ba ang system. Nagpapatakbo ito ng validation bago mag-sync para mahuli nang maaga ang mga problema.

Mga Konsiderasyon sa Open Source

Ginawa namin ang Orkestra para solusyunan ang sarili naming problema: pag-coordinate ng mga AI agent sa malaking sukat para sa isang komplikadong codebase. Ang mga pattern na natuklasan namin, hindi eksklusibo sa domain namin.

Ang character composition system (identity + mindset + style) ay umaapply sa anumang team na nagde-define ng agent personalities.

Nagbibigay ang skill tier system (K0-K4) ng mental model para sa pag-organisa ng reusable na capabilities ayon sa scope.

Ang rendering pipeline pattern (YAML source + templates + generated artifacts) ay naghihiwalay ng mga concern sa pagitan ng tooling at model consumption.

Iniiwasan ng flat orchestration model (isang coordinator, maraming specialist) ang complexity habang binibigyang-daan ang parallelism.

Ang kung magiging open source man ang Orkestra, nakadepende sa kung may value ba ang mga pattern na ito para sa iba na bumubuo gamit ang Claude Code. Kung tumatama ka sa mga pader na inilarawan namin, puwedeng makatulong ang architecture.

Ano ang Natutunan Namin

Itinuro sa amin ng pagbuo ng Orkestra na hindi tungkol sa paggawang mas matalino ng mga agent ang orchestration. Ito ay tungkol sa paggawa sa kanila na mas focused.

Isang solong agent na may perpektong instruction, uubusin pa rin ang context nito. Isang solong agent na may lahat ng skills, malilito pa rin kung alin ang ilalapat. Isang solong agent na sinusubukang maging lahat, gumagawa ng katamtamang resulta kahit saan.

Apatnapung specialist, bawat isa mahusay sa sariling domain, kino-coordinate ng isang orchestrator na alam kung kailan mag-delegate: ganoon kami nagship.

Hindi kasing halaga ng architecture ang mga numero. Baka limang agent lang ang kailangan mo o limampu. Nananatili ang prinsipyo: composition higit sa capability, specialization higit sa generalization, coordination higit sa individual heroics.

Pinapatakbo ng Orkestra ang agent ecosystem sa likod ng Maguyva, ang code intelligence platform namin. Gustong matuto pa? Makipag-ugnayan sa team.