لماذا يتجاهل وكيل البرمجة تعليماتك؟

لماذا تتجاهل وكلاء البرمجة تعليماتك

يتجاهل وكلاء البرمجة تعليماتك لأربعة أسباب، ولا يتعلق أيٌّ منها بكونك كنت مهذباً أكثر من اللازم. قد لا تكون القاعدة موجودة أصلاً في نافذة السياق. وقد تكون غامضة إلى درجة تمنع التحقق من أي إجراء مقارنةً بها. وقد يتعارض معها شيء آخر في السياق، وغالباً ما يكون ذلك هو الكود الذي قرأه الوكيل للتو. أو قد تظل القاعدة محمّلة، لكنها تكون بعيدة جداً عن الدور الحالي، فيعمل الوكيل استناداً إلى ما هو قريب منه.

لكل سبب إصلاحه الخاص، لذلك تتمثل المهمة الأولى في التمييز بينها. لا تمثل الأحرف الكبيرة وكلمة IMPORTANT تشخيصاً. تستخدم الآليات أدناه Claude Code مثالاً تطبيقياً، لأن سلوكه في تحميل السياق وضغطه موثّق بالتفصيل حتى August 2026. تختلف الأدوات الأخرى في التفاصيل، لكنها تتصرف بالطريقة نفسها عموماً.

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

ملف التعليمات رسالة وليس إعداداً

ملف التعليمات ليس ملف إعدادات. لا يقرأ أي مكوّن في وقت التشغيل CLAUDE.md ويفرضه. يقرأ الـharness الملف من القرص ويلصق النص في المحادثة. في Claude Code، يُرسل هذا المحتوى في رسالة مستخدم توضع بعد system prompt، ولذلك يرى النموذج قواعدك بالطريقة نفسها التي يرى بها أي نص آخر كتبته.

ينتج عن ذلك أثر غير مريح. تتنافس قواعدك مع كل جزء آخر من النص في نافذة السياق على قدم المساواة. القاعدة ادعاء. أما الملف الذي فتحه الـagent للتو فهو دليل. عندما يتعارضان، يفوز الدليل غالباً، ولا يظهر أي خطأ لأن شيئاً لم يجرِ بشكل خاطئ من وجهة نظر النموذج.

توضح الوثائق الرسمية ذلك صراحةً: تُعامل ملفات التعليمات كسياق، ولا تُفرض بوصفها إعدادات. لمنع إجراء ما بغض النظر عما يقرره النموذج، تحتاج إلى hook، لا إلى جملة. احتفظ بهذه الفكرة. معظم الإصلاحات في نهاية هذا المنشور هي تطبيق لهذه الفكرة على حالة محددة.

ملفات التعليمات التي تُحمَّل ووقت تحميلها

يتنقل Claude Code صعوداً في شجرة الأدلة بدءاً من الدليل الذي شغّلته منه. يُحمِّل بالكامل عند بدء التشغيل كل ملف CLAUDE.md وكل ملف CLAUDE.local.md من جذر نظام الملفات حتى دليل العمل. وتُدمج هذه الملفات بهذا الترتيب، لذلك يُقرأ الملف الأقرب إلى الدليل الذي شغّلت منه الأمر أخيراً. وداخل الدليل نفسه، يُضاف ملف .local بعد الملف الرئيسي.

تعمل الملفات الموجودة في الأدلة الفرعية الواقعة أسفل دليل العمل بطريقة مختلفة. فهي لا تُحمَّل عند بدء التشغيل. بل تُحمَّل عندما يقرأ الوكيل ملفاً في ذلك الدليل. وينطبق الأمر نفسه على القواعد المقيّدة بالمسار في .claude/rules/ التي تحتوي على حقل frontmatter هو paths:: إذ تُضاف إلى السياق عند قراءة ملف مطابق، وليس في كل دورة.

يفسّر هذا الفرق وحده نسبة كبيرة من حالات الفشل المُبلَّغ عنها. تضع قاعدة في packages/api/CLAUDE.md، ثم تطرح سؤالاً عن API، فيجيب الوكيل من دون أن يفتح أي ملف ضمن packages/api/. لم يتجاهل الوكيل القاعدة، بل لم تكن موجودة في السياق أصلاً. إذا كان مستودعك يقسّم الإرشادات عبر ملفات تعليمات لكل حزمة في مستودع monorepo، فهذا أول ما يجب التحقق منه في كل مرة.

هناك مشكلة أخرى في التحميل، وهي السبب الأكثر شيوعاً لعبارة «تجاهل الوكيل تعليماتي»: يقرأ Claude Code الملف CLAUDE.md، وليس AGENTS.md. إذا كان المستودع يعتمد معيارياً على AGENTS.md ولا يحتوي على CLAUDE.md، فلن يجد Claude Code أي شيء لتحميله. الحل المدعوم هو إنشاء ملف CLAUDE.md يكون سطره الأول @AGENTS.md، ما يؤدي إلى استيراد الملف عند بدء التشغيل، مع إضافة أي ملاحظات خاصة بـClaude أسفله. ويعمل الرابط الرمزي أيضاً إذا لم تكن لديك إضافات أخرى. أما تحديد المحتوى الذي يجب وضعه في هذا الملف من الأساس فهو مسألة منفصلة، وقد غطيناها في فصل تعليمات الوكيل عن توثيق المستخدمين.

تأكّد من تحميل الملف قبل إعادة كتابته

لا تغيّر الصياغة قبل أن تتأكد من أن الوكيل يستطيع رؤية الملف. هناك فحصان، ويأتي الفحص الأبسط أولاً.

شغّل /context داخل الجلسة. يعرض الأمر النافذة الحالية مقسّمة حسب الفئة، وتذكر قائمة Memory files أسماء كل ملفات التعليمات التي حُمّلت فعلياً. إذا لم يظهر الملف في هذه القائمة، فهو ليس ضمن المحادثة، ولذلك لن يكون لأي شيء تكتبه داخله تأثير. يعرض /memory مواقع الملفات ويفتحها للتحرير، بما في ذلك الملفات التي لم تُنشأ بعد.

للحصول على إجابة أكثر حسماً، سجّل عمليات التحميل. يعمل حدث الخطاف InstructionsLoaded في كل مرة يدخل فيها CLAUDE.md أو ملف قواعد إلى السياق، ويحدد المطابق سبب التحميل: session_start أو nested_traversal أو path_glob_match أو include أو compact. ضع ما يلي في .claude/settings.json:

{
  "hooks": {
    "InstructionsLoaded": [
      {
        "matcher": "nested_traversal",
        "hooks": [
          {
            "type": "command",
            "command": "cat >> /tmp/instructions-loaded.log"
          }
        ]
      }
    ]
  }
}

يتلقى الخطاف بياناته بصيغة JSON عبر الإدخال القياسي، لذلك يضيف cat السجل الكامل. راقبه باستخدام tail -f /tmp/instructions-loaded.log أثناء العمل. تُتجاهل حالة الخروج لهذا الحدث، لذلك لا يستطيع الخطاف سوى المراقبة ولا يمكنه حظر العملية. إذا لم يظهر ملفك المتداخل مطلقاً في ذلك السجل أثناء جلسة توقعت فيها تحميله، فتوقف عن إعادة الصياغة. المشكلة في موضع الملف.

تأثير الجلسة الطويلة في قواعدك

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

البعد الزمني. تظل القاعدة المذكورة في الجولة 1 ضمن نافذة السياق في الجولة 90، لكنها تنافس الآن 90 جولة من النص الأحدث والأكثر ارتباطاً بما تفعله حالياً. لا يمكنك معالجة ذلك من خلال الإعدادات، لكن يمكنك قياسه. نفّذ المهمة نفسها في جلسة جديدة. إذا التزمت القاعدة في الجلسة الجديدة وفشلت بعد التعمق في جلسة طويلة، فالبعد الزمني هو السبب.

الاختصار. عندما تمتلئ النافذة، يلخّص النظام المضيف المحادثة حتى تلك اللحظة ثم يواصل العمل انطلاقاً من الملخص. ما يبقى هو ما يراه مُنشئ الملخص مهماً، وهذا لا يطابق بالضرورة ما تراه أنت مهماً. توثّق Claude Code النتيجة لكل آلية، والفروق كبيرة. يُعاد حقن جذر المشروع CLAUDE.md والقواعد غير المقيّدة النطاق من القرص بعد الاختصار. وتُعاد حقن الذاكرة التلقائية من القرص. أما القواعد التي تحتوي على frontmatter من نوع paths: فتُفقد إلى أن تتم قراءة ملف مطابق مرة أخرى. وتُفقد ملفات CLAUDE.md المتداخلة في الأدلة الفرعية إلى أن تتم قراءة ملف في ذلك الدليل الفرعي مرة أخرى.

رتّب تعليماتك وفقاً لذلك الجدول، وستتضح درجة هشاشتها. القاعدة التي كتبتها في المحادثة فقط هي أكثر عناصر الجلسة هشاشة؛ إذ تستمر فقط إذا احتفظ بها الملخص مصادفةً. وتأتي بعدها القاعدة الموجودة في packages/api/CLAUDE.md، لأنها حُمّلت مرة واحدة ثم أزيلت من الملخص، ولا تعود إلا عند القراءة التالية في ذلك الدليل. أما القاعدة الموجودة في ملف جذر المشروع فهي الأكثر استمرارية، لأنها تُقرأ من القرص مرة أخرى في كل مرة.

لذلك، إذا كان يجب أن تظل التعليمات سارية طوال الجلسة، فضَعها في ملف جذر المشروع من دون frontmatter من نوع paths:. أما كل ما عدا ذلك فهو مفاضلة ينبغي أن تختارها عن قصد. يشرح إدارة ما يبقى في نافذة السياق /compact باستخدام وسيطة focus، و/clear بين المهام غير المرتبطة، ويؤثر كلاهما في معدل منح مُنشئ الملخص فرصة تحديد القواعد التي كنت تقصدها.

لماذا يتغلب الكود المحيط على القاعدة

هذا هو الفشل الذي يصفه الناس غالباً، لكنهم يشخّصونه نادراً. ينص ملفك على أن الوصول إلى قاعدة البيانات يمر عبر طبقة المستودع. فيكتب الوكيل معالجاً يستدعي ORM (مصمم الخرائط العلائقية للكائنات) مباشرة. لم يتجاهلك الوكيل بسبب قواعد التنسيق. بل رجّحته الأدلة.

تصف القاعدة تفضيلاً. أما الكود فيعرض مثالاً على تطبيقه. عندما يفتح الوكيل ثلاثة ملفات في الوحدة التي يستعد لتعديلها، وتستدعي الملفات الثلاثة ORM مباشرة، فسيجد في السياق جملة تجريدية واحدة في جانب، وثلاثة أمثلة ملموسة وحديثة ومطابقة للمهمة في الجانب الآخر. يكون نسخ النمط المحلي هو السلوك الصحيح عادةً. لكنه خاطئ هنا فقط لأنك تعرف شيئاً لا يعرفه السياق: هذه الملفات قديمة.

لذلك، اكتب هذه المعلومة في القاعدة. تصمد القواعد التي تذكر الأدلة المضادة لها عند التعامل مع مستودع حقيقي. أما القواعد التي تذكر تفضيلاً مجرداً فلا تصمد.

يمر الوصول الجديد إلى قاعدة البيانات عبر app/repositories/. ما زالت الملفات ضمن app/legacy/ تستدعي ORM مباشرةً. هذا كود قديم، وليس النمط المعتمد. لا تنسخه.

الجملة الثانية هي التي تؤدي العمل. فهي تخبر الوكيل بما سيجده وكيف يفسّره قبل أن يعثر عليه. وينطبق الإصلاح نفسه على أي قاعدة يناقضها مستودعك بوضوح: أسلوب كتابة commits لا يتبعه سجلّك، أو تنظيم اختبارات يتجاهله نصف مجموعة الاختبارات، أو اصطلاح imports ينطبق على الكود الجديد فقط. عندما يخالف الكود ما يرد في الملف، اذكر هذا الخلاف في الملف.

القاعدة الغامضة لا يمكن التحقق منها، ولذلك لا يمكن اتباعها

"اكتب تعليمات برمجية نظيفة." "لا تبالغ في هندسة الحل." "اجعل الحل بسيطاً." "توخَّ الحذر عند تنفيذ عمليات الترحيل." لا يمكن اختبار أي من هذه العبارات مقابل إجراء محدد، سواء من قِبل الوكيل أو من قِبلك. عندما تُعطى الوكيل قاعدة لا يستطيع التحقق منها مقابل مخرجاته، فإنه يخمّن، وأنت تقيّم التخمين بالانطباع.

طبّق الاختبار التالي على كل سطر في ملفك. اكتب أمر shell ينتهي بحالة غير صفرية عند مخالفة القاعدة. إذا لم تتمكن من كتابة هذا الأمر، فالقاعدة غير قابلة للتحقق. قارن بين الأزواج التالية:

• غير قابلة للتحقق: "اجعل الدوال صغيرة." قابلة للتحقق: "تحتاج الدالة التي يزيد طولها عن 60 سطراً إلى تعليق فوقها يشرح السبب."
• غير قابلة للتحقق: "اختبر تغييراتك." قابلة للتحقق: "شغّل npm test والصق عدد حالات الفشل قبل اعتبار المهمة مكتملة."
• غير قابلة للتحقق: "نظّم الملفات." قابلة للتحقق: "توجد معالجات HTTP في src/api/handlers/. لا يوضع أي شيء آخر في ذلك الدليل."
• غير قابلة للتحقق: "نسّق التعليمات البرمجية بطريقة صحيحة." قابلة للتحقق: "استخدم مسافة بادئة بمقدار مسافتين في ملفات .ts."

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

الحجم هو المشكلة نفسها في صورة مختلفة. تستهدف إرشادات Claude Code ملفات التعليمات التي يقل طولها عن 200 سطر، وتذكر مباشرةً أن الملفات الأطول تقلل الالتزام. الملف الذي يتكون من 700 سطر ليس تعليمات أكثر حزماً. بل هو 700 سطر من الادعاءات التي تزيد معها فرص التناقض، كما تُحتسب ضمن نافذة السياق في كل دور، وهو ما يظهر مباشرةً في استخدامك للرموز المميزة. تنظيم الملف بحيث توضع كل قاعدة تحت عنوان يمكن للقارئ استعراضه مشمول في كتابة ملف تعليمات يستطيع الوكيل تنفيذه. والأفضل من ذلك حذف الأجزاء التي تصف بدلاً من أن توجّه: فالجولة التعريفية في الدليل التي توضّح أماكن معالجات الطلبات والنماذج هي بنية يستطيع الوكيل البحث عنها عند الحاجة من خلال خريطة محللة للمستودع، بدلاً من إبقائها في نافذة السياق في كل دور.

كيفية تشخيص المشكلة خلال عشر دقائق

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

1. تأكد من تحميله. نفّذ /context واقرأ قائمة Memory files. إذا لم يكن الملف موجوداً، فأصلح موقعه وتوقف. لا تنطبق أي خطوة أخرى في هذه القائمة بعد.
2. أعد إنتاج المشكلة في جلسة جديدة. ابدأ جلسة جديدة ونفّذ أصغر مهمة يُفترض أن تفعّل القاعدة. إذا نجحت القاعدة في البداية ثم فشلت في جلسة طويلة، فهذا يشير إلى تراجع تأثيرها بسبب طول السياق أو إلى ضغط السياق. وإذا فشلت هنا أيضاً، فالمشكلة في القاعدة نفسها.
3. أزل القواعد المنافسة. اطلب التغيير نفسه في دليل يتبع الكود الموجود فيه القاعدة بالفعل. إذا عاد الالتزام بالقاعدة، فهذا يعني أن الكود المحيط كان يتغلب على عبارتك.
4. ابحث عن تعارض. وجود ملفين يقدمان إرشادات مختلفة للسلوك نفسه هو فشل موثق: قد يختار النموذج أحدهما عشوائياً، ولن يخبرك بأنه فعل ذلك.
5. اجعلها قابلة للتحقق ثم أعد الاختبار. أعد صياغة القاعدة باستخدام مسار محدد وشرط واضح. إذا تحسن الالتزام بها كثيراً، فهذا يعني أن الصياغة كانت سبب المشكلة.

الخطوة 4 عبارة عن أمر واحد. ابحث باستخدام Grep في كل مصادر التعليمات عن الموضوع، وليس في الملف الذي كنت تعدّله فقط:

grep -rni "migration" --include="CLAUDE.md" --include="CLAUDE.local.md" .
grep -rni "migration" .claude/rules/ ~/.claude/CLAUDE.md ~/.claude/rules/ 2>/dev/null

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

الإصلاحات مرتبة حسب مستوى التأثير

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

1. اجعل القاعدة محددة. اذكر مساراً أو أمراً أو شرطاً. أضف الأدلة المضادة التي سيجدها الوكيل في المستودع، كما ورد سابقاً. لا يكلّف ذلك شيئاً ويعالج نسبة مفاجئة من الحالات.
2. قرّبها من الشيء الذي تحكمه. استخدم CLAUDE.md متداخلاً، أو قاعدة محددة النطاق لمسار في .claude/rules/، أو تعليقاً في أعلى الملف نفسه. عندها تُقرأ القاعدة في الوقت نفسه الذي تُقرأ فيه الشفرة التي تنطبق عليها. اقبل المقايضة: كل ما يُحمّل بهذه الطريقة يختفي عند الضغط التالي ويعود عند القراءة المطابقة التالية.
3. انقل التنفيذ إلى hook. النص يطلب، أما hook فيقرّر. تعمل hooks كتعليمات برمجية عند أحداث ثابتة في دورة الحياة، وتُطبّق بغض النظر عما يستنتجه النموذج.
4. سلّم القاعدة إلى أداة حتمية واحذف النص. تنسيق الشفرة، وترتيب الاستيرادات، وطول السطر، والاستيرادات المحظورة، وبنية رسالة commit. استخدم ruff format وprettier --write وeslint وhook من نوع pre-commit. تكون أداة التنسيق صحيحة في كل مرة ولا تستهلك أي tokens. أما الجملة فتكون صحيحة في معظم الأوقات، وتستهلك tokens في كل دور.

الخطوة 3 بالتفصيل. افترض أن ملفات الترحيل يجب ألا يعدّلها الوكيل مطلقاً. ضع ما يلي في .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-migrations.sh"
          }
        ]
      }
    ]
  }
}

وضع ما يلي في .claude/hooks/guard-migrations.sh:

#!/usr/bin/env bash
set -euo pipefail

path=$(jq -r '.tool_input.file_path // empty')

case "$path" in
  */migrations/*)
    echo "Files under migrations/ are written by hand. Stop and ask first." >&2
    exit 2
    ;;
esac

exit 0

شغّل chmod +x .claude/hooks/guard-migrations.sh، ثم ابدأ جلسة جديدة واطلب من الوكيل تعديل ملف ضمن migrations/. سيرفض التعديل، وستعود رسالتك بوصفها السبب. تمنع حالة الخروج 2 في PreToolUse استدعاء الأداة قبل تشغيلها، ويُسلَّم نص stderr إلى النموذج بوصفه رسالة المنع. يُحلّ ${CLAUDE_PROJECT_DIR} إلى جذر المشروع، لذلك يعمل hook مهما كان الدليل الذي يوجد فيه الوكيل. لا يحتاج الوكيل إلى الموافقة على القاعدة أو تذكّرها أو استمرار وجودها في السياق. لن يحدث التعديل.

بالنسبة إلى حظر مباشر لا يتضمن أي منطق، تؤدي permissions.deny في إعداداتك المهمة نفسها من دون script تحتاج إلى صيانته، وتحدد أوضاع الأذونات ما يُشغَّل من دون أن يطلب موافقتك أولاً. وإذا كان يجب أن تكون التعليمات فعلاً على مستوى system prompt بدلاً من رسالة المستخدم، تضعها --append-system-prompt هناك، لكن يجب تمريرها في كل استدعاء، ولذلك تلائم scripts أكثر من العمل التفاعلي.

ما لا يمكنك معالجته بالتعليمات

كن واضحاً بشأن الجزء الواقع ضمن مسؤوليتك. الموضع، والصياغة، والتعارضات بين الملفات، وحجم الملف مشكلات تخص المؤلف، ولها إصلاحات يجريها المؤلف. أما الباقي فهو سلوك النموذج، ولن تزيله الصياغة الأفضل.

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

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

تصبح جلستك نفسها مثالاً. إذا خالف الوكيل القاعدة في الدور 12 وسمحت له بذلك، تصبح المخالفة الآن ضمن السياق بوصفها مثالاً، وتكون أحدث بكثير من القاعدة. صحّح المخالفة لحظة رؤيتها. فالمخالفة غير المصححة تعلّم بقية الجلسة.

ملف التعليمات ليس حدّاً أمنياً. فهو يوجّه السلوك ولا يفرضه. كل ما تكون كلفة الخطأ فيه مرتفعة، مثل بيانات الاعتماد أو الأوامر المدمّرة، يجب أن يخضع للصلاحيات أو لـhook. إبعاد الأسرار عن متناول الوكيل يطبّق المبدأ نفسه على البيانات: لا تطلب من الوكيل ألا يقرأ ملفاً، بل رتّب بحيث لا يكون الملف قابلاً للقراءة.

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

FAQ

لماذا يتجاهل Claude Code ملف CLAUDE.md الخاص بي؟

تحقق أولاً من تحميله قبل افتراض أنه جرى تجاهله. شغّل /context وانظر إلى قائمة Memory files؛ فالملف غير المذكور فيها ليس جزءاً من المحادثة. تُرسَل ملفات التعليمات في رسالة مستخدم بعد مطالبة النظام، وتُعامل باعتبارها سياقاً لا إعداداً مُلزِماً، لذلك لا يوجد ضمان صارم للامتثال لها. في معظم الحالات الفعلية، يكون السبب واحداً من أربعة: يوجد الملف في دليل فرعي لم يقرأ منه الوكيل، أو يتعارض ملفان واختار النموذج أحدهما عشوائياً، أو أن القاعدة غامضة جداً بحيث يتعذر التحقق منها مقابل إجراء معين، أو أن الشفرة المحيطة توضح سلوكاً مخالفاً لما تنص عليه القاعدة.

هل يغيّر تعديل ملف التعليمات أثناء الجلسة أي شيء؟

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

أي ملف تكون له الأولوية عند تعارض CLAUDE.md الجذري مع ملف متداخل؟

لا تكون الأولوية لأي منهما بشكل موثوق. تُلحق الملفات المكتشفة بسياق المحادثة بدلاً من أن يتجاوز أحدها الآخر، ويكون ترتيبها من جذر نظام الملفات نزولاً إلى دليل العمل، لذلك يُقرأ الملف الأقرب أخيراً فحسب. لا يوجد محرك أولوية يحل التناقضات، وتنص وثائق Claude Code على أن القواعد المتناقضة قد تُحل عشوائياً. اكتب الملفات المتداخلة باعتبارها إضافات تحدد المسار الذي تحكمه، واحذف التناقض بدلاً من محاولة منحه أولوية أعلى.

هل تبقى تعليماتي بعد /compact؟

يعتمد ذلك على طريقة تحميلها. يُعاد حقن CLAUDE.md الخاص بجذر المشروع، والقواعد غير المقيّدة بنطاق، والذاكرة التلقائية من القرص بعد إجراء compaction. أما القواعد التي تحتوي على frontmatter هو paths: والملفات المتداخلة CLAUDE.md في الأدلة الفرعية، فتُفقد إلى أن يُعادَت قراءة ملف مطابق. وكل ما كتبته في الدردشة فقط يبقى إذا احتفظ به الملخِّص بالصدفة. إذا كان يجب أن تستمر قاعدة طوال الجلسة، فضعها في ملف جذر المشروع من دون frontmatter هو paths:.

متى ينبغي تحويل القاعدة إلى hook بدلاً من إبقائها نصاً؟

عندما يكون الفحص حتمياً وتكون تكلفة عدم اكتشاف الخطأ أعلى من تكلفة كتابة script صغير. تندرج ضمن ذلك قيود مسارات الملفات، والأوامر المطلوبة قبل إجراء commit، واستدعاءات الأدوات الممنوعة. إن hook من نوع PreToolUse ينتهي بحالة status 2 يحظر استدعاء الأداة مباشرة، ويعيد نص stderr إلى النموذج باعتباره السبب، ولذلك يطبّق القاعدة سواء بقيت في السياق أم لا. وكل ما يستطيع formatter أو linter تحديده ينبغي أن تتولاه تلك الأداة، وأن يُحذف بالكامل من ملف التعليمات.