.claude/ klasör yapısının analizi

• .claude/ klasörü, Claude Code'un çekirdek kontrol dizini olarak proje bazlı kuralları, komutları, izinleri ve bellek durumunu yönetir
• CLAUDE.md, Claude'un davranış ilkelerini ve proje kurallarını tanımlayan merkezi dosyadır; birden çok katmandaki yapılandırmayı birleştirerek uygular
• commands/, skills/, agents/ klasörleri sırasıyla kullanıcı tanımlı komutlar, otomatik iş akışları ve uzman alt ajanları yapılandırarak iş birliği verimliliğini artırır
• settings.json, komut çalıştırma izinlerini ve dosya erişim kapsamını kontrol eder; settings.local.json ile kişisel override yapılabilir
• Genel yapı, Claude'a projenin kimliğini ve kurallarını ileten bir protokol olarak çalışır; açık yapılandırmalar üretkenliği ve iş birliği verimliliğini en üst düzeye çıkarır

---

.claude/ klasör yapısı ve bileşenleri

• .claude/ klasörü, Claude Code'un davranışını kontrol eden çekirdek dizindir ve proje bazlı kuralları, komutları, izinleri ve bellek durumunu yönetir
• Proje kökündeki klasör, ekip düzeyindeki yapılandırmaları içerir ve Git'e commit edilir
• Ana dizindeki (~/.claude/) klasör, kişisel ayarları ve oturum kayıtlarını saklar; otomatik bellek ve kişisel komutları içerir

• CLAUDE.md — Claude'un kılavuzu

  • Claude Code oturumu başlarken ilk okunan dosyadır ve Claude'un davranış ilkelerini ve proje kurallarını tanımlar
  • Proje kökündeki CLAUDE.md ekip ortak kurallarını, ~/.claude/CLAUDE.md genel kişisel kuralları, alt klasörlerdeki CLAUDE.md ise klasöre özel kuralları üstlenir
  • Claude, birden çok CLAUDE.md dosyasını birleştirerek uygular
  • Önerilen içerikler arasında build·test komutları, önemli mimari kararlar, sezgisel olmayan kısıtlar, adlandırma ve hata işleme kuralları yer alır
  • 200 satırın altında tutulması önerilir; aşırı uzunluk, Claude'un yönergelere uyma oranını düşürür

• CLAUDE.local.md — kişisel override

  • Ekip ortak kurallarından ayrı olarak kişisel tercihleri yansıtabilen bir dosyadır
  • Proje kökünde CLAUDE.local.md oluşturulursa Claude bunu da birlikte okur
  • .gitignore içine otomatik olarak eklenir ve depoya commit edilmez

• rules/ klasörü — modüler kural yönetimi

  • CLAUDE.md büyüdüğünde .claude/rules/ klasörüne bölünerek yönetilebilir
  • Her kural dosyası konuya göre ayrılır, bu da bakımı kolaylaştırır
    • Örnek: code-style.md, testing.md, api-conventions.md, security.md
  • YAML frontmatter içindeki paths alanı kullanılarak yalnızca belirli yollara uygulanan kurallar tanımlanabilir
    • Örnek: API kurallarını yalnızca src/api/**/*.ts yoluna uygulamak
  • Yol belirtilmeyen kurallar, tüm oturumlarda her zaman yüklenir

• commands/ klasörü — kullanıcı tanımlı slash komutları

  • .claude/commands/ klasöründeki her Markdown dosyası bir slash komutu (/) olarak kaydedilir
    • Örnek: review.md → /project:review, fix-issue.md → /project:fix-issue
  • ! backtick sözdizimi ile shell komutu çalıştırma sonucunu Claude prompt'una eklemek mümkündür
    • Örnek: !git diff main...HEAD
  • $ARGUMENTS değişkeni ile komut çalışırken argüman iletmek mümkündür
    • Örnek: /project:fix-issue 234 → GitHub issue 234 içeriği otomatik yüklenir
  • Proje komutları ekiple paylaşılır; kişisel komutlar ~/.claude/commands/ içinde saklanır ve tüm projelerde kullanılabilir

• skills/ klasörü — otomatik çalışan iş akışları

  • Komutlara benzer ama otomatik tetiklenen iş akışları olarak çalışır
  • Claude, konuşma içeriğini analiz ederek uygun durumlarda otomatik çalıştırır
  • Her skill, alt klasördeki SKILL.md dosyasıyla tanımlanır; YAML frontmatter ile tetikleme koşulları ve izin verilen araçlar belirtilir
    • Örnek: security-review skill'i güvenlikle ilgili konuşmalarda otomatik çalışır
  • Skill klasöründe DETAILED_GUIDE.md gibi yardımcı belgeler veya şablon dosyaları bulunabilir
  • Kişisel skill'ler ~/.claude/skills/ içinde saklanır ve genel olarak kullanılabilir

• agents/ klasörü — uzman alt ajanlar

  • .claude/agents/ klasöründe belirli rolleri üstlenen alt ajanlar (persona) tanımlanır
  • Her ajan bağımsız bir sistem prompt'una, modele ve araç erişim iznine sahiptir
    • Örnek: code-reviewer.md, security-auditor.md
  • tools alanı ile erişilebilen araçlar sınırlandırılarak güvenlik ve rol ayrımı sağlanır
  • model alanı ile işe uygun Claude modeli (ör. Haiku, Sonnet, Opus) seçilebilir
  • Claude, gerektiğinde ilgili ajanı ayrı bir bağlamda çalıştırır ve yalnızca sonucu özetleyerek raporlar

• settings.json — izinler ve proje ayarları

  • .claude/settings.json, Claude'un komut çalıştırma izinlerini ve dosya erişim kapsamını tanımlar
  • $schema alanı, VS Code gibi ortamlarda otomatik tamamlama ve doğrulama desteği sağlar
  • allow listesi otomatik onaylanan komutları, deny listesi ise tamamen engellenen komutları belirtir
    • Örnek: izin verilenler — Bash(npm run *), Read, Write, Edit
    • engellenenler — Bash(rm -rf *), Bash(curl *), .env dosyasını okuma
  • Listelerde olmayan komutlar için çalıştırmadan önce kullanıcı onayı istenir
  • Kişiye özel izin değişiklikleri .claude/settings.local.json içinde saklanır ve Git'e dahil edilmez

• ~/.claude/ klasörü — genel ayarlar ve bellek

  • ~/.claude/CLAUDE.md, tüm projelere ortak uygulanan kişisel yönergeleri içerir
  • ~/.claude/projects/, proje bazlı oturum kayıtlarını ve otomatik belleği saklar
    • Claude'un öğrendiği komutlar, kalıplar ve yapısal içgörüler korunur
    • /memory komutuyla görüntülenip düzenlenebilir
  • ~/.claude/commands/, ~/.claude/skills/, ~/.claude/agents/ dizinleri genel kişisel komutlar·skill'ler·ajanlar için depodur

• Genel yapı örneği

  your-project/  
  ├── CLAUDE.md  
  ├── CLAUDE.local.md  
  └── .claude/  
      ├── settings.json  
      ├── settings.local.json  
      ├── commands/  
      ├── rules/  
      ├── skills/  
      └── agents/  
  ~/.claude/  
  ├── CLAUDE.md  
  ├── settings.json  
  ├── commands/  
  ├── skills/  
  ├── agents/  
  └── projects/  
  

• İlk kurulum adımları

  • 1. adım: /init komutuyla temel CLAUDE.md oluşturup yalnızca çekirdek içeriği bırakın
  • 2. adım: .claude/settings.json yazın, çalıştırmaya izin verme·engelleme kurallarını tanımlayın

  • 3. adım:Sık kullanılan iş akışlarına (ör. kod inceleme, issue düzeltme) uygun komutlar ekleyin

    • 4. adım: CLAUDE.md büyürse .claude/rules/ içine ayırın
    • 5. adım: ~/.claude/CLAUDE.md içine kişisel tercih kuralları ekleyin

Temel içgörüler

• .claude/ klasörü, Claude'a projenin kimliğini ve kurallarını ileten bir protokoldür
• CLAUDE.md en önemli dosyadır; bu dosya ne kadar net tanımlanırsa Claude'un üretkenliği o kadar artar
• Diğer bileşenler bunu tamamlayan optimizasyon katmanlarıdır ve kademeli olarak genişletilebilir
• Açık yapılandırmalar, Claude'dan gelen düzeltme taleplerinin azalmasına ve verimli iş birliğine yol açar

Ek tartışmalar

• settings.json içindeki deny listesi insan kullanımı için güvenli olsa da, ajan modunda Bash erişimi nedeniyle ek koruma gerekebilir
• OneCLI, ağ düzeyinde kimlik bilgisi token'larını ikame eden bir proxy katmanı sağlayarak gizli bilgilerin açığa çıkmasını önler
• Gelecekte yalnızca ajan moduna özel .claude yapılandırmalarına (kurallar·izinler·skill'lerin ayrılması) ihtiyaç duyulabileceği belirtiliyor
• Güncel belgelere göre komutlar (commands) ile skill'ler (skills) birleştirildi; .claude/commands/deploy.md ile .claude/skills/deploy/SKILL.md aynı şekilde /deploy komutunu üretir, ancak skill'ler ek özellikleri (yardımcı dosyalar, otomatik tetikleme vb.) destekler

[GN⁺]

Hacker News yorumları

• Yapay zeka ajanları için toolkit kurmak, sanki kusursuz üretkenlik kurulumunu aramak gibi hissettiriyor
  İnsan blog yazıları ve YouTube videoları izleyip rutin kuruyor ama sonunda basit bir yapılacaklar listesi ile istikrarlı çalışan kişi daha ileri gidiyor
  Benim deneyimimde, Plain Claude'a plan yaptırıp gözden geçirdikten sonra uygulatmak hâlâ en iyi çalışan basit yöntem

  • Büyük ölçekli kod tabanlarında veya dağıtık sistemlerde durum farklı
    Ajanın veri pipe etmesi, istek oluşturması, sistemi takip etmesi ve kodu güncellemesi gibi teknik beceriler, geliştirme verimliliğini sıçratıyor
    10 milyon satırlık kodda üretkenlik ciddi biçimde arttı ve bunun içinde gerçek kod üretiminin payı %5 bile değil
    Esas neden, test ve doğrulama için toolchain'leri hızlıca kurabilme yeteneği
  • Birçok insan bu tuzağa düşüp para harcıyor
    Aslında kişi ne istediğini net biçimde bilip bunu iyi aktarabiliyorsa, yapay zekayla da oldukça çok iş yapılabiliyor
    Çoğu kişi bunu bilmiyor. Bu yüzden plan çıkarttırma süreci, anlayış kazanmak için bir kısayol oluyor
  • Bir PM olarak ajanların zaman kazandırmasını ve çıktıda bileşik etki (compounding) yaratmasını istiyorum
    Ama her oturumda bağlamı tekrar etmek ve .md dosyaları kopyalamak gibi verimsizlikler var
    Şu anki hedefim bu tekrarı ortadan kaldırmak.
    Biriken bağlamı tutan bir “context bank”i nasıl yönettiğinizi merak ediyorum — örneğin “rolüm, sorumlu olduğum ürün, güncel dokümanlar” gibi temel bilgiler
    Dokümanlarda tekrar ve güncelliğini yitirmiş çok içerik var, bu yüzden tüm Drive'ı bağlamak da mümkün değil
    Tekrarlanan bağlam iki kereden fazla ortaya çıkarsa bir Skill dosyası mı oluşturulmalı, yoksa dokümanları toplayıp tek bir klasörde mi yönetmeli, bunu düşünüyorum
  • Ben de benzer bir deneyim yaşadım. Çalışma sırasında üretilen çıktıların çoğu çöpe gidiyor
    Aşırı yapılandırma (over-configuration) kalite düşüşüne ve döngü sorunlarına yol açıyor
    Modeller giderek iyileştiği için, eskiden gerekli olan talimatlar artık performansı engelleyebiliyor
    Hatta Anthropic ekibinin her 30 günde bir claude.md dosyasını sıfırladığını da duydum
  • Tersine, ben yerel bir muhasebe API'sini entegre etmem gereken bir proje üzerinde çalışıyorum ve bu tamamen özel bir API olduğu için LLM bunu bilmiyor
    Bu yüzden Claude'a bir MCP server yaptırdım ve artık muhasebe işlerini otomatik yürütüyor
    Ay sonu kapanışından sonra Claude'a ana işleri çıkarıp Skill hâline getirtince, sanki bir junior muhasebeci edinmişim gibi çalıştı
    Özel MCP ve Skill'lerin gerçekten çok faydalı olduğunu düşünüyorum

• Birçok kişide, agentic coding'e başlamadan önce devasa bir kurulum duvarı oluşturuluyormuş hissi var
  Ama başlangıçta boş bir .claude ve AGENTS.md ile başlayıp kullanım şeklini doğrudan öğrenmek doğru yaklaşım

  • Ben hatta yalnızca kendi yaptığım skill'lerin kullanılmasını savunuyorum
    Başkalarının yaptığı skill'leri rastgele kurarsanız nondeterminism artıyor ve context window da boşa harcanıyor
    İstisna olarak sadece playwright-cli gibi dış kurulumları önerebilirim
  • Büyük ekiplerde belirli guardrail'lere ihtiyaç var
    Örneğin şu kural gibi ön koşulları kontrol edecek şekilde ayarlarsanız daha güvenli oluyor
    Güvenlik ekiplerinin de bu yaklaşımı tercih edeceğini düşünüyorum
    Ben de kural tanımlarken Claude'un GPG imzası olmadan commit atmamasını sağladım
    Ama bu tür kurallar sabit olmamalı, sürekli evrilmeli
  • Bu yazı devasa bir yapılandırmayı dayatmıyor
    Aksine, tekrar tekrar küçük başlayın ve kısa tutun diye vurguluyor
    Yeni başlayan biri bile AGENTS.md içine birkaç satır eklerse yapay zeka kullanıcının niyetini daha iyi anlıyor
    Basit yapılandırmalar yapay zeka arızalarını büyük ölçüde azaltıyor
  • Kodu tek başına ele almakla ekip olarak paylaşılan bir projeyi yönetmek tamamen farklı şeyler
    Her geliştirici agentic araçlar kullandığında iş birliği biçimi de baştan değişiyor
  • Önce sadece plan modunu kullansanız bile işin %90'ı çözülüyor
    Bu kadar karmaşık yapılandırma tartışmalarının, modeller geliştikçe 1 yıl içinde büyük ölçüde ortadan kalkacağını düşünüyorum

• Asıl ilginç kısım ~/.claude/projects klasörü

• Gereksiz yapılandırma ne kadar azsa sonuçlar benim için o kadar iyi oldu
  İnsanlar dokümanları aşırı derecede kuralcı hâle getiriyor ama yapay zeka yetkin ama gergin bir yetişkin gibi
  Fazla talimat verince daha aptalca davranıyor

• Bu yazı gerçek deneyimden çok üretilmiş gibi duruyor
  Claude.md kısa tutulmalı, içine sadece birkaç bağlantı konmalı
  Bağlam biriktikçe performans düştüğü için planlama ile uygulamayı ayırmak ve her seferinde sıfırlamak gerekiyor

  • Giriş kısmı Claude'un üslubuna fazla benzediği için ben de doğrudan Claude'a sorsam olurmuş gibi hissettim
  • Skill ile komut arasındaki fark kafa karıştırıcı
    Skill'ler her zaman bağlamda mı duruyor ve komutlar sadece elle mi çağrılıyor, bu net değil

• Keşke tüm model sağlayıcıları ortak bir standart dosya seti paylaşsa
  O zaman Claude, Codex, Cursor ve Opencode arasında geçiş yapmak daha kolay olurdu

  • Ama model ile harness birleşimi sonuç üzerinde büyük etki yaratıyor
    Aynı prompt'a her model farklı tepki verdiği için prompt tuning de modele göre değişmeli
  • Tek bir agents.md oluşturup Claude.md'nin ona referans vermesini sağlayabilir, sonra klasörler arasında symlink (sync) ile bağlayabilirsiniz
    Kusursuz değil ama oldukça iyi çalışıyor
  • Şu an durum ilk tarayıcı çağı gibi. Standartlaşmamış olması sayesinde AJAX gibi yenilikler çıkmıştı
    Bu yüzden bugünkü çeşitliliği aslında olumlu buluyorum
  • Ben şimdilik bu sorunu çözmek için Sentry'nin dotagents aracını kullanıyorum
  • Model sağlayıcılarının geçişi kolaylaştırmak için özellikle bir nedenleri olduğunu sanmıyorum

• Claude Fast'in alternatif dokümanı çok faydalı
  .claude klasörü tanımından neden nefret edeyim, bilmiyorum
  Ana ajanı dosyaları doğrudan yazacak, bunları yinelemeli biçimde güncelleyecek ve kendini iyileştiren bir sistem kuracak şekilde yönlendirebilirsiniz
  Şu anda .claude kendi kendini çoğaltıyor, değerlendiriyor ve güncelliyor — ben kod yazmaktan çok .claude kodluyorum

  • Kısacası, CLAUDE.md basit bir belge değil, Claude'un işletim sistemi
    Davranışı tanımlıyor, bilgiyi skill'lere devrediyor ve zamanla kendini geliştiren bir sistem kuruyor

• İnsanların pek fark etmediği engel şu: Claude'a dosya düzenlettirseniz bile, yeniden okuyacağını açıkça belirtmezseniz değişiklikler yansımıyor
  Örneğin CLAUDE.md dosyasını yeni yazdıysanız, Claude'un bunu yeni talimat olarak algılaması için yeniden yüklemesi gerekiyor

• ~/.claude/plans klasöründe plan modu çalıştırıldığında oluşturulan plan dosyaları saklanıyor
  Ben bu dizini açıp yedek almak ya da referans olarak bakmak için sık kullanıyorum

• Ben kurulumu global MCP server'lar ve composite agent etrafında yapıyorum
  Her MCP server kendi araç setini tanımlıyor ve ajan bu çerçevede otonom biçimde çalışıyor
  .agent.md, yalnızca kullanılabilir araçları açıklayan bir doküman; karmaşık yapılandırmalara gerek yok
  Skill'lerin veya yeniden kullanılabilir prompt'ların değerinin düşük olduğunu düşünüyorum
  Modeller zaten yeterince akıllı; gereken şey yönlendirme (orientation)