Bilgi Depoda, Anahtarlar Sizde: Geliştiriciniz Yarın Gitse Ne Olur?

Bir önceki yazıyı bir öneriyle bitirmiştim: ajanınızı çalıştıran aracı bir günlüğüne başka biriyle değiştirin; ne kadarı çalışmaya devam ediyorsa, bilginizin o kadarı depoda (repository) demektir. Bu yazıda aynı deneyi bir adım öteye taşıyorum. Bu kez aracı değil, geliştiriciyi değiştirelim.

Büyük bir şirket küçük bir yazılım firmasıyla çalışmayı düşündüğünde masaya ilk gelen soru hep aynı: “Bu kişiye yarın ulaşamazsak ne olacak?” Satın alma (procurement) dilinde bunun iki adı var: kilit kişi riski (key person risk) ve tedarikçi bağımlılığı (vendor lock-in). Soru haklı. Bir sistemi yalnızca bir kişi biliyorsa, o kişi o sistemin tek yedeksiz parçasıdır (single point of failure).

Bu soruya verilen klasik cevapların üçü de eksik kalıyor. Dokümantasyon sözleşmeye yazılır ama ya hiç yazılmaz ya da ilk sürümde donup eskir. İkinci bir geliştirici riski böler ama maliyeti ikiye katlar. Kaynak kod emaneti (source code escrow) kodu teslim eder, ama o kodu ayağa kaldırmak için gereken bilgiyi teslim etmez: hangi ortam nerede, hangi iş hangi sırayla yapılır, hangi kural neden konmuş.

Yapay zekâyla geliştirilen bir projede bu tablo değişiyor. Bu yazı nasıl değiştiğini ve neyin değişmediğini anlatıyor.

Bilgi artık depoda

Bir yapay zekâ ajanı (AI agent) her oturuma (session) hafızasız başlıyor. Önceki gün ne konuşulduğunu, hangi kararın neden verildiğini, hangi komutun hangi ortama dokunduğunu bilmiyor. Bilebilmesi için tüm bunların depoda, yani kodla aynı yerde yazılı olması gerekiyor. Yazılmayan bilgiyle iş yapamıyor.

Bunun bir yan ürünü var: yapay zekâyla iyi çalışan bir proje, kendiliğinden devredilebilir bir projedir. Ajanın her sabah okuduğu bilgi, yeni bir geliştiricinin ilk gün okuyacağı bilgiyle aynı. Bu sitenin deposunda bu bilgi şu katmanlarda duruyor:

• Her oturumda okunan bir kurallar dosyası (rules file): depo haritası, komutlar ve her yerde geçerli kurallar.
• Ağacın bir bölümüne bağlı kurallar (path-scoped rules): yalnızca o bölüm düzenlenirken yükleniyor.
• Gerekçeler: bir kuralın neden konduğu, hangi olaydan ya da ölçümden doğduğu.
• Skill'ler: makale yayınlamaktan yedek almaya, dağıtımı ilerletmekten canlı logları okumaya kadar iş biçiminde akışlar (workflows).
• Altyapının kendisi: kodla tanımlanmış (infrastructure as code) izleme kuralları (alert policies) ve tek seferlik kurulum rehberleri.
• Commit mesajları: neyin değiştiğini değil, neden değiştiğini anlatıyor.

Klasik dokümantasyondan farkı, eskidiğinde fark edilmesi. Depoda bir kural var: kodun davranışını değiştiren her değişiklik, eski davranışı anlatan her cümleyi aynı değişiklikte yeniden yazıyor. Kural kendiliğinden işlemiyor, ama çiğnendiğinde saklanamıyor: eskimiş bir cümleyi okuyan ajan ona göre yanlış bir iş yapıyor ve eskimiş cümle kısa sürede görünür bir hataya dönüşüyor. Kimsenin açmadığı bir PDF'te aynı cümle yıllarca fark edilmeden kalabilirdi.

Asıl risk bilgi değil, erişim

Bilginin devri çözülünce geriye daha sessiz bir soru kalıyor: kapılar kimin? Kodun durduğu depo, kodu çalıştıran bulut hesabı, alan adı (domain), fatura hesabı (billing account), dağıtım hattındaki (CI/CD pipeline) anahtarlar (credentials). Bunlar geliştiricinin kişisel hesabındaysa en iyi belgelenmiş depo bile kilitli bir kapının arkasında kalır. Yeni gelen kişi ne yapılacağını biliyordur ama yapamaz.

Bu yüzden müşteri projelerinde dört kuralla çalışıyoruz:

1. Her servis şirket hesabıyla açılır. Şirketin kod deposu hesabı (GitHub organization), bulut hesabı (cloud organization), alan adı, fatura hesabı ve projenin kullandığı her üçüncü taraf servis (third-party service). Kişiye yalnızca erişim verilir. Kişi gidince giden şey yalnızca o erişimdir.
2. Gözetimsiz çalışan her şey bir servis hesabı (service account) ya da fonksiyonel hesap (functional account) kullanır. Dağıtım hattı, çalışan fonksiyonlar (functions), e-posta gönderen eklenti (extension), alarm kanalı (alert channel). Hiçbiri bir insanın oturumuna bağlı değildir.
3. Dağıtım hattında kişisel token olmaz. Bir anahtarı yenilemek (rotate), onu ilk kez alan kişinin hesabına girmeyi gerektirmez.
4. Depoda hiçbir secret'ın değeri durmaz. Depo her anahtarın adını, nerede durduğunu, kime ait olduğunu ve nasıl yenilendiğini söyler. Değerin kendisi onu saklamakla görevli yerde durur: dağıtım hattının secret deposunda (GitHub Secrets), bulutun secret yöneticisinde (Secret Manager), geliştiricinin makinesinde.

Dördüncü kuralın somut karşılığı depoda bir envanter sayfası: hangi servis hangi hesaba ait, dağıtım hattı hangi anahtarları kullanıyor, çalışan sistem hangilerini, geliştirici makinesi hangilerini; her biri nasıl yenileniyor ve devralma (handover) günü hangi sırayla ne yapılıyor.

Kısaca: bilgi depoda, anahtarlar sizde.

Senaryolar

“Geliştirici giderse” tek bir senaryo değil. Her birinin başlangıcı farklı, ama hepsi aynı yere varıyor.

Geliştiriciye yarın ulaşılamıyor

Hastalık, kaza ya da başka bir sebeple. Hazırlık yapılamayan tek senaryo bu, o yüzden ölçüt de bu: hiçbir şey kişinin kendisinden alınamıyorsa ne kalıyor? Kurallara uyulmuşsa her şey. Hesaplar zaten sizin, erişimi siz veriyorsunuz. Yeni gelen geliştirici depoyu klonluyor ve ajan ona sistemin nasıl çalıştığını, sırada ne olduğunu ve neyin nerede durduğunu depodan okuyarak anlatıyor. Eksik kalan tek şey, eski geliştiricinin elindeki erişimler. Onları da siz kaldırıyorsunuz.

Sözleşme bitiyor

Bunu sizin taraf da isteyebilir, bizim taraf da. İki durumda da sırası aynı: önce bizim erişimlerimiz kaldırılıyor, sonra bizim kopyalamış olabileceğimiz her anahtar yenileniyor. Envanter hangi anahtarın nerede durduğunu ve nasıl yenilendiğini söylediği için bu bir pazarlık konusu değil, bir kontrol listesi (checklist). Ayrılan tarafın elinde kalan şey yalnızca deponun bir kopyası oluyor, o da hiçbir kapıyı açmıyor.

İşi kendi ekibinize almak istiyorsunuz

Projenin büyüdüğü ve artık şirket içinde yürümesinin mantıklı olduğu nokta. Ekibiniz depoyu açtığında karşısında bir kara kutu (black box) değil, kendini anlatan bir sistem buluyor. Geçiş bir bilgi aktarımı (knowledge transfer) projesi olmaktan çıkıp bir erişim devrine dönüşüyor.

Başka bir firmaya geçiyorsunuz, ya da başkasının projesini biz devralıyoruz

Aynı senaryonun iki yönü. Yeni firma için başlangıç noktası, yeni bir çalışan için olanla aynı. Ters yönde, başka birinin bıraktığı bir projeyi devraldığımızda ilk işimiz o projeyi bu hâle getirmek oluyor: hesapların sahibini, anahtarların yerini ve sürecin kendisini depoya yazmak. Kendini anlatmayan bir projeyi devralmanın tek güvenli yolu, önce ona kendini anlattırmak.

Ekibe yeni biri katılıyor

Kimsenin gitmediği, yalnızca birinin geldiği senaryo. Yine de aynı akışın provası: yeni kişiye erişim veriliyor, makinesini kuruyor ve ilk sorusunu ajana soruyor. Bir kişiyi işe alıştırmak (onboarding) ile bir projeyi devretmek arasındaki fark, eskisinin erişiminin kaldırılıp kaldırılmadığından ibaret.

Yapay zekânın kaldırmadığı üç şey

Bu yazının iddiası “yapay zekâ her şeyi bilir, kimseye gerek kalmaz” değil. Üç şey hâlâ insana ait ve bilerek öyle.

Erişim ve secret'lar. Bunlar devredilmiyor, yenileniyor. Ajan hangi anahtarın nerede durduğunu söyleyebilir; anahtarın kendisini bilmez ve bilmemelidir.

Onay veren insan. Ajan süreci biliyor ama sorumluluğu almıyor. Bu depoda her değişiklik uzak depoya çıkmadan (push) önce gözden geçiriliyor (code review), gerçek bir ortama yapılan her yazmanın farkı (diff) önce gösteriliyor ve bir insan onaylamadan yazılmıyor. Devralan kişinin o onayı verebilecek yetkinlikte olması gerekiyor. Yani doğru cümle “yeni gelen kusursuzca devam eder” değil, “yeni gelen kaldığı yerden, aynı güvenlik ağlarıyla devam eder”.

Disiplin. Bu yapı kendiliğinden ayakta durmuyor. Davranışı değişen kodun anlatımı aynı değişiklikte güncelleniyor, tekrar eden bir hata bir kurala ya da bir teste dönüşüyor, yeni bir anahtar envantere aynı gün giriyor. Bu yapıyı kurmak ve ayakta tutmak bizim işimiz.

Devralma günü

Kurallara uyulmuş bir projede yeni geliştiricinin ilk günü şöyle görünüyor:

Bu şemayı metin olarak okuyun

Yeni geliştiriciye önce şirket hesabıyla erişim veriliyor: kod deposu, bulut hesabı, alan adı ve fatura hesabı. Aynı yerlerde eski geliştiricinin erişimi kaldırılıyor. Ardından eski geliştiricinin kopyalamış olabileceği her anahtar envanterdeki sırayla yenileniyor. Yeni geliştirici kendi makinesini kuruyor, kendi kimlik bilgileriyle giriş yapıyor, ajanı depoda açıyor ve ona “merhaba” diyor.

1. Erişim şirket hesabı
2. Eski erişim kaldırılır
3. Anahtarlar yenilenir
4. Kurulum kendi makinesi
5. Giriş kendi kimliği
6. Merhaba ilk soru

1. Erişim. Yeni geliştiriciye şirket hesabıyla erişim veriliyor: kod deposu, bulut hesabı, alan adı, fatura hesabı ve projenin kullandığı diğer servisler.
2. Eski erişim. Aynı yerlerde eski geliştiricinin erişimi kaldırılıyor.
3. Anahtarlar. Eski geliştiricinin kopyalamış olabileceği her anahtar, envanterdeki sırayla yenileniyor: dağıtım hattının servis hesabı anahtarları, test token'ları, e-posta servisinin parolası.
4. Kurulum. Yeni geliştirici kendi makinesine depoyu ve bağımlılıkları (dependencies) kuruyor.
5. Giriş. Bulutun ve ajanın komut satırı araçlarına (CLI) kendi kimliğiyle giriş yapıyor.
6. Merhaba. Ajanı depoda açıp “merhaba, sırada ne var?” diyor. Ajan kurallar dosyasını okuyor, iş listesine (backlog) bakıyor ve kaldığı yerden devam ediyor.

Listede bilgi aktarımı diye bir adım yok. Toplantı, devir teslim belgesi (handover document) ya da eski geliştiriciyle geçirilecek bir hafta da yok. Bilginin aktarılacak bir yeri kalmadı, çünkü zaten depoda duruyordu.

Kendi sitemiz: kabul edilen farklar

Bu standardı bu siteye de uyguladım ve envanterini çıkardım. Birkaç yerde bilerek ayrılıyoruz. Biz tek geliştiricili, sahibinin de geliştirici olduğu küçük bir şirketiz ve bazı servislerde kişisel hesap şirket hesabından çok daha ucuz, hatta ücretsiz.

Bu farklar da depoda, envanterin içinde “kabul edilen farklar” başlığıyla yazılı. Her birinin neden kabul edildiği ve bir devirde ne gerektirdiği yanında duruyor. Bilinmeyen bir risk ile kaydedilmiş ve kabul edilmiş bir fark aynı şey değil. Devralan kişi onları sürpriz olarak karşısında bulmaz, listede bulur.

Müşteri projelerinde varsayılan, standardın kendisi. Bir maliyet ya da zaman kısıtı küçük bir farkı mantıklı kılıyorsa, o farka müşteriyle birlikte karar veriyoruz: neyin, neden ve hangi riskle kabul edildiği envantere yazılıyor, karar da müşterinin oluyor.

Sıkça sorulan sorular

Kapanış

Bir yazılım firmasını değerlendirirken sorulacak doğru soru “bu kişiye bir şey olursa ne olur?” değil. Doğru soru şu: “Bu kişi yarın gitse, yerine gelen ilk gün ne yapar?” Cevap bir kontrol listesi ve bir “merhaba” ise, küçük bir firmayla çalışmak bir kişiye değil, bir sisteme bağlanmak demek.

Mevcut projenizin bu soruya ne cevap verdiğini birlikte çıkarmak isterseniz iletişim sayfasından yazın. Başlamak için hesaplarınızın listesi ve deponuza bir bakış yeterli.

Bu yazı bir serinin dördüncüsü. Sistemin neden kurulduğu: GCP Maliyeti: Bir Kararın 8 Yıllık Faturası. Nasıl çalıştığı: Ziyaret Ettiğiniz Mimari: Bu Site GCP'de Nasıl Çalışıyor? Nasıl geliştirildiği: Claude Code CLI ve Antigravity CLI: Kural Nerede Durmalı?