راهنمای عملی Claude Code به زبان ساده: نصب روی مک، لینوکس و ویندوز، فایل CLAUDE.md، حالت‌های مجوز، دستورهای روزانه، MCP، هوک‌ها و اجرای خودکار در ترمینال.
Claude Code ایجنت برنامه‌نویسی شرکت Anthropic است که داخل ترمینال کار می‌کند. به آن می‌گویید چه می‌خواهید، و خودش فایل‌های پروژه را می‌خواند، کد را ویرایش می‌کند، فرمان‌ها و تست‌ها را اجرا می‌کند و نتیجه را گزارش می‌دهد. فرقش با یک پنجره گفت‌وگوی معمولی همین است: به‌جای اینکه کد را کپی کنید و جواب را برگردانید، خود ابزار روی پروژه شما کار می‌کند و پیش از کارهای حساس از شما اجازه می‌گیرد.
این راهنما از صفر شروع می‌کند: نصب، اولین جلسه کار، نوشتن فایل دستورکار پروژه، تنظیم مجوزها، دستورهای روزانه، اتصال ابزارهای بیرونی و اجرای خودکار. همه فرمان‌ها و نام‌ها در ۶ مهر ۱۴۰۵ (۲۸ سپتامبر ۲۰۲۶) با مستندات رسمی Claude Code تطبیق داده شده‌اند. این ابزار تقریباً هر هفته نسخه تازه می‌گیرد؛ اگر فرمانی رفتار دیگری داشت، صفحه مستندات پیوندشده را ببینید.
تصویر رسمی Anthropic برای Claude Code
Claude Code را می‌شود همکاری در نظر گرفت که به کل پوشه پروژه دسترسی دارد. می‌تواند ساختار پروژه را توضیح دهد، علت یک خطا را پیدا کند، تست بنویسد، کد قدیمی را بازنویسی کند، پیام کامیت پیشنهاد دهد و تغییرات را پیش از ارسال بازبینی کند. برای هر کار، اول فایل‌های مرتبط را می‌خواند، بعد راه‌حلی پیشنهاد می‌دهد و سپس تغییر را اعمال می‌کند.
همین ابزار به چند شکل در دسترس است: نسخه خط فرمان که موضوع اصلی این راهنماست، افزونه VS Code و JetBrains، اپلیکیشن دسکتاپ و نسخه وب. تنظیمات، فایل‌های دستورکار و مجوزها میان این‌ها مشترک است؛ پس هرچه اینجا یاد بگیرید در بقیه هم به کارتان می‌آید. اگر ایجنتی متن‌باز می‌خواهید که به مدل دلخواه خودتان وصل شود، آموزش OpenCode و آموزش Qwen Code را هم ببینید.
یک نکته را از همین ابتدا در نظر داشته باشید: Claude Code روی سیستم شما فرمان اجرا می‌کند. سرعتش زیاد است و اشتباهش هم می‌تواند به همان سرعت اتفاق بیفتد. بخش بزرگی از این راهنما درباره این است که چطور کنترل کار را در دست خودتان نگه دارید.
طبق صفحه نصب رسمی Claude Code، این حداقل‌ها لازم است:
روش پیشنهادی Anthropic، نصب‌کننده مستقل است که به‌روزرسانی را هم خودش انجام می‌دهد. در مک، لینوکس یا WSL این فرمان را در ترمینال اجرا کنید:
curl -fsSL https://claude.ai/install.sh | bash
در ویندوز، اگر از PowerShell استفاده می‌کنید:
irm https://claude.ai/install.ps1 | iex
و اگر در CMD هستید:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
برای اینکه بفهمید در کدام محیط هستید، به ابتدای خط فرمان نگاه کنید: در PowerShell عبارت PS پیش از مسیر می‌آید و در CMD نمی‌آید. نصب Git for Windows اختیاری است اما توصیه می‌شود، چون در آن صورت Claude Code فرمان‌ها را با Bash اجرا می‌کند.
راه‌های دیگر نصب هم وجود دارد:
# Homebrew (macOS)
brew install --cask claude-code
# WinGet (Windows)
winget install Anthropic.ClaudeCode
# npm (requires Node.js 22 or later)
npm install -g @anthropic-ai/claude-code
نسخه‌ای که با Homebrew یا WinGet نصب می‌شود خودکار به‌روز نمی‌شود و باید هر چند وقت یک بار brew upgrade claude-code یا winget upgrade Anthropic.ClaudeCode را اجرا کنید. در روش npm هرگز از sudo استفاده نکنید؛ مستندات صریحاً می‌گوید این کار هم دردسر دسترسی می‌سازد و هم ریسک امنیتی دارد.
بعد از نصب، یک پنجره ترمینال تازه باز کنید و نصب را بررسی کنید:
claude --version
claude doctor
فرمان اول شماره نسخه را چاپ می‌کند. فرمان دوم، بدون اینکه جلسه‌ای شروع شود، سلامت نصب، خطاهای فایل تنظیمات و وضعیت به‌روزرسانی خودکار را گزارش می‌دهد. اگر پیام command not found دیدید، مسیر نصب هنوز به PATH اضافه نشده است؛ ترمینال را ببندید و دوباره باز کنید.
به پوشه پروژه بروید و Claude Code را اجرا کنید:
cd path/to/your-project
claude
بار اول مرورگر برای ورود به حساب باز می‌شود. اگر متغیر محیطی ANTHROPIC_API_KEY را تنظیم کرده باشید، به‌جای مرورگر یک بار می‌پرسد که همین کلید استفاده شود یا نه. بعد از ورود، Claude Code می‌پرسد که به این پوشه اعتماد دارید یا نه. فقط پوشه‌ای را تأیید کنید که واقعاً می‌خواهید روی آن کار شود. Claude Code را در پوشه خانه کاربر یا پوشه‌ای که فایل رمز و کلید در آن نگه می‌دارید اجرا نکنید.
در شروع، فقط سؤال بپرسید و هنوز چیزی را تغییر ندهید. چند نمونه خوب برای جلسه اول:
Claude Code فارسی را خوب می‌فهمد و می‌توانید درخواست‌ها را به فارسی بنویسید. پیش از اولین تغییر واقعی، مطمئن شوید پروژه زیر کنترل git است و تغییر ذخیره‌نشده‌ای ندارید؛ فرمان git status این را نشان می‌دهد. این‌طوری هر تغییری که Claude Code بدهد دیده می‌شود و در صورت لزوم برگشت‌پذیر است.
هر جلسه Claude Code با حافظه خالی شروع می‌شود. فایل CLAUDE.md جایی است که قواعد ثابت پروژه را یک بار می‌نویسید تا در همه جلسه‌ها خوانده شود. ساده‌ترین شروع این است که داخل جلسه دستور /init را بزنید. این دستور پروژه را بررسی می‌کند و یک CLAUDE.md اولیه با فرمان‌های ساخت و تست و قراردادهایی که پیدا کرده می‌سازد. اگر فایل از قبل وجود داشته باشد، به‌جای بازنویسی، پیشنهاد اصلاح می‌دهد.
بعد خودتان چیزهایی را اضافه کنید که از روی کد قابل حدس نیست. نمونه:
# Project rules
- Build: npm run build
- Test one file: npm test -- path/to/file.test.ts
- Never edit files under migrations/ without asking
- UI strings live in src/locales/fa.json; keep Persian digits
- Done means: tests pass and git diff has been reviewed
به گفته مستندات حافظه Claude Code، این چند نکته را رعایت کنید:
CLAUDE.md یا .claude/CLAUDE.md در ریشه پروژه برای قواعد مشترک تیم که در git ثبت می‌شود؛ ~/.claude/CLAUDE.md برای ترجیح‌های شخصی شما در همه پروژه‌ها؛ و CLAUDE.local.md برای یادداشت‌های شخصی همین پروژه که نباید کامیت شود.@README یا @docs/api.md محتوای آن فایل هم همراه دستورکار خوانده می‌شود./context نشان می‌دهد کدام فایل‌های دستورکار واقعاً بارگذاری شده‌اند و /memory برای ویرایش آن‌هاست.یک نکته مهم: CLAUDE.md راهنماست، نه قفل. Claude معمولاً آن را رعایت می‌کند، اما اگر کاری باید قطعاً ممنوع باشد، باید با مجوزها یا هوک‌ها جلویش را بگیرید. رمز عبور، توکن و کلید API را هم هرگز در این فایل ننویسید.
Claude Code برای خواندن فایل‌های پروژه اجازه نمی‌خواهد، اما پیش از ویرایش فایل، اجرای فرمان و دسترسی به شبکه، بسته به «حالت مجوز» ممکن است بپرسد. طبق راهنمای حالت‌های مجوز، این حالت‌ها وجود دارد:
| حالت | رفتار | مناسب برای |
|---|---|---|
دستی، با نام default در تنظیمات | پیش از بیشتر ویرایش‌ها، فرمان‌ها و دسترسی‌های شبکه می‌پرسد | شروع کار و پروژه‌های حساس |
acceptEdits | ویرایش فایل و فرمان‌های ساده‌ای مثل ساخت و جابه‌جایی فایل را بدون پرسش انجام می‌دهد | وقتی به مسیر کار اطمینان دارید |
plan | فقط می‌خواند و بررسی می‌کند و فایلی را تغییر نمی‌دهد | پیش از تغییرهای بزرگ |
auto | یک مدل دوم هر اقدام را بررسی می‌کند و اگر با درخواست شما جور باشد، به‌جای شما تأیید می‌کند | کار روزانه با نظارت کمتر |
dontAsk | هرچه اجازه لازم داشته باشد رد می‌شود، مگر از قبل مجاز شده باشد | اجرای خودکار با فهرست مجاز مشخص |
bypassPermissions | تقریباً همه‌چیز را بدون پرسش انجام می‌دهد | فقط محیط ایزوله و دورریختنی |
از نسخه 2.1.283 به بعد، جلسه‌های تعاملی ترمینال به‌طور پیش‌فرض در حالت auto شروع می‌شوند. با کلید Shift+Tab میان حالت‌ها جابه‌جا می‌شوید: از auto به حالت دستی، بعد acceptEdits، بعد plan و دوباره حالت دستی. حالت فعلی همیشه پایین صفحه نوشته شده است.
برای قانون‌های دائمی از دستور /permissions یا فایل تنظیمات استفاده کنید. این نمونه در فایل .claude/settings.json پروژه، اجرای اسکریپت‌های npm را آزاد می‌کند و خواندن فایل‌های رمز را می‌بندد:
{
"permissions": {
"allow": ["Bash(npm run *)"],
"deny": ["Read(./.env)", "Read(./secrets/**)"]
}
}
مستندات مجوزها تأکید می‌کند که این قانون‌ها را خود Claude Code اجرا می‌کند، نه مدل؛ یعنی برخلاف CLAUDE.md با تصمیم مدل دور زده نمی‌شوند. فایل .claude/settings.json مال کل تیم است و در git ثبت می‌شود، .claude/settings.local.json فقط برای خود شماست و ~/.claude/settings.json روی همه پروژه‌هایتان اعمال می‌شود. حالت bypassPermissions یا پرچم --dangerously-skip-permissions را روی سیستم اصلی خودتان به کار نبرید. برای بحث عمیق‌تر درباره این موضوع، مقاله امنیت مجوز ابزارهای هوش مصنوعی را ببینید.
تصویر رسمی Anthropic از محیط کار Claude Code
داخل جلسه، هر پیامی که با / شروع شود یک دستور است. این‌ها پرکاربردترین‌ها هستند و فهرست کامل در صفحه دستورهای داخلی آمده است:
| دستور | کاربرد |
|---|---|
/init | ساختن فایل CLAUDE.md اولیه برای پروژه |
/plan | رفتن به حالت برنامه‌ریزی پیش از یک تغییر بزرگ |
/clear | شروع گفت‌وگوی تازه با حافظه خالی |
/compact | خلاصه‌کردن گفت‌وگو تا حافظه کاری آزاد شود |
/context | دیدن اینکه حافظه کاری با چه چیزهایی پر شده است |
/model | عوض‌کردن مدل |
/rewind | برگرداندن کد و گفت‌وگو به یک نقطه قبلی |
/resume | ادامه‌دادن یک گفت‌وگوی قبلی |
/diff | دیدن تغییرات فعلی پوشه کار |
/code-review | بازبینی تغییرات برای پیدا کردن باگ |
/usage | دیدن مصرف توکن و هزینه |
/permissions | مدیریت قانون‌های مجوز |
/doctor | عیب‌یابی نصب و تنظیمات |
وقتی گفت‌وگو طولانی می‌شود و کیفیت پاسخ‌ها پایین می‌آید، معمولاً /compact یا شروع دوباره با /clear بهتر از ادامه‌دادن است. بعد از هر کدام، قیدهای مهم کار را یک بار دیگر یادآوری کنید تا از قلم نیفتند.
درخواست خوب چهار چیز را روشن می‌کند: مشکل دقیقاً چیست، تغییر به کجا محدود است، چه چیزی نباید عوض شود، و از کجا بفهمیم کار درست انجام شده است. این دو درخواست را مقایسه کنید:
درخواست دوم هم جای حدس‌زدن را کم می‌کند و هم به شما معیاری می‌دهد که نتیجه را با آن بسنجید. برای کارهای بزرگ‌تر این ترتیب جواب می‌دهد:
Shift+Tab یا دستور /plan به حالت برنامه‌ریزی بروید و بخواهید اول بررسی کند و برنامه پیشنهاد دهد.git diff یا دستور /diff مرور کنید؛ درست همان‌طور که کد یک همکار تازه‌وارد را بازبینی می‌کنید./rewind برگردید و درخواست را دقیق‌تر بنویسید.گزارش پایانی Claude Code خلاصه‌ای از کار است، نه اثبات آن. اثبات، خروجی تست‌ها و تغییرات واقعی فایل‌هاست. در بخش‌هایی مثل ورود کاربران، پرداخت، داده شخصی و تغییر ساختار پایگاه داده، بازبینی انسانی را هیچ‌وقت حذف نکنید.
MCP استانداردی است که Claude Code را به ابزارهای دیگر وصل می‌کند؛ مثلاً پایگاه داده، سامانه مدیریت کارها، ابزار طراحی یا مستندات داخلی شرکت. طبق مستندات MCP در Claude Code، سرور راه‌دور این‌طور اضافه می‌شود:
claude mcp add --transport http notion https://mcp.notion.com/mcp
و سروری که روی سیستم خودتان اجرا می‌شود این‌طور؛ علامت -- گزینه‌های Claude را از فرمان خود سرور جدا می‌کند:
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server
پرچم --scope تعیین می‌کند سرور کجا ثبت شود: local که پیش‌فرض است و فقط برای شما در همین پروژه کار می‌کند، project که در فایل .mcp.json ذخیره و با تیم به اشتراک گذاشته می‌شود، و user که برای همه پروژه‌های شما در دسترس است. فرمان claude mcp list فهرست و وضعیت سرورها را نشان می‌دهد و داخل جلسه، دستور /mcp برای ورود به حساب سرورها و مدیریت آن‌هاست.
هر سرور MCP دسترسی Claude Code را بیشتر می‌کند. فقط سرورهایی را وصل کنید که سازنده‌شان را می‌شناسید، و بدانید سروری که محتوای بیرونی مثل صفحه وب یا ایمیل را می‌خواند، می‌تواند دستورهای مخرب را هم به داخل جلسه بیاورد. معماری امن این اتصال‌ها را در راهنمای معماری یکپارچه‌سازی MCP شرح داده‌ایم.
هوک فرمانی است که Claude Code در لحظه مشخصی از کار خودکار اجرا می‌کند؛ مثلاً بعد از هر ویرایش فایل یا پیش از اجرای یک فرمان. فرقش با CLAUDE.md این است که به تصمیم مدل بستگی ندارد و همیشه اجرا می‌شود. این نمونه از راهنمای هوک‌ها بعد از هر ویرایش، فایل تغییرکرده را با Prettier مرتب می‌کند:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
]
}
]
}
}
این تنظیم را در .claude/settings.json پروژه یا در ~/.claude/settings.json بگذارید و با دستور /hooks بررسی کنید که بارگذاری شده است. هوک با همان دسترسی‌های حساب کاربری شما اجرا می‌شود؛ پس اسکریپت‌هایش را مثل هر کد دیگری بازبینی کنید، رمزها را در خروجی‌اش چاپ نکنید و ورودی‌اش را غیرقابل‌اعتماد فرض کنید.
وقتی یک کار را چند بار در حالت تعاملی با موفقیت انجام دادید، می‌توانید آن را در اسکریپت یا خط لوله CI هم اجرا کنید. پرچم -p درخواست را اجرا می‌کند، جواب را چاپ می‌کند و خارج می‌شود. نمونه‌های زیر از مرجع خط فرمان گرفته شده‌اند:
# One-off question
claude -p "explain what src/lib/pricing.ts does"
# Pipe a log in and get JSON back
cat build.log | claude -p "why did this build fail?" --output-format json
# Cap the turns and the allowed tools
claude -p "fix the lint errors" --max-turns 5 --allowedTools "Bash(npm run lint *)" "Edit"
چند پرچم دیگر هم به کار می‌آید: claude -c آخرین گفت‌وگوی همین پوشه را ادامه می‌دهد، claude -r یک جلسه مشخص را با شناسه یا نامش از سر می‌گیرد، --permission-mode plan جلسه را در حالت برنامه‌ریزی شروع می‌کند و --add-dir پوشه دیگری را هم در دسترس قرار می‌دهد.
در اجرای خودکار کسی نیست که درخواست مجوز را ببیند. پس ابزارهای مجاز را دقیق مشخص کنید، برای تعداد نوبت‌ها سقف بگذارید، به اسکریپت کلید یا دسترسی محیط عملیاتی ندهید و خروجی را پیش از ادغام در شاخه اصلی بازبینی کنید. اینکه فرایند بدون خطا تمام شود فقط یعنی کارش را به پایان رسانده، نه اینکه کدی که نوشته درست است.
استفاده شخصی با راه‌اندازی برای یک تیم فرق دارد. پیش از اینکه ایجنت برنامه‌نویسی را در اختیار همه برنامه‌نویس‌های سازمان بگذارید، این موارد را روشن کنید:
CLAUDE.md یا AGENTS.md کوتاه در git، با فرمان‌های ساخت و تست و کارهای ممنوع؛اگر می‌خواهید ایجنت برنامه‌نویسی را با قواعد دسترسی و بازبینی روشن برای تیم نرم‌افزار سازمانتان راه بیندازید، با ما صحبت کنید: تماس تلفنی با ۰۹۰۱ ۵۵۵ ۵۶۵۱ یا پیام در واتس‌اپ. جزئیات این خدمت را در صفحه آموزش هوش مصنوعی و ایجنت برنامه‌نویسی برای تیم‌ها هم می‌توانید ببینید.
همه فرمان‌ها و تنظیمات این راهنما در تاریخ بالا با این صفحه‌های رسمی تطبیق داده شد:
راهنمای عملی GitHub Copilot CLI به زبان ساده: نصب روی مک، لینوکس و ویندوز، فایل دستورکار، مجوز ابزارها، حالت برنامه‌ریزی و autopilot، MCP، اجرای برنامه‌ای و اتصال به مدل دلخواه.
ادامه مطلب
راهنمای عملی ابزار خط فرمان Antigravity گوگل به زبان ساده: نصب روی مک، لینوکس و ویندوز، فایل AGENTS.md، مجوزها و محیط ایزوله، دستورهای روزانه، MCP و اجرای خودکار.
ادامه مطلب
راهنمای عملی Codex CLI به زبان ساده: نصب روی مک، لینوکس و ویندوز، ورود به حساب، فایل AGENTS.md، محیط ایزوله و مجوزها، MCP، اجرای خودکار با codex exec و اتصال به مدلی روی سرور خودتان.
ادامه مطلباگر می‌خواهید ایجنت‌های هوش مصنوعی و اتوماسیون این راهنما را در تیم نرم‌افزار یا فرایندهای سازمانتان به کار بگیرید، از یک آزمایش کوچک شروع کنید که بتوانید نتیجه‌اش را بسنجید.