بناء ملف AGENTS.md خطوة بخطوة

ملف AGENTS.md هو ملف Markdown واحد في جذر المستودع (repo root). يخبر وكلاء البرمجة بالذكاء الاصطناعي (AI coding agents) بكيفية العمل، حيث يغطي خطوات البناء، والاختبارات، والقواعد.

اتبع هذه الخطوات لإنشاء ملف لمشروع Python FastAPI.

  1. حدد التقنيات المستخدمة (the stack) ابدأ بجملة واحدة. أخبر الوكيل باللغة، وإطار العمل، وقاعدة البيانات. مثال: A URL shortener API in Python using FastAPI, SQLite, and pytest.

  2. قدم أوامر الإعداد أعطِ الوكيل أوامر حقيقية لتشغيلها. لا تستخدم نصوصاً مؤقتة (placeholders).

  • الإعداد: python -m venv .venv && source .venv/bin/activate
  • التشغيل: uvicorn app.main:app --reload
  1. حدد معايير الاختبار هذا أمر حيوي. يستخدم الوكيل الاختبارات للتحقق من عمله الخاص.
  • تشغيل pytest
  • تشغيل ruff check
  • تشغيل mypy
  1. حدد هيكلية المشروع قم بإدراج المجلدات حتى لا يضطر الوكيل للبحث في كل ملف.
  • app/main.py: معالجات المسارات (route handlers)
  • app/db.py: الوصول إلى SQLite
  • migrations/: ملفات SQL المُنشأة (لا تقم بتعديلها)
  1. حدد الاصطلاحات (Conventions) كن محددًا. القواعد الغامضة لا فائدة منها.
  • استخدم Pydantic لجميع عمليات التحقق من المدخلات.
  • استخدم HTTPException لأخطاء العميل.
  • قم بتحديد الأنواع (Type everything) لكل شيء للحفاظ على نظافة mypy.
  1. اذكر "الممنوعات" امنع الأخطاء من خلال وضع حدود صارمة.
  • لا تقم بتعديل ملفات migrations يدوياً.
  • لا تقم بعمل commit مباشرة إلى main.
  • لا تقم أبداً بتشغيل سكربتات البيانات الأولية (seed scripts) على قواعد بيانات غير محلية.

لماذا ينجح هذا؟ عندما تعطي وكيل ذكاء اصطناعي مهمة مثل "Add a DELETE endpoint"، فإنه يقرأ هذا الملف أولاً.

باستخدام ملف AGENTS.md، يقوم الوكيل بـ:

  • معرفة المكان الدقيق لإضافة الكود.
  • استخدام أدوات الاختبار الخاصة بك.
  • اتباع أسلوبك دون طرح أسئلة.
  • فتح فرع (branch) بدلاً من كسر الكود الأساسي (main code).

بدون هذا الملف، سيقوم الوكيل بالتخمين. قد يستخدم مشغل اختبار خاطئ أو يعدل ملفات لا ينبغي له لمسها.

تعامل مع هذا الملف كأنه كود برمجي. إذا تغير سير عملك (workflow)، فقم بتحديث الملف فوراً. الملف غير المحدث يؤدي إلى أخطاء.

المصدر: https://dev.to/wolfejam/agentsmd-hands-on-build-one-step-by-step-and-watch-an-agent-use-it-3g27

مجتمع تعليمي اختياري: https://t.me/GyaanSetuAi