mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-04-09 10:53:34 +08:00
Add Turkish (tr) docs and update README (#744)
* Add Turkish (tr) docs and update README Add a full set of Turkish documentation under docs/tr (agents, changelog, CLAUDE guide, contributing, code of conduct, and many agents/commands/skills/rules files). Update README to include a link to the Turkish docs and increment the supported language count from 5 to 6. This commit adds localized guidance and references to help Turkish-speaking contributors and users. * Update docs/tr/TROUBLESHOOTING.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> * Update docs/tr/README.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> * docs(tr): fix license link and update readmes Update Turkish docs: change license badge link to point to repository root (../../LICENSE), increment displayed language count from 5 to 6, and remove two outdated related links from docs/tr/examples/README.md to keep references accurate. * Update docs/tr/commands/instinct-import.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> * Update docs/tr/commands/checkpoint.md Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com> --------- Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>
This commit is contained in:
Berkcan Gümüşışık
committed by
GitHub
GitHub
parent
bb1efad7c7
commit
fd2a8edb53
422
docs/tr/TROUBLESHOOTING.md
Normal file
422
docs/tr/TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,422 @@
|
||||
# Sorun Giderme Rehberi
|
||||
|
||||
Everything Claude Code (ECC) eklentisi için yaygın sorunlar ve çözümler.
|
||||
|
||||
## İçindekiler
|
||||
|
||||
- [Bellek ve Context Sorunları](#bellek-ve-context-sorunları)
|
||||
- [Ajan Harness Hataları](#ajan-harness-hataları)
|
||||
- [Hook ve İş Akışı Hataları](#hook-ve-iş-akışı-hataları)
|
||||
- [Kurulum ve Yapılandırma](#kurulum-ve-yapılandırma)
|
||||
- [Performans Sorunları](#performans-sorunları)
|
||||
- [Yaygın Hata Mesajları](#yaygın-hata-mesajları)
|
||||
- [Yardım Alma](#yardım-alma)
|
||||
|
||||
---
|
||||
|
||||
## Bellek ve Context Sorunları
|
||||
|
||||
### Context Window Taşması
|
||||
|
||||
**Belirti:** "Context too long" hataları veya eksik yanıtlar
|
||||
|
||||
**Nedenler:**
|
||||
- Token limitlerini aşan büyük dosya yüklemeleri
|
||||
- Birikmiş konuşma geçmişi
|
||||
- Tek oturumda birden fazla büyük araç çıktısı
|
||||
|
||||
**Çözümler:**
|
||||
```bash
|
||||
# 1. Konuşma geçmişini temizle ve yeni başla
|
||||
# Claude Code kullan: "New Chat" veya Cmd/Ctrl+Shift+N
|
||||
|
||||
# 2. Analiz öncesi dosya boyutunu küçült
|
||||
head -n 100 large-file.log > sample.log
|
||||
|
||||
# 3. Büyük çıktılar için streaming kullan
|
||||
head -n 50 large-file.txt
|
||||
|
||||
# 4. Görevleri daha küçük parçalara böl
|
||||
# Bunun yerine: "50 dosyanın hepsini analiz et"
|
||||
# Kullan: "src/components/ dizinindeki dosyaları analiz et"
|
||||
```
|
||||
|
||||
### Bellek Kalıcılığı Hataları
|
||||
|
||||
**Belirti:** Ajan önceki context veya gözlemleri hatırlamıyor
|
||||
|
||||
**Nedenler:**
|
||||
- Devre dışı bırakılmış sürekli öğrenme hook'ları
|
||||
- Bozuk gözlem dosyaları
|
||||
- Proje algılama hataları
|
||||
|
||||
**Çözümler:**
|
||||
```bash
|
||||
# Gözlemlerin kaydedilip kaydedilmediğini kontrol et
|
||||
ls ~/.claude/homunculus/projects/*/observations.jsonl
|
||||
|
||||
# Mevcut projenin hash id'sini bul
|
||||
python3 - <<'PY'
|
||||
import json, os
|
||||
registry_path = os.path.expanduser("~/.claude/homunculus/projects.json")
|
||||
with open(registry_path) as f:
|
||||
registry = json.load(f)
|
||||
for project_id, meta in registry.items():
|
||||
if meta.get("root") == os.getcwd():
|
||||
print(project_id)
|
||||
break
|
||||
else:
|
||||
raise SystemExit("Project hash not found in ~/.claude/homunculus/projects.json")
|
||||
PY
|
||||
|
||||
# O proje için son gözlemleri görüntüle
|
||||
tail -20 ~/.claude/homunculus/projects/<project-hash>/observations.jsonl
|
||||
|
||||
# Bozuk bir observations dosyasını yeniden oluşturmadan önce yedekle
|
||||
mv ~/.claude/homunculus/projects/<project-hash>/observations.jsonl \
|
||||
~/.claude/homunculus/projects/<project-hash>/observations.jsonl.bak.$(date +%Y%m%d-%H%M%S)
|
||||
|
||||
# Hook'ların etkin olduğunu doğrula
|
||||
grep -r "observe" ~/.claude/settings.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ajan Harness Hataları
|
||||
|
||||
### Ajan Bulunamadı
|
||||
|
||||
**Belirti:** "Agent not loaded" veya "Unknown agent" hataları
|
||||
|
||||
**Nedenler:**
|
||||
- Eklenti doğru kurulmadı
|
||||
- Ajan yolu yanlış yapılandırılmış
|
||||
- Marketplace vs manuel kurulum uyumsuzluğu
|
||||
|
||||
**Çözümler:**
|
||||
```bash
|
||||
# Eklenti kurulumunu kontrol et
|
||||
ls ~/.claude/plugins/cache/
|
||||
|
||||
# Ajanın var olduğunu doğrula (marketplace kurulumu)
|
||||
ls ~/.claude/plugins/cache/*/agents/
|
||||
|
||||
# Manuel kurulum için ajanlar şurada olmalı:
|
||||
ls ~/.claude/agents/ # Sadece özel ajanlar
|
||||
|
||||
# Eklentiyi yeniden yükle
|
||||
# Claude Code → Settings → Extensions → Reload
|
||||
```
|
||||
|
||||
### İş Akışı Yürütmesi Takılıyor
|
||||
|
||||
**Belirti:** Ajan başlıyor ama hiç tamamlanmıyor
|
||||
|
||||
**Nedenler:**
|
||||
- Ajan mantığında sonsuz döngüler
|
||||
- Kullanıcı girdisinde takılı
|
||||
- API'yi beklerken ağ zaman aşımı
|
||||
|
||||
**Çözümler:**
|
||||
```bash
|
||||
# 1. Takılı işlemleri kontrol et
|
||||
ps aux | grep claude
|
||||
|
||||
# 2. Debug modunu etkinleştir
|
||||
export CLAUDE_DEBUG=1
|
||||
|
||||
# 3. Daha kısa zaman aşımları ayarla
|
||||
export CLAUDE_TIMEOUT=30
|
||||
|
||||
# 4. Ağ bağlantısını kontrol et
|
||||
curl -I https://api.anthropic.com
|
||||
```
|
||||
|
||||
### Araç Kullanım Hataları
|
||||
|
||||
**Belirti:** "Tool execution failed" veya izin reddedildi
|
||||
|
||||
**Nedenler:**
|
||||
- Eksik bağımlılıklar (npm, python, vb.)
|
||||
- Yetersiz dosya izinleri
|
||||
- Yol bulunamadı
|
||||
|
||||
**Çözümler:**
|
||||
```bash
|
||||
# Gerekli araçların kurulu olduğunu doğrula
|
||||
which node python3 npm git
|
||||
|
||||
# Hook scriptlerinin izinlerini düzelt
|
||||
chmod +x ~/.claude/plugins/cache/*/hooks/*.sh
|
||||
chmod +x ~/.claude/plugins/cache/*/skills/*/hooks/*.sh
|
||||
|
||||
# PATH'in gerekli binary'leri içerdiğini kontrol et
|
||||
echo $PATH
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hook ve İş Akışı Hataları
|
||||
|
||||
### Hook'lar Çalışmıyor
|
||||
|
||||
**Belirti:** Pre/post hook'lar çalışmıyor
|
||||
|
||||
**Nedenler:**
|
||||
- Hook'lar settings.json'da kayıtlı değil
|
||||
- Geçersiz hook sözdizimi
|
||||
- Hook scripti çalıştırılabilir değil
|
||||
|
||||
**Çözümler:**
|
||||
```bash
|
||||
# Hook'ların kayıtlı olduğunu kontrol et
|
||||
grep -A 10 '"hooks"' ~/.claude/settings.json
|
||||
|
||||
# Hook dosyalarının var olduğunu ve çalıştırılabilir olduğunu doğrula
|
||||
ls -la ~/.claude/plugins/cache/*/hooks/
|
||||
|
||||
# Hook'u manuel olarak test et
|
||||
bash ~/.claude/plugins/cache/*/hooks/pre-bash.sh <<< '{"command":"echo test"}'
|
||||
|
||||
# Hook'ları yeniden kaydet (eklenti kullanıyorsa)
|
||||
# Claude Code ayarlarında eklentiyi devre dışı bırak ve yeniden etkinleştir
|
||||
```
|
||||
|
||||
### Python/Node Sürüm Uyumsuzlukları
|
||||
|
||||
**Belirti:** "python3 not found" veya "node: command not found"
|
||||
|
||||
**Nedenler:**
|
||||
- Python/Node kurulumu eksik
|
||||
- PATH yapılandırılmamış
|
||||
- Yanlış Python sürümü (Windows)
|
||||
|
||||
**Çözümler:**
|
||||
```bash
|
||||
# Python 3'ü kur (eksikse)
|
||||
# macOS: brew install python3
|
||||
# Ubuntu: sudo apt install python3
|
||||
# Windows: python.org'dan indir
|
||||
|
||||
# Node.js'i kur (eksikse)
|
||||
# macOS: brew install node
|
||||
# Ubuntu: sudo apt install nodejs npm
|
||||
# Windows: nodejs.org'dan indir
|
||||
|
||||
# Kurulumları doğrula
|
||||
python3 --version
|
||||
node --version
|
||||
npm --version
|
||||
|
||||
# Windows: python'un (python3 değil) çalıştığından emin ol
|
||||
python --version
|
||||
```
|
||||
|
||||
### Dev Server Blocker Yanlış Pozitifleri
|
||||
|
||||
**Belirti:** Hook, "dev" içeren meşru komutları engelliyor
|
||||
|
||||
**Nedenler:**
|
||||
- Heredoc içeriği pattern eşleşmesini tetikliyor
|
||||
- Argümanlarda "dev" olan dev olmayan komutlar
|
||||
|
||||
**Çözümler:**
|
||||
```bash
|
||||
# Bu v1.8.0+'da düzeltildi (PR #371)
|
||||
# Eklentiyi en son sürüme yükselt
|
||||
|
||||
# Geçici çözüm: Dev sunucularını tmux'ta sarmalayın
|
||||
tmux new-session -d -s dev "npm run dev"
|
||||
tmux attach -t dev
|
||||
|
||||
# Gerekirse hook'u geçici olarak devre dışı bırak
|
||||
# ~/.claude/settings.json'u düzenle ve pre-bash hook'unu kaldır
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Kurulum ve Yapılandırma
|
||||
|
||||
### Eklenti Yüklenmiyor
|
||||
|
||||
**Belirti:** Kurulumdan sonra eklenti özellikleri kullanılamıyor
|
||||
|
||||
**Nedenler:**
|
||||
- Marketplace önbelleği güncellenmedi
|
||||
- Claude Code sürüm uyumsuzluğu
|
||||
- Bozuk eklenti dosyaları
|
||||
|
||||
**Çözümler:**
|
||||
```bash
|
||||
# Değiştirmeden önce eklenti önbelleğini incele
|
||||
ls -la ~/.claude/plugins/cache/
|
||||
|
||||
# Silmek yerine eklenti önbelleğini yedekle
|
||||
mv ~/.claude/plugins/cache ~/.claude/plugins/cache.backup.$(date +%Y%m%d-%H%M%S)
|
||||
mkdir -p ~/.claude/plugins/cache
|
||||
|
||||
# Marketplace'ten yeniden kur
|
||||
# Claude Code → Extensions → Everything Claude Code → Uninstall
|
||||
# Ardından marketplace'ten yeniden kur
|
||||
|
||||
# Claude Code sürümünü kontrol et
|
||||
claude --version
|
||||
# Claude Code 2.0+ gerektirir
|
||||
|
||||
# Manuel kurulum (marketplace başarısız olursa)
|
||||
git clone https://github.com/affaan-m/everything-claude-code.git
|
||||
cp -r everything-claude-code ~/.claude/plugins/ecc
|
||||
```
|
||||
|
||||
### Paket Yöneticisi Algılama Başarısız
|
||||
|
||||
**Belirti:** Yanlış paket yöneticisi kullanılıyor (pnpm yerine npm)
|
||||
|
||||
**Nedenler:**
|
||||
- Lock dosyası mevcut değil
|
||||
- CLAUDE_PACKAGE_MANAGER ayarlanmamış
|
||||
- Birden fazla lock dosyası algılamayı karıştırıyor
|
||||
|
||||
**Çözümler:**
|
||||
```bash
|
||||
# Tercih edilen paket yöneticisini global olarak ayarla
|
||||
export CLAUDE_PACKAGE_MANAGER=pnpm
|
||||
# ~/.bashrc veya ~/.zshrc'ye ekle
|
||||
|
||||
# Veya proje bazında ayarla
|
||||
echo '{"packageManager": "pnpm"}' > .claude/package-manager.json
|
||||
|
||||
# Veya package.json alanını kullan
|
||||
npm pkg set packageManager="pnpm@8.15.0"
|
||||
|
||||
# Uyarı: lock dosyalarını kaldırmak kurulu bağımlılık sürümlerini değiştirebilir.
|
||||
# Önce lock dosyasını commit et veya yedekle, ardından yeni bir kurulum yap ve CI'ı yeniden çalıştır.
|
||||
# Bunu sadece kasıtlı olarak paket yöneticilerini değiştirirken yap.
|
||||
rm package-lock.json # pnpm/yarn/bun kullanıyorsan
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performans Sorunları
|
||||
|
||||
### Yavaş Yanıt Süreleri
|
||||
|
||||
**Belirti:** Ajan yanıt vermek için 30+ saniye sürüyor
|
||||
|
||||
**Nedenler:**
|
||||
- Büyük gözlem dosyaları
|
||||
- Çok fazla aktif hook
|
||||
- API'ye ağ gecikmesi
|
||||
|
||||
**Çözümler:**
|
||||
```bash
|
||||
# Büyük gözlemleri silmek yerine arşivle
|
||||
archive_dir="$HOME/.claude/homunculus/archive/$(date +%Y%m%d)"
|
||||
mkdir -p "$archive_dir"
|
||||
find ~/.claude/homunculus/projects -name "observations.jsonl" -size +10M -exec sh -c '
|
||||
for file do
|
||||
base=$(basename "$(dirname "$file")")
|
||||
gzip -c "$file" > "'"$archive_dir"'/${base}-observations.jsonl.gz"
|
||||
: > "$file"
|
||||
done
|
||||
' sh {} +
|
||||
|
||||
# Kullanılmayan hook'ları geçici olarak devre dışı bırak
|
||||
# ~/.claude/settings.json'u düzenle
|
||||
|
||||
# Aktif gözlem dosyalarını küçük tut
|
||||
# Büyük arşivler ~/.claude/homunculus/archive/ altında olmalı
|
||||
```
|
||||
|
||||
### Yüksek CPU Kullanımı
|
||||
|
||||
**Belirti:** Claude Code %100 CPU tüketiyor
|
||||
|
||||
**Nedenler:**
|
||||
- Sonsuz gözlem döngüleri
|
||||
- Büyük dizinlerde dosya izleme
|
||||
- Hook'larda bellek sızıntıları
|
||||
|
||||
**Çözümler:**
|
||||
```bash
|
||||
# Kontrolden çıkmış işlemleri kontrol et
|
||||
top -o cpu | grep claude
|
||||
|
||||
# Sürekli öğrenmeyi geçici olarak devre dışı bırak
|
||||
touch ~/.claude/homunculus/disabled
|
||||
|
||||
# Claude Code'u yeniden başlat
|
||||
# Cmd/Ctrl+Q ardından yeniden aç
|
||||
|
||||
# Gözlem dosyası boyutunu kontrol et
|
||||
du -sh ~/.claude/homunculus/*/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Yaygın Hata Mesajları
|
||||
|
||||
### "EACCES: permission denied"
|
||||
|
||||
```bash
|
||||
# Hook izinlerini düzelt
|
||||
find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;
|
||||
|
||||
# Gözlem dizini izinlerini düzelt
|
||||
chmod -R u+rwX,go+rX ~/.claude/homunculus
|
||||
```
|
||||
|
||||
### "MODULE_NOT_FOUND"
|
||||
|
||||
```bash
|
||||
# Eklenti bağımlılıklarını kur
|
||||
cd ~/.claude/plugins/cache/everything-claude-code
|
||||
npm install
|
||||
|
||||
# Veya manuel kurulum için
|
||||
cd ~/.claude/plugins/ecc
|
||||
npm install
|
||||
```
|
||||
|
||||
### "spawn UNKNOWN"
|
||||
|
||||
```bash
|
||||
# Windows'a özgü: Scriptlerin doğru satır sonlarını kullandığından emin ol
|
||||
# CRLF'yi LF'ye dönüştür
|
||||
find ~/.claude/plugins -name "*.sh" -exec dos2unix {} \;
|
||||
|
||||
# Veya dos2unix'i kur
|
||||
# macOS: brew install dos2unix
|
||||
# Ubuntu: sudo apt install dos2unix
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Yardım Alma
|
||||
|
||||
Hala sorunlar yaşıyorsanız:
|
||||
|
||||
1. **GitHub Issues'ı Kontrol Edin**: [github.com/affaan-m/everything-claude-code/issues](https://github.com/affaan-m/everything-claude-code/issues)
|
||||
2. **Debug Logging'i Etkinleştirin**:
|
||||
```bash
|
||||
export CLAUDE_DEBUG=1
|
||||
export CLAUDE_LOG_LEVEL=debug
|
||||
```
|
||||
3. **Diagnostic Bilgisi Toplayın**:
|
||||
```bash
|
||||
claude --version
|
||||
node --version
|
||||
python3 --version
|
||||
echo $CLAUDE_PACKAGE_MANAGER
|
||||
ls -la ~/.claude/plugins/cache/
|
||||
```
|
||||
4. **Issue Açın**: Debug loglarını, hata mesajlarını ve diagnostic bilgiyi dahil edin
|
||||
|
||||
---
|
||||
|
||||
## İlgili Dokümantasyon
|
||||
|
||||
- [README.md](./README.md) - Kurulum ve özellikler
|
||||
- [CONTRIBUTING.md](./CONTRIBUTING.md) - Geliştirme rehberleri
|
||||
- [docs/](../) - Detaylı dokümantasyon
|
||||
- [examples/](./examples/) - Kullanım örnekleri
|
||||
Reference in New Issue
Block a user