RƏSƏDXANA

Həftə 6 · 11/23

Koddan əvvəl: xəritəni çək

6 dəqiqəlik oxu

Evi tikməzdən əvvəl plan çəkilir: su borusu haradan keçir, qapı hara açılır. Plan olmadan da ev tikilir — sonra hamam mətbəxin üstündə qalır.

Xəritə hissələri və aralarındakı axını göstərir: kim hansı məlumatın sahibidir, məlumat hansı istiqamətdə gedir, harada yoxlanılır. AI otaqları doldurur, divarları sən çəkirsən.

[browser]  --(untrusted)-->  [API: who are you? may you?]  -->  [DB]
    ^ shows things                    ^ decides things            ^ keeps things
Üç qutu, iki ox. Sol tərəfdə deyilən hər şey iddiadır; ortada isə hökm verilir.

Çox deyilən söz: Redaktoru aç, ilk fayldan başla — arxitektura yolda özü yaranar.

Kod yazdıracaq ilk prompt-dan əvvəl bir səhifə yazırsan: hansı hissələr var, hər məlumatın sahibi kimdir, məlumat hansı istiqamətdə axır, etibar sərhədləri haradadır. AI hissələri doldurur, divarların harada olacağına isə o qərar vermir. Onu öz başına buraxsan, ən tez yazılan yolu seçir.

Dərin modul, kiçik interfeys

Yaxşı modul az şey göstərib çox şeyi gizlədir. Sessiya modulu xam yaddaş açarlarını yox, get/set/clear göstərməlidir — o zaman açarın iki sahibi ola bilməz.

Sən bunu istə

// session-token.ts — the only file that touches the key
export function getToken(): string | null
export function setToken(token: string): void
export function clearToken(): void

Etibar sərhədlərini xəritəyə çək

Brauzerdən serverə keçən hər ox yoxlamanın yaşadığı yerdir: kimlik, icazə, validasiya. Xəritədə oxu görmürsənsə, yoxlamanı da unudacaqsan.

Sən bunu istə

[browser] --(untrusted)--> [API: authn, authz, validate] --> [DB]
              ^ everything left of the API is a suggestion

Məlumatın istiqamətinə qərar ver

Paylaşılan faktlar (səslər, sahiblik) üçün server nüfuzludur. Client yalnız göstərir və istəyir. İkitərəfli sinxronizasiya uyğunsuzluğun başladığı yerdir.

Diff oxuyanda soruş: AI-dan kodun xəritəsini istə: hansı fayl hansı məlumatın sahibidir? Sonra sahibi olmayan məlumatı axtar.

Terminlər

module boundary
Bir hissənin bitib digərinin başladığı yer; hər hissə yalnız öz işini görür.
data flow
Məlumatın hansı istiqamətdə getdiyi: client → API → DB və geri.
ownership
Bir məlumatı yazmağa haqqı olan tək yer; qalanları onu oxuyur.
trust boundary
Məlumatın yoxlanılmalı olduğu keçid: brauzerdən gələn heç nəyə avtomatik etibar edilmir.
coupling
İki hissənin bir-birindən nə qədər asılı olduğu; biri dəyişəndə digəri də qırılırsa, bağlılıq yüksəkdir.

İndi sən yoxla

1Hansı prompt bakımı mümkün olan bir başlanğıc verir?

2Daxil olmuş istifadəçilər serverə anonim kimi çatır. Niyə?

// auth-store.ts
localStorage.setItem("app-auth", JSON.stringify({ user, token }));

// api.ts
const token = localStorage.getItem("session-token");
fetch(url, { headers: token ? { Authorization: `Bearer ${token}` } : {} });

Hazır prompt

İngiliscədir, çünki terminlər ingiliscədir. Tərcümə etsən də terminləri saxla.

prompt
Before writing any code, produce an architecture note for <feature>.

1. Components: list each module/file and its single responsibility.
2. Data ownership: for every piece of state (tokens, ids, user data, cache),
   name the ONE module that owns it. Everything else reads through that owner.
3. Data flow: show the direction (client -> API -> DB, and back).
   Mark every trust boundary.
4. Out of scope: what this feature will not do.

Do not write implementation yet. Stop and wait for my approval.

Öz kodunda

  1. 1Öz layihəndə daxil olmuş istifadəçiyə aid bir funksiya seç (məsələn, səs vermək).
  2. 2AI-dan kimliyin yolunu izləməsini istə: harada yaranır, harada saxlanılır, harada oxunur, necə göndərilir, harada yoxlanılır — hər biri fayl:sətir ilə.
  3. 3Bunu kağızda qutular və oxlarla çək.
  4. 4Eyni faktın saxlandığı hər yeri qırmızı ilə işarələ.

Bunu görəndə bitib: Sessiyanın sahibi olan tək faylı göstərə bilirsən və onu oxuyan hər faylın adını çəkə bilirsən.

Daha dərinə

Oxumaq üçün

  • A Philosophy of Software Design (2nd edition) · John Ousterhout, 2021 · Dərin modullar və məlumatın gizlədilməsi
  • Vibe Coding: Building Production-Grade Software With GenAI, Chat, Agents, and Beyond · Gene Kim, Steve Yegge, 2025 · Agentə sərhəd qoymaq