# نکات گردش کار

این راهنما نحوه ادغام Claude Code را در گردش کار روزانه توسعه شما پوشش می‌دهد؛ از بهره‌وری فردی تا همکاری تیمی، و فرایندهای کارآمد توسعه با کمک هوش مصنوعی را پایه‌گذاری می‌کند.

## گردش کار برنامه‌ریزی-اجرا

مؤثرترین الگوی Claude Code این است: **اول برنامه‌ریزی، بعد اجرا** — از اینکه هوش مصنوعی مستقیم کد بنویسد پرهیز کنید.

### جریان پایه

```
1. Analyze Requirements → 2. Create Plan → 3. Confirm Plan → 4. Execute Step by Step → 5. Verify Results
```

### گام‌های عملی

**گام 1: از Claude بخواهید نیازمندی‌ها را درک کند**

```
> Read the code in @src/services/ directory and understand the existing architecture.
> Don't write any code, just analyze.
```

**گام 2: برنامه پیاده‌سازی را بسازید**

```
> Based on your understanding of the existing code, create a detailed implementation plan for "user permission management".
> Include: file changes, new files, dependencies, risk points.
```

**گام 3: برنامه را تأیید و تنظیم کنید**

برنامه Claude را بررسی کنید و اصلاحات را پیشنهاد دهید:

```
> In step 3 of the plan, I want to use Redis cache instead of memory cache. Please adjust the plan.
```

**گام 4: گام‌به‌گام اجرا کنید**

```
> Now execute step 1 of the plan: create the permission model.
```

پس از تکمیل هر گام، پیش از ادامه نتایج را بررسی کنید.

## گردش کار شاخه ویژگی

### بهترین شیوه‌های شاخه Git

```bash
# 1. Create feature branch
git checkout -b feature/user-permissions

# 2. Navigate to project and start Claude Code
cd your-project && claude

# 3. Commit frequently during development
> Commit this change  # First commit
# Continue developing...
> Commit this change  # Second commit

# 4. Feature complete, create PR
> Create a PR description for the current branch, summarizing all commit changes
```

### نکات دفعات کامیت

- **کامیت‌های کوچک**: پس از هر نقطه ویژگی مستقل کامیت کنید

- **پیام‌های کامیت**: از Claude بخواهید پیام مناسبی را از diff تولید کند (پروژه‌هایی که دستور سفارشی `/commit` دارند می‌توانند از آن استفاده کنند)

- **از کامیت‌های بزرگ پرهیز کنید**: پیش از کامیت، تغییرات زیادی را انبار نکنید

## گردش کار بازبینی کد

### بازبینی خود

پیش از ارسال PR، از Claude بخواهید بازبینی کند:

```
> /review
> Focus on: security, performance, code style
```

### بازبینی کد دیگران

```bash
# Get PR changes
gh pr diff 123 | claude "Review this PR, focus on:
1. Logic correctness
2. Edge case handling
3. Error handling
4. Code maintainability"
```

### فرایند بازبینی چندمرحله‌ای

برای PRهای پیچیده، از بازبینی ساختاریافته استفاده کنید:

```
> Phase 1: Check if architecture design is reasonable
> Phase 2: Check if implementation matches design
> Phase 3: Check if test coverage is sufficient
> Phase 4: Check if documentation is complete
```
## جریان کاری آزمون‌محور

### TDD با Claude Code

```
1. Write Tests → 2. Run Tests (Fail) → 3. Write Code → 4. Run Tests (Pass) → 5. Refactor
```

### گام‌های عملی

**گام 1: تعریف آزمون‌ها**

```
> Write test cases for user registration, covering:
> - Normal registration
> - Invalid email format
> - Weak password
> - User already exists
> Write tests first, don't implement the feature.
```

**گام 2: بررسی شکست آزمون‌ها**

```bash
npm test  # Expected: tests fail
```

**گام 3: پیاده‌سازی قابلیت**

```
> Now implement the code to make all tests pass.
```

**گام 4: بررسی و بازآرایی**

```bash
npm test  # Expected: tests pass
```

```
> Tests pass. Now refactor the code for better readability without breaking tests.
```

## جریان کاری اشکال‌زدایی

### اشکال‌زدایی ساخت‌یافته

```
1. Reproduce Issue → 2. Gather Information → 3. Analyze Cause → 4. Verify Hypothesis → 5. Fix Issue
```

### گام‌های عملی

**گام 1: توصیف مشکل**

```
> Issue: After login, clicking "My Orders" shows blank page
> Expected: Display user's order list
> Steps to reproduce: Login → Click "My Orders"
```

**گام 2: جمع‌آوری اطلاعات**

```
> Analyze these files to find possible issues:
> @src/pages/MyOrders.tsx
> @src/services/OrderService.ts
> @src/api/orders.ts
```

**گام 3: تحلیل لاگ‌ها**

```bash
# Collect error logs
cat app.log | claude "Analyze these logs, find errors related to the orders page"
```

**گام 4: رفع و بررسی**

```
> Based on the analysis, fix the issue in OrderService
> After fixing, I'll test to verify
```

## جریان کاری همکاری زیرعامل‌ها

### پردازش موازی

از زیرعامل‌ها برای پردازش موازی وظایف بهره بگیرید:

```
> Execute these tasks simultaneously:
> 1. Use Explore agent to analyze project structure
> 2. Use Plan agent to design new feature approach
```

### نقش‌های تخصصی

زیرعامل‌های مختلف نقاط قوت متفاوتی دارند:

| عامل | تخصص | کاربرد |
|-------|-----------|----------|
| Explore | جستجوی سریع | یافتن کد، درک ساختار |
| Plan | طراحی معماری | برنامه‌ریزی قابلیت‌های پیچیده |
| Background | پردازش موازی | وظایف دسته‌ای، وظایف طولانی‌مدت |

## جریان کاری یکپارچه‌سازی با IDE

### یکپارچه‌سازی با VS Code

1. افزونه VS Code برای Claude Code را نصب کنید

2. برای جابه‌جایی سریع از `Cmd+Esc` / `Ctrl+Esc` استفاده کنید

3. کد را در ویرایشگر انتخاب کنید، سپس Claude را فراخوانی کنید

### همکاری ترمینال + IDE

```
Terminal (Claude Code)          IDE (VS Code)
        ↓                           ↓
   Analyze, Plan              Manual adjustments, reading
        ↓                           ↓
   Generate Code  ←─────────→   View diff, test
        ↓                           ↓
   Commit Code                  Continue development
```
## گردش‌کار همکاری تیمی

### CLAUDE.md استانداردشده

پیکربندی CLAUDE.md را در تیم به اشتراک بگذارید:

```markdown
# Team Development Standards

## Code Style
- ESLint config: .eslintrc.js
- Prettier config: .prettierrc

## Git Standards
- Branch naming: feature/xxx, fix/xxx, hotfix/xxx
- Commit format: type(scope): description

## Testing Requirements
- Unit test coverage > 80%
- E2E tests cover core flows
```

### قالب‌های PR

از Claude بخواهید از قالب‌های یکسان PR استفاده کند:

```
> Create PR description using this template:
> ## Changes
> ## Test Plan
> ## Screenshots (if UI changes)
> ## Checklist
```

## چک‌لیست گردش‌کار

### پیش از شروع وظیفه جدید

- [ ] یک شاخه feature بسازید

- [ ] با `/clear` زمینه را پاک کنید

- [ ] ابتدا از Claude بخواهید کد موجود را درک کند

- [ ] برنامه پیاده‌سازی را تهیه کنید

### در حین توسعه

- [ ] گام‌به‌گام اجرا کنید و هر گام را بررسی کنید

- [ ] کامیت‌های کوچک بزنید و از Claude بخواهید مرتباً کامیت کند

- [ ] زمینه را با `/context` پایش کنید

- [ ] در صورت نیاز از `/compact` استفاده کنید

### پیش از ارسال

- [ ] برای بازبینی خودتان `/review` را اجرا کنید

- [ ] همه تست‌ها را اجرا کنید

- [ ] خطاهای lint را بررسی کنید

- [ ] توضیحات PR را تولید کنید

## سوئیچ‌هایی که گردش‌کارها بیشترین اتکا را به آن‌ها دارند

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

| موقعیت | چه کاری انجام دهید | مستندات چه می‌گوید |
|---|---|---|
| اول برنامه‌ریزی، بدون تغییر هیچ فایلی | `Shift+Tab` را فشار دهید تا به حالت plan بروید؛ نوار وضعیت `⏸ plan mode on` را نشان می‌دهد | Claude فایل‌ها را می‌خواند و برنامه‌ای پیشنهاد می‌دهد و تا زمانی که تأیید نکنید هیچ ویرایشی انجام نمی‌دهد |
| ادامه یک نشست قبلی | `claude --continue` (آخرین نشست در این پوشه)، `claude --resume` (انتخاب از یک فهرست)، یا `/resume` درون یک نشست | اگر پوشه نشست قبلی نداشته باشد، `--continue` پیام `No conversation found to continue` را چاپ می‌کند و خارج می‌شود |
| بازگردانی یک تغییر نامناسب | `/rewind`، یا وقتی ورودی خالی است دو بار `Esc` را فشار دهید | می‌توانید کد و مکالمه، فقط مکالمه، فقط کد را بازیابی کنید یا از یک پیام انتخابی خلاصه بگیرید |
| مشاهده مصرف نشست | `/usage` (نام مستعار `/cost`) | هزینه و مصرف نشست جاری را نشان می‌دهد |

دو محدودیت برای بازگردانی وجود دارد: مستندات می‌گوید عکس‌های لحظه‌ای فایل‌ها برای 100 نقطه بازرسی آخر یک نشست نگه داشته می‌شوند و این عکس‌ها به‌طور پیش‌فرض حدود 30 روز پس از آخرین ذخیره‌شدن توسط نشست پاک می‌شوند؛ پس از آن بازگردانی ممکن است با خطای `No files were restored` شکست بخورد. برای نگه‌داشتن آن‌ها برای مدت طولانی‌تر، `cleanupPeriodDays` را تنظیم کنید.
## نکته‌ها هنگام اجرای این گردش‌کارها روی QCode

- **هم‌زمانی**: هر پلن شخصی یا بسته پرداخت به‌ازای مصرف امکان 5 درخواست هم‌زمان به‌ازای هر کلید API را می‌دهد (10 در Ultimate؛ [پرسش‌های متداول](/docs/reference/faq) را ببینید). اجرای چند نمونه Claude Code یا تعداد زیادی subagent به‌صورت موازی ممکن است اول به این محدودیت برخورد کند که معمولاً به شکل 429 ظاهر می‌شود.
- **نشست‌های طولانی**: نشست‌های طرح‌ریزی سپس اجرا غالباً طولانی می‌شوند و نزدیک سقف پنجره زمینه `E015` / 429 می‌بینید. ابتدا `/compact` را اجرا کنید و اگر نتیجه نداد نشست را از نو راه‌اندازی کنید؛ [مدیریت زمینه](/docs/usage/context-management) را ببینید.
- **تقسیم کار میان مدل‌ها**: برای طرح‌ریزی و بازبینی از مدل قوی‌تر استفاده کنید، برای ویرایش‌های انبوه از `claude-sonnet-5` و با `/model` جابه‌جا شوید. QCode بر پایه توکن صورت‌حساب می‌کند؛ نرخ هر مدل در [qcode.cc/models](https://qcode.cc/models) است.

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

| نشانه | علت احتمالی | راه‌حل |
|---|---|---|
| 429 با `E015` در بدنه پاسخ | گفتگو بیش از حد طولانی است و زمینه به سقف خود نزدیک شده | `/compact`، یا خروج و راه‌اندازی مجدد |
| محدودیت نرخ درخواست محتمل (معمولاً 429) هرچند گفتگو کوتاه است | درخواست‌های هم‌زمان ممکن است از سقف هم‌زمانی کلید فراتر رفته باشند | تعداد نمونه‌ها یا subagentهای در حال اجرا را کاهش دهید و بعداً دوباره تلاش کنید |
| همچنان در حالت plan تلاش می‌کند فایل‌ها را ویرایش کند | واقعاً در حالت plan نیستید | نوار وضعیت را برای `⏸ plan mode on` بررسی کنید؛ اگر نبود دوباره `Shift+Tab` را بزنید |
| پس از `/rewind` فایل‌ها بازیابی نمی‌شوند، `No files were restored` | snapshotهای نقطه بررسی پاک‌سازی شده‌اند | از git بازیابی کنید و در نقاط مهم commit بزنید |
| تایپ `/commit` هیچ کاری نمی‌کند | تا تاریخ 2026-10-15 دستور `/commit` در فهرست رسمی دستورهای داخلی نیست؛ معمولاً از یک دستور یا skill سفارشی می‌آید و همچنین باید درون یک مخزن git باشید | با `/help` دستورهای موجود را ببینید؛ اگر نبود، کافی است بگویید «این تغییرات را با یک پیام commit خوب commit کن» |
| 401 / 404 / `model_not_available_on_endpoint` | مشکلی در پیکربندی اتصال که به گردش‌کارها مربوط نیست | خودآزمایی را در [نقاط پایانی و قالب‌های API](/docs/getting-started/endpoints-and-api-paths) اجرا کنید |

## پرسش‌های متداول

### آیا همیشه باید پیش از اجرا طرح‌ریزی کنم؟

تغییرهای کوچک را می‌توان مستقیم انجام داد. برای کارهایی که چند فایل را دست می‌زنند یا خطا در آن‌ها پرهزینه است، ابتدا بگذارید در حالت plan طرحی پیشنهاد دهد و پس از تأیید شما اجرا کند؛ این کار معمولاً دوباره‌کاری کمتری دارد.

### هر چند وقت یک بار باید `/compact` را اجرا کنم؟

ریتم ثابتی وجود ندارد. به‌جای انتظار برای سرریز شدن، هر بار که یک مرحله تمام شد یا وقتی `/context` مصرف را 70% تا 80% نشان می‌دهد یک بار compact کنید.

### پس از یک اشتباه چگونه برگردم؟

برای کد، git و `/rewind` را با هم به کار ببرید: در گام‌های کوچک commit بزنید و برای بازگردانی درون‌نشست از `/rewind` استفاده کنید. پیش از آنکه اجازه دهید Claude ادامه دهد، در نقاط مهم commit بزنید.

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

گفتگوهای آن‌ها مستقل‌اند، اما سهمیه هم‌زمانی یک کلید را با هم شریک‌اند. با کارهای موازی زیاد ممکن است به محدودیت نرخ درخواست بربخورید؛ هم‌زمانی را همان‌گونه که بالا گفتیم کاهش دهید.

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

- [نکته‌های CLI](/docs/usage/cli-tips) را بخوانید تا دستورهای بیشتری بیاموزید

- [دستورهای سفارشی](/docs/usage/cli-tips) را بررسی کنید تا دستورهای مخصوص تیم خود را بسازید

- [بهترین شیوه‌ها](/docs/usage/best-practices) را ببینید تا گردش‌کارها را بیشتر بهینه کنید