02ProjelerProje 02 / 06
Bilgi Mimarisi
Bloated tek AGENTS.md'den yönlendirici dosya + konu dokümanları + per-module ARCHITECTURE.md'ye geçiş. Bilgi görünürlüğü boşluğunu kapatın.
- Okuma
- 4 dakika
- Yayın
- 19 Mayıs 2026
Kodu al
git clone https://github.com/komunite/harness-docs && cd harness-docs/projeler/02/starter
Pazartesi sabahı, aynı reponun iki kopyası açık. Soldakinde AGENTS.md 248 satır: proje tarihi, eski Flask kalıntıları, kısayol aliaslar, "bir gün eklenecek" listeleri, ortada bir yere gömülmüş bir güvenlik kuralı. Sağdakinde 52 satırlık bir yönlendirici, üç konu dokümanı, ve src/api/ARCHITECTURE.md. Aynı kod tabanı, aynı Makefile, aynı testler. Sol kopyaya yeni bir ajan oturumu açtığında token bütçesinin yarısı daha ilk dosyada eriyor, sağ kopyada ajan görevin tipine göre tek bir konu dosyasına gidiyor.
Düzenek Mühendisliği (Harness Engineering) müfredatının bu projesi, Ders 03 ve Ders 04'ün önerisini elle hissedeceğin tek harekete indiriyor: şişmiş tek dosyadan yönlendirici dosya + konu dokümanlarına geçiş.
Bu projede ne öğreneceksin
- Bilgi Görünürlüğü Boşluğu'nun (Knowledge Visibility Gap) bir reponun içinde nasıl somut göründüğünü.
- Bir
AGENTS.mddosyasının neden 248 satıra şiştiğini ve aynı bilgi kümesinin 52 satırlık bir router'a nasıl indiğini. - "Progressive disclosure" yapısının pratikte ne demek olduğunu: kök dosya yalnızca tanım + sıkı kısıtlar + harita, ayrıntı
docs/altında ve modül-yerelARCHITECTURE.md'lerde yaşar. - Soğuk başlangıç testinin (Ders 03) yapı üzerinden nasıl yeşile döndüğünü.
- Sıkı kısıtların görünürlüğünün (örneğin "Authorization header asla loglanmaz" kuralının) neden ortadaki bir satırdan başa taşındığında ihlal oranının düştüğünü.
Yapı
projeler/02/
├── starter/
│ ├── AGENTS.md # 248 satır — şişmiş tek dosya
│ ├── app.py
│ ├── Makefile
│ ├── README.md
│ ├── pyproject.toml
│ ├── requirements.txt
│ └── tests/
└── solution/
├── AGENTS.md # 52 satır — yönlendirici (router)
├── docs/
│ ├── api-patterns.md
│ ├── database-rules.md
│ └── security.md
├── src/
│ └── api/
│ └── ARCHITECTURE.md
├── app.py # starter ile aynı
├── Makefile
├── README.md
├── pyproject.toml
├── requirements.txt
└── tests/Solution dizinindeki app.py, Makefile, testler: hepsi starter ile aynı. Değişen tek şey bilgi mimarisi.
starter ile solution arasındaki fark
| Eksen | projeler/02/starter/AGENTS.md | projeler/02/solution/AGENTS.md |
|---|---|---|
| Satır sayısı | 248 | 52 |
| Rol | ansiklopedi | yönlendirici (router) |
| Sıkı kısıtların konumu | dosya boyunca dağılmış | başta, beş madde, ayrılmış blok |
| Tarih / kısayollar / "bir gün" listeleri | var (≈ 80 satır) | yok (silinmiş veya konu dokümanına gitmiş) |
| Konu dokümanlarına yönlendirme | yok | var, görev tipiyle eşleşmiş |
Starter dosyasında "Tüm SQL sorguları parametreli olmalıdır" kuralı 40. satıra gömülmüştür. "Authorization header asla loglanmaz" kuralı 74. satırda, "Tarih" başlığının altında, eski Flask kalıntıları ve aliaslarla aynı dosya içinde. Liu et al. 2023'ün Lost in the Middle (yeni sekmede açılır) bulgusu tam burayı işaretliyor: U-şeklindeki performans eğrisi ortayı kör eder. Solution'da aynı iki kural, dosyanın ilk yirmi satırı içinde, "Sıkı kısıtlar (ihlal edilemez)" başlığı altında listelenmiş durumda.
Aynı zamanda solution bilgiyi silmiyor, taşıyor:
- Endpoint stili, status code haritası, validation kuralları →
projeler/02/solution/docs/api-patterns.md - SQLite kullanımı, parametreli sorgular, transaction'lar, migration →
projeler/02/solution/docs/database-rules.md - Bearer auth, secret yönetimi, token rotation, CORS, rate limiting →
projeler/02/solution/docs/security.md - API modülünün iç düzeni (
routes.py,models.py,dependencies.pyhedef düzeni) →projeler/02/solution/src/api/ARCHITECTURE.md
Konu dokümanlarının toplam satırı starter'dan daha uzun olabilir. Amaç sıkıştırma değil, doğru yerleştirme. Ajan görevine göre docs/security.md'yi yükler, docs/api-patterns.md'yi yüklemez, bağlam bütçesi just-in-time harcanır.
Adım adım
- Klonla.
git clone https://github.com/komunite/harness-docs cd projeler/02/starter AGENTS.md'yi baştan sona oku. Tüm 248 satırı. Bunu bilinçli yap. İlk yarıda dikkatin dağılacak, ortada bir yere geldiğinde ekrandan kaymaya başlayacaksın. Bu bir hata değil, gözlemin kendisi.- Soru 1: "Tüm SQL sorguları parametreli olmalıdır" kuralını okuduktan ne kadar sonra unuttun?
- Soru 2: "Authorization header asla loglanmaz" kuralını ilk okuyuşta yakalayabildin mi yoksa geri dönmek zorunda mı kaldın?
- Soru 3: "Test isimleri davranışı tanımlamalıdır" kuralı ile "Lisans belirsiz" notu aynı dosyada, aynı seviyede madde olarak duruyor. Hangisi ihlal edilemez, hangisi gevşek? Dosya sana bunu söylüyor mu?
- Solution'a geç.
cd ../solution - Router'ı oku:
projeler/02/solution/AGENTS.md, 52 satır. Aşağıdaki beş bölümün başlığına dikkat et: Proje (tek paragraf), Sıkı kısıtlar (beş madde), Hızlı başlangıç, Konu dokümanları (görev tipi → dosya eşlemesi), Bu dosyanın disiplini. Dosya kendi bakım kuralını da içeriyor: üst sınır iki yüz satır, hedef yüz satır civarı. - Konu dokümanlarını sırayla oku. Her birinin başında "Ne zaman oku" cümlesi ve "Sıkı kısıtlar" bölümü var. "Bu dosyada olmayan konular" listesi sınırları çiziyor.
projeler/02/solution/docs/api-patterns.mdprojeler/02/solution/docs/database-rules.mdprojeler/02/solution/docs/security.mdprojeler/02/solution/src/api/ARCHITECTURE.md
- Aynı görevi iki kopyaya ver. "Yeni bir
/notes/{nid}DELETE endpoint'i ekle" gibi küçük bir görev seç. Starter kopyasında ajan dosyayı baştan sona tarar, solution kopyasındaAGENTS.md→docs/api-patterns.mdrotasını izler. Token sayımları ve hata oranlarını not et.
Beklenen sonuçlar
- Soğuk başlangıç testi yeşil. Ders 03'ün beş sorusu (proje nedir, nasıl çalıştırılır, nasıl doğrulanır, hangi kurallar ihlal edilemez, detaya inmek için nereye bakılır) solution'ın
AGENTS.mddosyasından, başka hiçbir yere bakmadan cevaplanabilir. Solution dosyasının son bölümü ("Soğuk başlangıç testi") bu sözleşmeyi açıkça yazılı tutuyor. - Sıkı kısıtların görünürlüğü artar. "Parametreli sorgu" ve "Authorization loglanmaz" kuralları artık dosyanın ilk on satırında, ayrılmış bir blokta. Liu et al. 2023'ün U-şekilli eğrisinin baş-uç avantajına yerleşmiş durumdalar.
- Bağlam bütçesi just-in-time harcanır. Bir SQL refactoru sırasında ajan
security.md'yi yüklemez, bir token rotation görevindedatabase-rules.md'yi yüklemez. Anthropic'in "Effective Context Engineering" yazısının önerdiği "smallest possible set of high-signal tokens" prensibi mimari seviyede uygulanmış olur. - Öncelik karmaşası çözülür. Stil tercihi (
api-patterns.md) ile güvenlik kuralı (security.md) artık aynı dosyada yan yana iki tire değil, fiziksel olarak ayrılmış iki dosyadalar. Hangisinin müzakere edilebilir olduğu, dosyanın yerinden okunur. - Bakım maliyeti düşer. Yeni bir kural eklerken karar, "hangi konu dokümanına ait?" sorusuna döner. Router şişmez, konu dokümanı kendi sınırı içinde büyür.
Yerel çalıştırma
cd projeler/02/solution
make setup
make checkmake check testleri koşturur ve "ok" basar. Aynı komut projeler/02/starter içinde de yeşil döner, doğrulama sözleşmesi her iki tarafta aynı. Değişen tek şey bilginin yeri. Eğer Python 3.11+ kurulu değilse, starter'ın AGENTS.md'sindeki "Geliştirme ortamı" bölümünde gerekçesi yazılı, solution'da aynı bilgi AGENTS.md'nin "Hızlı başlangıç" satırında özet halinde.
İlgili dersler
- Ders 03, Repo: Hakikat Kaynağı: repoda olmayan bilgi ajan için yoktur. Bu projenin solution'ı dört ilkenin (kodun yanında, standardize giriş, minimum ama tam, kodla güncel) elle tutulur uygulamasıdır.
- Ders 04: Şişmiş Talimat Sendromu: tek büyük talimat dosyası neden çürür. Çözüm "kısalt" değil, "rolünü değiştir": ansiklopediden router'a.
Sıradaki proje
- Proje 03: Çok Oturumlu Süreklilik: bilgi mimarisi yerinde olduğuna göre, bir sonraki adım: oturumlar arası
progress.mdvedecisions.mdile sürekliliği kurmak. Router yapısı oradadocs/yerinestate/dizinine yönlendirme kazanır. Aynı prensip, farklı eksen.