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

إعداد مشروع Claude Code — يجعل إعداد مشروع Claude Code السليم كل جلسة أسرع. تعلّم استخدام /init، وتوليد CLAUDE.md، وضبط القواعد الخاصة بالمسارات، وتعيين التفضيلات المحلية.

إعداد مشروع Claude Code: ماذا ستتعلم

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

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

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

ابدأ بـ /init. يفحص Claude قاعدة شيفرتك — قارئًا package.json والوثائق الموجودة وبنية المجلدات — ويولّد ملف CLAUDE.md يلتقط حزمتك التقنية والأوامر الأساسية والاصطلاحات الأولية. أودِع هذا الملف في git فورًا ليحصل زملاؤك على السياق نفسه.

ملف CLAUDE.md الجيد موجز ومحدد. اهدف إلى أقل من 200 سطر لكل ملف. ينبغي أن يكون كل سطر ذا صلة بكل جلسة تقريبًا — فإن كان شيء ما مهمًا لميزة واحدة فقط، فضعه في ملف قواعد محصور بمسار بدلًا من ذلك. أكثر الأقسام قيمة هي: الحزمة التقنية والإصدارات، وأوامر التطوير (التثبيت، الاختبار، البناء، التدقيق)، والاصطلاحات التي ليست بديهية، والمزالق المعروفة التي قد تعثر مطورًا جديدًا.

# 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. أضف أنماطًا للأوامر التي سيستخدمها Claude مرارًا. استخدم Bash(git *) للسماح بكل أوامر git، أو Bash(npm *) لـ npm، أو Bash(npx jest *) لأداة محددة. يمكن حصر عمليات الملفات في مسارات بعينها.

تتحكم ملفات الإعدادات في الأذونات على مستوى المشروع والمستخدم. يُودَع .claude/settings.json في git للفريق. أما .claude/settings.local.json فيُستثنى من git للتجاوزات الشخصية:

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

أما العمليات الحساسة مثل عمليات النشر للإنتاج، فاتركها تتطلب الموافقة أو استخدم disable-model-invocation: true على المهارات حتى لا يتمكن Claude من تشغيلها تلقائيًا أبدًا.

عندما تحتاج مهمة إلى ملفات خارج جذر المشروع — مكتبة شقيقة، أو حزمة أنواع مشتركة، أو حزمة مولَّدة — استخدم --add-dir عند الإطلاق (أو /add-dir أثناء الجلسة) لتوسيع أدلة عمل Claude لتلك الجلسة. يجب أن يوجد كل مسار كدليل، ويمنح هذا الخيار صلاحية الوصول إلى الملفات فقط، لا بقية إعدادات .claude/ في تلك الشجرة:

# Start a session with read/edit access in two sibling directories
claude --add-dir ../shared-types --add-dir ../design-tokens

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

الأمان — قيود السوق

استخدم blockedMarketplaces لتقييد أسواق الإضافات التي يمكن استخدامها. تدعم المُدخلات hostPattern للحظر حسب النطاق (مثل "*.example.com") وpathPattern للحظر حسب مسار المستودع (مثل "acme/corp-plugins"):

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

يُفرض هذا على مستوى السياسة — لا يمكن للمستخدمين تجاوزه بالإعدادات المحلية. متوفر ضمن السياسة المُدارة لعمليات النشر المؤسسية.

عند كتابة بيانات إضافات (manifests) لمشروعك، لاحظ أن monitors وthemes تجريبية وينبغي التصريح بها ضمن experimental: {} بدلًا من المستوى الأعلى من plugin.json. لا تزال التصريحات في المستوى الأعلى تعمل، لكن claude plugin validate سيحذّر، وسيتطلب إصدار مستقبلي الصيغة المتداخلة.

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

تتبع الإعدادات هذه الأولوية من الأعلى إلى الأدنى: (1) الإعدادات المُدارة (لا يمكن تجاوزها بأي شيء، بما في ذلك وسائط سطر الأوامر)، (2) وسائط سطر الأوامر، (3) المحلية (.claude/settings.local.json) — التي تتجاوز إعدادات المشروع والمستخدم، (4) المشروع (.claude/settings.json)، (5) المستخدم (~/.claude/settings.json). تتجاوز الإعدادات المحلية إعدادات المشروع، لا العكس. يمكن أن يستخدم التسليم المُدار ملفات سياسة المنصة أو أدلة الضبط المُدارة، لكن تلك تفاصيل تنفيذية للطبقة المُدارة العليا وليست نطاقات يومية منفصلة.

يحدّث المثبّت الأصلي نفسه تلقائيًا في الخلفية افتراضيًا. أما عمليات تثبيت Homebrew وWinGet فلا تحدّث نفسها تلقائيًا افتراضيًا — للاشتراك، عيّن CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1. عندئذٍ سيشغّل Claude Code ترقية مدير الحزم في الخلفية عند توفر إصدار جديد، ويطالبك بإعادة التشغيل عند النجاح.

للترقية يدويًا بدلًا من ذلك، شغّل brew upgrade claude-code (أو brew upgrade claude-code@latest) أو winget upgrade Anthropic.ClaudeCode. يمكنك التحكم في قناة الإصدار بإعداد autoUpdatesChannel — تتلقى "latest" (الافتراضي) الميزات الجديدة فورًا، بينما تستخدم "stable" إصدارًا أقدم بنحو أسبوع يتخطى الإصدارات ذات التراجعات الكبرى. لتعطيل التحديثات التلقائية بالكامل، عيّن DISABLE_UPDATES إلى "1" في كتلة env بإعداداتك — يحظر هذا كل مسارات التحديث بما فيها claude update اليدوي. ولخيار أقل صرامة، يكبت DISABLE_AUTOUPDATER إشعارات تحديث مدير الحزم فقط.

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

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

أمثلة شيفرة واقعية: ضبط الذاكرة

المثال 1: ملف CLAUDE.md للمشروع

ملف ضبط مشروع شامل يعرّف البنية والمعايير والاصطلاحات:

# Project Configuration

## Project Overview
- Name: E-commerce Platform
- Tech Stack: Node.js, PostgreSQL, React 18, Docker
- Team Size: 5 developers

## Architecture
@docs/architecture.md
@docs/api-standards.md
@docs/database-schema.md

## Development Standards

### Code Style
- Use Prettier for formatting
- Use ESLint with airbnb config
- Maximum line length: 100 characters

### Naming Conventions
- Files: kebab-case (user-controller.js)
- Classes: PascalCase (UserService)
- Functions/Variables: camelCase (getUserById)

### Git Workflow
- Branch names: feature/description or fix/description
- Commit messages: Follow conventional commits
- PR required before merge

المثال 2: ملف CLAUDE.local.md الشخصي (غير مُودَع في Git)

تفضيلات شخصية تبقى محلية ولا تُشارك مع الفريق أبدًا:

# My Development Preferences

## About Me
- Experience Level: 8 years full-stack development
- Preferred Languages: TypeScript, Python
- Communication Style: Direct, with examples

## Code Preferences

### Error Handling
I prefer explicit error handling with try-catch blocks.
Avoid generic errors. Always log errors for debugging.

### Testing
I prefer TDD (test-driven development).
Write tests first, then implementation.

### Architecture
I prefer modular, loosely-coupled design.
Use dependency injection for testability.

المثال 3: قواعد محصورة بدليل لـ src/api/

ملف CLAUDE.md موضوع في src/api/ يتجاوز إعدادات الجذر لذلك الدليل:

# API Module Standards

This file overrides root CLAUDE.md for everything in /src/api/

### Request Validation
- Use Zod for schema validation
- Always validate input
- Return 400 with validation errors

### Authentication
- All endpoints require JWT token
- Token in Authorization header
- Token expires after 24 hours

### Response Format
{
  "success": true,
  "data": {},
  "timestamp": "2025-11-06T10:30:00Z",
  "version": "1.0"
}

### Rate Limiting
- 1000 requests per hour for authenticated users
- 100 requests per hour for public endpoints

نصائح احترافية

• القليل أفضل في CLAUDE.md. أدرج فقط المعلومات ذات الصلة بكل جلسة — اسم المشروع، والحزمة التقنية، والأوامر الأساسية، والاصطلاحات غير البديهية. أبقِه دون 300 سطر. كل ما عدا ذلك يذهب إلى قواعد مُجزّأة أو @imports.
• استخدم القواعد المُجزّأة للتجاوزات الخاصة بالمسارات. بدلًا من ملف CLAUDE.md عملاق واحد، أنشئ ملفات .claude/rules/*.md مع ترويسة YAML paths. يبقي هذا السياق رشيقًا — إذ لا تُحمَّل القواعد إلا عندما تعمل في أدلة مطابقة.
• لا تولّد CLAUDE.md تلقائيًا أبدًا. صُغه يدويًا بعناية متأنية. تميل الملفات المولَّدة تلقائيًا إلى الإسهاب والعمومية والامتلاء بمعلومات قليلة القيمة تهدر رموز السياق.
• أودِع ذاكرة المشروع في git. ينبغي وضع CLAUDE.md و.claude/rules/ تحت التحكم بالإصدارات ليستفيد الفريق كله. استخدم CLAUDE.local.md (المستثنى من git) للتفضيلات الشخصية الخاصة بالمشروع.
• استخدم /team-onboarding لتوليد أدلة التهيئة. يفحص هذا الأمر المدمج ملف CLAUDE.md والمهارات والضبط لينتج تلقائيًا وثيقة تهيئة — مثالية لرفع كفاءة زملاء جدد بسرعة.

تحدٍّ تطبيقي: تهيئة مشروع بـ CLAUDE.md + المهارات

المهمة: اضبط ضبطًا كاملًا لمشروع Claude Code — ملف CLAUDE.md مُحكم الصياغة، ودليل قواعد مُجزّأ، ومهارة خاصة بالمشروع — حتى يصبح زميل جديد منتجًا في دقائق.

الخطوات

1. أنشئ ملف CLAUDE.md جذريًا يحتوي: اسم المشروع، والحزمة التقنية، وأوامر التطوير الأساسية (npm run dev، npm test، إلخ)، و3–5 اصطلاحات حرجة
2. أنشئ .claude/rules/testing.md بقواعد خاصة بالمسار باستخدام الترويسة: paths: ["tests/**/*.ts"] — مثل: “استخدم Jest، اتبع نمط AAA، حاكِ الاستدعاءات الخارجية”
3. أنشئ .claude/rules/api.md بترويسة paths: ["src/api/**/*.ts"] — مثل: “تتطلب جميع نقاط النهاية التحقق من الإدخال وتعيد مغلَّف JSON قياسيًا”
4. أنشئ مهارة مشروع في .claude/skills/onboarding/SKILL.md تولّد دليل تهيئة بقراءة بنية المشروع وملف CLAUDE.md والمهارات المتاحة
5. شغّل /onboarding لتوليد وثيقة تهيئة لزميل، ثم تحقق من أنها تعكس بدقة إعداد مشروعك

النتيجة المتوقعة

ينبغي أن يحصل مطور جديد يشغّل /onboarding على دليل شامل يغطي غرض المشروع، والحزمة التقنية، وأوامر التطوير، واصطلاحات الشيفرة، والمهارات المتاحة، ومتطلبات الاختبار — مستمدًّا كله من ملفات الضبط لديك.

تلميح: استخدم الأمر المدمج /team-onboarding (الإصدار v2.1.101 فما فوق) كنقطة انطلاق. يفحص ملف CLAUDE.md والمهارات المثبتة والخطافات (hooks) ليولّد تلقائيًا دليل تهيئة. خصّص المخرجات بإثراء ملف CLAUDE.md أولًا.

اختبار المعرفة: إعداد مشروع Claude Code الخاص بك

اختبر فهمك بأسئلة الاختبار هذه. حاول الإجابة عن كل سؤال قبل كشف الإجابة.

1. ماذا يفعل الأمر /init؟

1. يهيئ مشروع Claude Code جديدًا من الصفر
2. يولّد قالب CLAUDE.md بناءً على بنية مشروعك
3. يعيد ضبط كل الذاكرة إلى الافتراضيات
4. ينشئ جلسة جديدة

الإجابة الصحيحة: B. يحلّل /init مشروعك ويولّد قالب CLAUDE.md مع قواعد ومعايير مقترحة. إنه أداة إقلاع لمرة واحدة.

2. تريد تفضيلات مشروع شخصية لا تُودَع في git. أي ملف ينبغي أن تستخدم؟

1. ~/.claude/CLAUDE.md
2. CLAUDE.local.md
3. .claude/rules/personal.md
4. .claude/memory/personal.md

الإجابة الصحيحة: B. ملف CLAUDE.local.md في جذر المشروع مخصص للتفضيلات الشخصية الخاصة بالمشروع. ينبغي استثناؤه من git.

3. كيف تحصر ملف قاعدة ليُطبَّق فقط على الملفات في src/api/؟

1. ضع القاعدة في src/api/CLAUDE.md
2. أضف ترويسة YAML بالشكل paths: src/api/** إلى ملف .claude/rules/*.md
3. سمِّ الملف .claude/rules/api.md
4. استخدم @scope: src/api في ملف القاعدة

الإجابة الصحيحة: B. تدعم الملفات في .claude/rules/ حقل ترويسة paths: بأنماط glob لحصر القواعد بأدلة محددة.

4. ما العمق الأقصى لعمليات الاستيراد @path/to/file في CLAUDE.md؟

1. 3 مستويات عمقًا
2. 5 مستويات عمقًا
3. 10 مستويات عمقًا
4. غير محدود

الإجابة الصحيحة: B. تدعم صيغة @import الاستيراد التعاودي حتى عمق أقصى قدره 5 لمنع الحلقات اللانهائية.

5. تعمل عبر مستودعين وتريد أن يحمّل Claude ملف CLAUDE.md من كليهما. أي خيار تستخدم؟

1. –multi-repo
2. –add-dir /path/to/other
3. –include /path/to/other
4. –merge-context /path/to/other

الإجابة الصحيحة: B. يحمّل الخيار –add-dir ملف CLAUDE.md من أدلة إضافية، متيحًا سياقًا متعدد المستودعات.

موارد إضافية

هل يجب أن أُعدّ كل مشروع من الصفر؟

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

ما الشيء الأكثر فائدة لضبطه على الإطلاق؟

أوامر البناء والاختبار والتدقيق. بتسجيلها، يستطيع المساعد التحقق من تغييراته بنفسه قبل تسليمها.

كيف تعمل المستودعات الأحادية؟

استخدم قواعد خاصة بالمسارات حتى يحصل كل مجلد على الاصطلاحات الصحيحة دون تضخيم ملف الضبط الجذري.

جمع كل ذلك معًا

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

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

دليل إعداد مشروع Claude Code: الأسئلة الشائعة

كيف تختلف صلاحيات الأدوات بين وضعي التطوير والإنتاج عند الإعداد؟

عادة تُمنَح صلاحيات أوسع في بيئة التطوير المحلية لتسريع التكرار، بينما تُقيَّد الصلاحيات في السياقات الحساسة (كخط الإنتاج) إلى الحد الأدنى الضروري فقط — قراءة بلا كتابة، أو أوامر محددة سلفًا بدل الوصول الحر للصدفة.

لماذا يُنصح بتسجيل أوامر البناء والاختبار والتدقيق ضمن ملف الإعداد؟

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

ما الذي يجب أن يبقى خارج الإعداد المشترك ويظل محليًا فقط؟

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

هل تحتاج قائمة التحقق القابلة للتكرار إلى تحديث مع كل مشروع جديد؟

تبقى بنيتها العامة ثابتة، لكن التفاصيل (أوامر البناء، مسارات الحزم، قيود الأمان) تتغير حسب المكدس التقني. الأفضل معاملتها كقالب يُعدَّل لا كنسخة تُكتب من الصفر في كل مرة.

هل يمكن ربط إعداد المشروع بخطوط CI/CD الموجودة أصلًا؟

نعم — سجّل نفس أوامر البناء والاختبار المستخدَمة في CI داخل ملف الإعداد كي يعمل المساعد بنفس المعايير التي يعمل بها خط التكامل المستمر، فلا تظهر فروق بين ما يوافق عليه محليًا وما يفشل لاحقًا في CI.

إعداد مشروع Claude Code يمنحك سير عمل متينًا قابلًا للتكرار. احفظ هذا الدليل عن إعداد مشروع Claude Code وعُد إلى الخطوات كلما احتجت إليها.

قائمة تحقق إعداد قابلة للتكرار

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

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

للمستودعات الأكبر، اعتمد على القواعد الخاصة بالمسارات. يمكن لمستودع أحادي به خدمة Python في مجلد وتطبيق TypeScript في آخر أن يمنح كلًّا منهما اصطلاحاته الخاصة دون تضخيم الملف الجذري. عندئذٍ يطبّق المساعد القواعد الصحيحة تلقائيًا بناءً على الملفات التي يعمل فيها.

إعداد مشروع Claude Code: أخطاء شائعة يجب تجنّبها

يكرّر كثير من الفرق العقبات نفسها عند تهيئة مشروع جديد لـ Claude Code. تجنّب هذه الأخطاء يوفّر عليك جلسات كاملة من التصحيح لاحقًا.

• ترك ملف CLAUDE.md بصيغته المولَّدة تلقائيًا دون تنقيح، فيمتلئ بمعلومات عامة لا قيمة سياقية فعلية لها.
• خلط الأذونات الشخصية مع أذونات الفريق في .claude/settings.json نفسه، بدلًا من فصلها إلى .claude/settings.local.json غير المُودَع.
• كتابة ملف ضبط عملاق واحد لكل شيء بدل تقسيمه إلى قواعد محصورة بمسارات، ما يُثقل السياق في مستودعات monorepo الكبيرة.
• نسيان إضافة .claude/settings.local.json إلى .gitignore، فتتسرّب تفضيلات شخصية أو مسارات محلية إلى بقية الفريق عبر git.

إعداد مشروع Claude Code: أفضل الممارسات

• شغّل /init أولًا لتوليد هيكل CLAUDE.md تلقائيًا من قاعدة شيفرتك.
• أضف أوامر البناء والاختبار والتدقيق ليتمكن المساعد من التحقق من عمله بنفسه.
• عيّن التفضيلات المحلية لأي شيء شخصي حتى لا يُودَع أبدًا.
• استخدم ضبطًا خاصًا بالمسارات للمستودعات الأحادية ذات الحزم المختلفة لكل مجلد.
• أودِع CLAUDE.md ليشارك الفريق كله ذاكرة المشروع نفسها.