النظريّة رخيصة. إليك تذكرة حقيقيّة شحنتها الأسبوع الماضي مع Claude Code، تمامًا كما جرت — ماذا كتبت في الـ prompt، ماذا فعل الوكيل، ماذا أمسكت، وماذا تركته يُشحن.

أستخدم تقنيات المقالات 3-7 (prompts رباعيّة الأقسام، sub-agents، slash commands، خطّ الأنابيب الخطّيّ). لا سحر، ولا صلصة سرّيّة.

التذكرة

العنوان: إضافة rate limiting لكلّ مستخدم على endpoints /api/notes/*
القبول:
- 60 req/min/user، نافذة منزلقة
- 429 مع header Retry-After عند التجاوز
- تجاوز للمستخدمين بـ `internal: true`
- الاختبارات الحالية يجب أن تبقى خضراء
- إضافة تغطية للمنطق الجديد

ميزة صغيرة بالكتاب: هدف واضح، قيود واضحة، قابلة للاختبار. النوع الذي يأكله Claude Code للفطور.

الخطوة 1 — تأطير الـ prompt بـ /feature

> /feature
> الهدف: إضافة rate limiting بنافذة منزلقة لكلّ مستخدم على /api/notes/*.
>   60 req/min/user، استجابة 429 + header Retry-After عند التجاوز.
>   تجاوز عندما user.internal === true.
>
> القيود:
>   - أعد استخدام عميل redis الحالي في lib/redis.ts.
>   - لا تضف اعتماديّة جديدة.
>   - نفّذ كـ Next.js middleware في middleware.ts (path-scoped).
>   - لا تلمس الاختبارات الحالية.
>
> تعريف الإنجاز:
>   - pnpm test ينجح.
>   - vitest جديد يغطّي: تحت الحدّ، فوق الحدّ 429، تجاوز internal.
>   - pnpm lint نظيف.
>
> الملفات:
>   - middleware.ts (نقطة الدخول)
>   - lib/redis.ts (العميل الحالي)
>   - lib/rate-limit.ts (جديد)
>   - tests/rate-limit.test.ts (جديد)

لاحظ الأقسام الأربعة: الهدف، القيود، DoD، السياق. المقال 3 لم يكن يمزح.

الخطوة 2 — implementer يأخذ الزمام

انتقلت إلى implementer sub-agent وتركته يعمل. إليك ما فعله تقريبًا، مرويًا:

1. cat middleware.ts، cat lib/redis.ts — بنى السياق.
2. صاغ lib/rate-limit.ts بنافذة منزلقة عبر Redis sorted sets.
3. كتب middleware.ts لاستدعاء الـ limiter على /api/notes/* واحترام علم internal.
4. كتب tests/rate-limit.test.ts بالحالات الثلاث من DoD.
5. شغّل pnpm test. اختبار واحد فشل — 429 لم يضمّ Retry-After.
6. أعاد قراءة كوده، وجد الـ header المفقود، أصلح، أعاد التشغيل. أخضر.
7. شغّل pnpm lint. نظيف.
8. أصدر تسليمًا منظّمًا: status: ok, artifacts: [...].

wall clock: ~6 دقائق. tokens: ~14k. تدخّلي: صفر حتى الآن.

الخطوة 3 — code-reviewer ثاني زوج عيون

> /agents code-reviewer
> راجع الـ diff.

حكم الـ reviewer (بإعادة صياغة):

SHIP، مع ملاحظتين:

1. قريب من خلل: تستعمل النافذة المنزلقة Date.now() داخل ZADD Redis. في
   نشر متعدّد المناطق مع انحراف ساعات، قد يسبّب ذلك إزالة بفارق واحد. أوصي
   باستعمال ZADD مع redis TIME بدلاً من ذلك.

2. أسلوب: rate-limit.ts يصدر كلاسًا بينما يُستعمل كدالّة في أمكنة أخرى.
   أوصي بتصدير factory function للاتّساق مع lib/cache.ts.

كلاهما لا يعرقل الميزة، لكنّهما يستحقّان متابعة.

هذه بالضبط قيمة وكيل reviewer منفصل. الكود نجح؛ الـ reviewer رفع علمين حقيقيّين لن يثيرهما المنفّذ على عمله.

اتّخذت قرارًا سريعًا: شحن الميزة، فتح تذاكر متابعة للملاحظتين. هذا قرار بشريّ، لا قرار وكيل.

الخطوة 4 — مراجعة الـ diff من قبلي (الإنسان)

فتحت الـ diff. ~180 سطرًا عبر 3 ملفات. قرأته من فوق إلى تحت.

ما أمسكته ولم يره أيّ من الوكيلين:

• في lib/rate-limit.ts الجديد تعليق يقول // rate limit logic. حذفته (نمط مضادّ من المقال 3: لا تروِ ما يفعله الكود).
• استيرادات الاختبار غير مرتّبة. ثغرة صغيرة في إعداد lint من جهتي، لا من الوكيل.

هكذا تبدو المراجعة في هذا الـ workflow: 5 دقائق قراءة، تعديلان دقيقان، شحن.

الخطوة 5 — release notes + وصف PR

> /agents release-bot
> صُغ وصف PR ومدخلة CHANGELOG.

المخرج (بتحرير طفيف):

## إضافة rate limiting لكلّ مستخدم على /api/notes/*

- نافذة منزلقة، 60 req/min/user، مدعوم بـ Redis.
- 429 مع header `Retry-After`.
- تجاوز لـ `user.internal === true`.

Closes ENG-2451.

نسخت ذلك إلى gh pr create ودفعت. wall clock الإجمالي للتذكرة: حوالي 22 دقيقة. منها ~6 للوكيل، ~5 لوكيل المراجعة، ~7 لمراجعة الـ diff، ~4 لـ PR + الـ push.

كيف بدا هذا الـ workflow قبل سنة، يدويًا

بالنسبة لي، نفس التذكرة كانت ستأخذ 90 دقيقة:

• 20 دقيقة لقراءة الكود الحالي.
• 30 دقيقة للتنفيذ.
• 20 دقيقة على الاختبار (خصوصًا mocking لـ Redis sorted set).
• 10 دقائق على lint / تنظيف.
• 10 دقائق على وصف PR.

22 دقيقة مقابل 90 دقيقة هو الرقم العنوان. لكن الانفراج الأصدق هو تخفيف الحمل المعرفي. لم أكن في تركيز عميق طوال 22 دقيقة؛ كنت في مراجعة فعّالة 12 منها، وأنتظر / أفكّر في التذكرة التالية في البقيّة.

أمور لم أُفوّضها

• قرار اختيار البدائيّة في Redis (sorted set مقابل counter مع TTL). أخبرت الوكيل.
• قرار دلالات التجاوز (internal: true مقابل دور جديد). قرّرت في الـ prompt.
• الـ push إلى remote. دائمًا بشريّ.

هذا التقسيم الصحيح للعمل. يمتلك الوكيل التنفيذ. أمتلك التصميم والإجراءات غير القابلة للعكس.

نمط يمكنك سرقته

لكلّ تذكرة "ميزة صغيرة":

1. خصّص 5 دقائق لكتابة prompt رباعيّ الأقسام. اكتبه فعلاً.
2. يعمل implementer حتى تخضرّ الاختبارات.
3. يعمل code-reviewer، يقرأ الـ diff، يدوّن المخاطر.
4. تقرأ الـ diff. 5 دقائق.
5. يصوغ release-bot وصف الـ PR.
6. تدفع.

افعل هذا 10 مرّات في أسبوع. بحلول الجمعة سيكون أكثر workflow طبيعيّ امتلكته.

---

المقال التالي: الاختبارات والتصحيح — كيف تترك Claude Code يمتلك حلقة الاختبارات بأسرها، بما فيها الأجزاء التي تجعل المهندسين متوتّرين (regressions، flakies، اختبارات تكامل).