إعداد 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 ما يقدرش يشغّلها تلقائيًا أبدًا.

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

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

بجانب الصلاحيات، إعدادات مفيدة تانية تشمل 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 المشتركة، بينما الإعدادات الشخصية والذاكرة التلقائية تفضل محلية على كل جهاز.