Claude Code ile AI Ajan Sistemi Nasıl Kurulur? Adım Adım Rehber

Bir AI ajan sistemi kurmak istiyorsun ama nereden başlayacağını bilmiyorsun. Ya da "ajan sistemi" kavramını duydun, ama pratik uygulama konusunda kafan karışık. Ben 8 aydır Claude Code üzerinde çalışan, 72'den fazla uzman ajan, 25+ MCP entegrasyonu ve kapsamlı bir hafıza sistemi barındıran bir yapı kurdum — ve bu yazıda tüm sistemi adım adım anlatacağım. Teori yok, soyut kavramlar yok — gerçek dosya yapıları, gerçek kod örnekleri, gerçek sonuçlar.

Neden Claude Code? Neden Başka Bir Araç Değil?

Piyasada çoklu ajan çatıları var — LangChain, CrewAI, AutoGen gibi. Bunları denedim. Ama Claude Code'un bir farkı var: kendi dosya sisteminizde yaşıyor. Sunucuya deploy etmenize, Docker container'lar kurmanıza gerek yok. Projenizin kök dizininde bir CLAUDE.md dosyası oluşturuyorsunuz ve Claude Code onu okuduğu anda tüm sistem ayağa kalkıyor.

Bu yaklaşımın avantajları net: sıfır altyapı maliyeti, sıfır devops bilgisi gereksinimi, ve en önemlisi — dosya tabanlı bir sistem olduğu için versiyonlanabilir, paylaşılabilir ve anlaşılabilir. Git ile versiyon kontrolü yapabilirsiniz. Bir başkasına tüm sisteminizi CLAUDE.md dosyası göndererek aktarabilirsiniz.

Mimari: Orkestratör + Uzman Ajanlar

Sistemimin mimarisi basit ama güçlü: bir orkestratör ajan ve altında uzman ajanlar. Orkestratör (ana CLAUDE.md) gelen her mesajı analiz eder, konuya göre ilgili ajana yönlendirir. Her ajan kendi alanında derinleşmiş, kendi hafıza dosyaları ve araç setleri olan bir uzmandır.

Benim sistemimde 9 departman var: Müzik, Yaratıcı, Pazarlama, Sosyal Medya, Görsel, Teknoloji, İstihbarat, Destek ve Spor. Her departmanın altında 3-12 uzman ajan bulunuyor. Toplam 72'den fazla ajan. Ama korkmayın — bu sistemi bir günde kurmadım. İlk gün 3 ajanla başladım, ihtiyaç oldukça büyüttüm.

Adım 1: Ana CLAUDE.md Dosyasını Oluştur

Her şey buradan başlıyor. Projenizin kök dizininde bir CLAUDE.md dosyası oluşturun. Bu dosya Claude Code'un her oturum başında okuduğu konfigürasyon dosyasıdır. İçinde şunlar olmalı:

• Kimlik tanımı: "Sen kimsin?" sorusunun cevabı. Claude'a rolünü, amacını ve sınırlarını söyleyin. Örnek: "Sen Kamer'in kişisel AI sistemisin. Gelen mesajları analiz et ve ilgili ajana yönlendir."
• Kullanıcı bilgisi: "Kamer kimdir?" — mesleği, tercihleri, hedefleri. Claude bu bilgiyi tüm önerilerinde kullanır
• Yönlendirme tablosu: Hangi anahtar kelime hangi ajana gider? Tablo formatında yazın. Örnek: "müzik, şarkı, melodi → Müzik Ajanı"
• İletişim kuralları: Dil, ton, format tercihleri. "Türkçe konuş, sycophancy yapma, belirsizliği söyle" gibi
• Dosya konumları: Ajan tanımları, araçlar, bilgi tabanı, çıktılar nerede? Claude'un dosya sisteminde yolunu bulması için bu bilgi şart
• Sistem sınırları: Claude'un ne yapmaması gerektiğini açıkça belirtin. "Profesyonel tıbbi tavsiye verme, ilaç dozu önerme" gibi

Bu CLAUDE.md dosyası 100 satır da olabilir, 500 satır da. Önemli olan net ve tutarlı olması. Claude her karakter'i okuyor ve ona göre davranıyor.

Adım 2: Ajan Tanım Dosyaları — AGENT.md

Her uzman ajan bir AGENT.md dosyasıyla tanımlanır. Dosya yapısı şöyle: agentlar/{departman}/{ajan-adi}/AGENT.md. Örneğin müzik prodüktör ajanı: agentlar/muzik/kamer-agent/AGENT.md

Bir AGENT.md dosyasında şunlar bulunur:

• Rol tanımı: "Sen bir müzik prodüksiyon uzmanısın. Görevin: BPM/ton/makam analizi, mix önerileri, metadata yönetimi"
• Uzmanlık alanları: Ajanın ne bildiği ve ne bilmediği. Sınırları net koyun
• Kullanabileceği araçlar: BPM analiz scripti, ses dönüştürücü, Spotify API gibi araçların listesi ve kullanım talimatları
• Hafıza dosyaları: Ajanın okuması gereken bilgi dosyaları. Örneğin müzik ajanı: BRAND.md (sanatçı kimliği), DISCOGRAPHY.md (diskografi), PREFERENCES.md (müzikal tercihler)
• Çıktı formatı: Ajanın cevaplarını nasıl formatlaması gerektiği. Başlık, maddeler, kod blokları, tablo kullanımı gibi
• Tetikleyiciler: Bu ajanı aktive eden anahtar kelimeler listesi

Her ajan kendi AGENT.md dosyasıyla birlikte bir MEMORY/ klasörüne sahip olabilir. Bu klasörde ajanın öğrendiği bilgiler, geçmiş kararlar ve referanslar tutulur. Claude oturumlar arası bu bilgileri okuyarak "hafızasını" korur.

Adım 3: Hafıza Sistemi — Claude'un Beyni

Claude Code'un doğal hafızası yok — her oturum sıfırdan başlar. Ama dosya sistemi üzerinden kalıcı hafıza kurabilirsiniz. Benim sistemimde 3 katmanlı bir hafıza yapısı var:

• Global hafıza (MEMORY.md): ~/.claude/projects/{proje}/memory/MEMORY.md — Claude Code'un otomatik okuduğu, tüm oturumlar arası kalıcı hafıza. Kullanıcı tercihleri, öğrenilen feedback'ler, proje durumları burada
• Bilgi tabanı (bilgi/): Konu bazlı bilgi dosyaları — marka kimliği, müzik tercihleri, piyasa verileri, rakip analizleri. Claude ilgili konuya göre bu dosyaları okur
• Ajan hafızası (MEMORY/): Her ajanın kendi klasöründeki öğrenilmiş bilgiler. Müzik ajanı şarkı tercihlerini, finans ajanı bütçe bilgilerini kendi hafızasında tutar

Hafıza güncelleme protokolüm şu: yeni bilgi öğrenildiğinde ilgili dosyaya yazılır, kullanıcı tercihi keşfedildiğinde MEMORY.md'ye eklenir, haftalık review yapılır. Bu sayede Claude her oturumda "taze" başlasa bile, önceki oturumların bilgisini taşır.

Adım 4: MCP Entegrasyonları — Claude'un Kolları

MCP (Model Context Protocol), Claude Code'un dış dünyayla bağlantı kurmasını sağlayan standart protokol. Bir MCP server'ı, Claude'a yeni yetenekler kazandırır — Gmail okuma, takvim yönetimi, tasarım oluşturma gibi.

Benim sistemimde aktif olan MCP entegrasyonları:

• Gmail MCP: E-posta okuma, taslak yazma, yanıt oluşturma. Müşteri iletişimini otomatikleştiriyor
• Google Calendar MCP: Takvim yönetimi, toplantı planlama, hatırlatıcılar
• Canva MCP: Görsel tasarım üretimi — sosyal medya postları, thumbnail'ler, sunumlar
• YouTube Transcript MCP: Video transkript çekme — araştırma ve içerik analizi için
• Context7 MCP: Güncel kütüphane ve framework dokümantasyonu — kodlama sırasında doğru bilgiye erişim
• PubMed MCP: Akademik makale araştırma — sağlık ve bilim konularında güvenilir kaynak

MCP kurulumu basit: ~/.claude/settings.json dosyasında MCP server tanımlarını ekliyorsunuz. Her MCP server'ı bir npx veya Docker komutuyla çalışır. Claude Code başlatıldığında otomatik bağlanır ve araçlar kullanılabilir hale gelir.

Adım 5: Araçlar — Özel Python Script'leri

MCP'lerin yanı sıra, kendi araçlarınızı da yazabilirsiniz. Ben araclar/ klasöründe 15+ Python script'i tutuyorum — Claude bunları doğrudan çalıştırıyor:

• transcribe.py: Ses dosyasından transkript çıkarma (Whisper tabanlı)
• bpm_analiz.py: Ses dosyasının BPM, ton ve enerji analizi
• tweet_isle.py: X/Twitter linkinden tweet metni, video ve transkript çıkarma
• session_save.py / session_resume.py: Oturum kaydetme ve devam etme — uzun çalışmalarda context kaybını önlüyor
• hooks/pre_compact.sh: Context sıkıştırmadan önce otomatik çalışan hook — önemli bilgileri kaydediyor

Araçlar dosya tabanlı olduğu için versiyon kontrolü altında. Yeni bir araç eklemek, bir Python dosyası yazmak ve CLAUDE.md'de referans vermek kadar basit. Claude araçları doğrudan çağırabilir: python3 araclar/bpm_analiz.py dosya.wav

Adım 6: Hook Sistemi — Otomatik Lifecycle Yönetimi

Claude Code'un hook sistemi, belirli olaylarda otomatik script'ler çalıştırmanızı sağlar. Bu, ajan sisteminin "reflekslerini" oluşturur:

• SessionStart hook: Her oturum başında çalışır — güncel tarihi yazar, bekleyen görevleri kontrol eder, son değişiklikleri özetler
• PreCompact hook: Context sıkıştırma başlamadan önce çalışır — önemli bilgileri hafıza dosyalarına yazar, kaybolmasını önler
• Stop hook: Her cevap sonrası asenkron çalışır — log tutar, metrik toplar

Hook konfigürasyonu ~/.claude/settings.json dosyasında yapılır. Her hook bir shell komutu çalıştırır. Matcher ile hangi projelerde aktif olacağını belirleyebilirsiniz. Hook'lar sistemin "otonom" hissettiren kısmıdır — siz söylemeden Claude kendi bakımını yapar.

Adım 7: Yönlendirme Kuralları — Akıllı Routing

72 ajan varsa, gelen mesajın doğru ajana gitmesi kritik. Benim yönlendirme sistemim anahtar kelime tabanlı:

CLAUDE.md'de bir yönlendirme tablosu var. "Logic Pro, şarkı, melodi" gibi kelimeler Müzik Ajanı'na; "echo bazaar, youtube, thumbnail" gibi kelimeler Echo Bazaar Ajanı'na; "stres, motivasyon, kaygı" gibi kelimeler Psikiyatr Ajanı'na gidiyor. Belirsiz veya çoklu konu varsa, orkestratör kendisi cevaplıyor ve ilgili ajanları referans gösteriyor.

Bu yaklaşım basit ama etkili. Daha gelişmiş bir routing için semantic matching veya intent classification kullanılabilir — ama anahtar kelime tabanlı sistem %90+ doğruluk oranıyla çalışıyor ve sıfır ek maliyet gerektiriyor.

Adım 8: Model Seçimi — Doğru İş İçin Doğru Model

Her görev aynı model gücünü gerektirmez. Benim sistemimde 3 katmanlı model stratejisi var:

• Opus (en güçlü): Strateji kararları, hukuk analizi, karmaşık planlama. HIT or LIT yarışma stratejisi gibi kritik konular
• Sonnet (varsayılan): Kod yazma, araştırma, içerik üretimi, ajan görevleri. Günlük işlerin %80'i burada dönüyor
• Haiku (hızlı ve ucuz): Basit sorular, format dönüştürme, dosya taşıma. Token tasarrufu

Sub-agent başlatırken modeli belirtiyorum: claude --model claude-sonnet-4-6 -p "Görevi yap". Bu sayede basit bir BPM hesaplama için Opus token'ı harcamıyorum. Aylık API maliyetim bu stratejiyle %40 düştü.

Adım 9: Bilgi Tabanı — 25 İçerik Üreticisi Referansı

Sistemimin benzersiz özelliklerinden biri: 25 YouTube içerik üreticisinin bilgi birikimini taşıyan referans kaynakları. Her içerik üreticisi için bir INDEX.md ve data/ klasörü var. "X'e sor" dediğimde Claude ilgili kaynağın bilgi tabanını okuyor ve o kişinin perspektifinden cevap veriyor.

Bu yaklaşım başka alanlara da uygulanabilir: rakip analizi için rakip şirketlerin bilgi tabanları, müşteri segmentasyonu için persona dosyaları, eğitim içeriği için uzman profilleri. Dosya tabanlı bilgi tabanı, Claude'un RAG (Retrieval Augmented Generation) yapmasını sağlar — dış bir veritabanı veya vector store'a gerek kalmadan.

Gerçek Dünya Sonuçları: 8 Aylık Deneyim

Bu sistemi 8 aydır günlük aktif kullanıyorum. Sonuçlar:

• Günde 4-6 saat tasarruf: E-posta, takvim, içerik üretimi, araştırma gibi işler büyük ölçüde otomatik
• 72+ ajan: Müzikten finansa, sosyal medyadan hukuka kadar her alan kapsanıyor
• 25+ MCP entegrasyonu: Gmail, Calendar, Canva, YouTube, PubMed ve daha fazlası
• Sıfır altyapı maliyeti: Tüm sistem dosya tabanlı, sunucu yok, veritabanı yok
• Echo Bazaar 15M+ dinlenme: İçerik pipeline'ı bu sistemle yönetiliyor
• 5 aktif yazılım projesi: 4 ajanlı dev ekibiyle paralel proje geliştirme
• Telegram entegrasyonu: 7/24 erişilebilir always-on bot — dışarıdan ses kaydı gönderiyorum, sistem işliyor

Yaygın Hatalar ve Nasıl Kaçınılır

• CLAUDE.md'yi çok uzun yazmak: 5000+ satırlık bir CLAUDE.md, Claude'un context window'unu doldurur ve performansı düşürür. Öz ve net tutun, detayları alt dosyalara yönlendirin
• Tüm ajanları aynı anda kurmaya çalışmak: 3 ajanla başlayın. İhtiyaç oldukça büyütün. İlk gün 72 ajan kurmak gereksiz ve karmaşıklaştırıcı
• Hafıza sistemini ihmal etmek: Hafıza dosyaları olmadan Claude her oturumda sıfırdan başlar. İlk günden MEMORY.md yapısını kurun
• Hook'ları atlamak: Hook'lar olmadan sistem "reaktif" kalır. Hook'larla sistem "proaktif" olur — kendi bakımını yapar, bilgi kaybını önler
• Model seçimini optimize etmemek: Her görev için Opus kullanmak gereksiz maliyet. Model stratejisi belirleyin

Hızlı Başlangıç: 30 Dakikada İlk Ajan Sisteminiz

Hemen başlamak istiyorsanız, minimum viable ajan sistemi şu 4 adımla kurulur:

• 1. Claude Code'u kurun: npm install -g @anthropic-ai/claude-code — Pro veya Max plan ile
• 2. Proje dizini oluşturun: mkdir ai-sistem && cd ai-sistem — ve bir CLAUDE.md dosyası yazın. İçine kimlik tanımı, kullanıcı bilgisi ve 2-3 yönlendirme kuralı koyun
• 3. İlk ajanı tanımlayın: mkdir -p agentlar/genel/asistan — ve içine AGENT.md yazın. Basit bir görev tanımı ve birkaç tetikleyici yeterli
• 4. Hafıza başlatın: Bir MEMORY.md oluşturun ve Claude'a "bu bilgiyi hafızana yaz" demeye başlayın. Sistem kendi kendini büyütecek

30 dakikada çalışan bir sisteminiz olacak. Sonra ihtiyaç oldukça yeni ajanlar, MCP entegrasyonları ve araçlar eklersiniz. Bu sistem organik büyür — ve en güçlü yanı da bu.

Sıkça Sorulan Sorular

Sonuç: Sistem Kurmak, Araç Kullanmaktan Büyük

ChatGPT'ye soru sormak, bir AI aracı kullanmaktır. Claude Code ile ajan sistemi kurmak, bir AI ekibi oluşturmaktır. Aradaki fark devasa. Araç kullanıcısı olarak saatte birkaç dakika kazanırsınız. Sistem kurucusu olarak günde saatler kazanırsınız — ve sistem siz yokken bile çalışır.

Ben 72 ajanlı, 25 MCP entegrasyonlu, kapsamlı hafıza sistemli bir yapı kurdum — ama sizin 72 ajana ihtiyacınız yok. 3 ajanla başlayın. İlk CLAUDE.md dosyanızı yazın. İlk ajanınızı tanımlayın. İlk MCP'yi entegre edin. Ve sistemin organik büyümesini izleyin. 30 dakikada başlarsınız, 30 gün sonra "bu olmadan nasıl çalışıyordum" dersiniz.