Kazanimlar:
- Yapay zekayı whitepaper, NatSpec, teknik-sade çeviri ve risk açıklaması üretmede güvenle kullanıp bunun en verimli alan olduğunu kavrayabilme
- Her teknik iddiayı gerçek kodla teyit edip abartılı ve garanti dilini kaldırarak yanlış dokümantasyon riskini önleyebilme
- Riskleri dürüstçe öne çıkarmayı, 'finansal tavsiye değildir' uyarısını ve dokümantasyon-kod tutarlılığını benimseyebilme
Web3'te dokümantasyon lüks değil, güvenlik ve güven meselesidir. Kullanıcı, bir akıllı sözleşmeyle etkileşerek gerçek parasını riske atar; ne yaptığını anlamıyorsa kandırılmaya açıktır. Denetçi, iyi belgelenmemiş bir kodu güvenle inceleyemez. Bu ünitede YZ'nin en güvenilir ve en verimli olduğu alanı ele alıyoruz: dokümantasyon ve teknik yazım. Whitepaper'dan kod içi yorumlara, kullanıcı kılavuzundan risk açıklamalarına kadar YZ burada gerçek bir güç çarpanıdır — yeter ki doğruluk insanca denetlensin.
Web3 dokümantasyonunun türleri
- Whitepaper / litepaper: Projenin vizyonunu, mekanizmasını ve tokenomiğini anlatan temel belge.
- Teknik dokümantasyon: Geliştiriciler için sözleşme arayüzleri, entegrasyon rehberi.
- NatSpec (Ethereum Natural Language Specification — Solidity'de fonksiyonların ne yaptığını anlatan standart kod-içi yorum formatı): Kodun içine gömülü, hem insan hem araç tarafından okunan dokümantasyon.
- Kullanıcı kılavuzu: Son kullanıcıya "nasıl kullanılır, hangi riskler var" anlatan sade metin.
- Risk açıklaması (disclaimer): Yasal ve etik olarak zorunlu uyarılar.
Bu türlerin ortak sorunu: geliştiriciler yazmayı sevmez ve genellikle son ana bırakır. YZ tam da bu boşluğu doldurur.
Neden dokümantasyon YZ'nin en güvenli alanı
Dokümantasyonda hatanın maliyeti, denetimdekinden düşüktür: yanlış bir cümle düzeltilir, para uçmaz (doğrudan). Ayrıca YZ dil üretiminde doğal olarak güçlüdür. Bu yüzden YZ burada hem verimli hem görece güvenlidir. Ama iki kritik risk sürer:
- Yanlış teknik iddia: YZ, kodun yaptığını yanlış anlatabilir; bu, kullanıcıyı yanıltır ve güvenlik açığına dönüşebilir ("bu fonksiyon fonunuzu korur" derken korumuyorsa).
- Abartılı/pazarlama dili: YZ, bir projeyi olduğundan güvenli veya kârlı gösteren dil üretebilir; bu hem etik hem yasal sorundur.
Dikkat: Dokümantasyon kodu tarif eder; kodun kendisi değildir. YZ'nin yazdığı her teknik iddia ("şu olur", "şu korunur") gerçek kodla karşılaştırılıp teyit edilmelidir. Yanlış dokümantasyon, doğru koddan daha tehlikeli olabilir çünkü kullanıcı belgeye güvenir.
YZ'yi dokümantasyonda kullanmanın katmanları
1. NatSpec üretme. YZ, var olan bir fonksiyonu okuyup NatSpec yorumu taslaklar: ne yapıyor, parametreleri ne, ne döndürüyor. Bu, denetim ve bakımı kolaylaştırır.
2. Teknik-sade çeviri. YZ, karmaşık bir mekanizmayı son kullanıcının anlayacağı dile çevirir — Web3'ün en büyük ihtiyaçlarından biri.
3. Whitepaper taslağı ve yapı. YZ, bir whitepaper'ın iskeletini ve bölümlerini üretir; içerik doğruluğu insanındır.
4. Çok dillilik ve seviye ayarı. YZ, aynı içeriği hem teknik hem sade, hem Türkçe hem İngilizce üretebilir.
Zayıf prompt / Güclü prompt
Zayıf prompt:
Bu proje için bir whitepaper yaz.
YZ, gerçek mekanizmayı bilmeden abartılı, muhtemelen yanlış ve pazarlama dolu bir metin uydurur.
Güçlü prompt:
Rolün: Web3 teknik yazarı. Aşağıda projenin GERÇEK mekanizması,tokenomiği ve kodu var. Yalnızca bu verilenlere dayanarak birwhitepaper taslağı yaz. Kurallar:- Abartma, "garantili kâr", "tamamen güvenli" gibi ifadeler KULLANMA.- Her teknik iddiayı verdiğim mekanizmaya dayandır; uydurma ekleme.- Riskleri açıkça yazan bir "Riskler" bölümü ekle.- "Bu finansal tavsiye değildir" uyarısı ekle.Emin olmadığın veya bende olmayan bilgiyi [DOLDURULACAK] diye işaretle.
Dört kopyalanabilir şablon
1) NatSpec üretme:
Aşağıdaki fonksiyona standart NatSpec yorumu yaz: @notice (neyapar, sade), @dev (teknik not), @param ve @return. Yalnızcakodun GERÇEKTE yaptığını yaz; kodda olmayan davranış ekleme.Emin olmadığın etkiyi işaretle.
2) Teknik-sade çeviri:
Bu mekanizmayı, kripto konusunda acemi bir kullanıcının anlayacağısade Türkçeyle açıkla: ne yapıyor, kullanıcı ne yapmalı, HANGİRİSKLER var? Abartma; güvenlik garantisi verme. Riskleri gizleme,öne çıkar.
3) Risk/uyarı bölümü:
Bu proje için dürüst bir "Riskler ve Uyarılar" bölümü yaz: akıllısözleşme riski, piyasa riski, likidite riski, düzenleyici belirsizlik,anahtar kaybı. Her riski sade dille açıkla. Riskleri küçümseme;"bu finansal tavsiye değildir" ile bitir.
4) Dokümantasyon-kod tutarlılık kontrolü:
Aşağıda bir fonksiyon ve onun mevcut dokümantasyonu var. Dokümanınkodun GERÇEK davranışıyla çeliştiği veya eksik bıraktığı yerleriişaretle. Kesin karar verme; "geliştirici teyit etsin" diye sun.
Üç mini vaka (sayılarla)
Vaka 1 — NatSpec denetimi hızlandırdı. Bir ekip, 25 fonksiyonluk bir sözleşmeyi yorumsuz denetime göndermişti; denetçi mantığı anlamak için ekstra zaman istedi. Ekip YZ ile NatSpec taslağı üretip her birini kodla teyit etti; denetim ön hazırlığı 1 güne yakın kısaldı. Ders: iyi dokümantasyon denetim maliyetini düşürür.
Vaka 2 — Yanlış iddia yakalandı. YZ'nin ürettiği kullanıcı kılavuzunda "fonlarınız her an geri çekilebilir" yazıyordu; oysa sözleşmede 7 günlük bir kilit vardı. Teknik gözden geçirme bunu yakaladı. Yayımlansaydı kullanıcılar yanılıp mağdur olacaktı. Ders: her teknik iddia kodla teyit edilir.
Vaka 3 — Abartı temizlendi. İlk whitepaper taslağında YZ "riskiz yüksek getiri" gibi ifadeler kullanmıştı. Ekip bunları çıkarıp dürüst risk bölümü ekletti. Bu hem etik hem yasal olarak projeyi korudu. Ders: YZ'nin pazarlama eğilimi denetlenmeli.
Dokümantasyonun etik yükü
Web3 dokümantasyonu, kullanıcının parasını riske attığı bir bağlamda okunur. Bu yüzden:
- Dürüstlük: Riskler gizlenemez, abartılı vaatler verilemez.
- Doğruluk: Teknik iddialar kodla örtüşmelidir; "belge öyle diyor" bir savunma değildir, aksine yanıltmadır.
- Erişilebilirlik: Kullanıcının gerçekten anlayacağı dilde yazmak bir güvenlik önlemidir; anlaşılmayan belge kandırmaya davetiyedir.
- Yasal uyarı: Finansal tavsiye olmadığı ve düzenleyici belirsizlik açıkça belirtilmelidir.
İpucu: Bir Web3 belgesinin dürüstlük testi: "Bir kullanıcı yalnızca bu belgeye güvenerek para koyarsa, gerçekle karşılaştığında kandırılmış hisseder mi?" YZ'ye risk bölümünü her zaman öne çıkarttırın, sona gömdürmeyin.
Sık yapılan hatalar
- Teknik iddiayı kodla teyit etmemek. Yanlış belge kullanıcıyı yanıltır.
- Abartılı/pazarlama dilini bırakmak. Etik ve yasal risk.
- Riskleri küçültmek veya gizlemek. Güven ihlali.
- YZ'ye gerçek mekanizmayı vermeden whitepaper yazdırmak. Uydurma üretir.
- "Finansal tavsiye değildir" uyarısını atlamak. Yasal zorunluluk.
- Dokümantasyonu kodla senkron tutmamak. Kod değişince belge yanıltıcı olur.
Özetle
- Dokümantasyon Web3'te bir güvenlik ve güven meselesidir; YZ'nin en verimli alanıdır.
- Hatanın maliyeti görece düşük ama yanlış teknik iddia ve abartı ciddi risktir.
- Her teknik iddia gerçek kodla teyit edilmelidir; belge kodun yerine geçmez.
- Riskler dürüstçe ve öne çıkarılarak yazılmalı; abartı ve garanti dili kaldırılmalıdır.
- "Finansal tavsiye değildir" ve düzenleyici uyarılar zorunludur.
Uygulama görevi
Bir akıllı sözleşme fonksiyonu alın. YZ'ye "NatSpec üretme" promptunu uygulayın ve üretilen yorumu kodun gerçek davranışıyla satır satır karşılaştırın — uyuşmayan var mı? Sonra aynı fonksiyon için "teknik-sade çeviri" ve "risk/uyarı bölümü" üretin. YZ'nin abartılı veya kodla çelişen en az bir ifadesini bulup düzeltin.
Kontrol listesi
- [ ] Her teknik iddiayı gerçek kodla teyit ettim.
- [ ] Abartılı/garanti ifadelerini kaldırdım.
- [ ] Riskleri dürüstçe ve öne çıkararak yazdım.
- [ ] YZ'ye gerçek mekanizmayı verdim; uydurmasına izin vermedim.
- [ ] "Finansal tavsiye değildir" uyarısını ekledim.
- [ ] NatSpec'i araç ve denetim için tam yazdım.
- [ ] Dokümantasyonu kodla senkron tutmayı planladım.