# راهنمای پیکربندی 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. پس از clone کردن، توسعه‌دهنده جدید 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 قواعد تیم را **به‌همراه** افزودنی‌های مخصوص خودش دریافت می‌کند. **از نگه‌داری دو نسخه واگرا** از قواعد یکسان **خودداری کنید** — این دام اصلی است، زیرا آن دو فایل ناگزیر از هم ناهمگام می‌شوند.

> برای جزئیات درباره قالب AGENTS.md و ابزارهای آن، [راهنمای پیکربندی AGENTS.md](/docs/usage/agents-md) را ببینید.

## گام‌های بعدی

- درباره [مدیریت زمینه](/docs/usage/context-management) بیاموزید — به تکنیک‌های مدیریت پنجره زمینه مسلط شوید
- درباره [پیکربندی مجوزها](/docs/usage/permissions) بیاموزید — کنترل کنید Claude اجازه انجام کدام عملیات را دارد
- درباره [نکات گردش کار](/docs/usage/workflow-tips) بیاموزید — یک گردش کار کارآمد در Claude Code برقرار کنید