Kod tabanı oryantasyonu için Claude Code: modülleri, temel akışları ve riskleri haritalamak için Soru&Cevap istemlerini kullanın; sonra notları kısa bir oryantasyon dokümanına dönüştürün.
Rasgele dosyalar okumak yavaş hissettirir çünkü çoğu kod tabanı bir hikâye gibi düzenli değildir. Bir klasör açarsınız, önemli görünen on isim görürsünüz, birine tıklarsınız ve yardımcılar, konfigürasyonlar ve kenar durumlarına saparsınız. Bir saat sonra birçok detaya sahipsiniz ama yine de uygulamanın nasıl çalıştığını açıklayamıyorsunuz.
Oryantasyon sırasında Claude Code için daha iyi hedef, basit bir zihinsel harita oluşturmaktır. Bu harita üç soruyu yanıtlamalıdır:
Bir-iki günde "yeterince iyi" oryantasyon, "her sınıfı açıklayabilirim" demek değildir. Daha çok şuna benzer:
Bazı şeyler bekleyebilir. Derin refaktörler, her soyutlamanın kusursuz anlaşılması ve kimsenin dokunmadığı eski kodu okumak nadiren hızlıca fayda getirir.
Oryantasyonu sokakları ezberlemek değil, bir harita oluşturmak olarak düşünün. İstemleriniz sizi sürekli şu sorulara geri çekmeli: "Sistemde nerede bulunuyorum, sonra ne oluyor ve burada ne ters gidebilir?" Bunları elde ettiğinizde detayları talep üzerine öğrenmek kolaylaşır.
Soru sormaya başlamadan önce, normalde ilk gün ihtiyaç duyduğunuz temel bilgileri toplayın. Claude Code gerçek dosyalara, gerçek konfigürasyona ve çoğaltabileceğiniz gerçek davranışa tepki verdiğinde en iyi şekilde çalışır.
Önce erişim ve çalışır bir kurulum sağlayın. Repoyu klonlayabildiğinizden, bağımlılıkları kurabildiğinizden ve uygulamayı (veya en azından küçük bir dilimi) yerelde çalıştırabildiğinizden emin olun. Yerel kurulum zorsa, staging ortamına ve logların bulunduğu yere erişim alın, böylece kodun gerçekte ne yaptığını doğrulayabilirsiniz.
Sonra “gerçeğin kaynağı” dokümanlarını bulun. Ekip değiştiğinde gerçekten güncelledikleri şeyleri arıyorsunuz: bir README, kısa bir mimari notu, ADR klasörü, runbook veya dağıtım notu. Dağınık olsalar bile modül ve akış isimleri verirler; bu da Soru&Cevap'ı çok daha hassas yapar.
Kapsamı erken belirleyin. Pek çok repo birden fazla uygulama, servis ve paylaşılan paket içerir. Sınırlar belirleyin: "sadece API ve fatura worker'ı" veya "sadece web uygulaması ve onun auth akışı" gibi. Net kapsam sonsuz sapmaları önler.
Asistanın tahmin etmesini istemediğiniz varsayımları yazın. Bu küçük görünür ama daha sonra saatler kaybettirebilecek yanlış zihinsel modelleri önler.
Basit bir hazırlık kontrol listesi:
Eğer bir şey eksikse, bunu bir ekip arkadaşına sorulacak bir soru olarak kaydedin. Eksik bağlamı "çözmeye" çalışmayın.
Zihinsel harita, şu soruyu cevaplayan küçük bir not setidir: bu uygulamanın ana parçaları neler, nasıl birbirleriyle konuşuyorlar ve nerede işler ters gidebilir. İyi yapıldığında oryantasyon dosyaları gezmekten ziyade yeniden kullanılabilir bir resim oluşturmak olur.
Başlangıç olarak çıktılarınuzu tanımlayın. Pratik bir modül listesi isteyin, kusursuz değil ama işe yarar olsun. Her modül için ne yaptığı, kimin sahibi olduğu (biliniyorsa) ve ana bağımlılıkları (diğer modüller, servisler, veritabanları, dış API'ler) not edin. Ayrıca ana giriş noktalarını da belirtin: UI rotaları, API endpoint'leri, arka plan işleri ve zamanlanmış görevler.
Sonra birkaç kullanıcı yolculuğu seçin. Üç ila beş yeterlidir. Para, izinler veya veri değişiklikleri içeren akışları seçin. Örnekler: kayıt ve e-posta doğrulama, ücretli plan oluşturma veya satın alma, bir yöneticinin kullanıcı erişimini değiştiren işlemi ve çoğu kullanıcının günlük olarak güvendiği kritik bir akış.
Başlamadan önce riski nasıl etiketleyeceğinize karar verin. Tarama yaparken basit kategoriler tutun. Yararlı bir set: güvenlik, veri bütünlüğü, kullanılabilirlik ve maliyet. Bir şeyi riskli olarak işaretlediğinizde, nedenini bir cümleyle ve güvenli olduğunu kanıtlayacak şeyi (bir test, bir log, bir izin kontrolü) ekleyin.
Notları yeniden yazmadan oryantasyon dokümanına dönüştürebilmek için tutarlı bir format kullanın:
Örnek: Checkout Billing'i çağırıp payments ve invoices'a yazıyorsa, bunu veri bütünlüğü ve maliyet olarak etiketleyin. Sonra retry'lerin nerede olduğunu ve çift ücretlendirmeyi neyin önlediğini not edin.
Yeni bir repo'ya katıldığınızda, hızlı oryantasyon istersiniz, mükemmel anlayış değil. Bu istemler size küçük, güvenli adımlarla zihinsel harita oluşturmanızda yardımcı olur.
Asistana repo ağacını (veya yapıştırılmış alt kümesini) vererek bir tur isteyerek başlayın. Her turu odaklı tutun, sonra bir sonraki okunacak şeyi söyleyen bir soru ile bitirin.
1) Repo tour
"Here is the top-level folder list: <paste>. Explain what each folder likely contains and which ones matter for core product behavior."
2) Entry points
"Find the app entry points and boot process. What files start the app, set up routing, configure DI/env, and start background jobs? Name the exact files and what they do."
3) Module index
"Create a module index: module name, purpose, key files, and important external dependencies. Keep it to the modules that affect user-facing behavior."
4) Data model hints
"Based on migrations/models, list the key tables/entities, critical fields, and relationships. Call out fields that look security-sensitive or used for billing/permissions."
5) Flow trace
"Trace this flow end-to-end: <flow>. Where does the request/event start, where does it end, and what does it call in between? List the main functions/files in order."
6) Next inspection
"What should I inspect next and why? Give me 3 options: fastest clarity, riskiest area, and best long-term payoff."
Somut bir örnek: "kullanıcı kaydolur ve ilk projesini oluşturur"u haritalıyorsanız, API route handler'ı, validasyon, DB yazımı ve e-posta gönderen veya kaynak sağlayan asenkron iş varsa onu isteyin. Sonra "kullanıcı proje siler" akışı için akış izini tekrar çalıştırın ve temizlik boşluklarını bulun.
Cevapları eyleme geçirilebilir kılmak için somut artefaktlar isteyin, sadece özet değil:
En büyük oryantasyon kazancı, dağınık Soru&Cevap'leri başka bir geliştiricinin de kullanabileceği notlara dönüştürmektir. Notlar sadece size anlamlıysa aynı kazmayı tekrar yapmak zorunda kalırsınız.
Basit bir yapı uzun sayfalardan daha iyidir. Her keşif oturumundan sonra cevapları beş küçük artefakte (tek bir dosya veya doküman olabilir) kaydedin: bir modül tablosu, bir sözlük, ana akışlar, bilinmeyenler ve bir risk kaydı.
İşte yaparken yapıştırıp doldurabileceğiniz kompakt bir şablon:
Module table
- Module:
Owns:
Touches:
Entry points:
Glossary
- Term:
Meaning:
Code name(s):
Key flow (name)
1.
2.
3.
Unknowns
- Question:
Best person to ask:
Where to look next:
Risk register
- Risk:
Location:
Why it matters:
How to verify:
Ana akışları kasıtlı olarak kısa tutun. Örnek: 1) kullanıcı giriş yapar, 2) backend bir oturum oluşturur, 3) istemci panoyu yükler, 4) API veri çeker, 5) UI render eder ve hataları ele alır. Bir akışı beş adıma sığdıramıyorsanız, onu bölün (giriş vs pano yükleme gibi).
Claude Code kullanırken her cevaba bir satır ekleyin: "Bunu nasıl test ederim?" Bu satır pasif notları daha sonra çalıştırabileceğiniz bir kontrol listesine dönüştürür, özellikle bilinmeyenler ve riskler çakıştığında.
Koder.ai gibi vibe-coding platformlarında bu tür not tutma aynı zamanda oluşturulan değişikliklerin yan etkilerini görmenize yardımcı olur. Çok temas eden modüller genelde değişiklik mıknatısıdır.
Kod tabanındaki risk nadiren rastgele dağılır. Kimlik doğrulama, veri değiştirme, diğer sistemlerle konuşma veya arka planda çalışma kararlarının yoğunlaştığı yerlerde kümelenir. Hedefli sorular ve birkaç odaklı aramayla çoğunu bulabilirsiniz.
Kimlikten başlayın. Kimlik doğrulamanın nerede gerçekleştiğini (login, oturum, token) ve yetkilendirme kararlarının nerede alındığını (rol kontrolleri, feature flag'ler, sahiplik kuralları) sorun. Yaygın bir sorun kontrollerin UI, API handler'ları ve veritabanı sorguları arasında dağınık olması ve tek bir güven kaynağı olmamasıdır.
Sonra yazım yollarını haritalayın. Kayıt oluşturan, güncelleyen veya silen endpoint'leri veya fonksiyonları ve zaman içinde veriyi yeniden şekillendiren migration'ları bulun. Arka plan işler de dahil edin. Birçok gizemli hata, isteğin bittikten sonra beklenmedik değerler yazan asenkron worker'lardan gelir.
Hızlıca riskleri ortaya çıkaracak istemler:
Ardından konfigürasyon ve gizli bilgi yönetimini kontrol edin. Ortam değişkenleri, çalışma zamanı konfig dosyaları ve varsayılan geri dönüşler için arama yapın. Varsayılanlar faydalıdır ama eksik bir değer nedeniyle (örneğin prod'da dev anahtarın kullanılması gibi) yanlış yapılandırmaları gizlediklerinde risklidir.
Kısa bir örnek: PostgreSQL kullanan bir Go backend'de, başarısızlıkta tekrar deneyen bir "e-posta gönder" işi bulabilirsiniz. Eğer retry idempotency anahtarı olmadan yapılıyorsa kullanıcılar çift e-posta alabilir. Hatalar yalnızca uyarı olarak log'lanıp hiçbir alarm yoksa, bu sessizce bozulur. Bu tür bir alan belgelendirip erken test edilmelidir.
İlk uçtan uca ipliği oluşturmak için bir gerçek akışı kullanın. Login başlamak için iyi bir akıştır çünkü routing, validasyon, oturum veya token ve veritabanı okumalarını kapsar.
Senaryo: React web uygulaması bir Go API'yi çağırıyor ve API PostgreSQL okuma/yazma yapıyor. Hedefiniz her dosyayı anlamak değil. Ama şu soruyu cevaplamaktır: "Kullanıcı Login'e tıkladığında sırada hangi kod çalışıyor, hangi veri hareket ediyor ve ne ters gidebilir?" Bu, oryantasyonun somut kalmasını sağlar.
UI'dan başlayıp ileri doğru, bir adımda bir adım yürüyün. Spesifik dosya isimlerini, fonksiyonları ve istek/yanıt şekillerini isteyin.
Her cevaptan sonra zihinsel haritanıza kısa bir satır yazın: "UI component -> API endpoint -> handler -> servis -> DB query -> response." Sadece "bir fonksiyon" demeyin; isimleri dahil edin.
Yolu elde ettikten sonra küçük bir test çalıştırmasıyla doğrulayın. Haritaladığınız kod yolunun gerçekten kullanılan yol olup olmadığını kontrol ediyorsunuz.
Tarayıcı geliştirici araçlarında ağ isteklerini izleyin (path, status kodu, response body). Handler ve DB çağrısı çevresine sunucu log'ları ekleyin (varsa request ID ile). PostgreSQL'de beklenen değişiklikleri sorgulayın (login için last_login_at, session'lar veya audit satırları olabilir). Bir başarısızlığı zorlayın (yanlış parola, eksik alan) ve hata mesajının nerede oluşturulduğunu ve nerede gösterildiğini not edin. Başarı ve hata için beklenen yanıtları kaydedin (status kodları ve önemli alanlar) ki bir sonraki geliştirici hızlıca temel kontrolleri yapabilsin.
Bu tek akış genelde sahiplik sınırlarını ortaya çıkarır: UI'nın neye güvendiği, API'nin neyi zorladığı ve hataların nerede kaybolduğu veya çift ele alındığı gibi.
İyi bir zihinsel haritaya sahip olduğunuzda, bunu 1–2 sayfalık bir notta sabitleyin. Amaç tamamlayıcı olmak değil. Bir sonraki geliştiricinin şu soruları cevaplayabilmesini sağlamaktır: bu uygulama nedir, nereden bakmalıyım ilk, ve en olası kırılma noktaları neler?
Claude Code kullanıyorsanız dokümanı Soru&Cevap çıktınız olarak düşünün: net, somut ve hızlı taranabilir.
Dokümanı tahmin edilebilir tutun ki insanlar hızlıca aradıklarını bulabilsin:
"Nerede bulunur" için şunlar gibi işaretler verin: "Auth X'de başlar, oturum mantığı Y'de, UI rotaları Z'de." Tam bir ağaç dökümü atmayın. Sadece insanların dokunacağı yerleri seçin.
"Ana akışlar" için her adımı 4–7 adımda tutun: tetik, controller/handler, ana modül, DB çağrısı ve dış etki (e-posta gönderildi, durum güncellendi, iş kuyruğa alındı). Her adımda dosya isimlerini ekleyin.
"Riskli alanlar" için başarısızlık modunu ve en hızlı güvenlik kontrolünü (belirli bir test, smoke run veya izlenecek log) yazın.
Sonunda yeni birinin güvenle katkıda bulunmasını sağlayacak küçük ilk görevler listesi ekleyin:
Asistanı boşa harcamanın en hızlı yolu "tüm repoyu tam açıklama" istemektir. Uzun ama muğlak bir özet alırsınız. Bunun yerine önemli bir dilim seçin (bir modül + bir kullanıcı akışı) ve sonra dışa doğru genişletin.
İkinci sık hata, hangi yolculukların önemli olduğunu belirtmemektir. Eğer "checkout", "login" veya "admin edit" demiyorsanız, cevaplar genel mimari konuşmasına kayar. Her oturuma somut bir hedefle başlayın: "Signup akışını uçtan uca anlamama yardım et, validasyon, hata durumları ve verinin nerede saklandığı dahil." gibi.
Bir diğer tuzak, asistanın tahmin yapmasına izin vermektir. Bir şey belirsizse, bunu etiketlemesini zorlayın. Koddaki kanıt ile çıkarımını ayırmasını isteyin.
Notlarınızda basit bir kural kullanın: her iddia şu etiketlerden biriyle işaretlensin:
Notlar yapısız toplandığında işe yaramaz hale gelir. Tutarlı bir şablon kullanın: ilgili modüller, giriş noktası, ana fonksiyonlar ve dosyalar, dokunan veri, yan etkiler, hata yolları ve çalıştırılacak testler.
Claude Code olsa bile çıktıyı taslak gibi kabul edin. Önemli akışları çalıştırarak doğrulayın; özellikle prod'u kırabilecek kısımları: auth, ödemeler, izinler, arka plan işler ve migration'lar.
Pratik örnek: asistan "şifre sıfırlama X üzerinden e-posta gönderir" diyorsa, bunu bir dev ortamında tetikleyip logları veya e-posta sandbox'ını kontrol ederek doğrulayın. Bu gerçek kontrol sizi gerçeğe uymayan bir hikâyede oryante olmaktan korur.
Repoyu ezberlemeniz gerekmez. Güvenli bir değişiklik yapacak, gerçek bir sorunu debug edecek ve sistemi bir sonraki kişiye açıklayacak kadar güveniniz olmalı.
Oryante olduğunuzu söylemeden önce şu soruları tahmin etmeden cevaplayabildiğinizden emin olun:
Eğer bir madde eksikse, geniş bir arama yerine küçük, odaklı bir geçiş yapın. Bir akışı seçin, veritabanı sınırına kadar izleyin, durun ve öğrendiklerinizi yazın. Bir şey belirsizse onu bir soru olarak kaydedin, paragraf yerine. "Role X nerede oluşturulur?" sorusu "auth kafa karışık" demekten daha faydalıdır.
İyi bir son test: bir özellik flag'i arkasına küçük bir özellik eklemeniz istendiğini hayal edin. Dokunacağınız dosyaları, çalıştıracağınız testleri ve izleyeceğiniz hata modlarını sayabiliyorsanız, katkıda bulunmak için yeterince oryante olmuşsunuz demektir.
Zihinsel harita yalnızca gerçeğe uyduğu sürece işe yarar. Bunu tek seferlik bir görev olarak değil, yaşayan bir belge olarak görün. Haritayı gerçeğe yakın tutmanın en kolay yolu, davranışı etkileyen değişikliklerden hemen sonra güncellemektir.
Hafif bir rutin büyük yeniden yazmalardan daha etkilidir. Yaptığınız işlere bağlı olarak güncelleme yapın:
Oryantasyon dokümanını koda yakın tutun ve aynı disiplinle versionlayın. Küçük diff'ler okunur; büyük doküman yeniden yazımları genelde atlanır.
Dağıtımlar riskliyse, bir sonraki kişinin hızlıca kurtarmasına yardımcı olacak bilgileri yazın: ne değişti, ne izlenmeli ve nasıl geri alınır. Platformunuz snapshot ve rollback destekliyorsa, snapshot adını, sebebini ve düzeltmeden sonra "iyi" olanın ne göründüğünü ekleyin.
Eğer Koder.ai (koder.ai) ile geliştiriyorsanız, planlama modu Q&A'den tutarlı bir modül haritası ve oryantasyon notu çıkarmanıza yardımcı olabilir; kaynak kodu dışa aktarmak da inceleme için temiz bir yol sağlar.
Son olarak, bir sonraki geliştiricinin tahmin yürütmeden takip edebileceği bir devralma kontrol listesi tanımlayın:
İyi yapıldığında, Claude Code kod tabanı oryantasyonu bir alışkanlık haline gelir: her değişiklik bir sonraki kişi için daha net bir harita bırakır.
Kullanılabilir bir zihinsel harita hedefleyin, tüm detayları ezberlemek değil.
İyi bir 1–2 günlük çıktı şu şekilde olabilir:
Claude Code'a gerçek kodu gösteren somut şeyler verin, böylece tahmin yapmak yerine gerçek dosyalara işaret edebilir:
Sınırları belli, dar bir dilim seçin.
İyi bir varsayılan kapsam:
Ayrıca açıkça dışarıda bıraktıklarınızı yazın (diğer servisler, legacy modüller, nadiren kullanılan özellikler) ki asistan dolaşmasın.
Bilinen tetiklerden başlayın, sonra ileri doğru yürüyün:
Sırayla dosya yolları ve fonksiyon isimleri isteyin ve son olarak: “Bunu hızlı nasıl test ederim?” diye sorun.
Sistemin karar verdiği veya durum değiştirdiği yerlerde yoğunlaşın:
Basit bir etiket sistemi kullanın ve her riske bir doğrulama adımı ekleyin.
Örnek format:
Asistanı varsayımlar yapmaya zorlamayın; kanıtla çıkarımını ayırmasını isteyin.
Her iddiayı şu etiketlerden biriyle işaretlemesini isteyin:
Bilinmeyen bir şey varsa bunu bir ekip arkadaşına sorulacak soru haline getirin (“Role X nerede tanımlanıyor?”) ve asistanın doldurmasını engelleyin.
Tek bir hafif not dosyası tutun, beş kısa bölümle:
Hızlı, gerçek bir kontrol yapın:
Bu, haritaladığınız yolun uygulamanın gerçekten kullandığı yol olduğunu doğrular.
Platform özelliklerini kullanarak hasarı azaltın ve değişiklikleri incelenebilir tutun.
Pratik varsayılanlar:
Bu, “koruma ekle”, “validasyonu sıkılaştır” veya “hata yolunu iyileştir” gibi oryantasyon görevlerinde özellikle işe yarar.
Sonra sorun: “Sessizce ne kırılabilir ve bunu nasıl fark ederiz?”
Kısa tutun ki öğrendikçe güncellesin.
Her akışa bir satır ekleyin: “Bunu nasıl test ederim?” — böylece kontrol listesine dönüşür.