Claude Code: تهيئة المشروع والهيكل
آخر تحديث: 2026-08-31
يحلل Claude Code هيكل المشروع تلقائياً عند الدخول إليه، لكن يمكنك أيضاً توجيهه بشكل فعال عبر CLAUDE.md.
💡 نصيحة: تهيئة المشروع ليست فقط عن قراءة Claude Code للملفات — بل عن كيفية فهمه "للاتفاقيات الضمنية" مثل أسلوب البرمجة ومعايير الدليل واستراتيجيات الاختبار. CLAUDE.md هو الناقل الصريح لهذه الاتفاقيات.
📋 المتطلبات المسبقة: الفصل 5 - التكامل مع VS Code و JetBrains
1. ما ستتعلمه
- كيف يفهم Claude Code هيكل المشروع
- ميزات التهيئة لمشاريع الأطر المختلفة
- دور CLAUDE.md والتوليد التلقائي له
- نافذة السياق وحجم المشروع
- استراتيجيات تحسين المشاريع الكبيرة
2. كيف يفهم Claude Code المشاريع
(1) سير التحليل التلقائي
graph TB
A[Enter project dir] --> B[Read CLAUDE.md]
B --> C[Scan directory structure]
C --> D[Identify framework/language]
D --> E[Read key config files]
E --> F[Build context]
| الخطوة | الملفات المقروءة | الغرض |
|---|---|---|
| CLAUDE.md | CLAUDE.md الجذري | الحصول على اتفاقيات وتعليمات المشروع |
| ملفات الإعداد | package.json، pom.xml، go.mod، إلخ | تحديد الحزمة التقنية والتبعيات |
| هيكل الدليل | src/، lib/، tests/، إلخ | فهم تنظيم الكود |
| README | README.md | الحصول على نظرة عامة على المشروع |
(2) الحزم التقنية المُتعرف عليها
| ملف الإعداد | التعرف | السلوك التلقائي |
|---|---|---|
package.json |
مشروع Node.js | استخدام npm/yarn/pnpm |
pom.xml |
Java Maven | استخدام أوامر mvn |
go.mod |
مشروع Go | استخدام أوامر go |
requirements.txt |
مشروع Python | استخدام pip/pytest |
▶ مثال 1: مخرجات تحليل المشروع
TEXT
📖 للعرض فقط
$ claude
╭─ Claude Code ──────────────────────────────╮
│ Project Analysis: │
│ Type: Node.js / TypeScript │
│ Framework: Express.js │
│ Test: Jest │
│ Package: npm │
│ Structure: │
│ src/ │
│ routes/ (12 route files) │
│ models/ (8 model files) │
│ middleware/ (4 files) │
│ utils/ (6 utility files) │
│ tests/ │
│ config/ │
│ Key deps: express, mongoose, jest │
╰─────────────────────────────────────────────╯
3. إعداد مشروع CLAUDE.md
(1) التوليد التلقائي لـ CLAUDE.md
BASH
# Have Claude Code analyze project and generate CLAUDE.md
claude /init
(2) كتابة CLAUDE.md يدوياً
MARKDOWN
# CLAUDE.md
## Project Overview
E-commerce admin system, using Express + TypeScript + Prisma
## Tech Stack
- Runtime: Node.js 20
- Framework: Express 4.x
- ORM: Prisma 5.x
- Test: Vitest
- Lint: ESLint + Prettier
## Common Commands
- Dev: `npm run dev`
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`
## Code Conventions
- Use ES Module syntax
- All API responses use unified format { code, data, message }
- Error handling uses custom AppError class
- Route files go in src/routes/
- Each route file corresponds to a test file
## Don'ts
- Don't use var, only const/let
- Don't use mongoose directly, use Prisma
- Don't modify prisma/schema.prisma unless explicitly asked
▶ مثال 2: CLAUDE.md لمشاريع مختلفة
MARKDOWN
<!-- Go project CLAUDE.md -->
# CLAUDE.md
## Project
RESTful API service, Go 1.22 + Gin + GORM
## Commands
- Run: `go run ./cmd/server`
- Test: `go test ./...`
- Build: `go build -o bin/server ./cmd/server`
## Conventions
- Use standard project layout (cmd/, internal/, pkg/)
- Error returns use pkg/errors package
- All handlers receive gin.Context
- Database operations only in repository layer
4. أفضل الممارسات لهيكل المشروع
(1) هيكل صديق لـ Claude Code
| الميزة | صديق | غير صديق |
|---|---|---|
| عمق الدليل | 3-4 مستويات، تسمية واضحة | تداخل 10+ مستويات |
| تسمية الملفات | اتفاقيات تسمية متسقة | تسمية عشوائية |
| ملفات الإعداد | مواقع قياسية | متناثرة في كل مكان |
| موقع الاختبارات | مركزي أو مجاور | بلا اختبارات |
| التوثيق | README + CLAUDE.md | بلا توثيق |
5. مشاريع متعددة اللغات/الوحدات
(1) دعم Monorepo
TEXT
📖 للعرض فقط
my-monorepo/
├── CLAUDE.md # Global config
├── packages/
│ ├── frontend/
│ │ └── CLAUDE.md # Frontend sub-project config
│ ├── backend/
│ │ └── CLAUDE.md # Backend sub-project config
│ └── shared/
│ └── CLAUDE.md # Shared library config
(2) إعداد مستقل للأدلة الفرعية
BASH
# Starting Claude Code in different sub-directories reads corresponding CLAUDE.md
cd packages/frontend && claude # Reads frontend/CLAUDE.md
cd packages/backend && claude # Reads backend/CLAUDE.md
6. مثال شامل: تهيئة مشروع كاملة
BASH
# Alice's complete project initialization
# 1. Create project
mkdir ecommerce-api && cd ecommerce-api
npm init -y
# 2. Initialize git
git init
# 3. Launch Claude Code to generate project skeleton
claude "Initialize an Express + TypeScript project:
1. Configure tsconfig.json
2. Set up ESLint + Prettier
3. Create src/ directory structure (routes, controllers, models, middleware, utils)
4. Configure Jest testing
5. Create .gitignore
6. Generate CLAUDE.md"
# 4. Check generated CLAUDE.md
cat CLAUDE.md
# 5. Adjust CLAUDE.md as needed
# 6. Commit initial state
git add -A && git commit -m "feat: project initialization"
❓ أسئلة شائعة
س ما الفرق بين CLAUDE.md و README.md؟
ج README وصف مشروع للبشر؛ CLAUDE.md تعليمات عمل لـ Claude Code. CLAUDE.md يركز أكثر على اتفاقيات البرمجة والأوامر الشائعة والقيود.
س المشروع كبير جداً، Claude Code لا يستطيع قراءة كل شيء؟
ج Claude Code يختار الملفات الرئيسية بذكاء، لا يحمل كل شيء. يمكنك أيضاً تحديد نطاق العمل في CLAUDE.md لتقليل استهلاك السياق.
س هل يجب أن يكون CLAUDE.md في الدليل الجذري؟
ج CLAUDE.md الجذري إعداد عام. الأدلة الفرعية يمكن أن يكون لها CLAUDE.md أيضاً؛ Claude Code يدمجها.
س هل يجب إلتزام CLAUDE.md في git؟
ج يُوصى بذلك. اتفاقيات المشروع المشتركة للفريق أكثر قيمة من الإعدادات الفردية. لا تضع معلومات حساسة في CLAUDE.md.
س CLAUDE.md المُولّد بـ /init غير دقيق؟
ج عدّله يدوياً. /init مجرد مساعدة؛ دقة CLAUDE.md تحتاج مراجعة وتعديل بشرياً.
س هل كل حزمة في Monorepo تحتاج CLAUDE.md؟
ج ليس بالضرورة. إذا كانت الحزم متشابهة، CLAUDE.md جذري واحد يكفي. إذا كانت مختلفة جداً، يُوصى بإعدادات منفصلة.
📖 ملخص
- Claude Code يحلل هيكل المشروع تلقائياً ويُتعرف على الحزم التقنية
- CLAUDE.md هو الناقل الصريح لاتفاقيات المشروع؛
/initيمكنه توليده تلقائياً - المشاريع الصديقة لـ Claude Code: أدلة واضحة، تسمية متسقة، إعدادات قياسية
- المشاريع الكبيرة تستخدم CLAUDE.md لتحديد نطاق العمل وتقليل استهلاك Token
- Monorepo يدعم إعداد CLAUDE.md متعدد المستويات
📝 تمارين
- أساسي (⭐): شغّل
claude /initفي مشروع موجود، تحقق من دقة CLAUDE.md المُولّد. - متوسط (⭐⭐): اكتب يدوياً CLAUDE.md كاملاً باتفاقيات المشروع والأوامر الشائعة والقيود.
- متقدم (⭐⭐⭐): صمم إعداد CLAUDE.md متعدد المستويات لـ Monorepo، مع ضمان عمل كل مشروع فرعي بشكل مستقل.