Planning Mode, CI/CD Entegrasyonu ve Session Yönetimi

Bu derste Claude Code’un “ne zaman dur, ne zaman devam et” mekaniğini, CI/CD pipeline’a nasıl bağlanacağını ve uzun investigation’ları nasıl yöneteceğini öğreniyoruz. Sınav bu üçünü de sorar; özellikle -p + --output-format json + --json-schema üçlüsü “CI/CD için hangi komut doğru” sorusunun tek cevabı. Session yönetimi ise “uzun kod review’da context kaybolmasın, bağlamı nasıl koruruz” sorusuna karşılık gelir.

Neden bu konu sınavda çıkıyor

Domain 3’ün yaklaşık üçte biri “operational” — yani Claude Code’u üretimde nasıl çalıştırırsın. Sınav senaryolarından biri CI/CD Code Generation — bu senaryoda aday claude -p ile non-interactive çalıştırmayı, JSON çıktıyı parse etmeyi ve schema ile doğrulamayı bilmeli. Bir diğer senaryo Developer Productivity — burada session resume/fork ve multi-pass review geliyor. İkisi de direkt bu dersten.

Temel kavramlar

1. Planning mode karar ağacı

Planning mode (plan mode), Claude’un yazma tool’larını kapatıp sadece okuma + düşünme ile sınırladığı mod. Amacı: büyük iş öncesi plan üret, kullanıcı onaylasın, sonra uygula.

Planning mode zorunlu olduğu durumlar:

Mimari karar: “Auth sistemini session-cookie mi JWT mi yapalım?” → iki yaklaşım var, yanlış seçim geri alınamaz.
Çok dosya (≥3): Refactor, dependency upgrade, schema migration → etki haritası çıkmalı.
Birden fazla yaklaşım: “Cache’i Redis mi Memcached mi?” → benchmark yapılmadan seçilmez.
Geri alınamaz işlem: DB migration, API breaking change, prod deploy → insan onayı şart.
Belirsiz scope: Kullanıcı talebi muğlak, 30+ dakikalık iş çıkabilir.

Direct execution uygun olduğu durumlar:

Tek dosya, tek fonksiyon fix (örn. “bu regex yanlış, doğrusunu yaz”).
Kullanıcı tam olarak ne istediğini söylemiş, alternatif yok.
Mevcut test yetersiz, test ekle → isolated change.
Refactor sonrası tip düzeltme (mekanik).

Plan mode’da Explore subagent devreye girer. Rehber 5.6 bunu tek bir mekanizma olarak tanımlar:

Explore subagent: Read-only dosya keşfi yapar; verbose çıktıyı ana context’ten izole eder, yalnız özet döner. Çok dosyalı, multi-phase işlerde ana session’ın context’i tükenmesin diye kullanılır.

Sınavda “Explore ne zaman devreye girer” sorusu gelirse: “plan mode’da, dosya keşfi verbose olacaksa ve ana context’i kirletmemek için”.

2. CI/CD üçlüsü: -p, —output-format json, —json-schema

CI/CD pipeline’ında Claude Code’u non-interactive çalıştırmak için üç bayrak birlikte kullanılır:

Bayrak	Rol	Örnek
`-p "<prompt>"`	Non-interactive, stdin okumaz, prompt’u argüman olarak al	`claude -p "Bu PR için review yap"`
`--output-format json`	Parse edilebilir JSON çıktı (text değil)	`claude -p "..." --output-format json`
`--json-schema '{...}'`	Çıktıyı verilen Pydantic/JSON schema’ya zorla	`--json-schema '{"type":"object","required":["severity"]...}'`

Üçlü birlikte “agentic CI step” oluşturur: PR’a review yorumu bırak, JSON olarak döndür, schema doğrula, aykırıysa fail et. Veya: commit mesajı üret, JSON parse et, schema’ya uy, git commit.

Örnek GitHub Actions step:

- name: Claude PR Review
  permissions:
    pull-requests: write   # gh pr comment için GITHUB_TOKEN gerekir
    contents: read         # diff / repo içeriği okumak için
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude -p "Bu PR'daki değişiklikleri review et" \
      --output-format json \
      --json-schema '{
        "type": "object",
        "properties": {
          "findings": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "file": {"type": "string"},
                "severity": {"enum": ["CRITICAL", "HIGH", "MEDIUM", "LOW"]},
                "message": {"type": "string"}
              },
              "required": ["file", "severity", "message"]
            }
          },
          "summary": {"type": "string"}
        },
        "required": ["findings", "summary"]
      }' > review.json

    # JSON doğrulama
    jq -e '.findings | length > 0 or .summary != ""' review.json

Sınav tuzağı: “CI’da Claude’u interaktif çalıştır” → yapılamaz, CI non-interactive olmalı, -p şart. İkinci tuzak: “Schema koymadan JSON al, manuel parse et” → kötü çünkü schema garantisi olmadan parse fragile. Doğru: schema ile sınırla, Pydantic/Zod ile validate et.

3. Session yönetimi: —resume, /compact, /memory

Uzun investigation’larda (kod review, debug, refactor) session context’i büyür. Üç komut bu yönetimi sağlar:

--resume <name> — Named session’ı kaldığı yerden devam ettirir. Context korunur. Kullanım:

claude --resume pr-review-42
# veya oturum içinde
> /resume pr-review-42

Ne zaman: “Dün code review’a başladım, bugün devam edeceğim. Context’i korumalıyım.”

fork_session — Mevcut session’dan bağımsız dal oluşturur. Her iki fork, branch noktasına kadar olan context’i miras alır, sonra bağımsız ilerler. Kullanım:

Codebase investigation
         |
    fork_session
    /           \
Approach A:      Approach B:
Redux            Context API

Ne zaman: “İki farklı refactor yaklaşımını paralel denemek istiyorum” — her dal aynı başlangıç noktasından başlar, sonra ayrı yürür. Rehber bu kalıba CLI flag göstermez; CLI’da bu amaç için örnek komut --resume <session-name>’dır. fork_session kavramı subagent / çok-katmanlı investigation senaryolarında devreye girer.

/compact — Geçmişi özetler, eski tool call’ları sıkıştırır, context budget’ı serbest bırakir. Kullanım:

> /compact
# "Son 50 tool call özetlendi, 12K token serbest kaldı"

Ne zaman: “Context 80% dolu, henüz iş bitmedi.” Kötüye kullanma: her 5 tool call’da bir compact — gereksiz overhead, kalite kaybı.

/memory — CLAUDE.md dosyasını düzenlemek için açar; değişiklikler oturumlar arası kalıcıdır (rehber 5.8). /compact context’i sıkıştırır, /memory kalıcı talimat düzenler — ikisini karıştırma. Kullanım:

> /memory
# CLAUDE.md açılır, notlar / tercihler / proje bağlamı eklenir
# Kaydet → bir sonraki oturum başında otomatik yüklenir

Re-review karar kuralı: Context güncelse --resume; stale ise (dosyalar değişti, uzun süre geçti, context bozuldu) yeni session + kısa yapılandırılmış özet daha güvenilir (rehber 5.10). Yeni session’da “Here is a short summary of what we found: …” ile başlamak, eski tool verisiyle resume etmekten daha sağlam. Resume ediyorsan agent’a dosyaların değişmiş olabileceğini bildir; eski tool result’ları güncelliğini yitirmiş olabilir.

4. Multi-pass review stratejisi

Self-review güvenilmez (Claude kendi yazdığı koda karşı önyargılı). Multi-pass review iki farklı agent ile yapılır:

Per-file pass: Her dosya ayrı review. Her dosyanın kendi context’inde inceleme.
Cross-file integration pass: Tüm dosyalar birlikte, entegrasyon hatalarını yakala (interface uyumsuzluğu, contract ihlali, kullanım yeri yanlışlığı).

Attention dilution problemi: Tek pass’te 50 dosya verirsen, modelin dikkati yayılır, her dosyaya ortalama %2 dikkat. Önemli hatalar sığ incelenir. Çözüm: per-file + cross-file olarak ayrı pass’ler, her pass kendi context’inde.

Örnek workflow:

# Pass 1: per-file review
for f in $(git diff --name-only main...HEAD); do
  claude -p "Şu dosyayı review et: $f. Sadece bu dosya, diğerlerini yoksay. \
    CRITICAL/HIGH/MEDIUM/LOW ile sınıflandır." \
    --output-format json --json-schema '...' >> per-file-findings.json
done

# Pass 2: cross-file integration
claude -p "Tüm PR'ı bütüncül review et. Önceki per-file bulgular şunlar: \
  $(cat per-file-findings.json). Şimdi ENTEGRASYON hatalarını yakala: \
  interface uyumsuzluğu, type mismatch, kullanım yeri yanlışlığı, \
  shared state, race condition. Per-file bulguları tekrarlama." \
  --output-format json --json-schema '...' > cross-file-findings.json

Yeniden review’da: önceki pass’in bulgularını context’e dahil et (ignore etme). Yeni pass sadece ek bulgu getirsin, öncekini tekrarlamasın. “Clean slate” yapmak dikkat kaybına yol açar.

📝 Rehber bu kalıba “Prompt Chaining” der (Ch 6.3): öngörülebilir, tekrarlanabilir sıralı adımlar (per-file → cross-file review) = prompt chaining; open-ended investigation’lar (henüz scope net değil, her adım öncekinin sonucuna göre şekilleniyor) = dynamic decomposition (Ch 8.2). Sınav “bu iş prompt chaining mi dynamic decomposition mı” diye sorabilir — review / migration gibi şablonu bilinen işler chaining, “kod tabanını anla, sonra ne yapacağına karar ver” tipi investigation dynamic.

📝 Session context isolation (rehber D3.6): kodu üreten session, aynı kodu review ederken önyargılıdır — kendi kararlarını challenge etmekte zayıf. Bu yüzden review için bağımsız ikinci instance daha güvenilir; kod üretim session’ı ile review session’ı aynı olmamalı.

Rehber Ch 13’ün iki kuralı (kod tabanını tanıma / düzeltme):

Incremental investigation: Grep ile entry point (fonksiyon tanımı, export) bul → Read ile akışı izle → Grep ile kullanım yerlerini bul → Read ile consumer’ları oku → wrapper modüllerden geçerek derinleş. Tek seferde 50 dosya okuyup “anladım” demek, gerçekte hiçbir şey anlamamak demek.
Edit non-unique match fallback: Edit benzersiz eşleşme bulamazsa başarısız olur (gürültü hatası). O durumda fallback: Read ile tam dosyayı yükle → programatik olarak düzenle → Write ile yaz.

5. Severity sınıflandırması standardı

Sınav tuzağı içermese de CI/CD entegrasyonunda sık karşılaşılan: severity scale standartlaştırması. Sınav sorularının kullandığı standart:

CRITICAL: Prod outage, data loss, security vulnerability → merge blocker
HIGH: Major bug, broken feature, performance regression → should fix before merge
MEDIUM: Code smell, minor bug, suboptimal pattern → fix eventually
LOW: Style, nitpick, suggestion → optional

Schema’da enum olarak zorla. Reviewer’ın “high” / “HIGH” / “High” karışımı output üretmesini engelle.

Sınav tuzakları

“Plan mode açıkken Edit/Write tool’u kullanılabilir” — Yanlış. Plan mode’da sadece read-only tool’lar açık. Yazma için plan onaylanmalı, sonra plan mode kapatılmalı.
“CI/CD’de Claude’u interaktif stdin ile çalıştırmak mümkün” — Yanlış. CI non-interactive olmalı, -p zorunlu. Stdin’den input bekleme, prompt’u argüman olarak ver.
“--output-format json çıktıyı Pydantic schema’ya uydurur” — Yanlış. Sadece JSON formatı verir. Schema uyumu için ayrıca --json-schema vermen gerekir. İkisi farklı mekanizma.
“Multi-pass review’da yeni session açarak önceki context’i unutturmak daha iyi” — Koşullu yanlış. Context hâlâ güncel ve önceki pass’in bulguları hâlâ değerliyse --resume doğru; “yeni session = temiz başlangıç” her zaman iyi değil. Önceki bulguları context’e al, yeni pass sadece ek bulsun. Ancak stale context durumunda (dosyalar değişti, çok zaman geçti) kısa özetle yeni session açmak meşrudur — bu, “unutturmak” değil “güncellemektir”.
“--fork ana session’ı değiştirir” — Yanlış. fork_session bağımsız daldır, branch noktasına kadar miras alınan context dışında ana session’a dokunmaz. fork_session rehberin kavramsal adıdır; CLI’da bu amaç için örnek --resume <session-name>’dır.
“/compact her tool call’dan sonra otomatik çalışmalı” — Yanlış. Manuel tetiklenir, aşırı kullanım kalite kaybı. Context %80 dolunca bir kez.
“Plan mode’da Explore subagent dosya değiştirebilir” — Yanlış. Explore read-only. Plan mode’da hiçbir subagent yazma yapamaz.

Hands-on

Senaryo: Bir PR için CI/CD’de Claude review çalıştıracaksın. Gerekli yapı:

# 1. Local'da çalıştır, sonra CI'ye taşı
claude -p "$(cat .github/prompts/review.md)" \
  --output-format json \
  --json-schema '{
    "type": "object",
    "properties": {
      "findings": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "file": {"type": "string"},
            "line": {"type": "integer"},
            "severity": {"enum": ["CRITICAL","HIGH","MEDIUM","LOW"]},
            "message": {"type": "string"}
          },
          "required": ["file","line","severity","message"]
        }
      }
    },
    "required": ["findings"]
  }' > /tmp/review.json

# 2. CRITICAL varsa fail
if jq -e '.findings | map(select(.severity == "CRITICAL")) | length > 0' /tmp/review.json > /dev/null; then
  echo "::error::CRITICAL bulgular var, merge engellendi"
  exit 1
fi

# 3. PR comment olarak postla
gh pr comment $PR_NUMBER --body "$(jq -r '.findings[] | "- **\(.severity)** \(.file):\(.line) — \(.message)"' /tmp/review.json)"

Multi-pass review workflow:

# Pass 1: per-file
git diff --name-only main...HEAD | while read f; do
  claude -p "Review only $f. Per-file bulguları listele." \
    --output-format json \
    --json-schema '...' >> per-file.json
done

# Pass 2: cross-file (önceki pass'in çıktısını context'e ver)
claude -p "Cross-file integration review. Önceki per-file bulgular:
$(cat per-file.json | jq -c .)
Şimdi SADECE entegrasyon hatalarını yakala." \
  --output-format json --json-schema '...' > cross-file.json

Session yönetimi:

# Yarın kaldığın yerden devam
claude --resume pr-investigation-42

# Alternatif yaklaşım dene (rehber fork_session kavramı; CLI'da bu örnek)
# İki farklı refactor branch'ini karşılaştırmak için: branch noktasına kadar olan
# context'i paylaşan iki bağımsız dal — yaklaşım A ve B ayrı yürür
# (CLI'da bu amaç için gösterilen örnek komut --resume <session-name>)

# Context şişti, sıkıştır
> /compact

# CLAUDE.md'de kalıcı not düzenle (oturumlar arası yaşar)
> /memory

Özet

Plan mode: Mimari karar, çok dosya, birden fazla yaklaşım, geri alınamaz iş → açık. Tek dosya fix, net talep → direkt çalış.
CI/CD üçlüsü: -p (non-interactive) + --output-format json (parse edilebilir) + --json-schema (yapı garantili). Üçü birlikte “agentic CI step”.
Session yönetimi: --resume <name> devam, fork_session paralel dal (CLI’da bu amaç için örnek --resume <session-name>), /compact context sıkıştır, /memory CLAUDE.md’de kalıcı talimat düzenler. Re-review’da: context güncelse --resume, stale ise yeni session + kısa özet.
Multi-pass review: Per-file (her dosya izole) + cross-file (entegrasyon hataları). Attention dilution’ı çözer. Yeni pass önceki bulguları görsün, tekrar etmesin ama görsün.
Severity standardı: CRITICAL/HIGH/MEDIUM/LOW, schema enum ile zorla.
Sınav formülü: “CI = -p + json + schema. Re-review = resume (yeni session değil). Multi-pass = per-file + cross-file, context korunarak.”

Kaynaklar

Anthropic Docs — Claude Code: CI/CD Integration — https://docs.claude.com/en/docs/claude-code/cicd
Anthropic Docs — Claude Code: Session Management — https://docs.claude.com/en/docs/claude-code/sessions
Anthropic Docs — Claude Code: Subagents (Plan/Explore) — https://docs.claude.com/en/docs/claude-code/sub-agents
Skilljar — Claude Code Foundations: Production Workflows (Foundation course)