ile ne değişti? Zamansız prensipler Claude Code ile pratik Öneriler SOLID, Clean Code, test, mimari · Repo, .claude dizini, agent akışı · Kavram, tarihçe 4K 1A · AI Connect Istanbul Rakamlar ve yeni borç türleri · Repolar ve kitaplar · 03
“İlk sürüm kodu göndermek borçlanmak gibidir. Küçük bir borç, hemen bir yeniden yazımla ödendiği sürece geliştirmeyi hızlandırır. Tehlike, borç ödenmediğinde başlar: tam doğru olmayan kodla geçirilen her dakika o borcun faizidir.” — Ward Cunningham, “The WyCash Portfolio Management System”, OOPSLA 1992 (çeviri) 4K 1A · AI Connect Istanbul NEDEN “BORÇ”? Cunningham bir portföy yönetim yazılımı yazıyordu; finansçı müşterilere “şimdi gönderelim, sonra düzeltelim” kararını anlatmak için onların dilini seçti. Metafor baştan beri bilinçli bir takası anlatıyordu, özensizliği değil. 05
iş — ve o işin üzerine her değişiklikte işleyen faiz. ANAPARA FAİZ AYRIM Eksik test, kestirme tasarım, geçici çözüm, güncellenmeyen bağımlılık, yazılmayan doküman. Her değişiklikte ödenen ek süre, yeni hata, “buna dokunmayalım” korkusu, yavaşlayan onboarding. Borç kötü değildir; farkında olmadan alınan ve ödenmeyen borç kötüdür. Dağınık kod ise borç değil, düpedüz zarardır. “A mess is not a technical debt” — Robert C. Martin, 2009 06
DİKKATSİZ · FARKINDA OLMADAN “Tasarıma ayıracak vaktimiz yok.” “Katmanlama ne demek?” AI çağının tuzağı: agent üretir, kimse okumaz, borcun varlığı bile bilinmez. İHTİYATLI · BİLİNÇLİ İHTİYATLI · FARKINDA OLMADAN “Şimdi gönderelim; sonuçlarını biliyoruz, sonra öderiz.” “Şimdi anlıyoruz; aslında nasıl yapmalıymışız.” Kaynak: martinfowler.com/bliki/TechnicalDebtQuadrant Yatay eksen: borç bilinçli mi alındı? Dikey eksen: alan kişi ihtiyatlı mıydı? Hedef sağ alt çeyrek değil; hedef hangi çeyrekte olduğunu bilmek. 07
Mimari borç Test borcu Kopya-yapıştır, dev fonksiyonlar, anlamsız isimler, ölü kod. Bulanık sınırlar, döngüsel bağımlılık, “her şeyi bilen” servis. Eksik, kırılgan ya da yalnızca mutlu yolu gezen testler. Dokümantasyon borcu Bağımlılık borcu Bilgi borcu Neden böyle yapıldığı hiçbir yerde yazmıyor; kararlar kafalarda. Eski sürümler, elle yapılan deploy, tekrar üretilemeyen ortam. Sistemi yalnızca bir kişi anlıyor; o kişi gidince faiz ikiye katlanıyor. 4K 1A · AI Connect Istanbul 08
pencere, binanın terk edilmiş olduğu mesajını verir; kısa sürede diğer camlar da kırılır. The Pragmatic Programmer (1999) bunu koda taşıdı: kötü bir örnek, yeni kötü örnekleri davet eder. Sonuç, değişim maliyeti eğrisidir: borç ödenmedikçe her yeni özellik bir öncekinden pahalıya çıkar. Agent, repodaki kalıpları örnek alır. Kırık pencere varsa onu da çoğaltır Hunt & Thomas, The Pragmatic Programmer, 1999 · Değişim maliyeti Borç ödenmeyince Düzenli refactor ile Zaman 09
Geliştirici zamanının teknik borçla geçen payı: haftada yaklaşık 13,5 saat Haftada bakım işlerine giden saat: hata ayıklama, refactor, kötü kodu düzeltme ABD'de birikmiş teknik borcun tahmini büyüklüğü: 1,52 trilyon dolar (2022) Stripe, The Developer Coefficient, 2018 Stripe, aynı araştırma (41 saatlik haftada) CISQ, Cost of Poor Software Quality in the US, 2022 Yani sorun yeni değil. Yeni olan, borcun alınma hızı. Kaynaklar: stripe.com/reports/developer-coefficient-2018 · it-cisq.org/cpsq-2022 10
review Lint, statik analiz Refactoring ve XP Sürekli entegrasyon Fagan: hatayı üretimden önce ikinci göz bulur. Makinenin yakalayabildiğini insana bırakma. Fowler ve Beck: küçük adım, önce test, pair. Her commit'te build ve test; kırık dal yasak. 2000 2008 2011 2014 SOLID Clean Code ADR DORA metrikleri Robert C. Martin'in beş tasarım ilkesi. Okunabilirlik zevk değil, bakım maliyeti. Nygard: mimari kararı gerekçesiyle repoya yaz. Teslimat hızı ve kararlılığını birlikte ölç. 4K 1A · AI Connect Istanbul 11
prompt, bin satır. Boş dosya korkusu bitti; “bir şeyler yazmak” artık darboğaz değil. Okumanın, anlamanın, sahiplenmenin maliyeti Aynı kaldı. Bin satırı okumak, doğrulamak ve üç ay sonra savunabilmek hâlâ insan zamanı istiyor. Darboğaz yazmaktan doğrulamaya kaydı. Borç bu makasta birikir. 4K 1A · AI Connect Istanbul 14
Herkes kullanıyor, kimse tam güvenmiyor %84 %46 %66 AI araçlarını kullanıyor ya da kullanmayı planlıyor Çıktının doğruluğuna güvenmiyor (2024: %31) 1 numaralı şikâyet: “neredeyse doğru ama tam değil” çözümler “Neredeyse doğru” kod, yanlış koddan daha pahalıdır: hatayı bulmak için önce doğru olduğuna inanmayı bırakmanız gerekir. Kaynak: survey.stackoverflow.co/2025 15
DEĞİŞEN SATIR, 2020–2024 Kod kopyalanıyor, taşınmıyor 8× 2024'te komşu koda benzeyen 5+ satırlık kopya blokların sıklığı sekiz kat arttı %46 Değişikliklerin yeni satır olma oranı; kopyalanan satırlar ilk kez taşınan satırları geçti NEDEN “TAŞINAN KOD” ÖNEMLİ? Taşınan kod, refactor'un imzasıdır: bir parça yeniden kullanılmak üzere doğru yere alınır. Taşıma azalıp kopyalama artıyorsa, sistem yeniden kullanmak yerine çoğaltıyor demektir. “Refactored systems, in general, and moved code in particular, are the signature of code reuse.” — Bill Harding, GitClear Kaynak: gitclear.com/ai_assistant_code_quality_2025_research · anonim özel repolar + 25 büyük açık kaynak proje 16
yavaşladılar, hızlı sandılar %19 +%24 +%20 AI izinli görevlerde daha yavaş tamamlama (ölçülen) Deneyden önce beklenen hızlanma Deneyden sonra hâlâ hissedilen hızlanma KURGU OLASI NEDENLER 16 deneyimli geliştirici, 246 gerçek görev, kendi olgun repoları (~10 yıl, 1M+ satır); her görev rastgele AI izinli / izinsiz; ekran kaydıyla doğrulama. Yüksek repo aşinalığı · büyük ve karmaşık kod tabanı · üretimlerin %44'ünden azının kabul edilmesi · ajanın bilmediği örtük bağlam · aşırı iyimserlik. Kaynak: metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study 17
~5.000 KATILIMCI AI bir amplifikatördür Throughput ile artık pozitif ilişki 2024'te negatifti; 2025'te ekipler daha fazla teslim ediyor. Instability artmaya devam ediyor Daha çok değişiklik, daha çok kırılma; “hızlı boz, hızlı düzelt” bunu dengelemiyor. ~%90 kullanım, %80+ “daha üretkenim” Tükenmişlik ve sürtüşme değişmedi: AI yükü azaltmıyor, çıktıyı artırıyor. DORA AI CAPABILITIES MODEL · 7 YETENEK Net ve paylaşılmış AI politikası Sağlıklı veri ekosistemi AI'ın erişebildiği iç veri ve bağlam Güçlü sürüm kontrolü pratikleri Küçük partilerle çalışmak Kullanıcı odaklılık Kaliteli iç platform Güçlü ekipleri güçlendiriyor, zayıf ekiplerin sorunlarını büyütüyor. Kaynak: dora.dev/research/2025 · Yetenekler ekip ve kurum düzeyinde çalışır, bireysel araç kullanımıyla değil 18
AI üretimi kod örneklerinin OWASP Top 10 güvenlik testlerinden kalma oranı; Java'da %72, XSS'te %86 AI'ın önerdiği bağımlılıkların var olmama oranı: paket halüsinasyonu (576.000 Python/JS örneği) AI bağlantılı yeni CVE sayısı Ocak'ta 6, Mart 2026'da 35; gerçek sayının 5–10 kat fazla olduğu tahmin ediliyor Veracode, GenAI Code Security Report 2025 Spracklen vd., USENIX Security 2025 Georgia Tech, Vibe Security Radar 2026 Güvenlik borcu Açıklar, ekiplerin inceleyebildiğinden hızlı birikiyor. Öneri: AI kodunu doğrulanmamış girdi gibi ele al; SAST/SCA'yı CI'da zorunlu kapı yap; önerilen paketin registry'de var olduğunu doğrula. Cloud Security Alliance, 2026 Derleme: CSA Research Note “Vibe Coding Security Debt” (2026) ve atıf yaptığı birincil kaynaklar 19
· 2025 Vibe coding'in altı borç türü 1 · GEREKSİNİM BELİRSİZLİĞİ 2 · MİMARİ TUTARSIZLIK 3 · GÜVENLİK AÇIKLARI Üretilen spec cilalı görünür; gereksiz özellik ekler, güvenlik ve performans gereksinimlerini atlar. Yeniden üretilen modüller yama yapısı kurar; değişen kimlik doğrulama bağımlı servisleri kırar. 7 MVP taramasında 970 bulgu, 801'i yüksek önem: güvensiz girdi, dosya işlemi, açıkta kimlik bilgisi. 4 · BAKIM YÜKÜ 5 · TEST BOŞLUKLARI 6 · DEPLOY KIRILGANLIĞI Kopya modüller, ölü dosyalar, çelişen mantık; kopya bir DB modülü sessiz çalışma zamanı hataları verdi. Yalnızca mutlu yol ve önemsiz mock'lar: giriş akışı bozukken kimlik doğrulama testleri geçiyordu. Tek başına çalışan servisler entegrasyonda düşer: bağımlılık, ortam değişkeni, port çakışması. Önerileri: prompt'ları versiyonla, CI'a güvenlik kapısı ekle, Definition of Done olmadan üretime çıkma. Nitel deneyim raporu; tarama 0,5–6 bin satırlık yedi MVP üzerinde tek araçla yapıldı 20
Agent her oturumda projeyi sıfırdan öğreniyor; aynı açıklamayı onuncu kez yapıyorsun. Faiz: her oturumda token ve zaman; tutarsız kararlar. Belirti: kodu üreten prompt hiçbir yerde yok; sonuç tekrar üretilemiyor. Faiz: “neden böyle yapılmış?” sorusunun cevabı kayıp. Anlaşılmamış kod borcu Agent-konfigürasyon borcu Belirti: merge edildi, çalışıyor, ekipte kimse açıklayamıyor. Faiz: ilk üretim hatasında ödenir; bilgi borcunun agent sürümü. Belirti: 600 satırlık CLAUDE.md, birbiriyle çelişen kurallar, kimsenin bakmadığı skill'ler. Faiz: Agent talimatları görmezden gelmeye başlar. 4K 1A · AI Connect Istanbul 21
AI notu İlke Özü Agent için anlamı S (Single Responsibility) · Tek sorumluluk Bir sınıfın, modülün veya fonksiyonun yalnızca bir tane sorumluluğu (değişim sebebi) olmalıdır. Yani bir yapı sadece tek bir işi yapmalıdır. Agent repoda ne görürse onu örnek alır. Her işi yapan dev bir sınıf varsa yeni işi de oraya ekler; sınıf büyüdükçe daha da büyür. Küçük ve tek işli sınıflar varsa yeni kodu da öyle yazar. O · Open/Closed Principle Yazılım varlıkları (sınıflar, modüller, fonksiyonlar) gelişmeye (genişlemeye) açık, ancak değişime kapalı olmalıdır. Mevcut kodu bozmadan yeni özellikler eklenebilmelidir Kodun uzantı noktaları varsa agent’a “mevcut kodu değiştirmeden ekle” diyebilirsiniz ve yeni özellik eklenti olarak gelir. Uzantı noktası yoksa agent çalışan kodun içini değiştirir; her yeni özellik eskisini bozma riski taşır. L · Liskov yerine geçme(substituion) prensibi Alt sınıflardan oluşan nesneler, programın işleyişini bozmadan üst sınıfların (base class) yerini alabilmelidir. Kalıtım alan sınıflar, üst sınıfın tüm özelliklerini ve kurallarını düzgün bir şekilde karşılamalıdır Agent bir alt sınıf yazarken “metot adı ve tipleri uyuyor, demek ki çalışır” diye düşünür; üst sınıfın yazılı olmayan kurallarını (örneğin “bu metot asla boş liste dönmez”) bilemez. Bu kuralları test olarak yazdırırsanız agent da onlara uymak zorunda kalır. I · Arayüz ayrımı( Interface Segregation) Hiçbir sınıf, kullanmadığı metotları içeren büyük bir arayüze (interface) bağımlı olmaya zorlanmamalıdır. Bunun yerine, daha özelleştirilmiş ve küçük arayüzler tercih edilmelidir. Agent’ın okuduğu her dosya bağlam penceresinden yer harcar. Arayüzler küçükse yalnızca ilgili birkaç dosyayı okur; hem ucuza hem daha az hatayla çalışır. Devasa bir arayüz onu her şeyi okumaya zorlar. D · Bağımlılığı tersine çevirme (Dependency Inversion) Yüksek seviyeli sınıflar, düşük seviyeli sınıflara doğrudan bağımlı olmamalıdır; her ikisi de soyutlamalara (abstractions/interface) dayanmalıdır. Port/adapter sınırları, ajana “buraya dokunma” diyen path-scoped kurallara dönüşür. 4K 1A · AI Connect Istanbul 24
Küçük fonksiyonlar İsim, yorumu gereksiz kılmalı. Tek iş, tek soyutlama düzeyi. Yorum yerine niyet DRY (Don't Repeat Yourself) Kod “ne”yi, yorum “neden”i anlatır. Her bilgi parçasının tek bir yetkili kaynağı olmalı. KISS (Keep It Simple Stupid) Çalışan en basit şey, zeki olanı yener. YAGNI (You Aren't Gonna Need It) AI NOTU YAGNI, ajanların en sık ihlal ettiği ilke: istenmeyen parametreler, “ileride lazım olur” yapılandırmaları, fazladan uç noktalar. Karşı önlem: prompt'ta “yalnızca isteneni, en az değişiklikle” de; review'da her yeni soyutlama için “bu neden var?” sor; büyük diff başarı değil, şüphe işareti. İhtiyacın olmayacak: isteninceye kadar yapma. 4K 1A · AI Connect Istanbul 25
düzenle, sonra değiştir REFACTORING TIDY FIRST? İZCİ KURALI Dış davranışı değiştirmeden iç yapıyı iyileştirmek. Küçük, güvenli, test destekli adımlar; büyük patlama yok. Kent Beck: değişikliği kolaylaştıran küçük düzenlemeleri önce yap, sonra asıl değişikliği. İkisini ayrı commit'lerde tut. Kamp yerini bulduğundan daha temiz bırak. Her dokunuşta küçük bir iyileştirme; borcu taksitle öde. AI NOTU Refactor ile özelliği aynı PR'a koyma. Ajana açıkça söyle: “önce yalnızca refactor PR'ı, davranış değişmeden, testler yeşil; sonra ayrı bir PR'da özellik.” Diff okunur kalır, review mümkün olur; ajan da dağılmaz. 4K 1A · AI Connect Istanbul 26
az Entegrasyon · orta Birim · çok, hızlı, kararlı Üst katmanlar pahalı ve kırılgan; tabanı geniş tut. 1 · Kırmızı: başarısız test 2 · Yeşil: en az kod 3 · Refactor AI NOTU Testi önce yazdır, kodu sonra: agent “bitti” demeden önce koşabileceği bir kontrol olur. Kontrol yoksa doğrulama döngüsü sensin. Mutlu yol tuzağı: agent geçen test yazmaya meyillidir. Sınır durumlarını, hata yollarını ve “bu test gerçekten kırılabilir mi?” sorusunu insan belirler. Çare: testi yazan ajan ile kodu yazan ajanı ayır. 4K 1A · AI Connect Istanbul 27
· PORT VE ADAPTER DDD · BOUNDED CONTEXT BAĞIMLILIK KURALI Alistair Cockburn, 2005 Domain-Driven Design, Eric Evans,2003 Clean Architecture İş mantığı ortada, dış dünya (DB, HTTP, kuyruk, LLM sağlayıcısı) adapter'larda. Sağlayıcı değişince çekirdek değişmez. AI NOTU “Başvuru”, “Ödeme”, “Belge” ayrı sözlükler, ayrı modeller. Aynı kelime iki bağlamda farklı şey demek olabilir; bu normaldir. Bağımlılıklar içeri doğru akar. Dış katman iç katmanı bilir, tersi asla. Bu kural bir araçla zorlanabilir. Net sınır, agent için iki şey demek: daha az bağlam (yalnızca ilgili modülü okur) ve yazılabilir kural (“payment/, ai-endpoint'i doğrudan çağıramaz” hem bir rule hem bir import-linter kuralı olur). Sınırsız mimaride ajana “nereye dokunma” diyemezsin. 4K 1A · AI Connect Istanbul 28
insana talimat Şimdi: mekanizma Tek sorumluluk, sınırlar Review'da “bu sınıf çok büyümüş” import-linter kuralı + path-scoped rule DRY Review'da dikkatli göz jscpd kopya tespiti CI'da; eşik aşılınca kırmızı Test “Test yazmayı unutma” CI kapısı + Stop hook: test geçmeden bitiş yok Stil ve biçim Stil rehberi dokümanı PostToolUse hook'unda formatter; tartışma yok Güvenlik Güvenlik eğitimi semgrep + secret tarama; PreToolUse'da engel Konvansiyon “Commit mesajı şöyle olsun” commitlint + Conventional Commits; sürüm otomatik Bağlam ve kararlar Wiki ve kafalar CLAUDE.md + rules/ + ADR; hepsi git'te Sağ sütundaki araçların hepsi beşinci bölümde 29
Ne zaman yüklenir? Ne için? Ne Yazılır? CLAUDE.md Her oturumda ve kompaksiyonda Her zaman geçerli gerçekler make check, dal adı, tuzaklar rules/*.md paths: varsa dosyaya dokununca Konuya göre bölünmüş kurallar payment/** için PCI kuralları skills/<ad>/SKILL.md Ad başta; gövde çağrılınca 30+ satırlık prosedürler /dev-workflow, /release commands/*.md Yalnızca sen yazınca Elle tetiklenen kısa komutlar /project:changelog agents/*.md Delege edilince; izole bağlam Yan görevler, uzman roller pm, backend, frontend, ai hooks (settings.json) Olaylarda, her seferinde Deterministik kapılar PostToolUse → ruff/biome settings.json / .local Her araç çağrısında İzinler: allow · deny · sor deny: rm -rf, .env okuma Proje .claude/ git'e girer, ekip paylaşır; ~/.claude/ kişisel. Kapsamsız bir rule, CLAUDE.md gibi her oturumda yüklenir. Kaynak: code.claude.com/docs · claude.com/blog/steering-claude-code 32
komutlar: make check, tek test koşturma Varsayılandan farklı stil kuralları Repo düzeni: dal isimleri, PR şeması Projeye özgü mimari kararlar Ortam farklılıkları: zorunlu env değişkenleri Kendiliğinden anlaşılmayan tuzaklar <200 satır. Her satır için: “silsem hata yapar mı?” İndeks gibi. @path ile içe aktar, detayı skill'e taşı Kodu okuyarak anlaşılabilecek her şey Dilin standart konvansiyonları Ayrıntılı API dokümantasyonu (link ver) Sık değişen bilgiler Dosya dosya kod tabanı anlatımı “Temiz kod yaz” gibi kendiliğinden açık öğütler Kod gibi. Git'te, sahibi var, review'dan geçer Araçla. /init ile başlat, /doctor ile buda Kaynak: code.claude.com/docs/en/best-practices · “Şişmiş CLAUDE.md, asıl talimatların görmezden gelinmesine yol açar” 33
"services/payment/**" - "**/*.payment.ts" --Ödeme servisinde: - Kart verisi (PAN, CVV) hiçbir log satırına yazılmaz. - Ödeme sağlayıcısına yalnızca providers/ altındaki adapter üzerinden erişilir; doğrudan SDK çağrısı yok. - Her yeni uç nokta için idempotency anahtarı zorunlu. - Para tutarları float değil, minor-unit integer. Kapsamsız kural = her oturumda token paths: olmayan kural CLAUDE.md gibi her zaman yüklenir; yalnızca evrensel olanı kapsamsız bırak. Path-scoped = dokununca gelir Frontend'de çalışırken PCI (Payment Card Industry Standard) kuralları bağlamda yer kaplamaz; payment/ altına dokununca gelir. Tek konu, tek dosya, review'dan geçer Kurallar da kod: PR ile değişir, gerekçesi yazılır. Ajan gerekçeli kurala daha iyi uyar. 4K 1A · AI Connect Istanbul 34
issues.md'deki görevi dal → ajanlar → test → PR ile bitirir --1. issues.md'den görevi oku; kapsamı tek cümleyle yaz 2. gitdoctor start feature <slug> (preflight + dal) 3. pm agent'ını çağır: görevi backend / frontend / ai'ye böl 4. Her agent kendi worktree'sinde çalışır; make check geçer 5. test agent'ı: eksik testleri yaz, koştur, PM'e raporla 6. Adversarial review subagent: diff'i plana karşı dene 7. Conventional commit · push · gh pr create Komut mu, skill mi? Komutlar seni bekler; skill'ler konuşmayı izler. Yan etkili akışı yalnızca elle tetikle. Bağlam ekonomisi Başta yalnızca ad ve açıklama; gövde çağrılınca gelir. 30+ satırlık prosedür buraya. Yanına dosya alır Şablonlar ve script'ler yanında durur. Prompt borcu ödenir: prompt artık repoda. 4K 1A · AI Connect Istanbul 35
--name: test description: Değişen kod için eksik testleri yazar, koşturur, sonucu PM'e raporlar. Üretim kodunu değiştirmez. tools: Read, Grep, Glob, Edit, Bash model: sonnet --Sen ürünün test mühendisisin. Diff'i oku, şunları yap: - Mutlu yol değil: sınır durumları, hata yolları, boş girdi - Yalnızca tests/ altına yaz; services/*/src'a dokunma - make check koştur; çıktıyı kanıt olarak raporla - Geçmeyen test varsa sebebini ve dosya:satır'ı yaz Kendi bağlam penceresi Yüzlerce dosya okur, ana oturuma yalnızca özet döner. Gürültülü işler için ideal. Araç allowlist'i = yetki sınırı Review ajanına Edit verme; test ajanına src/ yazdırma. En az yetki ilkesi burada da geçerli. Taze göz etkisi Yazarın gerekçeleri review ajanına taşınmaz; yalnızca diff'i ve ölçütü görür, sert bakar. Subagent'lar 5 seviyeye kadar iç içe çalışabilir · Rolünü uzman gibi tanımla, görevini dar tut 36
olmalı mı? Hook Talimat seçilir, hook çalışır Asla olmamalı mı? Permissions / deny Duvar, ikna edilemez 30+ satırlık çok adımlı bir prosedür mü? Skill Gerekince yüklenir, dosya alır Yalnızca bazı dosyalar için mi geçerli? Path-scoped rule Bağlamı kirletmez Gürültülü, çok dosya okuyan bir iş mi? Subagent Ana bağlam temiz kalır Her zaman bilinmesi gereken kısa bir gerçek mi? CLAUDE.md Tek yer, kısa, indeks Yalnızca benim tercihim mi? ~/.claude, *.local Ekibe yük olmaz Uyarlama: claude.com/blog/steering-claude-code-skills-hooks-rules-subagents-and-more 39
GİTDOCTOR /dev-workflow payment3ds-retry doctor (52 kontrol) → start feature # issues.md - [ ] payment-3ds-retry: 3D Secure doğrulaması zaman aşımında bir kez yeniden dene; kullanıcıya durumu göster. (payment, frontend) - [ ] docs-threshold: belge sınıflandırma eşiğini 0.85 → 0.80, A/B ile. (ai) - [x] status-notify: başvuru durumu bildirimi Senaryo Viza'nın akışının sadeleştirilmiş hâlidir DAL AGENT feature/payment3ds-retry pm agent'ı devralır BU ADIMDA NE KORUNUR? Kapsam: görev tek cümle, etkilenen servisler yazılı; ajan “bir de şunu yapayım” diyemez Git hijyeni: preflight kontrolü; kirli çalışma ağacı, yanlış taban, eski dal varsa akış başlamaz İnsan kapısı: plan mode'da PM'in planı onaylanmadan kod yazılmaz 40
sonra kod Planı yazar, görevleri böler, panoyu tutar PM önce API şemasını yazar; agent'lar birbirine arayüz verir. Her agent kendi worktree'sinde git worktree ile izole dizinler: paralel düzenlemeler çakışmaz. BACKEND AGENT payment/: retry mantığı, idempotency; worktree-1 FRONTEND AGENT 3DS durum ekranı, hata metinleri; worktree-2 AI AGENT Bu görevde iş yok: boşta kalır, bağlam harcamaz Küçük bağlam, dar yetki Backend agent'ı yalnızca payment/ kurallarını yükler. 41
backend + frontend diff'leri eksik testleri yazar, koşturur make check çıktısı, kapsam farkı PM'E RAPOR geçti / kaldı + dosya:satır POST TOOL USE PRE TOOL USE STOP Her düzenlemeden sonra Her komuttan önce Agent “bitti” demeden önce Formatter + lint + typecheck. Hata varsa stderr agent döner; ajan düzeltmeden devam edemez. Secret tarama, tehlikeli komut bekçisi, “migrations/ dizinine yazma” kuralı. Exit 2 = engel. make check yeşil değilse oturum bitemez. “Bitmiş görünüyor” artık bir ölçüt değil; kanıt ölçüt. Test agent'ı yalnızca tests/ altına yazar; üretim kodunu değiştiremez (tools ve path kuralı) 42
düşer: agent erken talimatları unutur, hata artar. /clear /compact <odak> plan mode İlgisiz görevler arasında bağlamı sıfırla. İki düzeltmeden sonra hâlâ yanlışsa: /clear ve daha iyi bir ilk prompt. Özetlemeye yön ver: “API değişikliklerine odaklan.” CLAUDE.md'ye neyin korunacağını yaz. Keşfet → planla → uygula → commit. Keşif ve plan, kod yazılmadan önce; tek cümlelik düzeltmelerde atla. subagent ile araştır /btw · /rewind Oturum sonu ritüeli “Token yenileme akışını subagent'larla araştır.” Yüz dosya onun penceresinde okunur, sana özet gelir. Yan soru bağlama girmesin; yanlış yola girince checkpoint'e dön, “özetle ve devam et”. Öğrenilen tuzak CLAUDE.md'ye mi, skill'e mi? Borç defterine yeni kalem var mı? Bir sonraki oturum sıfırdan başlamasın. Kaynak: code.claude.com/docs/en/best-practices 44
A · YAZAR OTURUM B · İNCELEYEN (taze bağlam) “payment servisine 3DS retry'ı PLAN.md'ye göre uygula; testleri koştur.” “Diff'i PLAN.md'ye karşı incele: her gereksinim var mı, sınır durumlarının testi var mı, kapsam dışı değişiklik var mı? Yalnızca doğruluğu etkileyen boşlukları raporla, stil tercihi değil.” Tüm gerekçeler, denenen yollar ve varsayımlar bu pencerede birikir. Yazar kendi varsayımına kör olur. Yalnızca diff'i ve ölçütü görür; yazarın gerekçeleri ona taşınmaz. Aynı desen testler için Uyarı: inceleyen hep bir şey bulur Bir ajan testleri yazar, diğeri testleri geçiren kodu. Test ajanı src'a yazamadığı için testi “kolaylaştıramaz”. Boşluk aramaya ayarlı bir ajan boşluk bulur. Her bulguyu kovalamak aşırı mühendisliğe götürür; ölçütü “doğruluk ve gereksinim” ile sınırla. Kaynak: code.claude.com/docs/en/best-practices · “Add an adversarial review step” 45
Düzeltme döngüsü Şişmiş CLAUDE.md Bir görev, araya ilgisiz soru, tekrar ilk görev. Bağlam çöplük. Çare: ilgisiz görevler arasında /clear. Yanlış, düzelt, hâlâ yanlış. Pencere başarısız denemelerle dolu. Çare: iki düzeltmeden sonra /clear ve daha iyi prompt. Önemli kurallar gürültüde kaybolur. Çare: acımasız budama; zaten doğru yapıyorsa sil, her seferinde gerekliyse hook'a çevir. Güven-sonra-doğrula boşluğu Sonsuz keşif Ortak payda Makul görünen uygulama sınır durumlarını kaçırır. Çare: her zaman bir kontrol ver (test, script, ekran görüntüsü). Kapsamsız araştırma; ajan yüzlerce dosya okur, pencere dolar. Çare: dar kapsam ya da subagent. Beşi de bağlam ya da doğrulama sorunu; yani beşi de borç: bağlam borcu ya da anlaşılmamış kod borcu. Kaynak: code.claude.com/docs/en/best-practices · “Avoid common failure patterns” 46
github.com/cagatayuncu/gitdoctor · MIT · bash github.com/komunite/kalfa · MIT · 245+ yıldız Ajanlar için tek komutla Git Flow: start, finish, tag, doctor. Claude Code plugin'i. Türkçe Claude Code katmanı: 10 agent, 22 komut, 990+ skill, 6 hafıza katmanı, 9 hook. doctor: 52 salt-okunur kontrol; topoloji, etiket, sürüm dosyası, dal hijyeni Eksik back-merge, yanlış tabanlı hotfix, eski dal ve etiket uyumsuzluğunu yakalar Yıkıcı varsayılan yok; JSON/SARIF çıktı ile PR botu ve prepush hook Borca etkisi: DORA'nın “güçlü sürüm kontrolü” yeteneğini ajan akışına gömer. Rakamlar Ekim 2026 itibarıyla repo sayfalarından Ritüel komutları: /start, /sync, /wrap-up; inceleme: /audit, /review, /release Tamlık Kapısı: TODO, TBD, FIXME kalmışsa hook bloklar; yarım iş merge edilemez Oturumlar arası hafıza katmanları ve TaskBoard ile bağlam kaybını azaltır Borca etkisi: .claude anatomisinin Türkçe, hazır örneği; önce oku, sonra kendininkini kur. 48
(ECC) superpowers github.com/affaan-m/everything-claude-code · 200K+ yıldız github.com/obra/superpowers · Claude Code plugin 260+ skill, 66 agent, hooks ve dil bazlı rules; oturum özetini yazıp geri yükleyen hafıza hook'ları; kalıpları “instinct” olarak öğrenme; config'i A– F notlayan AgentShield. “Önce plan, sonra kod” disiplini: brainstorm → plan → TDD ile uygula → review akışını skill'lerle zorlar. K3'ün hazır uygulaması. spec-kit awesome-claude-code github.com/github/spec-kit · GitHub github.com/hesreallyhim/awesome-claude-code Spec-driven development: specify → plan → tasks → implement. Spec, ajanın pusulası olur; gereksinim belirsizliği borcuna doğrudan karşılık. Derlenmiş liste: skill'ler, hook'lar, agent'lar, CLAUDE.md örnekleri. Kendi iskeletini kurarken fikir kaynağı; ne eklediğini bilerek ekle. Uyarı: 260 skill yüklemek bağlam ve bakım yükü getirir. Değerli olan kod değil, desenler: hafıza hook'u, tamlık kapısı, plan-önce-kod, config tarayıcı. Yıldız sayıları Ekim 2026 itibarıyla yaklaşıktır 49
pre-commit · lefthook ruff · biome Git hook yöneticileri: commit'ten önce formatter, lint, secret tarama. Ajanın PostToolUse hook'u ile aynı komutları çağırır; iki katman, tek gerçek. Python ve JS/TS için çok hızlı lint + format. Hızlı olması önemli: her düzenlemeden sonra çalışacak kadar ucuz. Stil tartışması biter. commitlint + Conventional Commits semgrep · SonarQube feat:, fix:, refactor: önekleri zorunlu. Refactor ile özellik ayrışır, changelog ve SemVer otomatik üretilir; gitdoctor sürüm önerisini buradan alır. Statik analiz ve güvenlik kuralları; kendi kuralınızı yazabilirsiniz (“doğrudan SDK çağrısı yasak”). SonarQube ayrıca borcu dakika cinsinden tahmin eder ve trendi gösterir. 4K 1A · AI Connect Istanbul 50
dört dedektör Belirti (2. bölümden) Dedektör Ne yapar, nasıl kullanılır Kopya-yapıştır bloklar 8× (GitClear) jscpd Dil bağımsız kopya tespiti; CI'da eşik koy (%3), aşılınca PR kırmızı. Çoğaltma refleksini ölçer. Kullanılmayan dosya ve export'lar knip (JS/TS) · vulture (Python) Ölü kod, kullanılmayan bağımlılık ve export'ları bulur. Her sprint sonunda bir “temizlik PR'ı” için girdi. Mimari tutarsızlık, sınır ihlali dependency-cruiser · import-linter “payment, ai'yi import edemez” kuralını kod olarak yazar; ihlalde build düşer. Path-scoped rule'un CI ikizi. Döngüsel bağımlılık madge Modül grafiğini çizer, döngüleri raporlar. Agentın “kolay yoldan import” alışkanlığına karşı erken uyarı. Hepsi CI'da koşar; çıktıları borç defterine beslenir: hangi eşik ne zaman aşıldı, kim, neden kabul etti. 4K 1A · AI Connect Istanbul 51
yedi kitap Clean Code Clean Architecture Refactoring The Pragmatic Programmer R. C. Martin, 2008 R. C. Martin, 2017 M. Fowler, 2018 (2. bs.) Hunt & Thomas, 2019 İsimler, fonksiyonlar, yorumlar; temiz örnek. Bağımlılık kuralı ve sınırlar. Küçük güvenli adımların kataloğu; ortak dil. Kırık pencereler, DRY, otomasyon. A Philosophy of Software Design Tidy First? Nereden başlamalı? Kent Beck, 2023 Working Effectively with Legacy Code J. Ousterhout, 2021 Önce düzenle, sonra değiştir. M. Feathers, 2004 Karmaşıklık ve derin modüller. 4K 1A · AI Connect Istanbul Testi olmayan kod legacy'dir. Tek kitap: A Philosophy of Software Design. Kısa, güncel, ajan çıktısını yargılamak için en iyi sözlük. 52
Technical Debt Kruchten, Nord, Özkaya · SEI Series, 2019 Borcu tanımlamak, ölçmek ve yönetmek için en sistematik çerçeve; borç defteri fikri buradan. İpek Özkaya: CMU SEI'de teknik borç araştırmasının öncülerinden. 4K 1A · AI Connect Istanbul Vibe Coding Beyond Vibe Coding Gene Kim & Steve Yegge · IT Revolution, 2025 Addy Osmani · O'Reilly, 2025 Üretim kalitesinde yazılımı ajanlarla geliştirmek: FAAFO çerçevesi, kıdemli mühendisin yeni rolü. Phoenix Project'in yazarından, DevOps diliyle. Vibe coding ile AI destekli mühendislik arasındaki çizgi: spec, bağlam mühendisliği, doğrulama. Bu sunumun 4. bölümüyle en çok örtüşen kitap. 53
birlikte versiyonla K2 Sınırları talimatla değil mekanizmayla koru Hook'lar (her seferinde) · deny listesi (asla) · CI kapıları · aynı make check her yerde K3 Küçük, planlı, doğrulanabilir adımlar Plan mode · tek cümlelik görev · refactor PR'ı ayrı · test önce · Stop kapısı · kanıtla raporla K4 Anlamadığın kodu merge etme; son söz insanın Writer/Reviewer ayrımı · adversarial subagent · PR'da plan ve kanıt · büyükse böl, geri gönder 1A Her oturumu temiz bitir /compact ve /clear · öğrenileni CLAUDE.md ya da skill'e yaz · CLAUDE.md'yi buda · borç defterine kalem ekle 4K 1A · AI Connect Istanbul CLAUDE.md (<200 satır) · path-scoped rules · ADR · hepsi git'te, review'dan geçer 54
CLAUDE.md'yi 200 satırın altına indir /doctor çalıştır; her satır için “silsem hata yapar mı?” Kalanı skill'e ya da rule'a taşı. K1 PostToolUse hook'u: formatter + lint “Her düzenlemeden sonra ruff/biome çalıştıran bir hook yaz” de; Claude kendisi yazar. K2 Stop kapısı: test geçmeden bitiş yok make check yoksa önce onu yaz; tek komut, her yerde aynı. K2 · K3 issues → PR akışını bir skill'e dök Önce tek ajanla, yedi adım; PM ve uzman ajanları sonra ekle. disable-modelinvocation: true. K3 · K4 Borç defteri aç: docs/debt.md Her bilinçli kestirme bir satır: ne, neden, faiz, ödeme planı. Fowler'ın kadranında “farkında” sütununa geçiş. 1A 4K 1A · AI Connect Istanbul 55
gokerguner
jmmastey
inesmontani
keithpitt
shlominoach
aleyda
lfama
ammeep
tammyeverts
portentint
nikkihalliwell
schroneko
mkilby
