Claude لأعمال أوراكل: اختيار نموذج Claude 5 وتصميم الوكلاء

أصبح Claude عائلة من النماذج بأسعار مختلفة جدًا، والأدوات المحيطة به (Claude Code والوكلاء الفرعيون والمهارات وMCP) هي التي تحدد معظم النتيجة في مشروع أوراكل. هذا الدليل نقطة البداية: أي نموذج يناسب أي مهمة في أوراكل، وكم يكلّف، وكيف تصمّم إعداد وكلاء حول PL/SQL وAPEX وSQLcl. وهو يحيلك إلى الأدلة التفصيلية بدل تكرارها.

• تعديل تطبيق APEX كملفات بمساعدة وكيل: برمجة Oracle APEX مع Claude Code وAPEXlang.
• تشغيل عدة وكلاء كفريق مع مراجع وضبط للميزانية: كيف أبني تطبيقات أوراكل بفريق من وكلاء الذكاء الاصطناعي.
• الأفكار نفسها في GitHub Copilot: GitHub Copilot Enterprise لمطوّري أوراكل.

نماذج Claude 5 في لمحة

فكّر بمستويات القدرة لا بالأسماء، لأن الأسماء تتغير مع كل إصدار. الأسعار لكل مليون رمز (MTok)، مدخلات / مخرجات، من صفحة الأسعار لدى Anthropic وقت كتابة هذا الدليل (19 أكتوبر 2026). للنماذج الأربعة نافذة سياق بحجم مليون رمز.

أي نموذج لأي مهمة في أوراكل

ابدأ من المهمة لا من النموذج. عند التردد تقترح Anthropic البدء بـ Claude Opus 5.5 لمعظم أنواع العمل. وفي مشاريع أوراكل يوفّر التقسيم التالي المال دون خسارة في الجودة، لأن جزءًا كبيرًا من اليوم تعديلات صغيرة متكررة يكون فيها النموذج المتوازن أرخص بالنصف وأسرع:

• إعادة هيكلة حزمة PL/SQL كبيرة، أو تحليل وحدة Forms ضخمة قبل نقلها إلى APEX ← النموذج الكبير (Claude Opus 5.5) بجهد high. تحتاج هذه المهام إلى رؤية الحزمة أو الوحدة كاملة واتخاذ قرارات دقيقة كثيرة.
• أصعب الأعمال الطويلة (خطة تحديث تمتد أيامًا، أو فكّ تشابك مئات الحزم المترابطة) ← النموذج الأقدر (Claude Fable 5.1). سعره للرمز 2.5 ضعف Opus، فاستخدمه حيث يستحق التفكير الإضافي ثمنه.
• صفحات APEX اليومية، وتعديلات APEXlang، وتغييرات PL/SQL الصغيرة، ومراجعة الكود ← النموذج المتوازن (Claude Sonnet 5.5). سريع بما يكفي لتبقى في إيقاع العمل، وقوي بما يكفي لمعظم التعديلات.
• المهام الكثيرة المتكررة (توثيق مئات مشغّلات Forms، وتصنيف آلاف أسطر سجلات الأخطاء، ووسم الجداول) ← النموذج السريع الرخيص (Claude Haiku 5.5)، والأفضل عبر واجهة Message Batches.
• الوكلاء الفرعيون الذين يبحثون أو يسردون أو يلخّصون داخل تشغيل وكيل أكبر ← النموذج السريع أيضًا، ويحتفظ الوكيل القائد بالنموذج الأكبر.

إبقاء الفاتورة تحت السيطرة

ثلاث أدوات تهمّ في مشاريع أوراكل، حيث تكون الموجّهات كبيرة عادةً (تفريغ المخططات، وأجسام الحزم، وملفات Forms XML):

• التخزين المؤقت للسياق المتكرر. إن كان كل طلب يبدأ بتفريغ المخطط نفسه أو معيار الكتابة نفسه، فخزّنه مؤقتًا. القراءة من الذاكرة المؤقتة تكلّف جزءًا صغيرًا من سعر المدخلات (0.05 من السعر على Opus 5.5 وSonnet 5.5 وقت الكتابة)، والكتابة إليها تكلّف 1.25 ضعفًا لمدة البقاء الافتراضية البالغة 5 دقائق. مثال: مخطط من 200,000 رمز على Opus 5.5 يكلّف نحو 0.80 دولار لكل طلب دون تخزين، ونحو 1.00 دولار في أول مرة يُخزَّن فيها، ونحو 0.04 دولار عند كل إصابة. التخزين المؤقت مطابقة للبادئة، فأبقِ التفريغ متطابقًا حرفًا بحرف وضع السؤال المتغيّر بعده.
• Message Batches للمهام التي لا ينتظرها أحد. تعمل الدفعات بشكل غير متزامن بنصف السعر القياسي، ويتراكم الخصم مع التخزين المؤقت. كل طلب في الدفعة طلب واحد دون حلقة أدوات، لذا استخرج نص المشغّلات أو أسطر السجلات أولًا، ثم أرسل طلبًا لكل عنصر.
• انتبه لقفزة سعر Haiku. يكلّف Claude Haiku 5.5 خمسة أضعاف للرمز حين يتجاوز الموجّه 100,000 رمز، فأبقِ موجّهات المهام الجماعية صغيرة: مشغّل واحد أو دفعة سجلات واحدة لكل طلب.

استدعاء Claude من Python

للسكربتات وخطوط المعالجة (مراجعة ليلية للحزم المتغيّرة، أو مهمة دفعات على تصديرات المشغّلات)، استدعِ واجهة Claude API بحزمة Python الرسمية من Anthropic (pip install anthropic). يراجع هذا المثال جسم حزمة واحدة بالنموذج الكبير مع التفكير التكيّفي وجهد high. الاستجابة قائمة من كتل المحتوى، فاطبع كتل text فقط، وتحقّق من سبب التوقف أولًا:

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from the environment

with open("db/packages/order_api.pkb", encoding="utf-8") as f:
    package_body = f.read()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # low | medium | high | xhigh | max
    system="You are a senior Oracle PL/SQL reviewer. Report findings only; do not rewrite the package.",
    messages=[{
        "role": "user",
        "content": "Review this package body for: SQL built by string concatenation "
                   "instead of bind variables, WHEN OTHERS THEN NULL, COMMIT or ROLLBACK "
                   "inside reusable procedures, and row-by-row loops that could be one "
                   "SQL statement. For each finding give the line, the rule and a fix.\n\n"
                   + package_body,
    }],
)

if response.stop_reason == "refusal":
    print("The model declined this request.")
elif response.stop_reason == "max_tokens":
    print("The review was cut off at max_tokens. Raise max_tokens and run it again.")
else:
    for block in response.content:
        if block.type == "text":
            print(block.text)

في Claude Opus 5.5 التفكير مفعّل دائمًا، لذا فإن thinking={"type": "adaptive"} يصرّح بالسلوك الافتراضي فقط؛ والجهد هو الإعداد الذي تضبطه. غيّر model إلى claude-sonnet-5-5 أو claude-haiku-5-5 لتقارن التكلفة والجودة على حزمك أنت. إن كان سبب التوقف refusal فقد رُفض الطلب ولا يوجد نص إجابة لقراءته. وإن كان max_tokens فقد انقطعت الإجابة: التفكير يُحتسب ضمن max_tokens، لذا قد تستنفد حزمة طويلة بجهد مرتفع الحد قبل اكتمال المراجعة. ارفع max_tokens وأعد التشغيل.

أربع طرق لبناء وكيل لأوراكل

تقدّم Anthropic أربعة مستويات، من أكثرها تحكمًا إلى أقلها جهدًا:

1. واجهة Claude API مع حلقتك الخاصة. ترسل الرسائل، وتنفّذ الأدوات التي يطلبها Claude (مثل دالة تنفّذ استعلامًا)، وتعيد النتائج إليه. تحكم كامل وكود أكثر.
2. Tool Runner في حزمة Anthropic SDK (نسخة تجريبية). تعرّف الأدوات، وتدير الحزمة الحلقة نيابةً عنك.
3. Managed Agents (نسخة تجريبية). تستضيف Anthropic حلقة الوكيل، ويمكنها استضافة البيئة المعزولة أيضًا. ولا يلزم كشف قاعدة بياناتك: فالبيئة المعزولة المستضافة ذاتيًا تشغّل الأدوات على عامل داخل شبكتك لا يحتاج إلا إلى اتصال HTTPS صادر، وأنفاق MCP تتيح لـ Anthropic الوصول إلى خادم MCP خاص. لكن مدخلات الأدوات ونتائجها تمرّ عبر Anthropic ليقرأها النموذج، فاقصر ذلك على بيانات الاختبار.
4. Claude Agent SDK. هو Claude Code كمكتبة: الأدوات والصلاحيات ودعم MCP نفسها، تعمل على جهازك أو خادمك.

للتطوير اليومي يكفي Claude Code نفسه عادةً. يُعدّه باقي هذا الدليل لمستودع أوراكل.

إعداد Claude Code لمستودع أوراكل

1. اكتب القواعد في CLAUDE.md

يحمّل Claude Code الملف CLAUDE.md (في جذر المستودع أو في .claude/CLAUDE.md) مع بداية كل جلسة. نفّذ /init لتحصل على مسودة أولى، ثم أضف قواعد أوراكل التي لا يستطيع Claude اكتشافها من الكود. توصي Anthropic بإبقاء كل ملف تحت 200 سطر؛ والقواعد القصيرة القابلة للتحقق تعمل أفضل:

# Oracle project rules

## Stack
- Oracle AI Database 26ai. Local development uses the Free container, service FREEPDB1.
- PL/SQL packages live in db/packages as .pks (spec) and .pkb (body) files.
- The APEX app lives in apex/my-app as APEXlang .apx files.
- SQLcl is the only deploy tool.

## PL/SQL
- Bind variables only. Never concatenate values into a SQL string.
- No COMMIT or ROLLBACK inside reusable package procedures; the caller owns the transaction.
- Never write WHEN OTHERS THEN NULL. Log the error and re-raise.
- Keep public signatures in .pks files unchanged unless I ask.

## APEXlang
- Never rename existing components or change their Static IDs.
- After editing .apx files, tell me to run apex validate -input apex/my-app in SQLcl.

## Database access
- Use only the saved SQLcl connection ora26ai_dev (a development schema).
- Show me every DDL or DML statement and wait for my approval before running it.

ملف CLAUDE.md توجيه لا إلزام. وكل ما يجب ألا يحدث أبدًا مكانه قواعد الصلاحيات (الخطوة 5).

2. أضف وكيلًا فرعيًا لمراجعة PL/SQL للقراءة فقط

الوكيل الفرعي نسخة منفصلة من Claude بتعليماتها وأدواتها ونموذجها. احفظ الملف التالي باسم .claude/agents/plsql-reviewer.md. يمنحه سطر tools أدوات قراءة فقط، فيستطيع الإبلاغ عن المشكلات دون أن يغيّر أي ملف، ويشغّله model: opus على النموذج الكبير بينما تبقى جلستك الرئيسية على Sonnet:

---
name: plsql-reviewer
description: Reviews PL/SQL changes for bind variables, exception handling and transaction control. Use after files in db/packages change. Read-only.
tools: Read, Glob, Grep
model: opus
---
You review Oracle PL/SQL. You cannot edit files.
For each finding give the file, the line, the rule from CLAUDE.md it breaks
and a corrected snippet. If you find nothing, say so in one line.

اطلب من Claude «استخدم الوكيل الفرعي plsql-reviewer على التغييرات في db/packages»، أو دعه يفوّض المهمة بنفسه حين يطابق الوصف. لا يرى المراجع إلا النتيجة لا تفكير الكاتب، وهذا هو المقصود؛ ويوضح دليل فريق الوكلاء متى تستدعيه.

3. حمّل مهارات أوراكل

المهارات مجلدات فيها ملف SKILL.md يحمّلها Claude فقط حين تحتاجها المهمة، فلا تملأ السياق. يضم مستودع Harby المجاني oracle-ai-skills (برخصة MIT) ثلاث مهارات: oracle-apex وplsql وforms-to-apex. ثبّتها لمستخدمك:

git clone https://github.com/Mohamedhrby/oracle-ai-skills
mkdir -p ~/.claude/skills
cp -r oracle-ai-skills/skills/* ~/.claude/skills/

ولمشاركتها مع فريقك بدلًا من ذلك، انسخ المجلدات إلى .claude/skills/ داخل المستودع. يستخدم Claude المهارة حين يطابق طلبك وصفها، أو يمكنك استدعاؤها مباشرة بالأمر /plsql. أما مهارة APEXlang من Oracle نفسها فيغطيها دليل APEXlang.

4. اتصل بقاعدة البيانات عبر خادم SQLcl MCP

يتضمن SQLcl خادم MCP يشغّله Claude Code بالأمر sql -mcp. ولا يستطيع استخدام إلا الاتصالات المحفوظة في SQLcl مع كلمة مرورها. احفظ اتصالًا بمخطط تطوير في FREEPDB1 المحلية (لا SYS ولا SYSTEM أبدًا)، ثم سجّل الخادم بالأمر claude mcp add. كل ما يأتي بعد -- هو الأمر الذي يشغّله Claude Code:

sql /nolog
SQL> conn -save ora26ai_dev -savepwd app_dev/<password>@//localhost:1521/FREEPDB1
SQL> exit

claude mcp add --transport stdio sqlcl -- /path/to/sqlcl/bin/sql -mcp

استبدل /path/to/sqlcl بمجلد SQLcl لديك. النطاق الافتراضي يخصّك أنت في هذا المشروع فقط؛ أضف --scope project لكتابة الإدخال في ملف .mcp.json مشترك بدلًا من ذلك. وعند تشغيله بهذه الطريقة يعمل SQLcl على مستوى التقييد 4، وهو الأشد: لا أوامر نظام ولا سكربتات. أبقِه كذلك. ويسرد دليل Copilot أدوات SQLcl MCP وجدول التدقيق الذي يكتب فيه SQLcl.

5. ضع أسوارًا لما يجب ألا يحدث أبدًا

ضع الحدود في .claude/settings.json، حيث تسري مهما قال الموجّه. تمنع هذه القواعد أدوات الملفات في Claude من قراءة .env ومجلد المحافظ، وترفض الصيغة المعتادة للأمر git push:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./wallets/**)",
      "Bash(git push *)"
    ]
  }
}

قواعد المنع ليست حدًا أمنيًا كاملًا. فقاعدة Bash تطابق نص الأمر، لذا لا تطابق دفعًا مكتوبًا بصيغة أخرى (مثل git -C . push)، ولا تغطي قاعدة Read سكربتًا يفتح الملف بنفسه. للفرض على مستوى نظام التشغيل فعّل العزل (sandboxing) في Claude Code، وأبقِ أسرار الإنتاج خارج الجهاز تمامًا.

لا تضف أدوات SQLcl (mcp__sqlcl__*) إلى قائمة السماح، ولا تختر «Yes, and don't ask again» في نوافذ موافقتها، لأن ذلك يحفظ قاعدة سماح. عندها يسألك Claude Code في وضع الصلاحيات الافتراضي (المسمّى Manual) قبل كل استدعاء، فترى SQL قبل تنفيذه. واستخدم وضع plan حين تريد من Claude أن يقرأ ويقترح فقط.

إلى أين بعد ذلك

• طبّق ذلك على تطبيق APEX: برمجة Oracle APEX مع Claude Code وAPEXlang.
• توسّع إلى عدة وكلاء مع مراجع واختبارات مطابقة وخط ميزانية: كيف أبني تطبيقات أوراكل بفريق من وكلاء الذكاء الاصطناعي.
• استخدم Claude داخل APEX نفسه: مساعد APEX الذكي.

اختبر فهمك