Hafıza kayıtları yazma

Hafıza kaydı, asistan daha sonra okuyabilsin diye ekibinizin not ettiği kısa bir Markdown notudur. Hafıza kayıtları bir çalışma alanı yolunda durur ve yalnızca asistan o yolun altında çalışırken karşısına çıkar. Pathrule'daki en yaygın içerik türüdür ve başlamak için en kolay olanıdır.

Bu sayfada ne zaman hafıza kaydı yazmanız gerektiğini, kaydı nasıl yapılandıracağınızı, kapsamın ve sürümlemenin nasıl çalıştığını bulacaksınız.

Ne zaman hafıza kaydı yazmalı

Elinizde koddan anlaşılmayan ve yeniden gündeme gelmesi muhtemel bir bilgi varsa hafıza kaydı yazın.

• Kararlar. "Bu depoda her şey için Supabase üzerinde Postgres kullanıyoruz. ORM eklemeyin. Doğrudan supabase-js istemcisini kullanın."
• Tuzaklar. "orders.status enum'unu değiştirirseniz şema migration'ından önce veri migration'ını çalıştırmanız gerekir. Sıra, şemanın geri kalanının tersidir."
• Olay sonrası analizler. "2026-04-12 tarihinde Stripe idempotency anahtarını kontrol etmediğimiz için müşterilerden iki kez ücret alan bir webhook handler yayına aldık. Artık bu anahtarı her zaman gönderin."
• Ekip alışkanlıkları. "Testler, paralel bir __tests__ dizininde değil, test ettikleri dosyanın yanında durur."
• Ekibin sözlü bilgisi. "Bu flag'in neden var olduğunu yalnızca bir kişi hatırlıyor. Upstream'deki bir çalışma zamanı tuhaflığı yüzünden hâlâ gerekli."

Kodun zaten açıkça söylediği, her hafta değişen ya da tamamen kişisel tercihe dayanan konular için hafıza kaydı yazmayın.

Yapı

Her hafıza kaydının bir başlığı ve bir Markdown gövdesi vardır. İkisini de kısa tutun.

• Başlık: kısa, kesin bir ifade; kenar çubuğuna sığmalı. "Yalnızca Postgres. ORM yok.", "Veritabanı erişim kalıplarına dair notlar" başlığından iyidir.
• Gövde: derdinizi anlatmaya yetecek en az Markdown. Madde işaretleri genellikle paragraflardan daha anlaşılırdır. İşe yarayacaksa bir örnek ekleyin.

Zorunlu bir şablon yoktur, ama kullanışlı bir varsayılan şöyledir:

The constraint or fact in one sentence.

Why:
- The reason this matters or the incident that prompted it.

How to apply:
- The concrete thing the assistant should do when the topic comes up.

Yol kapsamı

Yol, hafıza kaydının yarısıdır. Kaydın nerede karşınıza çıkacağını o belirler.

• /apps/api/payments yolundaki bir hafıza kaydı, apps/api/payments altındaki her çalışmada karşınıza çıkar.
• /apps/api yolundaki bir hafıza kaydı, api dizininin tamamında karşınıza çıkar.
• / yolundaki bir hafıza kaydı, çalışma alanının her yerinde karşınıza çıkar.

İstediğiniz durumları hâlâ kapsayan en özel yolu seçin. Ödemelerle ilgili bir hafıza kaydını çalışma alanı düzeyine koymak gürültü yaratır; payments klasörüne koymak çok daha iyidir.

Sürümleme ve eşzamanlı düzenlemeler

Her kayıt işlemi, başladığınız sürümle karşılaştırılır. Arada başka biri kaydetmişse, sizin kaydınız onunkinin üzerine yazmak yerine reddedilir. Bu, ekibinizi iki kişinin (ya da bir kişiyle bir ajanın) fark ettirmeden birbirinin üzerine yazmasından korur.

• VS Code için Pathrule'da hafıza kaydı bir Markdown sekmesidir. Bir ekip arkadaşınızın daha yeni değişikliğinin üzerine yazacak bir kayıt işleminde Reload, Copy My Version & Reload (metniniz önce panoya kopyalanır) veya Keep Mine (Overwrite) seçenekleri sunulur.
• MCP üzerinden asistan en son okuduğu sürümü gönderebilir. Uyuşmazlık olursa güncel sürümle birlikte bir çakışma yanıtı alır, kaydı yeniden okur ve üzerine yazmak yerine birleştirir.

Silme işlemi de geri alınabilir. VS Code'da silme işleminin hemen ardından Undo seçeneği sunulur. Pathrule Cloud çalışma alanında ise silinen hafıza kaydı kalıcı olarak silinene kadar çalışma alanı arşivinde kalır; bir sahip veya yönetici kaydı web konsolu ayarlarından (Workspace, Archive) geri yükleyebilir ya da kalıcı olarak silebilir. Hafıza kayıtları genellikle küçük ve odaklı olduğu için pratikte çakışmalar nadirdir, ama bu güvenlik ağı her zaman açıktır.

Kayıtları kim yazar

• İnsanlar, VS Code için Pathrule'da (New Memory… veya Save Selection as Memory) ya da CLI ile yazar.
• Asistan, siz bir şeyi kaydetmesini istediğinizde pathrule_write_memory MCP aracıyla yazar. Kurulum sırasında proje için hafıza kayıtları, kurallar ve beceriler önerir ve yalnızca sizin onayladıklarınızı yazar.

Terminalde hafıza kaydı oluşturmak tek bir komuttur. --body vermezseniz CLI, gövde için editörünüzü açar; --body parametresini de kullanabilir ya da metni pipe ile aktarabilirsiniz. pathrule memory list ve pathrule memory read "Exact title" --print komutları hafıza kayıtlarını okur.

pathrule memory add --path /apps/api/payments --title "Always pass the Stripe idempotency key"

İki kaynak da aynı yere düşer. Asistan bir insanın yazdığını, insan da asistanın yazdığını okur. Her kayıt, onu kimin oluşturduğunu, en son kimin düzenlediğini ve kaynağını saklar. VS Code'daki Info eylemi bunları gösterir, böylece yapay zekânın yazdığı hafıza kayıtlarını kolayca ayırt edebilirsiniz.

Hafıza kalitesi nasıl incelenebilir kalır

Pathrule, birbirinden bağımsız birkaç denetimle bir hafıza kaydını dar ve incelenebilir tutar:

• Genel dokümantasyon otomatik olarak içe aktarılmaz, kurulum sırasında önerilir. Etkin talimat dosyaları, bunların import zinciri, araç kuralları ve karar kayıtları ise etkin bilgi olduklarına dair daha güçlü kanıt taşır.
• Bir ajandan, kalıcı bilgiyi kaydetmeden önce önermesi istenir. Kaydettiği her şey de diğer içerikler gibi kime ait olduğu belli, sürümlü ve çalışma alanında görünür olur; böylece açabilir, düzenleyebilir veya kaldırabilirsiniz.
• Yol kapsamı, kaydın nerede karşınıza çıkabileceğini sınırlar; geçerli yolun dışındaki bir kaydın yine de alaka eşiğini geçmesi gerekir.
• Ölçülen kullanım, eşiği geçen kayıtların önceliğini değiştirebilir, ama ilgisiz bir hafıza kaydını bu eşiğin üzerine çıkaramaz.
• Bir hafıza kaydının koddan uzaklaştığını fark eden ajan, kaydı yenileme görevi olarak işaretleyebilir; bir asistan bu görevi daha sonra alır ve sizin kontrolünüzde düzeltir. Bkz. Öneriler ve öz denetim. Düzenlemeler sürümlüdür ve silme geri alınabilir.
• Başlığı aynı yoldaki mevcut bir kayıtla eşleşen yeni bir hafıza kaydı, ikinci bir kopya olarak kaydedilmek yerine varsayılan olarak reddedilir; böylece aynı karar iki kez iletilmez ya da kopyalar zamanla birbirinden kopmaz. Mevcut kaydı kontrol ettikten sonra bunu bilinçli olarak geçersiz kılabilirsiniz (CLI'da --allow-duplicate).

Ortaya çıkan çalışma modeli, çalışma alanına kopyalanmış büyük bir arşiv değil, dar ve incelenebilir kararlardan ve tuzaklardan oluşan küçük bir kümedir. Teknik sözleşmenin tamamı için Pathrule zor iddiaları nasıl kanıtlar sayfasına bakın.

Okumak ve atıfta bulunmak

En ilgili hafıza kayıtları, asistanın doğrudan üzerine iş yapabileceği tam gövdeler olarak gelir. Daha az emin olunan adaylar ise id'leriyle birlikte başlık olarak gelir; asistan bunlardan birine dayanmadan önce pathrule_read_memory ile kaydın tamamını okur. Bu sayede belirsiz içerik varsayılan yükün dışında kalır, güçlü eşleşmeler ise fazladan gidiş dönüşe dönüşmez.

VS Code'da Browse Knowledge Here…, bir yoldaki yapay zekâ oturumunun neler aldığını, üst yollardan devraldıkları da dahil olmak üzere gösterir.

Kaçınılması gereken kalıplar

• Tek bir dev "tüm notlarım" kaydı. Konuya ve kapsama göre bölün. Küçük ve yola bağlı kayıt, uzun ve genel kayda her zaman üstün gelir.
• Kodun zaten söylediğini tekrarlayan hafıza kayıtları. Asistan kodu okuyabilir. Hafıza kayıtlarını "neden"e ve tuzaklara ayırın.
• Eskimiş hafıza kayıtları. Arkasındaki karar değiştiğinde güncelleyin ya da silin. Bir asistan koddan uzaklaşmış bir kaydı yenileme görevi olarak işaretleyebilir, ama bir insan gözü daha hızlıdır.

Yerel modda ve Cloud'da içerik yazma

Bu sayfadaki terminal add örnekleri Cloud çalışma alanı içindir. Yerel modda kayıtları Local Console'da, VS Code'da ya da yerel MCP üzerinden oluşturup düzenleyin; CLI bilgi komutları bu kayıtları listeler, okur ve içlerinde arama yapar.

Sırada ne okumalı

• Öncelikli kısıtlar için Kural yazma.
• Yeniden kullanılabilir prosedürler için Beceri yazma.
• Bunların bağlandığı çalışma alanı ağacı için Temel kavramlar.