Belgeleme ile Sorgula

Matt Pocock'ın grill-with-docs projesinden türetilmiştir (MIT, © 2026 Matt Pocock). Matt'in mülakat disiplini + belgeler tarafından çıpalaşan sorgulama kuralları MIT altında aynen korunmuştur. Bu repodaki eklentiler: 3 stdlib doğrulayıcısı (CONTEXT.md linter, ADR scanner, glossary↔code tutarlılık kontrolü), her biri 7+ yetkili kaynağa atıfta bulunan 3 derinlemesine referans, cs-grill-with-docs ajanı, /cs:grill-with-docs komutu. Bkz. aşağıdaki Sarmalayıcı eklentiler.

Bu planın her yönü hakkında yoğun bir şekilde beni sorgula, ta ki ortak bir anlayışa ulaşana kadar. Tasarım ağacının her dalını adım adım gez, kararlar arasındaki bağımlılıkları birbir adım adım çöz. Her soru için, önerilen cevabını ver.

Soruları birer birer sor, her soruda devam etmeden önce geribildirim bekle.

Eğer bir soru kod tabanı keşfedilerek cevaplanabiliyorsa, bunun yerine kod tabanını keşfet.

Etki alanı farkındalığı

Kod tabanı keşfi sırasında, mevcut belgeleri de ara:

Dosya yapısı

Çoğu repoda tek bir context vardır:

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

Kök dizinde bir CONTEXT-MAP.md varsa, repoda birden fazla context vardır. Harita, her birinin nerede yaşadığını gösterir:

/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← sistem genelinde kararlar
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← context'e özgü kararlar
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/

Dosyaları tembel yarat — sadece yazacak birşey olduğunda. Eğer CONTEXT.md yoksa, ilk terim çözüldüğünde yarat. Eğer docs/adr/ yoksa, ilk ADR gerektiğinde yarat.

Oturum sırasında

Glossary'ye karşı sorgula

Kullanıcı CONTEXT.md içindeki mevcut dille çakışan bir terim kullandığında, bunu hemen fark et. "Glossary'niz 'cancellation'u X olarak tanımlar, ancak siz Y anlamına geliyormuş gibi görünüyorsunuz — hangisi doğru?"

Belirsiz dili keskinleştir

Kullanıcı belirsiz veya aşırı yüklü terimler kullandığında, kesin bir kanonik terim öner. "Siz 'account' diyorsunuz — Customer mi yoksa User mi demek istiyorsunuz? Bunlar farklı şeyler."

Somut senaryoları tartış

Alan ilişkileri tartışılırken, bunları belirli senaryolarla test et. Kenar durumları araştıran ve kullanıcıyı kavramlar arasındaki sınırlar hakkında kesin olmaya zorlayan senaryolar icat et.

Kodla çapraz referans

Kullanıcı bir şeyin nasıl çalıştığını söylediğinde, kodun buna uyup uymadığını kontrol et. Çelişki bulursan, bunu ortaya çıkar: "Kodunuz tüm Order'ları iptal eder, ancak siz az önce kısmi iptali mümkün olduğunu söylediniz — hangisi doğru?"

CONTEXT.md'yi satır içinde güncelle

Bir terim çözüldüğünde, hemen orada CONTEXT.md'yi güncelle. Bunları toplamayın — çıktığında yakala. CONTEXT-FORMAT.md içindeki formatı kullan.

CONTEXT.md uygulama ayrıntılarından tamamen arınmış olmalıdır. CONTEXT.md'yi bir spec, taslak pad veya uygulama kararları deposu olarak değerlendirme. Sadece bir glossary'dir.

ADR'leri tutumlu sun

Yalnızca üçünün hepsi doğru olduğunda ADR oluşturmayı öner:

Tersine çevirmesi zor — fikrinizi sonra değiştirmenin maliyeti anlamlıdır
Context olmadan şaşırtıcı — gelecekteki bir okuyucu "neden bu şekilde yaptılar?" diye merak edecektir
Gerçek bir ödünleşimin sonucu — gerçek alternatifler vardı ve belirli nedenlerle birini seçtiniz

Üçünden herhangi biri eksikse, ADR'yi atla. ADR-FORMAT.md içindeki formatı kullan.

Sarmalayıcı Eklentiler

Aşağıdaki eklentiler Matt'in upstream skill'inin parçası değildir. Upstream kurallarını, mülakat döngüsüyle doğal olarak eşleşen belirleyici, stdlib-only doğrulayıcılara operasyonelleştirirler.

İş Akışı (sarmalayıcı araçlarla)

Ön kontrol (ilk sorudan önce):
- Eğer CONTEXT.md varsa scripts/context_md_linter.py CONTEXT.md çalıştır — glossary'nin iyi biçimlendirilmiş olduğunu sorgulamadan önce onayla.
- Eğer docs/adr/ varsa scripts/adr_scanner.py docs/adr/ çalıştır — numaralandırma boşluklarını, hatalı biçimlendirilmiş ADR'leri, durum-frontmatter tutarsızlıklarını ortaya çıkar.
- scripts/glossary_code_consistency.py --context CONTEXT.md --code src/ çalıştır — tanımlanan ama kullanılmayan terimleri (ölü glossary) ve kod-sadece ortak isimleri işaretler. Bu işaretleri başlangıç sorgulama soruları olarak kullan.
Oturum sırasında (Matt'in kuralları uygulanır):
- Tur başına bir soru, derinlik-birinci olarak yürü.
- Bir terim keskinleştirildiğinde: CONTEXT.md'yi hemen düzenle; düzenleme yapısal ise context_md_linter.py'i yeniden çalıştır.
- Bir ADR gerektiğinde: docs/adr/ altında yaz; numaralandırmayı doğrulamak için adr_scanner.py'i yeniden çalıştır.
Kapanış:
- Son glossary_code_consistency.py çalıştırması hiçbir yeni yetim terimin tanıtılmadığını doğrulamak için.
- Özetle: eklenen/iyileştirilen terimler, yazılan ADR'ler, tartışılan senaryolar, açık maddeler.

Araçlar (stdlib-only)

Araç	Tek satırlık rol
`scripts/context_md_linter.py`	`CONTEXT.md`'yi CONTEXT-FORMAT.md yapısına karşı doğrula. Kural başına PASS/WARN/FAIL.
`scripts/adr_scanner.py`	`docs/adr/` içinde yürü, `NNNN-slug.md` deseni, numaralandırma bütünlüğü, gövde tamlığını kontrol et.
`scripts/glossary_code_consistency.py`	`CONTEXT.md` içindeki kalın terimleri kod tabanı kullanımına karşı çapraz referans al. Ölü glossary + kod-sadece ortak isimleri işaretle.

Referanslar (her kuralın arkasında alıntılar)

references/ubiquitous_language.md — neden bir glossary kaynak kontrolde olmalı (Evans, Vernon, Khononov, Wlaschin, Brandolini, Avram & Marinescu, Fowler)
references/adr_practice.md — ADR ne zaman işine yarar (Nygard, Tyree & Akerman, Zimmermann Y-statements, MADR, ThoughtWorks Radar, adr-tools, Backstage)
references/context_md_as_artifact.md — CONTEXT.md yaşayan bir yapı olarak (Khononov dil kayması, Kernighan adlandırma, BoundedContext bliki, Confluent veri sözleşmeleri, Brandolini EventStorming glossary)

Yardımcı

Agent: cs-grill-with-docs (bkz. ../../agents/cs-grill-with-docs.md)
Command: /cs:grill-with-docs (bkz. ../../commands/cs-grill-with-docs.md)

Sürüm: 1.0.0 Türetilmiş: Matt Pocock'ın grill-with-docs (MIT) + bu repoya ait sarmalayıcı

grill-with-docs

Bu skill hakkında