Ajanlı Ön Yüz Geliştirmenin Altı Temel Direği

Klasik yazılım mühendisliğinde ön yüz geliştirme genellikle görsel sezgilerin alanı olarak kabul edilir: bir CSS özelliğini değiştirirsiniz, tarayıcıyı yenilersiniz, boşluklara (padding) göz ucuyla bakar ve “güzel görünene” kadar ayarlamaya devam edersiniz.

Otonom yapay zekâ kodlama ajanlarının sizinle eş-programlama yaptığı, tam yığın arayüzleri yeniden modellediği ve refactor ettiği Ajanlı Kodlama (Agentic Coding) dünyasına geçtiğinizde bu “göz kararı yenile” döngüsü tamamen çöker. Yapay zekâ ajanı, siz ona doğrudan ekran görüntüsü vermediğiniz sürece piksellere gözlerini kısarak bakamaz. Ön yüz mimariniz dağınık sihirli sayılara, gevşek nesne tiplerine ve karmaşık boolean çorbalarına dayanıyorsa, ajan kaçınılmaz olarak zincirleme gerilemelere yol açar: ekranlar arasında tasarım kaymaları, bozulan dinamik import’lar ve sinsi null-pointer çökmeleri.

Bu gece, 50 yıllık akademik ders geçmişini, öğretim üyesi ayak izlerini ve derslik doluluk matrislerini barındıran BOUN Archive platformunu Boğaziçi Üniversitesi 2020 Kurumsal Kimlik Kılavuzu standartlarına modernize ederken tam olarak bu mimari meydan okumayla yüzleştik.

Geliştirdiğimiz çözümü Ajanlı Ön Yüz Geliştirmenin Altı Temel Direği olarak damıttık ve bunu SvelteKit, Next.js, Vue, Solid, Astro ve saf web standartları genelinde çalışan evrensel bir ajan yeteneğine (frontend-building) dönüştürdük.

---

1. Direk: Tasarım Token’larını Sınırda Merkezileştirin (Asla Başıboş Hex Kodları Kullanmayın)

Ajanlı ön yüz çalışmalarındaki en tehlikeli anti-pattern, modelin yirmi farklı şablon dosyası boyunca rastgele hex kodları (text-[#002d72], bg-[#faf8f5], border-[#e5e0d8]) uydurmasına veya tekrarlamasına izin vermektir.

Bir tasarım revizyonu veya karanlık mod temalama ihtiyacı doğduğunda, kırk farklı dosyadaki köşeli parantezli sınıfları değiştirmek pahalı ve hataya açık token aramaları gerektirir.

Ajanlı Çözüm

Tüm renk kimliklerini, yüzeyleri ve tipografi ölçeklerini merkezi bir tasarım sistemi temelinde tanımlayın:

/* layout.css (Tailwind CSS v4) */
@theme {
  --color-boun-navy: #002d72;          /* Pantone 280C Birincil Lacivert */
  --color-boun-sky: #8cc8ea;           /* Pantone 297C Gökyüzü Mavisi */
  --color-boun-gold: #c5a059;          /* Tarihi Kapı Bronz Altını */
  
  --color-canvas-light: #faf8f5;       /* Güney Kampüs Taş Zemin */
  --color-surface-light: #ffffff;      /* Saf Kart Yüzeyi */
  --color-border-light: #e5e0d8;       /* İnce Taş Kenarlık */

  --color-canvas-dark: #0a0e1a;        /* Boğaziçi Gece Mavisi Zemin */
  --color-surface-dark: #121827;       /* Koyu Arduvaz Yüzey */
  --color-border-dark: #1e293b;        /* Koyu Kenarlık */
}

Böylece ajana verilen komutlar üst seviye ve matematiksel olarak net hale gelir:

“Ana kartları bg-surface-light dark:bg-surface-dark ve aktif filtreleri text-boun-navy dark:text-boun-sky ile stillendir.”

---

2. Direk: Sınırda Ayrıştırın, Çekirdeğe Güvenin

Bir yapay zekâ ajanı doğrulanmamış bir JSON yanıtı döndüren bir API uç noktasıyla karşılaştığında, doğal savunma refleksi şablonun her yerine spekülatif ?. zincirleri serpiştirmektir:

<!-- Doğrulanmamış Sınırların Belirtisi -->
<span>{course?.instructor?.name ?? item?.instructor_name ?? 'Bilinmiyor'}</span>

Bu durum döngüsel karmaşıklığı patlatır ve kullanıcılar çalışma zamanında hata alana kadar şema uyuşmazlıklarını gizler.

Ajanlı Çözüm

Veri giriş noktasında (fetch işleyicileri, SvelteKit load fonksiyonları veya React Server Actions) sıkı şema doğrulamasını (Zod, Valibot veya ArkType) zorunlu kılın:

// src/lib/schemas/planner.ts
export const CoursePlannerSlotSchema = z.object({
  day_code: z.string(),
  slot_hour: z.number(),
  room_name: z.string().optional().nullable(),
  slot_title: z.string().optional().nullable(),
});

export const CoursePlannerItemSchema = z.object({
  id: z.union([z.number(), z.string()]).optional().nullable(),
  course_code: z.string().min(1),
  title: z.string().default(""),
  section: z.string().default(""),
  slots: z.array(CoursePlannerSlotSchema).default([]),
});

Veriler sınırda doğrulandığında, bileşenler temiz ve daraltılmış tipler alır. Ajan, döngüsel karmaşıklığı $CC \le 5$ olan yalın, deklaratif şablonlar yazar.

---

3. Direk: Deterministik Durum Modellemesi (Boolean Çorbası Yerine Durum Makineleri)

Ön yüz kodundaki klasik bir tuzak, asenkron arayüz durumlarını birbirine bağlı olmayan birden fazla bağımsız boolean ile yönetmektir:

// Boolean Çorbası Anti-Pattern'i
let isLoading = $state(false);
let isError = $state(false);
let isEmpty = $state(false);
let isRetrying = $state(false);

Bu durum $2^4 = 16$ olası durum kombinasyonu üretir ve bunların çoğu tamamen geçersizdir (örneğin aynı anda isLoading === true VE isError === true). Ajan bu tür bileşenlerde mantık düzenlerken uç durumları sıklıkla atlar veya boolean’lardan birini sıfırlamayı unutur.

Ajanlı Çözüm

Arayüz yaşam döngülerini birbirini dışlayan ayrık birleşimlerle (discriminated unions) veya sonlu durum makineleriyle modelleyin:

type ViewState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; message: string };

Her durum geçişi kesindir. Ajan, TypeScript derleyicisinin eksiksiz doğruladığı desen eşleme veya switch bloklarını güvenle kullanabilir.

---

4. Direk: Makine-Doğrulamalı Otomatik Geri Bildirim Döngüleri

Arka yüz mühendisliğinde pytest, cargo test veya go test anında ikili geri bildirim (çıkış kodu 0 veya 1) sağlar. Ön yüz geliştirmede ise ajanlar genellikle spekülatif değişiklikler yapıp durur; geliştirici ise daha sonra Vite derlemesinin veya TypeScript tip denetiminin çöktüğünü fark eder.

Ajanlı Çözüm

Her ajanlı ön yüz oturumu, tavizsiz bir doğrulama döngüsü tarafından yönetilmelidir:

graph LR
    EDIT[Bitişik Diff Düzenlemesi] --> CHECK[1. bun check / tsc]
    CHECK --> TEST[2. bun test / vitest]
    TEST --> BUILD[3. bun run build]
    BUILD --> VERIFY{Çıkış Kodu == 0?}
    VERIFY -->|Evet| DONE[Temiz Teslimat]
    VERIFY -->|Hayır| REMEDIATE[Anında Kendi Kendini Düzeltme]

Bu geceki oturumumuzda:

• bun check: 0 TypeScript hatası ve 0 Svelte uyarı teşhisi doğruladı.
• bun test: Planlayıcı serileştirmesini, sınır temizliğini ve CSV formül enjeksiyonu nötralizasyonunu doğrulayan 41 birim testini 85 milisaniyede başarıyla tamamladı.
• bun run build: @sveltejs/adapter-node ile üretim paketlemesini 12.30 saniyede hatasız derledi.

---

5. Direk: Katmanlaşma Yerine Yerellik (LoB & AHA)

Aşırı soyutlama (over-engineering) ajan hızını öldürür. Tek bir buton için 10 mikro dosya (ButtonContainer.tsx, ButtonWrapper.tsx, useButtonState.ts, button.types.ts) oluşturmak bağlam token’larını tüketir, dosya ağacını kirletir ve ajanların import yollarını uydurmasına yol açar.

Aksine, bir bileşenin 600 satıra kadar büyümesine izin vermek de token sınırlarına ve düzenleme çakışmalarına neden olur.

Ajanlı Çözüm

1. AHA (Aceleci Soyutlamalardan Kaçınma): Bir desen 3 farklı bileşende tıpatıp tekrarlanana kadar stilleri, tipleri ve yardımcı fonksiyonları aynı bileşende tutun (Üç Kuralı).
2. 250-300 Satır Tavanı: Tek bir görünüm (departments/+page.svelte gibi) 300 satırı aştığında, uyumlu alt görünümleri dışarı çıkarın:
   • DeptCourseTable.svelte (99 satır)
   • DeptInstructorTable.svelte (106 satır)
3. Ana kontrolcü 502 satırdan anında okunabilir, odaklanmış bir görünüme düşer.

---

6. Direk: Savunmacı İstemci Önbelleği ve Depolama Dayanıklılığı

Durumunu localStorage veya sessionStorage içinde saklayan ön yüz uygulamaları sıklıkla “önbellek zehirlenmesinden” muzdariptir: Kullanıcı bir güncellemeden sonra uygulamayı ziyaret eder, tarayıcısındaki eski şema istemci tarafı JavaScript paketini çökerterek beyaz ekran verir ve çerezleri temizleyene kadar siteye erişemez.

Ajanlı Çözüm

İstemci önbellekleri saklanan içeriğe asla körü körüne güvenmemelidir. Başlangıçta kendi kendini iyileştirmelidir:

export function safeParsePlannerCourses(jsonString: string): CoursePlannerItem[] {
  if (!jsonString || typeof jsonString !== "string") return [];
  try {
    const raw = JSON.parse(jsonString);
    if (!Array.isArray(raw)) return [];
    
    const validCourses: CoursePlannerItem[] = [];
    for (const item of raw) {
      const parsed = CoursePlannerItemSchema.safeParse(item);
      if (parsed.success) validCourses.push(parsed.data);
    }
    return validCourses;
  } catch {
    return [];
  }
}

Depolanan bir girdi bozuksa veya eskiyse, ayrıştırıcı geçerli öğeleri alır, zehirlenmiş kayıtları ayıklar ve localStorage’ı arka planda sessizce onarır.

---

Evrensel frontend-building Yeteneği

Gelecekteki tüm projelerimizde her ajanlı oturumun bu ilkeler üzerinde çalışmasını sağlamak için bu altı direği açık ve yeniden kullanılabilir bir yetenekte kurallaştırdık:

• Konum: ~/.gemini/config/skills/frontend-building/SKILL.md
• Çerçeve Kapsamı: Svelte 5 (Runes & Snippets), React 19 / Next.js App Router, Vue 3 / Nuxt Composition API, SolidJS Signal Takibi, Astro Sıfır-JS ve Saf HTML/CSS/Web Bileşenleri.

Bir yapay zekâ ajanıyla bu kurallara sahip bir ön yüz yığınında eşleştiğinizde, ön yüz mühendisliği bir tahmin döngüsü olmaktan çıkar. Deterministik, makine-doğrulamalı ve olağanüstü hızlı bir üretim motoruna dönüşür.