Kod Tabanı Mimarisini İyileştir

Mimari friksiyon yüzeye çıkar ve derinleştirme fırsatları öner — sığ modülleri derin modüllere dönüştüren refaktorlar. Amaç, test edilebilirlik ve AI-navigasyonudur.

Sözlük

Bu terimleri her öneride tam olarak kullan. Tutarlı dil önemlidir — "component," "service," "API" veya "boundary" gibi başka terimlere kaymayın. Tam tanımlar LANGUAGE.md içindedir.

• Modül — bir arayüzü ve uygulaması olan herhangi bir şey (function, class, package, slice).
• Arayüz — modülü kullanmak için bir çağıranın bilmesi gereken her şey: types, invariants, error modes, ordering, config. Sadece type signature değil.
• Uygulama — içerideki kod.
• Derinlik — arayüzde leverage: az bir arayüzün arkasında çok davranış. Derin = yüksek leverage. Sığ = arayüz uygulamaya neredeyse eşit derecede karmaşık.
• Seam — bir arayüzün yaşadığı yer; yerinde düzenleme yapmadan davranış değiştirilebilecek bir yer. (Bunu kullan, "boundary" değil.)
• Adapter — bir seam'de bir arayüzü tatmin eden somut bir şey.
• Leverage — çağıranların derinlikten elde ettikleri şey.
• Lokality — bakıcıların derinlikten elde ettikleri şey: değişiklik, hatalar, bilgi bir yerde toplanmış.

Temel prensipler (LANGUAGE.md içinde tam listeyi gör):

• Silme testi: modülü silmeyi hayal et. Eğer karmaşıklık ortadan kalkarsa, pass-through'tu. Eğer karmaşıklık N çağıranı arasında yeniden ortaya çıkarsa, değerini kanıtlıyordu.
• Arayüz test yüzeyidir.
• Bir adapter = varsayımsal seam. İki adapter = gerçek seam.

Bu beceri projenin domain modelinden bilgi alır. Domain dili iyi seamlere adlar verir; ADR'ler bu becerinin yeniden tartışmaması gereken kararları kaydeder.

Süreç

1. Keşfet

Önce projenin domain sözlüğünü ve dokunduğun alandaki ADR'leri oku.

Sonra subagent_type=Explore ile Agent toolunu kullan ve kod tabanında yürü. Katı heuristikleri takip etme — organik olarak keşfet ve friksiyon yaşadığın yerleri not et:

• Bir kavramı anlamak hangi yerlerde birçok küçük modül arasında zıplama gerektiriyor?
• Modüller sığ olan yerleri nerede — arayüz uygulamaya neredeyse eşit derecede karmaşık?
• Pure functionlar sadece test edilebilirlik için nerede çıkarılmış ama gerçek hatalar nasıl çağrıldıklarında gizlenmiş (yoksa lokality)?
• Sıkı bağlı modüller seamleri boyunca nerede sızıyor?
• Kod tabanının hangi parçaları test edilmemiş veya mevcut arayüzleri aracılığıyla test edilmesi zor?

Sığ olduğundan şüphelendiğin herhangi bir şeye silme testini uygula: silmek karmaşıklığı konsantre eder mi, yoksa sadece taşır mı? Bir "evet, konsantre eder" istediğin sinyaldir.

2. Adayları HTML rapor olarak sun

İşletim sistemi geçici dizinine kendini içeren bir HTML dosyası yaz, böylece hiçbir şey repo'ya inmez. Geçici dizini $TMPDIR den çöz, %TEMP% (Windows'ta) ile geri dön, ve <tmpdir>/architecture-review-<timestamp>.html ye yaz, böylece her çalıştırma yeni bir dosya alır. Kullanıcı için aç — Linux'ta xdg-open <path>, macOS'ta open <path>, Windows'ta start <path> — ve mutlak yolu söyle.

Rapor layout ve styling için Tailwind CDN aracılığıyla ve bir grafik/akış/dizi güvenilir bir şekilde yapıyı ilettiğinde diyagramlar için Mermaid CDN aracılığıyla kullanır. Mermaid'i el yapımı CSS/SVG görselleriyle karıştır — ilişkiler grafik şeklinde olduğunda Mermaid'i (call graphs, dependencies, sequences) ve daha çok editoryal bir şey istediğinde el yapımı divs/SVG'yi (mass diagrams, cross-sections, collapse animations) kullan. Her adayın bir before/after görselleştirmesi vardır. Görsel ol.

Her aday için, öncekiyle aynı şablon ama bir kart olarak render edilmiş:

• Dosyalar — hangi dosyalar/modüller ilgili
• Problem — mevcut mimarinin neden friksiyon yarattığı
• Çözüm — derinleştirmenin ne değişeceğinin düz İngilizce açıklaması
• Faydalar — lokality ve leverage açısından açıklanmış, ve testler nasıl iyileşecek
• Before / After diyagramı — yan yana, el yapımı, sığlığı ve derinleştirmeyi gösteren
• Tavsiye gücü — Strong, Worth exploring, Speculative den biri, badge olarak render edilmiş

Raporu En İyi Tavsiye bölümüyle sonlandır: hangi adayı ilk olarak ele alacağın ve neden.

CONTEXT.md sözlüğünü domain için ve LANGUAGE.md sözlüğünü mimari için kullan. Eğer CONTEXT.md "Order" tanımlarsa, "Order intake modülü" hakkında konuş — "FooBarHandler" değil, ve "Order service" değil.

ADR çatışmaları: eğer bir aday mevcut bir ADR'ye ters düşerse, sadece frikiyon ADR'yi yeniden açmayı garanti edecek kadar gerçek olduğunda yüzeye çıkar. Kart içinde net bir şekilde işaretle (örn. bir uyarı callout: "ADR-0007 ile ters düşer — ama çünkü yeniden açmaya değer…"). Bir ADR'nin yasakladığı her teorik refaktörü listeleme.

Tam HTML iskeleti, diyagram desenleri ve styling rehberi için HTML-REPORT.md ye bak.

Henüz arayüzler önerme. Dosya yazıldıktan sonra kullanıcıya sor: "Bunlardan hangisini keşfetmek istersiniz?"

3. Sorgulama döngüsü

Kullanıcı bir aday seçtikten sonra, sorgulama konuşmasına dal. Tasarım ağacında onlarla yürü — kısıtlamalar, bağımlılıklar, derinleştirilen modülün şekli, seamde neler yaşıyor, hangi testler hayatta kalıyor.

Kararlar kristalleştikçe yan etkiler satır içi olarak gerçekleşir:

• CONTEXT.md içinde olmayan bir kavramdan sonra derinleştirilen modülü adlandırıyorsun? Terimi CONTEXT.md ye ekle — /grill-with-docs ile aynı disiplin (CONTEXT-FORMAT.md ye bak). Dosya yoksa lazy yaratın.
• Konuşma sırasında bulanık bir terimi mi keskinleştiriyorsun? CONTEXT.md yi hemen orada güncelleyin.
• Kullanıcı adayı load-bearing bir sebeple mi reddediyor? Bir ADR teklif et, şu şekilde çerçeveli: "Bunu bir ADR olarak kaydetmemi ister misiniz ki gelecek mimari incelemeler tekrar önermesin?" Sadece sebep gelecek bir explorer tarafından aynı şeyi yeniden önermeyi önlemek için gerçekten gerekli olduğunda teklif et — efemeral sebepleri ("şu an değer") ve kendi kendini belleği olanları ("kendi kendini belleği") atla. ADR-FORMAT.md ye bak.
• Derinleştirilen modül için alternatif arayüzleri keşfetmek ister misiniz? INTERFACE-DESIGN.md ye bak.