إعداد Claude Code لمشروعك

إعداد Claude Code لمشروع بياخد حوالي عشر دقايق. المقابل إن Claude هيفهم الـ conventions بتاعتك من أول رسالة، هيكون عنده الصلاحيات المناسبة يعمل شغل مفيد، وهيتصرف بشكل متّسق لكل واحد في الفريق. الموديول ده بيمشيك على خطوات الإعداد بالترتيب.

تهيئة ذاكرة المشروع

ابدأ بأمر /init. Claude هيعمل scan للكود بتاعك — هيقرأ package.json، الـ docs الموجودة، وهيكلة المجلدات — وبعدين يولّد ملف CLAUDE.md فيه الـ tech stack، الأوامر المهمة، والـ conventions الأساسية. اعمل commit للملف ده في git فورًا عشان زملائك ياخدوا نفس الـ context.

ملف CLAUDE.md الكويس بيكون مختصر ومحدد. استهدف أقل من 200 سطر لكل ملف. كل سطر لازم يكون مفيد في تقريبًا كل جلسة — لو حاجة بتهم feature واحد بس، حطّها في ملف rules مخصص بالمسار بدلًا من كده. أهم الأقسام هي: الـ tech stack والـ versions، أوامر التطوير (install، test، build، lint)، الـ naming conventions اللي مش واضحة، والـ gotchas المعروفة اللي ممكن تلخبط مطور جديد.

# Project: Payment Service

## Stack

- Node.js 20, TypeScript 5, PostgreSQL 15
- Express for API, Prisma for ORM, Jest for tests

## Commands

- `npm run dev` — start with hot reload
- `npm test` — run test suite
- `npm run migrate` — apply pending migrations
- `npm run lint` — ESLint + Prettier check

## Conventions

- All monetary values stored as integers (cents)
- Use `Result<T, E>` pattern for error handling, never throw in service layer
- Database columns: snake_case; TypeScript: camelCase

ضبط الصلاحيات

Claude Code بيشتغل ضمن نظام صلاحيات بيتحكم في الأدوات اللي يقدر يستخدمها من غير ما يسألك. الوضع الافتراضي بيطلب موافقة لمعظم عمليات الكتابة وكل أوامر الـ bash. للتطوير النشط، هتحتاج تعتمد العمليات الشائعة مسبقًا.

افتح مدير الصلاحيات بـ /permissions. ضيف patterns للأوامر اللي Claude هيستخدمها بشكل متكرر. استخدم Bash(git *) عشان تسمح بكل أوامر git، Bash(npm *) لأوامر npm، أو Bash(npx jest *) لأداة محددة. عمليات الملفات ممكن تتحدد بمسارات معينة.

ملفات الإعدادات بتتحكم في الصلاحيات على مستوى المشروع والمستخدم. .claude/settings.json بيتعمل له commit في git للفريق. .claude/settings.local.json بيتعمل له git-ignore للتعديلات الشخصية:

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(npm *)",
      "Bash(npx *)",
      "Read(**/*)",
      "Write(src/**/*)",
      "Edit(src/**/*)"
    ]
  }
}

للعمليات الحساسة زي الـ production deploys، سيبها تطلب موافقة أو استخدم disable-model-invocation: true على الـ skills عشان Claude ما يقدرش يشغّلها تلقائيًا أبدًا.

لما المهمة تحتاج ملفات بره الـ project root — مكتبة جنب المشروع، أو حزمة types مشتركة، أو bundle متولد — استخدم --add-dir عند تشغيل الجلسة (أو /add-dir في النص) عشان توسّع الـ working directories للجلسة دي. كل مسار لازم يبقى موجود كـ directory، والـ flag بيدي وصول للملفات بس، مش باقي إعدادات الـ .claude/ اللي في الشجرة دي:

# ابدأ جلسة بصلاحية قراءة وتعديل في directoryين جنب المشروع
claude --add-dir ../shared-types --add-dir ../design-tokens

عشان تثبّت الـ directories دي لكل جلسات المشروع بدل ما تكتبها كل مرة، اضبط permissions.additionalDirectories في .claude/settings.json. --add-dir هو الشكل المؤقت لكل جلسة لنفس الصلاحية.

الأمان — قيود الـ Marketplace

استخدم blockedMarketplaces عشان تحصر الـ marketplaces اللي تقدر تستخدمها. الـ entries بتدعم hostPattern للتحكم بالمجال (مثلاً "*.example.com") وpathPattern للتحكم بمسار الـ repository (مثلاً "acme/corp-plugins"):

{
  "blockedMarketplaces": [
    { "hostPattern": "*.untrusted-domain.io" },
    { "pathPattern": "acme/corp-plugins" }
  ]
}

ده بيتنفّذ على مستوى السياسة — المستخدمين ما يقدروش يغيّروه بالإعدادات المحلية. متاح في managed policy لـ enterprise deployments.

الإعدادات والبيئة

الإعدادات بتمشي على نموذج الأولويات الرسمي. من الأعلى للأدنى: الإعدادات المُدارة (managed settings)، arguments الـ command-line للجلسة الحالية، .claude/settings.local.json، .claude/settings.json، و~/.claude/settings.json. خلّص، الإعدادات المحلية (.claude/settings.local.json) بتغلّب على إعدادات المشروع — التفضيلات الشخصية بتاخد الأولوية على إعدادات الفريق، وبس سياسة المنظمة وarguments سطر الأوامر بيتغلبوا على المحلي. التوصيل المُدار ممكن يستخدم ملفات سياسة المنصة أو مجلدات إعدادات مُدارة، لكن دي تفاصيل تنفيذ للطبقة المُدارة العليا مش نطاقات يومية منفصلة.

الـ native installer بيعمل auto-update في الخلفية بشكل افتراضي. تثبيتات Homebrew وWinGet مش بتعمل auto-update بشكل افتراضي — عشان تفعّلها، اضبط CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1. Claude Code هيشغّل أمر ترقية الـ package manager في الخلفية لما إصدار جديد يبقى متاح ويطلب منك تعيد التشغيل بعد النجاح. للترقية يدويًا، شغّل brew upgrade claude-code (أو brew upgrade claude-code@latest) أو winget upgrade Anthropic.ClaudeCode. تقدر تتحكم في قناة الإصدار بإعداد autoUpdatesChannel — "latest" (الافتراضي) بتجيب الميزات الجديدة فورًا، بينما "stable" بتستخدم إصدار عمره حوالي أسبوع وبتتخطى الإصدارات اللي فيها مشاكل كبيرة. لإيقاف التحديثات التلقائية نهائيًا، اضبط DISABLE_AUTOUPDATER على "1" في بلوك الـ env في الإعدادات.

بجانب الصلاحيات، إعدادات مفيدة تانية تشمل env لمتغيرات البيئة اللي لازم تكون موجودة في كل جلسة، agent عشان تحدد agent افتراضي مخصص، وclaudeMdExcludes لفلترة ملفات الذاكرة اللي مش ليها علاقة في الـ monorepos. كمان تقدر تحدد الموديل الافتراضي ومستوى الـ effort:

{
  "model": "claude-sonnet-4-6",
  "env": {
    "NODE_ENV": "development",
    "LOG_LEVEL": "debug"
  }
}

ضيف .claude/settings.local.json في .gitignore عشان التعديلات الشخصية تفضل شخصية. شارك .claude/settings.json، CLAUDE.md، .claude/rules/، .claude/skills/، واختياريًا .claude/agents/ مع الفريق عن طريق git. كده زملائك هياخدوا نفس تعليمات المشروع والـ extensions المشتركة، بينما الإعدادات الشخصية والذاكرة التلقائية تفضل محلية على كل جهاز.