Bir Klasör Adı Bir Proje Kimliği Değildir

Bir klasör yolu bir rotadır. Bir araca projenin şu anda nerede bulunduğunu söyler. Proje kimliği ise farklıdır.

Kimlik şu yaygın değişikliklere karşı hayatta kalmalıdır:

  • Dizini yeniden adlandırmak
  • Projeyi makineler arasında taşımak
  • Repoyu yeni bir yola klonlamak
  • Aynı projenin birden fazla checkout'unu kullanmak

Eğer kimlik yola bağlıysa, bu işlemler riskli hale gelir. Yol çalışabilir ancak projenin aynı olduğunu kanıtlamada yetersiz kalır. Bu da onu durum (state) saklamak için kötü bir anahtar yapar.

Bunu çözmek için APC ve APX ile ayrıştırılmış bir tasarım kullanıyorum.

APC proje sözleşmesini (contract) yönetir. Depoda (repository) bulunur. APX çalışma zamanı durumunu (runtime state) yönetir. Deponun dışında bulunur.

APC, kararlı bir çapa oluşturmak için belirli dosyalar kullanır:

  • Kök sözleşme için AGENTS.md
  • Proje meta verileri için .apc/project.json
  • Ajan tanımları için .apc/agents/*.md
  • MCP ipuçları için .apc/mcps.json

.apc/project.json dosyası çok küçüktür. Bir isim ve kararlı bir ID içerir. Büyük bir yapılandırma dosyası değil, bir işarettir.

APX, canlı bir checkout'u kalıcı bir kayda bağlamak için bu dosyayı kullanır. Yollar, APX'in projeyi bulmasına yardımcı olur. Meta veriler ise APX'in projeyi bulduktan sonra onu kararlı tutmasına yardımcı olur.

Bu tasarım repoyu temiz tutar. Oturum günlükleri ve mesaj geçmişi gibi çalışma zamanı verileri APX depolamasında kalır. Git geçmişinizi kirletmezler.

Yollara güvendiğinizde şu sorunlarla karşılaşırsınız:

  • Yollar değişir
  • Durum bozulur
  • Araç yanlış tahminlerde bulunur
  • Geliştirme yapmak yerine isimleri hata ayıklamakla vakit harcarsınız

Kararlı bir kimlik bu gürültüyü ortadan kaldırır. Kod incelemelerini kolaylaştırır. Diff'lerinizde kazara oluşan çalışma zamanı çıktıları yerine proje gerçeklerini görürsünüz.

Sınır basittir:

  • AGENTS.md: projenin bekledikleri
  • .apc/project.json: projenin ne olduğu
  • ~/.apx/: üzerinde çalışırken neler olduğu

Bir projenin tek bir kararlı çapaya ihtiyacı vardır. Klasör yolu çok değişkendir. Çalışma zamanı çok gürültülüdür. Bir repo sözleşmesi artı bir meta veri dosyası doğru boyuttur.

Source: https://dev.to/tecnomanu/a-folder-name-is-not-a-project-identity-4eca

Optional learning community: https://t.me/GyaanSetuAi