Kejuruteraan rangka: Codex dalam dunia berteraskan ejen

Sepanjang lima bulan yang lalu, pasukan kami telah menjalankan satu eksperimen: membina dan menghantar beta dalaman bagi sebuah produk perisian dengan 0 baris kod yang ditulis secara manual.

Produk ini mempunyai pengguna harian dalaman dan penguji alfa luaran. Ia dihantar, dikerahkan, rosak, dan dibaiki. Apa yang berbeza ialah setiap baris kod—logik aplikasi, ujian, konfigurasi CI, dokumentasi, kebolehlihatan, dan alat dalaman—telah ditulis oleh Codex. Kami menganggarkan bahawa kami membina ini dalam kira-kira 1/10 masa yang diperlukan untuk menulis kod itu secara manual.

Manusia mengemudi. Ejen melaksanakan tugas.

Kami sengaja memilih kekangan ini supaya kami dapat membina apa yang perlu untuk meningkatkan kelajuan kejuruteraan dengan pesat. Kami mempunyai beberapa minggu untuk menghantar apa yang akhirnya menjadi sejuta baris kod. Untuk melakukan perkara tersebut, kami perlu memahami apa yang berubah apabila tugas utama pasukan kejuruteraan perisian bukan lagi menulis kod, tetapi mereka bentuk persekitaran, menetapkan niat, dan membina gelung maklum balas yang membolehkan ejen Codex melakukan kerja yang boleh dipercayai.

Catatan ini adalah tentang apa yang kami pelajari dengan membina produk baharu sepenuhnya bersama pasukan ejen—apa yang rosak, apa yang bertambah rumit, dan bagaimana memaksimumkan satu-satunya sumber kami yang benar-benar terhad: masa dan perhatian manusia.

Komit pertama ke repositori kosong dilakukan pada akhir Ogos 2025.

Perancah awal—struktur repositori, konfigurasi CI, peraturan pemformatan, persediaan pengurus pakej, dan rangka kerja aplikasi—telah dijana oleh Codex CLI menggunakan GPT‑5, dipandu oleh satu set kecil templat sedia ada. Malah, fail AGENTS.md terawal yang mengarahkan ejen tentang cara bekerja dalam repositori itu sendiri ditulis oleh Codex.

Tiada kod sedia ada yang ditulis oleh manusia untuk menjadi penanda aras kepada sistem. Sejak awal, repositori itu dibentuk oleh ejen.

Lima bulan kemudian, repositori mengandungi sekitar sejuta baris kod yang meliputi logik aplikasi, infrastruktur, alat, dokumentasi, dan utiliti pembangun dalaman. Sepanjang tempoh itu, kira-kira 1,500 pull request telah dibuka dan dicantumkan oleh pasukan kecil yang terdiri daripada hanya tiga jurutera yang memacu Codex. Ini diterjemahkan kepada purata daya pemprosesan sebanyak 3.5 PRs bagi setiap jurutera setiap hari, dan yang mengejutkan, daya pemprosesan telah meningkat apabila pasukan telah berkembang kepada tujuh jurutera. Yang penting, ini bukan output demi output semata-mata: produk ini telah digunakan oleh ratusan pengguna secara dalaman, termasuk pengguna mahir dalaman yang menggunakannya setiap hari.

Sepanjang proses pembangunan, manusia tidak pernah secara langsung menyumbang sebarang kod. Ini menjadi falsafah teras untuk pasukan: tiada kod yang ditulis secara manual.

Ketiadaan pengekodan manusia secara langsung memperkenalkan jenis kerja kejuruteraan yang berbeza, yang tertumpu pada sistem, perancah, dan pengaruh.

Kemajuan awal lebih perlahan daripada yang kami jangkakan, bukan kerana Codex tidak mampu, tetapi kerana persekitaran itu tidak ditentukan dengan jelas. Ejen tersebut kekurangan alat, pengabstrakan, dan struktur dalaman yang diperlukan untuk membuat kemajuan ke arah matlamat peringkat tinggi. Tugas utama pasukan kejuruteraan kami adalah untuk membolehkan ejen melakukan kerja yang berguna.

Dalam amalan, ini bermaksud bekerja secara mendalam: memecahkan matlamat yang lebih besar kepada blok binaan yang lebih kecil (reka bentuk, kod, semakan, ujian, dll.), mengarahkan ejen untuk membina blok tersebut, dan menggunakannya untuk membuka kunci tugas yang lebih kompleks. Apabila sesuatu gagal, penyelesaiannya hampir tidak pernah “mencuba lebih keras”. Kerana satu-satunya cara untuk mencapai kemajuan adalah dengan membuat Codex melakukan kerja tersebut, jurutera manusia sentiasa melibatkan diri dalam tugas itu dan bertanya: “Apakah keupayaan yang tiada, dan bagaimana kita menjadikannya mudah difahami dan boleh dikuatkuasakan untuk ejen?”

Manusia berinteraksi dengan sistem hampir sepenuhnya melalui prom: seorang jurutera menerangkan tugas, menjalankan ejen dan membenarkannya membuka "pull request". Untuk menyelesaikan PR, kami mengarahkan Codex untuk menyemak perubahan sendiri secara setempat, meminta semakan tambahan ejen tertentu sama ada secara setempat atau di awan, memberi respons kepada sebarang maklum balas yang diberikan oleh manusia atau ejen dan mengulangi dalam satu gelung sehingga semua ejen penyemak berpuas hati (ini secara efektif adalah Ralph Wiggum Loop⁠(dibuka dalam tetingkap baru)). Codex menggunakan alat pembangunan standard kami secara langsung (gh, skrip tempatan dan kemahiran terbenam dalam repositori) untuk mengumpulkan konteks tanpa manusia menyalin dan menampal ke dalam CLI.

Manusia boleh menyemak pull request, tetapi tidak diwajibkan untuk berbuat demikian. Dari semasa ke semasa, kami telah menumpukan hampir semua usaha semakan kepada pengendalian ejen-ke-ejen.

Apabila daya pemprosesan kod meningkat, halangan kami menjadi kapasiti QA manusia. Oleh kerana kekangan tetap adalah masa dan perhatian manusia, kami telah berusaha untuk menambah lebih banyak keupayaan kepada ejen dengan menjadikan elemen seperti UI aplikasi, log, dan metrik aplikasi itu sendiri boleh dibaca secara langsung oleh Codex.

Sebagai contoh, kami menjadikan aplikasi boleh di but untuk setiap git worktree, supaya Codex boleh melancarkan dan mengendalikan satu instans bagi setiap perubahan. Kami juga menyepadukan Protokol Chrome DevTools ke dalam masa jalan ejen dan mencipta kemahiran untuk bekerja dengan petikan DOM, tangkapan skrin, dan navigasi. Ini membolehkan Codex menghasilkan semula pepijat, mengesahkan pembetulan, dan membuat penaakulan tentang tingkah laku UI secara langsung.

Kami melakukan perkara yang sama untuk alat pemerhatian. Log, metrik, dan jejak didedahkan kepada Codex melalui timbunan pemerhatian tempatan yang bersifat sementara untuk mana-mana worktree tertentu. Codex beroperasi pada versi aplikasi yang terasing sepenuhnya—termasuk log dan metriknya, yang akan dihapuskan sebaik sahaja tugas itu selesai. Ejen boleh membuat pertanyaan pada log menggunakan LogQL dan metrik menggunakan PromQL. Dengan konteks ini tersedia, prom seperti “pastikan permulaan perkhidmatan selesai dalam masa kurang daripada 800ms” atau “tiada rentang dalam empat perjalanan pengguna kritikal ini melebihi dua saat” menjadi lebih mudah dilaksanakan.

Kami kerap melihat satu larian Codex menjalankan satu tugas selama lebih daripada enam jam (sering kali ketika manusia sedang tidur).

Pengurusan konteks adalah salah satu cabaran terbesar dalam menjadikan ejen berkesan untuk tugas-tugas yang besar dan kompleks. Salah satu pelajaran terawal yang kami pelajari adalah mudah: berikan Codex peta, bukan manual arahan setebal 1,000 halaman.

Kami mencuba “satu AGENTS.md⁠(dibuka dalam tetingkap baru) yang besar” pendekatan. Ia gagal dalam cara yang boleh diramalkan:

• Konteks adalah sumber yang terhad. Fail arahan yang besar menenggelamkan tugas, kod, dan dokumen yang berkaitan—jadi ejen sama ada terlepas kekangan utama atau mula mengoptimumkan untuk kekangan yang salah.
• Terlalu banyak panduan menjadi bukan panduan. Apabila segala-galanya “penting”, tiada apa-apa yang penting. Ejen akhirnya membuat padanan corak secara tempatan dan bukannya menavigasi dengan niat.
• Ia reput serta-merta. Manual monolitik menjadi tanah perkuburan peraturan usang. Ejen tidak dapat memastikan apa yang masih benar, manusia berhenti menyelenggarakannya, dan fail itu secara senyap-senyap menjadi gangguan yang menarik.
• Adalah sukar untuk disahkan. Satu blob tunggal tidak sesuai untuk pemeriksaan mekanikal (liputan, kesegaran, pemilikan, pautan silang), jadi penyimpangan tidak dapat dielakkan.

Jadi, daripada menganggap AGENTS.md sebagai ensiklopedia, kami menganggapnya sebagai senarai kandungan.

Pangkalan pengetahuan repositori berada dalam direktori docs/ yang berstruktur dan dianggap sebagai sistem rekod. AGENTS.md yang ringkas (kira-kira 100 baris) dimasukkan ke dalam konteks dan berfungsi terutamanya sebagai peta, dengan petunjuk kepada sumber kebenaran yang lebih mendalam di tempat lain.

Dokumentasi reka bentuk dikatalogkan dan diindeks, termasuk status pengesahan dan satu set kepercayaan teras yang mentakrifkan prinsip operasi yang mengutamakan ejen. Dokumentasi seni bina⁠(dibuka dalam tetingkap baru) menyediakan peta aras tertinggi bagi domain dan lapisan pakej. Dokumen berkualiti menilai setiap domain produk dan lapisan seni bina, menjejaki jurang dari semasa ke semasa.

Rancangan dianggap sebagai artifak kelas pertama. Pelan ringan sementara digunakan untuk perubahan kecil, manakala kerja yang kompleks direkodkan dalam pelan pelaksanaan⁠(dibuka dalam tetingkap baru) dengan log kemajuan dan keputusan yang dimasukkan ke dalam repositori. Pelan aktif, pelan yang telah diselesaikan dan hutang teknikal yang diketahui semuanya diberi versi dan ditempatkan bersama, membolehkan ejen beroperasi tanpa bergantung pada konteks luar.

Ini membolehkan pendedahan progresif: ejen bermula dengan titik masuk yang kecil dan stabil serta diajar di mana untuk melihat seterusnya, bukannya dibebani dari awal.

Kami menguatkuasakan ini secara automatik. Linter khusus dan tugas CI mengesahkan bahawa pangkalan pengetahuan adalah terkini, saling dipautkan, dan distruktur dengan betul. Seorang ejen “doc-gardening” yang berulang kali mengimbas dokumentasi usang atau lapuk yang tidak mencerminkan tingkah laku sebenar kod dan membuka "pull request" pembetulan.

Seiring dengan evolusi kod asas, kerangka kerja Codex untuk keputusan reka bentuk juga perlu berkembang.

Oleh kerana repositori ini dijana sepenuhnya oleh ejen, ia dioptimumkan terlebih dahulu untuk kejelasan Codex. Dengan cara yang sama pasukan berhasrat untuk meningkatkan kemudahan menavigasi kod mereka untuk pengambilan jurutera baharu, matlamat jurutera manusia kami adalah untuk membolehkan ejen menaakul tentang keseluruhan domain perniagaan secara langsung daripada repositori itu sendiri.

Dari sudut pandangan ejen, apa-apa yang tidak dapat diakses dalam konteks semasa beroperasi dengan berkesan dianggap tidak wujud. Pengetahuan yang terdapat dalam Google Docs, jalur sembang, atau dalam fikiran orang tidak dapat diakses oleh sistem. Artifak tempatan repositori yang berversi (contohnya, kod, markdown, skema, pelan boleh laksana) adalah semua yang dapat dilihatnya.

Kami mendapati bahawa kami perlu memasukkan lebih banyak konteks ke dalam repo dari semasa ke semasa. Perbincangan Slack yang menyelaraskan pasukan mengenai corak seni bina? Jika ia tidak dapat ditemui oleh ejen, ia tidak dapat dibaca dengan cara yang sama seperti ia akan menjadi tidak diketahui oleh pekerja baharu yang menyertai tiga bulan kemudian.

Memberi Codex lebih banyak konteks bermaksud menyusun dan mendedahkan maklumat yang tepat supaya ejen boleh membuat penaakulan mengenainya, bukannya membebankannya dengan arahan ad-hoc. Dengan cara yang sama seperti anda akan memperkenalkan rakan sepasukan baharu kepada prinsip produk, norma kejuruteraan, dan budaya pasukan (termasuk keutamaan emoji), memberikan ejen maklumat ini menghasilkan output yang lebih selaras.

Rangka ini menjelaskan banyak pertukaran. Kami mengutamakan kebergantungan dan abstraksi yang dapat diserap sepenuhnya dan difahami dalam repo. Teknologi yang sering digambarkan sebagai “membosankan” cenderung lebih mudah untuk dimodelkan oleh ejen disebabkan oleh kebolehgubahan, kestabilan API, dan perwakilan dalam set latihan. Dalam beberapa kes, lebih murah untuk meminta ejen melaksanakan semula subset fungsi daripada mencari jalan mengatasi tingkah laku huluan yang tidak jelas daripada perpustakaan awam. Sebagai contoh, daripada menggunakan pakej generik gaya p-limit, kami melaksanakan pembantu pemetaan dengan keserentakan kami sendiri: ia diintegrasikan dengan rapat dengan instrumentasi OpenTelemetry kami, mempunyai liputan ujian 100%, dan berfungsi dengan tepat seperti yang dijangkakan oleh runtime kami.

Menarik lebih banyak sistem ke dalam bentuk yang boleh diperiksa, disahkan, dan diubah suai secara langsung oleh ejen meningkatkan pengaruh—bukan sahaja untuk Codex, tetapi untuk ejen lain (contohnya, Aardvark) yang turut bekerja pada pangkalan kod juga.

Dokumentasi sahaja tidak dapat memastikan pangkalan kod yang dijana sepenuhnya oleh ejen kekal koheren. Dengan menguatkuasakan invarian, bukan mengurus pelaksanaan secara mikro, kami membolehkan ejen menghantar dengan cepat tanpa menjejaskan asas. Sebagai contoh, kami memerlukan Codex untuk menghurai bentuk data di sempadan⁠(dibuka dalam tetingkap baru), tetapi kami tidak menetapkan secara terperinci bagaimana perkara itu berlaku (model nampaknya menyukai Zod, tetapi kami tidak menetapkan pustaka khusus itu).

Ejen paling berkesan dalam persekitaran dengan sempadan yang ketat dan struktur yang boleh diramal⁠(dibuka dalam tetingkap baru), jadi kami membina aplikasi ini berdasarkan model seni bina yang tegar. Setiap domain perniagaan dibahagikan kepada satu set lapisan tetap, dengan arah kebergantungan yang disahkan secara ketat dan satu set tepi terhad yang dibenarkan. Kekangan ini dikuatkuasakan secara mekanikal melalui linter tersuai (dijana oleh Codex, sudah tentu!) dan ujian struktur.

Rajah di bawah menunjukkan peraturan: dalam setiap domain perniagaan (contohnya, Tetapan Apl), kod hanya boleh bergantung “ke hadapan” melalui set lapisan tetap (Jenis → Konfig → Repo → Perkhidmatan → Masa Larian → UI). Kebimbangan merentas fungsi (auth, penyambung, telemetri, bendera ciri) masuk melalui satu antara muka eksplisit: Penyedia. Apa-apa yang lain tidak dibenarkan dan dikuatkuasakan secara mekanikal.

Ini adalah jenis seni bina yang biasanya anda tangguhkan sehingga anda mempunyai ratusan jurutera. Dengan ejen pengekodan, ini adalah prasyarat awal: kekangan yang membolehkan kelajuan tanpa kemerosotan atau hanyutan seni bina.

Dalam amalan, kami menguatkuasakan peraturan ini dengan linter tersuai dan ujian struktur, serta satu set kecil “invarian rasa.” Sebagai contoh, kami menguatkuasakan secara statik pengelogan berstruktur, konvensyen penamaan untuk skema dan jenis, had saiz fail, serta keperluan kebolehpercayaan khusus platform dengan lint tersuai. Oleh kerana lint tersebut disesuaikan, kami menulis mesej ralat untuk menyuntik arahan pemulihan ke dalam konteks ejen.

Dalam aliran kerja yang mengutamakan manusia, peraturan ini mungkin terasa cerewet atau membatasi. Dengan ejen, mereka menjadi pengganda: sebaik sahaja dikodkan, mereka digunakan di mana-mana sekaligus.

Pada masa yang sama, kami dengan jelas menyatakan di mana kekangan penting dan di mana ia tidak. Ini menyerupai memimpin organisasi platform kejuruteraan yang besar: kuatkuasakan sempadan secara berpusat, benarkan autonomi secara setempat. Anda amat mengambil berat tentang sempadan, ketepatan, dan kebolehulangan. Dalam batasan tersebut, anda membenarkan pasukan—atau ejen—kebebasan yang ketara dalam cara penyelesaian dinyatakan.

Kod yang terhasil tidak selalu sepadan dengan keutamaan gaya manusia, dan itu tidak mengapa. Selagi output itu betul, boleh diselenggara, dan mudah dibaca untuk larian ejen pada masa hadapan, ia memenuhi piawaian.

Cita rasa manusia dimasukkan semula ke dalam sistem secara berterusan. Komen semakan, pull request pemfaktoran semula, dan pepijat yang dihadapi pengguna direkodkan sebagai kemas kini dokumentasi atau dikodkan terus ke dalam alat. Apabila dokumentasi tidak mencukupi, kami menaikkan peraturan tersebut ke dalam kod

Apabila daya pemprosesan Codex meningkat, banyak norma kejuruteraan konvensional menjadi bertentangan dengan tujuan.

Repositori beroperasi dengan gerbang penggabungan yang meminimumkan sekatan. Pull request adalah bersifat sementara. Kepingan ujian sering ditangani dengan pelaksanaan susulan dan bukannya menyekat kemajuan tanpa had. Dalam sistem di mana daya pemprosesan ejen jauh melebihi perhatian manusia, pembetulan adalah murah, dan menunggu adalah mahal.

Ini akan menjadi tidak bertanggungjawab dalam persekitaran berdaya pemprosesan rendah. Di sini, ia selalunya pertukaran yang betul.

Apabila kami mengatakan bahawa pangkalan kod dijana oleh ejen Codex, kami maksudkan keseluruhan kandungan dalam pangkalan kod tersebut.

Ejen menghasilkan:

• Kod produk dan ujian
• Konfigurasi CI dan alat pelepasan
• Alat pembangun dalaman
• Sejarah dokumentasi dan sejarah reka bentuk
• Abah-abah penilaian
• Semak komen dan respons
• Skrip yang mengurus repositori itu sendiri
• Fail definisi papan pemuka pengeluaran

Manusia sentiasa kekal dalam gelung, tetapi bekerja pada lapisan abstraksi yang berbeza daripada yang biasa kita lakukan. Kami mengutamakan kerja, menterjemahkan maklum balas pengguna kepada kriteria penerimaan, dan mengesahkan hasil. Apabila ejen menghadapi kesukaran, kami menganggapnya sebagai isyarat: kenal pasti apa yang hilang—alat, panduan, dokumentasi—dan masukkan semula ke dalam repositori, sentiasa dengan membiarkan Codex sendiri menulis pembaikannya.

Ejen menggunakan alat pembangunan standard kami secara langsung. Mereka menarik maklum balas semakan, membalas secara inline, menolak kemas kini, dan sering melakukan squash dan merge "pull request" mereka sendiri.

Apabila lebih banyak gelung pembangunan dikodkan terus ke dalam sistem—pengujian, pengesahan, semakan, pengendalian maklum balas, dan pemulihan—repositori baru-baru ini melepasi ambang bermakna di mana Codex boleh memacu ciri baharu dari hujung ke hujung.

Diberi satu prom, ejen kini boleh:

• Sahkan keadaan semasa pangkalan kod
• Reproduksi pepijat yang dilaporkan
• Rakamkan video yang memaparkan kegagalan tersebut
• Melaksanakan pembetulan
• Sahkan pembetulan dengan menjalankan aplikasi
• Rakam video kedua yang menunjukkan resolusi
• Buka pull request
• Berikan respons kepada maklum balas ejen dan manusia
• Kesan dan atasi kegagalan binaan
• Hanya panjangkan kepada manusia apabila pertimbangan diperlukan
• Cantumkan perubahan tersebut

Tingkah laku ini sangat bergantung pada struktur dan alat khusus repositori ini dan tidak sepatutnya dianggap boleh digeneralisasikan tanpa pelaburan yang serupa—sekurang-kurangnya, belum lagi.

Autonomi penuh ejen juga memperkenalkan masalah baharu. Codex meniru corak yang sudah wujud dalam repositori—termasuk yang tidak sekata atau kurang optimum. Dari semasa ke semasa, ini tidak dapat dielakkan menjadikannya hanyut.

Pada mulanya, manusia menangani perkara ini secara manual. Pasukan kami dahulu menghabiskan setiap hari Jumaat (20% daripada minggu) untuk membersihkan “sampah AI”. Tidak menghairankan, itu tidak berkembang.

Sebaliknya, kami mula mengekod apa yang kami sebut sebagai “prinsip emas” secara langsung ke dalam repositori dan membina proses pembersihan yang berulang. Prinsip ini adalah peraturan mekanikal yang berpendirian, memastikan pangkalan kod kekal mudah dibaca dan konsisten untuk pelaksanaan ejen pada masa hadapan. Sebagai contoh: (1) kami lebih mengutamakan pakej utiliti yang dikongsi berbanding pembantu yang dibuat sendiri untuk memastikan invarian dipusatkan, dan (2) kami tidak menyiasat data “gaya YOLO”—kami mengesahkan sempadan atau bergantung pada SDK berjenis supaya ejen tidak boleh secara tidak sengaja membina berdasarkan bentuk yang diteka. Pada selang masa yang tetap, kami mempunyai satu set tugas latar belakang Codex yang mengimbas penyimpangan, mengemas kini gred kualiti, dan membuka pull request pemfaktoran semula yang disasarkan. Kebanyakan daripada ini boleh disemak dalam masa kurang daripada seminit dan digabungkan secara automatik.

Ini berfungsi seperti pengumpulan sampah. Hutang teknikal adalah seperti pinjaman berfaedah tinggi: hampir selalu lebih baik untuk membayarnya secara berterusan dalam jumlah kecil daripada membiarkannya berkompaun dan menanganinya dalam ledakan yang menyakitkan. Cita rasa manusia ditangkap sekali, kemudian dikuatkuasakan secara berterusan pada setiap baris kod. Ini juga membolehkan kami mengesan dan menyelesaikan corak buruk setiap hari, daripada membiarkannya merebak dalam pangkalan kod selama berhari-hari atau berminggu-minggu.

Strategi ini setakat ini telah berfungsi dengan baik sehingga pelancaran dalaman dan penerimaan di OpenAI. Membina produk sebenar untuk pengguna sebenar membantu menambat pelaburan kami dalam realiti dan membimbing kami ke arah penyelenggaraan jangka panjang.

Apa yang kita belum ketahui ialah bagaimana koherensi seni bina berkembang selama bertahun-tahun dalam sistem yang sepenuhnya dijana oleh ejen. Kami masih mempelajari di mana penilaian manusia memberikan pengaruh paling besar dan bagaimana untuk mengekodkan penilaian itu supaya ia berkembang. Kami juga tidak tahu bagaimana sistem ini akan berkembang apabila model terus menjadi lebih berkemampuan dari semasa ke semasa.

Apa yang menjadi jelas: membina perisian masih memerlukan disiplin, tetapi disiplin itu lebih ketara dalam perancah berbanding dalam kod. Alat, abstraksi, dan gelung maklum balas yang memastikan pangkalan kod kekal koheren semakin penting.

Cabaran paling sukar kami kini tertumpu pada mereka bentuk persekitaran, gelung maklum balas, dan sistem kawalan yang membantu ejen mencapai matlamat kami: membina dan menyelenggara perisian yang kompleks dan boleh dipercayai pada skala besar.

Apabila ejen seperti Codex mengambil alih bahagian yang lebih besar dalam kitaran hayat perisian, soalan-soalan ini akan menjadi lebih penting. Kami berharap bahawa dengan berkongsi beberapa pengajaran awal, ia dapat membantu anda menilai di mana untuk melaburkan usaha anda supaya anda boleh terus membina sesuatu.