آموزش Claude Code؛ نصب، اتصال و ساخت اولین پروژه

برای شروع کار با Claude Code لازم نیست از همان دقیقهٔ اول یک مخزن بزرگ را در اختیارش بگذارید. مسیر درست این است: ابزار رسمی را نصب کنید، روش اتصال را مشخص کنید، داخل یک پروژهٔ کوچک وارد شوید، ابتدا در حالت فقط‌خواندنی از آن نقشهٔ کار بخواهید و بعد هر تغییر را با diff و تست تحویل بگیرید. این آموزش Claude Code همین مسیر را قدم‌به‌قدم و با پروژه‌ای قابل بازتولید نشان می‌دهد؛ نه با نمایشی که در آن ایجنت ده فایل را عوض می‌کند و همه امیدوارند اتفاق بدی نیفتاده باشد.

نکات کلیدی:

• نصب native روش پیشنهادی Anthropic است؛ بعد از نصب، نسخه و وضعیت ورود را جداگانه بررسی کنید.
• برای پروژهٔ ناآشنا با Plan mode شروع کنید و فقط مجوزهای واقعاً لازم را بدهید.
• CLAUDE.md باید فرمان‌های واقعی build و test و قواعد غیرقابل‌حدس پروژه را ثبت کند، نه شرحی طولانی از بدیهیات.
• checkpoint برای برگشت سریع مفید است، اما تغییرات shell و سرویس‌های بیرونی را پوشش نمی‌دهد؛ Git همچنان خط اصلی دفاع است.
• دسترسی از ایران ریسک و محدودیت خودش را دارد و هیچ روش ثالثی تضمین «بدون بن» یا ریسک صفر نمی‌دهد.

فهرست مطالب

• Claude Code چیست و چه پیش‌نیازی دارد؟
• نصب Claude Code در macOS، Linux و Windows
• ورود و اتصال به Claude Code
• ساخت اولین پروژه و session
• تنظیم permissionها
• ساخت CLAUDE.md مفید
• تست، بازبینی و rollback
• دسترسی به Claude Code از ایران
• خطاهای رایج
• پرسش‌های متداول

Claude Code چیست و چه پیش‌نیازی دارد؟

Claude Code یک ابزار عامل‌محور در ترمینال است: فایل‌های پروژه را می‌خواند، در کد جست‌وجو می‌کند، فایل را ویرایش می‌کند و با اجازهٔ شما فرمان‌هایی مثل تست یا lint را اجرا می‌کند. فرقش با یک پنجرهٔ چت ساده همین «عمل کردن در محیط پروژه» است. همین تفاوت هم آن را مفیدتر و هم بالقوه پرریسک‌تر می‌کند.

طبق راهنمای شروع رسمی Anthropic، سیستم‌عامل‌های پشتیبانی‌شده شامل macOS 13 به بالا، Windows 10 نسخهٔ 1809 به بالا یا Windows Server 2019 به بالا، و توزیع‌های رایج Linux است. حداقل ۴ گیگابایت RAM، اتصال اینترنت و یک حساب پشتیبانی‌شده هم لازم است. روی Windows استفاده از Git for Windows توصیه شده تا ابزار Bash در دسترس باشد؛ در غیر این صورت Claude Code از PowerShell استفاده می‌کند.

آخرین بررسی: ۲۱ ژوئیهٔ ۲۰۲۶. پیش‌نیازها و فرمان نصب ممکن است تغییر کنند؛ اگر این مطلب را دیرتر می‌خوانید، همان صفحهٔ رسمی را دوباره ببینید.

پیش از نصب، این سه مورد را آماده کنید:

1. یک ترمینال عادی با دسترسی کاربر خودتان؛ نصب با حساب root انتخاب خوبی برای شروع نیست.
2. Git و یک پوشهٔ پروژه که ترجیحاً commit تمیز داشته باشد.
3. روش احراز هویت: اشتراک Claude، حساب Console با اعتبار API، سرویس ابری سازمانی یا gateway سازگار.

این مقاله از پروژهٔ کوچک JavaScript استفاده می‌کند، اما خود نصب native به Node.js وابسته نیست. Node فقط برای اجرای نمونه و تست آن لازم می‌شود.

نصب Claude Code در macOS، Linux و Windows

Anthropic نصب‌کنندهٔ native را مسیر پیشنهادی معرفی می‌کند. روی macOS و Linux فرمان زیر را در ترمینال اجرا کنید:

روی Windows، PowerShell را باز کنید و بنویسید:

اگر ترجیح می‌دهید از مدیر بسته استفاده کنید، مستندات رسمی این دو گزینه را هم ذکر می‌کنند:

نصب native در پس‌زمینه به‌روز می‌شود، اما نسخه‌های Homebrew و WinGet را باید با مدیر بسته به‌روز کنید. بعد از هر روش نصب، نتیجه را حدس نزنید؛ بررسی کنید:

فرمان اول باید شماره نسخه و عبارت Claude Code را نشان دهد. claude doctor وضعیت نصب، به‌روزرسانی و تنظیمات را بررسی می‌کند. مرجع جزئیات و گزینه‌های جایگزین، صفحهٔ نصب پیشرفته Anthropic است.

روش	مزیت	نکتهٔ به‌روزرسانی	پیشنهاد برای شروع
Native installer	مسیر رسمی و مستقل از Node	به‌روزرسانی خودکار	انتخاب اول
Homebrew	مدیریت یکپارچه روی macOS	اجرای دستی brew upgrade	مناسب کاربران Homebrew
WinGet	نصب آشنا روی Windows	اجرای دستی winget upgrade	مناسب محیط Windows
npm قدیمی	ممکن است هنوز روی سیستم باشد	احتمال تداخل چند نصب	برای نصب تازه پیشنهاد نمی‌شود

اگر claude پیدا نشد، ترمینال را یک‌بار ببندید و باز کنید. اگر باز هم شکست خورد، با which -a claude در macOS/Linux یا where.exe claude در Windows بررسی کنید چند نسخه هم‌زمان نصب نشده باشد. حذف کورکورانهٔ پوشه‌ها درمان نیست؛ اول منبع هر binary را پیدا کنید.

آخرین بررسی: ۲۱ ژوئیهٔ ۲۰۲۶. فرمان‌ها و رفتار به‌روزرسانی از مستندات نصب رسمی Anthropic گرفته شده‌اند.

ورود و اتصال به Claude Code

برای ورود رسمی، داخل یک پوشهٔ پروژه فرمان زیر را اجرا کنید:

در اجرای اول، مرورگر برای احراز هویت باز می‌شود. بر اساس مستندات احراز هویت Anthropic، می‌توانید با حساب Claude Pro، Max، Team یا Enterprise، حساب Claude Console، یا ارائه‌دهنده‌های ابری پشتیبانی‌شده وارد شوید. اگر مرورگر خودکار باز نشد، در رابط terminal کلید c را بزنید تا URL ورود کپی شود. در SSH، container و WSL2 ممکن است پس از ورود لازم باشد کد نمایش‌داده‌شده در مرورگر را داخل ترمینال paste کنید.

برای ورود مستقیم با Console و پرداخت مبتنی بر مصرف API:

فرمان دوم بررسی قابل بازتولید ماست: باید روش ورود فعال را نشان دهد. اگر متغیر ANTHROPIC_API_KEY از قبل در shell تنظیم شده باشد، ممکن است بر احراز هویت اشتراکی اولویت بگیرد. در چنین وضعی، /status داخل session نشان می‌دهد واقعاً از کدام روش استفاده می‌کنید.

آخرین بررسی: ۲۱ ژوئیهٔ ۲۰۲۶. انواع حساب و اولویت credentialها ادعاهای متغیر محصول‌اند و از مستندات رسمی بالا نقل شده‌اند؛ قیمت مشخصی اینجا نمی‌آوریم چون به پلن و روش اتصال وابسته است.

ساخت اولین پروژه و session

نمونهٔ زیر عمداً کوچک است تا بتوانید تمام تغییرات را با چشم ببینید. یک پوشه بسازید، واردش شوید و Git را آغاز کنید:

فایل calculator.js را بسازید:

سپس در package.json مقدار "type": "module" و script زیر را اضافه کنید:

حالا baseline بسازید:

اولین درخواست شما بهتر است فقط شناخت پروژه باشد:

بعد از دیدن طرح، کار را دقیق و محدود کنید:

این‌جا نکتهٔ اصلی «پرامپت جادویی» نیست. قرارداد خروجی مشخص است: رفتار مورد انتظار، ابزار تست، ممنوعیت dependency تازه و گزارش نهایی. هرچه کار قابل‌سنجش‌تر باشد، review هم واقعی‌تر می‌شود.

تنظیم permissionها

در session کلید Shift+Tab حالت permission را تغییر می‌دهد و /permissions فهرست قواعد را باز می‌کند. طبق مرجع permissionهای Claude Code، قواعد deny، سپس ask و بعد allow ارزیابی می‌شوند؛ CLAUDE.md رفتار مطلوب را توضیح می‌دهد اما جای permission اجرایی را نمی‌گیرد.

حالت	چه کاری بدون تأیید انجام می‌شود؟	کاربرد مناسب
default	عمدتاً خواندن؛ برای ابزارهای دیگر سؤال می‌پرسد	شروع کار و مخزن حساس
plan	خواندن و بررسی بدون ویرایش منبع	شناخت پروژه و طراحی تغییر
acceptEdits	ویرایش فایل و فرمان‌های رایج فایل‌سیستم در محدوده کار	تکرار سریع پس از اعتماد نسبی
dontAsk	فقط ابزارهای از قبل مجاز	اتوماسیون محدود و کنترل‌شده
bypassPermissions	تقریباً همه ابزارها بدون سؤال	فقط محیط ایزوله مثل VM یا container

نظر صریح ما: bypassPermissions روی لپ‌تاپی که کلیدها، مخزن‌های کاری و sessionهای ورود شما را دارد، صرفه‌جویی نیست؛ حذف ترمز است. برای اولین پروژه plan یا default را نگه دارید. فرمان شبکه، migration دیتابیس، deploy و دست‌کاری Git باید نیازمند بازبینی بمانند.

آخرین بررسی: ۲۱ ژوئیهٔ ۲۰۲۶. نام حالت‌ها و دامنهٔ هرکدام ممکن است با نسخه تغییر کند؛ جدول بالا از مستندات رسمی permission تهیه شده است.

ساخت CLAUDE.md مفید

در ریشهٔ پروژه، داخل Claude Code فرمان /init می‌تواند یک CLAUDE.md اولیه بسازد. این فایل دستورهای ماندگار پروژه است و می‌توانید آن را همراه کد commit کنید. مستندات memory رسمی توصیه می‌کند چیزهایی را بنویسید که در هر session ناچارید دوباره توضیح دهید: فرمان تست، قراردادهای نام‌گذاری، محدودیت معماری و دام‌های خاص پروژه.

برای نمونهٔ ما این فایل کافی است:

بعد از ذخیره، داخل session فرمان /context را اجرا کنید و ببینید فایل واقعاً load شده یا نه. دستور «کد را تمیز بنویس» تقریباً بی‌مصرف است؛ Claude تعریف ذهنی شما از تمیزی را نمی‌داند. دستور npm test و شرط منع dependency قابل اجرا و قابل بازبینی‌اند. و بله، CLAUDE.md رمان معماری نیست. هر خط اضافه از توجهی خرج می‌کند که باید صرف قواعد مهم شود.

تست، بازبینی و rollback

وقتی Claude اعلام کرد کار تمام شده، همان session را داور نهایی ندانید. بیرون از Claude Code این زنجیره را اجرا کنید:

انتظار دارید تست‌ها سبز باشند، git diff --check خطای whitespace ندهد و diff فقط calculator.js، فایل تست و احتمالاً CLAUDE.md را لمس کرده باشد. سپس یک اجرای دستی کوچک هم بد نیست:

خروجی باید 4 باشد. این آزمون را خواننده می‌تواند بازتولید کند؛ ما ادعا نمی‌کنیم همین session را روی دستگاه شما اجرا کرده‌ایم.

اگر نتیجه بد بود، سه سطح بازگشت دارید:

1. داخل Claude Code فرمان /rewind یا دو بار Esc را بزنید و checkpoint پیش از تغییر را انتخاب کنید.
2. برای فایل‌های tracked، با Git diff را بررسی و فقط فایل موردنظر را restore کنید: git restore path/to/file.
3. اگر تغییر درست است ولی رویکرد اشتباه، branch را نگه دارید و از baseline یک branch تازه بسازید.

بر اساس مستندات checkpointing Anthropic، checkpoint ویرایش‌هایی را ثبت می‌کند که ابزارهای ویرایش Claude Code انجام داده‌اند. فایل‌هایی که یک فرمان Bash با rm، mv یا cp عوض کرده، تغییرات دستی هم‌زمان و اثر روی API، دیتابیس یا deployment الزاماً با rewind برنمی‌گردند. پس rollback واقعی یعنی checkpoint به‌علاوهٔ Git و backup؛ نه یکی به‌جای دیگری.

آخرین بررسی: ۲۱ ژوئیهٔ ۲۰۲۶. محدودیت checkpoint از منبع رسمی بالا آمده است.

دسترسی به Claude Code از ایران

مسیر رسمی Anthropic به حساب و روش پرداخت پشتیبانی‌شده وابسته است و شرایط دسترسی می‌تواند با موقعیت، حساب و سیاست سرویس تغییر کند. استفاده از حساب مشترک، credential ناشناس یا کلیدی که فروشنده بین چند نفر پخش کرده، فقط مسئلهٔ راحتی نیست؛ audit مصرف و امکان قطع دسترسی را هم مبهم می‌کند. برای بحث متمرکزتر دربارهٔ حساب و ریسک‌ها، راهنمای دسترسی امن‌تر به Claude از ایران را بخوانید.

هیچ‌کدام از این مسیرها تضمین «بدون بن»، دسترسی همیشگی یا ریسک صفر نیست. پیش از واردکردن کد خصوصی، شرایط سرویس، مسیر عبور داده، نگه‌داری لاگ، امکان ابطال کلید و سقف مصرف را بررسی کنید. برای پروژهٔ کاری حساس، تصمیم دسترسی را با مالک داده و سیاست امنیتی تیم هماهنگ کنید؛ میان‌بُر ارزان ممکن است گران‌ترین بخش پروژه شود.

خطاهای رایج

فرمان claude پیدا نمی‌شود

ترمینال را بازگشایی کنید و مسیر نصب را با which -a claude یا where.exe claude ببینید. چند نصب هم‌زمان native، Homebrew یا npm می‌تواند نسخه‌ها را با هم قاطی کند. راهنمای رسمی عیب‌یابی نصب و ورود محل‌های رایج binary را فهرست کرده است.

مرورگر ورود باز نمی‌شود

در جریان ورود c را بزنید و URL را دستی باز کنید. در محیط remote ممکن است مرورگر کدی بدهد که باید در terminal وارد شود. بعد از پایان، claude auth status --text را اجرا کنید؛ دیدن صفحهٔ موفق مرورگر به‌تنهایی اثبات فعال بودن credential در shell فعلی نیست.

Claude فایل اشتباه را تغییر می‌دهد

کار را متوقف کنید، با /rewind به checkpoint مناسب برگردید و درخواست را با نام فایل، رفتار مورد انتظار و فرمان تست محدود کنید. سپس در Plan mode از آن بخواهید قبل از edit فهرست فایل‌های هدف را اعلام کند.

هزینه یا مصرف نامشخص است

داخل session از /usage و /status استفاده کنید و مرجع صورتحساب روش اتصال خود را ببینید. Anthropic در راهنمای مدیریت هزینه توضیح می‌دهد که عدد session برای کاربران API برآورد محلی است و صورتحساب Console مرجع نهایی است؛ مصرف اشتراک‌ها هم سازوکار متفاوتی دارد. آخرین بررسی: ۲۱ ژوئیهٔ ۲۰۲۶.

چک‌لیست تحویل اولین تغییر

• claude --version نسخه را نشان می‌دهد.
• claude auth status --text روش اتصال مورد انتظار را تأیید می‌کند.
• پروژه پیش از شروع یک commit تمیز دارد.
• Claude ابتدا در plan یا default پروژه را شناخته است.
• CLAUDE.md فرمان تست و محدودیت‌های واقعی را ثبت کرده است.
• تست خارج از ادعای ایجنت و در terminal اجرا شده است.
• git diff فایل ناخواسته، secret یا تغییر قفل dependency ندارد.
• برای rollback هم checkpoint و هم Git در دسترس‌اند.

این آموزش نصب، فقط یک شاخه از مسیر بزرگ‌تر است. پیلار برنامه‌نویسی با هوش مصنوعی چرخهٔ spec، diff، test، review و rollback را کامل می‌کند؛ برای دیدن تفاوت سطح محصول هم راهنمای Codex چیست را بخوانید.

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

Claude Code چیست؟

Claude Code ابزار عامل‌محور Anthropic برای کار با کد از داخل terminal است. می‌تواند مخزن را بررسی کند، فایل‌ها را ویرایش کند و با permission مناسب تست و فرمان‌های توسعه را اجرا کند.

آیا برای نصب Claude Code به Node.js نیاز دارم؟

نصب native پیشنهادی Anthropic به Node.js وابسته نیست. بااین‌حال پروژهٔ نمونهٔ این آموزش برای اجرای JavaScript و node:test به Node.js 20 یا جدیدتر نیاز دارد.

آیا Claude Code رایگان است؟

استفاده به یک روش احراز هویت و دسترسی پشتیبانی‌شده نیاز دارد؛ ممکن است از اشتراک Claude یا مصرف API در Console استفاده کنید. چون پلن و قیمت متغیر است، صفحهٔ رسمی حساب یا صورتحساب خود را در تاریخ استفاده بررسی کنید. آخرین بررسی: ۲۱ ژوئیهٔ ۲۰۲۶.

بهترین permission برای شروع کدام است؟

برای مخزن ناآشنا plan و برای اولین تغییر واقعی default انتخاب‌های محافظه‌کارانه‌اند. acceptEdits بعد از شناخت diffها مفید می‌شود؛ bypassPermissions را فقط در محیط ایزوله در نظر بگیرید.

CLAUDE.md را کجا بگذارم؟

برای قواعد مشترک پروژه آن را در ./CLAUDE.md یا ./.claude/CLAUDE.md قرار دهید و همراه مخزن commit کنید. تنظیمات شخصی سراسری می‌تواند در ~/.claude/CLAUDE.md باشد، اما secret را داخل هیچ‌کدام نگذارید.

آیا /rewind همه‌چیز را برمی‌گرداند؟

خیر. checkpoint ویرایش‌های ابزارهای edit را پوشش می‌دهد، نه لزوماً اثر فرمان‌های shell، تغییرات بیرونی، دیتابیس یا deploy. برای تاریخچهٔ پایدار همچنان Git و backup لازم است.

چطور Claude Code را از ایران متصل کنم؟

ابتدا امکان استفاده از مسیر رسمی را با شرایط جاری حساب و سیاست Anthropic بسنجید. اگر روش ثالث را بررسی می‌کنید، کلید اختصاصی، مشاهده مصرف، امکان ابطال، مسیر داده و سقف هزینه را ارزیابی کنید و راهنمای حساب Claude برای کاربران ایران را نیز ببینید؛ هیچ راهی ریسک صفر یا تضمین بدون مسدودشدن ندارد.

از کجا بفهمم تغییر Claude واقعاً درست است؟

معیار پذیرش را قبل از edit تعریف کنید، تست را در terminal خودتان اجرا کنید و git diff را خط‌به‌خط بخوانید. پاسخ مطمئن ایجنت مدرک نیست؛ تست قابل تکرار و review مدرک‌اند.

شروع کوچک، تحویل قابل‌اندازه‌گیری

در آموزش Claude Code مهم‌ترین مهارت حفظ‌کردن فرمان‌ها نیست؛ ساختن یک حلقهٔ کنترل است: baseline تمیز، درخواست محدود، permission حداقلی، تست مستقل، review و راه بازگشت. پروژهٔ نمونه را یک‌بار از ابتدا بسازید و عمداً یک تغییر بد را با /rewind و Git برگردانید. وقتی بازگشت را تمرین کرده باشید، تازه آماده‌اید Claude Code را وارد مخزن جدی‌تر کنید.

برای تصمیم‌های دسترسی و حساب، مسیر جداگانهٔ استفاده از Claude برای کاربران داخل ایران مکمل همین راهنمای فنی است.

---

تیم تحریریه کلادی — آموزش مستقل و کاربردی فناوری و هوش مصنوعی برای فارسی‌زبانان.