## راهنمای عمیق حالت Plan آیا تا به حال این تجربه را داشته‌اید: از Claude Code خواستید در تغییر کد به شما کمک کند و آن با تمام سرعت پیش رفت، دوازده فایل را تغییر داد و در پایان متوجه شدید از مسیر خارج شده است؟ یا در میانه تغییر متوجه شدید یک وابستگی را جا انداخته‌اید و مجبور شدید همه‌چیز را برگردانید؟ حالت Plan برای حل همین مشکلات ساخته شد. این حالت به Claude اجازه می‌دهد ابتدا یک برنامه اجرای دقیق بسازد و تنها پس از بازبینی و تأیید شما شروع به کار کند—و «تیر انداختن و سپس هدف را کشیدن» را به «پیش از اقدام، کامل برنامه‌ریزی کردن» تبدیل می‌کند. ## حالت Plan چیست ### حالت Plan در برابر حالت پیش‌فرض در حالت پیش‌فرض، Claude Code هم‌زمان فکر و اجرا می‌کند: تحلیل کد، ویرایش فایل‌ها و اجرای دستورها—این اقدامات درهم‌آمیخته‌اند. این برای کارهای ساده بسیار کارآمد است، اما در کارهای پیچیده می‌تواند به رویکردی «هر بار یک قدم» منجر شود. حالت Plan کاملاً متفاوت است: | ویژگی | حالت پیش‌فرض | حالت Plan | |---------|-------------|-----------| | اجرا | هم‌زمان فکر و اجرا می‌کند | ابتدا برنامه‌ریزی، سپس اجرا پس از تأیید | | عملیات فایل | به‌طور مستقیم فایل‌ها را می‌خواند و می‌نویسد | **فقط‌خواندنی**، فقط تحلیل و جست‌وجو | | اجرای دستور | ممکن است دستورها را مستقیم اجرا کند | هیچ دستور تغییردهنده‌ای را اجرا نمی‌کند | | مناسب برای | ویرایش‌های ساده، اصلاحات سریع | بازساخت چندفایلی، توسعه ویژگی پیچیده | | کنترل ریسک | به سیستم مجوزها متکی است | صفر ریسک در مرحله برنامه‌ریزی | به زبان ساده، Claude در حالت Plan مانند یک معمار است که فقط یک دفترچه یادداشت دارد—محل را به‌دقت بررسی می‌کند (کد را می‌خواند، فایل‌ها را جست‌وجو می‌کند)، نقشه‌های ساخت دقیق می‌کشد (برنامه اجرا)، اما هرگز حتی یک آجر هم نمی‌چیند. ### چرا پیش از اجرا برنامه‌ریزی کنیم مزایای برنامه‌ریزی پیش از اجرا بسیار فراتر از فقط «ایمنی» است: 1. **دیدگاه کلی**: Claude ابتدا همه فایل‌های مرتبط را بررسی می‌کند تا درکی کلی بسازد، نه اینکه در میانه کار متوجه جاافتادگی‌ها شود 2. **برنامه‌های قابل بازبینی**: می‌توانید پیش از اجرا برنامه را بازبینی کنید، مشکلات بالقوه را شناسایی کنید و بازخورد بدهید 3. **کاهش دوباره‌کاری**: تعارض‌های وابستگی و ناسازگاری‌های رابط می‌توانند در مرحله برنامه‌ریزی کشف شوند 4. **هم‌راستایی دانش**: با خواندن برنامه می‌توانید بررسی کنید که درک Claude از پروژه درست است یا نه 5. **قابلیت استفاده مجدد**: برنامه‌های خوب را می‌توان به‌عنوان قالب‌های مرجع برای کارهای مشابه ذخیره کرد ### چه زمانی از حالت Plan استفاده کنیم **برای حالت Plan به‌شدت توصیه می‌شود:** - تغییراتی که بیش از 5 فایل را درگیر می‌کنند - تغییر ماژول‌های اصلی یا رابط‌های عمومی - افزودن ویژگی‌های جدید (به‌ویژه مواردی که پایگاه‌داده‌ها، APIها و غیره را درگیر می‌کنند) - بازساخت ساختار کد موجود - رفع باگ‌هایی با علت نامشخص (ابتدا باید بررسی شود) - هنوز با پروژه آشنایی ندارید و لازم است Claude ابتدا به روشن‌کردن ساختار کمک کند **می‌توانید مستقیماً از حالت پیش‌فرض استفاده کنید:** - رفع یک باگ کوچک مشخص - تغییر محتوای محلی در یک فایل - افزودن توضیحات یا مستندات - قالب‌بندی ساده یا تغییر نام ## نحوه استفاده از حالت Plan ### تغییر حالت‌ها با Shift+Tab شروع حالت Plan بسیار ساده است. در فیلد ورودی Claude Code، `Shift+Tab` را فشار دهید تا بین حالت‌ها بچرخید: ``` auto → default → acceptEdits → plan → auto → ... ``` از Claude Code 2.1.283 به بعد، نشست‌های تعاملی در حالت auto شروع می‌شوند؛ بنابراین برای رسیدن به plan سه بار فشار دادن لازم است (دو بار از `default`). `bypassPermissions` تنها زمانی به چرخه اضافه می‌شود که با `--dangerously-skip-permissions` یا `--allow-dangerously-skip-permissions` شروع کنید. وقتی نشانگر حالت در سمت چپ فیلد ورودی را می‌بینید که **plan** را نشان می‌دهد، وارد حالت Plan شده‌اید. همچنین می‌توانید قصد خود برای برنامه‌ریزی را مستقیماً در prompt خود بیان کنید: ``` Please help me create a plan first, don't modify the code directly. I want to add email verification to the user system. ``` > **نکته**: برای خروج و بازگشت به حالت default هر زمان که بخواهید `Escape` را فشار دهید. ### رفتار Claude در حالت Plan پس از ورود به حالت Plan، توانایی‌های Claude محدود می‌شود: **می‌تواند انجام دهد:** - خواندن هر فایلی - جستجوی کد (Grep، Glob) - تحلیل ساختار پروژه - مشاهده تاریخچه Git - جستجوی اطلاعات وب - تولید برنامه‌های اجرایی دقیق **انجام نمی‌دهد:** - ایجاد یا تغییر فایل‌ها - اجرای دستورهایی که ممکن است عوارض جانبی داشته باشند - نصب بسته‌های وابستگی - اجرای ساخت یا آزمون‌ها این یعنی می‌توانید با خیال راحت بگذارید Claude در حالت Plan هر کدی را بررسی کند، بدون اینکه نگران باشید به‌طور تصادفی «لغزش» کند و چیزی را تغییر دهد. ### مشاهده و ویرایش برنامه‌ها برنامه‌هایی که Claude تولید می‌کند معمولاً ساختار زیر را دارند: ```markdown ## Execution Plan: Add Email Verification Feature ### Goal Add email verification to the user registration flow. ### Impact Analysis - Files to modify: 6 - Files to create: 3 - Database changes: 1 new table needed - Risk points: Existing users are not affected, but migration scripts are needed ### Execution Steps **Phase 1: Database Layer** 1. Create migration script for `email_verifications` table 2. Modify `users` table, add `email_verified` field **Phase 2: Backend Logic** 3. Create new `email_verification_service.py` 4. Modify `auth_router.py`, add verification-related endpoints 5. Modify `user_service.py`, trigger verification email in registration flow **Phase 3: Frontend Adaptation** 6. Modify registration page, add verification prompts 7. Create new email verification page 8. Modify routing configuration ### Risks and Notes - SMTP configuration must be prepared in advance - Need to consider expiration time for verification links - Existing users should skip verification ``` می‌توانید درباره برنامه بازخورد ارائه دهید: ``` The plan looks good overall, but I have a few adjustments: 1. No need to create a new verification page, just use the existing toast notification 2. Set verification link expiration to 24 hours 3. Don't modify the users table in phase 1, use the status in email_verifications table instead Please update the plan. ``` Claude برنامه را بر اساس بازخورد شما تغییر می‌دهد تا زمانی که راضی شوید. ### تأیید برنامه و شروع اجرا پس از تأیید درستی برنامه، `Shift+Tab` را فشار دهید تا به حالتی که می‌خواهید در آن اجرا کنید تغییر وضعیت دهید (برای مثال auto یا default)، سپس به Claude بگویید برنامه را اجرا کند: ``` The plan looks good, please start executing according to the plan. Start with phase one. ``` همچنین می‌توانید اجرا را به‌صورت مرحله‌ای انجام دهید: ``` Execute phase one (database layer) first, then stop and let me verify. ``` ## آموزش عملی Plan Mode ### مثال 1: افزودن احراز هویت کاربر به یک پروژه موجود فرض کنید یک پروژه FastAPI دارید که در حال حاضر هیچ سازوکار احراز هویتی ندارد و باید احراز هویت JWT را اضافه کنید. **مرحله 1: به Plan mode بروید، نیازمندی‌ها را شرح دهید** ``` My FastAPI project has no user authentication currently. Please help me create a plan to add a JWT-based user authentication system. Requirements: - User registration and login - JWT token issuance and verification - Route protection (some endpoints require login) - Use SQLAlchemy to manage user table Please analyze the existing code structure first, then create a detailed execution plan. ``` **مرحله 2: Claude پروژه را تحلیل می‌کند و یک برنامه تولید می‌کند** Claude ابتدا ساختار پروژه شما را بررسی می‌کند: ``` I have analyzed your project structure. Here are my findings and execution plan: ## Current Project Analysis - Framework: FastAPI 0.115.x - Database: Existing SQLAlchemy configuration (database.py), using PostgreSQL - Existing models: Product, Order (in models/ directory) - Routers: product_router.py, order_router.py (both without authentication protection) - Dependency management: Using requirements.txt ## Execution Plan ### Phase 1: Infrastructure (2 files) 1. Add python-jose[cryptography], passlib[bcrypt] to requirements.txt 2. Add JWT-related configuration items to config.py (SECRET_KEY, ALGORITHM, TOKEN_EXPIRE) ### Phase 2: User Model and Database (2 files) 3. Create new models/user.py — User model 4. Create new alembic migration script ### Phase 3: Authentication Logic (3 files) 5. Create new services/auth_service.py — password hashing, JWT issuance/verification 6. Create new schemas/auth.py — request/response models 7. Create new routers/auth_router.py — /register, /login, /me endpoints ### Phase 4: Route Protection (3 files) 8. Create new dependencies/auth.py — get_current_user dependency 9. Modify product_router.py — write operations require authentication 10. Modify order_router.py — all operations require authentication ### Risk Notes - SECRET_KEY in config.py must use environment variables, cannot be hardcoded - Existing API clients need to adapt to authentication headers - Recommend verifying in test environment first ``` **مرحله 3: بررسی و اجرا** ``` The plan is good. Two adjustments: 1. Don't use alembic, use SQLAlchemy's create_all directly 2. Read operations on product_router don't need authentication, only create and delete need it Everything else looks fine, please execute the plan. ``` ### مثال 2: بازآرایی یک ماژول بزرگ فرض کنید پروژه شما یک فایل `utils.py` با 3000 خط دارد که باید تقسیم و بازآرایی شود. **به Plan mode بروید:** ``` utils.py has ballooned to 3000 lines with everything mixed in. Please help me analyze this file and create a refactoring plan to split it into multiple modules with clear responsibilities. Requirements: 1. Analyze the responsibilities of all functions in utils.py 2. Design a new module structure 3. List all files that import utils.py and their affected imports 4. Ensure all existing functionality remains unaffected after refactoring ``` Claude برنامه‌ای مانند این تولید می‌کند: ``` ## utils.py Refactoring Plan ### Current State Analysis utils.py contains 47 functions, which can be categorized into 5 types based on their responsibilities: | Category | Function Count | Example Functions | |----------|---------------|-------------------| | String processing | 12 | slugify, truncate, sanitize_html | | Date and time | 8 | parse_date, format_datetime, get_timezone | | File operations | 9 | read_file, ensure_dir, get_file_hash | | Data validation | 11 | validate_email, validate_phone, check_url | | HTTP utilities | 7 | retry_request, parse_response, build_url | ### Import Analysis A total of 23 files import utils.py, detailed list as follows: (List each file and the specific functions used...) ### New Module Structure utils/ ├── __init__.py # Re-exports for backward compatibility ├── strings.py # String processing ├── datetime.py # Date and time ├── files.py # File operations ├── validators.py # Data validation └── http.py # HTTP utilities ### Execution Steps (List step by step...) ### Backward Compatibility Strategy Keep all original exports in utils/__init__.py: from .strings import * from .datetime import * ... This way, undiscovered references won't break. ``` ### مثال 3: رفع باگ در چندین فایل کاربران گزارش می‌دهند «مبالغ سفارش گاهی نادرست محاسبه می‌شوند»، اما مطمئن نیستید مشکل کجاست. **به Plan mode بروید:** ``` Users report that order amounts are occasionally calculated incorrectly, but not every time. Please help me investigate this issue: 1. Find all code involved in amount calculations 2. Analyze possible causes of occasional errors 3. Create a fix plan ``` Claude در Plan mode به‌طور عمیق تحلیل می‌کند: ``` ## Bug Investigation Report ### Amount Calculation Related Code After comprehensive search, code related to amount calculations is distributed across 4 files: - order_service.py:calculate_total() — main calculation logic - discount_service.py:apply_discount() — discount calculation - tax_service.py:calculate_tax() — tax calculation - cart_service.py:get_cart_total() — cart total ### Issues Found **Root cause: Floating point precision problem** In order_service.py line 127: total = sum(item.price * item.quantity for item in items) Python's floating point arithmetic has precision issues: >>> 0.1 + 0.2 0.30000000000000004 When orders contain multiple items with decimal amounts, cumulative errors may cause the final amount to be off by 1 cent. **Secondary issue: Discount calculation order** discount_service.py's discount calculation is executed after tax_service.py's tax calculation, but in some concurrent scenarios, the order may be reversed (because they are called asynchronously). ### Fix Plan 1. Change all amount calculations to use Decimal type 2. Modify the call order of discount and tax to be synchronous and sequential 3. Add unit tests for amount consistency ``` این مثال ارزش Plan mode را در بررسی باگ نشان می‌دهد — Claude برای تغییر کد شتاب نمی‌کند؛ ابتدا تحلیل کامل انجام می‌دهد. ## بهترین شیوه‌های حالت Plan ### 1. «چرا» را به‌جای «چگونه» توصیف کنید **توصیه نمی‌شود:** ``` Please add a verify_email method to user.py that accepts a token parameter, queries the email_verifications table, and if the token matches and hasn't expired, sets user.email_verified to True. ``` **توصیه‌شده:** ``` We need to allow users to verify their email addresses. Users will receive an email with a verification link after registration. After clicking the link, their email status becomes verified. Please help me plan the implementation. ``` چرا؟ زیرا وقتی «چرا» را توصیف می‌کنید، Claude فضای بیشتری برای طراحی راه‌حل بهینه دارد. ممکن است موارد مرزی را کشف کند که به آن‌ها فکر نکرده‌اید، یا پیاده‌سازی زیباتری پیشنهاد دهد. اگر جزئیات دقیق پیاده‌سازی را مشخص کنید، ارزش حالت Plan به‌شدت کاهش می‌یابد. ### 2. از Claude بخواهید نقاط ریسک را در طرح شناسایی کند به‌صورت فعال از Claude بخواهید ریسک‌ها را تحلیل کند: ``` Please pay special attention to the following in the plan: 1. What existing functionality might this modification break? 2. Are there configuration files that need to be modified together? 3. Do database changes require migration scripts? 4. Are there any concurrency safety concerns? ``` ### 3. طرح‌های پیچیده را مرحله‌به‌مرحله اجرا کنید برای کارهای بزرگ، کل طرح را یک‌جا اجرا نکنید. آن را به مراحل مستقلی که هرکدام جداگانه قابل راستی‌آزمایی هستند تقسیم کنید: ``` This plan has 4 phases, please execute as follows: - Stop after completing each phase - Report the completion status of that phase - Wait for my confirmation before continuing to the next phase ``` مزیت این رویکرد: اگر در یک مرحله مشکلی پیش برود، می‌توانید به‌موقع آن را اصلاح کنید بدون اینکه تعداد زیادی از تغییرات را بازگردانید. ### 4. طرح‌ها را با شاخه‌های Git ترکیب کنید گردش‌کار بهینه این است: **حالت Plan طرح را ایجاد می‌کند → ایجاد شاخه جدید → اجرا روی شاخه جدید → بازبینی کد → ادغام** ``` # Create plan in Plan mode first (Switch to Plan mode, describe requirements, review plan) # After satisfied, switch back to default mode Please create a new branch feature/email-verification first, then execute the plan. ``` اگر در حین اجرا متوجه شوید طرح اشتباه است، همیشه می‌توانید به شاخه اصلی برگردید و از نو شروع کنید. ## حالت Plan در برابر کدنویسی مستقیم ### چه زمانی به حالت Plan نیاز نیست - کارهای ساده که یک یا دو فایل را تغییر می‌دهند - به‌وضوح می‌دانید چه چیزی و چگونه باید تغییر کند - تغییرات غیرکارکردی مانند افزودن توضیحات یا تغییر متن - اجرای دستورها (مانند نصب وابستگی‌ها، اجرای آزمون‌ها) ### چه زمانی حالت Plan لازم است - تغییراتی که بیش از 5 فایل را درگیر می‌کنند - تغییر رابط‌های عمومی یا ماژول‌های اصلی - هنوز به‌اندازه کافی با ساختار پروژه آشنا نیستید - علت باگ نامشخص است و ابتدا باید بررسی شود - نیاز به ارزیابی بده‌بستان بین چند راه‌حل دارید ### مرجع تصمیم‌گیری ``` What is your task? │ ├─ Simple modification (1-2 files, clear direction) │ → Default mode, start directly │ ├─ Medium task (3-5 files, clear logic) │ → Can use Plan mode first for quick scan, then switch to execute │ └─ Complex task (multiple files, uncertain solutions, high risk) → Must use Plan mode, plan in detail before executing ``` ## نکته‌های پیشرفته ### 1. سفارشی‌سازی قالب‌های پلن از طریق CLAUDE.md می‌توانید الزامات پلن‌سازی را در `CLAUDE.md` پروژه خود تعریف کنید تا هر بار استفاده از حالت Plan از قالبی یکسان پیروی کند: ```markdown ## Plan Mode Requirements When entering Plan mode, please generate plans according to the following template: ### Required Sections 1. **Current State Analysis**: Current code structure and relevant files 2. **Solution Design**: Specific implementation approach, including alternatives 3. **Impact Scope**: Which files will be modified, which features will be affected 4. **Risk Assessment**: Possible issues and countermeasures 5. **Execution Steps**: In sequential order, each step verifiable independently 6. **Testing Plan**: How to verify the correctness of changes ### Format Requirements - Each execution step should indicate the files involved - New files should be marked with [NEW] - Files to modify should be marked with [MODIFY] - Risk points should be marked with High/Medium/Low severity ``` پس از افزودن این مورد به `CLAUDE.md`، هر بار که از حالت Plan استفاده می‌کنید، Claude پلن‌ها را بر اساس این قالب سازمان‌دهی می‌کند. ### 2. استفاده از زیرعامل‌ها برای کاوش در حالت Plan در حالت Plan می‌توانید از Claude بخواهید برای کاوش عمیق‌تر از زیرعامل‌ها (ابزارهای Agent) استفاده کند: ``` Before creating the plan, please help me figure out the following: 1. What does the current database schema look like? Use a sub-agent to analyze all model files 2. What is the list of existing API endpoints? Use a sub-agent to scan all router files 3. What third-party libraries does the project use? Check requirements.txt or pyproject.toml ``` زیرعامل‌ها این وظایف کاوش را در زمینه‌های جداگانه اجرا می‌کنند، سپس نتایج را برای نشست اصلی خلاصه می‌کنند تا Claude پلن‌های دقیق‌تری ایجاد کند. ### 3. ذخیره و استفاده مجدد از پلن‌ها پلن‌های خوب را می‌توان به‌عنوان قالب‌های مرجع ذخیره کرد. می‌توانید از Claude بخواهید پلن را به‌صورت یک فایل Markdown خروجی بگیرد: ``` Please save the plan we just created to docs/plans/add-email-verification.md. We can reference it when working on similar features in the future. ``` بار بعد که با نیازهای مشابه روبه‌رو شدید، می‌توانید مستقیماً به آن مراجعه کنید: ``` Please refer to the plan structure in docs/plans/add-email-verification.md and create a similar plan for SMS verification. ``` ### 4. استفاده از حالت Plan برای بازبینی کد ماهیت فقط‌خواندنی حالت Plan آن را برای بازبینی کد بسیار مناسب می‌کند: ``` (Enter Plan mode) Please review all service files in the src/services/ directory, focusing on: 1. Is error handling comprehensive? 2. Are there any SQL injection risks? 3. Are there unclosed resources (database connections, file handles)? 4. Do async code have race conditions? Please provide a detailed review report and improvement suggestions. ``` از آنجا که حالت Plan هیچ فایلی را تغییر نمی‌دهد، می‌توانید با خیال راحت بگذارید Claude کد تولید را بازبینی کند بدون اینکه نگران تغییر تصادفی و «به‌راحتی» چیزی توسط آن باشید. ### 5. ترکیب با /compact برای نشست‌های طولانی پلن فرایند کاوش در حالت Plan ممکن است زمینه زیادی مصرف کند (به‌ویژه پس از تحلیل فایل‌های متعدد). اگر احساس می‌کنید زمینه در حال تمام شدن است، می‌توانید پس از تکمیل پلن اما پیش از اجرا از `/compact` استفاده کنید: ``` /compact Keep the complete execution plan and impact analysis, compress the intermediate exploration process ``` این کار فضای زمینه کافی را برای مرحله اجرا باقی می‌گذارد. ## پرسش‌های متداول **س: آیا Claude در حالت Plan به‌طور تصادفی فایل‌ها را تغییر می‌دهد؟** پاسخ: خیر. حالت Plan تمام عملیات نوشتن را در سطح سیستم ممنوع می‌کند. Claude می‌تواند هر فایلی را بخواند اما نمی‌تواند هیچ محتوایی را ایجاد، تغییر یا حذف کند. **س: پس از ایجاد پلن، هنگام تغییر به حالت پیش‌فرض برای اجرا، آیا Claude هنوز پلن را به یاد می‌آورد؟** پاسخ: بله. تا زمانی که از `/clear` برای پاک کردن تاریخچه استفاده نکرده باشید، تغییر حالت‌ها زمینه را از دست نمی‌دهد. پلن هنوز در تاریخچه گفتگو است و Claude می‌تواند پلن را مستقیماً اجرا کند. **س: آیا می‌توانم در حالت Plan از ابزارهای MCP استفاده کنم؟** پاسخ: می‌توانید از ابزارهای MCP فقط‌خواندنی (مانند جستجو، جستجوی مستندات) استفاده کنید، اما نمی‌توانید از ابزارهایی که عوارض جانبی تولید می‌کنند استفاده کنید. **س: اگر فکر می‌کنم پلن خوب نیست، آیا می‌توانم از Claude بخواهم دوباره برنامه‌ریزی کند؟** پاسخ: قطعاً. می‌توانید مکرراً از Claude بخواهید پلن را تغییر دهد تا راضی شوید. ماهیت بدون‌ریسک حالت Plan به این معناست که می‌توانید آزادانه کاوش و تنظیم کنید. **س: چگونه پلن‌ها را در همکاری تیمی به اشتراک بگذارم؟** پاسخ: می‌توانید از Claude بخواهید پلن را به‌صورت یک فایل Markdown ذخیره کند و آن را در مخزن Git کامیت کند. همچنین می‌توانید محتوای پلن را مستقیماً در توضیحات PR قرار دهید تا بازبینی کد تسهیل شود.