Vibe Coding"den "Context Engineering"e: Claude Code CLI'da Üretkenliğimi Katlayan 6 Teknik
Son aylarda Claude Code CLI ile geliştirdiğim projelerin ortak bir paydası var: hiçbiri "vibe coding" ile bitmedi. Hepsi context engineering ile bitti.
Bu yazıda, "AI'a istediğini yazınca olur" inancından, "AI'ın bağlamını mühendislik gibi tasarlamak" disiplinine geçişimde işime yarayan teknikleri anlatacağım. Anlatımı somutlaştırmak için makale boyunca tek bir örnek proje kullanacağım: TaskFlow — kanban tabanlı bir takım yönetim SaaS'i. Stack tanıdık olabilir: .NET 10 Clean Architecture (CQRS + MediatR), Next.js 16, PostgreSQL, Redis, SignalR, RabbitMQ, Docker.
Önce Tanım: "Vibe Coding" Neden Yeterli Değil?
Vibe coding, Andrej Karpathy'nin popülerleştirdiği bir terim: AI asistana sezgisel komutlar verip çıkanı kabul etme tarzı. Ufak hobi projelerinde harika, eğlenceli, hızlı.
Ama gerçek bir projede — TaskFlow gibi multi-tenant, real-time, 4 ayrı microservice'li bir platformda — vibe coding 5. promptta çöker. Çünkü:
- AI önceki kararları unutur (yeni session, sıfır bağlam).
- Mimari tutarlılık kaybolur (bir yerde Repository pattern, başka yerde direkt DbContext).
- Aynı şeyi her seferinde baştan açıklarsın (Türkçe yaz, Onion Architecture kullan, ProblemDetails döndür...).
- Modelin context window'u alakasız bilgilerle dolar, asıl iş için yer kalmaz.
Burada context engineering devreye giriyor: AI'a verdiğin bağlamı tıpkı bir API tasarlar gibi tasarlamak. Doğru bilgiyi, doğru anda, doğru yapıda vermek.
İşte Claude Code CLI'da bunu yaparken kullandığım 6 teknik.
1. CLAUDE.md ve Modüler .claude/rules/ Yapısı
Bu, en temel taşı. CLAUDE.md, projenin köküne koyduğun ve Claude'un her oturumda otomatik okuduğu bir hafıza dosyası. İçinde mimari kararlar, dil tercihleri, kod stil kuralları, dokunulmaz kısıtlar bulunur.
Yaptığım hata: Başlarda CLAUDE.md'yi 1500 satırlık dev bir dosya yapmıştım. Sonuç: her sorguda bu dev metin context'i şişiriyor, asıl iş için yer kalmıyordu.
Çözüm: TaskFlow'da CLAUDE.md'yi modüler kuralları işaret eden ince bir indeks dosyasına dönüştürdüm:
.claude/
├── rules/
│ ├── 00-language.md # "Türkçe açıklama, kod İngilizce"
│ ├── 01-architecture.md # Clean Architecture katmanları
│ ├── 02-naming.md # Naming conventions
│ ├── 03-error-handling.md # ProblemDetails pattern
│ ├── 04-testing.md # xUnit + FluentAssertions
│ └── 05-frontend.md # Next.js 16 App Router kuralları
CLAUDE.md ise sadece şunu söylüyor:
MARKDOWN1# TaskFlow — Proje Bağlamı 2 3Bu projede aşağıdaki kuralları **zorunlu** olarak uygula: 4- Mimari: @.claude/rules/01-architecture.md 5- Dil: @.claude/rules/00-language.md 6- Hata yönetimi: @.claude/rules/03-error-handling.md 7 8Görev yönetimi için: @.claude/tasks/active/ 9Geçmiş dersler için: @.claude/tasks/lessons.md
@ ile dosya referansı verdiğinde Claude o dosyayı sadece gerektiğinde okur. Context window'un yeri boşa harcanmaz.
💡 Pratik not: Bir keresinde Claude Türkçe konuşma dilini bırakıp İngilizceye kayıyordu.
00-language.md'ye "TÜM açıklamalar Türkçe olacak, sadece kod ve teknik terimler İngilizce kalacak" diye eklediğimde sorun ortadan kalktı. Tek satır kural, 50+ promptta tekrarlamadığım bir disipline dönüştü.
2. Skills System: Tekrarlanabilir Uzmanlık Paketleri
.claude/skills/ klasörü, projeye özel "uzmanlık modülleri" tutmana izin veriyor. Her skill bir dizindir; içinde SKILL.md (zorunlu, giriş noktası) ve isteğe bağlı destekleyici dosyalar bulunur. Resmi dokümantasyondaki yapı tam olarak şöyle:
my-skill/
├── SKILL.md # Zorunlu — frontmatter + ana talimatlar
├── reference.md # Detaylı referans (gerektiğinde yüklenir)
├── examples.md # Kullanım örnekleri (gerektiğinde yüklenir)
└── scripts/
└── helper.py # Çalıştırılabilir script
SKILL.md'nin başında YAML frontmatter olur, sonrasında markdown içerik gelir. Frontmatter'da Claude Code'un resmi olarak desteklediği alanlardan en kritikleri:
name→ Slash komut adı olur (/my-skill). Sadece küçük harf, rakam, tire; 64 karakter limit.description→ Skill'in ne yaptığını ve ne zaman kullanılacağını anlatır. Claude bu metne bakarak skill'i otomatik tetikleyip tetiklemeyeceğine karar verir. Front-load et — en önemli kullanım senaryosu başta olsun.when_to_use→ İsteğe bağlı,description'a ek tetikleme ipuçları. Trigger fraz örnekleri buraya yazılır.disable-model-invocation: true→ Skill'i Claude otomatik yükleyemez, sadece sen/skill-nameile çağırabilirsin./deploy,/commitgibi yan etkili işler için kritik.allowed-tools→ Skill aktifken Claude'un izin sormadan kullanabileceği toolları listeler. Örn.Read GrepveyaBash(git add *) Bash(git commit *).argument-hintve$ARGUMENTS→ Slash komutuna parametre geçirmeyi mümkün kılar.
ℹ️ Önemli güncelleme: Yeni Claude Code sürümlerinde custom commands ile skills birleşti.
.claude/commands/deploy.mdve.claude/skills/deploy/SKILL.mdaynı/deploykomutunu üretir. Eski.claude/commands/dosyaların çalışmaya devam ediyor; ama destekleyici dosya, supporting scripts gibi ek özellikler isteyince skill yapısı çok daha güçlü.
TaskFlow'dan somut örnek: recurrence-engine skill'i
TaskFlow'da en çok dönüşü gördüğüm skill, tekrar eden görev (recurring task) motoru oldu. RRULE benzeri bir kural diliyle "her pazartesi", "her ayın son cuması", "iki haftada bir salı" gibi desenleri yöneten bir modül:
.claude/skills/recurrence-engine/
├── SKILL.md
├── rrule-syntax.md # RRULE detayları (gerektiğinde okunur)
├── timezone-edge-cases.md # DST, IANA tz davranışları
└── examples/
├── full-implementation.cs # C# referans implementasyonu
└── edge-cases.cs # Şubat 29, DST geçişleri, ay-sonu
SKILL.md'nin frontmatter'ı şöyle:
MARKDOWN1--- 2name: recurrence-engine 3description: TaskFlow'da tekrar eden görevler için RRULE tabanlı next-occurrence hesaplama motoru. Timezone-aware, DST ve takvim edge case'lerini yönetir. 4when_to_use: | 5 "Tekrar eden görev", "RRULE", "next occurrence", 6 "her ayın son X günü", "iki haftada bir" gibi 7 düzenleri kodlamak gerektiğinde. 8allowed-tools: Read Grep 9--- 10 11Tekrar eden görev planlamak için bu adımları izle: 12 131. RRULE string'ini parse et (detay: rrule-syntax.md) 142. Kullanıcının timezone'unu IANA formatında al 153. Bir sonraki occurrence'ı hesapla (bkz. timezone-edge-cases.md) 164. DST geçişinde double-trigger riskini kontrol et 175. C# referans implementasyonunu örnek al: examples/full-implementation.cs 18 19## Kritik kurallar 20- UTC'de değil, kullanıcının timezone'unda hesapla 21- "Last friday of month" için takvim ayını dolaş, hardcoded gün kullanma 22- Şubat 29 → şubat 28 fallback'i her zaman uygula
"Kullanıcı her ayın son cuması saat 17:00'da hatırlatma görevi oluşturuyor, Avrupa/İstanbul timezone'unda bir sonraki tetiklenmeyi nasıl hesaplarım?" diye sorduğum an, Claude description ve when_to_use alanlarındaki anahtar kelimelerle eşleştirip skill'i otomatik açıyor. DST geçişini, ay-sonu mantığını her seferinde anlatmak zorunda kalmıyorum.
💡 Anti-pattern uyarısı:
SKILL.md'yi 500 satırın altında tut. Detaylı reference materyali ayrı dosyalara böl veSKILL.md'den onlara link ver — Claude o dosyaları sadece gerektiğinde okur. Tüm bilgiyi tek dosyaya tıkıştırmak skill'in tüm context tasarrufu avantajını yok eder.Aynı şekilde her ufak iş için skill yazma. Skill, en az 3 farklı bağlamda tekrar edecek ve her seferinde aynı detayları açıklaman gereken bir uzmanlık alanı için anlamlı. "Bir kerelik" işler için skill üretmek over-engineering.
3. Slash Commands: Sık Tekrarlanan İşi Tek Komuta İndir
Yukarıda değindim: artık slash commands skills ile birleşti. Ama basit, supporting file gerektirmeyen sık-iş otomasyonları için hâlâ .claude/commands/ formatı ya da minimal bir SKILL.md işe yarıyor.
TaskFlow'da kendime şunları yazdım:
.claude/commands/
├── feature-skeleton.md # /feature-skeleton
├── pr-prepare.md # /pr-prepare
├── add-integration-test.md # /add-integration-test
└── docs-update.md # /docs-update
/feature-skeleton komutunun içeriği — frontmatter + $ARGUMENTS kullanımı:
MARKDOWN1--- 2description: Yeni feature için Onion Architecture iskeletini kur 3argument-hint: [feature-name] 4--- 5 6$ARGUMENTS feature'ı için aşağıdaki yapıyı oluştur: 7 81. Application/Features/$ARGUMENTS/ 9 - Commands/, Queries/, Validators/, DTOs/, Mappers/ 102. Domain'e gerekirse yeni entity ekle 113. BusinessRuleEngine üzerinden iş kuralı sınıfı 124. ProblemDetails formatında hata sınıfları 135. xUnit test scaffold'u Tests/ klasörüne 14 15Kod İngilizce, açıklamalar Türkçe. 16Mevcut başka feature'larla naming consistency koru 17(referans: @Application/Features/Boards/).
/feature-skeleton task-comments yazıyorum, $ARGUMENTS yerine task-comments geçiyor, dakikalarca süren bir setup işi tek prompt'a iniyor — üstelik her zaman aynı kalitede, yorgun olduğum günlerde de.
Yan etkili işler için disable-model-invocation: true koymayı unutma — Claude'un kendi başına /deploy çalıştırmasını istemezsin.
4. Task Management: backlog/active/done/lessons.md Akışı
Bu, Claude Code mastery yolculuğumda en geç keşfettiğim ama en çok dönüş aldığım pattern.
TaskFlow'da şu yapıyı kurdum:
.claude/tasks/
├── backlog/ # Yapılacak işler
│ ├── 001-realtime-presence.md
│ ├── 002-rabbitmq-dlq.md
│ └── 003-board-permissions.md
├── active/ # Şu an üstünde çalışılan
│ └── 002-rabbitmq-dlq.md
├── done/ # Bitmiş işler (ay/yıl alt klasörleriyle)
│ └── 2026-04/
│ ├── 001-realtime-presence.md
│ └── 004-redis-cache-layer.md
└── lessons.md # Bu projede öğrendiğim acı dersler
Her *.md task dosyası şu yapıda:
MARKDOWN1# 002 — RabbitMQ Dead Letter Queue Pattern 2 3## Bağlam 4Notification servisinde mesajlar kaybolmamalı. Şu an handler 5exception fırlatınca mesaj sessizce drop ediliyor. 6 7## Kabul Kriterleri 8- [ ] DLQ exchange + queue tanımı 9- [ ] 3 retry sonrası DLQ'ya geçiş 10- [ ] DLQ izleme dashboard endpoint'i (admin only) 11- [ ] Integration test: 3. fail'de DLQ'ya düşmeli 12 13## Notlar 14- Mevcut consumer'lar BasicAck/BasicNack pattern'ini kullanıyor 15- Retry sayısı message header'da tutulacak (x-death değil)
lessons.md ise altın değerinde. Oraya proje boyunca öğrendiğim, AI'a tekrar öğretmek istemediğim dersleri yazıyorum:
MARKDOWN1# Acı Dersler — TaskFlow 2 3## PostgreSQL 4- ❌ JSONB içinde search yaparken plain index 5- ✅ GIN index + jsonb_path_ops operator class 6 7## SignalR 8- ❌ Connection-id bazlı mesajlama (reconnect'te kayboluyor) 9- ✅ User-id bazlı groups + Redis backplane 10 11## RabbitMQ 12- ❌ Direct exchange + manual routing key dağıtımı 13- ✅ Topic exchange + 4 ayrı consumer queue + DLQ pattern 14 15## Claude Code'un kendisi 16- ❌ Büyük migration'ları tek promptta isteme 17- ✅ Önce plan mode, sonra parça parça uygula
Yeni bir oturum açtığımda Claude'a "lessons.md'yi oku ve bu kuralları unutma" demem yeterli. Aynı hatayı 3. kez yapmıyoruz.
Not — Opus 4.7 (Nisan 2026): Claude Code'a gelen otomatik Session Memory ile beraber, yeni oturumda Claude'a "lessons.md'yi oku" demeye artık gerek yok — geçmiş session özetlerini kendisi context'e alıyor. Structured task dosyalarını insan-okunur takip için tutmaya devam edebilirsin, ama oturum başlatma ritüeli ortadan kalktı.
5. MCP Serverları: AI'ı İzole Bir Beyin Olmaktan Çıkar
MCP (Model Context Protocol), Claude'a dış dünyaya pencere açan protokol. Doğru MCP server'lar, AI'ın "training data'sındaki eski bilgiyi söyleme" sorununu büyük ölçüde çözüyor.
TaskFlow'da aktif kullandıklarım:
- Context7 → Güncel dokümantasyon. ".NET 10'da Minimal API endpoint filter nasıl?" diye sorduğumda Claude'un kafasındaki .NET 8 bilgisini değil, gerçek dokümanı okuyor.
- PostgreSQL MCP → Migration dosyası yazdırırken canlı veritabanı şemasını görerek ilerliyor; "böyle bir kolon var mı" diye tahmin yürütmüyor.
💡 Anti-pattern uyarısı: Her gördüğün MCP server'ı projeye ekleme. Her aktif MCP, oturumda context tüketiyor. Sadece o projede gerçekten kullandıklarını ekle.
6. @ Dosya Referansı + Plan Mode: Context'i Sen Yönet
Son ve belki de en kritik teknik: AI'a ne kadar bilgi gösterdiğini sen kontrol et.
@ operatörü ile dosya/klasör referansı, Claude'a "şu anda şu dosyaya bak" demenin yolu. Tüm projeyi taratmak yerine cerrah hassasiyetiyle çalışıyorsun:
Şu hatayı çöz: NullReferenceException at TaskAssignmentService.
Bağlam:
- Implementation: @Application/Features/Tasks/Commands/AssignCommand.cs
- Test: @Tests/Tasks/AssignCommandTests.cs
- Domain entity: @Domain/Entities/TaskItem.cs
Not: Repository veya DbContext'e dokunma, sadece command handler'da çöz.
3 dosya, sınır çizilmiş bir görev. AI'ın kafası dağılmıyor.
Plan mode ise büyük değişikliklerden önce bir nefes alma noktası. Shift+Tab ile plan mode'a geçtiğinde Claude değişiklik yapmadan önce ne yapacağını yazıyor. Onayladığında uyguluyor. TaskFlow'da "guest user feature'ını projeden tamamen kaldır" gibi geniş yüzeyli işlerde plan mode'suz girmek intihar — modelin nereye dokunacağını önce görmek istersin.
Toparlarsak: Vibe Coding'i Terk Etme, Olgunlaştır
Vibe coding'in bir yeri var — hızlı prototip, throwaway script, "şunu bir denesem" anları. Ama production projende, müşteriye demo göstereceğin platformda, paranı kazandığın işte — sezgi yetmez.
Context engineering aslında bir disiplin: AI'ın bağlamını, kod tabanın gibi versiyonla, modülerleştir, dokümante et, refactor et.
Benim için 6 temel direk:
CLAUDE.md+ modüler.claude/rules/— proje hafızası.claude/skills/— tekrarlanabilir uzmanlık (SKILL.md+ supporting files + frontmatter).claude/commands/veya minimal SKILL'ler — sık işlerin otomasyonu.claude/tasks/(backlog/active/done/lessons) — stateful proje takibi- MCP serverları — dış dünyayla bağlantı
@referansı + plan mode — context disiplini
Bu altısını oturttuğumda fark ettim ki Claude Code CLI artık "kod yazan asistan" değil, projemin bağlamını paylaştığım bir takım arkadaşı gibi davranıyor. Aynı hatayı tekrar yapmıyor. Mimari kararları unutmuyor. Türkçeden İngilizceye kaymıyor.
Yapay zekayla çalışmak prompt yazmak değil — context kurmaktır.
Kaynak: Claude Code resmi dokümantasyonu — https://code.claude.com/docs/en/overview