Daha sonra, aşağıdaki içeriği otomatik olarak dahil edebilen ve kompakt özelliği şeffaf bir şekilde geliştiren bir eklenti oluşturdum.
https://x.com/u1/status/2073742408555343968
Claude Code'un Kompakt Özelliği Aslında Nasıl Çalışır?
Öncelikle, Claude Code'un kompakt özelliği iki yoldan çalışır:
- Manuel kompakt (/compact): Kullanıcı tarafından açıkça tetiklenir. Herhangi bir zamanda çalıştırılabilir.
- Otomatik kompakt: Oturum bağlam kullanımı sınıra yaklaştığında (pratikte kabaca %90-95) otomatik olarak çalışır. Kullanıcının tam olarak istediği anda değil, daha çok aniden sıkıştırıldığını fark ettiğiniz dönüş sınırlarında çalışır.
Her iki yolda da içerik aynıdır: önceki konuşma geçmişi, doğal dilde bir özet oluşturması için LLM'ye gönderilir ve özet + son turlar + sistem istemi yeni bir bağlam olarak yeniden yapılandırılır. Özet, "ne yapıldığına" dair anlatı temelli bir açıklama haline gelir ve sonuç olarak, "bu karar neden alındı", "hangi planlar reddedildi" ve "şu anda hangi aşamadayız" gibi karar yapısı zayıflar. Ayrıca, sıkıştırma çalıştırıldıktan sonra geri döndürülemez bir işlemdir; sıkıştırma öncesindeki ham kayıtlara dönemezsiniz.
Bir kanca perspektifinden bakıldığında, sıkıştırma PostCompact olayı tarafından yakalanabilir. Ancak, PostCompact kancası additionalContext döndüremez, bu nedenle sıkıştırmadan hemen sonra ajana doğrudan talimat enjekte etmenin bir yolu yoktur. Talimat eklemek için sonraki UserPromptSubmit olayından geçmek gerekir. Bu kısıtlama, bu makaledeki kanca tasarımını belirler.
Standart Kompaktın Sorunu Nedir?
Claude Code'un /compact'ı konuşma geçmişini özetler ve sonucu yeni bir oturumun başlangıç bağlamı olarak yerleştirir. Özetin kendisi makul olsa da, bu "bundan sonra ne yapılacağına dair bir talimat" değil, "geçmişin bir iş günlüğü"dür. Sonuç olarak, sıkıştırma sonrası ajan aşağıdaki yanlış anlamalara yatkın hale gelir:
- "İş talimatları" ile "iş günlükleri" arasındaki sınırı kaybetmek. Özet "Plan A değerlendirildi" derse, ajan aslında kabul edilen Plan B yerine Plan A'yı uygulamaya başlayabilir.
- Doğrulama aşaması ile uygulama aşamasını karıştırmak. "Dağıtmadan önce gerçek makinede doğrula" önermesi özetten düşer ve ajan bir sonraki turda yıkıcı dağıtım işlemlerine atlayabilir.
- Daha önce reddedilen yanlış yaklaşımları yeniden önermek. Özet, bir yaklaşımın "denendiğini" ancak "neden reddedildiğini" kaydedebilir.
- Plan modu, çalışan delegasyonu veya görev ağaçları gibi "oturum durumunu" kaybetmek. Ajan, plan modundan çıkmış halde çalışmaya devam edebilir veya tmux'te çalışan işçilerin varlığını unutup işi kendisi yapmaya başlayabilir.
Aslında Ne Tür Kazalar Meydana Geldi?
Geçen haftaki oturumlarıma baktığımda, her kompakttan hemen sonra en az dört desen gözlemledim. Hepsi "iş talimatları" ile "iş günlükleri"ni ayıramamaktan kaynaklanıyor gibi görünüyor:
- Doğrulamadan önce dağıtım: "Dosyaları yerleştirmeden önce makinede davranışı doğrula" konusunda anlaşmamıza rağmen, ajan sıkıştırmadan sonra özette yalnızca tamamlama görüntüsünü gördü, doğrulamayı atladı ve hedefin üzerine yazdı.
- Reddedilen kısayolları yeniden yürütme: Özet, başarısız bir kısayol yaklaşımını "denenmiş bir prosedür" olarak kaydettiği için, ajan onu yeniden yürüttü ve aynı başarısızlığa tekrar adım attı.
- Tasarım ilkelerini unutma: Oturum sırasında "hedef yerine kaynak deposunu düzenle" gibi belirlenen ilkeler özetten düştü ve ajanın kısa vadede çalışan ancak tekrarlanabilir olmayan doğrudan düzenlemeler yapmasına yol açtı.
- Görev hedeflerini yanlış anlama: Sıkıştırmadan önce düzeltilen bir testin belirli amacı kayboldu ve ajanın çevresel araştırmalara sapmasına ve tamamen farklı bir hat üzerinde çalışmaya başlamasına neden oldu.
Bunlar aynı oturum içinde birden çok kez meydana geldi ve her kompakttan sonra farklı türde yanlış anlamalar oldu. Bunları izole kazalar olarak değil, standart kompakt spesifikasyonunun yapısal başarısızlıkları olarak görüyorum.
Ne İnşa Ettim?
(1) compact-prep becerisi
Kullanıcının /compact yazmadan önce açıkça çalıştırdığı, eğik çizgi komutu olarak uygulanan bir beceri. Bir özete sığması muhtemel olmayan "karar yapısını" ve "oturum durumunu" çıkarır ve bunları belirli bir formatta sabit bir yoldaki (${TMPDIR}/claude-compact-state/<session_id>.md) bir durum dosyasına kaydeder.
Kaydedilen öğeler, özetlerde yakalanması zor olanları içerir:
- Aktif Plan (plan dosya yolu ve mevcut aşama)
- Görev Listesi Özeti (devam eden görevler ve eklemeler)
- Oturum Kararları (kabul edilen planlar / reddedilen planlar / ret nedenleri)
- Kısıtlamalar ve Engelleyiciler
- İşçi Topolojisi (tmux-bridge bölmeleri / roller / atamalar)
- Düzenlenen Dosyalar (kaydedilmemiş veya doğrulanmamış değişikliklerle ilgili notlar)
- Kurtarma Notları (sıkıştırma sonrası kendine mektup)
Anahtar tasarım noktası "mekanik zorlamadır". Bir session_id bulunamazsa dosya oluşturmayı önlemek için bir sert geçit, eksiklikleri tespit etmek için sabit başlıklarla bir zorlama işlevi ve durum bozulmasını önlemek için kısıtlı izin verilen araçlar kullanır.
(2) İki aşamalı kanca: PostCompact + UserPromptSubmit
(1) bir durum dosyası yazsa bile, sıkıştırma sonrası ajan onu okumazsa anlamsızdır. PostCompact additionalContext döndüremediğinden, iki aşamalı bir yapılandırma kullandım:
- PostCompact kancası, session_id ile bir işaretleyici dosya yazar (talimat yok, yalnızca sıkıştırmanın gerçekleştiğini kaydeder).
- Bir sonraki UserPromptSubmit kancası işaretleyiciyi algıladığında, additionalContext aracılığıyla talimatlar enjekte eder: "Plan dosyasını oku / Durum dosyasını oku / Görev Listesini kontrol et / Özetin sonraki adımlarını hipotez olarak ele al / Plan modu devre dışı bırakıldıysa yeniden girişi onayla" ve ardından işaretleyiciyi siler.
Claude Code, kancalar arasında paylaşılan bir durum mekanizmasından yoksun olduğundan, dosya sistemindeki bir işaretleyici tek iletişim yoludur. Bu, her kancayı tek bir sorumlulukla ince tutar. Normal turlarda, ek yük yalnızca bir test -f kontrolüdür.
(3) %60 Bildirimi (Otomatik kompakttan kaçınmak için)
Önceki araçlar, kullanıcının manuel olarak /compact-prep → /compact çalıştırdığını varsayar. Ancak, otomatik kompakt uyarı vermeden çalışır ve bu akışı atlar. Önce otomatik kompakt çarparsa, durum dosyası kaydedilmez ve ham kayıtlar bir özete dönüştürülerek kurtarma malzemesi kaybolur.
Çözüm, kullanıcının otomatik kompakt tetiklenmeden önce hazırlığı manuel olarak çalıştırabileceği bir durum yaratmaktır. %60 bildiriminin amacı budur.
Neden %60?
- Yeterli ön süre: Otomatik kompakt %90-95 civarında tetiklenir. %60, %30'luk bir marj sağlar ve kullanıcının bir sonraki turun otomatik kompaktı tetiklemesinden önce uyarıyı görmesini garanti eder.
- Bir durma noktasına ulaşmak için alan: %60'ta, durumu kaydetmeden önce bir alt görevi bitirmek için hala %30 kapasite vardır.
- Mekanik tetikleyici: Bağlam tüketimini fark edemeyecek kadar odaklandığınızda bir zorlama işlevi görür.
- 1M Bağlam Varsayımı: 200K bağlamla %60 çok küçüktür. 1M bağlam (Opus 4.7) kullanıyorum, burada %60 yaklaşık 600K token bırakır—işi bitirmek ve hazırlığı çalıştırmak için fazlasıyla yeterli alan.
Uygulama, eşikte bir uyarı işaretleyicisi yazan bir durum satırı kancası ve bunu algılayarak /compact-prep çalıştırmayı öneren bir UserPromptSubmit kancası içerir.
Sonuçlar
Oturumlar artık yaklaşık 10 sıkıştırmadan sonra bile mantıksal bir çöküş olmadan istikrarlı!
- Sıkıştırma nedeniyle iş kaybı neredeyse sıfır.
- Reddedilen fikirlerin yeniden önerilmesi ortadan kalktı.
- Plan modu korunuyor.
- tmux'te birden çok işçi çalıştırırken topolojiyi unutma yok.
Referans: Uygulama Kodu
Aşağıda gerçek beceri ve kanca kodları bulunmaktadır. Bunları standart Claude Code dizinine (~/.claude/) kopyalayarak çalışırlar.
A: compact-prep beceri gövdesi
~/.claude/skills/compact-prep/SKILL.md dosyasına yerleştirin.
1---2name: compact-prep3description: |4 Claude Code'da /compact yürütmeden önce, geçerli oturum durumunu geçici bir durum dosyasına kaydedin.5 ZORUNLU TETİKLEYİCİLER: /compact-prep, compact-prep, sıkıştırma hazırlığı.6 TETİKLEMEYİN: kompakt sonrası kurtarma, normal ilerleme raporları, plan oluşturma.7strict_procedure: true8argument-hint: "[kurtarma notları]"9allowed-tools: Read Write Bash(~/.claude/scripts/get-session-id.sh *) Bash(mkdir *) Bash(date *) Bash(pwd)10---1112# compact-prep1314Sıkıştırma özetlerinde tutulması zor olan oturum durumunu `/compact` öncesinde15`${TMPDIR}/claude-compact-state/${SESSION_ID}.md` dosyasına kaydeder.1617## Katı prosedür profili1819- Katılık: strict-procedure.20- Sert geçitler: session_id alınamazsa dur.21- Zorlama işlevi: Kaydettikten sonra sabit yol ve zorunlu başlık kontrolü.22- Tamamlama makbuzu: Dosya yolunu, kaydedilen öğeleri ve `/compact` çalıştırma yönergesini bildir.2324## Prosedür25261. `~/.claude/scripts/get-session-id.sh` aracılığıyla session_id alın.272. Yolu `${TMPDIR:-/tmp}/claude-compact-state/${SESSION_ID}.md` olarak ayarlayın.283. Görev Listesini, aktif planı, tmux-bridge'i ve düzenlenen dosyaları kontrol edin.294. Başlıkları sırayla kaydedin: # Compact Prep State, ## Active Plan, ## Current Phase, ## TaskList Summary, ## Session Decisions, ## Constraints and Blockers, ## Worker Topology, ## Editing Files, ## Recovery Notes.305. Tüm başlıkların mevcut olduğunu doğrulayın.316. Kullanıcıya söyleyin: "Hazırlık tamamlandı. Lütfen `/compact` çalıştırın."
B: Kurtarma kancaları (2 aşama)
B-1: PostCompact kancası
~/.claude/hooks/compaction-recovery.sh
B-2: UserPromptSubmit kancası (Enjeksiyon)
~/.claude/hooks/userpromptsubmit-compaction-recovery.sh
C: %60 Bildirimi
C-1: statusline kancası eşik dalı
~/.claude/hooks/statusline.sh dosyasına eklendi.
C-2: UserPromptSubmit kancası (Hatırlatıcı)
~/.claude/hooks/userpromptsubmit-compact-prep-reminder.sh
D: settings.json kaydı
Kancaları ~/.claude/settings.json dosyasına ekleyin.
