Kodlama ajanları talimatları neden uygulamıyor?
Kodlama ajanlarının talimatları görmezden gelmesinin dört temel nedeni ve bunları düzeltmek için uygulayabileceğiniz teknik teşhis yöntemleri bu rehberde yer almaktadır.
Kodlama ajanları talimatlarınızı neden görmezden gelir
Kodlama ajanlarının talimatlarınızı görmezden gelmesinin dört nedeni vardır ve bunlardan hiçbiri çok nazik olmanız değildir. Kural hiçbir zaman bağlam penceresinde (context window) yer almamıştır. Kural, bir eylemi doğrulamak için fazla belirsizdir. Bağlamdaki başka bir şey, genellikle ajanın az önce okuduğu kod, bu kural ile çelişmektedir. Veya kural hala yüklüdür ancak mevcut işlem sırasının çok gerisinde kalmıştır ve ajan kendisine yakın olan verilerle çalışmaktadır.
Her nedenin kendine özgü bir çözümü vardır, bu yüzden ilk iş bunları birbirinden ayırmaktır. Büyük harfler ve IMPORTANT kelimesi bir teşhis yöntemi değildir. Aşağıdaki mekanizmalar, Ekim 2026 itibarıyla yükleme ve sıkıştırma davranışları detaylı olarak belgelendiği için örnek olarak Claude Code kullanmaktadır. Diğer araçlar detaylarda farklılık gösterse de genel hatlarıyla aynı şekilde çalışırlar.
Öncelikle iki terimi tanımlayalım. Bağlam penceresi (context window), modelin belirli bir işlem sırasında gördüğü metin bloğudur: sistem istemi, talimat dosyalarınız, konuşma geçmişi ve ajanın okuduğu her dosya. Harness, modelin etrafındaki programdır; diskten dosyaları okuyan ve bu bloğu bir araya getiren yapıdır. Bu yazıdaki neredeyse tüm şikayetler aslında modele değil, harness yapısına yöneliktir.
Talimat dosyanız bir ayar değil, bir mesajdır
Bir talimat dosyası yapılandırma değildir. Çalışma zamanında hiçbir süreç CLAUDE.md dosyasını okumaz ve uygulamaz. Harness, dosyayı diskten okur ve metni konuşma içerisine yapıştırır. Claude Code içerisinde bu içerik, sistem isteminden sonra yerleştirilen bir kullanıcı mesajı olarak iletilir; bu da modelin kurallarınızı yazdığınız diğer her şeyle aynı şekilde gördüğü anlamına gelir.
Bunun rahatsız edici bir sonucu vardır. Kurallarınız, penceredeki diğer tüm metinlerle eşit düzeyde rekabet eder. Bir kural bir iddiadır. Aracın az önce açtığı dosya ise bir kanıttır. İkisi çeliştiğinde genellikle kanıt kazanır ve hiçbir hata oluşmaz; çünkü modelin bakış açısından ters giden bir durum yoktur.
Resmi belgeler bunu açıkça belirtir: talimat dosyaları zorunlu yapılandırma olarak değil, bağlam olarak ele alınır. Modelin kararı ne olursa olsun bir eylemi engellemek için bir cümleye değil, bir kancaya (hook) ihtiyacınız vardır. Bu prensibi unutmayın. Bu yazının sonundaki düzeltmelerin çoğu, bu prensibin belirli bir duruma uygulanmış halidir.
Hangi talimat dosyaları ne zaman yüklenir
Claude Code, başlatıldığı dizinden başlayarak dizin ağacında yukarı doğru ilerler. Dosya sistemi kök dizininden çalışma dizininize kadar olan tüm CLAUDE.md ve CLAUDE.local.md dosyaları, başlatma sırasında tamamen yüklenir. Bu dosyalar belirtilen sırayla birleştirilir; dolayısıyla başlatma yaptığınız yere en yakın olan dosya en son okunur ve aynı dizin içindeki .local dosyası, ana dosyadan sonra eklenir.
Çalışma dizininizin altındaki alt dizinlerde bulunan dosyalar farklı davranır. Bu dosyalar başlatma sırasında yüklenmez. Yalnızca aracı (agent) o dizindeki bir dosyayı okuduğunda yüklenirler. Aynı durum, paths: ön bilgisi (frontmatter) içeren .claude/rules/ içindeki yol kapsamlı kurallar için de geçerlidir: bu kurallar her adımda değil, eşleşen bir dosya okunduğunda bağlama (context) dahil edilir. v2.1.309 sürümünden itibaren, bu şekilde yüklenen dosyaların dosya başına bir boyut sınırı vardır (200K bağlam penceresinde 40.000 karakter) ve aracı, uzun bir dosyanın yalnızca başlangıç kısmını alır; bu nedenle büyük ve iç içe geçmiş bir dosyanın sonuna yakın kurallar hiçbir zaman bağlama ulaşmayabilir.
Bu tek fark, bildirilen hataların büyük bir kısmını açıklar. packages/api/CLAUDE.md içine bir kural koyarsınız, API hakkında bir soru sorarsınız ve aracı, packages/api/ altındaki hiçbir dosyayı açmadan yanıt verir. Kural göz ardı edilmemiştir; kural hiçbir zaman mevcut olmamıştır. Eğer deponuzdaki rehberlik monorepo içindeki paket bazlı talimat dosyaları arasında bölünmüşse, her seferinde kontrol etmeniz gereken ilk yer burasıdır.
Bir diğer yükleme tuzağı, AGENTS.md standardını kullanan depoları etkiler. v2.1.277 sürümünden itibaren Claude Code, çalışma dizininizde veya üst dizinlerinizde CLAUDE.md, .claude/CLAUDE.md veya CLAUDE.local.md bulunmadığı sürece AGENTS.md dosyasını varsayılan proje talimatlarınız olarak okur (kişisel ~/.claude/CLAUDE.md dosyanız buna dahil değildir). Bunlardan herhangi birini, kişisel notlar için bir CLAUDE.local.md olsa bile eklerseniz, Claude Code bunun yerine CLAUDE.md dosyalarınızı okur ve AGENTS.md dosyasını tamamen devre dışı bırakır. Her ikisini de yüklemek için /config içindeki Project instructions ayarını claude-md-and-agents-md olarak yapılandırın. v2.1.277 öncesi sürümlerde veya bir CLAUDE.md dosyasını korumak istediğinizde, köprü görevi gören bir CLAUDE.md dosyası oluşturun; bu dosyanın ilk satırı @AGENTS.md olmalıdır. Bu satır, dosyayı başlatma sırasında içe aktarır ve altına Claude'a özel notlar eklenebilir. Ekleyecek başka bir şeyiniz olmadığında sembolik bağ (symlink) da işe yarar. Bu dosyada nelerin yer alması gerektiğine karar vermek ise aracı talimatlarını insan belgelerinden ayırma konusunda ele alınan ayrı bir konudur.
Dosyanın yeniden yazılmasından önce yüklendiğini doğrulayın
Ajanın dosyayı görebildiğine dair kanıtınız olmadan metin üzerinde değişiklik yapmayın. İki kontrol yöntemi mevcuttur ve maliyeti düşük olan ilk uygulanmalıdır.
Oturum içinde /context komutunu çalıştırın. Bu komut, mevcut pencereyi kategorilere ayırarak listeler ve Memory files listesi, başlatma sırasında yüklenen tüm yönerge dosyalarını isimlendirir. Bu listede yer almayan bir dosya başlatma sırasında yüklenmemiştir; dolayısıyla bir şey onu yükleyene kadar dosya içinde yapacağınız hiçbir değişiklik etkili olmayacaktır. Alt dizindeki iç içe geçmiş bir dosya burada asla görünmez çünkü talep üzerine yüklenir; yüklendiğinde ise terminalde yolu ile birlikte bir Loaded satırı belirir. /memory, henüz var olmayanlar da dahil olmak üzere dosya konumlarını listeler ve düzenleme için açar.
Daha kesin bir sonuç için yükleme işlemlerini günlüğe kaydedin. InstructionsLoaded kanca olayı, her CLAUDE.md veya kural dosyası bağlama girdiğinde tetiklenir ve eşleştiricisi yüklemenin neden gerçekleştiğini size bildirir: session_start, nested_traversal, path_glob_match, include veya compact. Bunu .claude/settings.json içine yerleştirin:
{
"hooks": {
"InstructionsLoaded": [
{
"matcher": "nested_traversal",
"hooks": [
{
"type": "command",
"command": "cat >> /tmp/instructions-loaded.log"
}
]
}
]
}
}Kanca, yükünü standart girdi üzerinden JSON formatında alır, bu nedenle cat tüm kaydı ekler. Çalışırken tail -f /tmp/instructions-loaded.log ile bunu izleyin. Bu olayın çıkış durumu göz ardı edilir, bu nedenle kanca yalnızca gözlem yapabilir, engelleme yapamaz. İç içe geçmiş dosyanız, beklediğiniz bir oturum sırasında bu günlükte hiç görünmüyorsa yeniden düzenleme yapmayı bırakın. Sorun yerleşimdedir. Bir istisna: Claude Code tarafından doğrudan okunan bir AGENTS.md bu olayı tetiklemez, bu nedenle yolunu /memory içinde arayın. Bir CLAUDE.md üzerinden içe aktarılan bir AGENTS.md ise her zamanki gibi tetiklenir.
Uzun bir oturumun kurallarınız üzerindeki etkisi
Burada iki ayrı etki söz konusudur ve bunlar farklı yaklaşımlar gerektirir.
Mesafe. Bir sıkıştırma (compaction) işlemi gerçekleşene kadar, 1. turda belirtilen bir kural 90. turda hala pencere içerisindedir; ancak artık o an yaptığınız işe daha güncel ve daha özel olan 90 turluk metinle rekabet halindedir. Sıkıştırma işlemi bir kez gerçekleştiğinde, sadece sohbet ekranına yazdığınız bir kural pencerede hiç bulunmayabilir: Claude Code'un kendi belgeleri, konuşmanın başındaki talimatların kaybolabileceği konusunda uyarır; bu da aşağıdaki ikinci etkidir. Mesafeyi yapılandırarak ortadan kaldıramazsınız ancak ölçebilirsiniz. Aynı görevi yeni bir oturumda çalıştırın. Kural orada geçerli oluyor ancak uzun bir oturumun derinliklerinde başarısız oluyorsa, cevap mesafe veya sıkıştırmadır.
Sıkıştırma. Pencere dolduğunda, sistem şimdiye kadarki konuşmayı özetler ve bu özet üzerinden devam eder. Hayatta kalan kısım, özetleyicinin önemli bulduğu kısımdır; bu da sizin önemli bulduğunuzla aynı olmayabilir. Claude Code, sonucu mekanizmaya göre belgeler ve aradaki farklar büyüktür. Proje kök dizinindeki CLAUDE.md ve kapsam dışı bırakılmış kurallar, sıkıştırma işleminden sonra diskten yeniden enjekte edilir. Otomatik bellek diskten yeniden enjekte edilir. paths: ön bilgisine (frontmatter) sahip kurallar, eşleşen bir dosya tekrar okunana kadar kaybolur. Alt dizinlerdeki iç içe geçmiş CLAUDE.md dosyaları, o alt dizindeki bir dosya tekrar okunana kadar kaybolur.
Talimatlarınızı bu tabloya göre sıraladığınızda kırılganlık sırası ortaya çıkar. Sadece sohbet ekranına yazdığınız bir kural, oturumdaki en kırılgan şeydir: yalnızca özetleyici onu tutmayı seçerse varlığını sürdürür. packages/api/CLAUDE.md içindeki bir kural bir sonraki sıradadır; çünkü bir kez yüklenmiş, özetlenerek kaldırılmış ve ancak o dizindeki bir sonraki okumada geri dönmüştür. Proje kök dosyasındaki bir kural ise en dayanıklı olanıdır; çünkü her seferinde diskten yeniden okunur.
Bu nedenle, bir talimatın tüm oturum boyunca geçerli olması gerekiyorsa, bu talimat paths: ön bilgisi içermeyen proje kök dosyasında yer almalıdır. Diğer her şey, bilinçli olarak yapmanız gereken bir tercihtir. Bağlam penceresinde nelerin kalacağını yönetme, odak argümanı ile /compact ve ilgisiz görevler arasındaki /clear konularını ele alır; her ikisi de özetleyicinin kurallarınızın ne olduğuna ne sıklıkla karar vereceğini değiştirir.
Çevreleyen kodun kuralı neden geçersiz kıldığı
Bu, insanların en sık tanımladığı ancak en az teşhis ettiği başarısızlık türüdür. Dosyanız veritabanı erişiminin repository katmanı üzerinden yapılması gerektiğini belirtir. Ajan ise ORM (object relational mapper) ile doğrudan iletişim kuran bir işleyici yazar. Stil gerekçeleriyle görmezden gelinmediniz. Kanıtlar karşısında çoğunluk oyuyla elendiniz.
Bir kural tercihi tanımlar. Kod ise bir tercihi sergiler. Ajan, düzenlemek üzere olduğu modüldeki üç dosyayı açtığında ve her üçü de ORM'i doğrudan çağırdığında; bağlam, bir tarafta soyut bir cümle, diğer tarafta ise üç somut, güncel ve görevle eşleşen örnek tutar. Yerel deseni kopyalamak genellikle doğru davranıştır. Burada yanlış olmasının tek sebebi, bağlamın bilmediği bir şeyi sizin biliyor olmanızdır: bu dosyalar eski (legacy) koddur.
O halde bunu kuralın içine yazın. Kendi karşıt kanıtlarını ismen belirten kurallar, gerçek bir repozitör ile karşılaştığında hayatta kalır. Sadece çıplak bir tercih belirten kurallar ise hayatta kalamaz.
Yeni veritabanı erişimiapp/repositories/üzerinden yapılmalıdır.app/legacy/altındaki dosyalar hala ORM'i doğrudan çağırmaktadır. Bu eski koddur, desen değildir. Bunu kopyalamayın.
İkinci cümle işi yapan kısımdır. Ajana ne bulacağını ve onu bulmadan önce nasıl okuması gerektiğini söyler. Aynı düzeltme, repozitörünüzün gözle görülür şekilde çeliştiği her kural için geçerlidir: geçmişinizin takip etmediği bir commit stili, test paketinizin yarısının görmezden geldiği bir test düzeni, sadece yeni kodda geçerli olan bir import geleneği. Kodun dosya ile çeliştiği her yerde, bu anlaşmazlığı dosyanın içinde belirtin.
Belirsiz bir kural denetlenemez, dolayısıyla uygulanamaz
"Temiz kod yazın." "Aşırı mühendislikten kaçının." "Basit tutun." "Taşımalarda dikkatli olun." Bunların hiçbiri, ne sizin ne de bir temsilcinin (agent) belirli bir eyleme karşı test edebileceği kurallar değildir. Kendi çıktısına karşı denetleyemeyeceği bir kural verilen temsilci tahmin yürütür; siz de bu tahmini hislerinize göre değerlendirirsiniz.
Dosyanızdaki her satıra uygulamanız gereken test şudur: Kural ihlal edildiğinde sıfır olmayan bir çıkış kodu döndürecek shell komutunu yazın. Eğer bu komutu yazamıyorsanız, kural denetlenebilir değildir. Şu çiftleri karşılaştırın:
- Denetlenemez: "Fonksiyonları küçük tutun." Denetlenebilir: "60 satırdan uzun bir fonksiyonun üzerinde, nedenini açıklayan bir yorum satırı bulunmalıdır."
- Denetlenemez: "Değişikliklerinizi test edin." Denetlenebilir: "
npm testkomutunu çalıştırın ve bir görevi tamamlanmış saymadan önce hata sayısını yapıştırın." - Denetlenemez: "Dosyaları düzenli tutun." Denetlenebilir: "HTTP işleyicileri
src/api/handlers/dizininde bulunur. Bu dizine başka hiçbir şey konulamaz." - Denetlenemez: "Kodu düzgün biçimlendirin." Denetlenebilir: "
.tsdosyalarında 2 boşluklu girintileme kullanın."
"Aşırı mühendislikten kaçının" kuralı, insanların ilk vazgeçtiği kuraldır; çünkü bunun çözümü daha kısa bir cümle değil, daha uzun bir cümledir: çalışan en küçük değişikliğin ne anlama geldiğini açıkça belirtmek, temsilciye kendi diff çıktısını karşılaştırabileceği kriterler sunar.
Boyut, aynı sorunun farklı bir biçimidir. Claude Code rehberliği, talimat dosyası başına 200 satırın altını hedefler ve daha uzun dosyaların uyumu azalttığını doğrudan belirtir. 700 satırlık bir dosya, daha sağlam bir talimat değildir. Bu, birbiriyle çelişme olasılığı daha yüksek olan 700 satırlık iddialar bütünüdür ve her adımda pencerenizden harcanır; bu da token kullanımınızda doğrudan görülür. Dosyayı, her kural bir okuyucunun tarayabileceği bir başlık altında olacak şekilde yapılandırmak, bir temsilcinin uygulayabileceği bir talimat dosyası yazma konusunda ele alınmıştır. Daha da iyisi, talimat vermek yerine tanımlama yapan kısımları kesin: işleyicilerin ve modellerin nerede olduğuna dair bir dizin turu, temsilcinin ayrıştırılmış bir depo haritası üzerinden ihtiyaç duyduğunda bakabileceği bir yapıdır; bunu her adımda pencerede taşımasına gerek yoktur.
On dakikada nasıl teşhis edilir
Bunları sırasıyla çalıştırın. Son adıma atlamak, insanların neden hala çalışmayan uzun bir kural listesiyle baş başa kaldıklarının sebebidir.
- Yüklendiğini doğrulayın.
/contextkomutunu çalıştırın ve Memory dosyaları listesini okuyun veya iç içe geçmiş bir dosya için terminaldeLoadedsatırını arayın. Dosya orada değilse konumu düzeltin ve durun. Bu listedeki diğer hiçbir madde henüz geçerli değildir. - Yeni bir oturumda yeniden oluşturun. Yeni bir oturum başlatın ve kuralı tetiklemesi gereken en küçük görevi verin. Burada çalışıp uzun bir oturumda başarısız oluyorsa sorun mesafe veya sıkıştırmadan kaynaklanıyordur. Burada da başarısız oluyorsa sorun doğrudan kuralın kendisidir.
- Rekabeti ortadan kaldırın. Mevcut kodu zaten kurala uyan bir dizinde aynı değişikliği yapmasını isteyin. Uyumluluk geri gelirse, çevredeki kod sizin cümlenizi geçersiz kılıyordur.
- Çakışma arayın. Aynı davranış için farklı yönlendirmeler veren iki dosya, belgelenmiş bir başarısızlıktır: model bunlardan birini rastgele seçebilir ve size bunu söylemez.
- Denetlenebilir hale getirin ve tekrar test edin. Kuralı somut bir yol ve koşul ile yeniden yazın. Uyumlulukta büyük bir artış olması, sorunun ifade biçiminden kaynaklandığını gösterir.
- adım tek bir komuttur. Sadece düzenlediğiniz dosyayı değil, konuyla ilgili tüm talimat kaynaklarını grep ile tarayın:
grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" --include="AGENTS.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/nullFarklı şeyler söyleyen iki dosyada eşleşme bulmanız, hatanızın kaynağıdır. Birini silin. Daha güçlü ifadeler kullanarak onları sıralamaya çalışmayın, çünkü başvurabileceğiniz bir sıralama motoru yoktur. Claude Code v2.1.283 veya sonraki sürümlerde, /doctor prompt-audit bu aramayı talimat dosyalarınız, kurallarınız ve yetenekleriniz genelinde daha kapsamlı bir şekilde çalıştırır ve siz onay vermeden hiçbir şeyi değiştirmeden önerilen düzenlemelerle birlikte çelişkileri raporlar.
Kaldıraç etkisine göre düzeltmeler
Aşağıdaki her adım, bir öncekinden daha yüksek kaldıraç etkisine sahiptir ancak kurulumu daha maliyetlidir. Bir kuralın yeniden ifade edilmesi ucuz olduğunda en üstten başlayın. Ara sıra yapılan hataların kabul edilemez olduğu kadar önemli bir kural söz konusu olduğunda aşağıya doğru ilerleyin.
- Kuralı somutlaştırın. Bir yol, bir komut veya bir koşul belirtin. Daha önce gösterildiği gibi, temsilcinin depoda bulacağı karşıt kanıtı ekleyin. Bu işlem ücretsizdir ve vakaların şaşırtıcı derecede büyük bir kısmını çözer.
- Kuralı yönettiği öğeye yaklaştırın. İç içe geçmiş bir
CLAUDE.md,.claude/rules/içinde kapsamı belirlenmiş bir yol kuralı veya dosyanın en üstünde yer alan bir yorum. Kural, uygulandığı kodla aynı okuma işleminde karşınıza çıkar. Takasın farkında olun: bu şekilde yüklenen her şey bir sonraki sıkıştırma işleminde kaybolur ve bir sonraki eşleşen okumada geri döner. - Uygulamayı bir kancaya (hook) taşıyın. Metin rica eder, kanca ise karar verir. Kancalar, sabit yaşam döngüsü olaylarında kod olarak çalışır ve modelin ne sonuca vardığından bağımsız olarak uygulanır.
- Kuralı deterministik bir araca verin ve metni silin. Biçimlendirme, içe aktarma sırası, satır uzunluğu, yasaklı içe aktarmalar, commit mesajı biçimi.
ruff format,prettier --write,eslint, birpre-commitkancası. Biçimlendirici her zaman haklıdır ve sıfır token maliyeti vardır. Cümle ise çoğu zaman haklıdır ancak her seferinde token harcar.
- adımı detaylandıralım. Göç (migration) dosyalarının temsilci tarafından asla düzenlenmemesi gerektiğini varsayalım. Bunu
.claude/settings.jsoniçine yerleştirin:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-migrations.sh"
}
]
}
]
}
}Ve bunu .claude/hooks/guard-migrations.sh içine yerleştirin:
#!/usr/bin/env bash
set -euo pipefail
path=$(jq -r '.tool_input.file_path // empty')
case "$path" in
*/migrations/*)
echo "Files under migrations/ are written by hand. Stop and ask first." >&2
exit 2
;;
esac
exit 0chmod +x .claude/hooks/guard-migrations.sh komutunu çalıştırın, ardından yeni bir oturum başlatın ve temsilciden migrations/ altındaki bir dosyayı düzenlemesini isteyin. Düzenleme reddedilir ve mesajınız gerekçe olarak geri döner. PreToolUse üzerindeki 2 çıkış durumu, araç çağrısını çalışmadan önce engeller ve stderr metniniz, engelleyici mesaj olarak modele iletilir. ${CLAUDE_PROJECT_DIR} proje kök dizinine çözümlenir, bu nedenle kanca, temsilci hangi dizinde olursa olsun çalışır. Temsilcinin kuralı kabul etmesi, hatırlaması veya kuralın hala bağlam içinde olması gerekmez. Düzenleme gerçekleşmez.
İçinde mantık barındırmayan düz bir yasak için, ayarlarınızdaki permissions.deny, bakımı yapılacak bir betik olmadan aynı işi yapar ve izin modları size sormadan neyin çalışacağına karar verir. Bir talimatın kullanıcı mesajı yerine sistem istemi düzeyinde durması gerekiyorsa, --append-system-prompt bunu sağlar; ancak bu, her yeni oturumda tekrar geçilmesi gereken bir başlatma bayrağıdır ve etkileşimli çalışmadan ziyade betikler için daha uygundur.
Talimatla giderilemeyecek durumlar
Bu durumun hangi kısmının size ait olduğu konusunda net olun. Yerleşim, ifade biçimi, dosyalar arası çakışmalar ve dosya boyutu yazarın sorunlarıdır ve yazar tarafından düzeltilmelidir. Geri kalan kısım modelin davranışıdır; daha iyi bir ifade biçimi bunu ortadan kaldırmayacaktır.
Onaylama, uyum sağlamak değildir. Bir aracı kuralı kabul eder, size doğru şekilde geri ifade eder ve iki araç çağrısı sonra kuralı ihlal eder. Onaylamanın bir maliyeti yoktur ve hiçbir şeyi öngörmez. Bunu bir çözüm olarak okumayın ve bir test olarak saymayın.
Bazı alışkanlıklar kalıcıdır. Yorum eklemek, savunma amaçlı hata yönetimi eklemek, kapanış özeti yazmak, bir sonraki bariz komutu çalıştırmak gibi. Bunlar, kendilerini yasaklayan bir kural altında bile, sıfıra inmek yerine azalan bir oranda geri dönerler. Kendi hata oranınızı ölçebilirsiniz: aynı görevi on kez yeni oturumlarda çalıştırın ve ihlalleri sayın. Bu sayının sıfır olması gereken durumlarda, kuralın istemden (prompt) çıkarılması gerekir. Bir işi, parçası henüz tamamlanmamışken bitmiş olarak raporlamak aynı alışkanlık biçimidir ve bunun onarımı sözel değil yapısal olmalıdır: tembellik etmeme becerisi, cümleyi bir Derinlik Ağacı (Depth Tree) ile değiştirir ve aracın bittiğini iddia etmeden önce temizlemesi gereken dosya kapıları oluşturur.
Kendi oturumunuz bir örneğe dönüşür. Eğer aracı 12. adımda kuralı ihlal ettiyse ve siz buna izin verdiyseniz, bu ihlal artık bağlam içinde bir gösterim olarak yer alır ve kuraldan çok daha günceldir. Bir ihlali gördüğünüz anda düzeltin. Düzeltilmeyen bir ihlal, oturumun geri kalanına yanlış öğretir.
Bir talimat dosyası bir güvenlik sınırı değildir. Davranışı şekillendirir ancak zorunlu kılmaz. Hata yapmanın maliyetli olduğu, kimlik bilgileri veya yıkıcı komutlar içeren her şey, izinlerin veya bir kancanın (hook) konusudur. Sırları bir aracın erişemeyeceği yerde tutmak, aynı ilkeyi veriler için de uygular: bir araçtan bir dosyayı okumamasını istemeyin, dosyanın okunabilir olmamasını sağlayın.
Kısa versiyonu şudur: Dosyanın yüklendiğini kanıtlayın, kuralı denetlenebilir kılın, kuralı yönettiği şeyin yanına taşıyın ve hata oranı hala önemliyse, kuralı düz yazıdan çıkarın. Bir aracın görmezden gelemeyeceği bir kural, araca hiç sorulmamış olan kuraldır.
FAQ
Claude Code neden CLAUDE.md dosyamı yok sayıyor?
Yoksayıldığını varsaymadan önce yüklendiğinden emin olun. /context komutunu çalıştırın ve Memory files listesini kontrol edin; bu listede yer almayan bir dosya başlangıçta yüklenmemiş demektir. Talimat dosyaları, sistem isteminden sonra bir kullanıcı mesajı olarak iletilir ve zorunlu bir yapılandırmadan ziyade bağlam olarak ele alınır, bu nedenle kesin bir uyum garantisi yoktur. Çoğu gerçek durum şu dört nedenden birine dayanır: dosya ajanın hiç okumadığı bir alt dizindedir, iki dosya birbiriyle çelişiyordur ve model bunlardan birini rastgele seçmiştir, kural bir eylemi denetlemek için çok belirsizdir veya çevredeki kod kuralın söylediğinin tam tersini göstermektedir.
Oturum sırasında talimat dosyasını düzenlemek bir şeyi değiştirir mi?
Konuşmadaki mevcut kopya için değiştirmez. Çalışma dizininizin üzerindeki dosyalar başlangıçta tamamen yüklenir, bu nedenle modelin elinde tuttuğu metin başlangıç anındaki metindir. Bir düzenlemeyi işleme almak için yeni bir oturum başlatın veya ajandanın dosyayı normal dosya araçlarıyla okumasını isteyin; bu, güncel sürümü yeni bir mesaj olarak konuşmaya ekler. Bir sıkıştırma (compaction) işleminden sonra proje kök dizinindeki dosya diskten yeniden okunur, bu nedenle yeni sürüm o noktada sisteme dahil olur.
Kök dizindeki CLAUDE.md ile iç içe olan bir dosya çeliştiğinde hangisi geçerli olur?
Güvenilir bir şekilde hiçbiri. Keşfedilen dosyalar birbirinin üzerine yazılmak yerine bağlama eklenir (concatenated). Dosya sistemi kökünden çalışma dizininize doğru sıralanırlar, bu nedenle en yakındaki dosya en son okunmuş olur. Çelişkileri çözen bir öncelik motoru yoktur ve Claude Code belgeleri, çelişkili kuralların rastgele çözülebileceğini belirtir. İç içe dosyaları, yönettikleri yolu belirten eklemeler olarak yazın ve bir kuralı diğerinden üstün kılmaya çalışmak yerine çelişkili olanı silin.
Talimatlarım /compact komutundan sonra korunur mu?
Bu, nasıl yüklendiklerine bağlıdır. Proje kök dizinindeki CLAUDE.md, kapsam dışı kurallar ve otomatik bellek, sıkıştırma işleminden sonra diskten yeniden enjekte edilir. paths: ön bilgisine (frontmatter) sahip kurallar ve alt dizinlerdeki iç içe CLAUDE.md dosyaları, eşleşen bir dosya tekrar okunana kadar kaybolur. Yalnızca sohbet ekranına yazdığınız her şey, özetleyici (summariser) bunları tesadüfen tutarsa korunur. Bir kuralın tüm oturum boyunca geçerli olması gerekiyorsa, onu paths: ön bilgisi olmadan proje kök dizinindeki dosyaya ekleyin.
Bir kural ne zaman düz metin yerine bir kanca (hook) haline getirilmelidir?
Denetim deterministik olduğunda ve bir hatanın maliyeti, küçük bir betik yazmanın maliyetinden yüksek olduğunda. Dosya yolu kısıtlamaları, commit öncesi gerekli komutlar ve yasaklanmış araç çağrılarının tümü buna uygundur. 2 durum koduyla çıkan bir PreToolUse kancası, araç çağrısını doğrudan engeller ve stderr metninizi neden olarak modele geri iletir; böylece kuralın bağlam içinde herhangi bir yerde olup olmamasından bağımsız olarak geçerliliğini korur. Bir biçimlendiricinin (formatter) veya linter'ın karar verebileceği her şey o araca ait olmalı ve talimat dosyasından tamamen silinmelidir.