Markdown, ajanların bizimle iletişim kurmak için kullandığı baskın dosya biçimi haline geldi. Basit, taşınabilir, bir miktar zengin metin yeteneğine sahip ve sizin düzenlemeniz kolay. Claude, markdown dosyaları içinde ASCII kullanarak diyagramlar yapma konusunda bile şaşırtıcı derecede iyi hale geldi.
Ancak ajanlar giderek daha güçlü hale geldikçe, markdown'ın kısıtlayıcı bir biçim olduğunu hissettim. Yüz satırdan uzun bir markdown dosyasını okumayı zor buluyorum. Daha zengin görselleştirmeler, renk ve diyagramlar istiyorum ve bunları kolayca paylaşabilmek istiyorum.
Ayrıca bu dosyaları giderek kendim düzenlemiyor, bunun yerine bunları şartname, referans dosyası, beyin fırtınası çıktıları vb. olarak kullanıyorum. Düzenleme yaptığımda, genellikle Claude'a bunları düzenlemesi için talimat veriyorum, bu da markdown'ın en büyük avantajlarından birini ortadan kaldırıyor.
Markdown yerine çıktı biçimi olarak HTML'i tercih etmeye başladım ve Claude Code ekibindeki diğerlerinin de bunu giderek daha fazla kullandığını görüyorum, işte nedeni.
(bazı örneklerle başlamak isterseniz, burada birçoğunu görebilirsiniz: https://thariqs.github.io/html-effectiveness, ancak nedenini okumak için geri döndüğünüzden emin olun)
Neden HTML?
Bilgi Yoğunluğu
HTML, markdown'a kıyasla çok daha zengin bilgiler aktarabilir. Elbette başlıklar ve biçimlendirme gibi basit belge yapılarını yapabilir, ancak aynı zamanda aşağıdakiler gibi her türlü diğer bilgiyi de temsil edebilir:
- Tablolar kullanarak tablo verileri
- CSS ile tasarım verileri
- SVG ile çizimler
- Script etiketleriyle kod parçacıkları
- JavaScript + CSS kullanarak HTML öğeleriyle etkileşimler
- SVG ve HTML kullanarak iş akışları
- Mutlak konumlar ve tuvaller kullanarak uzamsal veriler
- Görüntü etiketleri kullanarak resimler
Claude'un okuyabildiği ve HTML ile oldukça verimli bir şekilde temsil edemeyeceğiniz neredeyse hiçbir bilgi kümesi olmadığını söyleyebilirim. Bu, modelin size derinlemesine bilgi iletmesi ve sizin de bunu gözden geçirmeniz için oldukça verimli bir yol haline getirir.
Bunu yapamadığımda, modelin markdown'da ASCII diyagramları veya en sevdiğim, Claude Code'dan bu ekran görüntüsündeki gibi unicode karakterlerle renkleri tahmin etme gibi daha verimsiz şeyler yapabileceğini fark ettim.
Claude Code, markdown'da renk göstermeye çalışıyor
Görsel Netlik ve Okuma Kolaylığı
Claude daha karmaşık işler yapabildikçe, daha büyük ve daha büyük şartnameler ve planlar da yazıyor. Pratikte, 100 satırdan uzun bir markdown dosyasını genellikle okumadığımı ve kuruluşumdaki başka birine kesinlikle okutamadığımı fark ettim.
Ancak HTML belgelerini okumak çok daha kolaydır, Claude yapıyı sekmeler, çizimler, bağlantılar vb. ile gezinmek için ideal olacak şekilde görsel olarak düzenleyebilir. Hatta mobil uyumlu olabilir, böylece form faktörünüze göre farklı şekilde okuyabilirsiniz.
Paylaşım Kolaylığı
Markdown dosyalarını paylaşmak oldukça zordur çünkü çoğu tarayıcı bunları yerel olarak iyi bir şekilde işlemez. Genellikle bunları e-postalara veya mesajlara ek olarak eklemeniz gerekir.
HTML ile, dosyayı yüklediğiniz sürece (örneğin S3'e), bağlantıyı kolayca paylaşabilirsiniz. İş arkadaşlarınız istedikleri yerde açabilir ve kolayca referans alabilir.
Şartnamenizi, raporunuzu veya PR yazınızı birinin gerçekten okuma olasılığı, HTML formatındaysa çok daha yüksektir.
Çift Yönlü Etkileşim
HTML, belgeyle etkileşime girmenize izin verebilir, örneğin bir tasarımı ayarlamak için kaydırıcılar veya düğmeler eklemesini veya algoritmadaki farklı seçenekleri değiştirerek ne olduğunu görmenizi isteyebilirsiniz. Ayrıca, bu değişiklikleri Claude Code'a geri yapıştırmak için bir istem olarak kopyalamanıza izin vermesini de isteyebilirsiniz.
Bu çift yönlü etkileşimin örneklerini görmek için oyun alanları yazım hakkında daha fazlasını okuyun: https://x.com/trq212/status/2017024445244924382
Veri Alımı
Neden ClaudeAI veya Claude Design gibi araçlar yerine HTML dosyaları yapmak için Claude Code kullanmalısınız? En büyük nedenlerden biri, Claude Code'un alabileceği tüm bağlamdır.
Örneğin, bu makaleyi yazarken, Claude Code'dan kod klasörümü okumasını ve oluşturduğum tüm HTML dosyalarını bulmasını, gruplamasını ve kategorize etmesini ve ardından her türü temsil eden tüm diyagramları içeren bir HTML dosyası yapmasını istedim. Bu makalede gördüğünüz diyagramlar bunun doğrudan bir sonucudur.
Dosya sisteminin yanı sıra, Claude Code MCP'lerinizi (Slack, Linear vb. gibi), web tarayıcınızı (Chrome'da Claude ile), git geçmişinizi vb. kullanarak ek bağlam bulabilir.
Keyifli
Claude ile HTML belgeleri yapmak daha eğlenceli ve yaratma sürecine daha dahil olmamı ve yatırım yapmamı sağlıyor ve bu tek başına yeterli.
Nasıl Başlanır
İnsanların bu makaleyi okuyup bunu bir /html becerisine dönüştürmesinden biraz korkuyorum. Bunda bir değer olabilir, ancak Claude'un bunu yapması için fazla bir şey yapmanıza gerek olmadığını vurgulamak istiyorum. Sadece "bir HTML dosyası yap" veya "bir HTML eseri yap" diyebilirsiniz.
İşin püf noktası, eserin ne yapmasını istediğinizi ve onu nasıl kullanabileceğinizi bilmektir. Zamanla bir beceri geliştirebilirsiniz, ancak şimdilik farklı durumlarda nasıl kullanılacağını anlamak için sıfırdan istem yapmanızı öneririm.
Kullanım Alanları
Bunu daha somut hale getirmek için farklı kullanım alanları için birçok farklı HTML dosyası yaptım. Hepsini burada görüntüleyebilirsiniz: https://thariqs.github.io/html-effectiveness/ ancak işte bir genel bakış.
Şartnameler, Planlama ve Keşif
HTML, Claude'un bir probleme dalması için zengin bir tuvaldir. Bir problem üzerinde çalışmaya başladığımda, basit bir markdown planı yerine bir HTML dosyaları ağı yapmayı beklerim. Örneğin, Claude Code'dan beyin fırtınası yapmasını ve farklı seçeneklerin bazı keşiflerini oluşturmasını isteyerek başlayabilirim. Daha sonra bir tanesini daha da genişletmesini, belki maketler veya kod parçacıkları yapmasını isterim. Son olarak, iyi hissettiğimde bir uygulama planı yazmasını isterim. Plandan memnun olduğumda yeni bir oturum açar ve uygulaması için tüm bu dosyaları ona iletirim.
Doğrulama yaparken, doğrulama ajanından dosyaları okumasını isterim ve neyin gerekli olduğu konusunda çok daha geniş bir bağlama sahip olur.
Örnek İstemler:
- Karşılama ekranı için hangi yöne gideceğimden emin değilim. 6 farklı yaklaşım oluştur — düzen, ton ve yoğunluğu değiştir — ve bunları yan yana karşılaştırabilmem için tek bir HTML dosyasında bir ızgara halinde düzenle. Her birini yaptığı ödünleşimle etiketle.
- Kapsamlı bir uygulama planını bir HTML dosyasında oluştur, bazı maketler yaptığından, veri akışını gösterdiğinden ve gözden geçirmek isteyebileceğim önemli kod parçacıkları eklediğinden emin ol. Okumayı ve sindirmeyi kolaylaştır.
Kullanım Alanları:
- Kodda bir şeyi uygulamanın diğer yollarını keşfetmek
- Birden çok görsel tasarımı keşfetmek
Kod İncelemesi ve Anlama
Kodu bir Markdown dosyasında okumak zor olabilir. Ancak HTML ile farkları, açıklamaları, akış şemalarını, modülleri vb. işleyebiliriz. Bunu, ajanın yazdığı kodu anlamak, kod incelemesi almak veya kodunuzu inceleyen birine bir PR'ı açıklamak için kullanın. Bunun genellikle varsayılan Github fark görünümünden daha iyi çalıştığını görüyorum ve şimdi yaptığım her PR'a bir HTML kod açıklayıcı ekliyorum.
Örnek istem:
Bu PR'ı incelememe yardım et ve onu açıklayan bir HTML eseri oluştur. Akış/geri basınç mantığına pek aşina değilim, bu yüzden ona odaklan. Gerçek farkı satır içi kenar boşluğu açıklamalarıyla işle, bulguları ciddiyete göre renk kodla ve konsepti iyi aktarmak için gereken başka her ne varsa ekle.
Kullanım Alanları:
- Bir PR oluşturmak
- Bir PR'ı incelemek
- Kodda bir konuyu anlamak
Tasarım ve Prototipler
Claude Design, HTML'e dayanır çünkü HTML tasarımda inanılmaz derecede etkileyicidir, nihai yüzeyiniz HTML olmasa bile. Claude, HTML'de bir tasarım taslağı çizebilir ve ardından bunu React, Swift vb. gibi seçtiğiniz dilde yazabilir.
Ayrıca animasyonlar, eylemler vb. gibi etkileşimlerin prototipini de yapabilirsiniz. Tam olarak aradığınız şeyi ayarlamak için Claude'dan kaydırıcılar, düğmeler vb. yapmasını istemeyi düşünün.
Örnek istem:
Yeni bir ödeme butonunun prototipini yapmak istiyorum, tıklandığında bir oynatma animasyonu yapıyor ve ardından hızla mora dönüyor. Bu animasyonda farklı seçenekleri denemem için birkaç kaydırıcı ve seçenek içeren bir HTML dosyası oluştur, iyi çalışan parametreleri kopyalamam için bir kopyalama butonu ver.
Bunu şunlar için kullan:
- Tasarım sistemi eserleri oluşturmak
- Bileşenleri ayarlamak
- Bileşen kütüphanelerini görselleştirmek
- Keyifli Animasyonların prototipini yapmak
Raporlar, Araştırma ve Öğrenme
Claude Code, birden çok veri kaynağındaki bilgileri sentezleme ve okunabilirlik için bir rapora dönüştürme konusunda inanılmaz derecede iyidir. Claude'a Slack'inizde, kod tabanınızda, git geçmişinizde, internette vb. arama yapması için talimat verebilir ve bunu kendiniz, yönetim, ekibiniz vb. için son derece okunabilir raporlar oluşturmak için kullanabilirsiniz.
Bunu uzun bir HTML belgesi, etkileşimli bir açıklayıcı ve hatta bir slayt gösterisi/güverte şeklinde bir araya getirebilirsiniz. Görselleştirmeye yardımcı olması için Claude'dan diyagramlar için SVG kullanmasını isteyin.
Örneğin, istem önbelleğe alma ile ilgili yazılarım için, Claude'dan git geçmişini okuduktan sonra istem önbelleğe alma ile ilgili tüm değişikliklerimiz hakkında okumam için HTML'de derinlemesine bir araştırma dosyası hazırlamasını istedim.
Örnek istem:
Hız sınırlayıcımızın gerçekte nasıl çalıştığını anlamıyorum. İlgili kodu oku ve tek bir HTML açıklayıcı sayfası üret: jeton kovası akışının bir diyagramı, açıklamalı 3-4 ana kod parçacığı ve altta bir "dikkat edilmesi gerekenler" bölümü. Bir kere okuyan biri için optimize et.
Bunu şunlar için kullan:
- Bir özelliğin nasıl çalıştığını özetlemek
- Bana bir konsepti açıklamak
- Patronuna haftalık durum raporları
- Yönetime olay raporları
- SVG çizimleri, akış şemaları, teknik diyagramlar vb.
Özel Düzenleme Arayüzleri
Bazen tam olarak ne istediğinizi yalnızca bir metin kutusunda tanımlamak zordur. Bu durumda, Claude'dan üzerinde çalıştığım tam şey için tek kullanımlık bir düzenleyici oluşturmasını isterim. Bir ürün veya yeniden kullanılabilir bir araç değil, bu tek veri parçası için özel olarak oluşturulmuş tek bir HTML dosyası.
İşin püf noktası her zaman bir dışa aktarma ile bitirmektir: UI'da yaptığım her şeyi Claude Code'a yapıştırabileceğim bir şeye dönüştüren bir "JSON olarak kopyala" veya "istem olarak kopyala" butonu.
Örnek istemler:
- Bu 30 Linear ticket'ı yeniden önceliklendirmem gerekiyor. Bana her ticket'ı Şimdi / Sonraki / Sonra / Kes sütunları arasında sürüklenebilir bir kart olarak gösteren bir HTML dosyası yap. Bunları en iyi tahminine göre önceden sırala. Son sıralamayı kova başına tek satırlık bir gerekçeyle dışa aktaran bir "markdown olarak kopyala" butonu ekle.
- İşte özellik bayrağı yapılandırmamız. Bunun için bir form tabanlı düzenleyici oluştur, bayrakları alana göre gruplandır, aralarındaki bağımlılıkları göster, ön koşulu kapalı olan bir bayrağı etkinleştirirsem beni uyar. Sadece değiştirilen anahtarları veren bir "farkı kopyala" butonu ekle.
- Bu sistem istemini ayarlıyorum. Yan yana bir düzenleyici yap: solda değişken yuvaları vurgulanmış düzenlenebilir istem, sağda doldurulmuş şablonu canlı olarak yeniden oluşturan üç örnek girdi. Bir karakter/ token sayacı ve bir kopyalama butonu ekle.
Bunu şunlar için kullan:
- Herhangi bir şeyi yeniden sıralamak, triyaj yapmak veya gruplamak (ticket'lar, test senaryoları, geri bildirim)
- Yapılandırılmış yapılandırmayı düzenlemek (özellik bayrakları, env değişkenleri, kısıtlamalı JSON/YAML)
- Canlı önizleme ile istemleri, şablonları veya metinleri ayarlamak
- Veri kümelerini düzenlemek, satırları onaylamak/reddetmek, örnekleri etiketlemek, seçimi dışa aktarmak
- Bir belgeyi, transkripti veya farkı açıklamak ve açıklamaları dışa aktarmak
- Metinle ifade edilmesi zor olan değerleri seçmek: renkler, yumuşatma eğrileri, kırpma bölgeleri, cron zamanlamaları, regex'ler.
Sıkça Sorulan Sorular
Birçok kişiye HTML'e nasıl geçtiğimi anlatıyorum ve birkaç tekrarlanan soru gördüm.
Daha az token verimli değil mi?
Markdown genellikle daha az token kullanırken, HTML'in eklenen ifade gücünün ve onu okuma olasılığımın çok daha yüksek olmasının genel olarak daha iyi çıktı almamı sağladığını gördüm. Opus 4.7'deki 1MM bağlam penceresiyle, artan token kullanımı bağlam penceresinde gerçekten fark edilmiyor.
Markdown'ı şimdi ne zaman kullanıyorsun?
Dürüst olmak gerekirse, neredeyse her şey için markdown kullanmayı tamamen bıraktım, ancak muhtemelen HTML maksimalist tarafında oldukça ilerideyim.
HTML dosyasını nasıl görüntülerim?
Genellikle yerel olarak bir tarayıcıda açarım (Claude'dan açmasını isteyebilirsiniz) veya paylaşılabilir bir bağlantı istiyorsanız S3'e yüklerim.
Bu, markdown'dan daha uzun sürmüyor mu?
Bu daha uzun sürüyor! HTML, Markdown'dan 2-4 kat daha uzun sürebilir, ancak sonuçların buna değdiğini gördüm.
Peki ya sürüm kontrolü?
Bu, HTML'in en büyük dezavantajlarından biri, HTML farkları gürültülü ve Markdown'a kıyasla incelenmesi zor.
Claude'u zevkime uygun hale nasıl getiririm / çirkin yapmasını nasıl engellerim?
Ön uç tasarım eklentisi, Claude'un iyi HTML dosyaları yapmasına yardımcı olur. Ancak kendi şirketinizin tarzına uyması için, Claude'u kod tabanınıza yönlendirerek tek bir tasarım sistemi HTML dosyası oluşturabilirsiniz. Daha sonra bu tasarım sistemi dosyasını diğer html dosyaları için referans olarak kullanabilirsiniz.
Döngüde Kalın
Yukarıdakilerin hepsi, HTML kullanmamın gerçek nedeninin Claude ile döngüde çok daha fazla hissetmem olduğunu söylemek içindir. Planları derinlemesine okumayı bıraktığım için Claude'un seçimlerini yapmasına izin vermek zorunda kalacağımdan korkmaya başlamıştım.
Ancak bunun yerine, HTML kullanırken her zamankinden daha fazla döngüde hissettiğimi söylemekten mutluluk duyuyorum. Umarım siz de öyle hissedersiniz.
