Claude Code veya Cursor'un monorepo mimarisini bozması nasıl önlenir?
Ajana kıdemli bir mühendisle aynı bağlamı verip veremediğinize bağlı: makine-okunur mimari sözleşmeler (AGENTS.md artı her paketin sınırlarını kaydeden .ai/ ayna dokümanları), .agents/skills/ altındaki görev playbook'ları, ajanın grep tahmini yerine yapılandırılmış araçlarla repoyu incelemesini sağlayan bir MCP sunucusu (@supastack/mcp) ve incelemeden önce geçilmesi zorunlu, kimlik bilgisi gerektirmeyen 693+ testten oluşan deterministik bir test gate'i. supastack dört katmanı da önceden bağlı sunar.
Her ajan kullanıcısının çarptığı 'on bin satır duvarı'
Claude Code veya Cursor ile ilk 5.000 satır sihir gibi gelir. Sonra repo, ajanın artık bütününü göremeyeceği kadar büyür — ve hatalar dizgi hatasına benzememeye başlar: iki paket ötede var olan bir yardımcıyı yeniden yazar; workspaceId'yi unutan bir sorgu ekler; bir hafta sonunuzu alan idempotency kontrolünü silerek webhook işleyicisini 'düzeltir'.
Bu bir yetenek değil, bağlam hatasıdır. Kıdemli mühendis o çatlaklara basmaz çünkü mimariyi kafasında taşır: hangi paket neye sahip, hangi değişmezler taşıyıcı, testler neyi vaat eder. Ajan basar çünkü kimse bunları onun için yazmamıştır.
Birinci katman: ajanların okuyabildiği yazılı bir sözleşme
supastack, ajan bağlamını birinci sınıf bir eser olarak ele alır. Repo kökündeki AGENTS.md mimari sözleşmeyi kaydeder — her paketin sahibi olduğu şey, test gate'inin gerektirdikleri, yasak desenler. .ai/PROJECT_CONTEXT.md mevcut durumu ve kararların gerekçesini kaydeder; dosya başına ayna dokümanları bağlamın bir wiki'de çürümek yerine kodla birlikte taşınmasını sağlar.
Üstte .agents/skills/ altında ~29 görev playbook'u vardır — web özelliği ekleme, veritabanı şemasını değiştirme, ödeme sağlayıcısı bağlama, değişikliği doğrulama — böylece ajan doğaçlamak yerine reponun kendi prosedürlerini çalıştırır.
your-saas/
AGENTS.md architecture contract every agent reads first
.ai/
PROJECT_CONTEXT.md current state, decisions, ship status
apps/web/src/... per-file mirror docs that travel with code
.agents/skills/ ~29 task playbooks for agent workflows
packages/mcp/ MCP server: structured repo access for agentsİkinci katman: @supastack/mcp ajanlara yapılandırılmış repo erişimi verir
Araçsız bir ajanın 700 dosyalık bir monorepo'yu keşfetmesinin tek yolu: grep atmak, yanlış dosyaları okumak ve tahmin yürütmek. @supastack/mcp, @modelcontextprotocol/sdk ve @supastack/agents araç çalışma zamanı üzerine kurulu gerçek bir Model Context Protocol sunucusudur — yapılandırılmış araçlar, dokümantasyon kaynakları ve hazır prompt'lar aracılığıyla repoyu MCP uyumlu ajanlara (Claude Code, Cursor, Devin, Windsurf) açar.
Fark, hata oranında görünür. 'Bu paket ne ihraç ediyor' ya da 'test gate'i ne istiyor' sorularını tipli araçlarla sorabilen bir ajan, rastgele açtığı dosyadan cevap uydurmayı bırakır. AI kodlama ajanları starter kit yazımız aynı iş akışını derleme tarafından anlatıyor.
Üçüncü katman: ajanların geçmek zorunda olduğu deterministik test gate'i
Zorlaması olmayan korkuluklar sadece öneridir. supastack 693+ otomatik testle gelir ve faturalama, kimlik doğrulama, e-posta ve depolama için kimlik bilgisi gerektirmeyen sahte sağlayıcılar içerir; kayıt, ödeme webhook'u, yetki ataması ve ekip davetinden oluşan altın yolun tamamı yerelde saniyeler içinde doğrulanır.
Bir ajanı güvenli kılan döngü basittir: ajan diff'i yazar, gate'i çalıştırır, hatayı okur ve kendini düzeltir — hepsi insan incelemesinden önce olur. Reponun verify-changes skill'i değişiklik türüne göre hangi kontrollerin koşulacağını söyler; böylece 'ajan faturalamayı bozdu', 'ajan kendisi yakaladı'ya dönüşür.
| Hata modu | Korkuluksuz repo | supastack korkuluklarıyla |
|---|---|---|
| Ajan var olan kodu yeniden yazar | İncelemede keşfedilir — belki | AGENTS.md + .ai/ aynalarındaki paket sınırları önceden engeller |
| Tenant kontrolü sessizce silinir | Üretimde patlar | Workspace kuralları yazılı ve test kapsamlı |
| Webhook regresyonu | Ödeme kesintisi olarak ortaya çıkar | İdempotent webhook defteri tekrar testleriyle sabitlenmiş |
| Repo keşfi | Grep ve tahmin | @supastack/mcp araçları + doküman kaynakları |
| Doğrulama | Ajan 'bitti' der | İncelemeden önce 693+ test gate'i zorunlu |
Korkuluklar müşteri işinde neden bileşik getiri sağlar
Bir ajans için hesap doğrudan: her müşteri reposu aynı sözleşmeyi miras alır, böylece yeni projedeki yeni ajan sınırları bozarak öğrenmek yerine ilk saatten üretken olur. 'Ajan hızını satmak' ile 'ajan temizliğini satmak' arasındaki fark budur.
Kitin üç kademesi ajansların gerçek satın alma biçimine karşılık gelir — tek yüzeyli projeler için $199 Starter, tüm yüzeyler ve 3 koltuk için $299 Full Bundle, 10 koltuklu $799 Agency — ve her kademe sınırsız ticari müşteri projesine izin verir. Fiyat sayfasında karşılaştırın.
SSS: Gerçek monorepo'larda AI kodlama ajanları
Ekiplerin üretim kod tabanını ajanlara emanet etmeden önce sorduğu sorular:
- Bu korkuluklar hangi ajanlarla çalışır?, Markdown okuyabilen her ajanla — Claude Code, Cursor, Windsurf, Copilot, Devin. MCP uyumlu istemciler ayrıca
@supastack/mcpüzerinden yapılandırılmış araçlar alır; .ai/ dokümanları ve skill'ler araçtan bağımsızdır. - Sadece AGENTS.md yeterli değil mi?, Yardımcı olur ama tek dosya çürür. Ayakta kalan kombinasyon sözleşme (AGENTS.md) + bellek (.ai/ aynaları) + prosedürler (Agent Skill'ler) + doğrulama (test gate'i) — bir katman eksikse sızar.
- Test süiti gerçekte ne kadar büyük?, 693+ otomatik test; faturalama idempotency'si, oturum doğrulaması, workspace izolasyonu, API anahtarları ve ajan odaklı paketleri kapsar — tümü gerçek kimlik bilgisi olmadan çalışır.
- Bu korkuluklar mevcut bir repoya eklenebilir mi?, Evet — kabaca iki haftalık özenli dokümantasyon artı kendi MCP sunucunuzu kurmayı göze alın. Kit kestirmedir: sözleşme, skill'ler, MCP sunucusu ve testler zaten birbiriyle uyumludur.