كتابة INTENT و CONSTRAINTS

INTENT ضعيف بيبان زي وصف function بالإنجليزي العادي. القوي بيبان زي أول سطر في ملف المصدر.

Intent ضعيف:

I want a function that removes duplicates while keeping the order.

Intent قوي:

Write a Python function dedupe_preserve_order(items: list[str]) -> list[str].

النسخة القوية بتلتزم باللغة، اسم الـ function، اسم الـ parameter، نوعه، ونوع الـ return — 5 قرارات في سطر. دلوقتي مفيش حاجة عند الموديل يخترعها على واجهة الـ API.

INTENT الكويس بيجاوب على 3 أسئلة:

1. إيه الـ signature؟ الاسم، الـ parameters بأنواعها، نوع الـ return. Type hints في Python، TS types كاملة، Go signature كاملة بـ receiver و error return.
2. بيعمل إيه بدقة جملة واحدة؟ "Remove duplicates while preserving first-seen order" — مش "make the list nicer."
3. إيه الـ side effects؟ Pure function؟ بيغيّر الـ input؟ بيقرا من disk؟ Network؟ لو ما قلتش، الموديل هيفترض pure.

CONSTRAINTS هي اللي بتشفّر الحاجات اللي كل reviewer مهتم بيها وما بتدخلش في الـ signature. بتنقسم لـ 4 buckets:

Bucket	أمثلة
Performance	O(n) time, O(1) extra memory, لازم يخلص في أقل من 100ms لـ n=10,000
Dependencies	مفيش external imports، stdlib بس، Python ≥ 3.10، مفيش lodash
Style	Type hints مطلوبة، مفيش any، snake_case، مفيش nested ternaries
Behaviour	Case-sensitive، يرفع ValueError على input فاضي، idempotent

قاعدة: لو تقدر تتخيّل reviewer بيكتب "كان المفروض تستخدم X" أو "ده مش هيـscale عشان Y"، يبقى X و Y مكانهم في CONSTRAINTS. حط كل اعتراض من الأول.

تخيّل تدفق قرار الموديل لما بيقرا الـ INTENT + CONSTRAINTS بتاعتك:

أهم constraint بينساه المهندسين هو الـ negative — الحاجة اللي الموديل مش المفروض يعملها. "مفيش external imports" بيمنعه يجيب more_itertools. "مفيش regex" بيمنعه يحط نمط ذكي ولا حد في الـ team هيقراه. "مفيش mutation للـ inputs" بيمنع side-effect bug. كل "لا" بتكتبها بتوفّر دورة code review.

هتشوف المبدأ ده في الـ CONSTRAINTS block المقابل لـ dedupe function في الدرس الخامس: O(n) time، O(n) memory، حافظ على الترتيب، case-sensitive، مفيش external imports، type hints مطلوبة.

التالي: كتابة TESTS و FORMAT. :::