انتقل إلى المحتوى الرئيسي

الوحدة 3 — CLAUDE.md والقواعد والذاكرة: تعليم Claude معالم المشروع

بيّنت الوحدة 2 لماذا يُعيد Claude قراءة CLAUDE.md عند كلّ /compact. هذه الوحدة تستخلص التبعات: ما يجب كتابته فيه، وما يجب إخراجه إلى قواعد محدَّدة النطاق، وما نتركه لـالذاكرة التلقائيّة التي يُغذّيها Claude وحده. على Kiosque، نستبدل ملفّ CLAUDE.md المولَّد بـ/init بملفّ متين يصمد لثلاث إعادات صياغة.

آليّتان متكاملتان​

كلّ جلسة تبدأ بسياق فارغ. آليّتان تملآنه: ملفّات CLAUDE.md التي تكتبها أنت (تعليمات، قواعد، تُحمَّل عند كلّ جلسة — مشروع، مستخدم، مؤسّسة)، والذاكرة التلقائيّة التي يكتبها Claude (دورك، تفضيلاتك، ما تُصحّحه غالبًا، وقائع لا يستنبطها Claude من الشيفرة).

كلاهما مجرّد سياق، لا إعدادات تنفيذيّة. تعليمة تظلّ توصية قد يتجاهلها نموذج إن كانت مبهمة أو متناقضة. لحظر شيء بشكل حتميّ — رفض الكتابة على .env، فرض lint — يجب hook PreToolUse (الوحدة 9). الثلاثيّة: CLAUDE.md لما يجب أن يعرفه Claude، skills لما يجب أن يعرف فعله عند الطلب، hooks لما يجب أن يحدث مهما كان.

تراتبيّة ملفّات الذاكرة​

يمكن أن تعيش ملفّات CLAUDE.md في عدّة مستويات. ترتيب التحميل يمضي من الأوسع إلى الأخصّ — كلّ مستوى يُضاف، ولا يُبدّل الآخر.

النطاقالموقعالاستعمال
سياسة مؤسّسةmacOS /Library/Application Support/ClaudeCode/CLAUDE.md، Linux/WSL /etc/claude-code/CLAUDE.md، Windows C:\Program Files\ClaudeCode\CLAUDE.mdتعليمات تُديرها IT أو DevOps، معايير أمن، التزامات قانونيّة
المستخدم~/.claude/CLAUDE.mdتفضيلات شخصيّة تسري على كلّ المشاريع
المشروع (مشترك)./CLAUDE.md أو ./.claude/CLAUDE.mdاصطلاحات الفريق، أوامر البناء، قرارات المعماريّة. يُودَع في git
محلّيّ (شخصيّ)./CLAUDE.local.mdعناوين sandbox الخاصّة بك، بيانات اختبار. يُضاف إلى .gitignore

يُحمّل Claude Code CLAUDE.md وCLAUDE.local.md من مسارك الجاري ومن كلّ المجلّدات فوقه، من أعلى الشجرة إلى أسفلها. ملفّات المجلّدات الفرعيّة لا تُحمَّل إلّا عند الطلب — حين يقرأ Claude ملفًّا داخل ذلك المجلّد. هذا السلوك ثمين في monorepo: لا يدخل apps/back/CLAUDE.md السياقَ ما دمنا لم نمسّ backend.

ملفّ CLAUDE.md يتجاوز 4 ميبيبايت يُتجاهَل؛ وملفّ يتجاوز 200 سطر أو 25 كيلوبايت يستهلك سياقًا كبيرًا ويُخفِض الالتزام. القاعدة الافتراضيّة هي البقاء دون 200 سطر.

كتابة تعليمات فعّالة​

التعليمات اللفظيّة تفشل: «نسّق بشكل صحيح»، «اختبر شيفرتك». التعليمات القابلة للتحقّق تنجح: «استعمل مسافتين للإزاحة»، «شغّل make test قبل الالتزام»، «مُعالجات API تعيش في app/api/handlers/». أضف إلى CLAUDE.md كلّما ارتكب Claude الخطأ نفسه مرّتين أو حين تلتقط code review شيئًا كان ينبغي أن يعرفه. جملة قصيرة، ووقيعة واحدة لكلّ سطر، خير من فقرة كثيفة.

ما لا يجب وضعه: شجرة المجلّدات، قائمة التبعيّات، المعماريّة (يستنبطها Claude)؛ الإجراءات المتعدّدة الخطوات (تلك skill، الوحدة 6)؛ ما يخصّ مجلّدًا فرعيًّا (تلك قاعدة محدَّدة النطاق)؛ tokens أو أسرار (الملفّ يُودَع في git).

.claude/rules/: التقسيم بالموضوع، التحديد بالمسار​

يسمح مجلّد .claude/rules/ بتقسيم CLAUDE.md إلى ملفّات موضوعيّة. كلّ .md تحت هذا المجلّد يُحمَّل تكراريًّا بأولويّة .claude/CLAUDE.md إن لم يحمل frontmatter. ملفّ لكلّ موضوع (api.md، front.md، security.md) يبقى أسهل صيانةً من ملفّ CLAUDE.md ضخم.

فائدته الأكبر تأتي من frontmatter paths:: قاعدة محدَّدة النطاق لا تُحمِّل محتواها إلّا حين يقرأ Claude ملفًّا يطابقها.

---
paths:
  - "app/**/*.py"
  - "tests/**/*.py"
---

# Règles API

- Toute route FastAPI valide ses entrées via Pydantic.
- Les réponses d'erreur suivent le format `{code, message, details}`.
- Les migrations SQLAlchemy sont générées avec `alembic`.
- Aucun accès direct à la session hors du dependency-injection.

تتبع الأنماط الصيغة المعتادة لـglob: **/*.ts وsrc/api/**/*.ts وsrc/**/*.{ts,tsx} مع توسيع الأقواس المعقوفة (ميزانيّة 1 000 نمط بعد التوسيع و4 ميبيبايت لكلّ قاعدة). النمط غير القابل للقراءة كتعبير bracket لم يعد يحجب منذ v2.1.207: لا يطابق شيئًا، وتظلّ القاعدة تعمل على البقيّة.

تنطبق القواعد حين يقرأ Claude ملفًّا يطابقها، لا في كلّ استدعاء أداة. منذ v2.1.198، تعمل المطابقة كذلك عبر مسار symlink.

استيرادات @chemin​

يمكن لملفّ CLAUDE.md استيراد ملفّات أخرى بصيغة @chemin (نسبيّ إلى الملفّ المستورِد أو مطلق). تُبسَط الاستيرادات عند الإطلاق، بعمق أقصى قدره أربعة.

Voir @README pour la vue d'ensemble et @package.json pour les scripts.

## Conventions détaillées
- Style Python : @docs/conventions-python.md
- Style front : @docs/conventions-front.md

الاستيرادات داخل ملفّ ذي نطاق مشروع، حين يستقرّ مسارها خارج مسار العمل (مثل @~/notes.md)، حسّاسة: أوّل مرّة، يفتح Claude Code صندوق موافقة؛ الرفض يُعطّلها بصمت. ملفّات ذاكرة نطاق المستخدم تُحمِّل استيراداتها بلا حوار. لمشاركة القواعد ذاتها بين مشاريع، يقوم symlink بالغرض: ln -s ~/shared-claude-rules .claude/rules/shared.

AGENTS.md والتوافق​

يقرأ Claude Code CLAUDE.md، لا AGENTS.md. خياران إن كان مستودعك يستعمل AGENTS.md: ملفّ CLAUDE.md يستورده (@AGENTS.md)، أو symlink ln -s AGENTS.md CLAUDE.md. يقرأ /init علاوة على ذلك .cursor/rules/ و.cursorrules و.github/copilot-instructions.md. مع CLAUDE_CODE_NEW_INIT=1، يُضيف أيضًا AGENTS.md و.devin/rules/ و.windsurf/rules/ و.clinerules. يُحضِر أمر /import [codex|gemini] (v2.1.213+) إعدادات وكيل آخر بمرور واحد.

الذاكرة التلقائيّة​

الذاكرة التلقائيّة مفعَّلة افتراضيًّا. كلّما تعلَّم Claude شيئًا متينًا، كتبه بنفسه في ~/.claude/projects/<projet>/memory/. أربعة أنواع من الملاحظات مؤشَّرة بحقل type: user (دورك، تفضيلاتك)، feedback (تصحيحات قدَّمتها لـClaude، مقاربات صدَّقتها)، project (قرارات، مواعيد، وقائع لا يستنبطها Claude من الشيفرة)، reference (أين نجد معلومة خارج المشروع). لا يكتب Claude في كلّ جلسة؛ بل يُقرّر مع الجريان إن كانت الحقيقة تستحقّ الحفظ ويتجنّب ما تعرضه الشيفرة أصلًا.

يحوي المجلّد فهرسًا MEMORY.md — الشيء الوحيد الذي يُحمَّل في كلّ جلسة (200 سطر أو 25 كيلوبايت) — وملفًّا لكلّ موضوع (user_role.md، feedback_testing.md) يُقرأ عند الطلب. منذ v2.1.214، تحصل كلّ ملاحظة على حقل modified بصيغة ISO 8601 عند إعادة الكتابة.

للتعطيل: "autoMemoryEnabled": false في settings.json للمشروع، أو عالميًّا CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. يُغيِّر مفتاح autoMemoryDirectory الموقعَ (مسار مطلق أو ~/...). ذاكرة الجلسة الرئيسيّة لا تُحمَّل في الوكلاء الفرعيّين — إلّا لـfork، الذي يرث المحادثة الأمّ. يمكن لوكيل فرعيّ أن تكون له ذاكرته الخاصّة عبر حقل memory في frontmatter الخاصّ به (الوحدة 10).

/init و/memory و/doctor​

ثلاثة أوامر تُغطّي دورة الحياة كاملة:

  • /init يُولّد CLAUDE.md مبدئيًّا بتحليل المستودع. مع CLAUDE_CODE_NEW_INIT=1، يقترح النسخة التفاعليّة أيضًا skills وhooks وملفّات ذاكرة شخصيّة، ويقرأ إعدادات محتملة من AGENTS.md أو .cursor/rules/. هي مسوّدة: تُنقَّح قبل الالتزام.
  • /memory يعرض ملفّاتك CLAUDE.md وCLAUDE.local.md وملفّات الذاكرة لكلّ النطاقات، بما فيها ما لم يُنشأ بعد. اختر عنصرًا لفتحه في محرِّرك؛ إن لم يكن موجودًا، يُنشئه /memory أوّلًا. يُعطي الأمر أيضًا مبدّل الذاكرة التلقائيّة ووصولاً مباشرًا إلى مجلّد الذاكرة.
  • /doctor (البديل /checkup) يُجري تشخيصًا كاملاً ويقترح إصلاحات: تثبيتات مكرّرة، PATH، إعدادات غير قابلة للقراءة، skills غير مستعملة، خوادم MCP خاملة، CLAUDE.md ثقيل جدًّا. منذ v2.1.206، يُنحِّف ملفّ CLAUDE.md مُودَعًا في git: يقطع ما يستنبطه Claude من الشيفرة (شجرة المجلّدات، التبعيّات) ويُبقي المزالق، والمنطق، والاصطلاحات التي تختلف عن الافتراضيّات. يُهاجر البقيّة إلى skills أو CLAUDE.md مُدمَجة تُحمَّل عند الطلب.

ما يصمد أمام /compact​

بعد /compact، يُعاد حقن ملفّ CLAUDE.md للمستودع والقواعد بلا paths: من القرص. تعليمة أُضيفت في المحادثة تختفي، وإضافة إلى CLAUDE.md تصمد كلّ الضغوط. الردّ الصائب حين تُصحّح Claude مرّتين: أضف القاعدة. يفعل /memory ذلك بثلاث ضغطات مفاتيح.

الإدارة داخل الفريق​

ملفّ CLAUDE.md يُودَع في git؛ CLAUDE.local.md لا يُودَع. نُدوِّن الاصطلاحات المشتركة في الأوّل، والتفضيلات الشخصيّة في الثاني. تستطيع مؤسّسة دفع CLAUDE.md مُدار أو claudeMd في managed-settings.json لا تستطيع إعدادات المستخدم والمشروع والمحلّيّة تجاوزه — مفيد لتذكيرات الامتثال، لا لاصطلاحات الشيفرة (التي تعيش في المستودع).

في monorepo، مفتاح claudeMdExcludes (في settings.json من أيّ نطاق باستثناء managed policy) يتخطّى ملفّات CLAUDE.md لفرق أخرى تعيش في المجلّدات الأمّ؛ تحمل الأنماط المسار المطلق. لا يمكن استثناء CLAUDE.md managed policy أبدًا.

الخيط الأحمر Kiosque: CLAUDE.md حقيقيّ​

أنتج /init في الوحدة 1 ملفًّا ثرثارًا. نُعيد كتابته يدويًّا ليستقرّ على نحو أربعين سطرًا مفيدًا:

# CLAUDE.md — Kiosque

Application de prise de commandes pour food-trucks : API FastAPI dans
`app/`, front React dans `web/`, SQLite via SQLAlchemy.

## Commandes

- `make dev`   : lance l'API `:8000` et le front `:5173`.
- `make test`  : pytest ; ne jamais commiter si rouge.
- `make lint`  : `ruff format` puis `ruff check --fix`.
- `mypy app/`  : avant chaque PR touchant l'API.

## Conventions

- **Entités en français** : `commande`, `paiement`, `menu`. Le code
  anglais est un legacy à convertir, pas à imiter.
- Routes dans `app/routers/`, modèles dans `app/models.py`, services
  purs dans `app/services/`.
- Schémas Pydantic en `In` / `Out` (`CommandeIn`, `CommandeOut`).
- `httpx` pour les appels sortants, jamais `requests`.

## Pièges

- `test_paiements_delai` instable — pas de conclusion sur un run isolé.
- `.env` **jamais** lu ni écrit par Claude.
- Migrations SQLAlchemy via Alembic ; pas de DDL direct.

## Compact instructions

- Garder décisions d'architecture et conventions.
- Jeter les extraits de code lus et les explorations ponctuelles.

إلى جانبه، .claude/rules/api.md مُحدَّد بـapp/**/*.py وtests/**/*.py (Pydantic، تنسيق الخطأ {code, message, details}، هجرات Alembic)، و.claude/rules/front.md مُحدَّد بـweb/**/*.{ts,tsx} (مكوّنات دالّيّة، TanStack Query، Tailwind). نُضيف .env إلى .gitignore. ستضع الوحدة 9 hook PreToolUse يرفض الكتابة على .env: حزام وحمّالة يجعلان القاعدة لا تُنقض.

خطأ شائع: «لماذا لا يتّبع Claude قاعدتي؟»​

تعود ثلاثة أسباب: القاعدة غير مُحمَّلة — يعرض /context Memory files؛ ملفّ غائب لا أثر له، تحقّق من المسار، وبالنسبة لقاعدة محدَّدة النطاق، تأكّد أنّ Claude قرأ ملفًّا يطابقها؛ القاعدة مبهمة — «format properly» لا يُقاس بـ«2 espaces d'indentation»؛ القاعدة تُناقض أخرى، فيحسم Claude اعتباطًا (يرصد /doctor أحيانًا التكرار). ركيزة أخيرة: hook InstructionsLoaded (الوحدة 9) يتتبّع بدقّة ملفّات التعليمات المحمَّلة، متى ولماذا.

الخلاصة​

  • آليّتان: CLAUDE.md الذي تكتبه، والذاكرة التلقائيّة التي يُغذّيها Claude. كلاهما مجرّد سياق.
  • تراتبيّة: managed policy ← user ← project ← local؛ المستويات تُضاف.
  • .claude/rules/*.md مع paths: يتجنّب تضخيم CLAUDE.md الرئيسيّ.
  • استيرادات @chemin مُبسَّطة على أربعة مستويات؛ symlinks لمشاركة القواعد بين المشاريع.
  • AGENTS.md: لا يُقرأ افتراضيًّا؛ استعمل @AGENTS.md أو symlink، أو شغّل /import.
  • الذاكرة التلقائيّة: أربعة أنواع (user, feedback, project, reference) في ~/.claude/projects/<projet>/memory/.
  • /init يُنتج مسوّدة، و/memory يُحرّر، و/doctor يُنحِّف. CLAUDE.md دون 200 سطر يصمد للمسافة.

الوحدة التالية: أوامر الشرطة المائلة المدمجة (1/2): الجلسة والسياق والإعدادات والنموذج — المرجع الشامل للعائلات الثمانية مع كلّ اسم بديل وكلّ وسيط.