Agent skill, MCP server ve rules dosyası farkları
Coding agent'a bağlam vermenin üç yolunu karşılaştırın. Skill, MCP server ve rules dosyasının token maliyetini ve bakım yükünü inceleyip doğru seçimi yapın.
Agent skill'leri, MCP server'ları ve rules dosyaları: kısa yanıt
Agent skill'leri, MCP server'ları ve rules dosyaları, bilgiyi coding agent'ın önüne getirir. Seçim, bilginin ne işe yaradığına göre yapılmalıdır. MCP (model context protocol), bir sonraki sorguda farklı olabilecek veriler içindir. Skill, bugün yazılı hale getirilebilecek ve 6 hafta sonra da geçerliliğini koruyacak prosedürler içindir. Rules dosyası ise her oturumda geçerli olması gereken az sayıdaki bilgi içindir.
Bu seçimin bir maliyeti vardır ve bu maliyet context'tir. Agent'ın ihtiyaç duymadığı bir talimat için harcanan her token, okuduğu kod için kullanılamayan bir token'dır. Ayrıca her istekte tüm context window yeniden gönderildiği için bu token'ın maliyeti her turda tekrar ödenir. Bu nedenle doğru soru, hangi mekanizmanın işi yapabildiği değildir. Çoğu gün üçünün de yapabildiği işler vardır. Sorulması gereken, kullanılmadan beklerken en az maliyete neden olan mekanizmanın hangisi olduğudur.
Kullanım öncesi maliyet analizi
Üç yöntem farklı zamanlarda yüklenir ve aralarındaki temel fark bu zamanlamadan kaynaklanır.
Koşulsuz bir kurallar dosyası, hariç tutulmadığı sürece her oturumun başlangıcında, ilgili olsun veya olmasın yüklenir. Claude Code, her konuşmanın başında CLAUDE.md dosyalarını okur, kod blokları dışındaki blok düzeyindeki HTML yorumlarını içerik enjeksiyonundan önce temizler ve 4 MiB üzerindeki dosyaları atlar; claudeMdExcludes ile yönetilen politika dosyası haricindeki dosyalar da hariç tutulabilir. Belgelenen hedef, dosya başına 200 satırın altıdır; çünkü daha uzun bir dosya hem daha fazla bağlam maliyeti yaratır hem de daha az güvenilir şekilde takip edilir. Bu iki etki aynı yönde işlediği için 900 satırlık bir kurallar dosyası işlevsiz olmaktan daha kötüdür.
Bir yetenek (skill) iki aşamada yüklenir. Başlangıçta, her SKILL.md ön bilgisinden (frontmatter) yalnızca description satırı bağlama girer; böylece model yeteneğin varlığından ve kabaca ne zaman uygulanacağından haberdar olur. Gövde kısmı ise yetenek çağrıldığında yüklenir. Bu nedenle 400 satırlık bir referans belgesi, ihtiyaç duyulana kadar size neredeyse hiçbir maliyet getirmez.
MCP sunucusu eskiden maliyetli olan taraftı; okuyacağınız çoğu karşılaştırmanın güncelliğini yitirdiği nokta burasıdır. Mevcut Claude Code sürümünde araç arama (tool search) varsayılan olarak açıktır. Oturum başlangıcında yalnızca araç isimleri ve sunucunun talimatlar alanı yüklenir; tam JSON (JavaScript object notation) şemaları ise Claude bunları arayana kadar ertelenir. Bir sunucu eklemek artık başlangıçta binlerce token maliyeti getirmez. Yine de bir maliyeti vardır ve araç aramanın kapalı olduğu yapılandırmalarda başlangıçta tüm yükü getirir.
Bu grafiğin arkasındaki veriler
[
{
"label": "Rules file, 200 lines",
"at_startup": "2,500",
"after_use": "2,500"
},
{
"label": "Skill, 12 KB body",
"at_startup": 40,
"after_use": "3,000"
},
{
"label": "MCP server, tool search on",
"at_startup": 500,
"after_use": "3,200"
},
{
"label": "MCP server, tool search off",
"at_startup": "4,500",
"after_use": "4,500"
}
]Bunlar makinenizden alınan ölçümler değil, tahminlerdir. Her mekanizmanın yüklediği metin boyutundan, token başına yaklaşık dört karakter hesabı yapılarak elde edilmiştir: 200 satırlık bir kurallar dosyası yaklaşık 10 KB markdown, bir yetenek açıklaması yaklaşık 160 karakter ve on iki araç sunan bir sunucu yaklaşık 18 KB şema ile 2 KB talimat bloğu taşır. Claude Code, sunucu talimatları alanını ve başlangıçta yüklenen her aracın açıklamasını varsayılan olarak 4.096 karakterde, araç arama yoluyla yüklenen araç açıklamasını ise 16.384 karakterde keser. v2.1.296 sürümünden önce kısa sınır 2.048 karakterdi ve CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH ayarlandığında her iki sınırı da değiştirir. Anthropic tarafından barındırılan bazı MCP sunucularından gelen talimatlar ve açıklamalar, bu değişken ayarlanmış olsa bile Claude'a tam olarak ulaşır; dolayısıyla bu sınırlar evrensel bir tavan değildir. Bir sonraki bölüm, kendi gerçek sayılarınızı nasıl okuyacağınızı gösterir.
İlk iki satırı birlikte okuyun. Kurallar dosyası, kimsenin ihtiyaç duymadığı bir oturumda 2,500 token maliyeti getirir. Yetenek, aynı oturumda 40 token, çalıştığı her on oturumdan birinde ise 3,000 token maliyetine sahiptir. Son iki satır, araç aramanın açık ve kapalı olduğu aynı sunucuyu gösterir: 500 token karşısında 4,500. MCP bağlam şişmesi hakkındaki eski tavsiyelerin hala dolaşmasının nedeni bu farktır.
Ekim 2026 itibarıyla Claude Code; Claude Opus 4, Sonnet 4, Haiku 4.5 ve sonraki modellerde, ayrıca Google Cloud Agent Platform üzerindeki Opus 4.5, Sonnet 4.5, Haiku 4.5 ve sonraki modellerde araç arama özelliğini kullanır. Daha eski modellerde ve Azure üzerinde barındırılan Microsoft Foundry dağıtımlarında, ayarlarınız ne olursa olsun her MCP aracı başlangıçta yüklenir. Bir LLM ağ geçidine yönlendirilen ANTHROPIC_BASE_URL ile araç arama, v2.1.304 sürümünden beri varsayılan olarak açıktır; daha eski sürümlerde siz özellikle seçmediğiniz sürece bu özellik kapalıydı. v2.1.305 sürümünden beri Claude Code, bir 400 veya 422 hatasından sonra araç arama olmadan ağ geçidi isteğini yeniden deneyebilir ve bu yeniden deneme başarılı olduğunda araçları başlangıçta yükler. Kontrol etmek için ENABLE_TOOL_SEARCH ayarını kullanın: false tüm şemaları başlangıçta yükler, true ayarlanmamış gibi aynı model ve dağıtım yedeklemeleriyle bunları erteler, auto ise tanımlamaların toplamı bağlam penceresinin %10'unun altında kaldığı sürece şemaları başlangıçta yükler ve toplam bu eşiğin altına düşse bile araç aramayı açık tutar. "alwaysLoad": true ile yapılandırılmış bir sunucu, ENABLE_TOOL_SEARCH ayarından bağımsız olarak araçlarını başlangıçta yükler.
# Load schemas up front only if they fit in 5% of the window
ENABLE_TOOL_SEARCH=auto:5 claudeKarar verdirici soru: Veri, çağrılar arasında değişiyor mu?
Bu soruyu ilk olarak sorun, çünkü bir seçeneği doğrudan eler. Eğer aracı (agent), bir sonraki bakışında farklı olabilecek bir veriyi okumak veya yazmak zorundaysa, bir sunucuya ihtiyacınız var demektir. Bir hata takip sistemi, veritabanı, izleme paneli veya kendi dahili API'niz (uygulama programlama arayüzü). Veriyi bir yere yazmak çözüm sağlamaz, çünkü başkası kaydı düzenlediği anda yazdığınız bilgi güncelliğini yitirir. Kendi kod tabanınız da bu listeye dahildir; çünkü yapısı her commit ile değişir. Araca, depo haritasının MCP üzerinden ayrıştırılmış halini sunmanın nedeni budur; yapıyı zamanla eskimiş bir dosyada tarif etmek yerine bu yöntem tercih edilir.
Eğer yanıt, altı hafta boyunca kimse bakım yapmasa bile doğru kalmaya devam edecekse, bir yeteneğe (skill) ihtiyacınız var demektir. Bir sürüm kontrol listesi. Bir taşıma prosedürü. Hata yanıtlarınızın biçimi. Bu deponun testlerin nasıl yazılmasını istediği gibi. Yetenek, git içindeki bir dosyadır. Bir portu, süreci ve yanlış olmanın dışında bir hata modu yoktur; yanlışlık ise bir kod incelemesi ile yakalanabilir.
Eğer henüz düşünmediğiniz işler için de geçerli olması gereken tek bir gerçeklik söz konusuysa, bunu kurallar dosyasına ekleyin. Run make lint before committing. Never push to main. Handlers live in src/api/handlers/. Her biri için tek satır. Bir girdi adımlardan oluşan bir sürece dönüştüğü an, artık bir gerçeklik olmaktan çıkıp bir prosedür haline gelmiş demektir ve bir yeteneğe taşınmalıdır.
Kurallar dosyası ne zaman yeterlidir
Kurallar dosyaları, en genelden en özele doğru çeşitli konumlardan yüklenir: yönetilen bir politika dosyası, kişisel ~/.claude/CLAUDE.md dosyanız, projenin ./CLAUDE.md veya ./.claude/CLAUDE.md dosyası ve git tarafından yoksayılan bir ./CLAUDE.local.md dosyası. Keşfedilen tüm dosyalar birbirinin üzerine yazılmak yerine birleştirilir ve çalışma dizininize daha yakın olan dosyalar en son okunur.
v2.1.277 sürümünden itibaren Claude Code, AGENTS.md dosyasını da okur; ancak bu işlem varsayılan olarak yalnızca çalışma dizininizde veya üst dizinlerinde CLAUDE.md, .claude/CLAUDE.md veya CLAUDE.local.md bulunmadığında gerçekleşir. Deponuzda her ikisi de mevcutsa, Claude yalnızca CLAUDE.md dosyalarını okur; bu nedenle zamanla birbirinden farklılaşacak iki kopya tutmayın.
ln -s AGENTS.md CLAUDE.mdSembolik bağ (symlink) başarılı olduğunda herhangi bir çıktı üretmez. Bir oturum başlatın, /context all komutunu çalıştırın ve CLAUDE.md öğesinin Memory files altında göründüğünü doğrulayın. Eğer orada listelenmiyorsa, ajan dosyayı hiç görmemiştir ve yeniden ifade etmek bir işe yaramayacaktır. Claude'a özel satırlar da eklemek istediğinizde, import formunu kullanın ve bu satırları import ifadesinin altına yerleştirin.
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.Burada bir tuzak bulunmaktadır. @path import işlemleri bağlam (context) kaydetmez. İçe aktarılan dosya genişletilir ve başlatma sırasında, ona referans veren dosya ile birlikte dört seviye derinliğe kadar yüklenir. 600 satırlık bir kurallar dosyasını altı import dosyasına bölmek, dosyayı insanlar için düzenli hale getirir ancak token maliyetini kesinlikle değiştirmez. Bir düzen üzerinde karar kılmadan önce AGENTS.md ve insan odaklı ikizi arkasındaki kurallar kısmını okumaya değerdir.
Maliyeti düşüren şey, paths alanına sahip .claude/rules/ kullanımıdır. paths ön bilgisine (frontmatter) sahip bir kural dosyası, yalnızca ajan bu desenlerden biriyle eşleşen bir dosyaya dokunduğunda yüklenir.
---
paths:
- "src/api/**/*.ts"
---
# API rules
- Every endpoint validates its input.
- Use the standard error response shape.paths alanı olmayan bir kural, başlatma sırasında .claude/CLAUDE.md ile aynı öncelikle yüklenir. Bu nedenle çalışma düzeni; kısa ve koşulsuz kurallar ile yalnızca tek bir dizin içinde geçerli olan her şey için bir paths listesinden oluşmalıdır.
Bir skill gerektiğinde
Bir skill, içinde bir SKILL.md bulunan bir dizindir. Kişisel skill'ler ~/.claude/skills/<name>/SKILL.md konumunda bulunur ve makinenizdeki her projeye uygulanır. Proje skill'leri .claude/skills/<name>/SKILL.md konumunda bulunur, repository ile birlikte taşınır ve diğer dosyalar gibi pull request içinde incelenebilir.
mkdir -p ~/.claude/skills/summarize-changes---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
Run `git status` and `git diff` against the merge base.
Group the changes by intent, not by file.
Call out anything touching auth, migrations or deletions.description, skill çalıştırılmadan önce bu dosyanın context içinde bulunan tek bölümüdür; bu nedenle iki işlevi vardır. Skill'in ne yaptığını ve hangi durumda kullanılacağını belirtir. "Helps with deploys" açıklaması, modelin isteği bununla eşleştirmesine yardımcı olmaz. Bunun sonucunda skill sessizce çalışmaz ve skill'lerin çalışmadığı sonucuna varırsınız.
Dizin adı command haline gelir; dolayısıyla yukarıdaki örnek size /summarize-changes komutunu verir. Kişisel veya proje skill'inde, dizin adından farklı bir frontmatter name bulunması, başka bir command bu adı zaten kullanmıyorsa, / menüsünde gösterilen command'i belirler. Dizin adı ise skill'i çalıştırmaya devam eder.
Bir skill çağrıldığında, işlenmiş içeriği conversation'a tek bir message olarak eklenir ve session'ın geri kalanında orada kalır. Claude Code sonraki turn'lerde dosyayı yeniden okumaz. Tek seferlik adımlar yerine sürekli geçerli talimatlar yazın ve gövdeyi kısa tutun. Çünkü bu noktadan sonra her satır, her istekte tekrarlanan bir maliyet oluşturur. Otomatik compact işleminden sonra Claude Code, her skill'in en son çağrılmasını yeniden ekler. Her skill'in ilk 5,000 token'ı, toplam 25,000 token'lık birleşik bütçeye dahil edilir. Tek bir session içinde birden fazla büyük skill çağırırsanız en eskiler tamamen çıkarılır. Bu nedenle uzun bir conversation sonrasında bir skill artık etkili değilmiş gibi görünebilir. Skill'i yeniden çağırdığınızda geri gelir. Prosedür ağırlıklı bir skill bu dengeyi somutlaştırır: unlazy skill'i ve Depth Tree yöntemi, işi erken tamamlandı ilan etmeyen bir agent karşılığında gate'ler ve bir plan dosyası için gerçek context harcar. Aynı prosedür birden fazla codebase için geçerliyse dosyayı kopyalamak yerine bir skill'i birden fazla repository arasında paylaşın.
MCP sunucusuna ihtiyaç duyulduğunda
Bir sunucu eklemek tek bir komutla yapılır ve aktarım yöntemi sunucunun çalışma biçimini belirler.
# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Remote HTTP server behind a bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"
# Local stdio server: everything after -- is passed through untouched
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-server-- önemlidir. stdio sunucusunda bu seçenek, Claude Code seçeneklerini sunucunuzu başlatan komut satırından ayırır. Bu seçeneği atlarsanız sunucuya gönderilmesi amaçlanan bir --port 8080, claude mcp add için seçenek olarak ayrıştırılır ve claude mcp add bunu reddeder.
claude mcp list
claude mcp get notionclaude mcp add, Added ... satırıyla onay verir. Bu yalnızca yapılandırmanın diske yazıldığını gösterir. Gerçek durumu gösteren komut claude mcp list komutudur; bu komut her sunucunun yanında bir sağlık durumu yazdırır: ✔ Connected, ! Needs authentication veya ✘ Failed to connect. Failed durumu, Claude Code'un ilgili sunucuya ulaşamadığı anlamına gelir; list komutunun başarısız olduğu anlamına gelmez. Bir oturum içinde /mcp, her sunucu için aynı görünümü ve araç sayısını gösterir.
MCP sunucusuna yapılan her çağrı bağımsızdır ve ihtiyaç duyduğu her şeyi kendi içinde taşır. Bu nedenle bir MCP sunucusu önceki isteğinizi hatırlamaz. Bunun bir sonucu vardır: korunması gereken tüm durum sunucunun arkasında, bir veritabanında veya dosyada tutulmalıdır. Bu bileşen artık işletmeniz gereken bir parçadır.
MCP sunucusu çalıştırmanız gereken bir süreçtir
Satıcı karşılaştırmalarının göz ardı ettiği maliyet budur. Bir yetenek (skill) bir dosyadan ibarettir. Bir MCP sunucusu ise bir yerlerde çalışan bir yazılımdır ve bu "bir yer" sizin VPS (sanal özel sunucu) hizmetiniz olduğunda, çalışma süresinin (uptime) sorumluluğu size aittir.
Stdio sunucusu en düşük maliyetli durumdur. Claude Code, oturum başladığında onu bir alt süreç olarak başlatır ve oturum bittiğinde süreç sonlanır. İzlenmesi gereken bir durum veya kendi takvimine göre yamalanması gereken bir yapı yoktur. Uzak bir HTTP sunucusu ise uzun ömürlü bir servistir ve her uzun ömürlü servisin ihtiyaç duyduğu şeylere, öncelikle de kendine ait bir kullanıcıya ihtiyaç duyar. Aşağıdaki birimin altında çalışacağı mcp kullanıcısını oluşturun ve sunucunun dizinini bu kullanıcıya atayın:
sudo useradd --system --home-dir /srv/notes-mcp --shell /usr/sbin/nologin mcp
sudo chown -R mcp:mcp /srv/notes-mcp[Unit]
Description=Notes MCP server
After=network-online.target
Wants=network-online.target
[Service]
User=mcp
WorkingDirectory=/srv/notes-mcp
ExecStart=/usr/bin/node /srv/notes-mcp/dist/server.js
Environment=PORT=8931
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true
[Install]
WantedBy=multi-user.targetsudo systemctl daemon-reload
sudo systemctl enable --now notes-mcp
systemctl is-active notes-mcp
journalctl -u notes-mcp -n 50 --no-pagersystemctl is-active komutu active çıktısını vermelidir. Eğer failed çıktısını veriyorsa, günlük kayıtlarında (journal) nedeni mevcuttur; ilk çalıştırmada bu genellikle eksik bir ortam değişkeni veya başka bir süreç tarafından halihazırda kullanılan bir porttur. Restart=on-failure burada isteğe bağlı değildir, çünkü çöken bir MCP sunucusu kendi durumunu bildirmez. Durumu ancak yapay zeka ajanı size sorun takip sisteminizi okuyamadığını söylediğinde fark edersiniz.
Süreci 127.0.0.1 adresine bağlayın ve önüne TLS (taşıma katmanı güvenliği) kullanan bir reverse proxy yerleştirin. Veritabanınıza erişen ve kimlik doğrulaması olmaksızın herkese açık bir port üzerinden yanıt veren bir MCP sunucusu, veritabanınızı dış dünyaya açmak anlamına gelir. Bir VPS üzerinde MCP sunucusu çalıştırma rehberi, proxy, sertifika ve güvenlik duvarı tarafını doğru şekilde ele almaktadır.
Ardından, tekrarlayan iş yükünü dürüstçe hesaplayın. Servis, onunla iletişim kuran ajandan bağımsız olarak kendi takvimine göre güvenlik güncellemeleri alır. OAuth belirtecinin süresi dolar ve claude mcp list, en uygunsuz anda ! Needs authentication çıktısını vermeye başlar. Kimlik bilgileri bir yapılandırma dosyasında veya bir Authorization başlığında tutulur; bu nedenle diğer tüm gizli verilerle aynı özeni gerektirirler ki bu başlı başına bir konudur: gizli verileri bir yapay zeka ajanının erişiminden uzak tutmak. Bir yetenek (skill) için bu iş yüklerinin hiçbiri mevcut değildir.
İnşa etmeden önce alternatifleriyle kıyaslayın. Eğer önerilen sunucunun arkasındaki veriler yaklaşık üç ayda bir değişiyorsa, ajana nereye bakacağını ve alanların ne anlama geldiğini söyleyen bir yetenek, ayakta tutmanız gereken bir servisten daha düşük maliyetlidir.
Bağlam maliyetinizi nasıl ölçersiniz
Tahmin yürütmeyi bırakın ve bir oturum içerisinde /context all komutunu çalıştırın. Bu komut; sistem istemi, bellek dosyaları, araçlar ve MCP sunucularının her birinin token ağırlığını içeren güncel dökümü yazdırır.
İki noktayı kontrol edin. Memory files başlığı altında, beklediğiniz tüm kural dosyalarının listelendiğini doğrulayın. Eksik bir dosya, ajan tarafından görülmez; bu nedenle talimatlar göz ardı edildiğinde elenmesi gereken ilk husus budur. Dosya listede olduğu halde kural hala atlanıyorsa, sorun tamamen başka bir yerdedir ve bir ajanın görebildiği bir talimatı neden uygulamadığına dair nedenler, satırı yeniden yazmadan önce incelenmeye değerdir. Ardından sunucularınızın maliyetine bakın. Ayda iki kez kullandığınız bir sunucu listedeki en büyük kalemlerden biriyse, /mcp üzerinden onu devre dışı bırakın ve ihtiyaç duyduğunuz oturumlarda tekrar açın. Yapılandırma her iki durumda da korunur.
Hesabınız için keşif önbelleği (discovery cache) açıksa, daha önce kullandığınız uzak bir sunucu cached 2h ago · connects on first use · 5 tools gibi bir durum gösterebilir. Bu, Claude Code'un başlangıçta bağlanmak yerine araç listesini önceki bir oturumdan okuduğu anlamına gelir; araç ilk kez çağrıldığında bağlantı kurulacaktır. Araçlar ilk mesajınızdan itibaren kullanılabilir durumdadır, bu yüzden düzeltilmesi gereken bir şey yoktur. Kademeli bir dağıtım sizin için etkinleştirmediği sürece önbellek varsayılan olarak kapalıdır: her sunucunun başlangıçta bağlanmasını sağlamak için MCP_DISCOVERY_CACHE=0 ayarını yapın veya önbelleği açmak için 1 komutunu kullanın. Daha geniş bir perspektif için, Claude Code bağlam penceresini yönetme konusu sıkıştırma işleminden nelerin sağ çıktığını ele alır ve bu tokenların size gerçek maliyeti bölümü sayıları para birimine dönüştürür.
Becerim neden hiç tetiklenmiyor?
Bunun yaygın nedeni description olur. Beceri çalıştırılmadan önce bağlamda bulunan tek metin budur. Bu nedenle durum belirtilmiyorsa hiçbir eşleşme gerçekleşmez. Tetikleyiciyi cümlenin içine yazın: "Kullanıcı neyin değiştiğini sorarsa, commit mesajı isterse veya diff dosyasını incelemenizi isterse kullanın." Belirsiz açıklamalar sessizce başarısız olur. Bu da sorunun fark edilmesini zorlaştırır.
İkinci neden frontmatter içindeki yazım hatasıdır. Claude Code'da bu hata da sessizce oluşur. Alan adı, tireler dahil olmak üzere tam olarak eşleşmelidir. Claude Code tanımadığı bir alanı hata bildirmeden yok sayar. Sesli hata yalnızca beceriyi paketlediğinizde veya claude.ai ya da Skills API'ye yüklediğinizde görülür. Bu sistemler daha az alan kabul eder ve diğer alanları doğrudan reddeder:
Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, nameÜçüncü neden konumdur. Proje becerileri, çalışma dizininizdeki ve repository root konumuna kadar tüm üst dizinlerdeki .claude/skills/ içinden yüklenir. Başladığınız konumun altındaki iç içe dizinlerde bulunan beceriler başlangıçta yüklenmez. Agent o alt dizindeki bir dosyayı ilk kez okuduğunda veya düzenlediğinde görünür hale gelir. Bu zamana kadar otomatik tamamlamada görünmez ve adlarıyla çağrılamaz.
MCP tarafındaki sessiz hata eşdeğeri, url içeren ancak type içermeyen bir .mcp.json girdisidir. Claude Code, type içermeyen her girdiyi stdio server olarak okur. Bu nedenle girdiyi atlar ve şu çıktıyı bildirir:
MCP server "notes" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entryÜçünün birlikte kullanılması
Bu mekanizmalar aynı alan için birbiriyle rekabet etmez. İşe yarayan bir kurulumda her biri, maliyetinin düşük olduğu yerde kullanılır. Rules dosyasında her yerde geçerli olan birkaç satır bulunur. Skills, prosedürleri içerir ve yalnızca gerektiğinde yüklenir. Bir MCP server, bazen de iki MCP server, içeriğini önceden tahmin edemeyeceğiniz sistemlere bağlanır. İlkinin çalışma modelini hâlâ oluşturuyorsanız bir agent skill'in gerçekte ne olduğu, biçimi ayrıntılı olarak açıklar.
Bir içeriğin nereye ait olduğu konusundaki tartışmaların çoğunu tek bir test sonuçlandırır. İçeriği silin, yeni bir session başlatın ve agent'a görevi verin. Agent yalnızca daha yavaş çalışıyorsa içerik bir skill'e ait olmalıdır. Agent kendinden emin biçimde yanlış yanıt veriyorsa içerik rules dosyasına ait olmalıdır. Agent bilgiyi hiç alamıyorsa server gereklidir; bu durumda server'ın çalışmaya devam etmesini sağlayacak bir plan da gerekir.
FAQ
Bir yetenek (skill) mi yazmalıyım yoksa bir MCP sunucusu mu kurmalıyım?
Kararınızı, bilginin bir çağrıdan diğerine değişip değişmediğine göre verin. Eğer ajan, bir sorun takip sistemi, veritabanı veya gösterge paneli gibi başkaları tarafından düzenlenebilen canlı bir durumu okumak zorundaysa, bir MCP sunucusuna ihtiyacınız vardır; çünkü yazdığınız her şey kayıt değiştiği anda güncelliğini yitirir. Eğer cevabı bir kez yazıp altı hafta sonra hala doğru kalacağını biliyorsanız, bir yetenek yazın. Yetenek, git içinde yer alan, çalıştırılacak bir süreci, açılacak bir portu veya yama takvimi olmayan bir dosyadır; bu nedenle mümkün olan her durumda daha düşük maliyetli seçenektir.
MCP sunucuları hala bağlam penceremi (context window) dolduruyor mu?
Eskisine göre çok daha az. Mevcut Claude Code sürümünde araç arama varsayılan olarak etkindir, bu nedenle oturum başlangıcında yalnızca araç isimleri ve sunucunun talimat alanı yüklenir; tam şemalar ise Claude onları aradığında getirilir. Bu durum, v2.1.304 sürümünden itibaren ANTHROPIC_BASE_URL üzerinden ayarlanan bir LLM ağ geçidinin arkasındaki oturumları da kapsar. Ön yükleme (upfront loading) işlemi; ENABLE_TOOL_SEARCH=false ile, "alwaysLoad": true olarak ayarlanmış bir sunucuda, Claude Opus 4 ve Sonnet 4'ten daha eski bir modelde (Google Cloud Agent Platform üzerindeki 4.5 neslinden daha eski) ve Azure üzerinde barındırılan Microsoft Foundry dağıtımlarında hala gerçekleşir. Hangi durumda olduğunuzu görmek için /context all komutunu çalıştırın, çünkü eski karşılaştırma yazılarındaki sayılar ön yükleme yapıldığı varsayımına dayanmaktadır.
Claude Code AGENTS.md dosyasını okuyor mu?
Evet, v2.1.277 sürümünden beri okuyor; ancak varsayılan olarak yalnızca çalışma dizininizde veya üst dizinlerinizde CLAUDE.md, .claude/CLAUDE.md veya CLAUDE.local.md bulunmadığında bunu yapar. Eğer deponuzda her ikisi de varsa, Claude yalnızca CLAUDE.md dosyalarını okur; bu yüzden iki kopya tutmak yerine birini diğerine yönlendirin. Basit bir sembolik bağlantı (symlink) için ln -s AGENTS.md CLAUDE.md komutunu çalıştırın veya bir CLAUDE.md dosyasının ilk satırına @AGENTS.md ekleyip altına Claude'a özel talimatlarınızı yazın. Ardından bir oturum başlatın ve CLAUDE.md öğesinin Bellek dosyaları (Memory files) altında göründüğünü doğrulamak için /context all komutunu çalıştırın.
Yeteneğim neden bir oturumun ortasında etkisini yitirdi?
Bunun yaygın nedeni otomatik sıkıştırmadır (auto-compaction). Konuşma özetlendiğinde, Claude Code her yeteneğin en son çağrısını, her biri için ilk 5.000 token'ı koruyacak şekilde ve toplamda 25.000 token'lık bir bütçe dahilinde yeniden ekler. Bu bütçe, en son çağrılan yetenekten başlayarak doldurulur; bu nedenle birden fazla büyük yetenek çağırdıysanız, daha eski olanlar tamamen çıkarılır. İçeriğinin tamamını geri yüklemek için yeteneği tekrar çağırın.
Uzun bir kurallar dosyasının her oturumda yüklenmesini nasıl durdurabilirim?
Yalnızca bazen önemli olan kısımları, ön bilgilerinde (frontmatter) paths alanı bulunan .claude/rules/ dosyalarına taşıyın; böylece her biri yalnızca ajan eşleşen bir dosyaya dokunduğunda yüklenir. Dosyayı @path içe aktarmalarıyla bölmek işe yaramaz, çünkü içe aktarılan dosyalar açılışta, onlara referans veren dosya ile birlikte genişletilir ve yüklenir. Kalıcı bir gerçeklikten ziyade çok adımlı bir prosedür olan her şey bir yeteneğe dönüştürülmelidir, çünkü bir yetenek gövdesi çağrılana kadar hiçbir maliyet oluşturmaz.