Hangi Dosyalarınızı Gerçekten Okuyorsunuz? Geliştirici Etkileşim Takibi

TL;DR

Claude Code'un PostToolUse hook'unu kullanarak her dosya okuma ve düzenleme işlemini otomatik logluyorum. Biriken veri dört farklı analizle yorumlanıyor: hot files (en çok erişilen), knowledge gaps (sonuçsuz aramalar), decay (azalan ilgi), query patterns (arama örüntüleri). Bir haftalık veriden bile projenin gerçek ağırlık merkezini görebiliyorsunuz.

store.py’i bu hafta 66 kez düzenlemiş ve projenin README.md dosyasını 79 kez okudum; bunu bilmiyordum. İnsan kendi çalışma örüntüsünü doğru tahmin edemiyor. Veri olmadan veya spesifik olarak takip etmeden, hangi dosyaların projenin gerçek ağırlık merkezi olduğunu bilmek zor.

Problem: Projenin Gerçek Haritası LOC’da Değil

Bir projenin en önemli dosyaları hangisi? Satır sayısına baksanız büyük dosyalar öne çıkar. Git churn’e baksanız en çok commit alan dosyalar. Ama bunların hiçbiri “geliştirici olarak gerçekte neye en çok baktığınızı” ölçmüyor.

Gerçek ağırlık merkezi, sizin davranışınızda gizli:

Hangi dosyayı her gün açıyorsunuz?
Hangi dosyayı tekrar tekrar düzenliyorsunuz?
Hangi aramalarınız boş dönüyor?
Hangi dosyalara artık bakmıyorsunuz?

Bu sorulara cevap vermek için etkileşim verisi lazım. Elbette, küçük bir projede çalışıyorsanız ister istemez bazı bilgi kırıntılarını zihniniz toplayaraktır ve bu sayede tahmin yürütmeniz kolaylaşcaktır.

Çözüm: Her Okuma ve Düzenlemeyi Loglamak

dnomia-knowledge projesinde Claude Code’un hook mekanizmasını kullanarak her dosya etkileşimini otomatik olarak kaydediyorum. Bu sistem, context engineering ekosistemimin öğrenme döngüsü katmanının bir parçası. Sistem üç parçadan oluşuyor:

1. PostToolUse Hook

Claude Code her Read veya Edit tool’unu çağırdığında, PostToolUse hook devreye girer:

# hooks/post_tool_use.py (basitleştirilmiş)
interaction = InteractionType.READ if tool_name == "Read" else InteractionType.EDIT
batch = [
    (chunk_id, interaction, f"hook:{tool_name}", project_id, rel_path)
    for chunk_id in chunk_ids
]
store.batch_log_interactions(batch)

Hook, dosyanın hangi projeye ait olduğunu bulur, o dosyanın indekslenmiş chunk’larını alır ve her chunk için bir etkileşim kaydı oluşturur. Tüm süreç 10-30ms.

2. Arama Loglama

Her MCP search çağrısı da loglanıyor:

# search.py
store.log_search(query, project_id, domain, chunk_ids, result_count)
store.batch_log_interactions(
    [(r.chunk_id, InteractionType.SEARCH_HIT, "search", r.project_id, r.file_path)
     for r in results]
)

Hem sorgunun kendisi (ne arandı, kaç sonuç döndü) hem de sonuçlardaki chunk’lar search_hit olarak işaretleniyor.

3. SQLite’da Depolama

İki tablo:

chunk_interactions:
  chunk_id    | project_id | file_path       | interaction | source_tool | timestamp
  142         | my-project | src/store.py    | edit        | hook:Edit   | 2026-03-18 10:23
  89          | my-project | README.md       | read        | hook:Read   | 2026-03-18 10:25

search_log:
  query                          | project_id | result_count | timestamp
  authentication middleware      | my-project | 5            | 2026-03-18 10:30
  frontmatter title slug         | ceaksan    | 0            | 2026-03-17 09:41

Verinin tamamı lokal SQLite dosyasında. Bulut servisi yok, API çağrısı yok.

Dört Analiz: Trace Analytics

Biriken veri dört farklı açıdan sorgulanıyor:

trace hot: En Çok Erişilen Dosyalar

dnomia-knowledge trace hot

                        Hot Files (last 30 days)
┏━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━┳━━━━┳━━━━┳━━━━━━━┓
┃ #   ┃ File                              ┃  R ┃  E ┃  S ┃ Total ┃
┡━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━╇━━━━╇━━━━╇━━━━━━━┩
│ 1   │ dnomia-knowledge README.md        │ 79 │ 37 │  0 │   116 │
│ 2   │ dnomia-knowledge store.py         │  0 │ 66 │  0 │    66 │
│ 3   │ turkish-diacritics README.md      │ 36 │ 12 │  0 │    48 │
│ 4   │ dnomia-knowledge server.py        │ 44 │  0 │  0 │    44 │
│ 5   │ ceaksan post-normalize.ts         │ 18 │  9 │  0 │    27 │
└─────┴───────────────────────────────────┴────┴────┴────┴───────┘

Bu tablo gerçek veriden geliyor (13 indeksli proje, 30 günlük pencere). Birkaç gözlem:

README.md en sıcak dosya. 79 okuma, 37 düzenleme. Bu dosya projenin “yüzü” ve sürekli güncelleniyor.

store.py sadece edit. 66 düzenleme, sıfır okuma. Bu mantıklı: store.py’nin yapısını zaten biliyorum, her değişiklikte doğrudan düzenliyorum, referans olarak okumuyorum.

server.py sadece okuma. 44 okuma, sıfır düzenleme. Tam tersi: server.py’yi referans olarak okuyorum ama nadiren değiştiriyorum.

Cross-project veri. Aynı tabloda farklı projeler görünüyor (dnomia-knowledge, turkish-diacritics, ceaksan). Tek bir bakışta tüm projelerdeki çalışma yoğunluğunu görmek mümkün.

trace gaps: Sonuçsuz Aramalar

dnomia-knowledge trace gaps

                 Knowledge Gaps (last 30 days)
┏━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ #   ┃ Query                                         ┃ Count ┃
┡━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ 1   │ date calendar pubDate display card            │     1 │
│ 2   │ frontmatter title slug                        │     1 │
│ 3   │ frontmatter başlık yapısı tüm bölümler        │     1 │
└─────┴───────────────────────────────────────────────┴───────┘

Bu analiz, aramanın nerede başarısız olduğunu gösteriyor. Üç farklı sorgu sıfır sonuç döndürmüş.

“frontmatter title slug” sorgusuna sıfır sonuç dönmesi, Astro component’lerinin veya layout dosyalarının indeksleme kapsamında olmadığına işaret ediyor. .knowledge.toml config’inde bu dosya tiplerinin eksik olduğu anlamına geliyor.

“date calendar pubDate display card” da benzer bir boşluk. Aranan bilgi muhtemelen bir Astro component’te var ama indekslenmemiş.

Knowledge gaps analizi, indeksleme kapsamını genişletmek için somut ipuçları veriyor. Sıfır sonuçlu aramalar, bilgi tabanınızın kör noktaları.

trace decay: Azalan İlgi

dnomia-knowledge trace decay

İki zaman penceresi karşılaştırılıyor: son 30 gün vs önceki 30 gün. Eskiden çok erişilen ama artık dokunulmayan dosyalar ortaya çıkıyor.

Bu analiz yeterli veri biriktiğinde (en az 60 günlük) anlamlı sonuç veriyor. Olası senaryolar:

Deprecated kod: Eskiden aktif ama artık kullanılmayan modüller
Bilgi eskimesi: Bir dönem yoğun çalıştığınız alan, artık güncel bilginiz yok
Tamamlanmış iş: Bir özellik bitti, artık o dosyalara dönmüyorsunuz (bu normal)

trace queries: Arama Örüntüleri

dnomia-knowledge trace queries

                     Top Queries (last 30 days)
┏━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━┓
┃ #   ┃ Query                                 ┃ Count ┃ Avg Results ┃
┡━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━┩
│ 1   │ GTM Zaraz server-side tracking        │     1 │         5.0 │
│ 2   │ etkinlik takibinde farklı yaklaşımlar │     1 │        10.0 │
│ 3   │ return IndexResult                    │     1 │        10.0 │
└─────┴───────────────────────────────────────┴───────┴─────────────┘

Henüz erken aşama (her sorgu 1 kez). Zaman geçtikçe tekrar eden sorgular ortaya çıkar. Bunlar, sık ihtiyaç duyulan ama hızlı erişilemeyen bilgi alanlarına işaret eder. Örneğin “GTM Zaraz server-side tracking” sorgusu, etkinlik verisi takip yaklaşımları yazısını ararken oluşmuş olabilir.

Git Churn ile Birleştirme: Crossover Analizi

Etkileşim verisi tek başına değerli. Ama git churn verisiyle birleştirildiğinde daha güçlü bir sinyal ortaya çıkıyor.

dnomia-knowledge analyze crossover

Her dosya iki eksende değerlendiriliyor:

Churn: Git’te ne kadar değişiyor (insertions + deletions)
Read: Ne kadar okunuyor (trace hot verisi)

Bu iki boyuttan altı sinyal türetiliyor:

Sinyal	Churn	Read	Anlam
HOT	Yüksek	Yüksek	Projenin kalbi. Hem çok değişiyor hem çok okunuyor.
BLIND	Yüksek	Sıfır	Tehlike. Aktif olarak değişiyor ama hiç bakılmıyor.
TURBULENT	Yüksek	Düşük	Riskli. Çok değişiyor, az izleniyor.
STABLE	Düşük	Yüksek	Referans kod. Az değişiyor, çok okunuyor.
ZOMBIE	Sıfır	Düşük	Ölü kod adayı. Hiç değişmiyor, nadiren bakılıyor.
COLD	Düşük	Düşük	İnaktif. Normal durum.

BLIND sinyali en kritik olanı. Bir dosya aktif olarak değişiyorsa ama hiç okunmuyorsa, bu değişikliklerin review edilmediği anlamına geliyor. Bug riski yüksek.

Etkileşim Verisi Arama Kalitesini İyileştiriyor

Bu veri sadece analitik amacıyla toplanmıyor. Arama sonuçlarını doğrudan etkiliyor.

Interaction Boost

Hybrid search (FTS5 + vector + RRF) sonuçlarına son adım olarak interaction boost uygulanıyor:

for r in results:
    count = interaction_counts.get(r.chunk_id, 0)
    bonus = 0.1 * min(count, 10) / 10
    r.score = r.score + bonus

Sık okunan veya düzenlenen dosyalar, arama sonuçlarında yukarı çıkıyor. Bu kişisel bir arama motoru oluşturuyor: aynı kod tabanında çalışan iki geliştirici, aynı sorguyu yaptığında farklı sıralama alır.

Neden İşe Yarıyor

“database connection” aradığınızda, projenizde muhtemelen birden fazla dosya bu kavramla ilgili. Ama her gün çalıştığınız store.py muhtemelen aradığınız dosya. Interaction boost bunu biliyor çünkü store.py’i 66 kez düzenlemişsiniz.

Bu, collaborative filtering’in tek kullanıcılı versiyonu. Netflix’in “daha önce izlediklerinize göre” önerisi gibi, ama kod dosyaları için.

Kurulum

1. dnomia-knowledge’ı kurun

git clone https://github.com/ceaksan/dnomia-knowledge.git
cd dnomia-knowledge
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Projenizi indeksleyin

dnomia-knowledge index /path/to/your/project

3. Claude Code hook’larını kaydedin

~/.claude/settings.json dosyasına ekleyin:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Read|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/.venv/bin/python -m dnomia_knowledge.hooks.post_tool_use"
          }
        ]
      }
    ]
  }
}

4. Çalışın ve veri biriktirin

Normal Claude Code session’larınızda çalışın. Hook arka planda veri toplar. Birkaç gün sonra:

dnomia-knowledge trace hot
dnomia-knowledge trace gaps

Gözlemler ve Çıkarımlar

Bir haftalık veriyle bile şunları öğrendim:

Projenin gerçek ağırlık merkezi LOC’dan farklı. En büyük dosya en önemli dosya değil. En çok etkileşime giren dosya en önemli dosya.

README’nin önemi küçümseniyor. 116 etkileşimle en sıcak dosya. README projenin sadece “yüzü” değil, aktif bir çalışma dokümanı.

Okuma ve düzenleme örüntüleri farklı bilgi veriyor. Sadece edit = dosyayı iyi biliyorsunuz, referansa ihtiyacınız yok. Sadece read = referans olarak kullanıyorsunuz ama değiştirmiyorsunuz. İkisi birlikte = aktif çalışma alanı.

Sonuçsuz aramalar, bilgi tabanınızın kör noktaları. Her sıfır sonuçlu sorgu, indekslenmemiş veya eksik dokümante edilmiş bir alana işaret ediyor.

Teknik Detaylar

Veri boyutu: Her etkileşim kaydı ~100 byte. Günde 200 etkileşim = ayda ~600KB.
Hook süresi: 10-30ms (DB lookup + insert). Claude Code akışını yavaşlatmıyor.
Pencere: trace hot/gaps/queries varsayılan 30 gün. trace decay 30 gün vs önceki 30 gün.
Cross-project: Tüm projeler tek DB’de. --project flag’i ile filtreleme mümkün.
Hook güvenliği: catch-all exception handler ile hook asla crash olmaz. Hata olursa stderr’e loglar, Claude Code session’ı etkilemez.

Kaynak kodu: dnomia-knowledge

Önemli Noktalar

01 README.md 116 etkileşimle en sıcak dosya çıktı. Kod dosyaları arasında store.py (66 edit) açık ara önde. LOC ile ölçseniz bu sıralamayı bulamazsınız.
02 Knowledge gaps analizi, arama motorunun nerede başarısız olduğunu gösteriyor. 'frontmatter title slug' sorgusuna sıfır sonuç dönmesi, indeksleme kapsamının eksik olduğuna işaret ediyor.
03 Etkileşim verisi sadece analitik değil, arama kalitesini de iyileştiriyor. Sık okunan dosyalar arama sonuçlarında otomatik olarak yukarı çıkıyor.
04 Tüm veri lokal SQLite'da kalıyor. Bulut servisi yok, API çağrısı yok, gizlilik endişesi yok.

Sık Sorulan Sorular (FAQ)

+ Bu sistem Claude Code dışında çalışır mı?

Hook mekanizması Claude Code'a özgü (PreToolUse/PostToolUse). Ama Store ve trace analytics modülleri bağımsız Python. Farklı bir editörün plugin API'si üzerinden aynı veriyi besleyebilirsiniz.

+ Etkileşim verisi ne kadar yer kaplıyor?

Her etkileşim kaydı yaklaşık 100 byte. Günde 200 dosya okuma/düzenleme yaparsanız, ayda ~600KB. Yılda ~7MB. SQLite için ihmal edilebilir.

+ Hook performansı etkiliyor mu?

PostToolUse hook her Read/Edit sonrası çalışıyor. DB lookup ve insert toplamda 10-30ms. Claude Code'un çalışmasını algılanabilir şekilde yavaşlatmıyor.

+ Decay analizi ne işe yarıyor?

Son 30 gündeki etkileşimi önceki 30 günle karşılaştırıyor. Eskiden çok okunan ama artık dokunulmayan dosyaları ortaya çıkarıyor. Bunlar ya deprecated kod ya da bilginizin eskidiği alanlar.

developer-tools ai