Bugüne kadar çalıştığım ekiplerde zorluk, Anthropic'in terminalde çalışan kodlama ajanı Claude Code'a erişim açıldıktan sonra başladı. Kurallar kimsenin kafasından repo'ya geçmeyince ajan, dün birinin düzelttiği hatayı bugün başka birinin makinesinde tekrarlıyor. Aynı değişiklik de onu kimin okuduğuna göre geçiyor ya da geri dönüyor.

Aşağıda yedi adım var ve sıra ölçüyle başlıyor, çünkü ölçü baştan seçilmezse sonradan herkes kendi izlenimini savunur. Hepsi yerine oturduğunda ajanla çalışma düzeni kişilerin alışkanlığından çıkıp repo'ya geçmiş olur.

Başlamadan bir sayı yaz

Ajanın ekibe ne kattığı sorulduğunda bir izlenimle cevap vermek kolay. Tek bir ölçü seç, örneğin bir işin PR'a dönme süresi ya da review'dan geri dönen PR sayısı, ve ilk adımı atmadan bugünkü değerini not et. Önceki değer yoksa sonraki sayının kıyaslanacağı bir şey de yoktur.

Kaç kişinin ajanı kullandığı ilk haftalarda en kolay toplanan sayı ve ajanın ekibe ne kadar yayıldığını iyi gösteriyor. Ekibin daha iyi iş çıkarıp çıkarmadığını ise seçtiğin ölçüdeki değişim söyler.

Kurallar repo'da durur

CLAUDE.md, Claude Code'un her oturumun başında, yani ajanı her açtığında okuduğu düz bir metin dosyası. Repo'nun kök dizinine koy ve içine kurulumu, test komutunu, branch ve commit kuralını yaz, ajanın dokunmaması gereken klasörleri de. Ajanın neye göre çalıştığını merak eden biri cevabı bu dosyada bulur.

İlk hata dosyanın yanlış yerde durması. Claude Code kişinin kendi ~/.claude/CLAUDE.md dosyasını da okur ve kurallar oraya yazılınca yalnız o kişinin ajanında çalışır. İkinci hata, repo'daki dosyanın ilk haftadan sonra hiç değişmemesi. Ajan aynı hatayı ikinci kez yaptığında elinde bir kural adayı var demektir ve o kural da kod gibi bir PR'la girdiğinde ekip onu görür.

Ajanın neye dokunacağı yazılı olsun

Claude Code bir komutu çalıştırmadan önce izin istiyor. Hangi komutun sorulmadan geçeceğini, hangisinin hiç çalışmayacağını repo'daki .claude/settings.json dosyasına yazabilirsin. Dosya commit'lendiği için ekipteki her ajan aynı tabanla başlıyor, kişisel ayarlar allow ve ask listelerini genişletebilir ama deny kuralını ezemez. Bir örnek:

{
  "permissions": {
    "allow": ["Bash(npm test *)", "Bash(npm run build *)"],
    "ask": ["Bash(git push *)"],
    "deny": [
      "Bash(git push --force*)",
      "Bash(gh pr merge *)",
      "Bash(rm -rf *)",
      "Read(**/.env*)"
    ]
  }
}

Deny listesi hepsinden önce gelir ve oradaki komut başka bir listede de olsa çalışmaz. Allow listesini dar tutmak daha güvenli görünüyor ama sonuç çoğu zaman tersine döner. Test komutu her koşuda izin isterse insanlar bir süre sonra istemi okumadan onaylar, tehlikeli bir komut da aynı alışkanlıkla geçer. Ekibin her gün koştuğu ve geri alınabilen komutları allow listesine koy, yalnız npm test gibi bir komutun ajanın yazdığı script'i de sormadan çalıştıracağını hesaba kat.

Production'ı ajana kapatmak için yalnız bu dosyaya güvenme. Ajan geliştiricinin makinesinde onun yetkileriyle çalışır, orada production'a erişen bir anahtar varsa ajanın da vardır. Deny kuralı da yalnız yazıldığı kalıbı yakalar. Örnekteki rm -rf * kuralı rm -fr diye yazılan komutu geçirir, git push -f ise deny'a takılmaz, yalnız onay ister. .env kuralı Claude Code'un dosya okuma aracını kapatır, aynı dosyayı terminalden okuyan bir komutu her durumda durdurmaz. Ajanın çalıştığı terminalde production anahtarı açık olmasın, settings dosyası bunun üstüne ikinci kat olsun.

İş küçük, plan onaylı

İş ajana sohbette anlatılınca ajan anladığı şeyi doğrudan koda döküyor ve yanlış anladığı yer ilk kez diff'te, kodun arasına dağılmış halde çıkıyor. Önce bir plan iste, yani işin adımlarını ve kabul kriterlerini, işin ne zaman bitmiş sayılacağını söyleyen cümleleri. Shift+Tab ile açılan plan modunda ajan dosyaları okur ama onay gelene kadar hiçbirini değiştirmez. Ajanın neyi yanlış anladığını yakalamanın en ucuz yeri plan.

İşi küçük tut, bir ile üç dosya arası. Büyük bir PR'ı satır satır okuyacak birini bulmak zor ve okunmadan onaylanan bir PR'daki hata çoğu zaman production'da bulunur. Kabul kriterini given/when/then biçiminde yaz, yani başlangıç durumu, yapılan tek şey ve beklenen sonuç. Bu biçimdeki bir kriter teste kolay çevrilir.

Test koddan önce yazılır

Testi kod bittikten sonra, vakit kalırsa yazan bir ekipte ajanın yazdığı test ajanın yazdığı kodu tarif ediyor. Kod yanlışsa test de aynı yanlışı doğru sayar.

Sırayı çevir. Ajan önce testi yazıp koştursun, test kırmızı yanar çünkü istenen davranış kodda yok. Kodu da testini de ajan yazdığı için sonradaki yeşil tek başına pek bir şey söylemez, kişinin bakacağı yer o kırmızı. Kırmızının kabul kriterini ölçüp ölçmediğine bak, ajan kodu ondan sonra yazsın.

Ajan bir testi geçiremeyince bazen testi gevşetiyor ya da siliyor. Diff'te bir test değişmişse PR'ı merge etmeden önce nedenini sor.

PR'ı yazan kişi merge etmez

Ajanın açtığı PR'da neye bakılacağı yazılı değilse herkes kendi listesiyle okur ve PR ya kuyrukta kalır ya da göz gezdirilip onaylanır. Neye bakılacağını repo'ya, CLAUDE.md'nin içine ya da yanına yaz.

Merge'e kimin basacağı baştan belli olsun. Örnekte gh pr merge deny listesinde, yani ajan o komutu çalıştıramaz. Asıl güvence GitHub ya da GitLab'daki merge ayarında. Kimin merge edebileceğini ve review'un zorunlu olup olmadığını orada belirle. Ajanla değişikliği çıkaran kişi PR'ını kendisi merge ederse de ajanın yazdığı koda ikinci bir insan bakmamış olur.

Diff yalnız değişen dosyaları gösterir ve ajanın güncellemeyi unuttuğu dosya orada hiç görünmez. Bu eksiği yakalayan, işin hangi dosyalara birlikte dokunduğunu bilen kişi olur.

Bulunan iyi yol skill olur

Skill, ajana bir işi nasıl yapacağını anlatan kısa bir talimat. Repo'daki .claude/skills/ klasörüne konduğunda ekipteki her ajan, skill'in açıklaması eldeki işe uyduğunda onu okur. Biri ajanla bir işi iyi yapmanın yolunu bulduğunda bunu toplantıda anlatıyor ya da bir dokümana yazıyor. Ajan o dokümanı okumaz, kişi hatırlarsa ajanına baştan anlatır.

Ekipte tekrar eden işleri bulmak için yazılan açık kaynak bir Claude Code plugin'i var, TeamHandbook. Repo'nun git geçmişinden bu işleri çıkarıp her biri için skill taslağı yazıyor ve taslakların hiçbiri onaylanmadan kurulmuyor. Bir işin bir kısmı git'e hiç girmez, merge'den önce elle koşulan bir kontrol gibi. Skill'in o kısmını ancak işi bilen kişi yazabilir.

Bu düzeni bir ekiple onun kendi repo'sunda kurmak için önerdiğim formatlar ve 2 saatlik canlı çalışmanın akışı /work sayfasında.