من التذكرة إلى ملف المهمة: الوكيل يصوغ والقرار للإنسان

انتهى الجزء السابق عند الملف الثالث، أي ملف المهمة. وهذا الملف يحمل قاعدة الجزء الأول: الوكيل ينفّذ نطاقاً () تقرّر مسبقاً، ولا يقرّره أبداً. وهو ما يثير اعتراضاً بديهياً: من يكتب النطاق إذن؟ أليس هذا هو الجزء البطيء؟

ليس كذلك، إذا تركت الوكيل يكتب مسودته.

وثيقتان وقرار واحد

الطلب مكتوب أصلاً لدى الشركات، واسمه التذكرة (). وهي مكتوبة للناس: بلغة الأعمال، ومعها معايير القبول ولقطات الشاشة والتعليقات. وتبقى حيث تحفظها الشركة.

أما ملف المهمة فهو القرار نفسه بلغة المستودع: المكتبات المسموح بتعديلها، ودوال المجال () التي يُعاد استخدامها، والأوامر التي تحدد معنى «انتهى»، والحد الأقصى لحجم الـ . نادراً ما تقول التذكرة «لا تعدّل التحققات الموجودة» أو «استدعِ canTransfer() من مكتبة المجال». ولا يكاد ملف المهمة يقول غير ذلك.

كتابة الوثيقتين يدوياً تكرار. أما أن تكتب التذكرة وتترك الوكيل يترجمها، فليس كذلك: فبعد أن يقرأ الوكيل الكود، يعدّد الملفات التي تمسّها التذكرة أسرع من الشخص الذي كتبها.

الخطوة الأولى: الوكيل يصوغ المسودة

برومبت · من التذكرة إلى ملف المهمة

اقرأ AGENTS.md و docs/tasks/TEMPLATE.md. في ما يلي التذكرة كما كتبها فريق الأعمال. حوّلها إلى ملف مهمة لهذا المستودع.

لا تكتب كوداً. اذكر الملفات التي ستعدّلها وسبب ذلك، والنطاق الذي تقترحه، وما تعدّه خارج النطاق، وقائمة «ينتهي حين» مع الأوامر الدقيقة، وكل سؤال تحتاج إلى جوابه قبل أن تبدأ. أبقِ الـ diff دون 300 سطر، وإن تعذّر ذلك فقسّمه إلى مهام مرقّمة.

--- التذكرة --- ATLAS-218 · تصدير المعاملات إلى ملف CSV بصفتي عميلاً، أريد تصدير معاملات حسابي مع عوامل التصفية التي طبّقتها، حتى أطابقها في Excel. الأعمدة: التاريخ، والوصف، والفئة، والمبلغ بالدرهم المغربي (MAD). الحد الأقصى 10,000 صف. يجب أن يعمل على واجهة الهاتف المحمول.

تصل المسودة في غضون دقائق. وغالباً ما تكون أكمل من تذكرة كُتبت من الذاكرة، ولها عادة يجدر بك أن تعرفها: تجيب عن أسئلتها بنفسها. «هل يلتزم التصدير بعوامل التصفية الحالية؟ سأفترض أن الجواب نعم.» هذا الافتراض قرار، واتخاذه ليس من شأن الوكيل. احفظ المسودة باسم docs/tasks/008-export-filtered-transactions-csv.md، فالخطوتان التاليتان تعملان على هذا الملف.

الخطوة الثانية: وكيل ثانٍ يتحقق

قبل أن يقرأ إنسانٌ المسودة، دع وكيلاً لا مصلحة له فيها يقرؤها: جلسة جديدة أو نموذج ذكاء اصطناعي مختلفاً، لا يملك إلا ملف القواعد والمسودة، فلا يكون لديه عمل خاص به يدافع عنه:

برومبت · تحقّق من المهمة قبل أن يقرأها إنسان

اقرأ AGENTS.md، ثم docs/tasks/008-export-filtered-transactions-csv.md. لست أنت من كتبه. تحقّق منه في ضوء القواعد، وأجب عن هذا فقط:

هل يمسّ النطاق أي مجلد تمنعه القواعد، أو أي مكتبة لا تحتاج إليها المهمة؟
هل كل بند في «ينتهي حين» أمرٌ أو نتيجة مرئية، لا رأي؟
هل يمكن أن يبقى الـ diff المقترح دون 300 سطر؟ إن لم يكن، فاقترح طريقة التقسيم.
ما الأسئلة المفتوحة التي أجابت عنها المسودة بنفسها بدل أن تطرحها؟
هل في التذكرة شيء غائب عن المهمة؟

قدّم ردّك قائمةً مرقّمة بالملاحظات، من دون إعادة كتابة.

هذا التحقق يجيد التقاط الأخطاء الآلية: نطاق يتسلل إلى مكتبة مشتركة، وبند «ينتهي حين» يكتفي بعبارة «يعمل بشكل صحيح»، و diff لا يتسع للحد المسموح، وكل سؤال أجابت عنه المسودة بنفسها في صمت.

الخطوة الثالثة: الإنسان يقرّر

ما تبقّى قصير. قلّص النطاق الذي توسّعت فيه المسودة. أجب عن الأسئلة داخل الملف نفسه. وقرّر هل هذا هو التغيير الذي تريده، فهذا وحده ما لا يستطيعه أي وكيل. احفظ الملف، أو أعد لصقه في التذكرة إن كان فريقك يقرأ هناك.

دقائق قليلة من وقت الوكيل، ومثلها من وقتك، ولا شيء يُكتب يدوياً مرتين. صارت لدى الوكيل الآن مهمة لم يقرّرها هو.

شكل ملف المهمة الجيد

ملف المهمة هو الحقيقة. والكود هو التفاصيل.

# المهمة 008: تصدير المعاملات المُصفّاة لحساب إلى ملف CSV
 
## الهدف
يستطيع العميل تنزيل المعاملات المُصفّاة لحساب ما في ملف CSV، على الحاسوب وعلى الهاتف.
 
## النطاق
- مسموح بتعديل: `libs/feature/accounts`
- ملفات جديدة مسموحة في: `libs/feature/accounts/src/lib/` (ملف `transactions-csv.ts` نقي + ملف الاختبار الخاص به)
 
## خارج النطاق
- `libs/ui` (لا مكوّن مشترك جديد). `libs/data-access/*` (المعاملات موجودة أصلاً في المخزن). `libs/legacy/**`.
 
## ينتهي حين
- [ ] ينجح `npm run lint:arch` و `npm run test` (دون تعديل أي تحقق) و `npm run typecheck`
- [ ] في `/accounts/a-current`، التصفية حسب الفئة ثم النقر على "Export CSV" تنزّل الصفوف المُصفّاة فقط (تقرّر: نعم، ATLAS-218 التعليق 3)
- [ ] الأعمدة بهذا الترتيب: التاريخ، والوصف، والفئة، والمبلغ بالدرهم المغربي (MAD)؛ وبحد أقصى 10,000 صف
- [ ] على واجهة الهاتف المحمول، يظهر زر "Export CSV" ويعمل التنزيل
- [ ] الـ diff ≤ 300 سطر
 
## ملاحظات للوكيل
- أقرب نظير يُحتذى به: `libs/feature/accounts/src/lib/account-detail.ts`
- دوال المجال المساعدة التي يُعاد استخدامها: `formatMad` و `categoryLabel` من `@atlas/domain`

سطر «أقرب نظير» () هو البطل الخفي. فالوكلاء ينسخون الشكل. أشِر إلى الشكل الصحيح، وسيعود الكود شبيهاً ببقية قاعدة الكود.

مع بداية الأسبوع

كفّ عن كتابة ملفات المهام يدوياً. الصق التذكرة، واطلب ملف المهمة لا الكود.
شغّل برومبت التحقق في جلسة جديدة قبل أن تقرأ أي مسودة.
قرّر داخل الملف، ولا تقرّر في المحادثة أبداً. فالملف هو ما سيقرؤه الوكيل الأسبوع المقبل.

التمرين: docs/tasks/TEMPLATE.md والمهمة 001 في المستودع التجريبي، وهي نسخة مكتملة وأقصر من هذا التصدير. البداية: git switch -c m1/you main. الحل المرجعي: origin/track1/m1-solution.

الميزة الجديدة هي الحالة السهلة. أما الجزء التالي فيتناول كوداً يعمل أصلاً في بيئة الإنتاج: وحدة قديمة () يجب ترحيلها، وأول ما يُراجَع فيها هو خطة الوكيل نفسها.

المسار 1، الجزء 3 من السلسلة المجانية المرافقة لورشة سريع وآمن: الذكاء الاصطناعي في قاعدة كود Angular الخاصة بك.