Kapston‑inteqrasiya: texniki‑məhsul demo və “App pasportu”

1. “App pasportu” nədir və sizə niyə lazımdır

App pasportu — kompakt, amma dolğun bir sənəddir (adətən 1–2 səhifəlik Markdown və ya README bölməsi), hansı ki, istənilən şəxsə sizin ChatGPT App‑iniz barədə tez təsəvvür yaradır: necə qurulub, məhdudiyyətləri nələrdir, necə pul qazanır və production‑da onu necə idarə edirsiniz.

Bu marketinq broşurası deyil. Burada “ən innovativ AI texnologiyaları” haqqında deyil, çox praktik şeylərdən söhbət gedir:

• ChatGPT, sizin widget, MCP serveri, agentlər və ACP/Stripe arasında sərhəd haradan keçir;
• hansı PII saxlanılır, OAuth/scopes və sirlərin rotasiyası necə qurulub;
• latency və availability üçün SLO‑larınız hansılardır, hansı dashboard və alertlər var;
• bir uğurlu ssenarinin orta dəyəri nə qədərdir və ondan necə gəlir əldə edirsiniz;
• hansı tipik insidentlər artıq təsvir olunub və runbook‑lar harada saxlanılır;
• bu App ilə yaxın aylarda nə etməyi planlaşdırırsınız.

Pasporta keçidlərin və high‑level təsvirlərin aqreqatoru kimi baxmaq olar: koddansa bir qədər gec, “investorlar üçün rəsmi təqdimat”dan isə daha tez dəyişir.

ChatGPT App tərtibatçısı kimi sizin üçün pasport həm də yetkinlik üçün yoxlama siyahısıdır. Əgər hansısa bölmə boşdursa (“SLO‑nu heç təsvir etməmişik…”), bu yaxşı bir qırmızı siqnaldır: deməli, təkcə sənədləşmə yox, praktika da çatışmır.

2. GiftGenius pasportunun əsas strukturu

GiftGenius üçün aşağıdakı strukturu götürmək məntiqlidir (öz App‑iniz üçün cüzi dəyişə bilərsiniz, amma ümumi fikir eyni qalacaq).

Kim nəyi və nə üçün oxuyur — bunu kiçik cədvəl şəklində göstərək:

Daha sonra bu blokların hər birini nəzərdən keçirəcək və paralel olaraq GiftGenius üçün real PASSPORT.md planını cızacağıq.

3. Arxitektura: bütün steki bir şəkildə necə göstərmək olar

Arxitektura bölməsi pasportun ürəyidir. Burada 200 düzbucaqlıdan ibarət UML diaqramı çəkmək lazım deyil. İstifadəçidən ChatGPT‑də başlayıb sizin DB və ödəniş qatına qədər qatları və axınları göstərmək vacibdir. Apps SDK və MCP ilə ChatGPT App üçün bu yol standartdır.

Rahat format — birbaşa PASSPORT.md daxilində Mermaid diaqramı. Məsələn, GiftGenius üçün:

flowchart TD
  U[User in ChatGPT] --> C[ChatGPT + GPT-5]
  C --> W[GiftGenius Widget
Next.js + Apps SDK]
  W --> MCP[MCP Server
giftgenius-mcp]
  MCP --> A[Agent: GiftPlanner]
  A --> DB[(Postgres: products,gifts)]
  A --> ACP[ACP / Stripe]
  ACP --> ORD[(Orders)]

Mətnin altında əsas ssenarini təsvir edirsiniz:

İstifadəçi çatda hədiyyə alıcısını təsvir edir. Model MCP serverində suggest_gifts alətini (tool) çağırmağa qərar verir. Agent əlavə olaraq kataloqları resurs kimi oxuya və bir neçə tool icra edə bilər. Daha sonra hədiyyə seçildikdə Stripe‑də ACP sessiyası yaradılır, checkout webhooks vasitəsilə keçirilir və nəticə DB‑də saxlanılır.

Burada texnologiyaları da qeyd etmək yaxşıdır: Next.js 16 + Apps SDK, MCP serveri Node/Python üzərində, PostgreSQL, keş üçün Redis, ödənişlər üçün Stripe.

Arxitekturaya kiçik texniki fraqment də əlavə etmək olar ki, “şəkildəki kərpiclərin” kodda necə göründüyü aydın olsun. Məsələn, requestId və userId‑ni MCP klientinə ötürən Next.js route fraqmenti:

// app/api/suggest-gifts/route.ts
import { mcpClient } from "@/lib/mcpClient";

export async function POST(req: Request) {
  const { occasion, budget } = await req.json();
  const requestId = crypto.randomUUID();      // loglar üçün treys
  const userId = req.headers.get("x-user-id") ?? "anonymous";

  const result = await mcpClient.callTool("suggest_gifts", {
    occasion, budget, requestId, userId,
  });

  return Response.json({ requestId, result });
}

Belə bir parça diaqramdakı “Widget → MCP” abstrakt oxunu real kodla əlaqələndirməyə kömək edir.

4. Security & Privacy: dəqiq nələri sabitləşdirmək lazımdır

Pasportda təhlükəsizlik “HTTPS istifadə edirik və backend TypeScript‑dədir, deməli hər şey qaydasındadır” haqqında deyil. Təhlükəsizlik, compliance və hüquq blokunun suallarına konkret cavablar lazımdır.

GiftGenius üçün qısa şəkildə təsvir edin:

Autentifikasiya və avtorizasiya modeli:
commerce ssenariləri üçün MCP Auth Server üzərindən PKCE ilə OAuth 2.1 istifadə olunur; token user_id və tenant_id ilə bağlıdır, checkout ilə əlaqəli bütün tool çağırışları commerce.checkout scope‑unu tələb edir.

Hansı məlumatlar PII‑dır və onlarla necə rəftar edirsiniz.
Məsələn: email və ad — PII, hədiyyə üstünlükləri — psevdonimləşdirilmiş məlumatdır; yalnız hash‑lənmiş email‑i loglayırıq, çatdırılma ünvanını saxlamırıq — onu Stripe və webhook‑lara ötürürük.

Retention və silinmə necə qurulub:
alətlərin loglarını 30 gün saxlayırıq, commerce hadisələrini — 1 il, istifadəçi istəyinə əsasən onun sifarişlərini və əlaqəli analitik hadisələri silə bilərik.

Sirləri necə idarə edirsiniz:
qısa olaraq göstərin ki, OpenAI API key, Stripe secret, OAuth client secret harada saxlanılır (məsələn, managed secret store), nə qədər tez‑tez rotasiya olunur və staging‑də necə test edilir.

Pasportda “minimal zəruri hüquqlar” prinsipini nümayiş etdirmək üçün kiçik texniki fraqment vermək olar.

// config/scopes.ts
export const TOOL_SCOPES = {
  suggest_gifts: ["read:products"],
  get_gift_details: ["read:products"],
  create_checkout_session: ["read:products", "write:orders", "stripe:checkout"],
} as const;

Daha sonra alətin və MCP‑auth təsvirində eyni scope‑lara istinad edirsiniz. Bu artıq “least privilege” haqqında söz yığını deyil, konkret kontraktdır.

5. Observability və SLO: App‑in necə yaşadığını görmək üçün

Növbəti blok — müşahidəolunarlıq: App‑in canlı və sağlam olduğunu necə anladığınız. Burada strukturlu loglar, metriklər, SLO və dashboard keçidləri birləşir.

GiftGenius üçün məntiqlidir ki, təsvir edəsiniz:

Açar SLO‑lar.
Məsələn: MCP əlçatanlığı ≥ 99.5%, suggest_gifts üçün p95 latency < 5 saniyə, checkout üçün success‑rate ≥ 99%.

Bu SLO‑lara harada baxmaq olar.
Grafana/Datadog/… içində dashboard adı və URL (pasportda sadəcə “Dashboard: GiftGenius / SLO” yazmaq olar).

Strukturlu logların formatı.
Müşahidəolunarlıq modulunda artıq sahələri düşünmüşdünüz: request_id, tool_name, user_id/tenant_id, tokens_in/tokens_out, cost_estimate, duration_ms, error_code. Pasportda kiçik JSON nümunəsi faydalıdır, amma daha yaxşısını edək — həm də kodda istifadə olunan TypeScript tipini göstərək.

// lib/logging.ts
export type ToolInvocationLog = {
  level: "info" | "error";
  timestamp: string;
  requestId: string;
  userId?: string;
  toolName: string;
  tokensIn?: number;
  tokensOut?: number;
  costEstimateUsd?: number;
};

Və helper funksiyası:

export function logToolInvocation(event: ToolInvocationLog) {
  console.log(JSON.stringify({ type: "tool_invocation", ...event }));
}

İndi bu tip kodla pasport arasında körpüyə çevrilir: Observability bölməsində bütün tool çağırışlarının ToolInvocationLog formatında loglandığını yazır və bu qeydləri toplayan dashboard‑a keçid verirsiniz.

Qısa mətn sxemi də əlavə etmək olar:

Hadisə logu → log anbarı → SLO dashboard‑ları → alertlər → insident/Runbook.

6. Economics & Product Metrics: pul və istifadəçi davranışı

Burada iqtisadiyyat haqqında əvvəlki (M19) blokda etdiklərinizi birləşdirirsiniz: cost metriklər, pricing və məhsul analitikası.

GiftGenius üçün pasportda aşağıdakıları möhkəmləndirmək lazımdır:

Açar ssenarinin unit‑iqtisadiyyatı (şərti, “bir tamamlanmış tapşırığın iqtisadiyyatı”).
Məsələn: “Orta cost_per_successful_task (uğurlu ödənişlə hədiyyə seçimi) = $0.13 (LLM + infra). Bir tapşırıq üzrə orta gəlir = $0.80 (partnyorlardan CPA).”

Əsas monetizasiya modeli.
Qısa: “Alış olmadan pulsuz baza seçimləri, monetizasiya — partnyor mağazalara keçid üçün CPA + genişləndirilmiş filtr və hədiyyə tarixçəsi ilə opsional premium abunə.”

Açar məhsul metrikləri.
Məsələn: activation‑rate = ən az bir workflow_completed olan istifadəçilərin payı; repeat‑rate = ay ərzində ən az bir dəfə qayıdan istifadəçilərin payı; workflow_completed → checkout_success konversiyası.

Eksperimentlər.
Aktiv A/B siyahısı: “Model A (bahalı) vs Model B (ucuz)”, “Uzun master vs sürətli inline”. Hər biri üçün experiment_id, variantlar, hədəf metriklər (konversiya, cost_per_task, quality‑score) saxlanılır.

Pasportun nəzəri qalmasın deyə bunu kodda da göstərmək olar, məsələn, analitik hadisələr üçün vahid helper vasitəsilə:

// lib/analytics.ts
export function trackEvent(
  name: string,
  payload: Record<string, unknown>,
) {
  console.log(JSON.stringify({
    type: "analytics",
    name,
    ts: new Date().toISOString(),
    ...payload,
  }));
}

Və workflow uğurla bitdikdə çağırış:

trackEvent("workflow_completed", {
  userId,
  requestId,
  experimentId: "model_ab_01",
  variant: "A",
  costUsd: 0.13,
  checkoutSuccess: true,
});

Pasportda hansı hadisələrin açar sayıldığını və hansı KPI‑ların onlara bağlandığını təsvir edirsiniz. Kod — həqiqətən ölçmə apardığınızın sübutudur, təkcə vəd deyil.

Amma metriklər və iqtisadiyyat yalnız App production‑da stabil işləyəndə məna kəsb edir. Buna görə növbəti bölmədə GiftGenius‑un əməliyyat tərəfini pasportda necə sabitləşdirməyi — insidentlər, on‑call və runbook‑ları — nəzərdən keçirəcəyik.

7. Ops & Incidents: production‑da App ilə necə yaşayacaqsınız

Bu bölmə — hər şey plan üzrə getməyəndə necə reaksiya verdiyiniz haqqındadır.

GiftGenius üçün pasportda ən azı iki tipik insidenti sadalamaq məntiqlidir:

Ödəniş problemləri.
Məsələn: checkout success‑rate SLO‑dan aşağı düşür, Stripe webhook‑larında kütləvi səhvlər. Pasportda qeyd edirsiniz ki, bunun üçün “Checkout Failures” runbook‑u var, burada simptomlar, harada baxmalı (səhv dashboard‑u, webhook endpoint logları), sürətli mitigation addımları (müvəqqəti tədbirlər: problemli feature‑flag‑ı söndürmək, trafikin bir hissəsini sandbox‑a keçirmək və ya müvəqqəti yalnız sertifikatlar təklif etmək) və follow‑up (post‑mortem, yeni alertlərin əlavə edilməsi) təsvir olunub.

MCP/LLM problemləri.
Məsələn: suggest_gifts üçün p95 latency 9 saniyəyə qədər artır və ya böyük faizli sorğular üçün “Error talking to app” xətası. Burada ayrıca runbook: OpenAI statusunun, tunel/Vercel‑in, MCP health‑check‑in yoxlanması, kataloqa çıxış olmadan cavab verməyə cəhd edən deqradasiya rejiminə keçid (modelin ümumi ideyaları əsasında, commerce olmadan).

Eyni bölmədə əməliyyat təqvimini də qısaca təsvir edirsiniz: SLO‑ları nə qədər tez‑tez yenidən nəzərdən keçirirsiniz, cost‑review nə vaxt olur, security logları necə yoxlanır və sirlər nə zaman rotasiya olunur.

Burada həmçinin kimin on‑call olduğu (bir nəfər də olsa) və alertlərin hansı Slack kanalına və ya hansı email‑ə gəldiyi qeyd oluna bilər.

8. Roadmap & Risks: irəliyə dürüst baxış

Final blok — gələcək haqqındadır. Roman yazmaq lazım deyil. App‑in inkişafı üzrə 3–5 real addım və bir neçə məlum məhdudiyyət kifayətdir.

GiftGenius üçün bu belə görünə bilər:

• keyfiyyəti konversiya ilə bağlamaq üçün LLM‑qiymətləndirmələrinin (LLM‑evals) işə salınması;
• daha bir lokallaşdırmanın əlavə edilməsi və alət təsvirlərinin lokallaşdırılmış variantlarının test edilməsi;
• trafikin bir hissəsində daha ucuz modellərlə eksperiment;
• Stripe nasazlıqlarına qarşı dayanıqlığın artırılması (webhook‑ları və gecikmiş təsdiqləri daha etibarlı emal etmək);
• Apps SDK və ya MCP‑nin yeni versiyasına miqrasiya üçün hazırlıq (alət kontraktlarının versiyalanması ilə).

Məhdudiyyətlər: API cap‑ləri, ChatGPT UI‑nın limitləri (məsələn, çıxışda kartların sayına məhdudiyyət), mövcud arxitekturanın zəif yerləri (tək regionlu DB, MCP üçün hot standby yoxdur və s.).

Eksperimentlər planı: pricing/UX/modellər üzrə hansı hipotezləri yoxlamağı planlaşdırırsınız və qərarları hansı metriklər əsasında qəbul edəcəksiniz.

9. Pasport harada yaşamalıdır və necə yenilənməlidir

Praktik olaraq ən rahat format — GiftGenius repozitorisinin kökündə və ya docs/ qovluğunda PASSPORT.md, həmçinin sizin sənədləşdirmə sisteminizdə (Confluence, Notion və s.) surət/keçid.

O, 10–15 dəqiqə ərzində oxuna biləcək qədər yüngül, eyni zamanda suallara cavab verəcək qədər sıx olmalıdır:

• “bu App ümumiyyətlə nədir, necə qurulub?”
• “X düşəndə nə baş verəcək?”
• “bir istifadəçi bizə nə qədər başa gəlir?”
• “hazırda ən çox hansı risklər bizi narahat edir?”

Pasportu aşağıdakılar dəyişəndə yeniləmək lazımdır:

• arxitektura sərhədləri (yeni servis, yeni ödəniş sistemi, başqa stack‑ə miqrasiya);
• açar SLO‑lar və ya təhlükəsizlik siyasəti (məsələn, başqa retention);
• monetizasiya modeli;
• əhəmiyyətli insidentlər və post‑mortem nəticələri.

Kiçik kod dəyişiklikləri pasportun dərhal redaktəsini tələb etmir, yoxsa o, daha bir köhnələn sənədə çevrilər.

Pasport — əslində, App‑iniz haqqında bildiklərinizin konsentratıdır. Növbəti məntiqli addım — onun əsasında məhsulu canlı insanlara danışmağı öyrənməkdir: texniklərə və biznesə.

10. Texniki‑məhsul demo: niyə iki “hekayə versiyası” lazımdır

GiftGenius‑u göstərərkən, demək olar ki, həmişə iki auditoriya növü qarşısında danışırsınız (bəzən onlar eyni otaqda qarışıq olur):

• texniki auditoriya (CTO, arxitektorlar, security, inkişaf lead‑ləri);
• məhsul/biznes auditoriyası (CEO, investorlar, product, marketinq).

Texniki insan üçün vacibdir ki:

• arxitektura anlaşılandır, qatlar ayrıdır, genişlənmə nöqtələri var;
• etibarlılıq və müşahidəolunarlıq düşünülüb: loglar, tracing, SLO, alertlər;
• dayanıqlılıq hekayəsi var: OpenAI, MCP, Stripe düşərsə nə olacaq;
• evolyusiyanı necə planlaşdırırsınız (SDK/MCP/modellərə miqrasiya).

Biznes üçünsə daha vacibdir:

• istifadəçinin ağrısı nədir (məsələn, “hədiyyə axtarışı 40 dəqiqə çəkir”);
• GiftGenius bu ağrını ChatGPT daxilində bir neçə dəqiqəyə necə həll edir;
• monetizasiya, unit‑iqtisadiyyat və böyümə metrikləriniz nələrdir;
• bu, müştəri cəlbetmə dəyərini azaldacaqmı, konversiyanı/gəliri artıracaqmı.

Odur ki, bunu eyni demo hekayəsinin iki “qatı” kimi düşünün: yetkin məhsul əlamətlərini hər ikisinə göstərirsiniz, amma vurğular fərqlidir.

11. GiftGenius üçün texniki demo ssenarisi (5–7 dəqiqə)

Tutaq ki, GiftGenius‑u texniki auditoriya qarşısında təqdim edirsiniz.

Əvvəlcə qısa kontekst.
Sözün əsl mənasında 30 saniyə: “GiftGenius — ACP checkout‑u olan hədiyyə seçimi üçün ChatGPT App‑dir. Biz ChatGPT daxilində yaşayırıq, Apps SDK, MCP və addımları planlaşdırmaq üçün agentdən istifadə edirik.”

Sonra arxitektura slaydı/pasportdan fraqment.
Mermaid‑də çəkdiyimizə bənzər diaqramı açır və ChatGPT‑nin məsuliyyət sərhədini (LLM hissə), sizin widgeti, MCP‑ni və Stripe ilə commerce qatını izah edirsiniz. Burada bütün tool‑ların MCP daxilində inkapsulyasiya olunduğunu, widgetin isə nazik UI qatı olduğunu göstərmək faydalıdır.

Loglarla canlı demo.
Daha sonra split‑screen açırsınız: solda — GiftGenius ilə ChatGPT, sağda — loglar və ya MCP Inspector. “gamer üçün 50$‑dək hədiyyə seç” kimi təbii bir sorğu edirsiniz. İcra zamanı göstərirsiniz:

• suggest_gifts tool çağırışını request_id ilə;
• tool_invocation strukturlu logunu, burada tokens, cost_estimate və duration_ms görünür;
• ACP sessiyasını açan və sifariş yaradan ikinci dərəcəli tool‑u.

Əla olardı ki, dərhal dashboard‑a da keçid göstərə biləsiniz: “budur son sutka üçün bu ssenarinin p95 latency‑si, budur checkout success‑rate.” Bu an texniki dinləyici başa düşür ki, bu, pet‑project deyil, müşahidəolunarlığı olan bir sistemdir.

Failure‑injection (opsional, amma çox təsirli).
Sistemə kifayət qədər güvənirsinizsə (və ya ssenarini əvvəlcədən hazırlamısınızsa), məsələn, kataloqa (DB‑yə) çıxışı müvəqqəti söndürüb sorğunu təkrarlaya bilərsiniz. Göstərirsiniz ki:

• MCP xətanı düzgün loglayır və alert işə düşür;
• agent deqradasiya rejiminə keçir və istifadəçiyə kataloqun əlçatan olmadığını səmimi şəkildə bildirir, amma ümumi ideyalar verə bilir;
• bu rejimdə checkout əlçatan deyil.

Sonda — qısa olaraq ekspluatasiya və evolyusiya.
Pasportdan SLO, insidentlər və roadmap slaydını göstərirsiniz: hədəf göstəriciləriniz nələrdir, onları necə monitor edirsiniz, hansı insidentlər artıq runbook‑larla işlənib, v2‑də nə olacaq (miqyaslama, yeni modellər, yeni bazarlar).

Auditoriyaya əsas siqnal: sizdə təkcə gözəl UI deyil, production‑da yaşamağa hazır düşünülmüş platforma var.

12. Məhsul demo ssenarisi (biznes rakursu)

Eyni GiftGenius, ancaq onu məhsul kimi danışırsınız.

İstifadəçi hekayəsi ilə başlayın.
Məsələn: “Bizdə Katya var, axşama qədər həmkarına hədiyyə seçməlidir. Adətən buna mağaza saytlarında 30–40 dəqiqə sərf edir.”

ChatGPT ilə GiftGenius‑u göstərin.
Katya marketpleysdə filtrlərə klikləmək əvəzinə canlı cümlə yazır: “həmkar üçün stolüstü oyunları sevən, büdcə 50$‑dək hədiyyə seç”. ChatGPT izah edir ki, GiftGenius‑dan istifadə edə bilər və widgetı açır. GiftGenius bir‑iki detalı dəqiqləşdirir və variantlar siyahısını göstərir.

Nəticə və dəyərə keçin.
Hədiyyə kartlarını, saxlama və ya dərhal alışa keçid imkanını, ACP/Stripe vasitəsilə checkout‑u göstərirsiniz. Demək vacibdir: “bütün bunlar 3–5 dəqiqə çəkir və istifadəçinin onsuz da vaxt keçirdiyi məkanda — ChatGPT‑də baş verir.”

Daha sonra 1–2 dəqiqə monetizasiya və metriklər haqqında.
CPA və ya mağazalardan komissiya ilə qazandığınızı, bəlkə də tez‑tez istifadə edənlər üçün premium rejim təklif etdiyinizi izah edirsiniz. Pasportdakı rəqəmlərə istinad edirsiniz: bir uğurlu ssenarinin nə qədərə başa gəldiyi, alışa konversiya və hansı marja ehtiyatının qoyulduğu.

Sonra — bir az böyümə barədə.
İstifadəçiləri necə gətirməyi planlaşdırırsınız: ChatGPT‑də Store‑listing, kontent, partnyor inteqrasiyaları. Amma hər şeyi məhsul metriklərinə bağlayırsınız: “listing dəyişikliyi yeni app_opened sayına və activation‑rate‑ə necə təsir edir; məqalə və videolar retention‑a və bir neçə workflow_completed olan istifadəçilərin payına necə təsir edir.”

Risklər və planla yekunlaşdırın.
Mövcud məhdudiyyətlər barədə səmimi danışın (məsələn, OpenAI/Stripe limitlərindən asılılıq, hazırda zəif lokal dəstək) və roadmap göstərin: pipeline‑da hansı eksperimentlər və təkmilləşdirmələr var.

Hər şeyi səliqə ilə etsəniz, biznes auditoriyası “daha bir AI widget” deyil, iqtisadiyyatı və böyümə planı olan anlaşılan məhsul görəcək.

13. Praktika: GiftGenius ətrafında pasportunuzu və demonuzu yığırıq

Bu mühazirənin praktikası kimi, elə öz GiftGenius repozitorinizdə PASSPORT.md faylını yaradıb ən az beş blok üzrə doldura bilərsiniz: arxitektura, təhlükəsizlik, observability/SLO, iqtisadiyyat və məhsul metrikləri, insidentlər/operasiyalar. Yeni runbook yazan kimi və ya SLO dəyişən kimi pasporta qayıdıb bu dəyişikliyi əks etdirin.

Paralel olaraq 5–7 dəqiqəlik demo üçün konspekt yazmaq məntiqlidir: ilk 2–3 dəqiqə — istifadəçi ssenarisi və dəyər, növbəti 2–3 — arxitektura və ekspluatasiya (SLO, cost, insidentlər). Belə konspekt həm biznesin, həm də texnikanın dili ilə danışmaq bacarığını məşq etdirir — nə quru koda, nə də boş marketinqə yuvarlanmadan.

Bu artefaktlar “sadəcə checkbox üçün kağız” deyil, final kapston‑demoya əsasdır. Məhz bu pasport və ssenari ilə sonra App‑inizi şərti CTO/CEO qarşısında müdafiə edəcəksiniz.

14. Pasport və demo hazırlanarkən tipik səhvlər

Səhv №1: pasportu marketinq bukletinə çevirmək.
Bəzən pasport landing‑ə bənzəyir: “innovativ AI” barədə çox ümumi söz, arxitektura, SLO, cost və insidentlər haqqında az konkretlik. Belə sənəd heç kimə kömək etmir: texniki adam içəridə necə yaşadığını anlamır, biznes isə riskləri idarə etdiyinizi görmür. Pasportda faktlar, sxemlər, metriklər və keçidlər olmalıdır.

Səhv №2: yalnız kodu təsvir etmək, məlumat axınlarını və məsuliyyətləri yox.
Tərtibatçılarda populyar meyl — bütün servisləri, kitabxanaları və framework‑ləri sadalamaq, “istifadəçi → ChatGPT → widget → MCP → agentlər → ACP/DB” kimi yüksək səviyyəli sxemi unutmaq. Nəticədə yeni adam kimin nəyə cavabdeh olduğunu və sərhədlərin haradan keçdiyini anlamır. Arxitektura bölməsində data flow və qatlar daha vacibdir, bütün npm paket adları yox.

Səhv №3: pasportu observability və cost alətləndirilməsi ilə əlaqələndirməmək.
Bəzən pasportda qürurla “bizdə SLO var” yazılır, amma onların necə ölçüldüyü, logların harada olduğu və JSON hadisələrində konkret hansı sahələrin yazıldığı görünmür. Və ya “LLM‑cost nəzarət altındadır” yazılıb, amma heç bir cost_per_task metriyi yoxdur. Real loglar, metriklər və dashboard‑larla əlaqə nə qədər azdırsa, SLO və cost‑un Google Docs‑da, yoxsa monitorinq sistemində “yaşaması” bir o qədər şübhəlidir.

Səhv №4: yalnız gözəl UI haqqında demo, arxitektura və dayanıqlılıq olmadan.
Şouya çevrilmək asandır: “baxın, nə gözəl hədiyyə kartları var”. Texniki auditoriya isə həmin an düşünür: “Stripe düşsə nə olacaq?”, “tool çağırışlarını necə loglayırsınız?”, “bunu miqyaslandırmaq olarmı?”. Demo azı bir‑iki hekayə ilə loglar, SLO və insidentlərə toxunmasa, texniklərdə bu, oyuncaq, yoxsa məhsuldur sualı yaranır.

Səhv №5: yalnız texniklər üçün demo, istifadəçi hekayəsi və iqtisadiyyat olmadan.
Əks meyl: 10 dəqiqə p95 latency, MCP handshake və alətlərin JSON Schema‑sını müzakirə edirik, amma bir dəfə də demirik ki, istifadəçinin hansı ağrısını həll edirik, kim ödəyir və bir ssenari nə qədərə başa gəlir. Biznes və product üçün bu, “bərk mühəndislik işi, amma biznes case yoxdur” kimi görünür. Həmişə azı iki şlyapanı yadda saxlayın: mühəndis və product meneceri.

Səhv №6: pasport və demo bir‑birindən ayrı yaşamaq.
Bəzən pasportda bir şey, demoda başqa şey: sənəddə bir SLO vəd olunur, dashboard‑larda başqası; pasportda üç insident və runbook, canlı təqdimatda isə ilk nasazlıqda hamı çaşır. Pasportdan demo üçün ssenari kimi istifadə etməyə çalışın: eyni SLO‑lara, eyni dashboard‑lara, eyni runbook‑lara istinad edin. O zaman dinləyicidə təsadüfi artefaktlar yox, bütöv sistem hissi yaranacaq.

Səhv №7: pasporta “bir dəfəlik kurs işi” kimi yanaşmaq.
Ən böyük tələ — modulu təhvil vermək üçün PASSPORT.md yazmaq və onu unutmaqdır. Real həyatda məhz belə sənədlər komandanı başlarda saxlanılan biliklərin zooparkına çevirir. Pasporta kodun canlı hissəsi kimi yanaşmağa çalışın: ciddi arxitektur, əməliyyat və ya biznes qərarlarında o da dəyişsin. Bir neçə aya özünüz özünüzə təşəkkür edəcəksiniz.