Dokümantasyon sapması için Claude Code: dokümanları koda uyumlu tutun

Dokümantasyon sapması nedir (ve neden sürekli oluyor)\n\nDokümantasyon sapması, dokümanlarınızın söyledikleriyle kodunuzun gerçekte ne yaptığı arasındaki yavaş ayrışmadır. Küçük uyumsuzluklarla başlar, sonra “geçen ay işe yarıyordu” kafa karışıklığına dönüşür.\n\nGerçek bir ekipte sapma şöyle görünür: README bir servis için tek bir komutla çalıştırılabileceğini söyler, ama yeni bir ortam değişkeni şimdi gereklidir. API dokümanları bir alanın yeniden adlandırıldığını gösterir. Bir runbook çağrı ekibine "worker-a"yı yeniden başlatmasını söyler, ancak süreç şimdi iki servise bölünmüştür.\n\nSapma, iyi niyetle bile olur çünkü yazılım, dokümantasyon alışkanlıklarından daha hızlı değişir. İnsanlar baskı altında düzeltmeleri yayınlar, eski örnekleri kopyalar veya dokümanları sonradan bir başkasının güncelleyeceğini varsayar. Ayrıca "gerçek kaynak" gibi görünen çok fazla yer olduğunda büyür: README dosyaları, API referansları, dahili wiki sayfaları, ticket'lar ve sözlü bilgi.\n\nMaliyetler somuttur:\n\n- İşe alım bozulur (yeni çalışanlar kurulum sorunları yüzünden günler kaybeder).\n- Dağıtımlar başarısız olur (adımlar mevcut konfigürasyonla eşleşmez).\n- Destek yükü artar (kullanıcılar güncel olmayan talimatları izler).\n- Olaylar uzar (runbook'lar müdahalecileri yanlış yöne yönlendirir).\n\nYazıyı cilalamak, gerçekler yanlışsa sapmayı düzeltmez. Yardımcı olan, dokümanları doğrulanabilir bir şey gibi ele almaktır: bunları mevcut koda, konfigürasyonlara ve gerçek çıktılara karşı karşılaştırın, sonra dokümanların vaat ettiği ama kodun artık sağlamadığı davranışların çelişkilerini ortaya çıkarın.\n\n## Sapmanın görüldüğü yerler: README, API dokümanları ve runbook'lar\n\nSapma genellikle insanların "hızlı referans" olarak gördüğü belgelerde ortaya çıkar. Bir kez güncellenirler, sonra kod hareket etmeye devam eder. Kontrol edebileceğiniz somut vaatler içerdiği için bu üçüyle başlayın.\n\n### README: kullanıcıların ilk acıyı hissettiği yer\n\nGünlük komutlar değiştiğinde README'ler sapar. Yeni bir bayrak eklenir, eski bir bayrak kaldırılır veya bir ortam değişkeni yeniden adlandırılır, ama kurulum bölümü hala eski gerçeği gösterir. Yeni ekip üyeleri örnekleri kopyala-yapıştır yapar, hatalarla karşılaşır ve projenin bozuk olduğunu varsayar.\n\nEn kötü versiyon "neredeyse doğru" olandır. Bir eksik ortam değişkeni, tamamen güncelliğini yitirmiş bir README'den daha fazla zaman kaybettirebilir, çünkü insanlar küçük varyasyonları tekrar denerler yerine dokümanı sorgulamaya başlamanın.\n\n### API dokümanları: uyumsuz şemalar ve yanıltıcı örnekler\n\nAPI dokümanları, istek veya yanıt alanları değiştiğinde sapar. Küçük değişimler bile (yeniden adlandırılan anahtarlar, farklı varsayılanlar, yeni zorunlu başlıklar) istemcileri kırabilir. Genellikle endpoint listesi doğruyken örnekler yanlıştır; kullanıcıların tam olarak kopyaladığı şey budur.\n\nTipik sinyaller:\n\n- Örnek yükler sunucunun artık kabul etmediği alanları içerir.\n- Yanıt örnekleri eski hata formatlarını veya durum kodlarını gösterir.\n- Parametre tabloları artık zorunlu olan alanları isteğe bağlı olarak gösterir.\n- Kimlik doğrulama notları artık çalışmayan başlıkları veya scope'ları bahseder.\n- Sayfalandırma, sıralama veya filtreleme kuralları gerçekle eşleşmez.\n\n### Runbook'lar: sessiz sapma, yüksek sesli olaylara neden olur\n\nRunbook'lar dağıtım, geri alma veya işletme adımları değiştiğinde sapar. Bir eski komut, yanlış servis adı veya eksik önkoşul rutin bir düzeltmeyi kesintiye uğratıp kesintiye yol açabilir.\n\nAyrıca "doğru ama eksik" olabilirler: adımlar hâlâ çalışır, ancak yeni bir migration, bir önbellek temizliği veya bir özellik bayrağı geçişini atlarlar. Bu durumda müdahaleciler runbook'u mükemmel şekilde uygular ama yine de şaşırır.\n\n## Claude Code nasıl kullanılır: diff'ler ve çelişki çağrıları\n\nClaude Code for documentation drift, dokümanları kod gibi ele aldığınızda en iyi şekilde çalışır: küçük, incelenebilir bir yama önerin ve nedenini açıklayın. README'yi "güncelle" demek yerine, belirli dosyalara karşı bir diff oluşturmasını isteyin. İnceleyenler net bir önce/sonra görür ve istenmeyen değişiklikleri çabucak fark edebilir.\n\nİyi bir sapma kontrolü iki şey üretir:\n\n1) Minimum bir diff\n2) Dürüst ve spesifik bir çelişki raporu: "Doküman X diyor, depo Y gösteriyor."\n\n### Görgü kanıtı isteyin, görüş değil\n\nPrompt atarken repodan kanıt isteyin: dosya yolları ve şu davranışı gösteren rotalar, konfigürasyon değerleri veya testler gibi ayrıntılar.\n\nAşağıda bunu sağlam tutan bir prompt kalıbı var:\n\n\nCheck these docs for drift: README.md, docs/api.md, runbooks/deploy.md.\nCompare them to the current repo.\nOutput:\n1) Contradictions list (doc claim -\u003e repo evidence with file path and line range)\n2) Unified diffs for the smallest safe edits\nRules: do not rewrite sections that are still accurate.\n\n\nClaude "API v2 kullanıyor" diyorsa, bunu router, OpenAPI şeması veya bir entegrasyon testi ile desteklemesini isteyin. Eğer kanıt bulamazsa, bunu söylemeli.\n\n### Düzenlemeden önce kapsamı belirleyin\n\nSapma genellikle tek bir kod değişikliğiyle başlar ve bu sessizce birden çok dokümanı etkiler. Önce Claude'a etki alanını belirlemesini isteyin: ne değişti, nerede değişti, hangi dokümanları muhtemelen bozdu ve hangi kullanıcı eylemleri etkilendi.\n\nÖrnek: bir ortam değişkeni API_KEY'den SERVICE_TOKEN'a yeniden adlandırılır. Faydalı bir rapor, eski adın geçtiği her yeri bulur (README kurulum, API örnekleri, runbook secret bölümü) ve sadece o satırları ve şimdi başarısız olacak örnek komutları güncelleyen sıkı bir diff üretir.\n\n## Prompt atmadan önce basit bir iş akışı kurun\n\nModele "tüm dokümanları" kurallar olmadan gösterirseniz, genellikle yanlış gerçekleri içeren yeniden yazılmış metinler alırsınız. Basit bir iş akışı değişiklikleri küçük, tekrarlanabilir ve gözden geçirilebilir tutar.\n\nBir doküman setiyle başlayın: README, API referansı veya gerçekten kullanılan bir runbook. Bir alanı baştan sona düzeltmek, kullanacağınız güvenilir sinyallerin ne olduğunu öğretir ve sonra ölçeklendirmeyi kolaylaştırır.\n\n### Gerçek kaynak olarak sayılacakları kararlaştırın\n\nO doküman seti için gerçeklerin nereden gelmesi gerektiğini düz yazıyla belirtin.\n\n- README için: CLI yardım çıktısı ve çalışan bir örnek uygulama.\n- API dokümanları için: router tanımları ve entegrasyon testleri.\n- Runbook'lar için: dağıtım konfigürasyonu ve prosedürü tetikleyen alarmlar.\n\nKaynakları adlandırdıktan sonra prompt'lar daha net olur: "README'yi mevcut CLI çıktısı ve konfigürasyon varsayılanlarıyla karşılaştır, sonra bir yama oluştur."\n\n### İnceleyicilerin hızlıca doğrulayabileceği bir çıktı seçin\n\nİlk kontrolü çalıştırmadan önce çıktı formatında anlaşın. Karışık formatlar neyin değiştiğini ve nedenini görmekte zorlaştırır.\n\nBasit bir kural seti:\n\n- Her doküman değişikliği için bir diff ve bir cümlelik neden isteyin.\n- Araç güvenle öneremediğinde kısa bir çelişki listesine izin verin.\n- Mümkünse diffları dosya başına bir değişiklikle sınırlandırın.\n- Başarısız örnekleri (komutlar, istekler, kod parçacıkları) genel ifadelerden daha yüksek öncelik verin.\n\nPratik bir alışkanlık: her doküman PR'sine küçük bir not ekleyin: "Source of truth checked: routes + tests" böylece inceleyenler hangi karşılaştırmanın yapıldığını bilir. Bu, doküman güncellemelerini "tamam gibi" yerine "gerçek bir şeye karşı doğrulandı" haline getirir.\n\n## Adım adım: her değişiklikte dokümanları kodla uyumlu tutun\n\nHer kod değişikliğini küçük bir doküman soruşturması gibi ele alın. Amaç çelişkileri erken yakalamak ve inceleyicilerin güvenebileceği minimal bir yama üretmektir.\n\nBaşlangıç: hangi dosyaların kontrol edileceğini ve net bir sapma sorusunu seçin. Örneğin: "Herhangi bir ortam değişkeni, CLI bayrağı, HTTP rotası veya hata kodunda dokümanların hala bahsettiği bir değişiklik oldu mu?" Spesifik olmak, modelin bütün bölümleri yeniden yazmasını engeller.\n\nSonra Claude Code'dan önce koddan sert gerçekleri çıkarmasını isteyin. Sadece somut öğeleri listelemesini isteyin: kullanıcıların çalıştırdığı komutlar, endpoint'ler ve metodlar, istek ve yanıt alanları, konfigürasyon anahtarları, gerekli ortam değişkenleri ve script veya konfigürasyonlarla referans verilen işletme adımları. Eğer bir şey kodda bulunmuyorsa "bulunamadı" demelidir, tahminde bulunmamalıdır.\n\nArdından basit bir karşılaştırma tablosu isteyin: doküman iddiası, kodun gösterdiği ve bir durum (eşleşiyor, uyuşmuyor, eksik, belirsiz). Bu tartışmayı somut tutar.\n\nBundan sonra, minimal düzenlemelerle bir birleşik diff isteyin. Sadece uyumsuzlukları çözmek için gereken satırları değiştirmesini, dokümanın mevcut stilini korumasını ve kod tarafından desteklenmeyen vaatler eklemekten kaçınmasını söyleyin.\n\nSon olarak kısa bir inceleyici özetiyle bitirin: ne değişti, neden değişti ve iki kere kontrol edilmesi gerekenler (ör. yeniden adlandırılan bir ortam değişkeni veya yeni bir zorunlu header).\n\n## API dokümanları: endpointleri ve örnekleri doğrulamanın pratik yolu\n\nAPI dokümanları kod sessizce değiştiğinde sapar: bir rota yeniden adlandırılır, bir alan zorunlu olur veya bir hata şekli değişir. Sonuç kırık istemci entegrasyonları ve boşa geçen hata ayıklama süresi olur.\n\nClaude Code for documentation drift ile iş, repodan API'nin ne yaptığını kanıtlamak ve sonra dokümanlardaki uyumsuzluklara işaret etmektir. Router ve handler'lardan bir envanter çıkarmasını (yollar, metodlar, istek ve yanıt modelleri) ve bunu API referansının iddialarıyla karşılaştırmasını isteyin.\n\nİnsanların gerçekten kopyala-yapıştır yaptığı şeylere odaklanın: curl komutları, header'lar, örnek payload'lar, durum kodları ve alan adları. Tek bir prompt'ta şunları kontrol etmesini isteyin:\n\n- Kimlik doğrulama gereksinimleri (header'lar, token türü, public endpoint'ler)\n- Sayfalandırma parametreleri ve varsayılanlar\n- Hata durum kodları ve JSON formatı\n- Versiyonlama davranışı (v1 vs v2)\n- Örneklerin mevcut doğrulama kurallarıyla eşleşip eşleşmediği\n\nUyumsuzluk bulduğunda, yalnızca koddan kanıt (tam rota tanımı, handler davranışı veya şema) gösterebildiği diffları kabul edin. Bu yamaları küçük ve gözden geçirilebilir tutar.\n\nÖrnek: kod artık POST /widgets için 201 döndürüyor ve name alanını zorunlu kılıyor. Dokümanlar hala 200 gösteriyor ve name'i atlıyor. İyi bir çıktı hem çelişkileri bildirir hem de yalnızca o endpoint'in durum kodu ve örnek JSON'unu günceller, geri kalanını dokunmadan bırakır.\n\n## Runbook'lar: eskimiş prosedürlerin neden olduğu kesintileri azaltın\n\nRunbook'lar en pahalı şekilde başarısız olur: tamamlanmış gibi görünürler ama adımlar artık sistemin bugün yaptıklarıyla eşleşmez. Yeniden adlandırılmış bir ortam değişkeni veya yeni bir dağıtım komutu gibi küçük bir değişiklik, müdahale edenlerin talimatları uygularken başarısız olmasına neden olabilir.\n\nRunbook'u kod gibi ele alın: mevcut repoya karşı bir diff isteyin ve çelişki çağrılarını zorunlu kılın. Bunu sistemin şu an ne kullandığıyla karşılaştırın: script'ler, konfigürasyon varsayılanları ve mevcut araçlarınız.\n\nOlay sırasında en çok karışıklığa yol açan hata noktalarına odaklanın:\n\n- Listelenen komutlar mevcut script'lerle ve bayraklarla eşleşiyor mu?\n- "Varsayılan" konfigürasyon değerleri uygulamanın şu anlaştığı değerlerle uyuyor mu?\n- Gerekli ortam değişkenleri ve secret'lar kod ve deploy konfigürasyonunda referanslanıyor mu?\n- Dağıtım ve geri alma adımları mevcut sürüm aracınızın adlandırmasıyla eşleşiyor mu?\n- "İyi bilinen" değerler (portlar, bölgeler, zaman aşımı) hâlâ gerçeklikle uyuşuyor mu?\n\nAyrıca müdahalecilerin yolunda olup olmadığını hızlıca anlayabilmeleri için kısa ön kontroller ve beklenen çıktılar ekleyin. "Çalıştığını doğrula" yeterli değil; beklenen sinyali (bir durum satırı, bir versiyon stringi veya bir sağlık kontrol cevabı) belirtin.\n\nEğer Koder.ai gibi platformlarda uygulama oluşturup dağıtıyorsanız, bu daha da önem kazanır çünkü anlık görüntüler ve geri alma yalnızca runbook doğru eylemi adlandırdığında işe yarar.\n\n## Sapmayı daha kötü yapan yaygın hatalar\n\nDokümanları "güzel metin" olarak ele almak, sapma yaratmanın en hızlı yoludur; oysa dokümanlar kodla eşleşmesi gereken iddialar setidir.\n\n### Hizalamayı sessizce bozan hatalar\n\nYaygın bir hata önce yeniden yazma istemektir. Çelişki kontrolünü atlarsanız, hâlâ yanlış davranışı tanımlayan daha düzgün bir metinle sonuçlanabilirsiniz. Her zaman önce sor: doküman ne iddia ediyor, kod ne yapıyor ve nerede uyuşmuyorlar.\n\nBir diğer hata modelin tahmin etmesine izin vermektir. Eğer bir davranış kodda, testlerde veya konfigürasyonda görünmüyorsa, bilinmiyor sayın. "Muhtemelen" README vaatlerinin icadı ve runbook'ların kurguya dönüşmesinin yoludur.\n\nBu problemler günlük güncellemelerde sık görülür:\n\n- Bir bölümü güncellemek ama örnekleri, hata mesajlarını ve kenar durumları dokunmadan bırakmak