# دليل إعداد CLAUDE.md

`CLAUDE.md` هو **ملف الإعداد على مستوى المشروع** في Claude Code. كلما بدأ Claude Code، يقرأ تلقائيًا ملف `CLAUDE.md` الخاص بالمشروع لمعرفة بنية المشروع واصطلاحات البرمجة والاتفاقات الخاصة، ما يتيح له فهم مشروعك بدقة أكبر.

## لماذا تحتاج إلى CLAUDE.md

بدون CLAUDE.md، قد تحتاج إلى أن تكرر الشرح في كل محادثة:
- "يستخدم هذا المشروع pnpm، وليس npm"
- "أمر الاختبار هو `yarn test:unit`، وليس `npm test`"
- "جميع المكوّنات تستخدم TypeScript — لا أنواع `any`"

اكتب هذه المعلومات في CLAUDE.md وسيقرأها Claude تلقائيًا عند كل بدء، فلن تحتاج إلى تكرار نفسك أبدًا.

## هرمية الملفات

يقرأ Claude Code ملفات CLAUDE.md من مستويات متعددة ويدمجها:

| الموقع | النطاق |
|----------|-------|
| `~/.claude/CLAUDE.md` | إعداد عام، ينطبق على جميع المشاريع |
| `<project root>/CLAUDE.md` | إعداد المشروع، يُودَع في Git لمشاركته مع الفريق |
| `.claude/CLAUDE.md` | إعداد خاص بالمشروع، يمكن إضافته إلى `.gitignore` |
| `CLAUDE.md` في دليل فرعي | لا يُقرأ إلا عندما يعمل Claude في ذلك الدليل |

## الإعداد السريع

استخدم الأمر `/init` لإنشائه تلقائيًا:

```
/init
```

سيحلل Claude بنية المشروع الحالية وينشئ تلقائيًا ملف CLAUDE.md مملوءًا بمعلومات المشروع.

## البنية الأساسية

```markdown
# Project Name

## Overview
Brief description of the project's purpose and tech stack.

## Tech Stack
- Runtime: Node.js 20
- Framework: Next.js 15
- Styling: Tailwind CSS
- Database: PostgreSQL + Prisma

## Common Commands
- Start dev server: `npm run dev`
- Run tests: `npm test`
- Build for production: `npm run build`
- Lint code: `npm run lint`

## Coding Conventions
- Use TypeScript; no `any` types allowed
- Components use functional style
- Styling with Tailwind only — no inline styles
- Commit message format: `feat:` / `fix:` / `docs:` prefixes, etc.

## Project Structure
- `src/app/` — Next.js App Router pages
- `src/components/` — Reusable components
- `src/lib/` — Utility functions
- `prisma/` — Database schema and migrations

## Notes
- Do not modify `prisma/migrations/` — only create new migrations
- All API routes are under `src/app/api/`
- Image assets go in `public/images/`
```
## نصائح عملية

### 1. حدّد مدير الحزم

```markdown
## Package Management
Use pnpm — do not use npm or yarn.
Install dependencies: `pnpm install`
Add a dependency: `pnpm add <package>`
```

### 2. وثّق اصطلاحات الاختبار

```markdown
## Testing
- Unit tests: `vitest`, files end in `.test.ts`
- E2E tests: `playwright`, located in `tests/e2e/`
- Run unit tests: `pnpm test:unit`
- Run E2E: `pnpm test:e2e`
- New features must include tests
```

### 3. حدّد الإجراءات المحظورة

```markdown
## Prohibited Actions
- Do not use `console.log` — use the project's `logger` module instead
- Do not modify `package-lock.json` directly
- Do not commit directly to `main` — use feature branches
```

### 4. وفّر سياقًا معماريًا

```markdown
## Architecture Overview
This project follows Hexagonal Architecture:
- `domain/` — Business logic, no external framework dependencies
- `application/` — Use cases, coordinating domain and infrastructure
- `infrastructure/` — External adapters for databases, HTTP, etc.
- `interfaces/` — Entry points such as web controllers and CLI

New features should follow this layering — do not introduce external dependencies in the domain layer.
```

### 5. أشر إلى وثائق أخرى

```markdown
## Further Reading
- API documentation: `docs/api.md`
- Deployment process: `docs/deploy.md`
- Database schema: `prisma/schema.prisma`
```

## CLAUDE.md وإدارة السياق

تستهلك محتويات CLAUDE.md مساحة السياق. توصيات:
- أبقِ CLAUDE.md موجزًا ومركّزًا على أهم المعلومات
- بالنسبة إلى وثائق معمارية مفصّلة، قدّم إشارات إلى مسارات الملفات في CLAUDE.md بدلًا من نسخ المحتوى مباشرة
- في الجلسات الطويلة، يبقى CLAUDE.md ظاهرًا دائمًا (لن يزيله `/compact`)

## قوالب المشاريع

البنى أدناه نقاط بداية مجرّبة لملف CLAUDE.md لأنواع المشاريع الشائعة. انسخ ما يطابق حزمة تقنياتك وكيّف التفاصيل.

### القالب 1: واجهة أمامية React + TypeScript

```markdown
# MyApp Frontend

## Tech Stack
- React 19 + TypeScript 5.x
- Build tool: Vite 6
- Styling: Tailwind CSS v4 (utility-first, no inline styles)
- State management: Zustand (global), TanStack Query (server state)
- Routing: React Router v7
- Testing: Vitest + Testing Library + MSW

## Commands
- Dev: `pnpm dev` (port 3000)
- Test: `pnpm test` (Vitest watch mode)
- Single run: `pnpm test:run`
- Build: `pnpm build`
- Lint: `pnpm lint` (ESLint + Prettier)
- Type check: `pnpm typecheck`

## Coding Conventions
- Components: functional components + Hooks, no class components
- Props: define with `interface` (not `type`)
- File names: components in PascalCase (UserProfile.tsx), utilities in camelCase (formatDate.ts)
- Import order: React → third-party → internal → styles
- No `any` type; explicit type annotations are required
- Async work goes through TanStack Query, not direct `useEffect` + `fetch`

## Project Structure
- src/components/ — reusable UI components
- src/pages/ — route pages
- src/hooks/ — custom Hooks
- src/api/ — API request wrappers (TanStack Query queryFn)
- src/stores/ — Zustand stores
- src/lib/ — utility functions
- src/types/ — global type definitions

## Notes
- Package manager: pnpm (not npm or yarn)
- Node.js 22+
- All API requests go through src/api/client.ts (with interceptors)
- Images live in public/images/, referenced via the /images/ path
```

### القالب 2: الواجهة الخلفية Python + FastAPI

```markdown
# MyApp Backend

## Tech Stack
- Python 3.12 + FastAPI
- ORM: SQLAlchemy 2.0 (async) + Alembic migrations
- Database: PostgreSQL 16
- Cache: Redis 7
- Testing: pytest + httpx + factory_boy

## Commands
- Dev: `uvicorn app.main:app --reload --port 8000`
- Test: `pytest -xvs`
- Migrate: `alembic upgrade head`
- New migration: `alembic revision --autogenerate -m "description"`
- Lint: `ruff check .`
- Format: `ruff format .`
- Type check: `mypy app/`

## Coding Conventions
- Type hints: all function parameters and return values must have type hints
- async/await: all I/O operations use async
- Pydantic v2: request/response schemas use Pydantic BaseModel
- Dependency injection: inject database connections, auth, etc. via FastAPI Depends()
- Error handling: business exceptions inherit from app.exceptions.AppError

## Project Structure
- app/main.py — application entry point
- app/api/ — routes (one file per resource)
- app/models/ — SQLAlchemy models
- app/schemas/ — Pydantic schemas
- app/services/ — business logic
- app/core/ — config, database, security, and other core modules
- tests/ — test files (mirror the app/ structure)
- alembic/ — database migrations

## Notes
- Do not modify existing migration files under alembic/versions/
- The .env file is not committed to Git; it is loaded via the Settings class in app/core/config.py
- Virtual environment: `python -m venv venv && source venv/bin/activate`
```

### القالب 3: خدمة مصغّرة بـ Go

```markdown
# MyService

## Tech Stack
- Go 1.23
- HTTP framework: Echo v4
- Database: PostgreSQL + sqlc (type-safe SQL)
- Message queue: NATS JetStream
- Containerization: Docker + docker-compose

## Commands
- Run: `go run ./cmd/server`
- Test: `go test ./...`
- Build: `go build -o bin/server ./cmd/server`
- Generate sqlc: `sqlc generate`
- Lint: `golangci-lint run`

## Coding Conventions
- Error handling: always check err, never ignore it with _
- Interface naming: single-method interfaces take the -er suffix (Reader, Writer)
- Package naming: lowercase words, no underscores
- Logging: use slog for structured logging
- Context: pass context.Context as the first parameter of every function

## Project Structure (standard Go layout)
- cmd/server/ — main program entry point
- internal/handler/ — HTTP handlers
- internal/service/ — business logic
- internal/repository/ — data access layer
- internal/model/ — data models
- sql/ — SQL query files (used by sqlc)
```

### القالب 4: مستودع أحادي (Turborepo)

```markdown
# MyPlatform Monorepo

## Tech Stack
- Package management: pnpm workspace
- Build system: Turborepo
- Language: TypeScript across the stack

## Commands
- Global dev: `pnpm dev`
- Global test: `pnpm test`
- Global build: `pnpm build`
- Single-package dev: `pnpm --filter @myplatform/web dev`
- Add a dependency: `pnpm --filter @myplatform/api add express`

## Package Structure
- apps/web/ — Next.js frontend
- apps/api/ — Express backend
- apps/admin/ — admin dashboard
- packages/ui/ — shared UI component library
- packages/config/ — shared config (eslint, tsconfig)
- packages/types/ — shared type definitions

## Notes
- Shared code goes in packages/; do not import directly between apps
- When creating a new package, follow the format of packages/ui/package.json
- Turborepo cache: build artifacts are cached in node_modules/.cache/turbo
```

### القالب 5: مشروع علم البيانات / تعلّم الآلة

```markdown
# ML Pipeline

## Tech Stack
- Python 3.12
- Framework: PyTorch 2.5 + Lightning
- Data processing: Polars (not Pandas)
- Experiment tracking: MLflow
- Dependency management: uv

## Commands
- Train: `python -m src.train --config configs/experiment.yaml`
- Evaluate: `python -m src.evaluate --checkpoint runs/latest`
- Preprocess data: `python -m src.preprocess --data-dir data/raw`
- Jupyter: `jupyter lab`
- Test: `pytest tests/`

## Coding Conventions
- Use YAML for configuration (do not hard-code hyperparameters)
- Use Polars for data processing (faster than Pandas, type-safe)
- All experiments must be logged to MLflow
- Notebooks are for exploration only; production code must live in src/

## Project Structure
- configs/ — experiment configuration YAML
- data/raw/ — raw data (not committed to Git, managed with DVC)
- data/processed/ — processed data
- src/ — core code (model, data, train, evaluate)
- notebooks/ — exploratory analysis
- runs/ — training outputs (checkpoints, logs)
```
## أفضل ممارسات التعاون داخل الفريق

### استراتيجية Git

```
CLAUDE.md          → commit to Git (shared by the team)
.claude/CLAUDE.md  → add to .gitignore (personal configuration)
```

أضف ما يلي إلى `.gitignore`:

```gitignore
# Personal Claude Code configuration
.claude/CLAUDE.md
.claude/settings.local.json
```

### قائمة تحقق مراجعة الشيفرة

عند مراجعة كل PR، تحقق مما يلي:
- هل حُدِّث CLAUDE.md عند إدخال تقنية جديدة؟
- هل حُدِّث قسم «Project Structure» عند تغيّر بنية المشروع؟
- هل حُدِّث قسم «Commands» عند إضافة أمر مهم؟

### دليل تأهيل الأعضاء الجدد

يعمل CLAUDE.md أيضًا كأفضل وثيقة تأهيل لمشروع:
1. بعد استنساخ المشروع، يقرأ المطوّر الجديد CLAUDE.md لفهم الصورة العامة
2. يشغّل `claude` → يعرف Claude مسبقًا كل اصطلاحات المشروع
3. يبدأ الاستكشاف باستخدام `> help me understand this project`

---

## نصائح متقدمة

### أَشِر، لا تُضمّن

يجب ألا يصبح CLAUDE.md طويلًا جدًا. للوثائق المفصلة، أَشِر إلى المسار بدلًا من تضمين المحتوى:

```markdown
## Architecture
Detailed architecture doc: `docs/architecture.md`.
API design conventions: `docs/api-design.md`.
Database schema: `prisma/schema.prisma`.
```

يقرأ Claude تلك الملفات تلقائيًا عندما يحتاج إليها.

### العلاقة بـ AGENTS.md

| | CLAUDE.md | AGENTS.md |
|---|---|---|
| الأداة | Claude Code | Codex CLI |
| التنسيق | Markdown | Markdown |
| المحتوى | يمكن إعادة استخدام 80%+ | يمكن إعادة استخدام 80%+ |

إذا كنت تستخدم Claude Code وCodex معًا، فيمكن للملفين أن يتعايشا:
- **المحتوى المشترك**: مجموعة التقنيات، والأوامر، ومعايير كتابة الشيفرة، وبنية المشروع
- **الخاص بكل أداة**: توجيهات `/model` و `/plan` الخاصة بـ Claude توضع في CLAUDE.md؛ وإعدادات وضع الموافقة الخاصة بـ Codex توضع في AGENTS.md

> راجع [دليل AGENTS.md](/docs/usage/agents-md).

### التحكم في استخدام السياق

يظل محتوى CLAUDE.md دائمًا في السياق (لا يزيله `/compact` أبدًا). التوصيات:

- **أبقِ الإجمالي أقل من 500 سطر**
- أَشِر إلى المسارات بدلًا من تضمين الوثائق المفصلة
- لا تضع فيه معلومات تتغير كثيرًا (مثل التقدم الحالي)
- لا تضع فيه أمثلة شيفرة (يمكن لـ Claude قراءة المصدر بنفسه)

---

## الأخطاء الشائعة وتصحيح الأخطاء

### لا تتم قراءة CLAUDE.md

```bash
# Confirm the file is in the project root
ls -la CLAUDE.md

# Confirm Claude sees it
claude
> Do you see CLAUDE.md? What tech stack does it describe?
```

### طوله المفرط يستنزف السياق

```bash
# Check the line count
wc -l CLAUDE.md
# Over 500 lines: trim it

# Check context usage
/cost
```

### اختلاف سلوك أعضاء الفريق

يختلف ملف `~/.claude/CLAUDE.md` العام لدى كل شخص. إذا لاحظ الفريق سلوكًا غير متسق، فتحقق مما يلي:
1. هل CLAUDE.md في جذر المشروع محدد بما يكفي؟
2. هل تجاوز أحدهم قواعد الفريق في `.claude/CLAUDE.md`؟

---
## CLAUDE.md مقابل AGENTS.md — كيف تختار

يقرأ Claude Code ملف `CLAUDE.md` أصلاً (إلى جانب ملفات الذاكرة وقواعد النطاق المساري الخاصة به). أما معظم الأدوات **الأخرى** — مثل Cursor وCodex وGitHub Copilot وCline وGemini / Antigravity وAider وZed وغيرها — فتقرأ `AGENTS.md` بدلاً من ذلك. يعتمد الملف الذي تحتفظ به على عدد الأدوات التي يستخدمها فريقك.

| السيناريو | التوصية |
|----------|----------------|
| **أداة واحدة (Claude Code فقط)** | يكفي `CLAUDE.md` — لا حاجة إلى AGENTS.md |
| **فريق متعدد الأدوات** | احتفظ بـ `AGENTS.md` كمصدر مشترك للحقيقة، مع ملف `CLAUDE.md` رفيع يستورده |

### أداة واحدة: CLAUDE.md وحده

إذا كان جميع أفراد الفريق يستخدمون Claude Code، فضع كل شيء في `CLAUDE.md`. لا فائدة تُرجى من ملف ثانٍ.

### تعدد الأدوات: AGENTS.md كمصدر للحقيقة

عندما يمزج الفريق بين Claude Code وCursor وCodex وCopilot وغيرها، فاحتفظ بالقواعد المشتركة — مكدس التقنيات والأوامر واصطلاحات البرمجة وبنية المشروع — في `AGENTS.md`، ثم اجعل `CLAUDE.md` ملفًا رفيعًا يستورده ويضيف إضافات خاصة بـ Claude:

```markdown
# Project Rules

@AGENTS.md

## Claude Code specifics
- Use /model to switch to Opus 4.8 for large refactors
- Reference docs/architecture.md instead of pasting it
```

يسحب سطر `@AGENTS.md` المحتوى المشترك إلى سياق Claude Code، فيحصل Claude على قواعد الفريق **إضافةً إلى** إضافاته الخاصة بـ Claude. **تجنّب الاحتفاظ بنسختين متباعدتين** من القواعد نفسها — فهذا هو المأزق الرئيسي، لأن الملفين ينحرفان عن التزامن حتمًا.

> لتفاصيل صيغة AGENTS.md وأدواتها، راجع [دليل إعداد AGENTS.md](/docs/usage/agents-md).

## الخطوات التالية

- تعرّف على [إدارة السياق](/docs/usage/context-management) — أتقن تقنيات إدارة نافذة السياق
- تعرّف على [إعداد الأذونات](/docs/usage/permissions) — تحكّم في العمليات المسموح لـ Claude بتنفيذها
- تعرّف على [نصائح سير العمل](/docs/usage/workflow-tips) — أنشئ سير عمل فعّالًا في Claude Code