Claude Code Review’i CLAUDE.md ve REVIEW.md ile pull request kapısına dönüştürün

Anthropic, 9 Mart 2026’da Claude Code için Code Review’i duyurdu ve her mühendislik yöneticisinin yüzünü buruşturması gereken tek bir sayı verdi: Anthropic içinde mühendis başına kod çıktısı bir yılda %200 artmıştı ve darboğaz artık review olmuştu (Anthropic). Asıl hikâye bu. AI ile kod yazmak review işini ortadan kaldırmadı. Baskı noktasını başka yere taşıdı.

Doğru tepki “bırak Claude kendi ödevini onaylasın” değil. Bu, kibar bir bug fabrikası kurmanın yoludur. Doğru tepki, Claude Code Review’i ekibinizin gerçekten inandığı kurallarla çalışan, tekrarlanabilir bir PR kapısına çevirmek.

Anthropic’in kurulum dokümanları artık bunu uygulanabilir kılıyor. Bir reviewer, @claude review yorumu yaparak review başlatabiliyor; Code Review de repository’deki CLAUDE.md dosyalarını ve root seviyesindeki REVIEW.md dosyasını okuyor. CLAUDE.md ihlalleri nit seviyesinde bulgular olarak ele alınıyor; hatta Claude, bir PR CLAUDE.md dosyasını güncelliğini yitirmiş hâle getiriyorsa bunu bile işaretleyebiliyor (Claude Help Center). REVIEW.md ise review’e özel kuralları koyduğunuz yer; Anthropic’in verdiği örnek dahil: “her yeni API route’unun bir integration test’i olmalı.”

İşte bütün mesele o tek cümlede. AI reviewer’lara “dikkatli ol” demeyi bırakın. Onlara repo hukuku verin.

Problem: AI, PR Review’i Daha Gürültülü Hale Getirdi

Topluluktaki tartışma dağınık, çünkü iki taraf da haklı.

Claude Code Review için açılan Hacker News başlığında geliştiriciler fiyatı, değeri ve bir AI satıcısının AI ile üretilmiş kod için reviewer satıyor olmasının verdiği rahatsız edici hissi sorguladı. Bir yorumcu Anthropic’in kendi büyük PR sayılarına bakıp bunu agentic development kalitesi için bir uyarı işareti olarak okudu; başkaları ise aracın asıl değerini derinlemesine ikinci bir göz olarak burada kazandığını savundu (Hacker News).

Reddit’te aynı tartışmanın daha pratik versiyonu var. Bir başlıkta bir geliştirici, Claude bazen kendilerinin anlamadığı kodlar yazdığı için insanların Claude tarafından üretilen koda review atlamaya yetecek kadar güvenip güvenmediğini sordu. Yanıtlar nettir: review et, doğrula, değişiklikleri küçük tut ve delegasyonun hesap verebilirliği ortadan kaldırdığını sanma (Reddit). Başka bir başlıkta insanlar Claude’un çıktısını review etmek için ayrı AI agent’ları kullanmayı, ama review’ün kendisini de codebase’e karşı kontrol etmeyi tartıştı (Reddit).

Benim görüşüm: Claude ile Claude’un yazdığı kodu review etmek, onu bağımsız yargı gibi görmediğiniz sürece sorun değil. Onu çok hızlı, çok literal, devasa context’e sahip ama sahiplenmesi olmayan junior bir reviewer gibi düşünün. Sıkıcı eksikleri, dosyalar arası tutarsızlıkları, eksik testleri, security footgun’larını, bayat dokümanları ve insan reviewer’ın muhtemelen hızlıca geçeceği yerleri yakalamalı.

Son onay merci olmamalı.

Anthropic bunu açıkça söylüyor. Code Review PR’ları onaylamıyor veya tek başına bloklamıyor. Mevcut review workflow’ları olduğu gibi kalıyor (Claude Help Center). Yani “kapı” bir ekip kapısı: Claude çalışmadan insan onayı yok, Important bulgular çözülmüş ya da açıkça waive edilmiş olacak ve PR sahibi repo’ya özgü kuralları ele almış olacak.

Bu sıkıcı. Güzel. Sıkıcı kapılar incident’ları önler.

Kurulum: İki Markdown Dosyası, İki İş

Claude Code Review’de önemli olan iki memory surface var.

CLAUDE.md ortak proje context’idir. Sadece review için değil, genel olarak Claude Code oturumlarına uygulanır. Anthropic bunu komutlar, konvansiyonlar, kısa mimari notlar, sert kısıtlar ve bilinen tuzaklar için kullanmayı öneriyor. Ayrıca sinyal yoğun tutmayı, kabaca 200 satırın altında kalmayı öneriyor; çünkü Enterprise oturumlarında prompt caching tekrar eden token maliyetini azaltsa bile bu dosya context’e yükleniyor (Claude Help Center).

REVIEW.md farklıdır. Repository root’unda durur ve yalnızca review içindir. Anthropic’in Code Review dokümanları, içeriğinin her review agent’ına yüksek öncelikli talimat olarak enjekte edildiğini ve buranın severity, nit hacmi, skip kuralları, repo’ya özgü kontroller, doğrulama standartları ve re-review davranışını kontrol edeceğiniz yer olduğunu söylüyor (Claude Code Docs).

Benim kullandığım ayrım şu:

Kararlı context’i CLAUDE.md içine koyun. Review baskısını REVIEW.md içine koyun. Deterministik olan her şeyi CI’a koyun.

API Route’ları İçin Gerçek Bir Kapı

Bir backend ekibinin sürekli happy-path unit test’leri olan ama integration coverage’ı olmayan route’lar gönderdiğini varsayın. İnsan reviewer’lar bazen yakalıyor. Claude tarafından üretilen PR’lar bunu daha da kötüleştiriyor, çünkü agent makul görünen handler code üretmekte iyi, ekibe özgü review yaralarını hatırlamakta kötü.

CLAUDE.md ile başlayın:

# Project conventions

- API routes live in `src/routes`.
- Integration tests live in `tests/integration`.
- Use `requireAuth()` on non-public routes.
- Validate request bodies with Zod schemas from `src/schemas`.
- Run `pnpm test:integration` before marking API work complete.

Sonra root seviyesinde REVIEW.md ekleyin:

# Code Review Rules

Treat these as Important unless stated otherwise.

## API routes

If a PR adds or changes a file under `src/routes/**`:
- Flag missing integration test coverage in `tests/integration/**`.
- Flag routes without explicit auth, unless the route is listed as public.
- Flag request bodies that are not validated with a Zod schema.

Do not accept unit tests as a substitute for route-level integration tests.

## Evidence bar

For every Important finding, cite the changed file and the missing or conflicting evidence.
If the claim depends on a convention, cite this REVIEW.md rule.

O son bölüm önemli. LLM reviewer’lar kendinden emin saçmalık üretebilir. Kanıt istemek, review’ün bir bulguyu bir dosyaya, bir satıra ya da açık bir politikaya bağlamasını zorlar. False positive’leri ortadan kaldırmaz, ama review’ün şeklini “hisler”den “göster bakalım”a çevirir.

Şimdi bir PR şunu ekliyor:

// src/routes/billing.ts
router.post("/billing/plan", async (req, res) => {
  const result = await updatePlan(req.body.planId);
  res.json(result);
});

İyi bir Claude Code Review yorumu buna benzer bir şey söylemeli:

• Important: src/routes/billing.ts görünür auth olmadan yeni bir POST route ekliyor.
• Important: request body, schema validation olmadan req.body.planId okuyor.
• Important: tests/integration/** altında eşleşen bir integration test eklenmemiş.

Kararı hâlâ insan reviewer verir. Belki router’ın üst seviyesinde auth middleware uygulanıyordur. Belki integration test generated contract suite içinde yaşıyordur. Tamam. Kapı, merge’den önce bu tartışmayı zorladıysa işini yaptı.

Para Yakmadan Tetiklemek

Anthropic üç repository trigger modu veriyor: PR oluşturulduktan sonra bir kez, her push’tan sonra veya manual. Manual modda biri @claude review yorumu yapana kadar maliyet yok; ondan sonra aynı PR’a gelen ek push’lar otomatik olarak review tetikliyor (Claude Help Center).

Çoğu ekip için “her push’tan sonra” ile başlamazdım. Anthropic, Code Review’in ortalama yaklaşık 20 dakika sürdüğünü ve genellikle review başına 15 ila 25 dolar tuttuğunu, bunun PR boyutu ve karmaşıklığıyla ölçeklendiğini söylüyor (Anthropic). Production incident’a kıyasla ucuz. ESLint çalıştırmaya kıyasla pahalı.

Katmanlı bir kapı kullanın:

1. Her PR normal CI çalıştırır.
2. Riskli PR’lar @claude review alır.
3. Büyük PR’lar, auth değişiklikleri, payments değişiklikleri, migrations ve public API değişiklikleri insan onayından önce Claude review gerektirir.
4. Her typo düzeltmesinden sonra değil, büyük değişikliklerden sonra Claude review’ü tekrar çalıştırın.
5. Son onay insanlara aittir.

Hafif bir GitHub PR checklist’i kapıyı açık hale getirir:

## AI Review Gate

- [ ] CI is green.
- [ ] `@claude review` has run, or this PR is exempt.
- [ ] Important findings are fixed or explained.
- [ ] If this PR changes conventions, `CLAUDE.md` is updated.
- [ ] If this PR changes review policy, `REVIEW.md` is updated.

Claude’u kendi workflow’unuz içinde çalıştırmayı tercih ediyorsanız, Anthropic’in GitHub Actions dokümanları anthropics/claude-code-action@v1 ve bir code-review plugin configuration gösteriyor; API anahtarları için GitHub Secrets kullanma yönündeki olağan uyarıyla birlikte (Claude Code Docs). Bu yol size daha fazla CI kontrolü verir. Managed Code Review yolu ise Anthropic’in tarif ettiği daha derin multi-agent reviewer’ı verir.

Bunları karıştırmayın. Biri programlanabilir otomasyon. Diğeri ücretli, depth-first bir reviewer.

Numara: Claude’a Stili Değil, Kontratı Review Ettirin

Kötü REVIEW.md dosyaları fal kurabiyesi gibi okunur:

Please ensure the code is clean, maintainable, secure, and well tested.

Bu pelte üretir.

İyi REVIEW.md dosyaları yaraları kodlar:

## Database migrations

Flag as Important if:
- A migration adds a non-null column without a default on an existing table.
- A migration backfills data without batching.
- Application code starts reading a new column before the migration is deployed.

Skip:
- Formatting comments in generated Prisma client files.

AI review’ün işe yaradığı yer burası. Kıdemli mühendisin zevkini ikame etmiyor. Ekibin kurumsal hafızasını her PR’da tekrar oynatıyor.

İyi çalışan birkaç kural:

## Re-review behavior

On the first review, report Important and Nit findings.
On later reviews of the same PR, suppress new Nits unless they are directly caused by the latest push.

## Test policy

Flag missing tests only when the changed behavior is observable through a stable public interface.
Do not request snapshot tests for purely visual copy changes.

## Security policy

Flag any new endpoint that:
- Accepts user input without validation.
- Performs authorization by trusting a user-provided account ID.
- Logs tokens, session IDs, API keys, or full request bodies.

Eksik olana dikkat edin: “kodu zarif yap.” Zarafeti review’de insanlar tartışabilir. Claude kontratları kontrol etmeli.

Tartışmaların Kaçırdığı Şey

HN ve Reddit tartışmaları aynı sorunun etrafında dönüp duruyor: AI, AI kodunu review etmeli mi?

Yanlış soru.

Doğru soru şu: review’ün hangi kısımlarını açık hale getirmeye razısınız?

Review kültürünüz kıdemli mühendislerin kafasının içindeyse, Claude Code Review gürültülü ve keyfi hissettirir. Review kültürünüz repo kuralları olarak yazılıysa, çarpan etkisi yaratır. CLAUDE.md Claude’a projenin nasıl çalıştığını anlatır. REVIEW.md Claude’a ekibinizin neyi merge etmeyi reddettiğini söyler.

Bu, “Claude için dokümantasyon yazıyoruz” şikâyetine de cevap verir. Evet, geliştiriciler artık bir agent için doküman yazıyor. Bu, o dokümanların aynı zamanda onboarding materyali, review politikası ve incident önleme aracı olduğunu fark edene kadar kulağa saçma geliyor. İyi bir CLAUDE.md, insanlar için de daha iyi bir “bu repo nasıl çalışır” dosyasıdır.

Keskin kenar hesap verebilirliktir. Claude bug’ı kaçırırsa, onu yine siz merge etmiş olursunuz. Claude hayali bir bug uydurursa, onu yine sizin reddetmeniz gerekir. Claude kendi çıktısını review ediyorsa, yine bağımsız sinyallere ihtiyacınız var: testler, type system’ler, static analysis, observability ve değişikliği anlayan bir insan.

Claude Code Review’i yargıç değil, kapı olarak kullanın. Her seferinde şu sinir bozucu soruları sordurun:

• Integration test nerede?
• Auth nerede enforce ediliyor?
• Bu PR CLAUDE.md dosyasını yanlış hale getirdi mi?
• Bu generated file yorum yapmaya değer mi?
• Bu bulgu koda mı dayanıyor, yoksa sadece bir sezgi mi?

Doğru PR’larda kendi parasını çıkarmasına bu yeter.

Aynı kurulumu Claude Fable 5 on OneHop ile deneyin, drop-in kullanın ve $10 ücretsiz başlayın.

Ek okuma: Claude Fable 5 ile başlangıç.