Rehberler

Yazan Matt Connor 2026-08-12 · Güncellendi 2026-08-27

Kodlama ajanları neden talimatları görmezden gelir?

Kodlama ajanlarının talimatları neden uygulamadığını teknik nedenleriyle öğrenin. Bağlam penceresi kısıtlamaları ve işlem sırası hatalarını teşhis etmek için izlenecek adımlar.

Kodlama ajanlarının talimatlarınızı görmezden gelme nedenleri

Kodlama ajanlarının talimatlarınızı görmezden gelmesinin dört nedeni vardır ve bunların hiçbiri fazla nazik olmanızla ilgili 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 unsur, genellikle ajanın az önce okuduğu kod, talimatla çelişmektedir. Ya da 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 nedenle ilk iş bunları birbirinden ayırmaktır. Büyük harfler ve ÖNEMLİ kelimesi bir teşhis yöntemi değildir. Aşağıdaki mekanizmalar, Ağustos 2026 itibarıyla yükleme ve sıkıştırma davranışları ayrıntılı olarak belgelendiği için örnek olarak Claude Code kullanmaktadır. Diğer araçlar ayrıntılarda farklılık gösterse de ana 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 anında bütünüyle yüklenir. Bu dosyalar belirtilen sırada 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 anında yüklenmez. Yalnızca aracı, 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 dahil edilir.

Bu tek fark, bildirilen hataların büyük bir kısmını açıklar. packages/api/CLAUDE.md içine bir kural eklersiniz, 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 edilmesi gereken ilk yer burasıdır.

Bir diğer yükleme tuzağı ise "aracı talimatlarımı görmezden geldi" şikayetlerinin en yaygın nedenidir: Claude Code AGENTS.md dosyasını değil, CLAUDE.md dosyasını okur. Standart olarak AGENTS.md kullanan ve CLAUDE.md dosyası bulunmayan bir depo, Claude Code'a yüklenecek hiçbir şey sunmaz. Desteklenen köprü, ilk satırı @AGENTS.md olan ve başlatma anında dosyayı içe aktaran, altında ise Claude'a özel notların bulunduğu bir CLAUDE.md dosyasıdır. Ekleyecek başka bir şeyiniz olmadığında sembolik bağ (symlink) da iş görür. Bu dosyada nelerin yer alması gerektiğine karar vermek ise aracı talimatlarını insan dokümantasyonundan ayırma konusunda ele alınan ayrı bir konudur.

Dosyayı yeniden yazmadan ö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; ilki daha hızlı ve basit olanıdır.

Oturum içerisinde /context komutunu çalıştırın. Bu komut, mevcut pencereyi kategorilere ayırarak listeler ve Memory files listesi, gerçekten yüklenmiş olan her bir yönerge dosyasının adını gösterir. Bu listede yer almayan bir dosya konuşmaya dahil edilmemiştir; dolayısıyla dosya içerisinde yapacağınız hiçbir değişiklik bir sonuç doğurmaz. /memory ise dosya konumlarını listeler ve henüz var olmayanlar da dahil olmak üzere dosyaları 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 size yüklemenin neden gerçekleştiğini bildirir: session_start, nested_traversal, path_glob_match, include veya compact. Bunu .claude/settings.json içerisine 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 bu kaydı izleyin. Bu olayın çıkış durumu göz ardı edilir; dolayısıyla kanca yalnızca gözlem yapabilir, engelleme yapamaz. İç içe yerleştirilmiş dosyanız, beklediğiniz bir oturum sırasında bu günlükte görünmüyorsa yeniden yazma işlemini durdurun. Sorun, dosyanın konumlandırılmasından kaynaklanmaktadır.

Uzun bir oturumun kurallarınız üzerindeki etkisi

Burada iki ayrı etki söz konusudur ve bunlar farklı yaklaşımlar gerektirir.

Mesafe. 1. turda belirtilen bir kural, 90. turda hala pencere içerisindedir ancak şu an yaptığınız işe daha güncel ve daha özel olan 90 turluk metinle rekabet halindedir. Bunu yapılandırma ile 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, sorun mesafedir.

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 mekanizma bazında belgeler ve farklar büyüktür. Proje kök dizini CLAUDE.md ve kapsam dışı kurallar, bir sıkıştırma işleminden sonra diskten yeniden enjekte edilir. Otomatik bellek diskten yeniden enjekte edilir. paths: ön bilgisine 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 içine 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 elenmiş ve yalnızca 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 olmadan 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, /compact konusunu bir odak argümanı ile ve /clear konusunu birbiriyle ilişkisiz görevler arasında ele alır; her ikisi de özetleyicinin kurallarınızın ne olduğuna karar verme sıklığını 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şimi app/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 test komutunu ç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: ".ts dosyaları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, karmaşık ve uzun kurallar listesiyle baş başa kaldıklarının sebebidir.

Yüklendiğini doğrulayın. /context komutunu çalıştırın ve Memory dosyaları listesini okuyun. Dosya orada değilse, konumu düzeltin ve durun. Bu listedeki diğer maddeler 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 başarılı olup uzun bir oturumda başarısız oluyorsa, sorun mesafe veya sıkıştırma kaynaklıdır. Burada da başarısız oluyorsa, sorun doğrudan kuralın kendisindedir.
Rekabeti ortadan kaldırın. Mevcut kodu zaten kurala uyan bir dizinde aynı değişikliği yapmayı deneyin. Uyumluluk geri gelirse, çevredeki kod sizin ifadenizi geçersiz kılıyordu.
Çakışma arayın. Aynı davranış için farklı yönlendirmeler veren iki dosya, belgelenmiş bir hata durumudur: model bunlardan birini rastgele seçebilir ve size bunu bildirmez.
Denetlenebilir hale getirin ve yeniden 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" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/null

Farklı ş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.

Düzeltmeler, etki düzeyine göre sıralanmıştır

Aşağıdaki her adım, bir öncekinden daha yüksek etki düzeyine sahiptir ancak kurulumu daha maliyetlidir. Bir kuralı yeniden ifade etmek ucuz olduğunda en üstten başlayın. Bir kural, ara sıra yapılan hataların kabul edilemeyeceği kadar önemli hale geldiğinde 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üne eklenen 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, bir pre-commit kancası. 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.json iç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 0

chmod +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 reddedilecek ve mesajınız gerekçe olarak geri dönecektir. 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 temsilci hangi dizinde olursa olsun kanca çalışır. Temsilcinin kuralla hemfikir olması, kuralı hatırlaması veya kuralın bağlam içinde kalması gerekmez. Düzenleme gerçekleşmez.

Herhangi bir mantık içermeyen düz bir yasak için, ayarlarınızdaki permissions.deny aynı işi herhangi bir betik bakımı gerektirmeden yapar ve izin modları size sormadan neyin çalışacağına karar verir. Bir talimatın kullanıcı mesajı yerine sistem istemi (system prompt) düzeyinde kalması gerekiyorsa, --append-system-prompt bunu oraya yerleştirir; ancak bu talimat her çağrıda iletilmelidir, bu da 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ı görmezden geliyor?

Dosyanın göz ardı edildiğini 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 konuşmaya dahil edilmemiştir. 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 katı bir uyumluluk garantisi yoktur. Çoğu gerçek durum şu dört nedenden birine dayanır: dosya, aracının hiç okumadığı bir alt dizindedir; iki dosya birbiriyle çelişiyordur ve model rastgele birini 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şmada halihazırda bulunan kopya için değiştirmez. Çalışma dizininizin üzerindeki dosyalar başlatma anında tamamen yüklenir, bu nedenle modelin elinde tuttuğu metin başlatma anındaki metindir. Bir düzenlemenin dikkate alınması için yeni bir oturum başlatın veya aracı, dosyayı normal dosya araçlarıyla okumaya zorlayın; bu işlem, dosyanın güncel sürümünü yeni bir mesaj olarak konuşmaya ekler. Bir sıkıştırma (compaction) işleminden sonra proje kök dizinindeki dosya diskten yeniden okunur, dolayısıyla 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?

Hiçbiri güvenilir bir şekilde geçerli olmaz. Keşfedilen dosyalar birbirinin üzerine yazılmak yerine bağlama eklenir (concatenated). Dosya sistemi kökünden çalışma dizininize doğru sıralandıkları için en yakındaki dosya en son okunur. Çelişkileri çözen bir öncelik mekanizması 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, talimatların nasıl yüklendiğine 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. Sadece sohbet ekranına yazdığınız her şey, yalnızca özetleyici (summariser) bunları tesadüfen saklarsa 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 belirleyici (deterministic) 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 zorunlu komutlar ve yasaklı araç çağrılarının tümü bu kapsama girer. 2 durum koduyla sonlanan bir PreToolUse kancası, araç çağrısını doğrudan engeller ve stderr metninizi neden olarak modele geri iletir; bu sayede kuralın bağlam içinde 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 bırakılmalı ve talimat dosyasından tamamen silinmelidir.

#claude-code #agents-md #context #prompting #coding-agents