Tutarlı kod incelemeleri için Claude Code stil rehberi promptları

Stil rehberi ihlalleri neden hızla yayılır

Stil rehberi ihlalleri nadiren tek büyük bir hata olarak ortaya çıkar. Genellikle küçük “yeterince iyi” seçimlerle başlarlar: bir pull request içinde zararsız görünen kararlar, sonra birikir ve kod tabanı dengesiz ve okunması daha zor hale gelir.

Stil sürüklenmesi genellikle şöyle görünür: bir dosya userID kullanır, başka bir dosya userId, bir üçüncüsü uid. Bir handler { error: "..." } döndürür, başkası throw eder, bir başkası loglayıp null döndürür. Her değişiklik küçük olsa da birlikte bir repo oluşturduklarında kalıplar öngörülemez hale gelir.

Hızlı iterasyon ve birden çok katkıda bulunan kişi durumu kötüleştirir. İnsanlar özellikle zaman baskısı altındayken gördüklerini kopyalar. Repodaki en son kod bir kısayol kullandıysa, o kısayol bir sonraki değişiklik için şablon olur. Birkaç haftadan sonra “varsayılan stil” yazılı rehberiniz değil; en son olan halidir.

İşte bu yüzden hedef kişisel tercihler değil, tutarlı kurallar olmalı. Soru "Bu ismi seviyor muyum?" değil, "Bu, üzerinde anlaştığımız kurallara uyuyor mu ki bir sonraki kişi düşünmeden takip edebilsin?" olmalı.

İhlalleri erken yakalamak kötü kalıpları kopyala-yapıştır yakıtı olmadan durdurmak demektir. Yeni ve düzenlenen koda odaklanın, yeni tutarsızlığın ilk görünümünü düzeltin ve yeni sürüklenme getiren mergeleri engelleyin. Bir sorunu işaretlediğinizde, insanların bir dahaki sefere taklit edebilmesi için kısa bir tercih edilen örnek ekleyin.

Gerçekçi bir örnek: bir geliştirici yeni bir API endpoint ekler ve ham istek gövdelerini “sadece hata ayıklama için” loglar. Bu kabul edilirse, bir sonraki endpoint bunu kopyalar ve kısa sürede hassas veriler loglarda görünür. İlk PR'de yakalamak ucuzdur; yayıldıktan sonra yakalamak acı verici ve risklidir.

Stil rehberinizi net, test edilebilir kurallara dönüştürün

Bir stil rehberi ancak incelemelerde bir kontrol listesi gibi okunursa işe yarar, tercihlerin bir listesi gibi değil. Her yönergeyi bir diff üzerinde kontrol edilebilecek kurala çevirin.

Kuralları gözden kaçmayacak şekilde dört kovaya ayırın: isimlendirme, katmanlama, hata yönetimi ve loglama. Her kova için iki şey yazın: ne doğru olmalı ve ne yasaklanmış.

Her kuralın gücünü baştan belirleyin:

• Mandatory: başarısız olursa değişikliği engeller.
• Recommended: açık bir sebep olmadıkça düzeltin.
• Optional: olması güzel, asla engelleyici değil.

İncelemelerin sonsuz refaktörlere dönüşmemesi için kapsam belirleyin. Basit bir kural iyi çalışır: “yeni ve değiştirilmiş kod uyumlu olmalı; mevcut dokunulmamış kod yalnızca düzeltmeyi engelliyorsa yeniden yazılmaz.” Temizlik istiyorsanız, bunu ayrı bir iş olarak zaman kutusuna alın.

Ayrıca incelemeden beklediğiniz çıktıyı tanımlayın ki üzerine harekete geçmek kolay olsun: geç/kırıl kararı, dosya ve satır referanslı ihlaller listesi, somut düzenlemeler şeklinde önerilen düzeltmeler ve bir şey hata veya sızıntı riski oluşturuyorsa kısa bir risk notu.

Örnek: bir PR ham kullanıcı tokenlerini logluyorsa, inceleme “logging: never log secrets” altında başarısız olmalı ve bunun yerine bir request ID loglamayı önermelidir.

Fikir yerine kuralları zorlayan prompt yapısı

Stil promptları tercih gibi okunduğunda başarısız olur. İyi bir inceleme promptu bir sözleşme gibi okunur: net vazgeçilemezler, açıkça adlandırılmış istisnalar ve öngörülebilir çıktı.

İki kısa blokla başlayın: ne zorunlu ve ne esnetilebilir. Sonra bir karar kuralı ekleyin: “Eğer belirsizse, Needs Clarification olarak işaretle. Tahmin etmeyin.”

Kanıt zorunlu kılın. Araç bir ihlal işaretlediğinde, bunu belirsiz bir açıklama yerine tam tanımlayıcı ve dosya yoluyla alıntılamasını zorunlu kılın. Bu tek kısıtlama birçok gereksiz tartışmayı ortadan kaldırır.

Kapsamı dar tutun: yalnızca değişen satırlar ve doğrudan etkilenen kod yolları hakkında yorum yapın. İlgisiz refaktörlere izin verirseniz, stil uygulaması “dosyayı yeniden yaz”a dönüşür ve insanlar geri bildiriye güvenmeyi bırakır.

Tekrar kullanılabilecek bir yapı:

Role: strict style guide reviewer.
Input: diff (or files changed) + style guide rules.
Non-negotiables: [list].
Allowed exceptions: [list].
Scope: ONLY comment on changed lines and directly impacted code paths. No unrelated refactors.
Evidence: Every finding MUST include (a) file path, (b) exact identifier(s), (c) short quote.
Output: structured compliance report with pass/fail per category + minimal fixes.

Raporun her seferinde aynı bölümleri tutmasını zorunlu kılın, bazıları "No issues found" olsa bile: Naming, Layering, Error handling, Logging.

Eğer rapor “service layer leaking DB details” diyorsa, internal/orders/service/order_service.go gibi bir alıntı ve tam çağrıyı (ör. db.QueryContext) belirtmeli ki tartışmaya girmeden sızıntıyı düzeltebilesiniz.

Adım adım: stil-denetim prompt iş akışı oluşturun

Bir stil rehberi tekrarlanabilir bir süreç olduğunda yerleşir. Amaç modelin kuralları kontrol etmesini sağlamak, tat kaygısıyla tartışmamak ve bunu her seferinde aynı şekilde yapmaktır.

Basit iki geçişli bir iş akışı kullanın:

1. Standartlarınızı kompakt, numaralandırılmış bir kural listesi olarak yapıştırın (10-25 satır). Her kural test edilebilir olsun.
2. Değişiklik için bağlam ekleyin: diff, dokunulan dosyalar ve niyet hakkında bir cümle.
3. Önce bir ihlaller raporu isteyin. Dosya ve satır referansları, kısa bir sebep ve tam kural numarası zorunlu olsun.
4. Sadece rapordan sonra uyumluluğu sağlamak için en küçük yama isteyin.
5. Güncellenmiş kod üzerinde aynı promptu tekrar çalıştırarak hiçbir şeyin kalmadığını doğrulayın.

Örnek: bir PR yeni bir endpoint ekler. 1. geçiş handler'ın doğrudan PostgreSQL ile konuştuğunu (layering), istek struct'larında karışık isimlendirme olduğunu (naming) ve e-postaları tam halinde logladığını (logging) bildirir. 2. geçiş en küçük düzeltmeleri yapar: DB çağrısını bir service veya repository'e taşır, struct'ı yeniden adlandırır ve loglarda e-postayı maskeler. Başka hiçbir şey değişmez.

İsimlendirme konvansiyonları: küçük şeyleri yakalayan promptlar

İsimlendirme sorunları önemsiz gibi gelir ama gerçek maliyeti vardır: insanlar niyeti yanlış anlar, aramalar zorlaşır ve “neredeyse aynı” isimler çoğalır.

Değişiklik kapsamı boyunca inceleyicinin zorlaması gereken isimlendirme kurallarını belirtin: dosya adları, exported type'lar, fonksiyonlar, değişkenler, sabitler ve testler. Yazım biçimi (camelCase, PascalCase, snake_case) konusunda açık olun ve bir kısaltma kuralı seçin (örneğin APIClient vs ApiClient). Sonra bunu her yerde zorlayın.

Ayrıca paylaşılan sözlüğü standartlaştırın: hata tipleri, log alanları ve config anahtarları. Loglar request_id kullanıyorsa, bir dosyada reqId veya requestId kullanılmasına izin vermeyin.

Pratik kalan bir inceleyici yönergesi:

Check every new or renamed identifier. Enforce casing + acronym rules.
Flag vague names (data, info, handler), near-duplicates (userId vs userID), and names that contradict behavior.
Prefer domain language: business terms over generic tech words.

Kısa bir rapor isteyin: en kafa karıştırıcı üç isim, near-duplicate olanlar ve hangisinin korunacağı, ayrıca standarda uymayan log/config/error isimleri.

Katmanlama kuralları: sorumlulukların karışmasını önleyin

Katmanlama kuralları basit dilde en iyi çalışır: handler'lar HTTP ile konuşur, servisler iş kurallarını tutar, repository'ler veritabanıyla konuşur.

Bağımlılık yönünü kilitleyin. Handler'lar service çağırabilir. Service'ler repository çağırabilir. Repository'ler service veya handler çağırmamalıdır. Handler'lar veritabanı kodunu, SQL yardımcılarını veya ORM modellerini import etmemelidir. Paylaşılan paketler (config, time, IDs) kullanıyorsanız, bunları uygulama mantığından uzak tutun.

Kesitsel işleri bir yere sabitleyin. Validasyon genellikle boundary'de (istek şekli) ve servis içinde iş kuralları için yapılır. Yetkilendirme genellikle handler'da başlar (kimlik, scope), ama nihai karar serviste doğrulanmalıdır. Mapping katman kenarlarında olmalı: handler HTTP'yi domain girdisine, repository DB satırlarını domain nesnelerine çevirir.

Aşağıdaki promptu kullanarak incelemeleri somut tutun:

Check layering: handler -> service -> repository only.
Report any leaks:
- DB types/queries in handlers or services
- HTTP request/response types inside services or repositories
- repository returning DB models instead of domain objects
- auth/validation mixed into repository
For each leak, propose the smallest fix: move function, add interface, or rename package.

Raporu açık hale getirin: dosya adını, ait olması gereken katmanı, kuralı bozan import veya çağrıyı ve deseni yayılmasını engelleyecek minimal değişikliği belirtin.

Hata yönetimi konvansiyonları: baskı altındayken tutarlılık

Çoğu stil tartışması prodüksiyonda bir şey kırıldığında şiddetlenir. Net bir hata yönetimi politikası düzeltmeleri sakin tutar çünkü herkes “iyi”nin nasıl göründüğünü bilir.

Felsefeyi yazın ve bunu zorlayın. Örneğin: “Bağlam eklemek için hataları wrap edin; yalnızca anlam değişirken veya kullanıcı mesajına eşlerken yeni bir hata oluşturun. Ham hataları yalnızca sistem sınırında döndürün.” Bu tek cümle rastgele kalıpların yayılmasını engeller.

Kullanıcıya gösterilen metinleri dahili detaylardan ayırın. Kullanıcı mesajları kısa ve güvenli olmalı. Dahili hatalar işlem adını ve anahtar tanımlayıcıları içerebilir ama sırlar içermemelidir.

İncelemelerde sık görülen birkaç hatayı kontrol edin: yutulan hatalar (loglanıp dönmeyen), belirsiz dönüşler (başarısızlıktan sonra nil değer ile nil hata), ve stack trace, sorgu metni, token veya PII sızdıran kullanıcı mesajları. Retry veya timeout destekleniyorsa, bunların açıkça belirtilmesini isteyin.

Örnek: bir ödeme çağrısı zaman aşımına uğruyor. Kullanıcı "Payment service is taking too long." görmeli. Dahilde ise timeout wraplenip op=checkout.charge ve sipariş ID'si eklenmeli ki aranabilir ve işlenebilir olsun.

Loglama konvansiyonları: okunabilir, aranabilir ve güvenli

Loglar herkes aynı şekilde yazdığında yardımcı olur. Her geliştirici kendi kelime seçimlerini, seviye ve alanları seçerse arama kaosa döner.

Log seviyelerini vazgeçilmez yapın: debug geliştirme detayları için, info normal kilometre taşları için, warn beklenmeyen ama işlendiği durumlar için ve error kullanıcı-etkili başarısızlıklar veya dikkat gerektiren durumlar için. “fatal” veya “panic” nadir olmalı ve net bir çökme politikasıyla bağlı olmalı.

Yapılandırılmış loglar mükemmel cümlelerden daha önemlidir. Dashboard ve uyarıların bozulmaması için sabit anahtar isimleri zorunlu kılın. Küçük bir çekirdek set belirleyin (örneğin event, component, action, status, duration_ms) ve buna sadık kalın.

Hassas veri kesinlikle loglanmamalıdır. Loglanmaması gerekenleri açıkça belirtin: parolalar, auth tokenleri, tam kredi kartları, sırlar ve ham kişisel veriler. Zararsız görünen ama olmayan şeyleri de belirtin: parola sıfırlama linkleri, oturum ID'leri ve tam istek gövdeleri gibi.

Korelasyon ID'leri katmanlar arasında hata ayıklamayı mümkün kılar. Her isteğe bağlı log satırında request_id bulunmasını zorunlu kılın. user_id logluyorsanız bunun ne zaman izinli olduğunu ve eksik/anonim kullanıcı nasıl temsil edileceğini tanımlayın.

Tekrar kullanılabilecek bir prompt bloğu:

Review the changes for logging conventions:
- Check level usage (debug/info/warn/error). Flag any level that does not match impact.
- Verify structured fields: require stable keys and avoid free-form context in the message.
- Confirm correlation identifiers: request_id on all request-bound logs; user_id only when allowed.
- Flag any sensitive data risk (tokens, secrets, personal data, request/response bodies).
- Identify noisy logs (in loops, per-item logs, repeated success messages) and missing context.
Return: (1) violations with file/line, (2) suggested rewrite examples, (3) what to add or remove.

Merge öncesi hızlı bir “güvenlik geçişi” yapın: herhangi bir yeni log request_id eksikse, yeni anahtarlar mevcut adları değiştiriyorsa (userId vs user_id), hata loglarında neyin başarısız olduğu eksikse (işlem, kaynak, durum), her istekte tetiklenebilecek yüksek hacimli loglar varsa ve alan veya mesajlarda sır veya kişisel veri görünme ihtimali varsa bunları yakalayın.

İhlalleri yayılmadan önce nasıl yakalarsınız

Stil sürüklenmesini bir öneri değil, build kırılması gibi ele alın. Merge öncesi çalışan ve net geç/kırıl döndüren katı bir kapı ekleyin. Bir zorunlu kural kırılırsa (isimlendirme, katman sınırları, log güvenliği, hata yönetimi) kapı başarısız olur ve tam dosya/satır gösterir.

Kapıyı kısa tutun. Pratik bir hile: her kural için EVET/HAYIR checklisti zorunlu kılın ve herhangi bir HAYIR varsa onayı reddedin.

Bir PR boyutundaki kontrol listesi çoğu problemi yakalar:

• Naming: dosya, type ve fonksiyonlar için onaylanmış paterne uyuyor mu
• Layering: katmanları atlayan doğrudan çağrılar yok mu (örn. handler'ların DB çağırması)
• Errors: bağlam ile dönülüyor mu, hiçbir şey sessizce atılmıyor mu
• Logging: tutarlı alanlar, sır yok ve seviye etkisiyle eşleşiyor mu
• Tests/docs: davranış veya açık API değiştiyse güncellenmiş mi

Araç düzeltmeler önerdiğinde, dokunduğu her kural için küçük, uyumlu bir kod parçası isteyin. Bu “anlam için yeniden adlandır” gibi muğlak geri bildirimleri önler.

Stil uygulaması için prompt kullanırken sık düşülen tuzaklar

Bir stil rehberinin başarısız olmasının en hızlı yolu yoruma açık alan bırakmaktır. İki inceleyici aynı kuralı okuyup farklı sonuca varabiliyorsa, araç zevki değil standartları uygular.

İsimlendirme sık rastlanan örneklerden biridir. “Net isimler kullan” test edilebilir değil. Bunu doğrulanabilir hale getirin: “fonksiyonlar fiil olmalı (örn. createInvoice), boolean'lar is/has/can ile başlamalı, exported type'lar PascalCase.”

Bir başka tuzak her şeyi tek seferde istemektir. Bir prompt isimlendirme, katmanlama, hatalar, loglama, testler ve performansı aynı anda kapsadığında, geri bildirim sığlaşır. Derinlik gerekiyorsa incelemeyi odaklı geçişlere bölün veya gate promptunu zorunlu kurallarla sınırlı tutun.

En sık enforcement'un kaymasına neden olan problemler:

• Vague rules: “temiz” ve “tutarlı” yerine ölçülebilir dil kullanın.
• Mixing style fixes with redesign: bir stil promptunun yeni bir mimari önermesine izin vermeyin.
• No quoted evidence: her yorumun tam tanımlayıcı veya snippet alıntısı yapmasını zorunlu kılın.
• Silent exceptions: istisna izinliyse, kısa bir notla nedenini ve ne zaman kaldırılacağını şart koşun.

Promptları test gibi ele alırsanız, tahmin edilebilir bir uygulama elde edersiniz. Tavsiye gibi ele alırsanız, ihlaller sızar ve çoğalır.

Her değişiklikte çalıştırabileceğiniz hızlı kontrol listesi

Diff üzerinde (tüm repo değil) hızlı bir geçiş yapın ve doğrulayın:

• Naming: yeni identifier'lar paterninize uyuyor (case, prefix, suffix). Bir kavram tek bir şekilde adlandırılmış.
• Layering: bağımlılıklar sadece izin verilen yönde. Alt katmanlar üst katmanları asla import etmez.
• Errors: hatalar bağlamla döndürülüyor. Hiçbir şey sessizce yok sayılmıyor.
• Logging: doğru seviye, sabit alanlar ve sır veya kişisel veri yok.
• Final pass: inceleyici açıkça: “no mandatory violations found” veya merge öncesi düzeltilmesi gereken ihlallerin listesi.

Her değişiklikle birlikte küçük bir prompt şablonu saklayın ve yapıştırın:

Review ONLY the changed code against our rules for naming, layering, errors, and logging.
List mandatory violations first (with file + line if available). Then list optional suggestions.
End with either: “no mandatory violations found” or “mandatory violations found”.

Örnek: handler içinde procUsr() adında yeni bir fonksiyon ve doğrudan PostgreSQL'e yazan bir kod varsa, feature çalışsa bile isimlendirme ve katmanlama hatası yüzünden reddedilmelidir. Bunu yakalamak kopyala-yapıştırın yayılmasını önler.

Örnek: sorunları erken düzelten gerçekçi bir inceleme

Bir ekip arkadaşı yeni bir endpoint ekliyor: POST /v1/invoices/{id}/send. Handler, service ve storage dosyalarını etkiliyor.

İlk geçişte rapor istiyorsunuz, yeniden yazma değil:

Pass 1 (report only)
You are a strict style checker. Read the patch.
Rules: naming must match our guide, handlers call services only, services call storage only, no SQL in handlers,
errors must be wrapped with context, logs must be structured and not leak PII.
Output: a numbered list of violations with file:line, rule name, and one-sentence impact. Do not propose fixes.
If a rule might be intentionally broken, ask one clarification question.

Tipik bulgular: SendInvoiceNow() vs SendInvoice isim uyumsuzluğu, handler'ın db.QueryRow'u doğrudan çağırması, err'i bağlam eklemeden geri döndürme ve log.Printf("sending invoice %v", invoice) gibi nesneleri döken gürültülü loglar.

İkinci geçiş en küçük, güvenli değişiklikleri ister:

Pass 2 (minimal fix suggestions)
Using the violations list, propose the smallest code edits to comply.
Constraints: keep behavior the same, no refactors beyond what is needed, show suggested function names and where code should move.
For each fix, include 1-2 lines of example code.

Eğer bir kuralın kırılmasına izin veriliyorsa, bunu baştan söyleyin: “İstisnalar yalnızca kısa bir yorum eklenirse izinlidir ve istisnayı kaldırmak için takip görevi eklenmelidir.”

Düzeltmeden sonra handler ince bir adaptör olur, service iş akışını yönetir, storage sorguyu sahiplenir, hatalar fmt.Errorf("send invoice: %w", err) şeklinde wraplenir ve loglar güvenli alanlarla (fatura ID'si, tam fatura değil) tek bir temiz satır haline gelir.

Sonraki adımlar: rutine dönüştürün, hızı yavaşlatmadan

Takım onaylı bir prompt seçin ve bunu ortak bir araç gibi ele alın. İncelemelerde sizi en çok yoran şeyle başlayın (isimlendirme sürüklenmesi, katman sızıntıları, tutarsız hatalar, güvensiz loglar). Gerçek koddaki gerçek bir ihlali görmeden promptu değiştirmeyin.

Promptun en üstünde küçük bir kural bloğu tutun ve her incelemeye değişmeden yapıştırın. Herkes kuralları her seferinde düzenlerse standardınız olmaz; tartışmanız olur.

Basit bir ritim işe yarar: haftanın en çok rastlanan stil hatalarını bir kişi toplar ve tam olarak bir tane daha net kural veya bir daha iyi örnek eklenir.

Chat tabanlı bir build akışında çalışıyorsanız, Koder.ai (koder.ai) gibi bir platformda aynı gate kontrollerini değişiklikler sırasında da çalıştırmak değerli olabilir. Planning, snapshot ve rollback gibi özellikler stil düzeltmelerini küçük ve geri alınabilir tutmaya yardımcı olur, kaynak kodunu dışa aktarmadan önce.