التعليمات

في كل مرة يبدأ فيها OpenCode جلسة جديدة، يبحث عن ملف اسمه AGENTS.md ويقرأ التعليمات التي كتبتها فيه. فكّر فيه كمجموعة أوامر دائمة لمساعدك الذكي — تفضيلات وقواعد وسياق تنطبق على كل ما يفعله.

برز AGENTS.md بوصفه أقرب شيء إلى معيار صناعي لملفات تعليمات الذكاء الاصطناعي. كثير من أدوات البرمجة بالذكاء الاصطناعي — وليس OpenCode وحده — تبحث عن ملف بهذا الاسم وتستخدم محتواه تعليمات دائمة. بكتابة AGENTS.md، تنشئ شيئًا قابلًا للنقل يعمل عبر الأدوات.

العام مقابل المشروع

هناك نوعان من ملفات AGENTS.md:

• عام (~/.config/opencode/AGENTS.md) — ينطبق على كل جلسة OpenCode على جهازك. هذا ملف تفضيلاتك الشخصية. لا يُودَع في Git ولا يُشارك مع أحد.
• مشروع (AGENTS.md في المجلد الجذر للمشروع) — ينطبق فقط عندما تعمل في ذلك المشروع. هذا عادة تودعه في Git حتى يستفيد فريقك كله من التعليمات نفسها.

يمكن أن يوجد الاثنان في الوقت نفسه. وعندما يحدث ذلك، يقرأ OpenCode كليهما — القواعد العامة أولًا، ثم قواعد المشروع فوقها.

في هذا الدرس، ننشئ الملف العام.

إنشاء ملف AGENTS.md الخاص بك

سينشئ OpenCode الملف ويملؤه بمحتوى ابتدائي. وافق على أي مطالبات صلاحيات تظهر.

ماذا تضع فيه

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

## About me

- My name is Ren. I'm a frontend developer based in Melbourne.
- My GitHub username is `rendev` and my email is `ren@example.com`.
- I primarily work in TypeScript and Python.

## Communication

- Be concise. Don't oversell changes or use fancy words like
  "comprehensive", "utilize", "streamline", or "leverage".
- Never use em dashes. Use commas, colons, or separate sentences instead.
- If your last message included URLs, list them at the end so I can
  open them easily.

## Writing

- When writing pull request descriptions, start with "This PR..." and
  keep it to 2-3 sentences.
- When writing markdown, avoid headings smaller than H2 and don't
  use bold for emphasis.

## Working with Git

- Always use semantic commit prefixes (feat:, fix:, docs:, etc.).
- Never push to the main branch. Always push to a feature branch.
- Run the project's lint script before committing, if one exists.

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

عدّله في أي وقت

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

مثلًا:

Add a rule to my global AGENTS.md: always use semantic commit messages when making git commits.

تهيئة AGENTS.md للمشروع

عندما تبدأ العمل على مشروع مع OpenCode، يمكنك توليد AGENTS.md خاص بالمشروع باستخدام الأمر /init. يمسح هذا الأمر قاعدة شيفرتك وينشئ AGENTS.md يصف بنية مشروعك وأعرافه ومكدسه التقني.

/init

ملف AGENTS.md الخاص بالمشروع معدّ ليُودَع في Git. يساعد OpenCode (وجلسات OpenCode لدى زملائك) على فهم المشروع بشكل أفضل.

لمزيد من التفاصيل، راجع وثائق القواعد.

عندما يوجد AGENTS.md العام لديك في ~/.config/opencode/AGENTS.md، يكتمل هذا الدرس.