Codex Go Projelerinde Nasıl Kullanılır: Pratik Rehber

Codex, bir Go projesinde terminalde codex komutuyla başlar; bulunduğu klasördeki AGENTS.md dosyasını okur ve go test, gofmt, go vet gibi araçları doğal biçimde kullanır. Genel kurulum için Codex sayfasına, Codex CLI’nın çalışma mantığı için Codex CLI nasıl kullanılır? Adım adım rehber rehberine bakabilirsiniz. Bu yazıda kurulum tekrarına girmeden doğrudan Go’ya özgü pratikleri anlatacağım.

Neden Codex Go işlerinde iyi çalışır

Go’nun en büyük avantajı araç zincirinin hızlı ve belirleyici olmasıdır. go test ./... çoğu projede saniyeler içinde döner; derleyici hataları dosya:satır biçiminde net çıktı verir. Codex bu çıktıyı okuyup küçük düzeltmeler yapabilir; aynı hatayı birkaç turda çözmesi gerekse bile her turda somut bir ilerleme gösterir. gofmt sayesinde biçim tartışması yaşanmaz; ajanın yazdığı kod standart formata girer, böylece diff yalnızca mantık değişikliklerini gösterir. Statik tipler ve açık hata döndürme, ajanın fonksiyon imzalarını kolayca takip etmesini sağlar; örneğin bir handler’ı değiştirirken request ve response tiplerini doğrudan kod içinden çıkarabilir. Tablo testleri yaygın olduğu için Codex yeni test vakalarını var olan tabloya ekleyebilir; bu, test ekleme işini neredeyse mekanik hale getirir. Küçük arayüzler de ajanın mock ve fake üretmesini kolaylaştırır; io.Reader gibi tek metotlu arayüzler zaten standart kütüphanede hazırdır. Ancak goroutine, context.Context ve sync kullanımı gibi Go’ya özgü riskli alanlarda ajanı serbest bırakmamak gerekir; bu alanlarda go test -race ve go vet sizin güvenlik ağınız olmalıdır.

Projeyi ajana hazırlama: AGENTS.md

Codex her turda AGENTS.md dosyasını bağlam olarak alır; bu yüzden dosya, projenin komutlarını ve Go kurallarını kalıcı biçimde öğretmenin en etkili yoludur. Bağlam mühendisliği: yapay zeka kodlama ajanları rehberi rehberinde bağlamın nasıl yönetileceği ayrıntılı anlatılıyor. Go projesi için dosyada mutlaka şunlar bulunmalı: modül yolu, test/build/lint komutları, dizin düzeni, tablo testi kuralı, hata sarmalama ve context kullanımı. Ajanın go.mod ile oynamasını istemiyorsanız bunu da kurala bağlayın. Aşağıdaki örnek gerçek bir servis projesine göre kısaltılmıştır.

# AGENTS.md

## Proje
- Modül: `github.com/sirket/api`
- Go sürümü: `go.mod` içindeki `go` satırına bak

## Komutlar
- Tüm testler: `go test ./...`
- Tek paket testi: `go test ./internal/order -run TestCreate -v`
- Biçimlendirme: `gofmt -w .`
- Statik analiz: `go vet ./...`
- Derleme: `go build ./...`

## Dizin düzeni
- `cmd/` uygulama girişleri
- `internal/` dışarı açılmayan paketler
- `pkg/` yeniden kullanılabilir kütüphaneler
- `testdata/` test verileri

## Kurallar
- Her değişiklikten sonra `go test ./...` çalıştır.
- Yeni testler tablo testi olmalı; adı `TestXxx` biçiminde olmalı.
- Hataları `fmt.Errorf("bağlam: %w", err)` ile sarmala.
- `context.Context` fonksiyonlara ilk parametre olarak geçir; goroutine başlatırken mutlaka context kullan.
- Yeni bağımlılık eklemeden önce gerekçeyi bir cümleyle yaz; standart kütüphaneyi tercih et.
- Arayüzleri kullanan tarafta tanımla; tek metotluk arayüzler dışında gereksiz soyutlama ekleme.
- `go:generate` satırı olan dosyaları elle değiştirme; üreten komutu öner.

Bu dosyadaki komutlar ajana deterministik bir geri bildirim döngüsü sağlar. go test ./... tüm paketlerin testini çalıştırır; go vet ./... ise format string hataları, kopyalanmış kilitler gibi statik sorunları yakalar. Ajan bu komutları kendi başına çalıştırabildiği için hatayı düzeltip yeniden deneyebilir. Özellikle internal dizini altındaki paketlerin dışarıdan import edilemeyeceğini bilmek, ajanın yanlış bağımlılık yönleri önermesini engeller. Dosya güncel değilse ajan yanlış komutları çalıştırabilir; her bağımlılık veya dizin değişikliğinde AGENTS.md’yi de güncelleyin. Build tag’leri olan dosyalarınız varsa (_linux.go gibi), ajana bu dosyaları değiştirmemesi gerektiğini açıkça yazın.

Çalışma döngüsü ve örnek promptlar

Codex ile Go’da en verimli döngü şudur: önce ajanın planını küçük bir diff olarak istemek, sonra testleri çalıştırmak, ardından git diff üzerinden değişiklikleri okumak. Büyük bir refactor’ü tek promptla istemeyin; ajanı paket veya dosya sınırında tutun. Her turda go test ./... ve gofmt -l . çıktısını isteyin; bu iki komut temizse diff’i incelemeye geçebilirsiniz. Ajanın plan önerisini önce yazılı olarak vermesini istemek, yanlış yöne giden değişiklikleri erkenden yakalamanızı sağlar. Aşağıdaki promptlar tipik görevler için başlangıç olabilir.

• cmd/api içindeki create handler’ını incele. Request doğrulaması eksikse net/http ile ekle; hata yanıtlarını JSON olarak döndür. Yeni testleri tablo testi olarak handler_test.go dosyasına ekle ve go test ./cmd/api/... çalıştır.
• internal/order paketindeki ProcessOrders fonksiyonunu context cancellation’a uygun hale getir. select ile ctx.Done() dinle, goroutine sızıntısı olmadığını gösteren bir test yaz.
• Şu go vet ./... çıktısını kullanarak sorunları düzelt: [çıktıyı yapıştır]. Sadece ilgili dosyaları değiştir, biçimlendirme yapma.
• internal/cache paketindeki Get fonksiyonu için benchmark yaz; go test -bench=. -benchmem ./internal/cache çalıştır ve allocation sayısını azaltacak somut bir değişiklik öner.
• AGENTS.md’deki komutları sırayla çalıştır; kırılan testleri tek tek düzelt. Her düzeltmeden sonra üç satırlık git diff özeti ver.

Ajan bir testi düzelttiğinde git diff --stat ile yalnızca hedeflenen dosyaların değiştiğini kontrol edin. internal/ dışındaki paketlerde beklenmedik değişiklikler varsa ajanın planını tekrar isteyin. Döngüyü şöyle sürdürün: prompt ver, testleri ajan çalıştırsın, siz git diff inceleyin, sonra bir sonraki adımı verin. Bu ritim, hem ajanın bağlamını küçük tutar hem de Go projesinin değişmezlerini korur.

İyi olduğu işler ve dikkat edilecek noktalar

Codex Go projelerinde en çok şu işlerde güvenilirdir: tablo testlerini genişletmek, %w ile hata sarmalama eklemek, context parametresini alt fonksiyonlara yaymak, küçük arayüzleri ayıklamak, gofmt ve go vet uyarılarını gidermek ve dokümantasyon yorumlarını güncellemek. Buna karşılık şu alanlarda mutlaka gözünüz üzerinde olsun: goroutine yaşam döngüsü, sync.WaitGroup ve errgroup kullanımı, data race ihtimali, go.mod ve go.sum değişiklikleri, build tag’leri ve go:generate dosyaları.

Özellikle goroutine ve context hataları sinsidir; ajan, context.WithCancel eklemeden go func başlatabilir veya sync.WaitGroup içinde defer wg.Done() eklemeyi unutabilir. Böyle bir değişikliği üretim koduna almak testlerde görünmeyen bir sızıntıya yol açar; bu yüzden go test -race ./... her PR öncesi zorunlu olmalıdır. Hata sarmalamada %w yerine %v kullanması, errors.Is ve errors.As tabanlı kontrolün sessizce bozulmasına neden olur; diff içinde fmt.Errorf çağrılarını arayın. Tablo testlerinde ajan bazen beklenen değeri gerçek sonuca eşitleyerek testi geçirebilir; assertion’ın değişip değişmediğini ayrıca inceleyin. Arayüz ayıklarken gereğinden fazla metotlu bir arayüz önerebilir; tüketici tarafta tek metotlu arayüz tanımlamasını kural olarak hatırlatın. Ayrıca nil pointer döndüren bir arayüz implementasyonu, interface değeri nil olmadığı için beklenmedik hatalara yol açabilir; bunu yakalayan bir test eklemek sağlıklıdır.

Go projelerinde test ve doğrulama

Ajanın çıktısını kabul etmeden önce aşağıdaki tabloyu uygulayın. Codex testleri kendisi çalıştırabilir ama siz diff’i ve komut çıktılarını görmelisiniz. Özellikle go test -race ./... ve go vet ./... çıktılarını isteyin; bunlar Go’ya özgü hataları erken yakalar.

Tabloda verilen komutların çıktısını ajan size getirdiğinde, go test -json ile birleştirmek istemiyorsanız düz metin yeterlidir. Bir testin neden kırıldığını anlamak için ajana şu komutu çalıştırmasını söyleyin: go test -run TestCreate -count=1 -v ./internal/order. -count=1 test önbelleğini devre dışı bırakır; özellikle ajanın ardışık düzeltmelerinde her seferinde aynı testin çalıştığından emin olursunuz. Gofmt denetimi en son gofmt -w . ile kapatılır; ajan bunu çalıştırdıktan sonra diff’i yeniden alın. Ayrıca git diff --check boşluk hatalarını, go test -coverprofile=coverage.out ise hangi paketlerin test kapsamının düşük kaldığını gösterir; coverage çıktısını ajana verip boşlukları kapatmasını isteyebilirsiniz.

Birden çok ajan: AgentVera ile paralel Go çalışması

Birden fazla Codex oturumunu aynı Go deposunda koşmak istiyorsanız AgentVera iyi bir seçenektir; AgentVera nasıl kullanılır: ilk proje, ajanlar ve ızgara bağlantısındaki uygulama, gerçek CLI araçlarını yan yana terminal panellerinde çalıştırır. Go için en önemli avantajı, her ajanın kendi git worktree’sinde ilerleyebilmesidir; böylece internal/ paketlerinde aynı anda yapılan değişiklikler birbirini ezmez. Ayrıca ajan bir turu bitirdiğinde ikinci modelin diff’i incelemesi, özellikle goroutine ve arayüz hatalarını file:line ile gösterir; checkpoint’ler sayesinde hatalı bir refactor tek tıkla geri alınabilir. Token bütçeleri de uzun test ve refactor döngülerinde ajanın kontrolden çıkmasını engeller.

Kapanış

Codex, Go’da en çok, net bir AGENTS.md ve sıkı doğrulama döngüsüyle işe yarar. Ajanın her değişikliğini gofmt, go vet, go test -race ve git diff ile süzün; concurrency kokan yerleri mutlaka kendiniz okuyun. Özellikle goroutine, context ve hata sarmalama alanlarında test kapsamını yükseltmek, ajanın önerdiği kodu güvenle almanızı sağlar. Böylece hızlı bir asistan değil, güvenilir bir Go pair programmer’ı elde edersiniz.