Yapay zeka ile dokümantasyon: README’den changelog’a

Yapay zeka ile dokümantasyon yazmak için bir kodlama ajanının kodu okumasına ve belgelediği komutları çalıştırmasına izin ver, her belgeye net bir okur belirle ve bahsettiği her fonksiyonu, bayrağı ve örneği depoya karşı kontrol et. Claude Code ve Codex gibi ajanlar dokümantasyonun zahmetli kısımlarında iyidir: bir kod tabanını README’ye dönüştürmek, docstring’leri doldurmak, bir sürümü git geçmişinden özetlemek. Zayıf noktaları ise özgüvenleri: kulağa doğru gelen ama hiç yazılmamış bir seçeneği gönül rahatlığıyla anlatırlar.

Bu rehber bir ajanla neleri belgeleyeceğini, her belge türü için işe yarayan prompt’ları, git log’dan changelog üretmeyi, belgeleri senkron tutmayı, AGENTS.md’nin nereye oturduğunu ve yapay zekanın yazdığı belgeleri uydurma API’lere karşı nasıl inceleyeceğini anlatıyor.

Sohbet penceresi değil, ajan

En büyük kalite sıçraması modelin nerede yazdığından gelir. Bir dosyayı sohbet penceresine yapıştırıp belge istemek modele tek bir dosya verir ve hiçbir şeyi kontrol etme imkânı bırakmaz. Deponda çalışan bir kodlama ajanı ise şunları yapabilir:

• yalnızca yapıştırdığın dosyayı değil, kodun çağırdığı dosyaları da açar;
• --help’i, test paketini ya da az önce yazdığı örneği çalıştırır;
• bir fonksiyonun kullanıldığı her yeri arar;
• mevcut belgeleri okuyup üsluplarına uyar.

Aşağıdaki her prompt, ajanın depoda çalıştığını varsayıyor. Henüz kurmadıysan Claude Code nasıl kullanılır ve Codex CLI nasıl kullanılır yazıları seni oraya götürür.

Önce okuru belirle

“Bu proje için belge yaz” genel geçer bir sayfa üretir. Her belge türünün farklı bir okuru ve farklı bir doğruluk kaynağı vardır:

Okuru ve kaynağı prompt’a yaz. Sonucu herhangi bir üslup talimatından daha çok değiştirir.

README

İyi bir README dört soruyu hızla yanıtlar: bu nedir, nasıl kurarım, nasıl kullanırım, nasıl katkı veririm. Ajandan yazarken doğrulamasını iste:

Bu depo için README.md yaz. Okur: depoyu ilk kez gören bir geliştirici.
Bölümler: ne yaptığı (2-3 cümle), gereksinimler, kurulum, hızlı başlangıç,
yapılandırma, testleri çalıştırma, proje yapısı.

Kurallar:
- Komutları package.json betiklerinden ve CI workflow’undan al; her kurulum
  ve hızlı başlangıç komutunu çalıştır, biri başarısız olursa README’yi düzelt.
- Yalnızca kodda gerçekten okunan ortam değişkenlerini listele; her biri
  için dosyayı belirt.
- Rozet yok, pazarlama dili yok, kodda olmayan özellik yok.

Makul görünen bir README’yi doğru bir README’ye çeviren şey “her komutu çalıştır” talimatı. Ajan bir şeyi çalıştıramıyorsa (örneğin kimlik bilgisi gerekiyorsa) o adımı doğrulanmadı diye işaretlemesini iste ki elle kontrol et.

API referansı

Kütüphaneler ve servisler için referans malzemesinin olabildiğince fazlasını kaynaktan üret; ajanı da üreticilerin yazamadığı kısımlar için kullan: genel bakışlar, örnekler ve çetrefilli davranışların açıklamaları.

Bir HTTP API’si için ajandan referansı doğrudan route tanımlarından çıkarmasını iste:

src/routes altındaki her HTTP endpoint’ini belgele. Her biri için: metot,
yol, kimlik doğrulama gereksinimi, tipleriyle istek gövdesi ve sorgu
parametreleri, yanıt yapısı, hata durum kodları. Handler’ı ve doğrulama
şemasını oku; isimlerden çıkarım yapma. Her endpoint için bir curl örneği
ekle ve yerel geliştirme sunucusunda çalıştır.

Proje zaten OpenAPI kullanıyorsa ajana ayrı bir Markdown referansı yazdırmak yerine spec dosyasını güncellet ve onu mevcut araçlarının göstermesine bırak. Tek bir doğruluk kaynağını dürüst tutmak, iki kaynağı tutmaktan kolaydır.

Docstring ve JSDoc

Ajanlar bir modül boyunca docstring doldurmakta hızlıdır, ama bir fonksiyonun ne yaptığını değil ne yapması gerektiğini en sık burada anlatırlar. Gövdede görünen davranışı iste:

src/billing/ altındaki her export edilen fonksiyona JSDoc ekle. Her biri
için: tek satırlık özet, tipi ve anlamıyla @param, @returns ve fonksiyonun
gerçekten fırlatabildiği her hata için @throws (gövdeyi ve çağırdığı
fonksiyonları oku). @example’ı yalnızca çalıştırırsan ekle.
Hiçbir kodu değiştirme.

İki ucuz kontrol docstring’leri güvenilir yapar:

• JS projelerinde TypeScript: dosyanın başında // @ts-check ya da tsconfig.json içinde checkJs varsa TypeScript JSDoc tiplerini denetler; yanlış bir @param tipi hata olarak görünür.
• Python: doctest biçiminde (>>> satırları) yazılmış örnekler python -m doctest module.py -v ile çalıştırılabilir; koddan sapan bir örnek kırılır.

İşe yarar bir kural: bir docstring imzayı tekrarlamamalı, neden ve ne için sorularını yanıtlamalı. getUser(id): User üzerindeki “Kullanıcıyı döndürür” gürültüdür; “Yumuşak silinmiş kullanıcılar için null döner; çağıranlar bunu ele almalı” ise değerlidir. Bunu ajana söyle.

Mimari notlar

Mimari belgeler ajanların en çok zaman kazandırdığı yerdir, çünkü zor kısım çok miktarda kodu okuyup özetlemektir. Halüsinasyonların en iyi saklandığı yer de burasıdır, çünkü kimse bir diyagramı satır satır kontrol etmez. Ajanı sınırla:

Kod tabanına yeni gelen mühendisler için docs/architecture.md yaz.
Kapsam: ana modüller ve her birinin sorumluluğu, bir isteğin HTTP
katmanından veritabanına nasıl aktığı, arka plan işleri ve dış servisler.
Her iddia için geldiği dosyayı (ve fonksiyonu) belirt.
İstek akışı için bir Mermaid diyagramı ekle.
Emin olmadığın her şeyi "TODO: doğrula" ile işaretle.

Asıl mesele kaynak göstermek: inceleyen kişinin iddiaları saniyeler içinde yoklamasını sağlar ve o dosyalar değiştiğinde hangi kısımların eskiyeceğini gösterir. Yalnızca neyin var olduğunu değil, kararların neden alındığını da kaydet; kısa bir karar kaydı (ADR tarzı: bağlam, karar, sonuçlar) mevcut kodun tarifinden daha iyi yaşlanır. Yapay zeka ajanları için kod haritası yazısı, ajanlara gezinebilecekleri bir genel bakış vermeyi ele alıyor.

git log’dan changelog

Sürüm notları bir ajan için biçilmiş kaftandır: ham malzeme git’te, iş ise onu kullanıcılar için süzüp yeniden yazmak. Son etiketten bu yana olan aralıkla başla:

git describe --tags --abbrev=0
git log v1.4.0..HEAD --no-merges --pretty=format:'%h %s%n%b'

Sonra prompt:

git log v1.4.0..HEAD --no-merges çıktısından bir sonraki sürüm için
CHANGELOG.md girdisini yaz. Okur: sürüm yükselten kullanıcılar.
Keep a Changelog başlıklarını kullan (Added, Changed, Deprecated,
Removed, Fixed, Security). Refactor, test, CI ve ufak işleri atla.
Her maddeyi kullanıcının diliyle yeniden yaz, geriye uyumsuz değişiklikleri
yükseltme adımlarıyla en üste koy ve her maddenin yanında kısa hash’i tut.

Ekibin Conventional Commits kullanıyorsa (feat:, fix:, geriye uyumsuz değişiklikler için feat!:) bunu belirt; ajan türe göre güvenilir şekilde sıralayabilir. Commit mesajları kısaysa önemli maddeler için ajanın diff’i (git show <hash>) ya da bağlantılı pull request’i okumasına izin ver. Her satırın yanında hash’i tutmak incelemeyi hızlandırır: bir maddeyi commit’ini açarak kontrol edersin.

Belgeleri senkron tutmak

Belgeler, kimsenin planlamadığı ayrı bir adımda güncellendikleri için çürür. Çözüm belgeleri değişikliğin parçası yapmak:

1. Aynı değişiklik, aynı ajan. Ajan kurallarına tek bir satır ekle: “Davranışı, bayrakları, ortam değişkenlerini ya da genel API’leri değiştirdiğinde ilgili belgeleri aynı commit’te güncelle.”

2. Her görevin sonunda bir belge kontrolü iste:

   Değiştirdiğin koddan bahseden her belgeyi, README bölümünü, docstring’i
   ve örneği listele. Artık yanlış olanları güncelle.

3. Birleştirmeden önce dalı kontrol et: ajana diff’i (git diff main...HEAD) ve belge klasörünü ver, diff’in belgelerdeki hangi ifadeleri yanlış hâle getirdiğini sor.

4. Örnekleri test olarak çalıştır. Doctest’ler, README parçalarını çalıştıran bir betik ya da tip denetimli JSDoc, eskimiş belgeleri kırılan build’lere dönüştürür.

5. Üretebildiğini üret. Kaynaktan üretilen CLI yardım metni, OpenAPI spec’leri ve tip referansları koddan sapamaz.

AGENTS.md senin dokümantasyonun değil

AGENTS.md (Codex ve birçok başka ajan okur) ve CLAUDE.md (Claude Code okur) kodlama ajanları için talimat dosyalarıdır. Her oturuma yüklenirler, bu yüzden kısa olmalıdırlar: build ve test komutları, kurallar, dokunulmaması gereken klasörler. Claude Code’da ya da Codex’te /init çalıştırmak ilk sürümü üretir.

İnsanlar için yazılan dokümantasyonun işi farklıdır ve gerektiği kadar uzun olabilir. İkisini karıştırmak iki sorun doğurur: uzun bir AGENTS.md her görevde ajanın bağlamını boşa harcar, ajan kurallarıyla dolu bir README ise insanların kafasını karıştırır. Ayrı tut ve aralarında bağlantı ver:

# AGENTS.md
## Commands
- Test: pnpm test
## Docs
- Architecture overview: docs/architecture.md (read before changing modules)
- When you change public APIs, update docs/api.md in the same commit.

CLAUDE.md nasıl yazılır yazısı bu dosyalara neyin girdiğini ve tek bir kural setini ajanlar arasında nasıl paylaşacağını anlatıyor.

Yapay zekanın yazdığı belgeleri uydurma API’lere karşı incele

En zararlı belge hatası var olmayan bir API’dir: benzer projelerde olduğu için modelin uydurduğu bir yapılandırma seçeneği, CLI bayrağı ya da metot. Okurlar belgelere güvenir, bu yüzden belgenin yanlış olduğundan şüphelenene kadar zaman kaybederler. Bunu bilerek incele:

• Her adı grep’le. Ajandan (ya da ikinci bir ajandan) yeni belgelerde geçen her fonksiyonu, seçeneği, bayrağı, ortam değişkenini ve endpoint’i çıkarıp kodda aramasını iste. Bulunamayan her şey silinir.

  docs/api.md içindeki her tanımlayıcıyı, CLI bayrağını, yapılandırma
  anahtarını ve ortam değişkenini çıkar. Her biri için kodda tanımlandığı
  yeri dosya:satır olarak göster ya da BULUNAMADI yaz. Hiçbir şeyi düzenleme.

• Her örneği çalıştır. Hiç çalıştırılmamış kod blokları tahmindir.

• Varsayılanları ve sınırları kontrol et. Sayılar (zaman aşımları, boyutlar, yeniden denemeler) sıklıkla uydurulur; her biri koddaki bir sabite kadar izlenebilmeli.

• “Ayrıca destekler” cümlelerine dikkat et. “Ayrıca YAML yapılandırmasını destekler” ya da “Redis ile kullanılabilir” gibi satırlar klasik dolgulardır. Bunu yapan kodu iste.

• İkinci bir inceleyici kullan. Belgeleri koda karşı inceleyen ayrı bir ajan, onları yazan ajana göre daha tarafsızdır. Yapay zeka ile kod incelemesi yazısı bunun kurulumunu anlatıyor.

AgentVera ile dokümantasyon

AgentVera, Claude Code, Codex, Gemini CLI ve diğer CLI ajanlarını yan yana çalıştıran, macOS, Windows ve Linux için bir masaüstü uygulaması. Araçlarından birkaçı belge işine yardım ediyor:

• Yazan ve kontrol eden yan yana: aynı çalışma alanında bir ajan belgeleri yazarken ikincisi onları koda karşı kontrol etsin ya da belge işine kendi worktree’sini ver.
• Spec’ler sekmesi: deponun Markdown dosyalarını en yeniden başlayarak spec, plan ve belge olarak ayırıp listeler; ajanların başka worktree’lerde yazdığı commit’lenmemiş dosyalar da buna dahil. Markdown önizlemede açılır.
• Brain: README, ARCHITECTURE, CHANGELOG, ADR’ler, commit’ler ve PR’ları okur, kararları gerekçeleriyle listeler ve kod terimleri artık kodda geçmeyenleri işaretler; eskimiş belgeler için işe yarar bir sinyal.
• Proje turu: bir deponun teknoloji yığınını, modüllerini ve önemli dosyalarını özetleyen salt okuma bir Claude Code çalıştırması; mimari notlar için iyi bir ilk taslak.
• Kod incelemesi: bir ajanın belge değişikliklerini seçtiğin Claude modeliyle incelet; bulgular dosya ve satıra bağlı gelir.
• Git paneli: changelog’u ürettiğin geçmişte gezin ve commit mesajlarını deponun üslubunda Claude Haiku’ya yazdır; bu da bir sonraki changelog’u kolaylaştırır.

Sonuç

Yapay zeka dokümantasyon yazmayı ucuzlatıyor, bu da asıl işi doğruluğa kaydırıyor. Ajanı depo içinde çalıştır, ona okurun kim olduğunu ve doğrunun nerede durduğunu söyle, komutları ve örnekleri çalıştırmasını iste, changelog’ları hash’leri koruyarak git log’dan üret. Belgeleri kodla aynı değişiklikte güncelle, AGENTS.md’yi ajanlara, belgeleri insanlara ayır ve yayımlamadan önce belgelenen her adı grep’le. Bir belge bunun yerine bir hatayı ortaya çıkarırsa yapay zeka ile hata ayıklama yazısı oradan devam ediyor.