دليل تشغيل أدوات البرمجة بالذكاء الاصطناعي دون تعارض

هذا الدليل يشرح كيف تعمل أربع أدوات معًا على مشروع واحد دون أن تتعارض تعليماتها أو إعداداتها أو أدواتها:

Claude Code
Google Antigravity
OpenCode
OpenAI Codex CLI

ملاحظة مهمة: هذه الأدوات تعمل محليًا على جهازك أو داخل بيئة التطوير، ولا تعمل داخل صفحة Hugging Face نفسها. لذلك يقوم هذا الـ Space بدور المرجع والتوثيق فقط. لا يحتاج أي مفتاح API هنا، ولا تُرفع إليه أي أسرار.

1. المبدأ الأساسي: مصدر واحد للحقيقة

الخطأ الأشهر هو كتابة نفس التعليمات في أربعة ملفات مختلفة. مع مرور الوقت تختلف النسخ، ويتصرف كل وكيل بطريقة مختلفة.

الحل:

الطبقة	الملف	من يقرؤه	المحتوى
مشتركة	`AGENTS.md` في جذر المشروع	الأدوات الأربع	القواعد، أوامر البناء والاختبار، الهيكلية، ممنوعات المشروع
Claude Code	`CLAUDE.md`	Claude Code	سطر واحد يستورد `AGENTS.md` + ملاحظات خاصة بـ Claude فقط
Antigravity	`GEMINI.md` أو `.agents/rules/`	Antigravity	سطر واحد يحيل إلى `AGENTS.md` + قواعد خاصة بـ Antigravity
OpenCode	`opencode.json`	OpenCode	إعداد الأداة والنماذج والصلاحيات
Codex	`~/.codex/config.toml` و `AGENTS.md`	Codex	إعداد الأداة والصلاحيات وخوادم MCP

القاعدة الذهبية: أي تعليمة تخص المشروع تُكتب مرة واحدة فقط في AGENTS.md.

2. أين يوجد كل ملف إعداد؟

2.1 Claude Code

~/.claude/CLAUDE.md: تعليمات عامة لكل المشاريع.
CLAUDE.md في جذر المشروع: تعليمات المشروع.
.claude/settings.json: صلاحيات وإعدادات مُلزِمة يتم تطبيقها سواء التزم بها النموذج أم لا. يُرفع إلى Git.
.claude/settings.local.json: إعدادات شخصية. لا يُرفع إلى Git.
.mcp.json في جذر المشروع (وليس داخل .claude/): خوادم MCP الخاصة بالمشروع. يُرفع إلى Git.

الفرق الجوهري: CLAUDE.md يُقرأ كإرشاد يمكن للنموذج أن يتجاهله، أما settings.json فيُطبَّق كقيد (مرجع). لذلك تُكتب القواعد الصارمة في settings.json وليس في CLAUDE.md.

ويُنصح بإبقاء CLAUDE.md قصيرًا، أقل من حوالي 300 سطر، لأن الإفراط في التعليمات يجعل النموذج يتجاهلها جميعًا (مرجع).

2.2 Google Antigravity

AGENTS.md في جذر المشروع: يقرؤه الوكيل عند بداية الجلسة (مرجع).
~/.gemini/GEMINI.md: قواعد عامة لكل المشاريع (مرجع).
.agents/rules/: قواعد خاصة بالمشروع.
.agents/workflows/: أوامر محفوظة تُستدعى بـ /.

⚠️ تحقق من مسارات Antigravity في وثائقها الرسمية قبل الاعتماد عليها، فقد تتغير أثناء مرحلة المعاينة العامة.

2.3 OpenCode

opencode.json في جذر المشروع أو ~/.config/opencode/opencode.json للإعداد العام.
AGENTS.md: تعليمات المشروع. يحمّل OpenCode ملفات AGENTS.md من مجلد العمل صعودًا حتى جذر المشروع، إضافة إلى الملف العام ~/.config/opencode/AGENTS.md (مرجع).
ترتيب الأولوية: إذا وُجد AGENTS.md فلن يُستخدم CLAUDE.md في المجلد نفسه، لأن أول ملف مطابق يفوز ضمن كل فئة (مرجع).

⚠️ توجد اختلافات بين إصدارات OpenCode. الإصدار 2 يتعرف على AGENTS.md فقط ولا يستخدم CLAUDE.md احتياطيًا (مرجع). لذلك نستخدم AGENTS.md دائمًا.

2.4 OpenAI Codex CLI

~/.codex/config.toml: الإعداد العام، ومنه النموذج وسياسة الموافقة ووضع الصندوق الرملي وخوادم MCP (مرجع).
~/.codex/AGENTS.override.md و ~/.codex/AGENTS.md: تعليمات عامة.
AGENTS.md في جذر المشروع: يتم قراءة الملف الأقرب إلى الملف المعدَّل.
[projects."/path/to/repo"] trust_level = "trusted": يحدد أن المشروع موثوق.
الحد الافتراضي لقراءة AGENTS.md هو 32 KiB، لذلك يُفضَّل إبقاؤه أقل من ذلك (مرجع).

3. قالب `AGENTS.md` المشترك

ضع هذا الملف في جذر المشروع، ثم عدّله حسب مشروعك:

# AGENTS.md

## نظرة عامة على المشروع
- الغرض: <اكتب الغرض في سطر واحد>
- اللغة والإطار: <مثال: TypeScript + Next.js 16>
- قاعدة البيانات: <مثال: PostgreSQL عبر Prisma>

## أوامر التشغيل
- التثبيت: `<npm ci>`
- التطوير: `<npm run dev>`
- البناء: `<npm run build>`
- الاختبار: `<npm test>`
- الفحص اللغوي: `<npm run lint>`

## قواعد البرمجة
- اتبع أسلوب التنسيق الموجود في المشروع.
- لا تعدّل الملفات المولَّدة تلقائيًا مباشرة.
- أضف اختبارًا لكل ميزة جديدة أو إصلاح خطأ.

## حدود واضحة
- لا تكتب مفاتيح API أو كلمات مرور أو ملفات `.env` داخل الكود.
- لا تُنفِّذ `git push` أو تغيّر الفرع الرئيسي دون طلب صريح.
- لا تعدّل ملفات الهجرة (migrations) الموجودة؛ أنشئ ملفًا جديدًا.

## التحقق قبل إنهاء أي مهمة
1. شغّل الاختبارات.
2. شغّل الفحص اللغوي.
3. لخّص ما تغيّر وما الذي لم يُختبر.

ملف الربط الخاص بـ Claude Code (`CLAUDE.md`)

@AGENTS.md

## خاص بـ Claude Code
- استخدم وضع التخطيط (plan mode) للمهام التي تغيّر أكثر من ثلاثة ملفات.

ملف الربط الخاص بـ Antigravity (`GEMINI.md`)

Follow all project rules defined in AGENTS.md at the repository root.

## Antigravity-specific
- Use the Planning mode for multi-file changes.

تنبيه: استخدام @AGENTS.md داخل CLAUDE.md مدعوم في Claude Code. أما GEMINI.md فالأفضل فيه نسخ محتوى AGENTS.md أو استخدام رابط رمزي (symlink) إن كان نظامك يدعمه. تحقق من ذلك عمليًا في أداتك.

إنشاء الروابط الرمزية (Linux / macOS)

ln -s AGENTS.md CLAUDE.md   # إن أردت أن يكون الملفان متطابقين تمامًا
ln -s AGENTS.md GEMINI.md

على Windows استخدم نسخ الملف بدل الرابط الرمزي، لأن الروابط الرمزية غالبًا تحتاج صلاحيات خاصة.

4. إعداد الأدوات دون تكرار

4.1 خوادم MCP: عرّفها مرة واحدة لكل أداة

لا تحاول مزامنة إعدادات MCP تلقائيًا بين الأدوات. عرّف كل خادم في المكان الخاص بكل أداة فقط:

Claude Code (.mcp.json في جذر المشروع):

{
  "mcpServers": {
    "docs": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.docs]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["CONTEXT7_API_KEY"]   # يمرر المتغير من البيئة دون كتابته في الملف
tool_timeout_sec = 60

OpenCode (opencode.json): عرّف الخادم في قسم mcp وفق توثيق OpenCode الحالي.

لا تضع المفاتيح السرية في أي ملف إعداد يُرفع إلى Git. استخدم متغيرات البيئة دائمًا.

4.2 الصلاحيات: لا تنسخها بين الأدوات

كل أداة لها نظام صلاحيات مختلف. اضبط الحد الأدنى في كل أداة:

Claude Code: permissions.deny في .claude/settings.json، مثل منع قراءة .env.
Codex: approval_policy و sandbox_mode في config.toml.
OpenCode: permission داخل تعريف الوكيل في opencode.json.
Antigravity: اضبط مستوى الاستقلالية من إعداداتها، وابدأ بوضع المراجعة.

4.3 ملف `.gitignore` المقترح

.env
.env.*
.claude/settings.local.json
CLAUDE.local.md
.codex/*.local.*

5. قواعد تمنع التعارض

مالك واحد لكل ملف. لا تكتب في AGENTS.md من أداتين في الوقت نفسه.
لا تشغّل وكيلين على الملفات نفسها في آنٍ واحد. استخدم فروعًا (branches) منفصلة أو git worktree.
لا تكرر القواعد. إذا وُجدت في AGENTS.md فلا تكررها في CLAUDE.md أو GEMINI.md.
القيود الصارمة في الإعدادات، والإرشادات في Markdown.
راجع التغييرات بعد كل جلسة باستخدام git diff قبل الالتزام.
أبقِ AGENTS.md قصيرًا ودقيقًا. الملفات الطويلة تُقرأ جزئيًا أو تُهمل.
ضع القواعد الخاصة بمجلد معين في AGENTS.md داخل ذلك المجلد، فالملف الأقرب هو الذي يُطبَّق في الغالب.

6. قائمة فحص قبل الاعتماد

يوجد AGENTS.md واحد في جذر المشروع.
CLAUDE.md و GEMINI.md لا يحتويان إلا على إحالة أو تعليمات خاصة بالأداة.
لا توجد مفاتيح API في أي ملف مرفوع إلى Git.
.mcp.json موجود في جذر المشروع وليس داخل .claude/.
~/.codex/config.toml يحتوي على trust_level للمشروع.
كل أداة تقرأ AGENTS.md (اسألها: "ما القواعد التي تتبعها؟").
أوامر build و test و lint تعمل من الطرفية.
حجم AGENTS.md أقل من 32 KiB.

7. أين يُشغَّل كل شيء؟

المكوّن	المكان المقترح
هذا الدليل	Hugging Face Space (توثيق)
الأدوات الأربع	جهازك أو بيئة التطوير السحابية
ملفات `AGENTS.md` و `CLAUDE.md` و `GEMINI.md`	مستودع المشروع على Git
مفاتيح API	متغيرات البيئة أو مدير الأسرار، وليست داخل الملفات

الخلاصة: الأفضل أن تبقى الأدوات محلية، ويكون المستودع هو مصدر الإعداد المشترك. رفعها إلى Hugging Face لا يضيف فائدة تُذكر، لأن الـ Space صفحة ويب وليس بيئة لتشغيل وكلاء البرمجة.