# شروع سریع

> ⚡ هنوز راه‌اندازی نکرده‌اید؟ یک فرمان همه کارها را انجام می‌دهد: `curl -fsSL https://qcode.cc/install/claude-code.sh | bash` (Windows: `irm https://qcode.cc/install/claude-code.ps1 | iex`). [اسکریپت راه‌اندازی یک‌کلیکی](/docs/getting-started/one-click-install) را ببینید.

> هنوز کلید ندارید؟ ابتدا [یک پلن انتخاب کنید و کلید خود را دریافت کنید](/docs/getting-started/choose-a-plan): کلید در هر گزینه‌ای که انتخاب کنید یکسان کار می‌کند، بنابراین مراحل زیر تغییری نمی‌کنند.

پس از تکمیل نصب و پیکربندی محیط، بیایید در 5 دقیقه بر ویژگی‌های اصلی Claude Code مسلط شویم.

## اجرای Claude Code

در ترمینال به دایرکتوری پروژه خود بروید و اجرا کنید:

```bash
cd /path/to/your/project
claude
```

رابط تعاملی Claude Code را خواهید دید که آماده شروع گفتگوست.

## تعامل‌های اصلی

### 1. درک کد

```
> What's the architecture of this project?
> Explain how src/auth/login.ts works
> Find all places that call the database
```

### 2. تولید کد

```
> Write a user registration API endpoint
> Add unit tests for the UserService class
> Create a React login form component
```

### 3. ویرایش کد موجود

```
> Refactor utils.js to improve readability
> Fix the memory leak in handleSubmit function
> Add TypeScript types to all public functions
```

### 4. اشکال‌زدایی مشکلات

```
> Why is the user redirected to 404 after login?
> Analyze this error: TypeError: Cannot read property 'id' of undefined
> Investigate why the API response is slow
```

### 5. عملیات Git

```
> Show me what files I've modified
> Commit these changes with a good commit message
> Create a PR description
```

## ارجاع به فایل‌ها با @

از نماد `@` برای ارجاع دقیق به فایل‌های مشخص استفاده کنید تا Claude بتواند محتوای آن‌ها را مستقیماً بخواند:

```
> Review @src/components/Header.tsx and optimize performance
> Compare @src/v1/api.js with @src/v2/api.js
> Analyze project dependencies based on @package.json
```

**نکته**: پس از تایپ `@`، `Tab` را فشار دهید تا مسیرهای فایل به‌صورت خودکار تکمیل شوند.

## ورودی از طریق پایپ

خروجی سایر فرمان‌ها را برای تحلیل به Claude Code بدهید:

```bash
# Explain git changes
git diff | claude "explain these code changes"

# Analyze log errors
cat error.log | claude "analyze these errors and provide solutions"

# Review PR changes
gh pr diff 123 | claude "review this PR for code quality"
```
## دستورهای اسلش رایج

در طول یک نشست از دستورهای `/` استفاده کنید:

| دستور | توضیح |
|---------|-------------|
| `/help` | نمایش اطلاعات راهنما و همه دستورهای موجود |
| `/clear` | پاک کردن تاریخچه گفتگوی فعلی |
| `/compact` | فشرده‌سازی تاریخچه گفتگو برای صرفه‌جویی در توکن‌ها |
| `/model` | مشاهده یا تغییر مدل‌ها (مثلاً opus، sonnet) |
| `/memory` | ویرایش فایل حافظه پروژه CLAUDE.md |
| `/init` | تولید خودکار پیکربندی پروژه |
| فقط بگویید «تغییرات را کامیت کنید» | Claude تغییرات را بررسی می‌کند، یک پیام کامیت می‌نویسد و کامیت می‌کند (`/commit` به یک دستور سفارشی یا یک مهارت (skill) نیاز دارد که شما یا یک افزونه فراهم می‌کنید؛ این قابلیت به‌صورت داخلی وجود ندارد) |
| `/review` | بازبینی کد |
| `/cost` | مشاهده هزینه نشست فعلی |
| `/doctor` | تشخیص مشکلات نصب و پیکربندی |
| `/config` | مشاهده یا ویرایش پیکربندی |
| `/mcp` | مشاهده وضعیت سرور MCP |
| `/loop` | اجرای Claude Code در حالت حلقه خودمختار |
| `/bug` | گزارش یک مشکل |

## میان‌برهای صفحه‌کلید

| میان‌بر | عملکرد |
|----------|----------|
| `Tab` | تکمیل خودکار مسیرهای فایل |
| `Esc` | قطع خروجی فعلی |
| `Ctrl+C` | لغو عملیات فعلی |
| `↑` / `↓` | مرور تاریخچه دستورها |

## راه‌اندازی اولیه پیکربندی پروژه

در اولین استفاده، `/init` را اجرا کنید تا Claude پروژه شما را تحلیل کند و پیکربندی تولید کند:

```
> /init
```

این کار یک فایل `CLAUDE.md` ایجاد می‌کند که شامل موارد زیر است:

- نمای کلی پشته فناوری و معماری پروژه

- دستورهای رایج ساخت و آزمون

- راهنماهای سبک کد

- قواعد مخصوص پروژه

**هدف CLAUDE.md**: Claude Code هنگام راه‌اندازی این فایل را به‌طور خودکار می‌خواند و به هوش مصنوعی کمک می‌کند زمینه پروژه شما را بهتر درک کند.

## مثال‌های کاربردی

### مثال 1: افزودن یک قابلیت جدید

```
> I need to add a user avatar upload feature with:
  1. Support for JPG/PNG formats
  2. 2MB file size limit
  3. Auto-crop to 200x200 after upload
  4. Store in S3
```

### مثال 2: رفع یک باگ

```
> User feedback: Page freezes after clicking "Save" button
> Please investigate the issue in @src/pages/EditProfile.tsx
```

### مثال 3: بازبینی کد

```
> /review
> Focus on security issues and performance bottlenecks
```

### مثال 4: کامیت هوشمند

```
> Commit these changes and write a good commit message
```

Claude به‌طور خودکار این کارها را انجام می‌دهد:

1. همه تغییرات را تحلیل می‌کند

2. یک پیام کامیت مناسب تولید می‌کند

3. کامیت را کامل می‌کند
## نکات کارایی

1. **دقیق باشید**: به‌روشنی توصیف کنید چه می‌خواهید، از جمله محدودیت‌ها

2. **آن را به بخش‌های کوچک‌تر تقسیم کنید**: کارهای پیچیده را به مراحل کوچک‌تر بشکنید

3. **وقفه را زود بزنید**: اگر خروجی آنچه می‌خواهید نیست، بلافاصله `Esc` را فشار دهید

4. **از ارجاع‌ها استفاده کنید**: از `@` برای مشخص کردن فایل‌ها استفاده کنید تا هوش مصنوعی حدس نزند

5. **زمینه را حفظ کنید**: Claude گفتگوی قبلی را در همان نشست به یاد می‌آورد

## توضیح تنظیمات کلیدی

برای شروع سریع فقط به چهار مورد نیاز دارید؛ بقیه را در صورت نیاز ببینید:

| تنظیم | چه کاری انجام می‌دهد | محل |
|---|---|---|
| `ANTHROPIC_BASE_URL` | به QCode اشاره می‌کند: `https://api.qcode.cc/api` (در سرزمین اصلی چین از `https://asia.qcode.cc/api` استفاده کنید)، بدون اسلش انتهایی | متغیر محیطی، یا بلوک `env` در `~/.claude/settings.json` |
| `ANTHROPIC_AUTH_TOKEN` | کلید QCode شما که با `cr_` شروع می‌شود | همانند بالا |
| `/model` | نمایش یا تغییر مدل در یک نشست، مثلاً `claude-sonnet-5` | فرمان درون نشست |
| `CLAUDE.md` | یادداشت‌های پروژه که در هر شروع به‌طور خودکار خوانده می‌شوند | ریشه پروژه، تولیدشده توسط `/init` |

فهرست کامل متغیرها در [متغیرهای محیطی](/docs/getting-started/environment) آمده است؛ برای راه‌اندازی یک‌مرحله‌ای، [اسکریپت راه‌اندازی یک‌کلیکی](/docs/getting-started/one-click-install) را ببینید.

## مدیریت نشست: چند فرمان رسمی

تا تاریخ 2026-10-15، بر اساس مستندات Claude Code:

- `/usage` هزینه و مصرف نشست را نشان می‌دهد و `/cost` نام مستعار آن است؛
- `claude --continue` آخرین نشست را در پوشه جاری ادامه می‌دهد، `claude --resume` فهرست نشست‌ها را برای انتخاب نشان می‌دهد، و `/resume` درون یک نشست کار می‌کند؛
- برای مشاهده یک پلن بدون اینکه به آن اجازه دهید فایل‌ها را ویرایش کند، `Shift+Tab` را فشار دهید تا بین حالت‌های مجوز جابه‌جا شوید؛ وقتی نوار وضعیت `⏸ plan mode on` را نشان می‌دهد، در حالت پلن هستید و تا زمانی که پلن را تأیید نکنید، چیزی ویرایش نمی‌شود.

## خطاهای رایج و روش عیب‌یابی

| نشانه | علت احتمالی | راه‌حل |
|---|---|---|
| `401` / `Invalid API key` | کلید اشتباه یا دارای فاصله اضافی، یا `ANTHROPIC_API_KEY` قدیمی در محیط که احراز هویت را در دست می‌گیرد | `env \| grep -i anthropic` را اجرا کنید تا باقی‌مانده‌ها را بیابید، آن‌ها را حذف کنید و ترمینال را دوباره باز کنید |
| `402` / `insufficient_quota` | سهمیه تمام شده است (روزانه، کل یا هفتگی)؛ خود کلید مشکلی ندارد | مقدار `code` در پاسخ را بررسی کنید: سهمیه روزانه در 00:00 به وقت پکن بازنشانی می‌شود و بسته‌های تقویتی در دسترس هستند؛ [کدهای خطا](/docs/reference/errors#402-quota-exhausted) را ببینید |
| 404 | `/v1` به Base URL اضافه شده است، یا اسلش انتهایی وجود دارد | آن را به `https://api.qcode.cc/api` بازگردانید |
| `model_not_available_on_endpoint` | یک مدل GPT درون Claude Code انتخاب شده است | Claude Code از رابط Anthropic استفاده می‌کند، بنابراین فقط مدل‌های Claude و مدل‌های چینی کار می‌کنند؛ برای GPT از [Codex](/docs/ide/codex) استفاده کنید |
| پاسخ‌های کند، `E015` / 429 | گفتگو بیش از حد طولانی است و زمینه به محدودیت خود نزدیک شده است | ابتدا `/compact` را اجرا کنید، اگر نتیجه نداد نشست را دوباره شروع کنید؛ [مدیریت زمینه](/docs/usage/context-management) را ببینید |
| اتصال به‌هیچ‌وجه برقرار نمی‌شود | متغیرهای شبکه یا پراکسی سیستم تداخل می‌کنند | `asia.qcode.cc` را امتحان کنید، سپس مورد 6 از [عیب‌یابی](/docs/reference/troubleshooting) را ببینید |

اگر مطمئن نیستید کدام لایه دچار خطا است، آزمون curl را از بخش 5 [نقاط پایانی و قالب‌های API](/docs/getting-started/endpoints-and-api-paths) اجرا کنید: 400 یا 401 یعنی مسیر قابل دسترسی است.
## پرسش‌های متداول

### چگونه تأیید کنم که درخواست‌ها واقعاً از QCode عبور می‌کنند؟

کلید API خود را در [probe.qcode.cc](https://probe.qcode.cc) وارد کنید تا مدل و توکن‌های آخرین درخواست‌های خود را ببینید. اگر چیزی نمایش داده نشد، درخواست‌ها هرگز به QCode نرسیده‌اند؛ بنابراین متغیرهای محیطی خود را دوباره بررسی کنید.

### کجا می‌توانم هزینه یک نشست را ببینم؟

داخل یک نشست، `/usage` (یا `/cost`) مصرف نشست جاری را نشان می‌دهد. مصرف در سطح حساب کاربری در Console QCode نمایش داده می‌شود. QCode به‌ازای هر توکن صورت‌حساب می‌کند؛ نرخ هر مدل در [qcode.cc/models](https://qcode.cc/models) فهرست شده است.

### آیا می‌توانم پس از بستن ترمینال، گفتگوی دیروز را ادامه دهم؟

بله. دستور `claude --continue` را در همان پوشه پروژه اجرا کنید تا آخرین نشست بازیابی شود، یا `claude --resume` را اجرا کنید تا از یک فهرست یکی را انتخاب کنید.

### با کدام مدل شروع کنم؟

برای کدنویسی روزمره از `claude-sonnet-5` استفاده کنید و برای کارهای دشوارتر با `/model` به مدل قوی‌تری سوئیچ کنید؛ برای مقایسه [انتخاب مدل](/docs/usage/model-selection) را ببینید.

### اگر بخواهم از GPT یا مدل‌های چینی استفاده کنم چه؟

خود Claude Code از رابط Anthropic استفاده می‌کند، بنابراین مدل‌های چینی را می‌توان مستقیماً انتخاب کرد. برای مدل‌های GPT از Codex CLI استفاده کنید؛ مراحل راه‌اندازی در [راهنمای کامل Codex](/docs/ide/codex) آمده است.

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

تبریک می‌گوییم که مبانی Claude Code را فرا گرفتید! ادامه دهید با:

1. [نکات CLI](/docs/usage/cli-tips) را برای 34 نکته کاربردی بررسی کنید

2. [نکات گردش کار](/docs/usage/workflow-tips) را برای افزایش بهره‌وری بیاموزید

3. [یکپارچه‌سازی Codex](/docs/ide/codex) را ببینید تا از ابزار هوش مصنوعی دیگری استفاده کنید