Rekayasa harness: nggunakke Codex ing donya sing agent-first

Sajrone limang wulan kepungkur, tim kita wis nglakokake eksperimen: mbangun lan ngrilis beta internal saka produk piranti lunak kanthi 0 baris kode sing ditulis manual.

Produk iki nduweni pangguna internal saben dina lan penguji alfa eksternal. Iku dirilis, di-deploy, rusak, lan didandani. Sing beda yaiku saben baris kode—logika aplikasi, tes, konfigurasi CI, dokumentasi, observabilitas, lan tooling internal—ditulis dening Codex. Perkiraan kita, iki bisa dibangun mung watara 1/10 wektu dibandhing nulis kode kanthi tangan.

Manungsa ngarahake. Agen nglakokake.

Kita sengaja milih watesan iki supaya mbangun apa sing dibutuhake kanggo nambah kacepetan rekayasa nganti pirang-pirang orde magnitudo. Kita mung nduweni sawetara minggu kanggo ngrilis sing pungkasane dadi sejuta baris kode. Kanggo nindakake kuwi, kita kudu mangerteni apa sing owah nalika tugas utama tim rekayasa piranti lunak ora maneh nulis kode, nanging ngrancang lingkungan, nemtokake maksud, lan mbangun loop umpan balik sing ngidini agen Codex nindakake pakaryan sing andal.

Kiriman iki babagan apa sing kita sinaoni kanthi mbangun produk anyar saka nol nganggo tim agen—apa sing rusak, apa sing ngasilake efek gandha, lan carane ngoptimalake siji sumber daya sing pancen langka: wektu lan perhatian manungsa.

Commit pisanan menyang gudang kode kosong mlebu ing pungkasan Agustus 2025.

Scaffold awal—struktur gudang kode, konfigurasi CI, aturan formatting, setelan manajer paket, lan framework aplikasi—digawe dening Codex CLI nggunakake GPT‑5, dipandu dening sakelompok cilik cithakan sing wis ana. Malah berkas AGENTS.md awal sing ngarahake agen carane kerja ing gudang kode kuwi dhewe uga ditulis dening Codex.

Ora ana kode sing ditulis manungsa sadurunge kanggo dadi jangkar sistem. Wiwit awal, gudang kode iki diwujudake dening agen.

Lima wulan mengko, gudang kode iki ngemot kira-kira sejuta baris kode sing nyakup logika aplikasi, infrastruktur, tooling, dokumentasi, lan piranti pengembang internal. Sajrone periode kuwi, kurang luwih 1.500 panyuwunan tarik wis dibukak lan digabungake kanthi tim cilik mung telung insinyur sing ngarahake Codex. Iki padha karo rata-rata kapasitas pangolahan 3,5 PR saben insinyur saben dina, lan sing nggumunake kapasitas pangolahan iki malah mundhak nalika tim tuwuh dadi pitung insinyur. Sing penting, iki dudu output mung demi output: produk iki wis digunakake atusan pangguna internal, kalebu pangguna internal intensif saben dina.

Sajrone proses pangembangan, manungsa ora tau nyumbang kode kanthi langsung. Iki dadi filosofi inti tim: ora ana kode sing ditulis manual.

Ora anane coding langsung dening manungsa nggawa jinis pakaryan rekayasa sing beda, fokus ing sistem, scaffold, lan daya ungkit.

Kemajuan awal luwih alon tinimbang sing diarepake, dudu amarga Codex ora mampu, nanging amarga lingkungane kurang ditemtokake. Agen kekurangan alat, abstraksi, lan struktur internal sing dibutuhake kanggo maju menyang tujuan tingkat dhuwur. Tugas utama tim rekayasa kita dadi ngidini para agen nindakake pakaryan sing migunani.

Ing praktik, iki tegesé kerja kanthi depth-first: mecah tujuan gedhe dadi blok bangunan luwih cilik (desain, kode, review, tes, lsp), menehi prompt marang agen kanggo mbangun blok-blok kuwi, lan nggunakke kanggo mbukak tugas sing luwih kompleks. Nalika ana sing gagal, perbaikane meh ora tau mung “nyoba luwih keras.” Amarga siji-sijine cara kanggo maju yaiku njaluk Codex nindakake pakaryane, insinyur manungsa mesthi mlebu menyang tugas lan takon: “kapabilitas apa sing kurang, lan kepiye carane supaya bisa diwaca lan ditegakake kanggo agen?”

Manungsa sesambungan karo sistem meh sakabehe liwat prompt: insinyur njlentrehake tugas, mbukak agen, lan ngidini agen mbukak panyuwunan tarik. Kanggo nggawa PR nganti rampung, kita mrentah Codex supaya mriksa owah-owahane dhewe sacara lokal, njaluk review agen tambahan sing spesifik loro-lorone lokal lan ing cloud, nanggapi umpan balik saka manungsa utawa agen, lan ngiterasi ing loop nganti kabeh reviewer agen wareg (sakjane iki yaiku Ralph Wiggum Loop⁠(mbukak ing jendhela anyar)). Codex nggunakke piranti pangembangan standar kita kanthi langsung (gh, skrip lokal, lan skills sing ditempel ing gudang kode) kanggo nglumpukake konteks tanpa manungsa nyalin-tempel menyang CLI.

Manungsa bisa mriksa panyuwunan tarik, nanging ora wajib. Suwe-suwe, kita wis nggeser meh kabeh usaha review supaya ditangani agen-karo-agen.

Nalika kapasitas pangolahan kode mundhak, bottleneck kita dadi kapasitas QA manungsa. Amarga watesan tetep yaiku wektu lan perhatian manungsa, kita nyoba nambah luwih akeh kapabilitas marang agen kanthi nggawe bab kaya UI aplikasi, log, lan metrik aplikasi dadi bisa diwaca langsung dening Codex.

Contone, kita nggawe aplikasi bisa diboot saben git worktree, supaya Codex bisa mbukak lan ngoperasikake siji instans saben owah-owahan. Kita uga nyambungake Chrome DevTools Protocol menyang runtime agen lan nggawe skills kanggo nggarap snapshot DOM, screenshot, lan navigasi. Iki ndadekake Codex bisa ngasilake maneh bug, ngesahake perbaikan, lan nalar prilaku UI kanthi langsung.

Kita nindakake perkara sing padha kanggo tooling observabilitas. Log, metrik, lan trace diekspos menyang Codex liwat stack observabilitas lokal sing sifaté ephemeral kanggo worktree tartamtu. Codex kerja ing versi app sing terisolasi kanthi lengkap—kalebu log lan metriké, sing bakal dibongkar sawise tugas kasebut rampung. Agen bisa ngquery log nganggo LogQL lan metrik nganggo PromQL. Kanthi konteks iki kasedhiya, prompt kaya “pastikake startup layanan rampung kurang saka 800ms” utawa “ora ana span ing papat perjalanan pangguna kritis iki ngluwihi rong detik” dadi bisa ditangani.

Kita kerep ndeleng siji eksekusi Codex nggarap siji tugas nganti luwih saka enem jam (asring nalika manungsa lagi turu).

Manajemen konteks iku salah siji tantangan paling gedhe kanggo nggawe agen efektif ing tugas gedhe lan kompleks. Salah siji pelajaran paling awal sing kita sinaoni kuwi sederhana: wenehana Codex peta, dudu manual instruksi 1.000 kaca.

Kita nyoba pendekatan “siji AGENTS.md⁠(mbukak ing jendhela anyar) gedhe”. Iku gagal kanthi cara sing bisa ditebak:

• Konteks iku sumber daya langka. Berkas instruksi raksasa nggeser tugas, kode, lan dokumen sing relevan—mula agen bisa kelangan kendala penting utawa wiwit ngoptimalake perkara sing salah.
• Kakehan pandhuan dadi ora dadi pandhuan. Nalika kabeh dianggep “penting,” ora ana sing pancen penting. Agen pungkasane mung pattern-matching sacara lokal tinimbang navigasi kanthi sengaja.
• Iku cepet usang. Manual monolitik malih dadi kuburan aturan lawas. Agen ora bisa mbedakake endi sing isih bener, manungsa mandheg ngopeni, lan berkas kuwi alon-alon dadi gangguan sing katon migunani.
• Angel diverifikasi. Siji blob ora cocog kanggo pengecekan mekanis (cakupan, kebaruan, kepemilikan, pranala silang), mula drift ora bisa diendhani.

Dadi tinimbang nganggep AGENTS.md minangka ensiklopedia, kita nganggep iku minangka daftar isi.

Basis pengetahuan gudang kode urip ing direktori docs/ terstruktur sing dianggep minangka system of record. AGENTS.md sing cekak (kurang luwih 100 baris) disuntikake menyang konteks lan utamane dadi peta, kanthi penunjuk menyang sumber kebenaran sing luwih jero ing panggonan liya.

Dokumentasi desain dikatalogake lan diindeks, kalebu status verifikasi lan sakumpulan keyakinan inti sing nemtokake prinsip operasi agent-first. Dokumentasi arsitektur⁠(mbukak ing jendhela anyar) nyedhiyakake peta tingkat ndhuwur babagan domain lan pelapisan paket. Dokumen kualitas menehi nilai saben domain produk lan lapisan arsitektur, nglacak kesenjangan saka wektu ke wektu.

Rencana dianggep minangka artefak kelas siji. Rencana ringan sing ephemeral digunakake kanggo owah-owahan cilik, dene pakaryan kompleks dicathet ing rencana eksekusi⁠(mbukak ing jendhela anyar) karo log kemajuan lan keputusan sing dicheck-in menyang gudang kode. Rencana aktif, rencana rampung, lan utang teknis sing wis dingerteni kabeh diversi lan dipasang bebarengan, ngidini agen beroperasi tanpa gumantung konteks eksternal.

Iki ndadekake pengungkapan progresif: agen miwiti saka titik mlebu sing cilik lan stabil lan diwulang kudu ndeleng menyang endi sabanjure, tinimbang langsung kewalahan ing ngarep.

Kita ngetrapake iki kanthi mekanis. Linter khusus lan job CI ngvalidasi manawa basis pengetahuan tetep anyar, saling-terhubung, lan terstruktur kanthi bener. Agen “doc-gardening” sing mlaku berkala mindhai dokumentasi lawas utawa usang sing ora nggambarake prilaku kode nyata lan mbukak panyuwunan tarik perbaikan.

Nalika codebase berkembang, kerangka Codex kanggo keputusan desain uga kudu berkembang.

Amarga gudang kode iki kabeh diasilake agen, optimisasine utamane kanggo keterbacaan Codex. Kaya tim sing ngupaya ningkatake kemudahan navigasi kode kanggo rekrutan insinyur anyar, tujuan insinyur manungsa kita yaiku nggawe agen bisa nalar babagan domain bisnis sakabehe langsung saka gudang kode kasebut dhewe.

Saka sudut pandang agen, apa wae sing ora bisa diakses ing konteks nalika mlaku, kanthi efektif ora ana. Pengetahuan sing urip ing Google Docs, utas obrolan, utawa ing sirah wong ora bisa diakses sistem. Artefak lokal-gudang-kode sing diversi (umpamane kode, markdown, skema, rencana eksekusi) iku kabeh sing bisa dideleng.

Kita sinau manawa suwe-suwe kita kudu nyurung konteks saya akeh menyang repo. Diskusi Slack sing nyelarasake tim babagan pola arsitektur kuwi? Yen ora bisa ditemokake dening agen, iku ora bisa diwaca kanthi cara sing padha kaya ora dingerteni dening pegawai anyar sing gabung telung wulan mengko.

Menehi Codex konteks luwih akeh tegesé ngatur lan mbabarake informasi sing pas supaya agen bisa nalar saka kono, dudu mbebayani kanthi instruksi ad-hoc sing numpuk. Kaya nalika sampeyan onboarding kanca tim anyar babagan prinsip produk, norma rekayasa, lan budaya tim (kalebu preferensi emoji), menehi informasi iki marang agen ngasilake output sing luwih selaras.

Framing iki njlentrehake akeh tradeoff. Kita luwih milih dependensi lan abstraksi sing bisa diinternalisasi lan dipahami kanthi lengkap ing repo. Teknologi sing asring diarani “mboseni” cenderung luwih gampang dimodelake agen amarga composability, stabilitas api, lan keterwakilan ing training set. Ing sawetara kasus, luwih murah yen agen ngetrapake maneh subbagian fungsionalitas tinimbang kudu muteri prilaku upstream saka pustaka publik sing opaque. Contone, tinimbang narik paket gaya p-limit generik, kita ngetrapake helper map-with-concurrency dhewe: iki terintegrasi rapet karo instrumentasi OpenTelemetry kita, nduweni cakupan tes 100%, lan prilakune persis kaya sing diarepake runtime kita.

Narik luwih akeh sistem menyang wangun sing bisa dipriksa, divalidasi, lan diowahi langsung dening agen nambah daya ungkit—ora mung kanggo Codex, nanging uga kanggo agen liya (umpamane Aardvark) sing uga nggarap codebase iki.

Dokumentasi wae ora cukup kanggo njaga codebase sing kabeh diasilake agen tetep koheren. Kanthi negakake invariant, dudu micromanage implementasi, kita ngidini agen ngirim cepet tanpa ngrusak pondhasi. Contone, kita nuntut Codex supaya parse wujud data ing wates⁠(mbukak ing jendhela anyar), nanging ora preskriptif babagan kepiye carane kuwi kelakon (model katon seneng Zod, nanging kita ora nemtokake pustaka kuwi kanthi spesifik).

Agen paling efektif ing lingkungan kanthi wates sing ketat lan struktur sing bisa diprediksi⁠(mbukak ing jendhela anyar), mula kita mbangun aplikasi ngubengi model arsitektur sing kaku. Saben domain bisnis dipérang dadi sakumpulan lapisan tetep, kanthi arah dependensi sing divalidasi kanthi ketat lan sakumpulan edge sing diidini sing winates. Kendala iki ditegakake kanthi mekanis liwat linter kustom (asil Codex uga, mesthi!) lan tes struktural.

Diagram ing ngisor nuduhake aturane: ing saben domain bisnis (umpamane App Settings), kode mung bisa gumantung “maju” liwat sakumpulan lapisan tetep (Types → Config → Repo → Service → Runtime → UI). Kekuwatan lintas-pemotong (auth, connectors, telemetry, feature flags) mlebu liwat siji antarmuka eksplisit: Providers. Saliyane kuwi ora diidini lan ditegakake kanthi mekanis.

Iki jinis arsitektur sing biasane ditundha nganti sampeyan nduweni atusan insinyur. Kanthi agen coding, iki dadi prasyarat awal: kendala-kendala iki sing ngidini kacepetan tanpa pembusukan utawa drift arsitektur.

Ing praktik, kita negakake aturan iki nganggo linter kustom lan tes struktural, plus sakelompok cilik “invariant selera.” Contone, kita kanthi statis negakake logging terstruktur, konvensi penamaan kanggo skema lan tipe, wates ukuran berkas, lan syarat keandalan khusus platform nganggo lint kustom. Amarga lint iki kustom, kita nulis pesen kesalahane supaya nyuntikake instruksi remediasi menyang konteks agen.

Ing alur kerja sing human-first, aturan iki bisa krasa cerewet utawa mbatesi. Kanthi agen, aturan iki dadi pengali: yen wis dienkode, kabeh langsung berlaku ing endi wae.

Ing wektu sing padha, kita terang-terangan babagan ing endi kendala iku penting lan ing endi ora. Iki mirip mimpin organisasi platform rekayasa gedhe: tegakake wates kanthi terpusat, paring otonomi sacara lokal. Sampeyan peduli banget marang wates, ketepatan, lan reproduksibilitas. Ing njero wates kuwi, sampeyan ngidini tim—utawa agen—kebebasan sing cukup gedhe babagan cara solusi diungkapake.

Kode sing diasilake ora tansah cocog karo preferensi stilistika manungsa, lan kuwi ora apa-apa. Sajrone outpute bener, bisa dirawat, lan bisa diwaca dening eksekusi agen ing mangsa ngarep, iku wis nyukupi standar.

Selera manungsa diparingake bali menyang sistem kanthi terus-terusan. Komentar review, panyuwunan tarik refactoring, lan bug sing katon pangguna dicathet dadi update dokumentasi utawa dienkode langsung menyang tooling. Nalika dokumentasi kurang cukup, kita ngunggahake aturan kuwi dadi kode

Nalika kapasitas pangolahan Codex mundhak, akeh norma rekayasa konvensional dadi kontraproduktif.

Repo beroperasi kanthi gerbang merge pemblokiran minimal. Panyuwunan tarik umuré cekak. Flake tes asring ditangani nganggo eksekusi tindak lanjut tinimbang ngalangi kemajuan tanpa wates. Ing sistem nalika kapasitas pangolahan agen ngluwihi perhatian manungsa, koreksi kuwi murah, lan ngenteni kuwi larang.

Iki bakal ora tanggung jawab ing lingkungan kapasitas pangolahan rendah. Ing kene, asring dadi tradeoff sing bener.

Nalika kita ngomong codebase iki diasilake agen Codex, maksude kabeh sing ana ing codebase.

Agen ngasilake:

• Kode produk lan tes
• Konfigurasi CI lan tooling rilis
• Piranti pengembang internal
• Dokumentasi lan sejarah desain
• Harness evaluasi
• Komentar review lan tanggapan
• Skrip sing ngatur repo dhewe
• Berkas definisi dashboard produksi

Manungsa tansah tetep ana ing loop, nanging kerja ing lapisan abstraksi sing beda tinimbang biyen. Kita memprioritasekake kerja, nerjemahake umpan balik pangguna dadi kriteria panriman, lan ngesahake asil. Nalika agen kesulitan, kita nganggep kuwi minangka sinyal: ngenali apa sing kurang—alat, guardrail, dokumentasi—lan ngetokake maneh menyang repo, tansah kanthi cara Codex dhewe sing nulis perbaikane.

Agen nggunakke piranti pangembangan standar kita kanthi langsung. Dheweke narik umpan balik review, nanggapi inline, nyurung update, lan asring squash lan merge panyuwunan tarik dhewe.

Nalika luwih akeh loop pangembangan dienkode langsung menyang sistem—testing, validasi, review, penanganan umpan balik, lan pemulihan—repo iki bubar ngliwati ambang penting ing ngendi Codex bisa nyopir fitur anyar saka ujung nganti ujung.

Kanthi siji prompt, agen saiki bisa:

• Ngesahake kahanan codebase saiki
• Nggawé ulang bug sing dilapurake
• Ngrekam video sing nduduhake kegagalan
• Ngetrapake perbaikan
• Ngesahake perbaikan kanthi ngoperasikake aplikasi
• Ngrekam video kapindho sing nduduhake resolusi
• Mbukak panyuwunan tarik
• Nanggapi umpan balik agen lan manungsa
• Ndeteksi lan ndandani kegagalan build
• Ngeskalasi menyang manungsa mung nalika dibutuhake penilaian
• Nggabungake owah-owahan

Prilaku iki gumantung banget marang struktur lan tooling khusus repo iki lan ora kena dianggep bakal umum tanpa investasi sing padha—paling ora, durung saiki.

Otonomi agen penuh uga ngenalake masalah anyar. Codex nggandakake pola sing wis ana ing repo—kalebu sing ora rata utawa kurang optimal. Suwe-suwe, iki mesthi nuntun marang drift.

Ing wiwitan, manungsa nangani iki kanthi manual. Tim kita biyen ngentekake saben Jumat (20% saka minggu kerja) kanggo ngresiki “AI slop.” Ora nggumunake, kuwi ora bisa diskalakake.

Nanging, kita wiwit ngodekake apa sing diarani “prinsip emas” langsung menyang repo lan mbangun proses resik-resik sing berulang. Prinsip iki yaiku aturan mekanis sing duwe pendapat cetha lan njaga codebase tetep bisa diwaca lan konsisten kanggo eksekusi agen ing mangsa ngarep. Contone: (1) kita luwih milih paket utilitas bebarengan tinimbang helper gaweyan tangan supaya invariant tetep terpusat, lan (2) kita ora mriksa data kanthi “gaya YOLO”—kita ngesahake wates utawa ngandelake SDK bertipe supaya agen ora sengaja mbangun ing ndhuwur bentuk sing mung dikira-kira. Kanthi cadence rutin, kita nduweni sakelompok tugas Codex latar mburi sing mindhai penyimpangan, nganyari nilai kualitas, lan mbukak panyuwunan tarik refactoring sing ditargetake. Akeh saka iki bisa direview kurang saka semenit lan di-automerge.

Iki fungsine kaya garbage collection. Utang teknis kuwi kaya utangan bunga dhuwur: meh tansah luwih apik yen dibayar mudhun terus-terusan kanthi tambahan cilik tinimbang dibiarke ngembang lan ditangani kanthi letupan sing nglarani. Selera manungsa dijupuk sepisan, banjur ditegakake terus ing saben baris kode. Iki uga ngidini kita nyekel lan ngrampungake pola ala saben dina, tinimbang mbiyarke nyebar ing codebase sajrone dina utawa minggu.

Strategi iki nganti saiki bisa mlaku apik nganti peluncuran lan adopsi internal ing OpenAI. Mbangun produk nyata kanggo pangguna nyata mbantu njangkar investasi kita ing kasunyatan lan nuntun kita menyang kemudahan pangopènan jangka panjang.

Sing durung kita mangerteni yaiku carane koherensi arsitektur berkembang sajrone pirang-pirang taun ing sistem sing kabeh diasilake agen. Kita isih sinau ing endi penilaian manungsa nambah daya ungkit paling gedhe lan carane ngodekake penilaian kuwi supaya ngasilake efek gandha. Kita uga durung ngerti carane sistem iki bakal berkembang nalika model terus dadi luwih mumpuni saka wektu ke wektu.

Sing dadi cetha: mbangun piranti lunak isih nuntut disiplin, nanging disiplin kuwi luwih katon ing scaffold tinimbang ing kode. Tooling, abstraksi, lan loop umpan balik sing njaga codebase tetep koheren dadi saya penting.

Tantangan paling angel saiki pusaté ing ngrancang lingkungan, loop umpan balik, lan sistem kontrol sing mbantu agen ngrampungake tujuan kita: mbangun lan njaga piranti lunak kompleks sing andal ing skala gedhe.

Nalika agen kaya Codex njupuk porsi luwih gedhe saka siklus urip piranti lunak, pitakonan iki bakal saya penting. Kita ngarep manawa kanthi nuduhake sawetara pelajaran awal bisa mbantu sampeyan nalar babagan ing endi kudu nandur upaya supaya sampeyan bisa mung mbangun barang.