كيف تكتب تذكرة يستطيع وكيل الذكاء الاصطناعي إنهاءها فعلًا

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

الأرقام المجمّعة تقول إن هذا هو الوضع الطبيعي. معايير الهندسة لعام 2026 من LinearB، المبنية على 8.1 مليون pull request من نحو 4,800 فريق، تضع نسبة دمج الطلبات المكتوبة بمساعدة الذكاء الاصطناعي عند 32.7% خلال ثلاثين يومًا، مقابل 84.5% للطلبات التي كتبها بشر. وحجم هذه الطلبات أكبر بنحو 2.5 مرة عند الشريحة المئينية 75، وتنتظر أكثر من خمسة أضعاف المدة قبل أن يلتقطها مراجع. تحققنا من هذه الأرقام في يوليو 2026.

النموذج نادرًا ما يكون المتغيّر الذي تتحكم فيه. التذكرة هي ذلك المتغيّر، ومعظم الفرق تسلّم الوكيل مهمة مكتوبة لزميل يعرف الكود، ويتذكّر نقاش المعمارية الذي دار الشهر الماضي، ويعرف أي المجلدات لا يُقترب منها. الوكيل لا يملك شيئًا من ذلك، فيملأ الفراغ بنفسه. أحد عشر ملفًا هو شكل ملء الفراغ.

نحن من نبني Taskfolk، فاقرأ الأقسام المتعلقة بالمنتج بوصفها نصيحة صاحب مصلحة. أما صناعة التذكرة نفسها فتنفع في أي أداة.

ما تفترضه التذكرة البشرية ولا يملكه الوكيل

التذكرة المكتوبة لإنسان مجرد إشارة. عبارة «أصلح اختبار الدفع المتقلّب» تنجح لأن زميلك يعرف أي اختبار تقصد، ويتذكّر حيلة إعادة المحاولة التي أُضيفت في مارس، ويعرف ألا يمسّ عميل الدفع يوم الجمعة. لا شيء من ذلك مكتوب في التذكرة. إنه يعيش في الاجتماع اليومي، وفي سجل محادثات Slack، وفي رأس المراجع.

انزع ذلك كله وستغيب خمسة أشياء في كل مرة: أين ينتمي هذا النوع من التغيير داخل المستودع، وأي المقاربات جُرِّبت ورُفضت من قبل، وما هو الممنوع، وما الذي يُحتسب إنجازًا بعد «أنه يعمل»، ومن تسأل حين يتبيّن أن التذكرة نفسها خاطئة.

الفرق تعرف نصف هذا، ولهذا بدأت المستودعات تمتلئ بملفات سياق للوكلاء. انظر إلى ما يوضع فيها. دراسة على 2,303 ملف سياق في 1,925 مستودعًا وجدت أن المطورين يوثّقون أوامر البناء والتشغيل في 62.3% من الحالات، وتفاصيل التنفيذ في 69.9%، والمعمارية في 67.7%، ثم متطلبات الأمان والأداء عند 14.5% لكل منهما. الفرق تشرح للوكلاء كيف يبنون. ونادرًا ما تخبرهم بما يجب ألا يكسروه.

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

الحقول السبعة التي تغيّر النتيجة

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

حدود ما يجوز تغييره

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

صياغة ضعيفة: «أصلح اختبار الدفع المتقلّب.»

صياغة صالحة: «أصلح اختبار الدفع المتقلّب. عدّل الملفات داخل tests/checkout/ فقط. لا تعدّل عميل الدفع، ولا تضف اعتماديات، ولا تعِد تنسيق ملفات لم تلمسها لسبب آخر.»

تبدو الجملة الأخيرة تافهة إلى أن تراجع فرقًا من 900 سطر، منها 40 سطر إصلاح و860 سطرًا من أداة التنسيق.

تعريف التوقف

إن لم تقل شيئًا، فالافتراضي هو المتابعة، والوكيل المصرّ سيلتف على العائق بإعادة هيكلة ما حوله بدل أن يعترف بأن التذكرة أرقّ من أن تُنجَز.

صياغة صالحة: «إن تطلّب الإصلاح تغيير سلوك إعادة المحاولة في عميل الدفع، فتوقف. انقل جلستك إلى needs input وعلّق بما وجدته. لا تجرّب أكثر من ثلاث مقاربات.»

وامنح التعليمة مكانًا تهبط فيه. جلسات الوكلاء هنا لها حالة needs_input، والدخول إليها يُشعِر مالك الوكيل، ومعه المُبلِّغ والمُسند إليه والمتابعون على المهمة، فيصبح التوقف مرئيًا لا صامتًا.

مسار التصعيد

عبارة «اسأل إن كان شيء غير واضح» ليست مسار تصعيد. فهي لا تسمّي شخصًا ولا مكانًا ولا صيغة.

صياغة صالحة: «إن احتاج الأمر قرارًا في المنتج، علّق على هذه التذكرة وأشِر إلى @dana. وإن كانت بيانات البذرة في بيئة الاختبار مفقودة، فأشِر إلى @omar. ولا تفتح تذكرة جديدة في أي من الحالتين.»

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

أما الحقول الأربعة الباقية فبديهية، ومعظم الفرق تكتب نسخة رديئة منها بالفعل.

الحقل	الصياغة الضعيفة	صياغة يستطيع الوكيل العمل بها
الهدف، في جملة واحدة	«حسّن موثوقية الدفع.»	«امنع صفحة الدفع من الإرسال مرتين حين ينقر المستخدم على Pay نقرتين متتاليتين.»
اختبار القبول	«يعمل بشكل صحيح.»	‏«npm test tests/checkout/double-submit.test.ts ينجح، وهو يفشل على main الحالي.»
القيود	غائبة عادةً	«لا اعتماديات جديدة. أبقِ التوقيع المُصدَّر للدالة submitOrder كما هو. لا ترحيل لقاعدة البيانات.»
من أين تبدأ	«في مكان ما داخل الدفع.»	‏«src/checkout/submit.ts. والملف src/cart/apply-coupon.ts ينفّذ هذا الحارس بالفعل، فاتبع النمط نفسه.»

صف القبول هو الذي يستحق المعركة. إن كان «منجز» أمرًا ينتهي بالرمز صفر، فالوكيل يفحص عمله بنفسه قبل أن يطلب منك فحصه. وإن كان «منجز» فقرة نصية، فأنت مجموعة الاختبارات.

ضع البنية في القالب، لا في ذاكرتك

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

يملأ Taskfolk وصف المهمة مسبقًا في نافذة إنشاء المهمة من قالب خاص بكل نوع. وقالب المهمة قصير عن قصد:

## Context
Why this task exists. What changed upstream.

## What to do
- Step 1
- Step 2

## Definition of done
- [ ] Code shipped
- [ ] Verified in staging

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

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

تصحيح واحد، لأن النسخة التسويقية من هذه الميزة كذبة في الغالب: تعليم الحقل بأنه مطلوب لا يمنع أحدًا من فتح تذكرة بدونه. ما يرفضه الخادم هو تفريغ حقل مطلوب وإعادته إلى null بعد أن صارت له قيمة. هذا قيد باتجاه واحد يمنع شخصًا من حذف المعايير بعد ثلاثة أيام، وليس بوابة عند الإنشاء. وإن أردت بوابة صارمة عند الاستقبال، فضع الحقل في نموذج طلب، حيث يرفض التحقق الإرسال من أصله. أما الأنواع والخيارات وتحديد النطاق فيغطيها مقال الحقول المخصصة في تتبع المهام.

كفّ عن لصق أعرافك في كل تذكرة

نمط الفشل الثاني يظهر بعد أن تتحسن التذاكر: صارت كل تذكرة تحمل فقرة من حشو مساحة العمل. مفاتيح المشاريع، ومفردات الوسوم، ومن تُشير إليه، وأي حقل يحمل معايير القبول. مكرّرة أربعين مرة، وقديمة بصمت في ثلاثين منها.

قسّم السياق بحسب سرعة تغيّره.

flowchart LR
  A["Repo agent file: build and test commands"] --> R["What the agent knows when it starts"]
  B["Workspace skill bundle: project keys, labels, mention handles"] --> R
  C["The ticket: goal, boundary, done, stop"] --> R

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

يولّد Taskfolk الطبقة الوسطى. حزمة المهارة ملف SKILL.md مبني من جرد مساحة عملك الحيّة، ومعه إعدادات عميل MCP لـ Claude Desktop وCursor وVS Code. وكل مشروع نشط يظهر بمفتاحه، ومعرّفه النصي، وصيغة مفاتيح مهامه، ووسومه الحقيقية، وتعريفات حقوله المخصصة بأنواعها وخياراتها:

### WEB - Web app
- Slug: `web`
- Issue keys look like `WEB-123`. Reference them in comments as `#WEB-123`.
- Labels: `frontend`, `checkout`, `regression`
- Custom fields:
  - `Acceptance criteria` (text, required)
  - `Risk` (select), options: `low`, `medium`, `high`

والأعضاء يظهرون في جدول من @handle والاسم والدور، وهذا ما يحوّل «أشِر إلى @dana» إلى تعليمة ينفّذها الوكيل. والصلاحيات الممنوحة مذكورة كذلك. أما تركيب الحزمة على أدواتك فيشرحه مقال كيفية تثبيت Taskfolk كمهارة للوكيل.

أسنِد المهمة، ثم راقب الجلسة بدل التعليقات

إسناد مهمة إلى وكيل يُنشئ جلسة بحالة pending فورًا، قبل أن يستيقظ الوكيل. والسبب ممل ومفيد: التفويض يظهر على المهمة وفي مركز الوكلاء لحظة إجرائه، فلا يلتقط شخص آخر العمل نفسه بينما الوكيل ما زال في الطابور.

stateDiagram-v2
    [*] --> pending
    pending --> running
    running --> needs_input
    needs_input --> running
    running --> review
    review --> done
    running --> failed
    pending --> cancelled
    done --> [*]
    failed --> [*]
    cancelled --> [*]

يستطيع الوكيل أن يغادر pending لكنه لا يدخلها أبدًا، وحين يطالب بالعمل فإنه يستولي على الصف الموجود بدل تكراره. والجلسة في حالة running التي تمضي ثلاثين دقيقة بلا نبضة تظهر متوقفة، وهذه الحالة تُحسب لحظة نظرك إليها بدل أن تُكتب في عمود يتقادم وحده. والجلسات التي لا يطالب بها أحد تُلغى بعد سبعة أيام.

وإنصافًا للمنافسين، لأن مدونات المزوّدين تبالغ في حجم الفارق، وهذا ما تحققنا منه في يوليو 2026: Jira يتيح إسناد عناصر العمل إلى الوكلاء منذ نسخته التجريبية في فبراير 2026، ووكلاء Linear مستخدمو تطبيق يمكن الإسناد إليهم والإشارة إليهم، مع إنشاء جلسة عند التفويض. وفي Linear يكون الوكيل مفوَّضًا بينما يبقى إنسان هو المُسند إليه الأساسي والمالك. أما هنا فالوكيل يحمل الإسناد تحت هوية مستخدمه هو، فتحمل الأنشطة والتعليقات اسمه دون معالجة استثنائية.

ولمراجعة العمل مقال مستقل هو إدارة فريق من وكلاء الذكاء الاصطناعي، وسطر واحد عنه هنا: الجلسة التي تصل إلى review أو done دون صف نشاط منسوب إليها ودون تعليق على مهمتها تُوسم بأنها غير مُتحقَّق منها. وهذا جرس إنذار لا حكم نهائي، ويكفي تعليق واحد لإسكاته. دراسة على 9,799 pull request من إنتاج الوكلاء راجعها بشر وجدت أن 33.1% من حالات الرفض لم تترك أي مبرر قرار ظاهر، وأن 5.5% من الطلبات المدموجة لم تُظهر أثر تفاعل مرئيًا أيضًا، فغياب الأثر دليل ضعيف في الاتجاهين. ومجموعة اختباراتك تبقى هي ما يثبت الصحة.

قيّد ما يستطيع الوكيل كتابته

إن كانت التذكرة هي العقد، فسياسة الحقول وقواعد الانتقال هي بنوده. كل وكيل متصل يمكن أن يحمل قائمة سماح على أربعة عشر رمزًا من حقول المهمة: title وdescription وstatus وpriority وassignee وlabels وmilestone وsprint وrelease وestimate وspent وcompletion وstart_at وdue_at. وغياب السياسة (null) يعني أن كل شيء قابل للكتابة. والتطبيق يجري في نقطة اختناق واحدة، فتمرّ نداءات REST ونقطة نهاية الانتقال ونداءات أدوات MCP ونقطة نهاية الوقت على الفحص نفسه، بدل فحوص متشابهة تتباعد مع الوقت.

ولنقل الحدّ بوضوح: السياسة لكل حقل، لا لكل قيمة. أنت تقرر هل يجوز للوكيل أن يكتب status أصلًا. ولا تستطيع أن تقول «إلى قيد المراجعة فقط». هذا الشكل يأتي من الانتقالات المسموحة على حالات اللوحة، وهي بوابة حقيقية، لأن أي نقلة غير مسموحة تُعيد خطأً على كل مسارات الكتابة بما فيها كتابة الوكيل نفسه. أما ترتيب البطاقات على اللوحة فلا يُقيَّد أبدًا، لأن منع وكيل الفرز من إعادة ترتيب البطاقات ليس الغاية.

حدود WIP هي الضابط الوحيد هنا الذي يبدو أصرم مما هو. شارة العدد وإطار العمود الأحمر يأتيان من مفتاح في عرض اللوحة، ويغيّران اللون فقط. قواعد الانتقال تفرض، وحدود WIP تنبّه.

القدرة	Taskfolk	Linear	Jira
الوكيل يحمل الإسناد	نعم، بهوية مستخدم خاصة به	نعم، كمفوَّض بينما يبقى إنسان هو المالك الأساسي	نعم، يظهر الوكلاء في خانة المُسند إليه
قائمة سماح بالكتابة لكل حقل ولكل وكيل	نعم، 14 رمز حقل	أذونات تثبيت على مستوى التطبيق، لا لكل حقل	مخططات أذونات وسير عمل، لا لكل وكيل ولكل حقل
ملف تعليمات مولّد من مساحة عملك الحيّة	نعم	لا يوجد مكافئ معلن	لا يوجد مكافئ معلن

إعداد الاثنين مشروح في كيفية ضبط أذونات حقول الوكيل، أما مسار التفويض نفسه ففي كيفية تفويض العمل إلى وكيل.

القالب كاملًا

انسخ هذا، واحذف ما لا ينطبق، وأبقِ العناوين الثلاثة الأخيرة حتى لو بدت بديهية.

## Goal
One sentence. The observable change, not the activity.

## Scope
Files or modules you may change. Everything else is out of bounds.

## Acceptance
- [ ] Command that must pass, and the fact that it fails today
- [ ] Behaviour a human can check in staging

## Constraints
No new dependencies. Public signatures unchanged. No schema migration.

## Start here
Path to the entry point, plus one file that already does something similar.

## Stop when
The condition under which you stop and ask instead of continuing.

## Escalate to
@handle for product decisions. @handle for environment problems.

وإنشاء التذكرة عبر API يحتاج نداءً واحدًا، والقالب يوضع في description_md:

curl -X POST https://taskfolk.ai/api/v1/workspaces/acme/projects/WEB/issues \
  -H "Authorization: Bearer tfk_live_a1b2..." \
  -H "Content-Type: application/json" \
  -d '{"type":"bug","title":"Checkout submits twice on double click","description_md":"## Goal\nStop double submission...","labels":["checkout","regression"],"priority":"high"}'

const res = await fetch(
  "https://taskfolk.ai/api/v1/workspaces/acme/projects/WEB/issues",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer tfk_live_a1b2...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "bug",
      title: "Checkout submits twice on double click",
      description_md: "## Goal\nStop double submission...",
      labels: ["checkout", "regression"],
      priority: "high",
    }),
  },
);

import requests

res = requests.post(
    "https://taskfolk.ai/api/v1/workspaces/acme/projects/WEB/issues",
    headers={"Authorization": "Bearer tfk_live_a1b2..."},
    json={
        "type": "bug",
        "title": "Checkout submits twice on double click",
        "description_md": "## Goal\nStop double submission...",
        "labels": ["checkout", "regression"],
        "priority": "high",
    },
)

{
  "id": "0199c1f4-8a2e-7c31-9d55-6b0a2f13e4c7",
  "key": "WEB-412",
  "url": "https://taskfolk.ai/w/acme/p/web/WEB-412",
  "type": "bug",
  "status": "backlog",
  "assignee_id": null
}

وقيم الحقول المخصصة تحتاج نداءً ثانيًا، لأن جسم الإنشاء لا يحوي مكانًا لها:

curl -X PUT https://taskfolk.ai/api/v1/workspaces/acme/projects/WEB/issues/WEB-412/custom-fields/$FIELD_ID \
  -H "Authorization: Bearer tfk_live_a1b2..." \
  -H "Content-Type: application/json" \
  -d '{"value":"npm test tests/checkout/double-submit.test.ts exits zero"}'

والإسناد نداء PATCH يحمل معرّف مستخدم الوكيل، وتقرأه من نقطة نهاية الوكلاء. وهذا النداء هو الذي يُنشئ الجلسة المعلّقة.

ما لا يعالجه هذا كله

لا يمنح Taskfolk تذاكرك درجات. لا يوجد فاحص يرفع علمًا على تذكرة غامضة قبل أن تُسندها، وبناء شيء كهذا سيصنع ثقة زائفة في الغالب. الحقول أعلاه انضباط، لا ميزة.

وهو لا يشغّل وكيلك أيضًا. الإسناد والإشارات تُدفع عبر مجرى أحداث خاص بكل وكيل، وسجل الجلسة يعيش هنا، لكن بيئة التشغيل لك، على جهازك أو في CI. وتكلفة الجلسة هي ما يبلّغ عنه الوكيل، أو تقدير مبني على عدد الرموز (tokens) التي يبلّغ عنها، لأن الرموز تُصرف على حسابك لدى المزوّد حيث لا نراها.

والأطول ليس أفضل كذلك. دراسة على ملفات إعداد الوكلاء في مئة مستودع شائع وجدت تضخّمًا في السياق في 42% منها، وقواعد فحص الكود تتسرب إلى التعليمات في 62%. الموجز القصير المكتوب بيد إنسان يتفوق على الموجز الطويل المولّد، والموجز المولّد الذي ابتعد عن الواقع أسوأ من لا شيء.

وبعض العمل لا ينبغي أن يذهب إلى وكيل أصلًا، وأوضح قائمة بذلك تأتي من مزوّد يبيع الوكلاء. توثيق GitHub نفسه يقول: أبقِ لديك إعادة الهيكلة العابرة للمستودعات، ومنطق العمل الجوهري، وكل ما يمسّ الأمان أو المصادقة أو البيانات الشخصية، والاستجابة للحوادث، والعمل الغامض المفتوح بلا نهاية، وأي مهمة أخذتها على عاتقك لتتعلم منها شيئًا. والتذكرة التي يصعب كتابتها بالشكل أعلاه تخبرك عادةً أنها تريد إنسانًا.

وإن كان هذا تفويضك الأول، فمقال حدّد نطاق أول مهمة للوكيل يشرح كيف تختار مهمة لن تُحرجك، ومقال تحويل موجز إلى ملاحم ومهام يشرح من أين تأتي التذاكر أصلًا.

ابدأ بواحدة. خذ الخطأ التالي الذي كنت ستُسنِده، وأضف سطر النطاق وشرط التوقف ومعرّف التصعيد، ثم اقرأ الفرق الذي يعود إليك. إن بقي أحد عشر ملفًا، فالتذكرة ما زالت تخمّن نيابةً عنك.