Software Engineer Encyclopedia
0%
Domain 14 · SaaS & Product Engineering · Topic 14.2

هندسة المنتج من المتطلب إلى القياس

Product Engineering

تحويل احتياج المستخدم إلى متطلبات وقواعد أعمال وواجهات وتجارب ومقاييس قابلة للقياس.

  • Professional Engineering
  • ~14 min read
  • 15 sections
  • 12 code examples
  • 1 diagrams
  • 7 questions
  • Priority L2 · Important
  • Requirements · UX · APIs · Analytics · Experiments

بعد الدرس ده هتقدر

  • تنفّذ feature flags بـ deterministic bucketing وrollout تدريجي.
  • تقرأ نتيجة A/B test بهامش خطأ وتتجنب الـ peeking.

المتطلبات قبل ما تبدأ

Security + Architecture + System Design.

مستوى التعمق المطلوب

PRACTICALتحوّل متطلب أعمال لـ user story وacceptance criteria وAPI contract وأحداث ومقياس نجاح واضح.

01

Product Engineering Is More Than Implementing Tickets

Solve a user problem, not just a technical task
Deep dive

Product Engineering يربط user problem و business outcome بالحل التقني. قبل كتابة الكود، افهم من المستخدم؟ ما المهمة التي يحاول إنجازها؟ ما الألم الحالي؟ ما البديل؟ وما الدليل أن المشكلة تستحق الاستثمار؟ Feature مكتملة تقنيًا قد تفشل إذا لم تُستخدم أو لم تحسن outcome.

افصل output عن outcome: output هو “أطلقنا dashboard”، outcome هو “قل وقت إتمام المهمة 30%”. اكتب hypothesis قابلة للاختبار، وحدد target segment والقياس baseline والنتيجة المتوقعة والـ guardrails.

مثال: نفس الـ ticket، مهندسين مختلفين

الـ ticket: «ضيف زر تصدير CSV للفواتير». مهندس tickets بيعمل endpoint بيرجّع كل الفواتير كـ CSV ويقفل. Product engineer بيسأل قبل ما يكتب سطر: مين بيطلب ده وليه؟ (المحاسب بيعمل reconciliation شهري في Excel) ← يبقى المطلوب فلتر بالشهر، أعمدة بأسماء يفهمها المحاسب، أرقام بصيغة Excel صح (العربي + الفواصل!)، وتصدير غير متزامن لو الفواتير 200 ألف. وبيسأل: إزاي هنعرف إن ده نجح؟ (عدد التصديرات الشهرية، وقلة تذاكر «الأرقام مش مظبوطة في Excel»).

Failure case

CSV اتعمل UTF-8 من غير BOM؛ Excel على Windows فتحه بـ encoding غلط والأسماء العربي ظهرت رموز. 40 تذكرة دعم في أسبوع. Product thinking = تجرّب على أداة المستخدم الفعلية مش على VS Code.

02

Product engineering loop

From problem to measured outcome
Basics
Problemuser + evidenceHypothesismetric + targetSmallest slicebehind a flagMeasureA/B, funnelsDecidescale · iterate · killlearnings feed the next problem
Ship small, measure the outcome, decide; features are hypotheses until the metric moves
03

Requirements Discovery and Business Rules

Turn ambiguity into explicit decisions
Deep dive

اجمع requirements من interviews و support tickets و analytics و workflow observation و regulatory constraints. ميّز functional requirements عن non-functional: correctness، latency، availability، security، accessibility، auditability، و cost. اسأل عن edge cases: duplicate request، partial failure، permission denied، cancellation، stale data، و concurrent updates.

Business rule يجب أن تكون testable: “لا يمكن اعتماد refund أكبر من refundable balance” أو “المستخدم لا يرى invoice إلا إذا كان عضوًا في tenant”. تجنب متطلبات مثل “النظام سريع”؛ حولها إلى SLO و workload محدد. سجل assumptions المفتوحة بدل دفنها داخل implementation.

PythonTurn ambiguity into explicit decisions
requirement = {
  'actor': 'tenant_admin',
  'goal': 'invite a member',
  'business_rule': 'invite only to the current tenant',
  'failure_states': ['already_member', 'invalid_email', 'quota_exceeded'],
  'non_functional': {'p95_ms': 500, 'audit_required': True},
}
print(requirement['failure_states'])

Discovery عملي: من «عايزين خصومات» لقواعد قابلة للتنفيذ

الطلب: «العملاء القدام ياخدوا خصم». أسئلة الـ discovery اللي بتطلع القواعد المخفية:

  • «قديم» = من تاريخ أول اشتراك ولا من آخر تجديد؟ اللي ألغى ورجع؟
  • الخصم على كل الفاتورة ولا على الـ seats بس؟ بيتجمع مع كوبونات؟ (التجميع = أشهر bug مالي)
  • مين يقدر يلغيه؟ بيتسجل فين؟ بيأثر على الضريبة إزاي؟
C#LoyaltyDiscountPolicy.cs (rules made explicit and testable)
public sealed record DiscountDecision(decimal Percent, string Reason);

public static class LoyaltyDiscountPolicy
{
    // Business rules agreed in discovery (2026-10-12, finance + product):
    // R1 tenure counts from first PAID invoice; gaps > 60 days reset it.
    // R2 >= 24 months -> 10%, >= 12 months -> 5%.
    // R3 does NOT stack with coupons: the larger one wins.
    public static DiscountDecision Decide(int tenureMonths, decimal couponPercent)
    {
        var loyalty = tenureMonths switch { >= 24 => 10m, >= 12 => 5m, _ => 0m };   // R2
        if (couponPercent > loyalty) return new(couponPercent, "coupon (no stacking, R3)");
        return new(loyalty, loyalty > 0 ? "loyalty (R2)" : "none");
    }
}

القواعد مكتوبة في الكود بأرقام (R1..R3) ومربوطة بقرار موثّق، والـ tests بتغطي الحدود (11/12/24 شهر، كوبون أكبر/أصغر). لما المالية تسأل «ليه العميل ده خد 10%؟» الإجابة في سطر.

04

User Stories and Acceptance Criteria

Describe observable behavior
Practical

User story صياغة مختصرة للهدف: As a [actor], I want [capability], so that [outcome]. لكنها ليست specification كاملة؛ أضف acceptance criteria بصيغة Given/When/Then أو قائمة شروط واضحة. اكتب examples للنجاح والفشل والحدود، وحدد permissions والـ data scope.

Acceptance criteria يجب أن تكون قابلة للاختبار من QA/developer/product owner دون تخمين. فرّق بين acceptance criteria و implementation tasks. لا تكتب الحل التقني داخل story إلا إذا كان constraint ضروريًا؛ اترك مساحة للفريق لاختيار التصميم.

TextDescribe observable behavior
Feature: Invite a tenant member

Scenario: Admin invites a new member
  Given the user is an admin of Tenant A
  When they invite a new email address to Tenant A
  Then an invitation is created for Tenant A
  And the action is written to the audit log

Scenario: User cannot invite into another tenant
  Given the user is not a member of Tenant B
  When they submit an invitation for Tenant B
  Then the request is rejected without creating an invitation

Acceptance criteria بصيغة قابلة للاختبار (ومع AI)

Markdownstory-ASSIST-142.md
**Story:** As a support agent, I want a suggested reply for a ticket so that I answer faster.

**Acceptance criteria**
1. Given a ticket in Arabic or English, when I open it, a suggestion appears within 3 s (p95) or a "not available" state — never a spinner forever.
2. The suggestion cites the help-center articles it used; citations open the article.
3. If no relevant article is found, the suggestion says so and does not invent policy (refusal correctness >= 90% on eval set `support-golden@v3`).
4. The suggestion is never sent automatically; the agent edits/sends.
5. Edits are captured (diff) for quality measurement; no customer PII leaves our region.
6. Feature flag `assist.suggest-reply` per tenant; default off.

**Out of scope:** auto-send, voice tickets.

لاحظ البنود 1 و3: الـ AI feature محتاجة criteria إحصائية ومرتبطة بـ eval set (تفاصيل في AI Product Engineering). وبند 4 قرار منتج وأمان في نفس الوقت.

05

Domain Modeling and State Transitions

Model lifecycle, invariants and ownership
Deep dive

ارسم entity lifecycle بدل تخزين status string يتغير بلا قواعد. مثال Invitation: Pending → Accepted أو Expired أو Revoked. حدد allowed transitions ومن يملكها والـ preconditions. لا تسمح بـ Accepted → Pending دون use case واضح. State transition service/domain method أفضل من تعديل status مباشرة في أي endpoint.

عرّف invariants مثل unique active invitation per tenant/email، expiry must be future، و accepted user must be linked to tenant. استخدم DB constraints للحقائق التي يجب أن تصمد أمام concurrency، وليس validation في application فقط. Optimistic concurrency يحمي من lost updates.

C#Model lifecycle, invariants and ownership
public enum InvitationStatus { Pending, Accepted, Expired, Revoked }

public sealed class Invitation
{
    public InvitationStatus Status { get; private set; } = InvitationStatus.Pending;
    public DateTimeOffset ExpiresAt { get; init; }

    public void Accept(DateTimeOffset now)
    {
        if (Status != InvitationStatus.Pending || now >= ExpiresAt)
            throw new InvalidOperationException("Invitation cannot be accepted");
        Status = InvitationStatus.Accepted;
    }
}

State machine صريحة للطلب

C#Order.cs
public enum OrderState { Draft, Submitted, Paid, Fulfilled, Cancelled, Refunded }

public sealed class Order
{
    private static readonly Dictionary<OrderState, OrderState[]> Allowed = new()
    {
        [OrderState.Draft]     = [OrderState.Submitted, OrderState.Cancelled],
        [OrderState.Submitted] = [OrderState.Paid, OrderState.Cancelled],
        [OrderState.Paid]      = [OrderState.Fulfilled, OrderState.Refunded],
        [OrderState.Fulfilled] = [OrderState.Refunded],
    };
    public OrderState State { get; private set; } = OrderState.Draft;

    public void TransitionTo(OrderState next, string actor)
    {
        if (!Allowed.TryGetValue(State, out var ok) || !ok.Contains(next))
            throw new DomainException($"Cannot go from {State} to {next}");
        DomainEvents.Raise(new OrderStateChanged(Id, State, next, actor));   // audit + outbox
        State = next;
    }
    public Guid Id { get; } = Guid.NewGuid();
}

ليه؟ من غيرها، الـ Status string بيتعدّل من 6 أماكن، ويظهر طلب «Refunded» من غير ما يكون «Paid». الـ state machine بتخلي الحالات المستحيلة مستحيلة في الكود، والـ UI بيعرض الأزرار من Allowed نفسها.

06

API Contracts, Errors and Backward Compatibility

Design for clients you do not control
Deep dive

API contract يحدد resources، methods، request/response schemas، validation، auth scopes، pagination، sorting، idempotency، error model، و versioning policy. استخدم stable machine-readable error codes مع human-readable message؛ لا تجعل client يعتمد على نص exception. HTTP status يجب أن يعكس semantics: 400 malformed/invalid، 401 unauthenticated، 403 forbidden، 404 not found/hidden by policy، 409 conflict، 429 rate limited.

Backward compatibility تعني عدم كسر clients القديمة عند إضافة feature. أضف optional fields بحذر، لا تغير معنى field موجود، ولا تحذف enum value دون migration plan. Contract tests بين API وال clients تقلل integration surprises. وثّق deprecation timeline.

C#Design for clients you do not control
public sealed record ApiError(string Code, string Message, string? TraceId);

// Example stable codes: quota_exceeded, invitation_already_used,
// tenant_membership_required, concurrency_conflict.
// Never expose stack traces, SQL text, secrets or internal provider errors.

Backward compatibility: قواعد بتمنع كسر العملاء

تغييرآمن؟ليه
إضافة field اختياري في الـ response✓ غالبًاالعملاء الكويسين بيتجاهلوا المجهول (لو مش strict deserializers!)
إضافة قيمة enum جديدة⚠عميل عامل switch من غير default هيقع
تغيير نوع/اسم field، حذفه✗breaking — version جديد أو فترة deprecation
field إجباري جديد في الـ request✗كل العملاء القدام هياخدوا 400
C#Deprecation.cs
app.MapGet("/api/v1/invoices", GetInvoicesV1)
   .WithMetadata(new DeprecatedAttribute())
   .AddEndpointFilter(async (ctx, next) =>
   {
       ctx.HttpContext.Response.Headers["Deprecation"] = "true";
       ctx.HttpContext.Response.Headers["Sunset"] = "Wed, 30 Jun 2027 00:00:00 GMT";
       ctx.HttpContext.Response.Headers["Link"] = "</api/v2/invoices>; rel=\"successor-version\"";
       return await next(ctx);
   });
// And measure who still calls v1 (per API key / tenant) before the sunset date.
07

UX Fundamentals and Error-State Design

The failure path is part of the product
Deep dive

UX لا تعني الألوان فقط؛ هي وضوح الخطوات وال feedback و discoverability وال accessibility والثقة. صمم loading/empty/error/success/permission-denied/offline states. Empty state يجب أن يوضح ماذا يفعل المستخدم بعد ذلك، و error state يشرح هل يمكن retry وهل تم حفظ العملية أم لا.

في AI features، وضّح أن الإجابة مولدة، اعرض citations ومتى لا يوجد دليل، واسمح للمستخدم بالإبلاغ عن الخطأ. لا تعرض spinner بلا نهاية؛ اعرض progress للـ long-running jobs و cancel/retry حيث مناسب. لا توحي بنجاح عملية مالية إذا كانت pending approval.

الحالات الخمسة لكل شاشة

كل شاشة بتعرض بيانات ليها على الأقل: loading، empty (مفيش بيانات لسه — اشرح وادي خطوة أولى)، error (إيه اللي حصل وإيه اللي يتعمل، من غير stack trace)، partial (جزء اتحمل)، permission denied. ومع AI: degraded (الـ AI مش متاح، الباقي شغال).

TypeScriptinvoices.component.ts (Angular signals)
type ViewState<T> =
  | { kind: 'loading' }
  | { kind: 'empty' }
  | { kind: 'error'; message: string; retry: () => void }
  | { kind: 'forbidden' }
  | { kind: 'ready'; data: T };

@Component({ selector: 'app-invoices', standalone: true, templateUrl: './invoices.component.html' })
export class InvoicesComponent {
  private readonly api = inject(InvoicesApi);
  readonly state = signal<ViewState<Invoice[]>>({ kind: 'loading' });

  constructor() { this.load(); }

  load() {
    this.state.set({ kind: 'loading' });
    this.api.list().subscribe({
      next: (rows) => this.state.set(rows.length ? { kind: 'ready', data: rows } : { kind: 'empty' }),
      error: (e: HttpErrorResponse) => this.state.set(
        e.status === 403 ? { kind: 'forbidden' }
                         : { kind: 'error', message: e.error?.title ?? 'تعذر تحميل الفواتير', retry: () => this.load() }),
    });
  }
}

الـ discriminated union بيخلي الـ template (@switch (state().kind)) ما يقدرش ينسى حالة، وده أرخص تحسين UX ممكن.

08

Feature Flags, Analytics Events and Product Metrics

Instrument behavior with a clear event taxonomy
Deep dive

Feature flag يفصل deployment عن release ويسمح gradual rollout و kill switch و experiments. Flag يحتاج owner و purpose و expiry/cleanup date؛ تراكم flags يخلق configuration complexity. لا تستخدم flag كبديل authorization؛ user لا يملك feature permission لمجرد أن UI أخفاها.

Analytics event يجب أن يكون له stable name و schema و timestamp و actor/tenant scope و source، مع data minimization. لا تسجل PII في event properties دون ضرورة وموافقة. صمم funnel/cohort/retention metrics من user journey، وتأكد من deduplication و event delivery semantics.

PythonInstrument behavior with a clear event taxonomy
event = {
  'name': 'document_answer_feedback_submitted',
  'schema_version': 2,
  'properties': {'rating': 'negative', 'answer_type': 'retrieval_augmented'},
  'tenant_scope': 'tenant_id_from_server_context',
  'contains_raw_prompt': False,
}
print(event['name'])

Analytics events بـ schema، مش strings عشوائية

TypeScriptanalytics.ts
// One typed catalogue: a typo becomes a compile error, and the data team gets a contract.
type AnalyticsEvent =
  | { name: 'invoice_export_started'; props: { format: 'csv' | 'xlsx'; rows: number } }
  | { name: 'assist_suggestion_shown'; props: { ticketId: string; latencyMs: number; release: string } }
  | { name: 'assist_suggestion_used'; props: { ticketId: string; editDistance: number } };

export function track<E extends AnalyticsEvent>(e: E): void {
  // no PII in props; tenant/user ids are attached server-side from the session
  navigator.sendBeacon('/api/analytics', JSON.stringify({ ...e, ts: Date.now() }));
}
Failure case

Dashboard الـ adoption أظهر انهيار 60% بعد release. السبب مش المستخدمين: event اتغير اسمه من exportStarted لـ export_started في refactor. الحل: event catalogue typed + tests + تنبيه لو event شائع اختفى فجأة.

09

Product Metrics and A/B Experimentation

Measure causal impact, not vanity numbers
Deep dive

اختَر North Star metric تعكس value المقدمة، ثم input/guardrail metrics. مثال knowledge assistant: successful self-service resolution، time-to-resolution، citation click-through، escalation rate، و harmful answer rate. DAU وحده قد يزيد دون تحسن القيمة. عرّف numerator/denominator و cohort window بدقة.

A/B test يحتاج randomization unit مناسبًا (user أو tenant لتجنب contamination)، primary metric محددة مسبقًا، sample size/power، مدة تشمل seasonality، guardrails، و analysis plan. لا توقف التجربة عند أول نتيجة إيجابية دون sequential testing plan. في B2B tenants قد يكون عدد العملاء قليلًا؛ qualitative evidence أو staged rollout قد يكون أنسب.

PythonMeasure causal impact, not vanity numbers
experiment = {
  'hypothesis': 'Citations increase successful self-service resolution',
  'randomization_unit': 'tenant',
  'primary_metric': 'resolved_without_escalation_rate',
  'guardrails': ['harmful_answer_rate', 'p95_latency', 'cost_per_resolution'],
  'minimum_runtime_days': 14,
}
print(experiment['randomization_unit'])

A/B test بشكل صحيح: الحسبة قبل الإطلاق

  • Metric واحد أساسي محدد قبل البداية (مثلًا نسبة التذاكر اللي اتحلت في أول رد) + guardrail metrics (وقت الحل، CSAT، تكلفة الـ AI).
  • حجم العينة من الـ baseline وأقل فرق يستاهل (MDE). من غير الحسبة دي، هتوقف التجربة بدري على «نتيجة» هي noise (peeking) — اتشرح بالأرقام في درس Math for ML.
  • وحدة التوزيع: في B2B غالبًا الـ tenant مش الـ user (الموظفين في نفس الشركة بيكلموا بعض، والإعدادات per tenant) ← عينات أقل ← تجارب أطول.
10

Feedback Loops and Prioritization

Turn signals into a product learning system
Deep dive

Feedback يأتي من explicit ratings، support tickets، user interviews، behavioral analytics، sales/customer success، و operational incidents. لا تساوِ thumbs-down بسبب latency مع thumbs-down بسبب factual error؛ صنّف السبب. اجمع feedback مع trace/evidence/model version بطريقة تحمي privacy، واسمح للمستخدم بتصحيح معلومة.

Prioritization يمكن أن يستخدم impact × confidence ÷ effort، لكن الأرقام تقريبية وليست حقيقة. أضف risk reduction و strategic fit و dependency cost. حافظ على discovery backlog منفصلًا عن delivery commitments، وراجع outcomes بعد الإطلاق بدل اعتبار ticket closure نهاية العمل.

Prioritization بالأرقام: RICE مثال

FeatureReach (tenants/ربع)Impact (0.25–3)ConfidenceEffort (أسابيع)RICE
Suggested replies (AI)120250%620
SSO (SAML)15390%410.1
CSV export fix3000.5100%1150

الرقم مش قرار؛ هو أداة نقاش. الـ SSO ليه RICE أقل لكنه شرط لصفقات enterprise بقيمة كبيرة — الـ impact لازم يعكس الإيراد مش عدد المستخدمين بس. والـ confidence 50% للـ AI = اعمل prototype + eval أسبوع قبل ما تلتزم بـ 6 أسابيع.

11

Feature Flags و A/B Tests: الـ Rollout كهندسة مش كمفتاح

Deterministic bucketing, gradual rollout, and reading an experiment without fooling yourself — executed
Practical

الـ feature flag بيفصل الـ deploy (الكود نزل) عن الـ release (المستخدم شافه). ده بيخليك تنزّل كود كل يوم وتفتح الميزة لـ 1% ثم 10% ثم الكل، وتقفلها في ثانية من غير rollback. بس التنفيذ له شروط: نفس المستخدم لازم يشوف نفس النسخة كل مرة، وزيادة النسبة ما تبدّلش اللي دخلوا قبل كده، والتجارب المختلفة ما تتأثرش ببعض.

Pythonrollout.py — stable hashing for flags, monotonic rollout, experiment independence, and an A/B readoutExecuted ✓
import hashlib, math, random

def bucket(flag, user_id, buckets=10_000):
    """Same (flag, user) -> same bucket, on every server, forever. No storage needed."""
    digest = hashlib.sha256(f"{flag}:{user_id}".encode()).digest()
    return int.from_bytes(digest[:8], "big") % buckets

def is_enabled(flag, user_id, percent, allow=(), deny=()):
    if user_id in deny:  return False                    # kill switch for specific users/tenants
    if user_id in allow: return True                     # internal users, beta customers
    return bucket(flag, user_id) < percent * 100         # percent has 2 decimal places of resolution

users = [f"user-{i}" for i in range(50_000)]

# 1) the share of users is what you asked for
for pct in (1, 10, 50):
    on = sum(is_enabled("new-checkout", u, pct) for u in users)
    print(f"1) rollout {pct:>2}% -> {on / len(users):.2%} of users enabled")

# 2) monotonic: raising the percentage never switches anyone OFF
at10 = {u for u in users if is_enabled("new-checkout", u, 10)}
at50 = {u for u in users if is_enabled("new-checkout", u, 50)}
print(f"2) users enabled at 10% who are still enabled at 50%: {len(at10 & at50) / len(at10):.0%}")

# 3) salting by flag name keeps experiments independent
other = {u for u in users if is_enabled("new-pricing-page", u, 10)}
print(f"3) overlap between two unrelated 10% flags: {len(at10 & other) / len(at10):.1%} (expected ~10% if independent)")
naive10 = {u for u in users if int(u.split('-')[1]) % 100 < 10}      # a common mistake: user_id % 100
naive_other = {u for u in users if int(u.split('-')[1]) % 100 < 10}
print(f"   with 'user_id % 100' for both flags the overlap is {len(naive10 & naive_other) / len(naive10):.0%}: the same users get every experiment")

# 4) an A/B test readout: conversion in control vs treatment
random.seed(1)
def experiment(n_per_arm, p_control, p_treatment):
    c = sum(random.random() < p_control for _ in range(n_per_arm))
    t = sum(random.random() < p_treatment for _ in range(n_per_arm))
    pc, pt = c / n_per_arm, t / n_per_arm
    se = math.sqrt(pc * (1 - pc) / n_per_arm + pt * (1 - pt) / n_per_arm)
    diff = pt - pc
    return pc, pt, diff, diff - 1.96 * se, diff + 1.96 * se

print("\n4) true conversion: control 4.0%, treatment 4.4% (a real +10% relative lift)")
for n in (1_000, 10_000, 100_000):
    pc, pt, diff, lo, hi = experiment(n, 0.040, 0.044)
    verdict = "significant" if lo > 0 or hi < 0 else "inconclusive"
    print(f"   n/arm={n:>7,}  control={pc:.2%} treatment={pt:.2%}  diff={diff:+.2%}  95% CI=[{lo:+.2%}, {hi:+.2%}]  {verdict}")

# 5) peeking: checking every day and stopping at the first 'significant' result
def peeking_false_positive_rate(days=20, per_day=500, runs=1000):
    false_alarms = 0
    for _ in range(runs):
        c = t = n = 0
        for _ in range(days):
            c += sum(random.random() < 0.04 for _ in range(per_day)); t += sum(random.random() < 0.04 for _ in range(per_day)); n += per_day
            pc, pt = c / n, t / n
            se = math.sqrt(pc * (1 - pc) / n + pt * (1 - pt) / n)
            if se and abs(pt - pc) / se > 1.96:
                false_alarms += 1; break               # "we have a winner!" — but there is NO real difference
    return false_alarms / runs
print(f"\n5) A/A test (no real difference), peeking daily for 20 days: declared a 'winner' in {peeking_false_positive_rate():.0%} of runs (nominal error rate is 5%)")
ConsoleOutput — captured from a real run
1) rollout  1% -> 1.01% of users enabled
1) rollout 10% -> 9.87% of users enabled
1) rollout 50% -> 50.13% of users enabled
2) users enabled at 10% who are still enabled at 50%: 100%
3) overlap between two unrelated 10% flags: 10.6% (expected ~10% if independent)
   with 'user_id % 100' for both flags the overlap is 100%: the same users get every experiment

4) true conversion: control 4.0%, treatment 4.4% (a real +10% relative lift)
   n/arm=  1,000  control=4.40% treatment=5.20%  diff=+0.80%  95% CI=[-1.07%, +2.67%]  inconclusive
   n/arm= 10,000  control=4.10% treatment=4.34%  diff=+0.24%  95% CI=[-0.32%, +0.80%]  inconclusive
   n/arm=100,000  control=3.97% treatment=4.40%  diff=+0.42%  95% CI=[+0.25%, +0.60%]  significant

5) A/A test (no real difference), peeking daily for 20 days: declared a 'winner' in 26% of runs (nominal error rate is 5%)

1–2) الـ hashing: مفيش جدول «مين مفعّل له إيه» — القرار بيتحسب من الـ id. نفس المستخدم بياخد نفس النتيجة على أي server. ولما النسبة تطلع من 10% لـ 50%، كل اللي كانوا جوه فضلوا جوه (100%): محدش الميزة ظهرتله واختفت.

3) الـ salt باسم الـ flag: من غيره (أو بـ user_id % 100) نفس المجموعة من المستخدمين بتدخل كل التجارب. يعني أي نتيجة ممكن تكون سببها تجربة تانية، ونفس الناس بيتحملوا كل المخاطر.

4) الحجم: التحسين حقيقي (+10% نسبي) ومع ذلك على عيّنات صغيرة النتيجة غير حاسمة، وممكن حتى تطلع في الاتجاه الغلط. تحسينات صغيرة على معدلات تحويل منخفضة محتاجة عشرات الآلاف لكل ذراع. احسب حجم العيّنة قبل ما تبدأ.

5) الـ peeking: مفيش أي فرق بين الذراعين، ومع ذلك «أعلنّا فايز» في نسبة أعلى بكتير من الـ 5% الاسمية — لأننا بصّينا 20 مرة ووقفنا عند أول مرة الرقم عدّى. القاعدة: حدد مدة أو حجم التجربة مسبقًا واقرأ النتيجة مرة واحدة، أو استخدم طريقة sequential مصممة للمراجعة المتكررة.

نوع الـ flagعمرهمثالالخطر لو اتنسى
Releaseأيام–أسابيعcheckout جديد بيتفتح تدريجيًاكود ميت ومسارين لازم يتختبروا للأبد
Experimentمدة التجربةA/B على صفحة التسعيرمستخدمين عالقين في نسخة «خسرانة»
Ops / kill switchدائمإيقاف الـ recommendations لما الـ LLM يقعلازم يتجرّب دوريًا وإلا مش هيشتغل وقت الحاجة
Permission / planدائمميزة للخطة Pro بسده entitlement مش flag — مكانه نظام الاشتراكات

بدأت A/B test، وبعد 3 أيام الـ dashboard بيقول «treatment أحسن، p < 0.05». كنت مخطط لأسبوعين. تعمل إيه؟

12

اختبر فهمك

Knowledge Check
Practical
ما الفرق بين output و outcome؟
Output هو ما تم بناؤه أو إطلاقه؛ outcome هو التغيير القابل للقياس في قيمة المستخدم أو العمل.
لماذا acceptance criteria يجب أن تكون observable؟
حتى يستطيع الفريق اختبار السلوك دون تخمين أو اختلاف تفسير.
ما الفرق بين feature flag و authorization؟
Feature flag يتحكم في rollout/availability؛ authorization يقرر صلاحية المستخدم ولا يجوز استبداله بإخفاء الواجهة.
13

تمارين محلولة

Solved exercises
Practical
1: اكتب acceptance criteria لـ «بحث في الفواتير»

الحل: بحث برقم الفاتورة (exact) واسم العميل (جزئي، عربي/إنجليزي، case-insensitive)؛ نتائج خلال 500ms p95 لـ tenant فيه 100 ألف فاتورة؛ pagination ثابتة الترتيب؛ empty state بيقترح مسح الفلاتر؛ النتايج محصورة في الـ tenant؛ الـ query ما بتتسجلش لو فيها بيانات حساسة.

2: الـ PM عايز يغير اسم field في الـ public API عشان «أوضح». ردك؟

الحل: ضيف الاسم الجديد جنب القديم (الاتنين في الـ response)، علّم القديم deprecated في OpenAPI والـ headers، قيس مين لسه بيستخدمه، وحدد sunset بعد فترة متفق عليها مع العملاء. ما تكسرش integration عميل عشان تجميل.

3: A/B test بعد يومين: B أحسن 8%. الـ PM عايز يعمم. ردك؟

الحل: هل وصلنا لحجم العينة المحسوب مسبقًا؟ لو لأ، ده peeking والنتيجة غالبًا noise. كمّل للمدة المخططة (دورة أسبوع كامل على الأقل في B2B)، وبص على الـ guardrails قبل القرار.

14

Mini project: Feature من الفكرة للقياس

Mini project
Practical

خد feature من الـ capstone (مثلًا «اقتراح أسئلة متابعة في الـ chat»): discovery notes (5 أسئلة وإجاباتها)، story بـ acceptance criteria (منها criteria إحصائية)، state/UX states في Angular، event catalogue، feature flag، وخطة قياس (metric أساسي + guardrails + حجم عينة). المخرج: PR فيه الكود + docs/features/follow-ups.md.

15

أسئلة إنترفيو: Junior → Senior → Staff

Interview ladder
Basics
(Junior) إيه الفرق بين requirement و acceptance criterion؟
الـ requirement بيوصف الاحتياج؛ الـ acceptance criterion شرط قابل للاختبار يحدد إمتى الشغل يعتبر خلص.
(Senior) إزاي تتعامل مع ticket غامض جاي من sales لعميل كبير؟
أكلم المستخدم الفعلي أو الـ sales engineer، أحدد المشكلة مش الحل المقترح، أكتب الـ rules والحالات الحدية، أتفق على criteria وأصغر slice يتسلم ويتقاس، وأوثق القرارات.
(Staff) فريقين بيختلفوا على أولوية features، وكل واحد عنده رقم RICE. تعمل إيه؟
أوحّد تعريفات الـ reach/impact (إيراد، retention، استراتيجية)، أطلع الافتراضات اللي بتفرق، وأحوّل الـ confidence المنخفض لتجارب صغيرة قبل الالتزام. والقرار النهائي مربوط بأهداف الشركة للربع، ويتوثق مع سببه.
↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

التوثيق الرسمي — Official documentation

خريطة التغطية: 19 عنصر من الـ Roadmap ومكان شرحه في الدرس
New sectionRequirements Engineering§01
New sectionBusiness Logic Modeling§01
New sectionUser Stories§01
New sectionAcceptance Criteria§01
New sectionAPI Contract Design§03
New sectionError State Design§03
SuggestedRequirements Engineering§03
SuggestedBusiness Logic Modeling§03
SuggestedUser Stories§04
SuggestedAcceptance Criteria§04
SuggestedAPI Contract Design§04
SuggestedError State Design§05
SuggestedUX Fundamentals§05
SuggestedFeature Flags§05
SuggestedAnalytics Events and Product Analytics§06
SuggestedProduct Metrics§06
SuggestedFeedback Loops§06
SuggestedA/B Testing§06
SuggestedExperiment Statistics§07

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس