Hiç eksik, tutarsız ve güncel olmayan bir dokümantasyon miras aldıysanız, sorunu biliyorsunuzdur: ekipler iyi niyetlerle dokümanlar oluşturur, ancak titiz bir inceleme olmadan netlik kaybolur. API parametreleri belgelenmez. Hata yanıtlarında rehberlik eksikliği olur. Örnekler sessizce bozulur. Terminoloji dosyalar arasında farklılık gösterir.
Claude Code Yetenekleri bunu sistematik olarak çözer. Bu yapay zeka destekli iş akışları, tüm dokümantasyon deponuzu inceler, boşlukları ve tutarsızlıkları belirler ve düzeltmeleri doğrudan uygular. Ne incelenmesi gerektiğini siz tanımlarsınız, Claude yapılandırılmış bir denetim oluşturur, iyileştirmeler uygular ve eksiksizliği terminalinizden doğrular.
Teknik dokümantasyon; API spesifikasyonlarını, kullanıcı kılavuzlarını, dağıtım kılavuzlarını ve sürüm notlarını kapsar. Claude Code, tüm bunları incelemeyi otomatikleştirir. Özellikle API dokümantasyonu için, görsel doğrulama ve eksiksizlik puanlaması için Apidog ile birleştirin.
Dokümantasyon için Claude Code Yeteneklerini Anlama
Dokümantasyon Yetenekleri Nelerdir?
Claude Code Yetenekleri, Claude Code'un dokümantasyon yeteneklerini genişleten özel, yeniden kullanılabilir yapay zeka iş akışlarıdır. Bunları, şunları yapabilen akıllı dokümantasyon denetçileri olarak düşünebilirsiniz:
- Tüm dokümantasyon deponuzu okuma ve bağlamı anlama
- Spesifikasyonları uygulamalar ve kılavuzlarla çapraz referanslama
- Eksik bölümleri, belirsiz dili ve tutarsızlıkları belirleme
- Dosya konumları ve satır numaralarıyla belirli iyileştirmeler önerme
- Düzeltmeleri doğrudan dosyalarınıza uygulama ve değişiklikleri doğrulama
Sözdizimini kontrol eden geleneksel lint araçlarının aksine, yetenekler Claude'un muhakeme yeteneğini kullanarak anlamsal sorunları (belirsiz açıklamalar, eksik hata dokümantasyonu, tutarsız örnekler) anlar.
Yetenekler Nasıl Çalışır?
Yetenekler çeşitli mekanizmalar aracılığıyla çalışır:
1. Kullanıcı Tarafından Çağrılabilir Komutlar
# Bir yeteneği slash komutuyla çalıştırın
/review-docs --completeness
/check-consistency --terminology
/validate-api-specs
/update-broken-examples
2. İzin Verilen Araçlar
Yetenekler, hangi araçları kullanabileceklerini belirtir:
Bash: Doğrulama komutlarını çalıştırınRead,Write,Edit: Dokümantasyon dosyalarını yönetinGlob,Grep: Dokümanlarda arama yapınWebFetch: Harici referansları alınTask: Karmaşık incelemeler için alt görevler oluşturun
3. Planlama Dosyaları
Yetenekler, inceleme ilerlemesini, belirlenen sorunları ve uygulanan düzeltmeleri izlemek için markdown dosyalarını kullanarak durumu korur.
Yetenekler Neden Dokümantasyon İncelemede Üstündür?
Geleneksel dokümantasyon incelemesi manuel ve tutarsızdır. Yetenekler zeka ve ölçek getirir:
- Bütünsel Anlayış: Tüm dosyaları inceler, dosyalar arası desenleri yakalar
- Tutarlı Standartlar: Her dosyaya aynı kalite kriterlerini uygular
- Bağlamsal Öneriler: Bir şeyin neden yanlış olduğunu anlar, sadece yanlış olduğunu değil
- Otomasyon: Dokümantasyon geliştikçe sürekli inceleyebilir
- Hız: Yüzlerce sayfayı dakikalar içinde analiz eder, manuel inceleme saatler sürerken
Temel Dokümantasyon İnceleme Yetenekleri
1. Eksiksizlik Analizi
İstek: "API dokümantasyonunu eksiksizlik açısından denetleyin. Her bir uç noktayı şunlar açısından kontrol edin: parametreler, istek örnekleri, tüm hata yanıtları ve hız sınırlaması."
Claude şunları oluşturur:
POST /users uç noktasından eksik:
- [ ] İstek gövdesi parametre açıklamaları
- [ ] Hata yanıtı dokümantasyonu (400, 401, 409)
- [ ] Hız sınırlama bilgileri
- [ ] Güvenlik/kimlik doğrulama gereksinimleri
2. Tutarlılık Tespiti
İstek: "/docs/ içinde terminoloji tutarlılığını inceleyin. Birden fazla kez farklı anlamlarla görünen terimleri işaretleyin."
Claude şunları belirler:
Tutarsız terminoloji bulundu:
- "API key" vs "access token" vs "auth token" (birini kullanın)
- "endpoint" vs "route" vs "method" (birini kullanın)
- "user object" vs "user resource" (birini kullanın)
3. Çapraz Referans Doğrulaması
İstek: "/api/openapi.yaml dosyasındaki OpenAPI spesifikasyonunu /docs/api/ içindeki dokümantasyonla karşılaştırın. Belgelenmiş ancak kodda olmayan veya kodda olan ancak belgelenmemiş uç noktaları işaretleyin."
Claude şunları tespit eder:
Tutarsızlıklar bulundu:
- POST /api/webhooks belgelenmiş ancak openapi.yaml içinde yok
- PATCH /api/users kodda mevcut ancak dokümanlarda eksik
- Yanıt şeması değişti ancak örnek güncellenmedi
4. Netlik Değerlendirmesi
İstek: "Netlik açısından inceleyin. Belirsiz açıklamaları, tanımlanmamış terimleri ve muğlak talimatları işaretleyin."
Claude şunları belirler:
Netlik sorunları:
- Satır 45: "Yapılandırmayı uygun değerlere ayarlayın" - hangi değerlere?
- Satır 120: "kullanıcı nesnesi" şema tanımı olmadan kullanılmış
- Satır 200: "gerekli alanlar" - hangileri?
5. Örnek Doğrulaması
İstek: "Tüm kod örneklerini inceleyin. Mevcut API şemasına göre test edin. Bozuk veya güncel olmayan örnekleri işaretleyin."
Claude şunları günceller:
Güncellenmiş örnekler:
- curl örneği: Yanıt formatı değişti, payload güncellendi
- Python örneği: Eski parametre kullanıyor, düzeltildi
- JavaScript örneği: Hata yönetimi eksik, eklendi
Dokümantasyon Yeteneği Anatomisi
Dizin Yapısı
Dokümantasyon yetenekleri, aşağıdaki düzenle .claude/skills/ içinde yer alır:
.claude/
├── skills/
│ ├── docs-completeness/
│ │ ├── SKILL.md # Yetenek bildirimi
│ │ ├── planning.md # İnceleme ilerlemesi
│ │ └── criteria.md # Kalite kontrol listesi
│ ├── api-validation/
│ │ ├── SKILL.md
│ │ └── schemas/ # API şemaları
│ └── consistency-check/
│ └── SKILL.md
└── skills.md # Tüm yeteneklerin indeksi
SKILL.md Bildirimi
Her dokümantasyon yeteneği, YAML ön bilgisiyle başlar:
---
name: docs-completeness
version: "1.0.0"
description: Dokümantasyonu eksiksizlik ve netlik açısından incele
user-invocable: true
allowed-tools:
- Read
- Write
- Grep
- Glob
- Edit
hooks:
SessionStart:
- matcher: command
command: "echo '[Doküman İncelemesi] Dokümantasyon denetimi başlatılıyor...'"
Stop:
- matcher: command
command: "echo '[Doküman İncelemesi] Denetim tamamlandı. Bulguları yukarıda inceleyin.'"
---
# Dokümantasyon Eksiksizlik Yeteneği
Teknik dokümantasyonu eksiksizlik ve netlik açısından inceler.
## Kullanım
```bash
/docs-completeness # Tüm depo denetimi
/docs-completeness --api-only # Yalnızca API dokümanları
/docs-completeness --section api/endpoints.md # Belirli dosya
Claude İçin Talimatlar
Çağrıldığında:
- Kapsam tespiti → Hedef dosyaları veya tüm depoyu belirle
- Eksiksizlik analizi → Her bölümü kontrol listesine göre kontrol et
- Sorun toplama → Tüm sorunları konumlarıyla birlikte topla
- Önceliklendirme → Etkiye göre sırala (eksik vs. belirsiz vs. tutarsız)
- Rapor oluşturma → Yapılandırılmış bulguları çıktı olarak ver
- Düzeltme önerileri → Belirli iyileştirmeler sun
- Doğrulama → Uygulamadan önce düzeltmeleri doğrula
İlk Dokümantasyon Yeteneğinizi Oluşturma
Uygulamalı olarak dalın: Eksiklikleri denetlemek ve API dokümanlarının kapsamlı ve geliştiriciye hazır olmasını sağlamak için kullanışlı bir araç oluşturacağız. Bunu kişisel doküman uygulayıcınız olarak düşünün.
Adım 1: Yetenek Klasörünü Kurun
Yapıyı basit bir komutla başlatın. Claude'un yetenekleri kolay keşfedilmesi için özel bir yerde bulunur.
Bash
mkdir -p .claude/skills/api-docs-reviewAdım 2: Yetenek Bildirimini Yazın
.claude/skills/api-docs-review/SKILL.md dosyasını oluşturun:
---
name: api-docs-review
version: "1.0.0"
description: API dokümantasyonunu eksiksizlik açısından incele
user-invocable: true
allowed-tools:
- Read
- Write
- Grep
- Edit
---
# API Dokümantasyon İnceleme Yeteneği
API dokümantasyonunu eksiksizlik, netlik ve doğruluk açısından denetler.
## İnceleme Kriterleri
Her uç nokta şunları içermelidir:
**Temel Bilgiler**
* Uç noktanın ne yaptığının net açıklaması
* HTTP metodu ve yolu
* Kimlik doğrulama gereksinimleri
**İstek Dokümantasyonu**
* Tüm yol parametreleri (türleri ve açıklamalarıyla)
* Tüm sorgu parametreleri (varsayılanları ve kısıtlamalarıyla)
* İstek gövdesi şeması (POST/PUT/PATCH için)
* Content-Type başlık gereksinimleri
* Örnek istek (curl veya dile özgü)
**Yanıt Dokümantasyonu**
* Başarı yanıtı (200/201) (şeması ve örneğiyle)
* Tüm hata yanıtları (400, 401, 403, 404, 409, 429, 500) (örnekleriyle)
* Hız sınırlaması bilgisi
* Yanıt başlıkları (ilgiliyse)
**Ek Bilgiler**
* İlgili uç noktalar veya kılavuzlar
* Varsa sürüm geçmişi
* Kullanım dışı bırakma uyarıları (kullanım dışı bırakıldıysa)
## Talimatlar
Çağrıldığında:
1. /docs/api/ içindeki **uç nokta dosyalarını tara**
2. Her bir uç noktayı inceleme kriterlerine göre **kontrol et**
3. Belirli dosya/satır referanslarıyla **eksik öğeleri kaydet**
4. **Netlik sorunlarını belirle** (belirsiz açıklamalar, tanımlanmamış terimler)
5. **Tutarlılık sorunlarını işaretle** (terminoloji kayması, format farklılıkları)
6. Gerekli düzeltmelerin **kontrol listesini oluştur**
7. **Düzeltmeleri örneklerle uygulama teklifinde bulun**
Rapor formatı:
UÇ NOKTA: POST /api/users Dosya: docs/api/users.md Durum: %65 Tamamlandı
Eksik:
- [ ] Hata yanıtı dokümantasyonu (400, 401, 409)
- [ ] Hız sınırlaması bilgileri
- [ ] İstek gövdesi şeması tanımı
Sorunlar:
- Satır 45: "kullanıcı nesnesi" tanımlanmamış - şemaya bağlantı ekle
- Satır 60: Örnek güncel değil - yanıt formatı değişti
Mevcut düzeltmeler: Evet (uygulamayı iste)
Adım 3: Yeteneği Kaydedin
.claude/skills.md dosyasına ekleyin:
# Mevcut Dokümantasyon Yetenekleri
## API Dokümantasyonu
### /api-docs-review
API dokümantasyonunu standart kriterlere göre eksiksizlik açısından denetleyin.
- **Sürüm**: 1.0.0
- **Kullanım**: `/api-docs-review [--file YOL] [--endpoint AD]`
- **Ne zaman kullanılmalı**: API sürümünden önce, kod değişikliklerinden sonra
- **Süre**: Orta büyüklükteki API için 5-10 dakika
Adım 4: Yeteneği Test Edin
# Claude Code içinde
/api-docs-review
Claude artık API dokümantasyonunuzu sistematik olarak denetleyecektir.
Gelişmiş Dokümantasyon Desenleri
Desen 1: Sürümlü Dokümantasyon Takibi
Yetenekler, sürümler arasında dokümantasyon kalitesini takip edebilir:
## Sürüm Geçmişi
### v2.0.0 [2026-01-22]
Eksiksizlik: %95 ✅
- Tüm uç noktalar belgelenmiş
- Hata yanıtları tamamlanmış
- Örnekler güncellenmiş
- Kullanım dışı bırakılan /v1 uç noktaları işaretlenmiş
### v1.0.0 [2025-12-01]
Eksiksizlik: %70
- Eksik hata dokümantasyonu
- Güncel olmayan örnekler
- Kullanım dışı bırakma uyarıları yok
Claude zaman içinde yapılan iyileştirmeleri tespit eder.
Desen 2: Koda Karşı API Spesifikasyon Doğrulaması
Yetenekler, OpenAPI spesifikasyonlarının uygulama ile eşleşip eşleşmediğini doğrulayabilir:
## Spesifikasyon Doğrulaması
/api/openapi.yaml dosyasını koda karşı karşılaştırın:
1. **Uygulamayı tara** tüm rotalar için
2. Her bir rota için **OpenAPI spesifikasyonunu kontrol et**
3. **Eksik uç noktaları işaretle**
4. **Parametrelerin** uygulamayla eşleştiğini doğrula
5. Mevcut şemaya uygun **örnekleri güncelle**
Sonuç: Spesifikasyon kodla %100 senkronize
CI/CD ile Otomasyon
Dokümantasyon Doğrulama Hattı
Her dokümantasyon güncellemesinde otomatik kontroller kurun:
# .github/workflows/docs-check.yml
name: Dokümantasyon Kontrolü
on:
push:
paths:
- 'docs/**'
- 'api/openapi.yaml'
pull_request:
paths:
- 'docs/**'
- 'api/openapi.yaml'
jobs:
validate-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Apidog CLI Kur
run: npm install -g apidog-cli
- name: OpenAPI Spesifikasyonunu Doğrula
run: |
apidog lint api/openapi.yaml
apidog check-completeness api/openapi.yaml --min-score 85
- name: Bozuk Bağlantıları Kontrol Et
run: |
npm install -g markdown-link-check
find docs -name "*.md" -exec markdown-link-check {} \;
- name: Örneklerin Geçerliliğini Doğrula
run: |
# curl örneklerinin çalıştığını test et
bash scripts/test-curl-examples.sh
- name: PR'a Yorum Yap
if: failure()
uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '❌ Dokümantasyon doğrulaması başarısız oldu. İş akışı günlüklerini inceleyin.'
})
Gerçek Dünya Senaryosu: API Dokümantasyon Eksiksizliği
Gerçekçi bir API dokümantasyon setini eksiksizlik açısından denetleyelim ve iyileştirmeler uygulayalım.
Senaryo
6 aylık bir REST API dokümantasyonunuz var. Kısmen tamamlanmış, ancak hata dokümantasyonu eksik, bazı yerlerde belirsiz ve güncel olmayan örnekler içeriyor.
Denetim
Claude'a istek: "/docs/api/ içindeki dokümantasyonu denetleyin. Her uç nokta için şunları kontrol edin: açıklama, istek parametreleri, yanıt örneği ve tüm hata yanıtları. Düzeltmeleri etkiye göre önceliklendirin."
DENETİM SONUÇLARI
=============
KRİTİK (Eksik hata dokümanları):
├── POST /api/users - Eksik 400, 401, 409 hata yanıtları
├── POST /api/auth/login - Eksik 429 (hız sınırı) yanıtı
└── DELETE /api/resources/{id} - Eksik 403 (yasak) yanıtı
YÜKSEK (Netlik sorunları):
├── users.md:45 - "kullanıcı nesnesi" tanımlanmamış
├── auth.md:60 - "Bitiş süresini uygun değere ayarla" - çok belirsiz
└── resources.md:30 - Sayfalandırma imleç formatının açıklaması eksik
ORTA (Güncel olmayan örnekler):
├── products.md:120 - cURL örneği eski format döndürüyor
├── orders.md:80 - Python SDK örneği kullanım dışı bırakılmış parametre kullanıyor
└── webhooks.md:60 - Node.js örneğinde hata yönetimi eksik
TUTARLILIK:
├── "API key" vs "access token" - 5 örnekte tutarsızlık
├── İstek gövdesi formatı - uç noktalar arasında 3 farklı stil
└── Hata yanıtı şeması - 1 yerine 2 varyasyon
Öncelikli düzeltmeler: toplam 15
Tahmini efor: manuel 2-3 saat, Claude Code ile 15 dakika
İyileştirmeler
Düzeltmeleri sistematik olarak uygulayarak:
Önce - POST /api/users (Eksik):
## Kullanıcı Oluştur
POST /api/users
Yeni bir kullanıcı oluşturur.
**Parametreler:**
- name: Kullanıcının adı
- email: Kullanıcının e-postası
**Yanıt:**
```json
{
"id": "usr_123",
"name": "Alice",
"email": "alice@example.com"
}
**Sonra - POST /api/users (Tamamlanmış):**
```markdown
## Kullanıcı Oluştur
`POST /api/users`
Sağlanan ayrıntılarla yeni bir kullanıcı hesabı oluşturur. E-posta benzersiz olmalıdır.
### Kimlik Doğrulama
`Authorization` başlığında API anahtarı gerektirir: `Bearer YOUR_API_KEY`
### İstek Parametreleri
| Parametre | Tür | Gerekli | Açıklama |
|-----------|------|----------|-------------|
| `name` | string | Evet | Tam ad (2-100 karakter) |
| `email` | string | Evet | Geçerli e-posta (benzersiz olmalı) |
| `role` | string | Hayır | Rol: `admin`, `developer`, `viewer`. Varsayılan: `viewer` |
### İstek Örneği
```bash
curl -X POST https://api.example.com/v1/users \
-H "Authorization: Bearer sk_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"name": "Alice Smith",
"email": "alice@example.com",
"role": "developer"
}'
Yanıt (201 Oluşturuldu)
{
"id": "usr_abc123",
"name": "Alice Smith",
"email": "alice@example.com",
"role": "developer",
"created_at": "2026-01-22T10:30:00Z"
}
Hata Yanıtları
400 Hatalı İstek - Geçersiz giriş
{
"error": "validation_error",
"message": "Geçersiz e-posta formatı",
"field": "email",
"request_id": "req_xyz789"
}
401 Yetkilendirilmemiş - Eksik/geçersiz API anahtarı
{
"error": "unauthorized",
"message": "Geçersiz API anahtarı",
"request_id": "req_xyz789"
}
409 Çakışma - E-posta zaten mevcut
{
"error": "conflict",
"message": "Bu e-postaya sahip kullanıcı zaten mevcut",
"request_id": "req_xyz789"
}
429 Çok Fazla İstek - Hız sınırlandırıldı
{
"error": "rate_limited",
"message": "Çok fazla istek. 60 saniye sonra tekrar deneyin.",
"retry_after": 60,
"request_id": "req_xyz789"
}
Hız Sınırlaması
Her API anahtarı için dakikada 100 istek. Bkz. Hız Sınırlamaları.
**Uygulanan iyileştirmeler:**
- Kimlik doğrulama gereksinimleri eklendi
- Tüm parametreler kısıtlamalarıyla belgelendi
- Başarılı + tüm hata yanıtları tamamlandı
- Üretime hazır cURL örneği
- Hız sınırlama bilgileri
- Tutarlı formatlama
Claude'u Apidog ile Entegre Ederek Üstün API Dokümantasyonu Elde Etme
💡 Profesyonel İpucu: Anlatım dokümanlarının içgörülü incelemeleri için Claude'u kullanın, Apidog ise API spesifikasyonlarınızın sağlam olmasını sağlar ve pratik örneklerle boşlukları otomatik olarak doldurur.
Claude için Önerilen İstek:"/docs/api/ klasörünü genel netlik ve etkileyicilik açısından inceleyin. Ardından, /api/openapi.yaml dosyasının eksiksizliğini Apidog kullanarak çapraz kontrol edin. Herhangi bir tutarsızlığı veya eksik öğeyi vurgulayın, böylece devam etmeden önce bunları doğrudan Apidog'da düzeltebilirim."
Bash
# Adım 1: Claude Aracılığıyla İlk Metin İncelemesi
> /docs-completeness # Daha net dil ve yapı için öneriler çıktısı verir
# Adım 2: Apidog'da API Spesifikasyon Doğrulaması
apidog check-completeness api/openapi.yaml # Eksik şemalar veya eksik yanıtlar gibi sorunları işaretler
# Adım 3: Apidog'un Yapay Zekası ile İçerik Otomatik Oluşturma
# (Apidog kullanıcı arayüzü aracılığıyla: Ayarlar → Yapay Zeka → Açıklamaları, örnekleri ve özetleri otomatik oluştur)
# Adım 4: Claude ile Son Uyum Kontrolü
> /consistency-check # Dokümanların ve spesifikasyonun mükemmel şekilde hizalandığından emin olurBu, Apidog'un yapılandırılmış spesifikasyon doğrulamasını, Claude Code'un ise metin kalitesini yönettiği bir iş akışı oluşturur.
Dokümantasyon İncelemesi İçin En İyi Uygulamalar
Kitlenizi Tanıyın
Dokümantasyon derinliğini okuyuculara göre uyarlayın:
| Kitle | Stil | Örnek |
|---|---|---|
| Geliştiriciler | Çoklu dillerde kod örnekleri | cURL, Python, JS |
| DevOps | Dağıtım adımları, yapılandırma | Kubernetes YAML örnekleri |
| Ürün ekipleri | Üst düzey iş akışları, diyagramlar | Ekran görüntüleriyle özellik akışları |
| Destek | Sorun giderme, sık karşılaşılan sorunlar | "Hata 429 şu anlama gelir..." |
Netliği Önceliklendirin
Aktif dilde yazın, taramaya uygun bir yapı oluşturun:
❌ Önce: "İstek POST aracılığıyla gönderilir. Yanıt kullanıcıyı içerecektir."
✅ Sonra: "Kullanıcı oluşturmak için bir POST isteği gönderin. API yeni kullanıcıyı döndürür."
Her Zaman Örnekler Ekleyin
Soyut kavramların bir dayanağa ihtiyacı vardır. Her API uç noktası şunları gerektirir:
# ✅ Kopyala-yapıştır yapmaya hazır
curl -X GET https://api.example.com/v1/users/usr_123 \
-H "Authorization: Bearer YOUR_API_KEY"
Yaygın Tuzaklar
| Tuzak | Çözüm |
|---|---|
| Jargon yoğunluğu | Terimleri ilk kullanımda tanımlayın |
| Güncel olmayan örnekler | CI/CD'de test edin |
| Eksik hata dokümanları | Tüm hata kodlarını belgeleyin |
| Tutarsız biçimlendirme | Şablonlar kullanın |
| Bozuk bağlantılar | CI/CD'de kontrol edin |
Sonuç
Claude Code Yetenekleri, teknik dokümantasyon incelemesini sıkıcı manuel bir süreçten akıllı, otomatik bir iş akışına dönüştürür. Ne incelenmesi gerektiğini siz tanımlarsınız ve Claude tüm dokümantasyon deponuzu denetler, boşlukları ve tutarsızlıkları belirler ve kalite standartlarını korurken düzeltmeleri uygular.
API spesifikasyon doğrulama için Apidog ile birleştirildiğinde, kapsamlı dokümantasyon kapsamı elde edersiniz.