Web için sezgisel kodlamanın ötesinde

1. Giriş

Kodlama aracıları günlük yazılım geliştirme sürecinin ayrılmaz bir parçası haline geldikçe, ister deneyimli bir mühendis olun ister ilk uygulamanızı yayınlamak isteyen yeni bir geliştirici, nasıl geliştirdiğiniz ve ne geliştirdiğiniz temelden değişiyor. Kodlama aracılarını kullanmaya başladığınızda genellikle "sıfır görevli" istemlerle başlarsınız. Bu istemler, istediğiniz şeyi kısa ve anlaşılır bir dille ifade eden tek bir talimattır. Bu durum hızlıca sorunlara yol açar:

• Herkesi memnun etme eğilimi: Modeller, isteğinizi olabildiğince hızlı bir şekilde tamamlamak için genellikle kusurlu kısıtlamaları veya öncülleri kabul eder ve oluşturduklarının gerçekten istediğiniz şeyi yaptığını doğrulamaz.
• Doğrulama eksikliği: Temsilciler, test yazsalar bile genellikle çalışmalarının işe yaradığından emin olmak için kontrol etmezler. Web sitelerini canlı tarayıcıda kullanmaya çalışmak, gizli hataların, bozuk düzenin ve erişilemeyen kontrollerin ortaya çıkmasına neden olur.
• Teknik borç: Modellerin eğitilme ve çalışma şekli nedeniyle yazdıkları kod, eski ve güncel olmayan kalıplara yönelir. Bu durum, hem daha fazla jeton hem de daha fazla insan ve makine zamanı ve çabası gerektiren teknik borcun artmasına neden olur. Teknik borç, kullanıcı deneyiminizi bile olumsuz etkileyebilir.

4 adımlı oyun planı

Kodlama aracılarının, gereksinimlerinize daha uygun ve daha iyi kodlar üretmesine yardımcı olmak için 4 adımlı bir ürün geliştirme yaşam döngüsü izleyebilirsiniz:

1. Planlama ve tasarım: Üretim uygulamasına başlamadan önce, aracıyla birlikte ürün şartları dokümanları (PRD'ler) yazın ve bu dokümanların tarayıcıda prototipini oluşturup tasarlayın. Ardından, kodlamaya başlamadan önce PRD'lerinizden ve tasarımlarınızdan mimari tasarım dokümanları (özellikler) oluşturun.
2. Kodlama ve geliştirme: Temsilcilerinize sıfır görevli istem yerine PRD'lerinize, tasarımlarınıza ve spesifikasyonlarınıza göre geliştirme yapmasını söyleyin ve çalışmasını kontrol etmek için başka bir temsilciyi çalıştırmasını sağlayın.
3. Tekrar edin: Eklemek istediğiniz her yeni özellik için 1. ve 2. adımları tekrarlayın.
4. Dağıt: Üretime gönderme.

Bu belgede, yapay zeka aracılarını aktif işbirliği ortakları olarak kullanma ve teknik borcu azaltmanıza ve çıkış kodu kalitesini artırmanıza yardımcı olacak uygulamalar hakkında bilgi verilmektedir. Basit bir kelime oyunu oluşturmak ve yapay zeka özellikleriyle geliştirmek için Antigravity'yi Modern Web Rehberi ve DevTools for Agents ile birlikte kullanıyorsunuz. Ardından, arkadaşlarınız ve ailenizle paylaşmak için Firebase'i kullanarak Google Cloud'a dağıtırsınız.

Neler öğreneceksiniz?

• Yapay zeka kodlama görevlerini mini ürün geliştirme yaşam döngüleri olarak ele alma
• Ürün gereksinimlerini mimari spesifikasyonlardan neden ayırmanız gerektiği.
• Doğrudan tarayıcıda prototip oluşturmak ve kodunuzu incelemek için çoklu aracı iş akışlarını düzenleme
• Hem geliştirme hem de kullanıcı deneyimlerinizi iyileştirmek için üçüncü taraf becerilerinden ve araçlarından nasıl yararlanabilirsiniz?
• Firebase MCP'yi kullanarak web uygulamalarını doğrudan üretime dağıtma.

Ön koşullar

• Kişisel Google Hesabı ve Google Cloud veya Firebase projesi (talimatlar proje kurulumu bölümünde)
• HTML, CSS ve JavaScript'e aşina olmanız gerekir.
• Chrome gibi bir web tarayıcısı
• Node.js yüklü olmalıdır (LTS önerilir).

2. Proje ayarlama

Google hesabı

Kişisel Google Hesabınız yoksa Google Hesabı oluşturabilirsiniz.

Google Cloud Console'da oturum açma

Kişisel bir Google Hesabı kullanarak Google Cloud Console'da oturum açın.

Faturalandırmayı etkinleştir

İpucu: Faturalandırmayı Google Cloud kredilerini kullanarak ayarlarsanız "Firebase projesi oluşturma" bölümüne geçebilirsiniz.

Kişisel faturalandırma hesabı oluşturmak için Cloud Console'da faturalandırmayı etkinleştirme bölümüne gidin.

Firebase projesi oluşturma

İpucu: Google Cloud kredilerini ayarlarken bir Google Cloud projesi oluşturduysanız Firebase projenizi ayarlamak için bu projeyi kullanın. Bu durumda, faturalandırma hesabınız zaten bağlı olduğundan hesabınızı bağlamanız gerekmez.

1. Firebase Console'a gidin ve kişisel Google Hesabınızla oturum açın.
2. Proje ekle'yi (veya Proje oluştur'u) tıklayın.
3. Proje oluşturma sihirbazında:
   • Bir proje adı girin (ör. wordup-web-app) veya proje kurulumu sırasında oluşturduğunuz Google Cloud projesini yeniden kullanın.
4. Faturalandırma Hesabını Bağlama
   • Firebase Console kenar çubuğunda, en alttaki plan rozetini bulun ("Spark" yazıyor). Yükselt'i tıklayın.
   • Giderken ödeyin planını seçin.
   • Proje kurulumu adımında oluşturduğunuz Faturalandırma hesabı'nı seçin.
   • Faturalandırma hesabınızı projeye eklemek için seçimi onaylayın. (Firebase Hosting, cömert bir ücretsiz katman sunar. Bu eğitimin tamamlanması genellikle 0 ABD doları tutarındadır.)

Araçları yükleme

• Antigravity 2.0: Hızlı ve en üst düzey kodlama için en yeni Gemini Flash modeliyle eşleştirilmiş, birlikte çalıştığınız birincil temsilci tabanlı kodlama aracı.
• Modern Web Rehberi: Kodlama ajanlarının modern CSS, HTML ve JavaScript yazmasına yardımcı olmak için kullanılan beceri. Antigravity Ayarlar > Özelleştirme > Google Eklentileriyle Oluşturma > Modern Web Rehberi bölümünden yükleyin.
• Ajanlar için Geliştirici Araçları: Ajanların Chrome'u kullanmasına, canlı DOM'u incelemesine, düzeni test etmesine ve çalışma zamanında hata ayıklamasına olanak tanır. Antigravity Ayarlar > Özelleştirme > Google Eklentileriyle Oluşturun > Chrome Geliştirici Araçları ve Antigravity Ayarlar > Özelleştirme > MCP Sunucuları Ekle > Ajanlar için Chrome Geliştirici Araçları üzerinden yükleyin.
• Firebase MCP sunucusu: Sorunsuz proje kurulumu ve tek istemli dağıtımlar için. Antigravity Ayarlar > Özelleştirme > Google Eklentileri ile Oluşturma > Firebase ve Antigravity Ayarları > Özelleştirme > MCP Sunucuları Ekle > Firebase üzerinden yükleyin.

3. Planla başlama

Ajanlı kodlamada yaygın olarak karşılaşılan bir durum, sıfır görevli istem ("Build me a word game") gönderip en iyi sonucu beklemektir. Bu durum neredeyse her zaman sıra dışı durumların atlanmasına, kod tabanlarının şişmesine ve bitmek bilmeyen hata düzeltme döngülerine yol açar.

Bunun yerine, her görevi mini bir ürün geliştirme yaşam döngüsü olarak ele alın. Kodlama aracıları, kod yazmadan önce fikirlerinizi netleştirmenize yardımcı olmak için ortak çalışan bir iş ortağı gibi hareket etmelerini sağlayan araştırma ve muhakeme araçlarına sahiptir. Fikrinizi sesli olarak ifade etmek, soruları sorun haline gelmeden önce bulup yanıtlamanıza yardımcı olur. Yazılım mühendisliğinde bu işleme lastik ördek hata ayıklama adı verilir. Projelerinizi ve özelliklerinizi planlamak için kodlama temsilcilerinizi "lastik ördek" olarak kullanabilirsiniz.

Basit bir kelime oyunu geliştiriyorsunuz. Temsilcinizden istediğiniz oyunu tasarlamanıza yardımcı olmasını isteyin.

I want to make a casual word guessing game. Go do deep research on those kinds
of games, then ask me questions to help me write a PRD for the game's features.

Bu, istemin temel şeklidir. Kendi ihtiyaçlarınıza göre yeniden düzenleyebilirsiniz. Buradaki önemli nokta, Deep Research'ün derinlemesine araştırma yapmasını ve bu araştırmaya dayalı olarak size sorular sorarak işinizi planlamanıza yardımcı olmasını sağlamaktır.

Kodlama aracıyla çalışmak çok fazla inceleme gerektirdiğinden bu istemle başlayın. Tam bir uygulama planını daha küçük ve odaklanmış parçalara ayırmak, incelemeyi çok daha kolay hale getirir, uç durumları erken yakalamanızı sağlar, temsilcinin eğitim verilerinin dışındaki bilgileri kullanmanıza olanak tanır ve en önemlisi, inceleme arasında daha fazla ara vermenizi sağlar.

• "Ne"yi "nasıl"dan ayırır: Kullanıcı deneyimini ve ürün kapsamını resmi bir Ürün Gereksinimleri Belgesi'nde (PRD) tanımlamak, ne istediğinizi nasıl uygulandığından ayırır. Böylece, ürün geliştirmenin tüm yönlerine aynı anda odaklanmak yerine her seferinde bir yönüne odaklanabilirsiniz.
• Sınır durumları erken aşamada belirler: Etkileşimli bir soru-cevap oturumu, tasarım veya uygulama başlamadan önce gereksinimlerinizi netleştirmenizi sağlar.
• Etkin temsilci araştırması: Temsilci eğitimi belirli bir tarihte sona erdiğinden ve eğitimdeki bilgiler oldukça özetlendiğinden, canlı araştırmadan alınan bilgiler aksi takdirde kaçırılacak yeni bilgileri getirebilir.

İpucu: Kodlama aracınızın beğendiğiniz veya beğenmediğiniz bir şey yaptığını görürseniz davranışını düzeltmek ya da pekiştirmek için proje klasörünüzdeki bir AGENTS.md dosyasına talimat ekleyebilirsiniz. Antigravity'nin size soru sorarken yerleşik soru aracını kullandığından emin olmak için aşağıdakileri eklemeyi deneyin:

When I ask you to ask me questions, you are **REQUIRED** to use your `ask_question` tool to do so.

Egzersiz 1

Şimdi sıra sizde. Projenizi oluşturun ve PRD'nizi oluşturun.

1. AGENTS.md dosyanıza, çıktınızı docs/plans/{{YYYY-MM-DD}}-{{description}}.md konumuna kaydetmesini söyleyen bir talimat ekleyin.
2. PRD'nizi oluşturmak için önceki araştırma istemini istediğiniz değişikliklerle birlikte çalıştırın.
3. [Ek Hedef] AGENTS.md dosyanızı, ajanınızın yapmasını istemediğiniz şeylerle güncelleyin ve isteminizi tekrar çalıştırın.

İpucu: Antigravity 2.0'da bu tür keşifler yapmak için özel olarak çalıştırabileceğiniz bir /grill-me komutu bulunur.

En iyi uygulama: Antigravity 2.0'da, Google Dokümanlar'da olduğu gibi satır satır yorum yapmanıza veya belirli metinleri vurgulayıp yorum bırakmanıza olanak tanıyan bir "Artifact" aracı bulunur. Yorumları isteme eklemek yerine satır içi olarak bırakmalısınız. Doküman genelinde yorumlar için istemi kaydedin. İsteminizi göndermek (boş bir istem olsa bile) yorumlarınızı gönderir ve Antigravity'ye dokümanınızı yorumlarınız dikkate alınarak yeniden oluşturmasını söyler.

Dikkat: Bazen yalnızca PRD yazmasını istediğinizde bile yazılım tasarımı ve mimarisi PRD'nize dahil edilir. Bu durumda, yorum bırakın veya bu öğeleri kaldırıp yalnızca kullanıcı deneyimine odaklanmasını isteyin.

4. Tarayıcıda tasarım yapma

Statik kullanıcı arayüzü tasarımı, genellikle çarpıcı görünen ancak uç durumları, kısıtlamaları ve gerçek kullanıcı etkileşimlerini hesaba katamayan maketlere dayanır. Ayrıca, kodda olduğu gibi, bir aracıdan site uygulamanızı "tasarlamasını" istemek, genel bir tasarıma (genellikle mor) yakın tasarımlarla sonuçlanır.

Web uygulamaları için, tarayıcıda tasarım yapmak üzere aracılar için geliştirici araçları aracılığıyla aracınızın web tarayıcısını kontrol etme özelliğini kullanabilirsiniz. İster tasarımlarınıza daha fazla ayrıntı katmak için çalışan bir tasarımcı, ister projenizin kullanıcı arayüzünü ve kullanıcı deneyimini iyileştirmek isteyen bir kod yazıcı veya geliştirici olun, ister ikisi birlikte çalışıyor olsun, oluşturduğunuz ortamda çalışmak daha iyi sonuçlar verir.

Tarayıcıda tasarım yapmak, tek bir çıktı üretmek için birlikte çalışan birden fazla ajanı koordine etme fırsatı da sunar. Bu alt aracılar, tek başına çalışan bir aracıya kıyasla daha iyi sonuçlar elde etmek için koordine edilebilen, belirli karakterlere ve hedeflere sahip aracılardır. Tasarım konusunda, görsel tasarım temsilcisinin, kullanıcı deneyimi temsilcisinin ve erişilebilirlik temsilcisinin tasarımınıza yardımcı olmak için birlikte çalışmasını ve tasarımları doğrudan tarayıcıda göstermesini isteyebilirsiniz.

Dikkat: Görevleri tamamlamak için alt aracıları kullanmak daha fazla jeton tüketir. Bu özellikler çok daha yüksek kaliteli sonuçlar üretebilse de bunların kullanımının ek maliyetlere yol açabileceğini unutmayın.

PRD'nize göre tasarım seçmenize yardımcı olacak bir tasarım ajanı paneli başlatın.

Using the PRD, start a panel of expert agents: one UX design, one web
accessibility, and one for visual design, and have them work together to design
3 different UI mockups and show them to me in-browser.

İpucu: Antigravity'nin istem alanına @ yazıp bakmasını istediğiniz dosyanın adını yazmaya başlayarak Antigravity'yi belirli bir dosyaya yönlendirebilirsiniz.

Bu durumda web gibi, oluşturduğunuz ortamda tasarım yapmak, statik bir ortamda tasarım yapmaktan daha avantajlıdır. Bu sayede, aksi takdirde yönetilmesi zor olan uç durumları ve kısıtlamaları yakalayabilir, üretime uygun anında görsel geri bildirim alabilirsiniz.

2. Egzersiz

Şimdi sıra sizde. Projenizi tasarlayın.

1. Tasarımınızı oluşturmak için önceki tasarım istemini istediğiniz gibi düzenleyerek çalıştırın. Görmek istediğiniz farklı tasarım yönleriyle ilgili fikirler ekleyin (ör. modern, eğlenceli, gerçekçi vb.).
2. Beğendiğiniz bir tasarımı seçin ve ajanınızla birlikte bu tasarım üzerinde yineleme yapın.
3. Temsilcinizden, PRD'nizi üzerinde anlaşmaya varılan tasarıma yönlendirecek şekilde güncellemesini isteyin.
4. Ek hedef: Seçtiğiniz tasarım için erişilebilirlik testleri ve duyarlı tasarım testleri yapın ve tasarımınızı bu denetimlere göre düzenleyin.

Dikkat: Ajanlar bazen aşırı hevesli davranarak bu talimatı tüm uygulamayı oluşturma onayı olarak algılayabilir. Düşünme sürecini izleyin ve beklenenden daha fazlasını yaptığını görürseniz durdurup yönünü değiştirmesini isteyin.

5. Şartname yazma

Onaylanmış bir PRD ("ne inşa edilecek") ve seçilmiş bir görsel tasarım ("nasıl görünecek") ile artık mimari konusunda teknik uyum ("nasıl inşa edilecek") sağlamanız gerekiyor.

Teknik tasarım belgesi veya spesifikasyon (kısaca spec), dosya yapılarını, durum yönetimini, bileşen arayüzlerini, etkinlik işlem hatlarını ve bağımlılıkları ayrıntılı olarak açıklar. Kod yazmadan önce bir spesifikasyon oluşturmak, uyumsuzlukları ve istenmeyen kodlama kalıplarını, üzerinde düşünülmesi ve yeniden düzenlenmesi daha zor olan kodlara dönüşmeden önce erken aşamada yakalamanızı sağlar.

Write a detailed technical design document on how to implement the game with
the chosen design.

Bunu yapma nedeniniz

• Mimari netlik: Bileşen hiyerarşisini ve durum geçişi akışını (ör. Idle → InGame → EvaluatingGuess → GameOver) tanımlamak, yarış durumlarını ve kırılgan spagetti kodunu önler.
• Modern standartlara uygunluk: Modern Web Guidance (Modern Web Rehberliği) etkinleştirildiğinde, aracı eski ağır kitaplıkları çekmek yerine modern standartlara (ör. CSS @container sorguları, modallar veya yardım katmanları için yerleşik
  öğeleri ve modüler ES modülleri) başvurur.
• Aşamalı incelemeler: İşlevsel PRD incelemesini teknik tasarım belgesi incelemesinden ayırmak, mimariyi kullanıcı deneyiminden bağımsız olarak değerlendirmenize olanak tanır.

Egzersiz 3

1. AGENTS.md'nıza çıkışınızı geçerli klasöre kaydetmesini söyleyin:

   PRDs should _always_ be written to the current project's root in `docs/plans/{{YYYY-MM-DD}}-{{description}}.md` format
   

2. Tasarım belgesi istemini çalıştırın ve dizin yapısı, etkinlik işleme ve depolama gibi konuları kapsadığından emin olarak belgeyi inceleyin.
3. Ek hedef: Henüz içermiyorsa uygulamadaki durum akışını açıklamak için Mermaid diyagramları ekleyin.

6. Son olarak, uygulamayı oluşturun.

Ürün gereksinimleri belgesi, kullanıcı arayüzü taslağı ve tasarım belgesi oluşturulduktan sonra geliştirme aşamasına geçilir. Bu üç öğe, temsilcilerin ne yapmaları gerektiği konusunda net ve kesin bir rehberlik sağlar.

Alt aracıları kullanmak için bir başka iyi fırsat. Oluşturulan kodun, önceden hazırladığınız tasarımlara ne kadar bağlı kaldığını incelemek için kodu oluşturduktan sonra bir test çalıştırabilir, oluşturulan kodun kalitesini kontrol etmek için ise başka bir test çalıştırabilirsiniz.

Use the PRD, design doc, and mockup to implement the site, then send out 2
agents, one to check how closely you followed the requirements, and one to
review the code.

Bunu yapma nedeniniz

İlk incelemecilerle birlikte spesifikasyon odaklı geliştirme, temsilcinize oluşturulacak net ve önceden incelenmiş gereksinimler sunar. Ayrıca, size ulaşmadan önce plana uyulduğundan emin olmak için yeni bir bakış açısı sağlar. Bu sayede kalite ve doğruluk artırılır.

• Onaylanmış şartlar: Temsilcinin ne istediğinizi tahmin etmesi gerekmez. Uygulama dışındaki her şeyi, herhangi bir kod yazılmadan önce zaten incelemişsinizdir.
• Yeni bir bakış açısı: Yeni bir bağlamda oluşturulan bir inceleme aracısı, kod tabanını oluşturmaktan kaynaklanan doğrulama önyargısına sahip olmadığından işlenmemiş uç durumları, eksik uygulama gereksinimlerini ve gözden kaçan diğer kod veya ürün ayrıntılarını yakalamada etkilidir.

Egzersiz 4

1. İncelemesini istediğiniz dosyalara işaret ederek oluşturma istemini çalıştırın.
2. Çıkışı çalışırken izleyin. Bu model, isteğinizi yerine getirmeye çalışırken gereksinimlerinizi gerekçelendirir. Bir şeyin kontrolden çıktığını düşünüyorsanız onu durdurup düzeltebilirsiniz.
3. Son siteyi görmek ve çalışmasını kontrol etmek için geliştirme sunucunuzu çalıştırmasını sağlayın.
4. Ek hedef: Otomatik testler eklemek için bu süreci tekrar uygulayın.
5. Ek hedef: Sitenin oluşturulmasını istediğiniz belirli bir çerçeve veya teknoloji yığını seçin. PRD, test modeli ve tasarım dokümanı ayrı olduğundan farklı çerçevelere uyum sağlamak kolay olacaktır.

7. Üretime dağıtma

Planlama, tasarım ve kodlama işlemlerini tamamlamış olmanız gerekir. Ne kaldı? Üretim ortamına dağıtma.

Deploy this site to my Firebase project [YOUR_PROJECT_ID] using Firebase
Hosting.

Dikkat: Bu işlem işe yaramazsa Firebase MCP'nin yüklü olduğundan emin olun. Ayrıca, bu işlemi ilk kez çalıştırdığınızda oturum açmanız gerekebilir.

Egzersiz 5

1. Proje kimliğinizi kullanarak dağıtım istemini çalıştırın.
2. Temsilci tarafından sağlanan canlı görüşme URL'sini kopyalayın.
3. Dağıtıldığını ve çalıştığını doğrulamak için canlı URL'yi açın.
4. Ek hedef: Üretim sitenizin Lighthouse denetimini çalıştırmak, Lighthouse puanını iyileştirmek için ayarlamalar yapmak ve güncellemeleri yayınlamak üzere aracıların DevTools'u kullanması.

8. [İsteğe bağlı] Yapay zeka iyileştirmeleri

Kelime oyununuz artık statik bir sözlük kullanarak tam işlevli olarak çalışıyor. Statik sözlüğü dinamik bir kelimeye dönüştürmek için Prompt API'den küçük bir yerel dil modeli kullanarak her seferinde bir istemde bulunabilirsiniz.

Dikkat: Henüz yapmadıysanız bu konuda size yardımcı olması için Modern Web Rehberi'ni yüklediğinizden emin olun.

Bu özellik tüm cihazlarda kullanılamadığından API ve modelin kullanılabilir olup olmadığını kontrol etmek için progresif geliştirme kullanırsınız. Varsa bunları kullanırsınız, yoksa statik listenize geri dönersiniz.

Egzersiz 6

Öğrendiklerinizi uygulamaya geçirin.

1. Geçerli bir gizli kelime oluşturmak için Prompt API'yi kullanacak bir PRD yazmak üzere temsilcinizle birlikte çalışın.
2. Tarayıcıda indirme ilerleme çubuğunu ve yapay zeka entegrasyonu kullanıcı arayüzünü tasarlayın.
3. Uygulama için bir spesifikasyon yazın. (İpucu: Burada doğru API söz diziminin kullanıldığından emin olmak için bir aracı çalıştırın.)
4. Yeni özelliğinizi geliştirin.
5. Üretime dağıtın.

9. Özet

Tebrikler. Temsilci tabanlı kodlamayla ilgili en iyi uygulamaları kullanarak modern, erişilebilir ve yapay zeka odaklı bir web uygulamasını başarıyla oluşturup iyileştirdiniz, geliştirdiniz ve dağıttınız.

Öğrendikleriniz

• Ürüne dayalı aracı iş akışları: Görevleri mini ürün yaşam döngüleri (PRD → Tasarım → Şartname → Oluşturma) olarak ele almanın borcu, inceleme ek yükünü ve ileri geri iletişimden kaynaklanan sürtünmeyi nasıl azalttığı.
• Çoklu aracı uzman panelleri: Birden fazla yapay zeka alt aracısı çalıştırmak, çalışmanızın kalitesini ve doğruluğunu nasıl artırabilir?
• PRD ve tasarım belgesi: İşlevsel kapsamı (plan) teknik mimariden (şartname) ayırmanın, sıfır görevli özellik isteminden daha ölçeklenebilir ve doğru bir süreç olmasının nedeni.
• Sorunsuz dağıtım: Sitenizi dağıtma gibi üçüncü taraf sistemlerine erişimi kolaylaştırmak için MCP sunucularını (ör. Firebase MCP) kullanma.