Yapay zeka ile Chrome eklentisi yapmak (Manifest V3)

Yapay zeka ile Chrome eklentisi yapmak, vibe coding’e başlamanın en kolay yollarından biri: eklentiler birkaç küçük dosyadan oluşur, sunucu kurmadan tarayıcında anında denenir ve Claude Code ya da Codex gibi bir kodlama ajanı Manifest V3 yapısını iyi bilir. İşin zor kısmı kod değil; doğru parçayı (content script, service worker, popup) seçmek, en az izni istemek ve API anahtarlarını eklentinin içine koymamak. Bu yazıda boş klasörden Chrome Web Store’a kadar izlediğim yolu anlatıyorum.

Örnek olarak basit ama gerçek bir eklenti yapacağız: açık sayfadaki makaleyi bir yapay zeka API’siyle özetleyen bir eklenti. Vibe coding ile ilk sürümü bir öğleden sonra çıkarmak mümkün; mağazaya çıkacak sürüm için birkaç kurala daha dikkat etmek gerekiyor.

Önce parçaları tanı

Ajana ne istediğini anlatabilmen için bir Chrome eklentisinin dört temel parçasını bilmen yeter:

• manifest.json: Eklentinin kimliği. Adı, sürümü, hangi dosyaların ne işe yaradığı ve hangi izinleri istediği burada yazar. Bugün yeni eklentiler Manifest V3 ile yazılıyor.
• Content script: Ziyaret ettiğin sayfanın içinde çalışan JavaScript. Sayfanın metnini okuyabilir, düğme ekleyebilir, öğe gizleyebilir. Sayfanın kendi JavaScript değişkenlerine doğrudan erişemez; ayrı bir “dünyada” çalışır.
• Service worker (arka plan): Sayfadan bağımsız çalışan kod. Eklenti simgesine tıklama, sekme değişimi, alarm gibi olaylara tepki verir ve ağ isteklerini atar. Önemli bir özelliği var: boşta kaldığında Chrome onu kapatır. Global değişkende tuttuğun her şey kaybolabilir.
• Popup ve ayarlar sayfası: Simgeye tıklayınca açılan küçük pencere ve kullanıcı ayarları için ayrı bir sayfa. Bunlar sıradan HTML sayfalarıdır.

Bu parçalar birbirleriyle chrome.runtime.sendMessage ve chrome.tabs.sendMessage ile mesajlaşır. Ajanın yazdığı kodda bir şey “çalışmıyorsa” sorun çoğu zaman yanlış parçada çalışan koddur; örneğin service worker’da document kullanmaya çalışmak.

1. Kurulum ve proje yapısı

İhtiyacın olanlar: Chrome (ya da Chromium tabanlı başka bir tarayıcı), Git, bir kod editörü ve bir kodlama ajanı. İlk eklenti için derleme aracı şart değil; düz JavaScript yeter. Projeyi büyütmek istersen Vite tabanlı WXT gibi eklenti çatıları TypeScript ve otomatik yeniden yükleme getirir, ama ilk sürümde araya bir katman daha koymamanı öneririm. Ajanın yaptığı hatayı görmek daha kolay olur.

mkdir sayfa-ozetleyici && cd sayfa-ozetleyici
git init

Sonra proje köküne ajanın her oturumda okuyacağı kısa bir kural dosyası koy (CLAUDE.md ya da AGENTS.md):

# Sayfa Özetleyici (Chrome eklentisi)
- Manifest V3, düz JavaScript, derleme adımı yok.
- İzinler en az düzeyde: activeTab, scripting, storage. <all_urls> yok.
- Uzaktan kod yüklenmez; eval ve uzak <script> yasak.
- API anahtarı eklentide tutulmaz; istekler bizim sunucumuza gider.
- Service worker'da kalıcı durum global değişkende değil chrome.storage'da.
- Yeni izin ya da paket eklemeden önce sor.

2. İlk prompt

İlk mesajda ajandan ne yapacağını ve hangi dosyaları oluşturacağını açıklamasını, sonra kodu yazmasını istiyorum:

CLAUDE.md'yi oku. Manifest V3 ile bir Chrome eklentisi yap:
- Kullanıcı eklenti simgesine tıklayınca popup açılsın, içinde "Özetle" düğmesi olsun.
- Düğmeye basınca açık sekmedeki makale metni alınsın (activeTab + scripting
  ile, content script'i yalnızca o anda enjekte et).
- Metin service worker'a gönderilsin; service worker bunu
  https://api.ornek-sunucum.com/summarize adresine POST etsin.
- Gelen özet popup'ta gösterilsin; hata olursa okunur bir mesaj çıksın.
- Son 10 özeti chrome.storage.local'da tut.
Önce dosya listesini ve her dosyanın görevini yaz, sonra kodu oluştur.
En sonda eklentiyi nasıl yükleyip deneyeceğimi adım adım anlat.

Ajanın üreteceği manifest.json aşağı yukarı şöyle olmalı:

{
  "manifest_version": 3,
  "name": "Sayfa Özetleyici",
  "version": "0.1.0",
  "description": "Açık sayfadaki makaleyi tek tıkla özetler.",
  "action": { "default_popup": "popup.html" },
  "background": { "service_worker": "background.js" },
  "permissions": ["activeTab", "scripting", "storage"],
  "host_permissions": ["https://api.ornek-sunucum.com/*"]
}

Burada dikkat ettiğim şey izin listesi. activeTab, kullanıcı simgeye tıkladığında yalnızca o sekmeye geçici erişim verir. Ajanlar kolaylık olsun diye sıkça "<all_urls>" ya da "tabs" ekler; bu hem kullanıcıyı korkutan bir uyarı çıkarır hem de mağaza incelemesini uzatır.

3. Yükle, dene, hata ayıkla

Eklentiyi mağazaya koymadan kendi tarayıcında böyle denersin:

1. Adres çubuğuna chrome://extensions yaz.
2. Sağ üstten Geliştirici modunu aç.
3. Paketlenmemiş öğe yükle ile proje klasörünü seç.
4. Simgeyi araç çubuğuna sabitle ve bir makale sayfasında dene.

Kodu değiştirdiğinde chrome://extensions sayfasındaki yenile düğmesine basman gerekir. Content script değiştiyse ayrıca denediğin sayfayı da yenile.

Hata ayıklarken en çok işe yarayan üç yer:

• Service worker: Eklenti kartındaki “service worker” bağlantısı ona ait DevTools’u açar. Ağ istekleri ve arka plan hataları burada.
• Popup: Popup açıkken üzerine sağ tıkla, İncele’yi seç.
• Content script: Sayfanın kendi DevTools konsolunda görünür; konsolun üstündeki bağlam menüsünden eklentini seçebilirsin.

Eklenti kartında bir Hatalar düğmesi çıktıysa içeriği olduğu gibi kopyalayıp ajana ver:

Eklentiyi yükledim, popup'ta "Özetle"ye basınca şu hata çıkıyor:
[hata metni]
Service worker konsolunda da şu var:
[log]
Nedenini açıkla, düzelt, hangi dosyada ne değiştirdiğini listele.

“Çalışmıyor” demek yerine nerede, neye basınca ve hangi konsolda ne gördüğünü yazmak ajanın tahmin etmek yerine düzeltmesini sağlar.

4. Depolama: doğru yeri seç

• chrome.storage.local: Bu cihazdaki veriler; özet geçmişi gibi.
• chrome.storage.sync: Kullanıcının Chrome hesabıyla cihazlar arasında eşitlenir. Kotası küçüktür; yalnızca ayarlar için kullan.
• chrome.storage.session: Tarayıcı kapanınca silinir; service worker kapanıp açılırken geçici durumu tutmak için iyidir.

Service worker’da localStorage yoktur. Ajan onu kullanmaya çalışırsa bu sorunun cevabı yukarıda. manifest.json’a storage iznini eklemeyi de unutma.

5. API anahtarlarını eklentiye koyma

Bu, yapay zekayla yapılan eklentilerde en sık gördüğüm hata. Ajan, “OpenAI anahtarını şuraya yapıştır” diye background.js içine bir sabit koyar. Yayımladığın eklenti bir ZIP dosyasıdır; isteyen indirip açar ve anahtarını okur. Küçültmek ya da karıştırmak (obfuscation) bunu değiştirmez.

Doğru yapı bir ara sunucu:

1. Eklenti kendi sunucuna (https://api.ornek-sunucum.com/summarize) istek atar.
2. Sunucu anahtarı kendi ortam değişkeninde tutar ve asıl yapay zeka API’sini çağırır.
3. Sunucu istek sayısını sınırlar (kullanıcı ya da IP başına), çok uzun metinleri reddeder.

Bu sunucu için ayrı bir proje açıp ajana şunu söyleyebilirsin:

Küçük bir HTTP servisi yaz: POST /summarize, gövdede { text } alır.
Metni 20.000 karakterle sınırla, ortam değişkenindeki API anahtarıyla
yapay zeka API'sini çağır, { summary } döndür. CORS'u yalnızca
chrome-extension://<EKLENTI_ID> kaynağına aç. Basit bir hız sınırı ekle.
Anahtarı loglara yazma. .env.example dosyası oluştur.

Eklenti kimliği, paketlenmemiş yüklediğinde chrome://extensions sayfasında görünür; mağazada yayımlandığında ise değişebilir. Yayımlamadan önce CORS ayarını güncellemeyi unutma. Kullanıcı kendi anahtarını girecekse (bazı geliştirici araçlarında olduğu gibi) bunu ayarlar sayfasında iste ve chrome.storage.local’da tut; kendi anahtarını asla gömme.

Yapay zekanın sık yaptığı hatalar

• Manifest V2 kodu yazmak. background.page, chrome.browserAction, kalıcı arka plan sayfası ya da webRequestBlocking görürsen eski örneklerden gelmiştir. Ajana “Manifest V3 karşılığını kullan” de.
• Service worker’ın hep açık olduğunu varsaymak. Global değişkende tutulan sayaç ya da setInterval bir süre sonra durur. Zamanlanmış işler için chrome.alarms, durum için chrome.storage kullanılmalı.
• Fazla izin istemek. <all_urls>, tabs, history gibi izinler genelde gereksizdir. Ajana “her izni neden istediğini tek cümleyle açıkla” de; açıklayamadığı izni çıkar.
• Uzaktan kod yüklemek. CDN’den bir kütüphaneyi <script> ile çekmek ya da eval kullanmak Manifest V3’te yasak. Kütüphane pakete dahil edilmeli.
• Content script’te sayfanın değişkenlerine erişmeye çalışmak. Ayrı dünyada çalıştığı için window.ornekUygulama göremez; DOM üzerinden çalışmalı.
• Mesajlaşmada asenkron cevabı unutmak. onMessage dinleyicisinde asenkron cevap verilecekse return true gerekir; yoksa popup boş cevap alır.
• Her sitenin aynı HTML’e sahip olduğunu varsaymak. Makale metnini almak için önce article ya da main öğesine bak, yoksa makul bir yedek kullan. Üç farklı sitede dene.

Güvenlik

• Gizli anahtarlar .env’de, sunucuda. Eklenti klasöründe .env olmasın; ZIP’e girer.
• API anahtarını sohbete yapıştırma. Ajanın anahtarı değil, değişkenin adını bilmesi yeter.
• Ajanın çalıştırdığı komutları oku. Özellikle paket kurulumları ve curl … | sh gibi komutlar.
• Sayfadan gelen veriye güvenme. Content script’in okuduğu metni popup’ta innerHTML ile basma; textContent kullan. Aksi halde kötü niyetli bir sayfa eklentinin içine kod sokabilir.
• Mesajın kimden geldiğini kontrol et. Dışarıdan mesaj kabul etmen gerekmiyorsa externally_connectable ekleme; ekliyorsan izinli kaynakları dar tut.
• Kullanıcı verisini gerektiği kadar topla. Sayfa metnini sunucuna gönderiyorsan bunu açıkça söyle ve sunucuda saklama.

6. Chrome Web Store’da yayımlama

Yayımlama adımları kabaca şöyle:

1. Geliştirici hesabı aç. Chrome Web Store geliştirici panelinde kayıt ol; tek seferlik bir kayıt ücreti var.
2. Paketi hazırla. Proje klasörünü (manifest kökte olacak şekilde) ZIP’le. .git, node_modules, test dosyaları ve .env içinde olmasın.
3. Mağaza sayfasını doldur. Açıklama, ekran görüntüleri, simgeler, kategori.
4. Gizlilik bölümünü doldur. Eklentinin tek bir amacını (single purpose) yaz, istediğin her izin için gerekçe ver, hangi kullanıcı verisini topladığını beyan et. Veri topluyorsan erişilebilir bir gizlilik politikası adresi gerekir.
5. İncelemeye gönder. Süre değişken. Geniş host izinleri ve okunması zor kod incelemeyi uzatabilir; reddedilirsen gelen e-posta hangi kurala takıldığını söyler.

Ajan burada da yardımcı olur:

Bu eklentiyi Chrome Web Store'a göndereceğim. manifest.json'daki her izin
için mağaza formuna yazılacak bir cümlelik gerekçe hazırla, tek amaç
açıklamasını yaz ve topladığımız kullanıcı verilerini listele.
Gereksiz görünen bir izin varsa söyle. Yayın için ZIP oluşturan bir
komut ver; .git, .env ve test dosyaları dahil olmasın.

Güncelleme yayımlarken manifest.json’daki version değerini artırman gerekir. Yeni bir izin eklemek, mevcut kullanıcılarda eklentiyi yeniden onay isteyene kadar devre dışı bırakabilir; izin eklemeden önce iki kez düşün.

Bunu AgentVera ile nasıl yapıyorum

Eklentiyi tek bir terminal ve tarayıcıyla da yaparsın. Ben eklenti ile ara sunucuyu aynı anda geliştirirken AgentVera kullanıyorum:

• İki ajan, iki iş. Çalışma alanında eklenti için bir Claude Code ajanı, ara sunucu için bir Codex ajanı açıyorum; ikisi ayrı klasörlerde ya da ayrı git worktree’lerde çalışıyor.
• Sunucuyu denemek. API istemcisi sunucunun endpoint’lerini koddan bulabiliyor; /summarize’ı eklentiye bağlamadan önce oradan deniyorum.
• Hatayı ajana göndermek. Terminaldeki bir hata çıktısını Ajana gönder ile seçili ajana iletiyorum; kopyala-yapıştır yok.
• Birleştirmeden önce inceleme. Kod incelemesi biten her turu kontrol ediyor, Git paneli diff’i gösteriyor. Fazladan bir izin ya da gömülü bir anahtar genelde burada yakalanıyor.
• Token takibi. Panelde canlı bağlam boyutu görünüyor; küçük bir eklenti için şişmiş bir oturuma gerek yok.

Eklentiyi Chrome’a yükleyip denemek yine senin işin; AgentVera bunu senin yerine yapmaz.

Sonuç

Yapay zeka ile Chrome eklentisi yapmak için önce parçaları (manifest, content script, service worker, popup) tanı, ajana kuralları yazılı ver, en az izinle başla, paketlenmemiş yükleyip konsollardan hata ayıkla ve API anahtarlarını bir ara sunucunun arkasında tut. Mağazaya göndermeden önce her izni gerekçelendirebildiğinden emin ol. Ajanların ürettiği kodu nasıl kontrol edeceğine dair daha fazlası için yapay zeka kod incelemesi yazısına, araç seçimi için de en iyi yapay zeka kodlama araçları yazısına bakabilirsin.