Harness Mühendisliği: Ajan Odaklı Dünyada Codex’ten Yararlanmak
Son beş ayda, ekibimiz bir deney yürüttü: sıfır satır manuel yazılmış kodla dahili bir yazılım ürününün beta sürümünü oluşturmak ve piyasaya sürmek. Ürün, dahili günlük kullanıcılara ve harici alfa test uzmanlarına sahip. Piyasaya sürülüyor, dağıtılıyor, bozuluyor ve düzeltiliyor. Fark şu ki, uygulama mantığı, testler, CI yapılandırması, dokümantasyon, gözlemlenebilirlik ve dahili araçlar dahil her bir kod satırı Codex tarafından yazıldı. Bunu, kodu elle yazmanın gerektireceği sürenin yaklaşık 1/10’unda oluşturduğumuzu tahmin ediyoruz.
İnsanlar yönlendirir. Ajanlar uygular.
Bu kısıtlamayı kasıtlı olarak seçtik, böylece mühendislik hızını kat kat artırmak için neyin gerekli olduğunu inşa edecektik. Bir milyon satır kodla sonuçlanan şeyi göndermek için haftalarımız vardı. Bunu yapmak için, bir yazılım mühendisliği ekibinin birincil görevi artık kod yazmak değil, Codex ajanlarının güvenilir işler yapmasına izin veren ortamlar tasarlamak, amacı belirtmek ve geri bildirim döngüleri oluşturmak olduğunda nelerin değiştiğini anlamamız gerekiyordu.
Bu yazı, bir ajan ekibiyle yepyeni bir ürün oluşturarak öğrendiklerimiz hakkında: neyin bozulduğu, neyin biriktiği ve tek gerçekten kıt kaynağımızı, yani insan zamanını ve dikkatini nasıl maksimize edeceğimiz.
Boş Bir Git Deposunda Başladık
Boş bir depoya ilk taahhüt Ağustos 2025’in sonlarında yapıldı. Başlangıç iskelesi—depo yapısı, CI yapılandırması, biçimlendirme kuralları, paket yöneticisi kurulumu ve uygulama çerçevesi—GPT‑5 tarafından yönlendirilen küçük bir mevcut şablon seti kullanılarak Codex CLI tarafından oluşturuldu. Ajanlara depoda nasıl çalışacaklarını gösteren ilk AGENTS.md dosyası bile Codex tarafından yazıldı. Sistemi demirleyecek önceden var olan insan yazımı kod yoktu. Başından itibaren, depo ajan tarafından şekillendirildi.
Beş ay sonra, depo uygulama mantığı, altyapı, araçlar, dokümantasyon ve dahili geliştirici yardımcı programları dahil olmak üzere bir milyon civarında kod satırı içeriyor. Bu süre zarfında, Codex’i yönlendiren sadece üç mühendisten oluşan küçük bir ekiple yaklaşık 1.500 çekme isteği açıldı ve birleştirildi. Bu, mühendis başına günde ortalama 3,5 PR üretkenliğine denk geliyor ve şaşırtıcı bir şekilde, ekip şu anda yedi mühendise ulaştıkça üretkenlik arttı. Önemlisi, bu çıktı sadece çıktı uğruna değildi: ürün dahili olarak yüzlerce kullanıcı tarafından kullanıldı, buna günlük dahili güç kullanıcıları da dahil.
Geliştirme süreci boyunca, insanlar asla doğrudan herhangi bir kod katkısında bulunmadı. Bu, ekip için temel bir felsefe haline geldi: manuel yazılmış kod yok.
Mühendis Rolünü Yeniden Tanımlamak
Manuel insan kodlamasının olmaması, sistemlere, iskeleye ve kaldıraça odaklanan farklı bir mühendislik işi türü ortaya çıkardı.
Başlangıçtaki ilerleme beklediğimizden daha yavaştı, çünkü Codex yetersiz değildi, aksine ortam yeterince belirtilmemişti. Ajanın üst düzey hedeflere doğru ilerlemek için gereken araçları, soyutlamaları ve dahili yapısı yoktu. Mühendislik ekibimizin birincil görevi, ajanların faydalı işler yapmasını sağlamak haline geldi.
Pratikte, bu derinlemesine çalışmak anlamına geliyordu: daha büyük hedefleri daha küçük yapı taşlarına (tasarım, kod, inceleme, test vb.) bölmek, ajanı bu blokları oluşturması için yönlendirmek ve bunları daha karmaşık görevleri açığa çıkarmak için kullanmak. Bir şeyler başarısız olduğunda, çözüm neredeyse hiç ‘daha çok dene’ olmadı. İlerlemenin tek yolu Codex’i işi yapmaya ikna etmek olduğundan, insan mühendisler her zaman göreve adım attı ve sordu: ‘Hangi yetenek eksik ve bunu ajan için hem okunaklı hem ve uygulanabilir hale nasıl getiririz?’
İnsanlar sistemle neredeyse tamamen komutlar aracılığıyla etkileşim kurar: bir mühendis bir görevi tanımlar, ajanı çalıştırır ve bir çekme isteği açmasına izin verir. Bir PR’yi tamamlamak için, Codex’e kendi değişikliklerini yerel olarak gözden geçirmesi, hem yerel hem de bulutta ek özel ajan incelemeleri talep etmesi, verilen insan veya ajan geri bildirimlerine yanıt vermesi ve tüm ajan gözden geçirenler memnun olana kadar bir döngüde yinelemesi talimatını veriyoruz (bu etkili bir şekilde Ralph Wiggum Döngüsü‘dür). Codex, bağlamı toplamak için standart geliştirme araçlarımızı doğrudan kullanır (gh, yerel betikler ve depoya gömülü beceriler) böylece insanların CLI’ya kopyala-yapıştır yapmasına gerek kalmaz.
İnsanlar çekme isteklerini gözden geçirebilir, ancak bu zorunlu değildir. Zamanla, neredeyse tüm inceleme çabalarını ajanlar arası işlenecek şekilde yönlendirdik.
Uygulama Okunabilirliğini Artırma
Kod çıktısı arttıkça, darboğazımız insan QA kapasitesi haline geldi. İnsan zamanı ve dikkati sabit bir kısıtlama olduğu için, uygulama arayüzü, günlükler ve uygulama metrikleri gibi şeyleri Codex için doğrudan okunaklı hale getirerek ajana daha fazla yetenek eklemek için çalıştık.
Örneğin, uygulamayı her git worktree için başlatılabilir hale getirdik, böylece Codex her değişiklik için bir örnek başlatabilir ve sürebilir. Ayrıca Chrome DevTools Protokolünü ajan çalışma zamanına bağladık ve DOM anlık görüntüleri, ekran görüntüleri ve gezinme ile çalışmak için beceriler oluşturduk. Bu, Codex’in hataları yeniden üretmesine, düzeltmeleri doğrulamasına ve UI davranışını doğrudan yorumlamasına olanak tanıdı.
Aynısını gözlemlenebilirlik araçları için de yaptık. Günlükler, metrikler ve izler, herhangi bir worktree için geçici olan yerel bir gözlemlenebilirlik yığını aracılığıyla Codex’e gösterilir. Codex, bu uygulamanın tamamen izole edilmiş bir sürümü üzerinde çalışır—bu görevin tamamlanmasından sonra kaldırılan günlükleri ve metrikleri dahil. Ajanlar günlükleri LogQL ve metrikleri PromQL ile sorgulayabilir. Bu bağlam mevcut olduğunda, ‘hizmet başlangıcının 800ms’nin altında tamamlandığından emin ol’ veya ‘bu dört kritik kullanıcı yolculuğundaki hiçbir sürenin iki saniyeyi aşmadığından emin ol’ gibi komutlar uygulanabilir hale gelir.
Tek Codex çalıştırmalarının tek bir görev üzerinde altı saate kadar (genellikle insanlar uyurken) çalıştığını düzenli olarak görüyoruz.
Depo Bilgisini Kayıt Sistemi Haline Getirdik
Bağlam yönetimi, ajanları büyük ve karmaşık görevlerde etkili kılmanın en büyük zorluklarından biridir. Öğrendiğimiz ilk derslerden biri basitti: Codex’e bir harita verin, 1.000 sayfalık bir talimat kılavuzu değil.
- Bağlam kıt bir kaynaktır. Devasa bir talimat dosyası, görevi, kodu ve ilgili dokümanları kalabalıklaştırır—bu nedenle ajan ya temel kısıtlamaları kaçırır ya da yanlış olanlar için optimize etmeye başlar.
- Çok fazla rehberlik, rehbersizlik haline gelir. Her şey ‘önemli’ olduğunda, hiçbir şey önemli değildir. Ajanlar kasıtlı olarak gezinmek yerine yerel olarak desen eşleştirmesi yaparlar.
- Anında çürür. Monolitik bir kılavuz, eski kuralların mezarlığına dönüşür. Ajanlar neyin hala doğru olduğunu anlayamaz, insanlar onu korumayı bırakır ve dosya sessizce çekici bir rahatsızlığa dönüşür.
- Doğrulaması zordur. Tek bir blob mekanik kontrollere (kapsam, tazelik, sahiplik, çapraz bağlantılar) uygun değildir, bu nedenle kayma kaçınılmazdır.
Bu yüzden AGENTS.md’yi ansiklopedi olarak ele almak yerine, onu içindekiler tablosu olarak ele alıyoruz.
Deponun bilgi tabanı, kayıt sistemi olarak ele alınan yapılandırılmış bir docs/ dizininde bulunur. Kısa bir AGENTS.md (yaklaşık 100 satır), bağlama enjekte edilir ve öncelikle bir harita görevi görür, daha derin doğruluk kaynaklarına işaretçilerle birlikte.
Depo içi bilgi deposu düzeni. Tasarım dokümantasyonu kataloglanır ve dizinlenir, doğrulama durumu ve ajan odaklı işletim prensiplerini tanımlayan bir dizi temel inanç dahil. Mimari dokümantasyon, etki alanlarının ve paket katmanlarının üst düzey bir haritasını sağlar. Bir kalite belgesi, her ürün etki alanını ve mimari katmanı derecelendirir, zaman içindeki boşlukları izler.
Planlar birinci sınıf eserler olarak ele alınır. Küçük değişiklikler için geçici hafif planlar kullanılırken, karmaşık işler ilerleme ve karar günlüklerini içeren ve depoya kaydedilen yürütme planlarında yakalanır. Aktif planlar, tamamlanmış planlar ve bilinen teknik borçların tümü sürüm kontrolüne alınır ve birlikte yer alır, bu da ajanların harici bağlama dayanmadan çalışmasına olanak tanır.
Bu, aşamalı ifşa sağlar: ajanlar küçük, kararlı bir giriş noktasıyla başlar ve baştan bunalmak yerine bir sonraki nereye bakacakları öğretilir.
Bunu mekanik olarak uyguluyoruz. Özel lint araçları ve CI işleri, bilgi tabanının güncel, çapraz bağlantılı ve doğru yapılandırılmış olduğunu doğrular. Tekrarlayan bir ‘doküman-bahçıvanlık’ ajanı, gerçek kod davranışını yansıtmayan eski veya modası geçmiş dokümantasyonu tarar ve düzeltme çekme istekleri açar.
Ajan Okunabilirliği Hedefimizdir
Kod tabanı geliştikçe, Codex’in tasarım kararları çerçevesinin de gelişmesi gerekti. Depo tamamen ajan tarafından üretildiği için, öncelikle Codex’in okunabilirliği için optimize edilmiştir. Ekiplerin yeni mühendis işe alımları için kodlarının gezinebilirliğini artırmayı hedeflediği gibi, insan mühendislerimizin amacı da bir ajanın tüm iş alanını doğrudan depodan yorumlamasını mümkün kılmaktı.
Ajanın bakış açısından, çalışırken bağlam içinde erişemediği hiçbir şey fiilen yoktur. Google Dokümanlar’da, sohbet dizilerinde veya insanların kafasında yaşayan bilgiler sisteme erişilemez. Depo yerel, sürüm kontrolüne alınmış eserler (örn. kod, markdown, şemalar, yürütülebilir planlar) görebildiği tek şeydir.
Zamanla depoya daha fazla bağlam itmemiz gerektiğini öğrendik. Ekibi bir mimari desen üzerinde hizalayan o Slack tartışması mı? Eğer ajan için keşfedilemezse, üç ay sonra katılan yeni bir işe alım için bilinmediği gibi okunaksızdır.
Codex’e daha fazla bağlam vermek, ajanın üzerinde düşünebilmesi için doğru bilgiyi organize etmek ve ifşa etmek anlamına gelir, onu geçici talimatlarla bunaltmak yerine. Yeni bir ekip arkadaşına ürün prensipleri, mühendislik normları ve ekip kültürü (emoji tercihleri dahil) hakkında bilgi verdiğiniz gibi, ajana bu bilgiyi vermek daha iyi hizalanmış çıktılar sağlar.
Bu çerçeve birçok ödünleşimi açıklığa kavuşturdu. Tamamen dahilleştirilebilecek ve depo içinde üzerinde düşünülebilecek bağımlılıkları ve soyutlamaları tercih ettik. Genellikle ‘sıkıcı’ olarak tanımlanan teknolojiler, birleştirilebilirlik, API istikrarı ve eğitim setindeki temsiliyetleri nedeniyle ajanların modellemesi için daha kolay olma eğilimindedir. Bazı durumlarda, genel bir ‘p-limit’ tarzı paket çekmek yerine, işlevselliğin alt kümelerini ajanın yeniden uygulaması, genel kütüphanelerden gelen opak yukarı akış davranışını aşmaktan daha ucuzdu. Örneğin, kendi eşzamanlılık yardımcı haritamızı uyguladık: OpenTelemetry enstrümantasyonumuzla sıkı bir şekilde entegre, %100 test kapsamına sahip ve çalışma zamanımızın beklediği gibi davranıyor.
Sistemin daha fazlasını ajanın doğrudan inceleyebileceği, doğrulayabileceği ve değiştirebileceği bir forma sokmak, sadece Codex için değil, kod tabanı üzerinde çalışan diğer ajanlar (örn. Aardvark) için de kaldıraç artırır.
Mimari ve Zevki Uygulamak
Yalnızca dokümantasyon, tamamen ajan tarafından üretilmiş bir kod tabanını tutarlı tutmaz. Uygulamaları mikroyönetmek yerine değişmezleri uygulayarak, ajanların temeli bozmadan hızlı bir şekilde gönderim yapmalarına izin verdik. Örneğin, Codex’ten sınırda veri şekillerini ayrıştırmasını istiyoruz, ancak bunun nasıl olacağı konusunda reçeteci değiliz (model Zod’u seviyor gibi görünüyor, ancak bu belirli kütüphaneyi belirtmedik).
Ajanlar, katı sınırlar ve öngörülebilir yapıya sahip ortamlarda en etkilidir, bu nedenle uygulamayı katı bir mimari model etrafında inşa ettik. Her iş alanı, kesin olarak doğrulanmış bağımlılık yönleri ve sınırlı sayıda izin verilen kenarlarla sabit bir katman setine ayrılmıştır. Bu kısıtlamalar, özel lint araçları (elbette Codex tarafından üretilen) ve yapısal testler aracılığıyla mekanik olarak uygulanır.
Aşağıdaki diyagram kuralı göstermektedir: her iş alanı içinde (örn. Uygulama Ayarları), kod sadece sabit bir katman seti aracılığıyla ‘ileri’ bağımlı olabilir (Tipler → Yapılandırma → Repo → Hizmet → Çalışma Zamanı → UI). Çapraz kesen endişeler (kimlik doğrulama, bağlayıcılar, telemetri, özellik bayrakları) tek bir açık arayüz aracılığıyla girer: Sağlayıcılar. Diğer her şeye izin verilmez ve mekanik olarak uygulanır.
Bu, genellikle yüzlerce mühendisiniz olana kadar erteleyeceğiniz türden bir mimaridir. Kodlama ajanlarıyla, bu erken bir önkoşuldur: kısıtlamalar, bozulma veya mimari kayma olmadan hız sağlayan şeydir.
Pratikte, bu kuralları özel lint araçları ve yapısal testlerle birlikte küçük bir ‘zevki değişmezleri’ setiyle uyguluyoruz. Örneğin, yapılandırılmış günlük kaydını, şemalar ve tipler için adlandırma kurallarını, dosya boyutu limitlerini ve platforma özgü güvenilirlik gereksinimlerini özel lint’lerle statik olarak uygularız. Lint’ler özel olduğu için, hata mesajlarını ajan bağlamına düzeltme talimatları enjekte edecek şekilde yazarız.
İnsan odaklı bir iş akışında, bu kurallar pedantik veya kısıtlayıcı gelebilir. Ajanlarla, bunlar çarpan haline gelir: bir kez kodlandığında, her yere aynı anda uygulanırlar.
Aynı zamanda, kısıtlamaların nerede önemli olduğunu ve nerede olmadığını açıkça belirtiyoruz. Bu, büyük bir mühendislik platformu organizasyonunu yönetmeye benzer: sınırları merkezi olarak uygulayın, yerel olarak özerkliğe izin verin. Sınırlar, doğruluk ve tekrarlanabilirlik konusunda derinlemesine ilgilenirsiniz. Bu sınırlar içinde, ekiplere—veya ajanlara—çözümlerin nasıl ifade edildiği konusunda önemli özgürlük tanırsınız.
Ortaya çıkan kod her zaman insan stilistik tercihlerine uymayabilir ve bu sorun değil. Çıktı doğru, sürdürülebilir ve gelecekteki ajan çalıştırmaları için okunabilir olduğu sürece, barı karşılar.
İnsan zevki sürekli olarak sisteme geri beslenir. İnceleme yorumları, yeniden düzenleme çekme istekleri ve kullanıcıya dönük hatalar dokümantasyon güncellemeleri olarak yakalanır veya doğrudan araçlara kodlanır. Dokümantasyon yetersiz kaldığında, kuralı koda yükseltiriz.
Üretkenlik Birleştirme Felsefesini Değiştirir
Codex’in üretkenliği arttıkça, birçok geleneksel mühendislik normu ters etki yaratmaya başladı.
Depo, minimum engelleme birleştirme geçitleriyle çalışır. Çekme istekleri kısa ömürlüdür. Test hataları genellikle süresiz olarak ilerlemeyi engellemek yerine takip eden çalıştırmalarla ele alınır. Ajan üretkenliğinin insan dikkatini kat kat aştığı bir sistemde, düzeltmeler ucuzdur ve beklemek pahalıdır.
Bu, düşük üretkenlikli bir ortamda sorumsuzluk olurdu. Burada ise genellikle doğru bir ödünleşmedir.
‘Ajan Tarafından Üretilmiş’ Gerçekte Ne Anlama Geliyor
Kod tabanının Codex ajanları tarafından üretildiğini söylediğimizde, kod tabanındaki her şeyi kastediyoruz.
Ajanlar şunları üretir:
- Ürün kodu ve testler
- CI yapılandırması ve yayın araçları
- Dahili geliştirici araçları
- Dokümantasyon ve tasarım geçmişi
- Değerlendirme donanımları
- İnceleme yorumları ve yanıtları
- Depoyu yöneten betikler
- Üretim panosu tanımlama dosyaları
İnsanlar her zaman döngüde kalır, ancak eskiden olduğumuzdan farklı bir soyutlama katmanında çalışırız. İşi önceliklendirir, kullanıcı geri bildirimlerini kabul kriterlerine çevirir ve sonuçları doğrularız. Ajan zorlandığında, bunu bir sinyal olarak ele alırız: neyin eksik olduğunu—araçlar, koruyucular, dokümantasyon—belirleriz ve her zaman Codex’in kendisi düzeltmeyi yazarak depoya geri besleriz.
Ajanlar standart geliştirme araçlarımızı doğrudan kullanır. İnceleme geri bildirimlerini çeker, satır içi yanıt verir, güncellemeleri iter ve genellikle kendi çekme isteklerini birleştirir.
Artan Özerklik Seviyeleri
Geliştirme döngüsünün daha fazlası doğrudan sisteme kodlandıkça—test etme, doğrulama, inceleme, geri bildirim işleme ve kurtarma—depo yakın zamanda Codex’in uçtan uca yeni bir özelliği yönlendirebileceği anlamlı bir eşiği aştı.
Tek bir komut verildiğinde, ajan artık şunları yapabilir:
- Kod tabanının mevcut durumunu doğrulamak
- Bildirilen bir hatayı yeniden üretmek
- Hatayı gösteren bir video kaydetmek
- Bir düzeltme uygulamak
- Uygulamayı çalıştırarak düzeltmeyi doğrulamak
- Çözümü gösteren ikinci bir video kaydetmek
- Bir çekme isteği açmak
- Ajan ve insan geri bildirimlerine yanıt vermek
- Derleme hatalarını tespit etmek ve düzeltmek
- Yargı gerektiğinde sadece insana bildirmek
- Değişikliği birleştirmek
Bu davranış, bu deponun özel yapısına ve araçlarına büyük ölçüde bağlıdır ve benzer bir yatırım yapılmadan genelleşeceği varsayılmamalıdır—en azından henüz değil.
Entropi ve Çöp Toplama
Tam ajan özerkliği aynı zamanda yeni sorunlar da ortaya çıkarır. Codex, depoda zaten var olan desenleri—hatta düzensiz veya suboptimal olanları bile—kopyalar. Zamanla, bu kaçınılmaz olarak kaymaya yol açar.
Başlangıçta, insanlar bunu manuel olarak ele aldı. Ekibimiz eskiden her Cuma (haftanın %20’si) ‘yapay zeka pisliğini’ temizlemekle uğraşırdı. Şaşırtıcı olmayan bir şekilde, bu ölçeklenmedi.
Bunun yerine, ‘altın prensipler’ dediğimiz şeyleri doğrudan depoya kodlamaya başladık ve düzenli bir temizlik süreci oluşturduk. Bu prensipler, kod tabanını gelecekteki ajan çalıştırmaları için okunaklı ve tutarlı tutan, özel, mekanik kurallardır. Örneğin: (1) değişmezleri merkezileştirmek için el yapımı yardımcılar yerine paylaşılan yardımcı program paketlerini tercih ederiz ve (2) veriyi ‘YOLO tarzı’ incelemeyiz—sınırları doğrularız veya yazılı SDK’lara güveniriz, böylece ajan yanlışlıkla tahmin edilen şekiller üzerine inşa edemez. Düzenli bir tempoda, sapmaları tarayan, kalite derecelerini güncelleyen ve hedeflenen yeniden düzenleme çekme istekleri açan bir dizi arka plan Codex görevi vardır. Bunların çoğu bir dakikadan kısa sürede gözden geçirilebilir ve otomatik olarak birleştirilebilir.
Bu, çöp toplama gibi işlev görür. Teknik borç, yüksek faizli bir krediye benzer: birikmesine izin verip acı verici patlamalarla uğraşmaktansa, küçük artışlarla sürekli olarak ödemek neredeyse her zaman daha iyidir. İnsan zevki bir kez yakalanır, sonra her kod satırında sürekli olarak uygulanır. Bu ayrıca, kötü desenleri günlerce veya haftalarca kod tabanında yayılmasına izin vermek yerine günlük olarak yakalayıp çözmemizi sağlar.
Hala Ne Öğreniyoruz
Bu strateji, OpenAI’da dahili lansman ve benimsemeye kadar iyi çalıştı. Gerçek kullanıcılar için gerçek bir ürün inşa etmek, yatırımlarımızı gerçekliğe sabitlememize ve bizi uzun vadeli sürdürülebilirliğe yönlendirmemize yardımcı oldu.
Henüz bilmediğimiz şey, tamamen ajan tarafından üretilmiş bir sistemde mimari tutarlılığın yıllar içinde nasıl geliştiğidir. İnsan yargısının en çok nerede kaldıraç eklediğini ve bu yargıyı nasıl bileşik hale getireceğimizi hala öğreniyoruz. Ayrıca, modeller zamanla daha yetenekli hale geldikçe bu sistemin nasıl gelişeceğini de bilmiyoruz.
Açıkça ortaya çıkan şey: yazılım inşa etmek hala disiplin gerektiriyor, ancak disiplin koddan çok iskelede ortaya çıkıyor. Kod tabanını tutarlı tutan araçlar, soyutlamalar ve geri bildirim döngüleri giderek daha önemli hale geliyor.
En zorlu zorluklarımız artık ajanların hedefimize ulaşmasına yardımcı olan ortamlar, geri bildirim döngüleri ve kontrol sistemleri tasarlamak üzerine odaklanıyor: ölçekte karmaşık, güvenilir yazılım inşa etmek ve sürdürmek.
Codex gibi ajanlar yazılım yaşam döngüsünün daha büyük kısımlarını üstlendikçe, bu sorular daha da önemli hale gelecek. Erken dersleri paylaşmanın, çabanızı nereye yatıracağınız konusunda size yardımcı olacağını umuyoruz, böylece sadece şeyler inşa edebilirsiniz.
