ورقة مرجعية

ورقة مرجعية لهارنس الوكيل: المكوّنات والملفات والمشكلات الشائعة وقائمة التشغيل

آخر تحديث: · Skillaria.Top

يتكون هارنس الوكيل من خمسة أنظمة فرعية: التعليمات والأدوات والبيئة والحالة والتغذية الراجعة. وأدنى مجموعة من الملفات تشمل AGENTS.md كموجّه قصير، وسكربت التحقق (make check وverify.sh)، وملف التقدم، وقائمة ميزات بحالات. وحالة «الاكتمال» يضعها السكربت، لا الوكيل.

الأنظمة الفرعية الخمسة للهارنس

النظام الفرعيالمعنىالمخرجاتعلامة التعطل
التعليماتما ينبغي للوكيل معرفته عن المشروعAGENTS.md / CLAUDE.md، وskills، وdocs/، وADRيخرق أعرافًا معروفة
الأدواتما يستطيع الوكيل فعلهshell، والاختبارات، والمدقق، والمتصفح، وخوادم MCP«يريد لكنه لا يستطيع»
البيئةأين يعمل الوكيلملفات القفل، وDocker/devcontainer، وgit worktree، وصندوق الرمل، وinit.shكل جلسة تبدأ بإصلاح البيئة
الحالةما يبقى بعد إعادة التشغيلPROGRESS.md، وDECISIONS.md، وfeature_list.json، وcommitsالجلسة الجديدة لا تعرف أين توقف العمل
التغذية الراجعةكيف يعلم الوكيل أنه أخطأmake check، وE2E، والخطافات، وفحص المعمارية، والمُقيِّم«اكتمل» والميزة لا تعمل

ترتيب البناء من الصفر: التغذية الراجعة ← التعليمات ← الحالة ← البيئة ← الأدوات.

ملفات الهارنس

الملفالغرضالقاعدة
AGENTS.md / CLAUDE.mdنقطة الدخول: ما هو المشروع، وكيف يُشغَّل، وكيف يُتحقَّق منهموجّه قصير (نحو 80 سطرًا)، مع روابط للوثائق مشروطة بـ«متى تُقرأ»
docs/*.mdتفاصيل كل موضوعتُقرأ عند الحاجة، لا تُحمَّل كلها
.claude/skills/*/SKILL.mdإجراءات متكررة (النشر، والمراجعة)تُحمَّل عندما تتطابق المهمة مع الوصف
PROGRESS.mdالحالة، والمنجَز، والعوائق، والخطوة التاليةيُحدَّث في نهاية كل جلسة
DECISIONS.mdالقرار، والسبب، والخيارات المرفوضةيُسجَّل المسار، لا النتيجة فقط
feature_list.jsonالميزات: behavior، وverification، وstateميزة واحدة فقط active (WIP=1)
scripts/verify.shيتحقق من الميزة ويضعها passingالوحيد الذي يضع passing، مع SHA للـ commit
scripts/arch-check.shيفحص حدود المعماريةرمز خروج 1، مع WHY وFIX في المخرجات
scripts/init.shيفحص البيئة قبل العملالبيئة سليمة، وشجرة git نظيفة، وmake check أخضر، وتوجد ميزة نشطة
sprint contractاتفاق على الميزة قبل كتابة الشيفرةضمن النطاق / خارج النطاق / أسئلة مفتوحة
.claude/settings.jsonصلاحيات Claude Code وخطافاتهفحوص عند الأحداث، لا تعتمد على ذاكرة الوكيل

هيكل AGENTS.md

# المشروع: الواجهة الخلفية للدفع (FastAPI، PostgreSQL)

## التشغيل
docker compose up -d && ./scripts/init.sh

## التحقق
make check   # المدقق، والأنواع، واختبارات الوحدة، وarch-check
make e2e     # سيناريوهات من طرف إلى طرف

## تعريف الإنجاز
- ينتهي make check وmake e2e برمز 0
- تُوضع الميزة passing عبر السكربت scripts/verify.sh
- يكون PROGRESS.md محدَّثًا

## MUST
- الوصول إلى قاعدة البيانات عبر المستودعات فقط
- الأسرار تُقرأ من متغيرات البيئة فقط

## الوثائق
- docs/payments.md — عندما تتعلق المهمة بالدفع والاسترداد
- docs/migrations.md — عندما يتغير مخطط قاعدة البيانات

حالات الميزة

الحالةالمعنىمن يغيّرها
pendingفي الانتظارالمخطِّط
activeقيد العمل (واحدة فقط في كل مرة)الوكيل عند بدء العمل
passingاجتازت التحققverify.sh وحده
blockedتحتاج قرارًا بشريًا، مع ذكر السببالوكيل

مستويات التحقق

المستوىالمحتوىمتى
1المدقق، والأنواعدائمًا
2اختبارات الوحدة والتكاملدائمًا
3اختبارات E2Eعند تغيير يمس أكثر من طبقة؛ وقبل كلمة «اكتمل»
4arch-checkعند ظهور استيراد جديد عبر الطبقات

لا يحق إعلان «اكتمل» إلا بعد اجتياز أعلى مستوى. الاختبارات الوحدوية الخضراء ليست اكتمالًا.

تحويل القواعد إلى آليات

المستوىالأداةالتكلفة
حارس grepسكربت يبحث عن نمط ويطبع WHY/FIXدقائق
قاعدة مدققimport-linter (Python)، وdependency-cruiser، وeslint-plugin-boundaries (JS/TS)نحو ساعة
اختبار معمارياختبار في CI يفشل عند كسر الطبقاتأكثر، لكنه مرئي في make check
 
#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: طبقة الخدمات لا تصل إلى قاعدة البيانات مباشرة"
  echo "FIX: استخدم المستودع من app/repositories/"
  fail=1
fi
exit $fail

المشكلات الشائعة وحلولها

المشكلةالنظام الفرعيالحل
القاعدة في CLAUDE.md لا تُحترمالتعليماتاختصار الملف، وتحويل القاعدة إلى فحص أو خطاف
الوكيل لا يستطيع تشغيل الاختباراتالأدواتالسماح بالأمر، وتثبيت التبعيات في الصورة
سلوك مختلف بين الأجهزةالبيئةملفات القفل، وDocker/devcontainer، وتثبيت إصدار بيئة التشغيل
فقدان الذاكرة بين الجلساتالحالةPROGRESS.md، وملاحظة تسليم الجلسة، والقراءة عند البداية
بدأت ثلاث ميزات ولم تكتمل أي منهاالحالةWIP=1 في feature_list.json
«اكتمل» والميزة لا تعملالتغذية الراجعةتعريف الإنجاز، وE2E، وverify.sh، ومُقيِّم مستقل
الاختبارات الوحدوية خضراء والميزة معطلةالتغذية الراجعةE2E بقاعدة بيانات وإعدادات حقيقية
يكرر الوكيل أنماطًا سيئةالتغذية الراجعةarch-check من اليوم الأول
لا يُعرف ما الذي فعله الوكيلالحالةcommits صغيرة، وتقرير في PROGRESS.md، وتسجيل في DECISIONS.md
الوكيل كسر البيئة بين ليلة وضحاهاالبيئةصندوق رمل، وgit worktree، ونقاط حفظ، والتراجع عبر init.sh
التعليق نفسه في المراجعة ظهر مرتينالهارنس كلهتحويله إلى فحص في make check، وحذفه من التعليمات

الأدوار في المهام الطويلة

الدوريتولىلا يتولى
المخطِّطميزات مع معايير قبوللا يكتب شيفرة
المولِّدينفّذ ميزة واحدة ويشغّل الاختباراتلا يقرر الإنجاز
المُقيِّمحكم وفق المعايير، مع الاستشهاد بملف أو سطر أو سجللا يرى استدلال المولِّد
الدمجيُنفَّذ عندما تكون المراجعة passهذه شيفرة، لا وكيل

ميزانية العمل المستقل

  • هدف يُكتب في جملة واحدة (مثلًا: جعل كل الميزات passing).
  • WIP=1، وحدود زمن ومحاولات لكل ميزة.
  • المؤشر يتزايد باطراد، وأي تراجع يعني تراجعًا فوريًا.
  • الترحيلات والبنية التحتية والأموال تُحال إلى إنسان.
  • بعد عدة إخفاقات في المراجعة، تبدأ الميزة من جديد بسياق نظيف.

قائمة تشغيل الوكيل

  1. يوجد AGENTS.md: التقنيات، وطريقة التشغيل، وأوامر التحقق، وتعريف الإنجاز.
  2. ينجح make check على نسخة نظيفة من المستودع.
  3. البيئة قابلة للتكرار: ملفات قفل، وDocker أو devcontainer.
  4. للوكيل الصلاحيات للأوامر اللازمة، والأوامر الخطرة ممنوعة أو داخل صندوق رمل.
  5. يوجد اختبار E2E واحد على الأقل للسيناريو الرئيسي.
  6. يوجد PROGRESS.md، والقاعدة تقضي بقراءته عند بداية الجلسة.
  7. قائمة الميزات فيها حالات، والنشطة واحدة فقط.
  8. حالة passing يضعها السكربت.
  9. رسائل الفحوص تتضمن WHY وFIX.
  10. للمهمة معايير قبول، وحدود نطاق واضحة.
  11. معروف ما الذي يحتاج قرارًا بشريًا.
  12. قبل التغييرات، حُسبت فجوة التحقق لتكون مرجعًا للمقارنة لاحقًا.

مقاييس الهارنس

المقياسطريقة الحساب
Verification gapنسبة المهام من 10 التي أُعلن فيها «اكتمل» دون تأكيد التحقق
MTTRالزمن من وقوع العطل حتى استعادة حالة صالحة للعمل
البدء الباردهل تجيب جلسة جديدة عن «أين نحن، وما التالي؟» دون تخمين
الاستئصال (ablation)الانخفاض عند إزالة نظام فرعي واحد على مجموعة مهام ثابتة

الخلاصة

الهارنس دورة مغلقة وليس ملفًا واحدًا: تعليمات، وأدوات، وبيئة، وحالة، وتغذية راجعة. ابدأ بالتحقق، واجعل AGENTS.md قصيرًا، واترك حكم الإنجاز للسكربت، وراجع الهارنس بانتظام. وكل ذلك يتجمع في دورة هندسة الهارنس ضمن هارنس متكامل على مشروع حقيقي.

الأسئلة الشائعة

ما الفرق بين AGENTS.md وCLAUDE.md؟

الغرض واحد، وكلاهما ملف تعليمات للوكيل. يقرأ Claude Code ملف CLAUDE.md، أما AGENTS.md فصيغة مشتركة بين وكلاء متعددين، ويمكن الإشارة إليه من CLAUDE.md.

كم يجب أن يكون طول AGENTS.md؟

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

هل يحتاج مشروع صغير إلى feature_list.json؟

لا يحتاجه في التعديلات المنفردة الصغيرة. تظهر فائدته عندما يعمل الوكيل على ميزات متعددة متتالية أو عبر عدة جلسات.

أين أحفظ الأسرار التي يحتاجها الوكيل؟

في متغيرات البيئة أو مدير الأسرار، لا في ملفات التعليمات ولا في الشيفرة. تمنح الوكيل وصولًا إلى البيئة، لا القيم المكتوبة في النص.

تعلّم هذا الموضوع بالفيديو

يُشرح هذا الموضوع بالتفصيل مع التطبيق العملي في دورة «Harness Engineering: инженерия надёжности AI-агентов».

الانتقال إلى الدورة