Bir düzeltmeyi nasıl doğrularsınız?

Puanların hesaplanmasını düzelttiler. Yanıtta terminal çıktısı, skor tablosunun ekran görüntüsü ve kısa bir "tamamlandı" mesajı var. Dosya çok, ama soru basit: Bunlardan hangisi gereksinimi karşılıyor?

Kanıt, düzeltmenin yanına konmuş herhangi bir dosya değildir. Neyin, kodun hangi durumunda kontrol edildiğini ve sonucun ne olduğunu gösteren belirli bir kontrolün çıktısıdır. Farklı materyaller farklı soruları yanıtlar; hiçbiri hepsini birden yanıtlamaz.

Bir gereksinimi nasıl doğrulanabilir bir ifadeye dönüştüreceğinizi, komut çalıştırması hakkında ne kaydedeceğinizi, logun, diff'in ve ekran görüntüsünün neyi kanıtladığını inceleyelim. Sonra bunları altı alanlı kısa bir EVIDENCE_LOG günlüğünde bir araya getirip hazır kanıt paketinin yeterli olup olmadığına bakalım.

Kriter kontrolü belirler

Makale boyunca aynı örneği kullanacağız: skor tablosu olan küçük bir bonus oyunu. Başlangıç skoru 0; üç eşleşme 3 puan kazandırmalı, düzeltmeden önceyse 30 puan kazandırıyordu. Puanlama kuralı bu oyun için tasarlandı; başka bir projede kural bambaşka olabilir, oraya taşımayın.

"Skor düzeltildi" ifadesi doğrulanamaz: neyi çalıştıracağınız ve neye bakacağınız belli değil. Doğrulanabilir bir ifade üç parçadan oluşur: başlangıç durumu, eylem ve beklenen gözlem. Örneğin: "Skor 0 iken üç eşleşme 3 puan kazandırır ve tabloda 3 görünür." Artık bu ifadeyi kontrol edebilirsiniz.

Bu ifade daha sonra ayrı gözlemlere ayrılır. Hesaplama ile oyuncunun gördüğü şey farklıdır ve farklı kanıtlarla doğrulanır. Tablonun üçüncü satırı liderlik tablosundaki puanla ilgilidir. Görevde bu gereksinim olmayabilir; varsa onun da ayrı bir gözlemi olmalı.

Burada en işe yarayan sütun üçüncüsü. Kanıt, neredeyse her zaman umduğunuzdan daha azını doğrular; sınır, yapılan eylemin bittiği yerden geçer. Örneğimizde hesaplama testi skor tablosunu kontrol etmez; tablonun görüntüsü de kodun değiştirilen satırını göstermez.

Şu iki şeyi ayrı tutun: gereksinim, işin sonunda doğru olması gereken şeydir; sonuç ise gerçekten elde ettiğiniz şey. Aynı paragrafta birbirine karıştıklarında "3 puan kazandırmalı" ifadesi, kimse hiçbir şey çalıştırmamışken fark ettirmeden "3 puan kazandırıyor" hâline gelir.

Komut ve sonucu

Bir kontrol çalıştırmasını beş bilgiyle tanımlayabilirsiniz. Kontrolü bir hafta sonra tekrarlayacak kişi için bunların hiçbiri kendiliğinden anlaşılmaz:

• komutun çalıştırıldığı klasör;
• komutun kendisi, aynen;
• kodun durumu: düzeltmeden önce mi sonra mı, commit edilmemiş hangi değişikliklerle;
• sonuç: çıkış kodu ve son sayaçlar;
• hangi kontroller gerçekten çalıştı, hangileri çalışmadı.

"npm test çalıştırılmalı" demekle "npm test çalıştırdım, işte çıktısı" demeyi birbirinden ayırın. İlki geleceğe yönelik bir talimat ve plandır. İkincisi bir olgudur. Özellikle yanıtta nelerin kontrol edilmesi gerektiği düzgünce sıralanmışsa, niyeti sonuç gibi göstermek kolaydır.

npm test "bütün testleri" çalıştırmaz. Belirli bir package.json dosyasında, yani npm'in seçtiği projeninkinde, scripts bölümünün test alanında ne yazıyorsa onu yürütür. Hangi projenin seçildiğini tahmin etmemek için komutu onun kök klasöründen çalıştırın ve bu klasörü günlüğe yazın. Aynı komut adı başka bir projede farklı bir araca, farklı adımlara ya da hiçbir şeye karşılık gelebilir.

Komut bir çıkış koduyla biter: 0 genellikle "araç çalıştırmayı başarılı saydı" demektir. Bash'te bu kodu komutun hemen ardından echo $? gösterir; PowerShell'de npm gibi harici programlar için $LASTEXITCODE kullanılır. Ancak sıfır, gereken testin çalıştığı anlamına gelmez: test atlanmış, adına göre filtrelenmiş ya da hiç yazılmamış olabilir. Bu yüzden çıkış kodunun yanında sayaçlara ve ilgilendiğiniz testin adına da yer verin.

Logdan ne saklamalı?

Çalıştırma çıktısı uzun olabilir; kimse tamamını günlüğe kopyalamaz. Kısa bir alıntıda dört bilgi yeterlidir: başarısız testin adı, beklenen ve gerçek değer, başarısızlık nedeni ve son sayaçlar. Geri kalanı bağlantı vereceğiniz dosyada saklanır. Aşağıdaki, yapılmış bir çalıştırmanın kaydı değil, kısaltılmış ve eğitim amaçlı bir çıktı örneğidir.

✖ three matches give 3 points (2.4108ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  30 !== 3
      at TestContext.<anonymous> (src/bonus-game/score.test.js:8:10)
ℹ tests 1
ℹ pass 0
ℹ fail 1
ℹ skipped 0

Bu yalnızca bir alıntı; tam çıktı örneğin logs/test-fail.txt dosyasına kaydedilmiştir. Alıntıdan temel noktalar anlaşılıyor: üç eşleşmeyle ilgili test başarısız olmuş, beklenen 3 iken 30 alınmış ve atlanan kontrol yok.

Ham çıktı günlüğe aynen girer. Kendi sözlerinizle özetlemek ("test yanlış çarpan yüzünden başarısız oldu") daha anlaşılır görünebilir, ancak bu artık bir yorumdur, gözlem değil; günlükten doğrulayamazsınız. İkisini yan yana tutun: önce aracın satırları, sonra açıklamanız.

Stack trace satırındaki adres, kontrolün çalıştığı yeri, yani test dosyasını gösterir. Nedeni oyunun kodunda ararsınız; orada bulduğunuz çarpan kodu incelemenizin sonucudur, log satırı değildir. Günlükte bu iki kaynağı farklı biçimde etiketleyin, yoksa 10 sayısının nereden çıktığını sonradan anlayamazsınız.

Diff neyi kanıtlar?

Diff, bir dosyanın iki durumu arasındaki farkı gösterir. Düzeltmeden sonra kodun bir kez olsun çalıştırıldığını kanıtlamaz; davranışın beklediğiniz gibi değiştiğini ise hiç kanıtlamaz.

--- a/src/bonus-game/score.js
+++ b/src/bonus-game/score.js
@@ -1,5 +1,5 @@
-const POINTS_PER_MATCH = 10;
+const POINTS_PER_MATCH = 1;

 function calcScore(matches) {
   return matches * POINTS_PER_MATCH;
 }

Bu alıntının altına hangi iki durumun karşılaştırıldığını belirten tek bir açıklama satırı ekleyin. Örneğin: "çalışma ağacı ile düzeltme öncesindeki a1b2c3d commit'i karşılaştırılıyor, komut git diff HEAD". Buradaki kimlik eğitim amaçlıdır; günlüğünüzde gerçek kimlik olmalı. Bu komut, commit için stage edilmiş değişiklikler dahil olmak üzere geçerli izlenen dosyaları HEAD ile karşılaştırır. HEAD olmadan sıradan git diff yalnızca index ile farkı gösterir ve git add sonrasında boş çıkabilir. Açıklama yoksa diff "bir şey ile başka bir şey" gibi görünür ve karşılaştırmayı tekrarlayamazsınız.

Testteki beklenen değerin hâlâ 3 olduğunu ayrıca kontrol edin. Kodla birlikte beklenen sayı da değiştiyse bu başka bir durumdur: davranış gereksinime uydurulacağına kontrol davranışa uydurulmuştur.

Kolayca gözden kaçan küçük bir teknik ayrıntı: değişiklik commit edilmeden önce çalışma ağacı ile son commit arasındaki karşılaştırmada görünür. Commit'ten sonra aynı karşılaştırma boş çıkar; bu, görevde hiçbir şey değişmedi demek değildir. Değişiklik geçmişe kaydedilmiştir; commit'i önceki durumla karşılaştırmanız gerekir. Boş bir diff tek başına hiçbir şeyi kanıtlamaz; önemli olan hangi iki durumu karşılaştırdığınızdır.

Ekran görüntüsünde ne görülür?

Durum ve eylem

Skor tablosunda 3 görünen bir kare yalnızca şunu kanıtlar: Görüntü alındığı anda tabloda 3 vardı. Bu, "üç eşleşme 3 puan kazandırdı" demek değildir. İki ifade arasında görüntüde yer almayan her şey var: başlangıç skoru ve ne yaptığınız.

Görüntünün kanıt sayılması için yanına senaryoyu da kaydedin:

1. ne açıldı: sayfanın adresi veya başlatma yöntemi ve hangi sürüm olduğu, düzeltmeli mi değil mi;
2. başlangıç durumu: başlangıç skoru 0, eski veriler yüklenmemiş;
3. eylem: üç eşleşme oluşturuldu;
4. gözlem: tabloda 3 var ve görüntü eylemden hemen sonra alındı.

Bu kayıt olmadan aynı görüntü onlarca farklı yolla elde edilebilir. Dünden açık kalan eski sürüm sekmesi, farklı bir başlatma, zaten sıfırdan büyük olan skor... Bunların hepsi ikna edici görünen ama hiçbir şey ifade etmeyen bir görüntü oluşturabilir.

Bu makalede özellikle skor tablosunun ekran görüntüsü yok. Kontrol amacıyla görüntüyü, senaryoyu gereken sürümde elle ya da otomasyonla yeniden çalıştırdıktan sonra alın. Çizilmiş veya örnek olsun diye hazırlanmış bir tablo, birebir aynı görünse bile kanıt sayılmaz. Kendi görüntünüzü alırken tablonun tamamını gösterin, senaryo kaydına sayfa adresini ekleyin ve görüntüyü bu kaydın yanına koyun; yoksa bir hafta sonra hangi çalıştırmaya ait olduğunu hatırlamayabilirsiniz.

Model ne okuyabilir?

Görüntüyü oturuma verip okumasını isteyebilirsiniz. Burada her şey isteğin nasıl ifade edildiğine bağlı: önceden belirlenmiş bir sonucu onaylatmak yerine, görünen sayıyı söylemesini ve belirsizlikleri sıralamasını isteyin ("başlangıç durumu görünüyor mu", "hangi sürüm olduğu anlaşılıyor mu"). "Bug'ın düzeldiğini doğrula" derseniz, hiçbir şeyi kontrol etmeyen nazik bir onay almanız kolaydır.

Görüntü gönderme olanağı kullandığınız modele ve ortama bağlıdır. Claude Code'da kaydedilmiş görüntünün yolunu belirtip okumasını isteyebilirsiniz. Görüntü yüklenmediyse önce dosya yolunu ve erişilebilirliği kontrol edin; yalnızca modeli değiştirmek sorunu mutlaka çözmez.

Düzeltmeden önce ve sonra aynı senaryo

İşe yarar bir çift şöyle görünür: aynı kontrol, bozuk implementasyonda başarısız olur ve düzeltilmiş implementasyonda başarılı olur. Başarısızlık, kontrolün bu kusuru yakaladığını; başarıysa düzeltmeden sonra kusurun bu senaryoda kalmadığını gösterir.

Bu karşılaştırma yalnızca aynı girdiler ve aynı beklentiler kullanılırsa anlamlıdır. Başlangıç skoru aynı, eşleşme sayısı aynı, beklenen değer yine 3. İşte düzeltmeden sonra aynı testin başarılı sonucu:

✔ three matches give 3 points (1.3983ms)
ℹ tests 1
ℹ pass 1
ℹ fail 0
ℹ skipped 0

Çalıştırmalar arasında implementasyon değişir; test, girdiler, beklenti ve çalıştırma koşulları aynı kalır. Gereksinimi ya da testteki beklentiyi değiştirmeniz gerekirse bu kontrolle yeni bir çalıştırma çifti elde edin: sözel açıklama, kontrolün her iki durumda da çalıştırılmasının yerini tutmaz. Böyle bir durumda sessizce "önce kırmızıydı, şimdi yeşil" demek yanıltıcıdır.

before.txt ve after.txt adlı iki dosya da tek başına hiçbir şeyi garanti etmez. Dosya adı kanıt değildir. İçeriğe bakın: komut aynı mı, test aynı mı, beklenti aynı mı? Bozuk durumu geri getirme kontrolü (git stash yöntemi) kendi kuralları olan ayrı bir kontroldür. Şimdilik bilmeniz gereken, düzeltme öncesindeki başarısız sonucun bellekten değil gerçek bir çalıştırmadan gelmesidir.

Kısa bir EVIDENCE_LOG

EVIDENCE_LOG, bu makalede altı alanlı ve sıralı, düz metin bir günlük anlamına gelir: BELİRTİ, LOG KANITI, BOZUK SÜRÜMDE BAŞARISIZLIK, DÜZELTME, GERÇEK BAŞARI, EKRAN GÖRÜNTÜSÜ. Bu sıralama belirtiyi, düzeltmeyi ve sonucu karşılaştırmayı kolaylaştırır. Ancak alanların sırası kayıtların doğruluğunu garanti etmez.

Yukarıda topladıklarımız bu alanlara yerleşir. Komut ve klasör başarısızlık alanına, karşılaştırılan durumlar düzeltme alanına, tam dosyalara verilen bağlantılar da kaynaklarının yanına yazılır. Yanına bir belge paketi daha eklemeniz gerekmez.

Aşağıda eğitim amaçlı bir doldurma örneği var. Her alana ne yazılacağını gösterir; yapılan kontrollerin raporu değildir. Kendi günlüğünüzde metinleri gerçek sonuçlarla değiştirin.

BELİRTİ: bonus oyununda başlangıç skoru 0 iken üç eşleşme
3 yerine 30 puan kazandırıyor. Her seferinde tekrarlanıyor:
oyunu aç, üç eşleşme oluştur, skor tablosuna bak.

LOG KANITI: çalıştırma çıktısında "30 !== 3", testin adı
"three matches give 3 points", tam çıktı logs/test-fail.txt dosyasında.
Ayrıca kod incelemesinden: src/bonus-game/score.js dosyasında
POINTS_PER_MATCH çarpanı 10. Bu kodu inceleyerek elde edilen sonuç;
test çıktısında 10 sayısı yer almıyor.

BOZUK SÜRÜMDE BAŞARISIZLIK: HEAD a1b2c3d (eğitim kimliği),
çalışma ağacı temiz; commit'te bozuk hesaplama ve test var.
Klasör - /project/bonus-game, komut - npm test.
package.json içinde scripts.test = node --test. "three matches give 3 points"
başarısız; neden "30 !== 3", tests 1, pass 0, fail 1, skipped 0,
çıkış kodu 1. Çıktı alıntısı yukarıda, tamamı logs/test-fail.txt dosyasında.

DÜZELTME: POINTS_PER_MATCH, src/bonus-game/score.js dosyasında
10'dan 1'e değiştirildi; başka değişiklik yok. HEAD yine a1b2c3d.
Diff: git diff HEAD, çalışma ağacı bu commit ile karşılaştırıldı;
diffs/score-fix.diff dosyasına kaydedildi.
Testteki beklenen değer değişmedi, hâlâ 3.

GERÇEK BAŞARI: aynı komut npm test, aynı klasörden, açıklanan
düzeltme sonrasındaki kodla çalıştırıldı. Aynı test başarılı:
tests 1, pass 1, fail 0, skipped 0, çıkış kodu 0.
Tam çıktı logs/test-pass.txt dosyasında.
Beş eşleşmeli senaryo çalıştırılmadı.

EKRAN GÖRÜNTÜSÜ: screenshots/bonus-score-3.png. Düzeltmeden sonra
oyun aynı çalışma ağacından http://localhost:3000 adresinde yeniden açıldı.
Başlangıç skoru 0, üç eşleşme oluşturuldu, tabloda 3 var.
Sonucun liderlik tablosuna kaydedildiği kontrol edilmedi.

Örnekteki yollar yalnızca örnek. Tam logları, diff'leri ve görselleri projede benzer içeriklerin zaten bulunduğu yere koyun; ayrı ve zorunlu bir klasör yapısı yok.

Beşinci ve altıncı alanlardaki son cümlelere dikkat edin. Atlanan kontrolü tek bir ifadeyle açıkça belirtin: "çalıştırılmadı", "kontrol edilmedi". Bu tembellik itirafı değil, çıkarımın sınırıdır. Bu cümleler olmadan günlük daha eksiksiz görünür, ama aslında kimsenin yapmadığı şeyler hakkında susar.

Kendinizi sınayın

Görevde iki kriter var: başlangıç skoru sıfırken üç eşleşme 3 puan kazandırmalı ve bu üç eşleşmeden sonra arayüzde 3 görünmeli. Elinizde altı materyal var:

1. ajandan gelen "tamamlandı, bug düzeltildi" mesajı;
2. npm test çalıştırma talimatı;
3. aynı testin gerçek çalıştırmaları: düzeltmeden önce başarısız, sonra başarılı;
4. çarpandaki değişikliği gösteren diff;
5. çalıştırma açıklaması olmayan, 3 sayısını gösteren tek bir görüntü;
6. yeniden çalıştırılmış senaryo kaydı ve ona bağlı görüntü.

İki kriter için hangileri yeterli, neler hâlâ kontrol edilmemiş? Devamını okumadan önce bir yanıt düşünün.

Yanıt: İlk kriteri 3. madde karşılıyor: aynı testin gerçek çalıştırma çifti. 4. maddedeki diff kodda neyin değiştiğini açıklar, ancak çalıştırmanın yerini tutmaz: değişiklik yapmakla kodu çalıştırmak farklı şeylerdir. İkinci kriteri 6. madde karşılıyor: başlangıç durumunu ve eylemi gösteren senaryo kaydıyla birlikte görüntü. 1. ve 2. maddeler hiçbir şeyi kanıtlamaz: tamamlandı mesajı doğrulanabilir kanıt içermez, talimat ise gelecekte yapılacak eylemi anlatır. 5. madde 3 sayısını gösterir, o kadar; puanların nasıl verildiği anlaşılamaz. Üstelik altı materyalin tamamı elinizde olsa bile sonuç liderlik tablosuna kaydedilmiş mi hâlâ bilinmez: kayıtlı değeri geri okuyan bir senaryo yok.

Bu günlüğü oturumda da hazırlatabilirsiniz. Kullanıma hazır prompt:

Altı alanı kullanarak bir EVIDENCE_LOG hazırla. Her çıkarım için
fiilen yapılan kontrolü, kodun durumunu ve sonuç kaynağını belirt.
Çalıştırılmayanları ayrıca işaretle. Ekran görüntüsü için yalnızca
görünenleri söyle; görüntüden iç hesaplamanın doğru olduğu sonucunu çıkarma.

Claude Code ile kanıtları toplama

İş akışı şöyle olabilir:

1. ajan her kriteri belirli bir kontrolle ilişkilendirir: ne çalıştırılmalı, kod hangi durumda olmalı, hangi sonuç bekleniyor;
2. bu ortamda yapılabilen kontrolleri çalıştırır ve komutu ham çıktısıyla gösterir;
3. gözlemleri ekler: çıktı alıntıları, tam dosyalara bağlantılar ve yeniden çalıştırılan senaryonun açıklaması;
4. sınırı açıkça belirtir: neler çalıştırılmadı, mevcut materyallerle neler söylenemez.

Kanıtları kontrol etmek yine size kalır: ekli dosyaları açıp içeriğine bakın, senaryoyu kriterde anlatılanla karşılaştırın ve kontrolü görünmeyen madde hakkında zor bir soru sorun. Genellikle bu, gerçekten toplanmış kanıtları düzgün biçimde yazılmış bir özetten ayırmaya yeter.

Teknik kaynaklar: git diff, git stash, Node.js test runner, npm test, Claude Code'da görüntüler.