İçindekiler
Claude Code’u ilk kez açan birinin yaptığı şey genelde aynıdır: “Bana bir müşteri yönetim uygulaması yaz.” Beş dakika sonra ekranda dört yüz satır kod vardır. Uygulama belki çalışır da. Ama birkaç soru cevapsız kalır: Hangi dosyalara dokunuldu? Hangi paketler kuruldu? Veritabanına hangi kullanıcıyla bağlanıldı? Ve en önemlisi: Bu kodu yarın kim anlayacak, kim bakımını yapacak?
Kod üreten bir sohbet ile projenizin içinde çalışan bir asistan arasındaki fark burada başlar. Claude Code projenizi okur, dosya düzenler, komut ve test çalıştırır. Bu güç, doğru bir çerçeve içinde kullanıldığında bir ekibin haftalarca süren işini günlere indirir. Çerçevesiz kullanıldığında ise kimsenin tam anlamadığı, bakımı yapılamayan ve güvenliği belirsiz bir yazılım üretir.
Bu yazı, Claude Code ile uygulama geliştirmek: Fikirden yayına bir yol haritası serisinin ilk bölümü. Bu bölümde Claude Code’a tek satır kod yazdırmadan önce yapılması gerekenleri anlatıyorum. İkinci bölüm plan modundan yayına kadar olan kısmı kapsıyor. Seri boyunca örnek olarak basit bir CRM kuruyoruz: müşteriler, yetkililer, görüşme notları ve fırsatlar.
Bir ön not: Bu seriyi takip etmek için usta bir yazılımcı olmanız gerekmiyor, ama kodu okuyabilmek büyük avantaj. Çünkü bütün yazının üzerine kurulduğu ilke şu: Kodu siz anlamıyorsanız, o kod sizin değildir. Claude Code yazar; ama yayına giden her satırdan siz sorumlusunuz.
1. Ne yapacağınızı bir sayfada yazın
İlk adımın Claude Code ile hiçbir ilgisi yok. Bir metin dosyası açın ve uygulamanızı bir sayfada tarif edin. Bu sayfa iki işe yarar: Size ne yapmak istediğinizi netleştirir, Claude Code’a da her konuşmada geri döneceği bir pusula olur.
Örnek CRM için böyle bir sayfa şöyle görünür:
# Ürün tanımı: Basit CRM
## Amaç
Satış ekibinin müşteri bilgilerini, görüşmelerini ve açık fırsatlarını
tek bir yerden takip etmesi. Bugün bu bilgiler kişisel Excel dosyalarında.
## Kullanıcılar
- Satış temsilcisi: kendi müşterilerini ve fırsatlarını yönetir.
- Satış müdürü: ekibinin bütün müşterilerini ve fırsatlarını görür.
## Üç ana iş
1. Müşteri ve yetkili kaydı açmak, aramak, güncellemek.
2. Bir görüşmeyi not olarak kaydetmek.
3. Fırsatları aşamalarıyla (yeni, teklif, kazanıldı, kaybedildi) izlemek.
## Veri
Müşteri (unvan, vergi numarası, telefon), yetkili, görüşme notu, fırsat.
## "Bitti" ne demek?
Bir temsilci yeni bir müşteriyi, ilk görüşmesini ve bir fırsatı
beş dakikadan kısa sürede kaydedebiliyor; müdür ekibinin açık
fırsatlarını tek ekranda görüyor.
## Şimdilik yapmayacaklarımız
- Teklif ve fatura üretmek
- E-posta entegrasyonu
- Mobil uygulama
En değerli bölüm sondaki listedir. CRM projeleri yazısında anlattığım “herkesin her isteği” tuzağına karşı en iyi korunma, neyi yapmayacağınızı baştan yazmaktır. Claude Code istekli bir asistandır; ona sınır çizmezseniz kapsam her konuşmada biraz daha büyür.
2. Araçları kurmak
Claude Code’u iki ayrı yerden kullanabilirsiniz. İkisi aynı motoru, aynı ayarları ve aynı proje dosyalarını kullanır; fark çalışma biçimindedir.
- VS Code eklentisi günlük geliştirme için idealdir. Claude’un yaptığı her değişikliği editörde fark görünümünde (diff) görür, kabul ya da reddedersiniz. Seçtiğiniz kodu ya da bir dosyayı doğrudan bağlam olarak verebilirsiniz.
- Terminal uzun süren görevler, otomasyon ve sunucu üzerindeki işler için daha rahattır.
Kurulumun ikinci yarısı Git’tir ve isteğe bağlı değildir. Claude Code ile çalışırken Git sizin güvenlik ağınızdır: Her anlamlı adımdan sonra bir commit, her deneme için ayrı bir dal. Yanlış giden bir adımı geri almanın en güvenilir yolu budur.
Projeye başlarken hangi dosyanın ne işe yaradığını bilmek de önemli. Kural basit: Ekibin ortak kuralları repoda, kişisel tercihler dışarıda.
| Dosya | Ne için | Git’e girer mi? |
|---|---|---|
CLAUDE.md | Projenin ekip için ortak talimatları | Evet |
CLAUDE.local.md | Bu projedeki kişisel notlarınız | Hayır, .gitignore’a ekleyin |
.claude/settings.json | Ekibin ortak ayarları: izinler, hook’lar | Evet |
.claude/settings.local.json | Bu projedeki kişisel ayarlarınız | Hayır |
~/.claude/CLAUDE.md | Bütün projelerde geçerli kişisel tercihleriniz | Projenin parçası değil |
3. Ortama uygun teknoloji: Kodu yazan değil, işleten belirler
Claude Code her dilde kod yazabildiği için teknoloji seçmek hiç bu kadar kolay olmamıştı. Tuzak da tam burada. Asıl soru “hangisini yazdırabilirim?” değil, “bunu kim çalıştıracak, kim güvenliğini sağlayacak, benden sonra kim bakımını yapacak?” sorusudur.
Diyelim ki şirketinizin uygulamaları Windows sunucularda, IIS üzerinde React ve Node.js ile çalışıyor. Kendi portalınızı Flutter ve Java ile yazarsanız, bilgi işlem ekibinden hiç bilmediği bir şeyi işletmesini, güncellemesini ve güvenliğini sağlamasını istemiş olursunuz. Uygulama bir hafta sonra çalışır; ama bir yıl sonra sahipsiz kalır.
Seçim yaparken bakılacak şey mevcut ortamdır: sunucular ve barındırma, şirketin oturum açma sistemi, kullanılan veritabanı, yayın süreci ve ekibin bildiği diller. Bu ortamın içinde kalan seçenekler arasında ise şu ilke yol gösterir:
Yapay zekanın en iyi çalıştığı yapı, insanın da en kolay bakım yaptığı yapıdır.
Yapay zeka; açık kaynakta çok örneği bulunan, tipli, kararlı ve bir işin yapılış biçimi belli olan teknolojilerde en iyi sonucu verir. TypeScript, C#, Java gibi tipli dillerde asistanın hatalarının önemli bir kısmını derleyici, kod hiç çalışmadan yakalar. Her altı ayda bir köklü değişen çatılarda ise asistan eski ve yeni yazım biçimlerini karıştırabilir. Bu ölçütlerle birkaç güçlü seçenek:
| Yapı | Ne zaman uygun | Yapay zeka açısından güçlü yanı | Dikkat |
|---|---|---|---|
| React ve Node.js (uçtan uca TypeScript) | Şirket zaten JavaScript ve Node kullanıyorsa | Tek dil; arayüz ile sunucu arasında ortak tipler | Paket bolluğu: İzin verilen paketleri yazın, asistan her işe yeni paket eklemesin |
| Angular ve Python (FastAPI) | Kurumsal bir arayüz ile veri ağırlıklı bir arka uç bir aradaysa | Angular’ın katı düzeni; Python tiplerinden üretilen ortak API sözleşmesi | İki dil: API sözleşmesi tek kaynak olmalı, elle kopyalanmamalı |
| React ya da Angular ile ASP.NET Core (C#) | Microsoft ekosistemi: Windows sunucular, IIS, SQL Server, kurumsal giriş | Güçlü tipli bir dil ve yerleşik kurumsal kalıplar | Sunucudaki .NET sürümüyle uyumu baştan netleştirin |
| Django (Python, tek proje) | Küçük ekip, hızlı başlangıç, çok etkileşimli olmayan ekranlar | Çok kararlı ve yaygın; hazır giriş sistemi, yönetim paneli, veritabanı katmanı | Çok etkileşimli ekranlarda sınırlarına daha erken gelinir |
Bu serideki örnek CRM’i Angular ve Python (FastAPI) ile kuruyoruz. Angular’ın katı düzeni asistanın kodu dağıtmasını önler; FastAPI’de tanımlanan tiplerden otomatik bir API sözleşmesi çıkar ve Angular tarafının istemcisi bu sözleşmeden üretilebilir. İki ayrı dil olduğu halde “müşteri” nesnesinin tanımı tek bir kaynaktan gelir.
Uzun dosya, az okunan dosyadır. Aynı ilkenin bir de dosya düzeyindeki karşılığı var. Claude Code çok uzun bir dosyayı tek seferde okumaz; ilk bölümünü okur, gerisi için tekrar tekrar parça ister. Bu, bağlamı hızla tüketir ve dosyanın bir kısmını gözden kaçırma, yanlış yeri düzenleme riskini artırır. Aynı dosya bir insan için de okunmaz haldedir. Her dosya tek bir iş yapsın, kod iş alanlarına göre klasörlensin (musteriler/, gorusmeler/, firsatlar/) ve birkaç yüz satırı geçen dosyalar bölünsün. Bu kuralı aşağıda CLAUDE.md’ye yazacak, hook’larla da destekleyeceğiz.
Proje değil, portföy düşünün. Yapay zeka her yeni projeyi istediğiniz teknolojide sıfırdan başlatmayı kolaylaştırdığı için şirketlerde teknoloji karmaşası hiç olmadığı kadar hızlı büyüyebilir. Bedeli projeyi kurarken değil, aylar sonra işletirken ortaya çıkar: Bir proje MSSQL’de, biri PostgreSQL’de, biri MariaDB’de ise üç ayrı yedekleme, izleme ve güncelleme düzeni, üç ayrı uzmanlık gerekir. Bunun yerine şirketin iç uygulamaları için bir kez karar verin ve yazın: tek bir veritabanı motoru, bir ya da en fazla iki dil, tek bir yayın yöntemi, tek bir giriş sistemi. Bu kararları içeren bir şablon proje ve onunla gelen ortak bir CLAUDE.md hazırlayın; her yeni proje oradan başlasın. Standarttan sapmak mümkün, ama yazılı bir gerekçeyle.
Kaçınılması gerekenler kısaca:
- Her projede farklı bir dil, çatı ve veritabanı.
- Tek projede üç dört dil.
- Yeni ve az bilinen çatılar; asistan eğitim tarihinden sonra çıkmış sürümlerde olmayan fonksiyonlar uydurabilir.
- Küçük bir CRM için mikroservisler.
- Her işe yeni bir kütüphane.
4. Projenin hafızası: CLAUDE.md
CLAUDE.md, Claude Code’un her oturumun başında okuduğu talimat dosyasıdır. Projenin ne olduğunu, nasıl çalıştırıldığını ve hangi kurallara uyulacağını burada söylersiniz. Her konuşmada aynı şeyleri baştan anlatmak zorunda kalmazsınız.
Başlamanın en kolay yolu /init komutudur. Claude projenizi inceler ve bulduğu komutlarla, yapıyla, kurallarla bir taslak CLAUDE.md hazırlar; dosya zaten varsa üzerine yazmaz, iyileştirme önerir. Sonra bu taslağı, Claude’un kendi başına keşfedemeyeceği bilgilerle siz tamamlarsınız: ürün tanımı, teknoloji kararları, yasaklar.
Claude Code’un belgeleri CLAUDE.md dosyasını 200 satırın altında tutmayı öneriyor: Uzun dosyalar daha fazla bağlam tüketir ve talimatlara uyumu azaltır. Bu yüzden CLAUDE.md bir el kitabı değil, bir özet olmalı. Sadece belirli klasörlerde geçerli kuralları ayrı kural dosyalarına taşıyabilirsiniz; bunlar yalnızca Claude o klasörlerde çalışırken yüklenir. Başka bir dosyayı @docs/urun.md gibi bir yazımla CLAUDE.md’ye bağlamak da mümkün; ama bağlanan dosya da her oturumda yüklendiği için bağlam maliyetini azaltmaz.
Örnek CRM’in CLAUDE.md dosyası şöyle başlayabilir:
# Basit CRM
Satış ekibi için müşteri, görüşme ve fırsat takibi.
Ürün tanımı: @docs/urun.md
## Teknoloji
- Arayüz: Angular (TypeScript). Sunucu: Python, FastAPI. Veritabanı: PostgreSQL.
- Bunların dışında dil, çatı ya da veritabanı ekleme.
- Yeni bir paket eklemeden önce sor; adını, ne işe yaradığını ve neden
gerektiğini açıkla.
## Komutlar
- Sunucuyu çalıştır: `uvicorn app.main:app --reload`
- Sunucu testleri: `pytest`
- Arayüz: `npm start`, testler: `npm test`
## Yapı
- Kod iş alanlarına göre klasörlenir: musteriler/, gorusmeler/, firsatlar/.
- Her dosya tek bir iş yapar; 300 satırı geçen dosyayı böl.
## Kurallar
- Testler geçmeden bir işi bitmiş sayma.
- Veritabanı şemasını yalnızca migration dosyasıyla değiştir, asla elle.
- Şifre, anahtar ya da bağlantı bilgisini koda yazma; ortam değişkeninden oku.
- Gerçek müşteri verisi kullanma; örnek veriyi kendin üret.
## Yasaklar
- .env dosyalarını okuma ya da değiştirme.
- Canlı veritabanına bağlanma.
- main dalına doğrudan push yapma.
Bu dosyanın en büyük düşmanı eskimesidir: Kod değişir ama CLAUDE.md değişmezse Claude eskimiş talimatlara göre çalışır. Bunu nasıl önleyeceğimizi ikinci bölümde ayrıca anlatacağım.
5. Skill’ler: az ama doğru
Skill, Claude Code’a belirli bir işi nasıl yapacağını öğreten, paketlenmiş bir talimat setidir; gerekirse yardımcı betikler de içerir. Örneğin bir güvenlik denetimini adım adım nasıl yapacağını ya da bir rapor biçimini nasıl üreteceğini anlatan bir skill. Kendi skill’lerinizi yazabileceğiniz gibi hazır olanları da kurabilirsiniz. Hazır skill’leri bulmak için skills.sh iyi bir başlangıç noktası; listelenen skill’ler tek bir komutla kurulur:
npx skills add <sahibi/repo>
Kurmak kolay olduğu için çok kurma eğilimi doğar. Fazla skill’in dört bedeli vardır:
- Bağlam şişer. Claude, hangi skill’i ne zaman kullanacağına karar verebilmek için kurulu her skill’in açıklamasını konuşmanın başından itibaren elinde tutar. Ne kadar çok skill, o kadar az yer.
- Talimatlar çakışır. Benzer işler için birden fazla skill olunca Claude yanlış olanı seçebilir ya da aynı işi her seferinde farklı yapar.
- Güvenlik. Bir skill, sizin bilgisayarınızda sizin yetkilerinizle çalışan betikler içerebilir. Üçüncü taraf bir skill, kurduğunuz bir yazılım kadar dikkat ister.
- Bakım. Unutulmuş ve eskimiş bir skill, projeyi çoktan değişmiş kurallara göre yönlendirmeye devam eder.
Pratik kural: Sıfırla başlayın. Bir işi Claude’a üçüncü kez tarif ettiğinizde, o tarif bir skill olmayı hak ediyordur. Kurmadan önce içeriğini okuyun, sadece güvendiğiniz kaynaklardan kurun ve projeye özel skill’leri proje klasöründe tutun. /context komutu, kurulu skill’lerin bağlamda ne kadar yer kapladığını da gösterir.
6. Hook’lar: ricadan kurala
CLAUDE.md’ye yazdığınız bir kural bir ricadır. Claude çoğu zaman uyar; ama uzun bir oturumda, araya giren onlarca dosyanın arasında unutabilir. Hook ise Claude Code’un belirli anlarda her seferinde çalıştırdığı bir komuttur: bir dosya düzenlendikten sonra, bir komut çalışmadan önce, Claude işini bitirdiğinde ya da onayınızı beklediğinde. Modelin hatırlamasına bağlı değildir.
Örnek CRM için iki hook yeterli bir başlangıç: Her düzenlemeden sonra dosyayı biçimlendirmek ve tehlikeli komutları daha çalışmadan durdurmak. Hook’lar ekibin ortak ayar dosyası .claude/settings.json’a yazılır:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/bicimlendir.sh" }]
}
],
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/tehlikeli-komut.sh" }]
}
]
}
}
Hook’a gelen bilgi, örneğin düzenlenen dosyanın adı ya da çalıştırılmak istenen komut, JSON olarak verilir. Biçimlendirme betiği dosyanın türüne göre doğru aracı çalıştırır:
#!/bin/bash
# .claude/hooks/bicimlendir.sh
DOSYA=$(jq -r '.tool_input.file_path')
case "$DOSYA" in
*.py) ruff format "$DOSYA" ;;
*.ts | *.html | *.scss) npx prettier --write "$DOSYA" ;;
esac
Tehlikeli komut betiği ise komutu inceler ve gerekirse engeller. Claude engellendiğini ve nedenini görür, başka bir yol arar:
#!/bin/bash
# .claude/hooks/tehlikeli-komut.sh
KOMUT=$(jq -r '.tool_input.command')
if echo "$KOMUT" | grep -qiE 'rm -rf|drop (table|database)|git push .*main'; then
jq -n '{
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "deny",
permissionDecisionReason: "Bu komut proje kurallarına göre engellendi."
}
}'
fi
Betikleri çalıştırılabilir yapmayı unutmayın (chmod +x .claude/hooks/*.sh). Windows’ta aynı hook’lar PowerShell betikleriyle yazılabilir. Hook’u kendiniz yazmak zorunda da değilsiniz; Claude’a ne istediğinizi anlatın, betiği ve ayarı o yazsın, siz okuyup onaylayın.
Hook’ların başka yerinde kullanımları da var: Claude işini bitirdiğinde testleri çalıştırıp sonucu ona geri vermek, Claude onayınızı beklediğinde size bildirim göndermek ya da bir lint kuralıyla dosya uzunluğu sınırını denetlemek. Pratik kural: Bir kuralı CLAUDE.md’de ikinci kez hatırlatmak zorunda kaldıysanız, o kural hook olmayı hak ediyordur.
7. Güvenlik çerçevesi: önce çit, sonra bahçe
Claude Code’a kod yazdırmaya başlamadan önce neye dokunabileceğini ve neye asla dokunamayacağını belirleyin.
İzin modunu bilin. Claude Code’un birkaç çalışma modu var: Her işlemde size soran manuel mod, dosya düzenlemelerini onaysız yapan mod, sadece okuyup plan çıkaran plan modu ve işlemleri sizin yerinize ikinci bir modelin değerlendirdiği auto modu. Güncel sürümlerde terminal ve VS Code oturumları varsayılan olarak auto modunda başlar. Hassas bir projede bunu bilin ve gerekiyorsa manuel modda çalışın. Modlar arasında terminalde Shift+Tab ile, VS Code’da mod göstergesinden geçilir. Bütün izin kontrollerini kapatan modu şirket projelerinde hiç kullanmayın.
Kuralları yazın. Mod ne olursa olsun, ayar dosyasına yazdığınız kurallar sınırı çizer. Bir yasaklama kuralı, daha dar bir izin kuralıyla delinemez:
{
"permissions": {
"allow": ["Bash(pytest *)", "Bash(npm test *)"],
"ask": ["Bash(git push *)", "Bash(alembic upgrade *)"],
"deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
}
}
Bu ayarla testler onaysız çalışır; push ve veritabanı şemasını değiştiren komutlar her seferinde size sorulur; şifrelerin durduğu dosyalar hiç okunamaz.
Şifreler koda girmez. Bağlantı bilgileri ve anahtarlar ortam değişkenlerinde ya da şirketin şifre yöneticisinde durur; kod onları oradan okur. Claude’un .env dosyalarını okuyamaması bu yüzden önemli: Okuyamadığı bir şifreyi yanlışlıkla bir dosyaya, bir loga ya da bir commit’e yazamaz.
Asistana asla yetkili bir veritabanı kullanıcısı vermeyin. Claude’un ve geliştirme ortamınızın bağlandığı veritabanı kullanıcısı, işi için gereken en az yetkiye sahip olmalı. Tablo silme ya da şema değiştirme yetkisi olmamalı, canlı veritabanına hiç bağlanamamalı:
CREATE ROLE crm_gelistirme LOGIN PASSWORD '...';
GRANT CONNECT ON DATABASE crm_gelistirme TO crm_gelistirme;
GRANT USAGE ON SCHEMA crm TO crm_gelistirme;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA crm TO crm_gelistirme;
-- Tablo silme, tabloyu boşaltma ya da şema değiştirme yetkisi yok.
Şema değişiklikleri bu kullanıcıyla değil, sürümlü migration dosyalarıyla ve ayrı bir yetkiyle yapılır. Claude migration dosyasını yazabilir; ama onu siz okursunuz ve onaylı bir süreç uygular.
Satır düzeyi güvenlik (RLS) ikinci kilittir. Uygulamanın kendi kuralı, örneğin “her temsilci sadece kendi ekibinin müşterilerini görür”, kodda unutulsa bile veritabanında garanti altına alınabilir:
ALTER TABLE crm.musteri ENABLE ROW LEVEL SECURITY;
CREATE POLICY ekip_musterileri ON crm.musteri
USING (ekip_id = current_setting('app.ekip_id', true)::int);
Uygulama her istekte app.ekip_id değerini oturumdaki kullanıcının ekibine göre ayarlar; yanlış yazılmış bir sorgu bile başka bir ekibin müşterisini göremez. Değer hiç ayarlanmamışsa koşul hiçbir satırla eşleşmez: Uygulama bir yerde ekibi ayarlamayı unutursa ekran boş gelir, başkasının verisi gelmez. Önemli bir ayrıntı: PostgreSQL’de süper kullanıcılar RLS’e takılmaz, tablonun sahibi de ayrıca zorlanmadıkça takılmaz. Yetkili kullanıcı vermemenin bir nedeni daha. SQL Server’da da aynı fikir bir koşul fonksiyonu ve bir güvenlik politikasıyla uygulanır.
Uydurma paket tuzağı. Yapay zeka bazen var olmayan ama kulağa gerçekçi gelen bir paket adı önerir. Kötü niyetli kişiler de tam bu uydurma adlarla zararlı paketler yayımlar. Claude bir paket eklemek istediğinde paketin gerçekten var olduğunu, kimin yayımladığını, ne kadar kullanıldığını ve kaynak kodunun nerede olduğunu kontrol edin. Bağımlılık dosyalarını sabitleyin ve düzenli olarak bir bağımlılık taraması çalıştırın; npm audit ve pip-audit bu iş için var. CLAUDE.md’deki “yeni paket eklemeden önce sor” kuralı bu yüzden orada.
8. KVKK ve şirket verisi: Asistana neyi asla vermezsiniz?
Bir önceki bölüm teknik çiti anlatıyordu. Bu bölüm davranışla ilgili: Claude Code’a ya da herhangi bir yapay zeka sohbetine neyi yapıştırdığınız.
Asla paylaşılmayacaklar: Müşteri ve çalışan bilgileri, sözleşmeler, finansal veriler, iç yazışmalar, başka sistemlerin şifreleri ve bağlantı bilgileri. Kişisel veriler KVKK kapsamındadır; bir yapay zeka hizmetine gönderilmeleri, şirketin bu işleme için bir dayanağı ve onayı olmadan yapılmamalıdır.
Gerçek veri yerine örnek veri. Geliştirme için gerçek müşteri listesine ihtiyacınız yok. Claude’dan gerçekçi ama uydurma bir örnek veri seti üretmesini isteyin: Türkçe isimler, geçerli biçimde telefonlar, kontrol hanesi tutan ama kimseye ait olmayan vergi numaraları. Bir hatanın kaynağını bulmak için gerçek bir kayda bakmanız gerekiyorsa, onu önce anonimleştirin. Aynı dikkat log dosyaları ve ekran görüntüleri için de geçerli; ikisi de çoğu zaman kişisel veri içerir.
Hesabınızın veri ayarını bilin. Anthropic’in bireysel planlarında (Free, Pro, Max), Claude Code oturumları dahil, verilerinizin model eğitiminde kullanılıp kullanılmayacağı sizin seçtiğiniz bir ayardır ve gizlilik ayarlarından değiştirilebilir. Kurumsal planlar ve API gibi ticari koşullardaki hizmetler bu kapsamda değildir. Şirket işi için hangi hesapla çalıştığınızı ve şirketinizin yapay zeka politikasını bilin.
Pratik bir test: Bir şeyi sohbete yapıştırmadan önce kendinize sorun: “Bunu şirket dışından birine e-postayla gönderir miydim?” Cevap hayırsa, yapıştırmayın.
9. Promptu dışarıda olgunlaştırın, Claude Code’a temiz verin
Claude Code’a yarım bir fikirle başlamak cazip gelir: Bir şey istersiniz, sonuca bakarsınız, düzeltirsiniz, tekrar istersiniz. Her tur hem zaman hem kullanım harcar; oturum da yarım kalmış denemelerle dolar ve Claude’un neyin geçerli olduğunu ayırt etmesi zorlaşır.
Daha iyi bir yol: Fikri önce bir sohbet arayüzünde, örneğin claude.ai’da, olgunlaştırın. Belirsiz noktaları sordurun, alternatifleri konuşun, eksikleri tamamlayın. En sonda dört parçalı temiz bir görev tanımı çıkarın ve Claude Code’a sadece bu son hali verin:
- Bağlam: Ne üzerinde çalışılıyor, ilgili dosyalar hangileri?
- Hedef: Ne yapılacak?
- Kısıt: Neye dokunulmayacak, hangi kurallara uyulacak?
- Kabul kriteri: İş ne zaman bitmiş sayılacak?
Fark, aynı isteğin iki halinde açıkça görülür. Önce yarım fikir:
müşteri listesine arama ekle
Sonra olgunlaşmış hali:
Bağlam: musteriler/ altındaki liste ekranı ve GET /musteriler uç noktası.
Hedef: Listeye, unvan ya da vergi numarasıyla arama yapan bir arama kutusu ekle.
Kısıt:
- Arama sunucu tarafında yapılsın; bütün listeyi tarayıcıya çekme.
- Türkçe karakterler doğru eşleşsin: "Sukru" araması "Şükrü"yü bulsun.
- Yeni paket ekleme. Mevcut tablo bileşenini kullan.
Kabul kriteri:
- Unvanın bir kısmıyla ya da vergi numarasının tamamıyla arama çalışıyor.
- Boş arama bütün listeyi gösteriyor.
- Yeni davranış için sunucu tarafında test var ve bütün testler geçiyor.
İkinci prompt’u yazmak birkaç dakika sürer; ama ilk denemede doğru işe başlatır. Türkçe karakter kısıtının neden önemli olduğunu tekilleştirme yazısındaki Türkçe karakter tuzağı ayrıntılı anlatıyor. Bir uyarı: Bir önceki bölümdeki kural bu dış sohbetler için de geçerli. Fikri olgunlaştırırken de şirket verisi paylaşmayın.
10. Gücü nerede harcamalı? Effort, model ve alt ajanlar
Claude Code’da iki ayarla ne kadar “güç” harcadığınızı belirlersiniz: hangi modelin çalıştığı ve modelin ne kadar düşüneceği. Model /model komutuyla, düşünme düzeyi (effort) /effort komutuyla değişir; effort low, medium, high, xhigh ve max düzeylerinden birine ayarlanır.
Her işi en pahalı modele yaptırmayın. En güçlü model ve en yüksek effort, gerçekten düşünmeyi gerektiren işler içindir: mimari kararlar, planlama, inatçı bir hatanın kaynağını bulmak. Bir planın maddelerini tek tek uygulamak, test yazmak, küçük düzeltmeler ise daha hızlı bir modelin ve daha düşük bir effort düzeyinin işidir. Yüksek ayar bu işlerde daha iyi sonuç vermez; sadece daha yavaş çalışır ve daha fazla kullanım tüketir. Varsayılanı en yüksekte bırakmayın; gerektiğinde yükseltin. Claude Code’un bunun için hazır bir model ayarı da var: opusplan plan modunda en güçlü modeli, uygulamada daha hızlı olanı kullanır. Bu iş bölümünü ikinci bölümde bir plan dosyası üzerinden ayrıntılı anlatacağım. Ne kadar kullanım harcadığınızı /usage komutuyla görebilirsiniz.
Alt ajanları gereğinden fazla kullanmayın. Alt ajanlar kendi bağlamlarında, ana konuşmadan bağımsız çalışır ve aynı anda birkaç iş yürütebilir. Cazip görünürler; ama her yeni ajan yönetilmesi gereken bir iş daha demektir:
- Çakışma. Aynı dosyalara dokunan iki ajan birbirinin değişikliğini ezer.
- İnceleme yükü. On ajanın yaptığını gözden geçirmek, işi kendinizin yapmasından uzun sürebilir.
- Maliyet. Her ajan ayrı bir bağlam açar ve ana konuşmayla aynı kullanım limitinden harcar.
Alt ajanları birbirinden bağımsız ve çoğunlukla okuma ağırlıklı işlere verin: kod tabanında arama, araştırma, inceleme. Aynı dosyalara yazan paralel işler çıkarmayın; paralel değişiklik gerçekten gerekiyorsa her ajan ayrı bir çalışma kopyasında (worktree) çalışsın. Sonuçları birleştiren hep tek bir yer olsun: ana oturum ve siz.
Bu bölüm, skill’ler bölümündeki uyarının bir tekrarı aslında: Daha fazla araç daha iyi sonuç demek değildir. Yönetemediğiniz her parça bir risktir.
Hazırlık kontrol listesi
- Ürün tanımı bir sayfada yazılı; “şimdilik yapmayacaklarımız” listesi var.
- Proje Git’te; her anlamlı adım bir commit.
- Teknoloji, şirketin mevcut ortamına ve standardına uygun.
- CLAUDE.md 200 satırın altında; teknoloji kararları, komutlar, kurallar ve yasaklar yazılı.
- Kurulu skill’ler az, okunmuş ve güvenilir kaynaktan.
- Biçimlendirme ve tehlikeli komut engeli hook olarak tanımlı.
- İzin kuralları yazılı;
.envve şifre dosyaları okunamıyor. - Geliştirme veritabanı kullanıcısı en az yetkili; canlıya erişimi yok; RLS açık.
- Gerçek müşteri verisi yok; örnek veri üretildi.
- Görevler bağlam, hedef, kısıt ve kabul kriteriyle yazılıyor.
- Varsayılan model ve effort ayarı her iş için en yüksekte değil.
Bonus: Projeyi başlatan ilk prompt
Hazırlık bittiğinde Claude Code’a vereceğiniz ilk görev, yazılmış kuralları anlayıp bir plan çıkarmaktır; kod yazmak değil. Aşağıdaki prompt’u plan modunda verin. Köşeli parantezli yerleri kendi projenize göre doldurun:
Yeni bir projeye başlıyoruz. Önce @docs/urun.md dosyasındaki ürün tanımını
ve CLAUDE.md'deki kuralları oku. Henüz kod yazma.
Senden istediğim:
1. Ürün tanımını kendi cümlelerinle beş maddede özetle. Belirsiz ya da
çelişkili bulduğun yerleri soru olarak listele.
2. CLAUDE.md'deki teknoloji kararlarına uyan bir klasör yapısı öner.
[Angular, FastAPI, PostgreSQL] dışında bir teknoloji önermen gerekirse
önce gerekçesini yaz ve onayımı bekle.
3. Kurulması gereken paketleri listele; her biri için ne işe yaradığını
ve neden gerektiğini yaz. Hiçbirini kurma.
4. İlk dikey dilim olarak "müşteri ekle ve listele" işini uçtan uca
(veritabanı tablosu, migration, API uç noktası, arayüz ekranı, testler)
küçük adımlara böl. Her adımın "bitti" tanımını yaz.
Bu planı docs/plan.md dosyasına yazmayı öner; ben onaylamadan hiçbir
dosya oluşturma.
Bu prompt’un sonunda elinizde bir kod değil, bir plan olur. Planın nasıl okunacağını, düzeltileceğini ve uygulatılacağını, ekranı kodlamadan önce tasarımın nasıl seçileceğini ve uygulamanın güvenli bir şekilde nasıl yayına alınacağını serinin ikinci bölümünde anlatacağım.
Özet
- Kodu siz anlamıyorsanız, o kod sizin değildir. Claude Code yazar; sorumluluk sizde kalır.
- Önce bir sayfa: Kim kullanacak, hangi üç işi yapacak, “bitti” ne demek ve şimdilik neyi yapmayacaksınız.
- Ortama uygun teknoloji: Kodu yazan değil, işleten belirler. Yapay zekanın en iyi çalıştığı yapı, insanın da en kolay bakım yaptığı yapıdır: tipli diller, küçük dosyalar, tutarlı bir düzen. Proje değil portföy düşünün.
- CLAUDE.md kısa ve güncel olmalı; skill’ler az ve güvenilir; kurallar hook’larla garanti altında.
- Önce çit, sonra bahçe: İzinler, en az yetkili veritabanı kullanıcısı, RLS ve paket kontrolü.
- Şirket verisi asistana gitmez; örnek veriyi asistan üretir.
- Prompt dışarıda olgunlaşır, içeride temiz verilir. Güç, gerektiği yerde harcanır.
Claude Code’a ne kadar iyi bir çerçeve verirseniz, o kadar az kod yazmanız ve o kadar çok karar vermeniz gerekir. İyi bir çerçevede kod yazmak, işin en kolay kısmıdır.