Bir kalıbın anatomisi

Bir kalıp bilinçli olarak basit tutulmuştur. Türü belli parçalardan oluşan küçük bir paket ile onu göstermek, sürümlemek ve bir projeyle eşleştirmek için gereken meta verilerden ibarettir. Bu yapıyı anladığınızda, bir kalıbı içe aktardığınızda elinize ne geçtiği de netleşir.

Kalıp, parçalardan oluşan bir pakettir

Her kalıp bir parça listesi taşır. Her parça tam olarak bir hafıza kaydı, bir kural ya da bir beceridir ve nereye yerleşeceğini bilir.

Bir parça şunları tanımlar:

• kind: memory, rule ya da skill. İçe aktarmada hangi içerik türüne dönüşeceğini bu alan belirler.
• nodePath: parçanın ait olduğu, çalışma alanına göre yol; örneğin /app, /services/billing ya da kök için /. Parça bu kapsamla iletilir.
• title: hafıza kaydının başlığı, kuralın adı ya da becerinin adı.
• summary: paket listesinde gösterilen, gövdeden ayrı tek satırlık açıklama.
• body: eksiksiz Markdown içeriği. Çalışma alanınıza hiçbir dönüşüm uygulanmadan aynen bu yazılır.

Her parça kendi yolunu belirttiği için kalıp, yapısı gereği yola bağlıdır. Paket, bir yere yerleştirilmesi gereken tek bir belge değildir; nereye gideceğini zaten bilen parçalardan oluşan bir kümedir.

Türe özgü meta veriler

Bazı parçalar, içerik türlerine uyan ek alanlar taşır ve bu alanlar içe aktarmada olduğu gibi korunur.

• Kural parçaları bir kapsam türü (folder, file_type ya da project) ve bir öncelik (high, medium, low) belirler. Bunları belirtmeyen bir kural, orta öncelikli bir proje kuralı olarak içe aktarılır. İçe aktarılan kural ikisini de korur; böylece bir kalıptan gelen yüksek öncelikli bir klasör kuralı, kendi yazdığınız bir kuralla tamamen aynı şekilde öne çıkar.
• Beceri parçaları bir beceri adı ve isteğe bağlı etiketler taşır; tek satırlık özetleri becerinin açıklaması olur. İçe aktarmada beceri ayrıca pattern:<slug> ile etiketlenir; böylece bir kalıbın getirdiği tüm becerileri tek grup olarak bulabilirsiniz. İçe aktarmadan sonra beceri, çalışma alanındaki diğer beceriler gibi bulunabilir ve adıyla çağrılabilir.
• Hafıza parçaları ek meta veri gerektirmez; gövde ve yol yeterlidir.

Kural parçaları ayrıca bir otomatik denetim modu (advisory ya da strict) taşır ve elle kopyalanan sürüm her kuralı bunlardan biriyle etiketler. İçe aktarma bu modu taşımaz: içe aktarılan bir kural, katalogda nasıl etiketlenmiş olursa olsun, bağlamla birlikte gelen tavsiye niteliğinde bir kural olarak gelir. Bir düzenlemeyi engellemek için, her kuralda olduğu gibi, bir kişinin onayladığı çalıştırılabilir bir kısıt gerekir; ayrıntılar Güvenlik bariyeri olarak kurallar sayfasında. Böylece engelleme, bir kataloğun açtığı bir şey değil, ekibinizden birinin verdiği bir karar olarak kalır.

Kapsam, öncelik ve otomatik denetimin temel anlamı için Temel kavramlar sayfasına bakın.

Sayılar ve yollar türetilir

Bir kalıp kendi özetini asla elle tutmaz. Her katalog sayfasında ve paketin README dosyasında görünen "4 Rules, 2 Memories, 1 Skill" satırı ile hedef yol listesi parçalardan hesaplanır. Bu sayede gösterilen içerik, paketin gerçekte içerdiğinden asla sapamaz. Bir kalıba kural eklediğinizde sayısı kendiliğinden güncellenir.

Sürümleme ve güncellik

Her kalıp sürümlenir ve tarihlenir; böylece neyi benimsediğinizi ve en son ne zaman değiştiğini bilirsiniz:

• version, 1.0.1 gibi bir gösterim sürümüdür. Katalog sayfasında ve içe aktarma önizlemesinde gösterilir. İçe aktarma token'ı bunu taşımaz: ::pathrule:package:<slug> her zaman istemcinizle birlikte gelen sürümü ifade eder.
• updatedAt, son içerik değişikliğinin tarihidir. Katalog sayfasındaki "Updated" tarihi ve sitemap'teki son değişiklik tarihi budur.
• changelog, sürümler arasında nelerin değiştiğini kaydeden, en yenisi başta olacak şekilde dizilmiş, okunabilir girdilerden oluşan bir listedir. Katalogdaki her kalıpta bulunur ve açık pakette okunabilir.

Sürümleme önemlidir, çünkü içe aktarma tek seferlik bir başlangıç içeriğidir (bkz. Bir kalıbı içe aktarma). Sizdeki kopya siz farkına varmadan değişmez; Pathrule hangi sürümü içe aktardığınızı izlemez ve daha yeni bir sürüm yayımlandığında size bildirmez. Katalog sayfasındaki sürümü ve güncelleme tarihini içe aktardığınız zamanla karşılaştırın, nelerin değiştiğini görmek için de değişiklik günlüğünü okuyun. Daha yeni bir sürümü nasıl alacağınız Bir kalıbı içe aktarma sayfasında anlatılıyor.

Gösterim meta verileri

Parçaların yanı sıra bir kalıp, kataloğun onu sunmak için ihtiyaç duyduklarını da taşır: bir ad, tek satırlık bir slogan, daha uzun bir açıklama, bir kategori (Framework, Frontend, Backend, Billing, Infra, Workflow, AI ve Security'den biri) ve bir simge. Katalogdaki her kalıp ayrıca çözdüğü sorunu, hangi kitle için hazırlandığını ve asistanınızın yapmasını engellediği hataların listesini de açıklar. Katalog sayfası bu üçünü "Why this pattern" başlığı altında gösterir.

Eşleştirme meta verileri

Bir kalıp, hangi tür projeye uyduğunu bir appliesTo bloğunda tanımlayabilir: ilgili yollar, stack etiketleri (örneğin nextjs, react) ve bağımlılık adları. Katalogdaki her kalıp bu bloğu tanımlar. Web kataloğu arama için stack etiketlerini kullanır. İçe aktarma önizlemesi aynı bloğu asistanınıza verir; asistan bir şey yazmadan önce bunu projenizin dizin ağacı ve stack'iyle karşılaştırır, kalıp uymuyor gibi görünürse sizden onay ister.

Açık paket

Kataloğun arkasında tek bir açık paket vardır: npm'de Apache-2.0 lisansıyla yayımlanan @pathrule/patterns. Paket saf ve serileştirilebilirdir: kalıp tanımlarını, türlerini ve birkaç yardımcı fonksiyonu içerir; hiçbir arayüz ya da bulut koduna bağımlılığı yoktur. Bu sayede düz veri olarak okunabilir kalır ve her yüzey birebir aynı paketleri kullanır.

Kalıp eklemek, o pakete kaydedilen tek bir yeni girdi demektir. Paket tek doğruluk kaynağı olduğu için web sitesi kataloğu, içe aktarma araçları ve Markdown görünümleri aynı içeriği gösterir. Pathrule MCP sunucusu paketin kendi kopyasını taşır; yeni yayımlanan bir kalıbın, ancak çalıştırdığınız Pathrule sürümü onu içerdiğinde içe aktarılabilir hale gelmesinin nedeni budur.

Sırada ne okumalı

• Bir kalıbı içe aktarma, bir paketin çalışma alanınıza nasıl yazıldığını ve nasıl kaldırılacağını gösterir.
• Kalıplara genel bakış, atladıysanız konunun genel resmini sunar.
• Kural yazma ve Beceri yazma, parça türlerini ayrıntılı olarak ele alır.