Kod Turu

CodeTour dosyaları oluşturun — belirli bir kişiye yönelik, bir kod tabanının adım adım anlatımları ve dosyalar ile satır numaralarına doğrudan bağlantılar. CodeTour dosyaları .tours/ klasöründe yaşar ve VS Code CodeTour uzantısı ile çalışır.

Özet

Harika bir tur bir anlatıdır — belirli bir kişiye ne önemliyse, neden önemliyse ve sonra ne yapacağını anlatan bir hikaye. Yalnızca .tour JSON dosyaları oluşturun. Asla kaynak kodu değiştirmeyin.

Bu Beceriyi Ne Zaman Kullanmalısınız

• Kullanıcı bir kod turu, onboarding turu veya mimari anlatım oluşturmayı isterse
• Kullanıcı "bu PR için tur", "X nasıl çalışıyor", "vibe check", "RCA turu" derse
• Kullanıcı bir katkıda bulunan rehberi, güvenlik incelemesi veya hata araştırması anlatımı isterse
• Dosya/satır çapaları ile yapılandırılmış bir anlatım için herhangi bir istek

Temel İş Akışı

1. Repoyu keşfedin

Hiçbir şey sormadan önce kod tabanını keşfedin:

Paralel olarak: kök dizini listeleyin, README'yi okuyun, config dosyalarını kontrol edin. Sonra: dil(ler)i, framework'leri, proje amacını tanımlayın. Klasör yapısını 1-2 seviye derinliğinde haritala. Giriş noktalarını bul — turdaki her yol gerçek olmalı.

Repoda 5'ten az kaynak dosya varsa, persona fark etmeksizin hızlı derinlik turu oluşturun — derin bir turu garanti etmek için yeterli değil.

2. Niyeti tahmin edin

Bir mesaj yeterli olmalı. Persona, derinlik ve odağı sessizce tahmin edin.

Kullanıcı söylerse	Persona	Derinlik
"bu PR için tur"	pr-reviewer	standart
"X neden kırıldı" / "RCA"	rca-investigator	standart
"onboarding" / "yeni başlayan"	new-joiner	standart
"hızlı tur" / "vibe check"	vibecoder	hızlı
"mimari"	architect	derin
"güvenlik" / "auth incelemesi"	security-reviewer	standart
(niteleyici yok)	new-joiner	standart

Niyet belirsiz olduğunda, new-joiner personası ile standart derinliğe varsayılan olarak ayarlanır — en genel olarak faydalıdır.

3. Gerçek dosyaları okuyun

Her dosya yolu ve satır numarası doğrulanmalıdır. Yanlış satıra işaret eden bir tur, hiç tur olmamaktan daha kötüdür.

4. Turu yazın

.tours/<persona>-<focus>.tour klasörüne kaydedin.

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "Açıklayıcı Başlık — Persona / Amaç",
  "description": "Bu kimin için ve anlatımdan sonra ne anlayacakları.",
  "ref": "<current-branch-or-commit>",
  "steps": []
}

Adım türleri

Tür	Ne zaman kullanılır	Örnek
Content	Giriş/kapanış sadece (maks 2)	{ "title": "Hoşgeldiniz", "description": "..." }
Directory	Bir modüle yönelim	{ "directory": "src/services", "title": "..." }
File + line	Workhorse	{ "file": "src/auth.ts", "line": 42, "title": "..." }
Selection	Bir kod bloğunu vurgula	{ "file": "...", "selection": {...}, "title": "..." }
Pattern	Regex eşleştirme (değişken dosyalar)	{ "file": "...", "pattern": "class App", "title": "..." }
URI	PR, issue, doca bağla	{ "uri": "https://...", "title": "..." }

Adım sayısı

Derinlik	Adımlar	Kullanım alanı
Hızlı	5-8	Vibecoder, hızlı keşif
Standart	9-13	Çoğu persona
Derin	14-18	Architect, RCA

Açıklamaları yazma — SMIG formülü

• S — Durum: Okuyucu neye bakıyor?
• M — Mekanizma: Bu kod nasıl çalışıyor?
• I — İmplication: Bu persona için neden önemli?
• G — Gotcha: Zeki biri ne yanlış anlamış olurdu?

5. Doğrula

• [ ] Her file yolu repo köküne göre (başta / veya ./ yok)
• [ ] Her file var olduğu doğrulanmış
• [ ] Her line dosya okunarak doğrulanmış
• [ ] İlk adım file veya directory çapasına sahip
• [ ] En fazla 2 sadece içerik adımı
• [ ] nextTour ayarlandıysa başka bir turun title ile tam eşleşiyor

Personalar

Persona	Amaç	Kapsanması gereken
Vibecoder	Hızlı vibe al	Giriş noktası, ana modüller. Maks 8 adım.
New joiner	Yapılandırılmış ramp-up	Dizinler, kurulum, iş bağlamı
Bug fixer	Kök neden hızlı	Tetikle -> hata noktaları -> testler
RCA investigator	Neden başarısız oldu	Nedensellik zinciri, gözlemlenebilirlik çapaları
Feature explainer	End-to-end	UI -> API -> backend -> depolama
PR reviewer	Doğru şekilde incele	Değişim hikayesi, değişmezler, riskli alanlar
Architect	Şekil ve mantık	Sınırlar, tradeoff'lar, genişletme noktaları
Security reviewer	Güven sınırları	Auth akışı, doğrulama, gizli yönetimi
Refactorer	Güvenli yeniden yapılandırma	Seams, gizli bağımlılıklar, çıkarma sırası
External contributor	Güvenli katkı	Güvenli alanlar, kurallar, tuzaklar

Anlatı Ark

1. Yönelim — file veya directory adımı (asla sadece content ile ilk adım — VS Code'da boş)
2. Yüksek seviye harita — Ana modülleri gösteren 1-3 directory adımı
3. Temel yol — file/line adımları, turun kalbi
4. Kapanış — okuyucunun artık ne yapabileceği, önerilen follow-up'lar

Anti-Desenler

Anti-desen	Çözüm
Dosya listesi — "bu dosya modelleri içerir"	Bir hikaye anlat. Her adım öncekine bağlı.
Genel açıklamalar	Bu kod tabanına özgü deseni adlandır.
Satır numarası tahmini	Okumadan hiçbir zaman satır yazma.
Hızlı derinlik için çok fazla adım	Gerçekten adımları kes.
Hallüsinasyon dosyaları	Yoksa adımı atla.
Recap kapanışı — "X, Y, Z'yi ele aldık"	Okuyucuya artık ne yapabileceğini söyle.
Sadece content ilk adımı	1. adımı bir dosya veya dizine çapa.

Çapraz Referanslar

• İlgili: engineering/codebase-onboarding — turların ötesinde daha geniş onboarding için
• İlgili: engineering/pr-review-expert — otomatik PR review iş akışları için
• CodeTour uzantısı: microsoft/codetour
• Gerçek dünya turları: coder/code-server