درس ۳ از ۵

الف — Course 1: Claude Code 101 (دوازده lecture)

این course اولین برخورد developer با ابزار است. هدف این است که در پایان یک ساعت، بتوانید Claude Code را نصب کنید، اولین prompt مفید را بنویسید، context را تمیز نگه دارید، و چهار primitive پیشرفته (subagent، skill، MCP، hook) را در سطح مفهومی توضیح دهید.

Lecture 1.1 — Claude Code چیست؟

عنوان اصلی: What is Claude Code?

هدف یادگیری: تعریف Claude Code به‌عنوان یک ابزار agentic coding و قراردادن آن روی طیف ابزارهای AI dev (autocomplete → chat assistant → agent).

مفاهیم کلیدی: agentic coding, terminal-first agent, multi-surface, agentic loop, low-level / unopinionated.

سند رسمی Anthropic Claude Code را این‌گونه تعریف می‌کند: «یک ابزار agentic coding که codebase شما را می‌خواند، فایل‌ها را ویرایش می‌کند، فرمان اجرا می‌کند و با ابزارهای توسعه‌ی شما یکپارچه می‌شود.» تفاوت کلیدی با یک chatbot این است: chatbot به سوال شما پاسخ می‌دهد، اما Claude Code می‌تواند روی یک مسئله‌ی چندفایلی به‌صورت خودگردان کار کند، در حالی که شما تماشا، اصلاح یا حتی فعالیت دیگری می‌کنید.

Claude Code در terminal اجرا می‌شود ولی منحصر به آن نیست؛ همان engine در VS Code، JetBrains، Desktop app، web، Slack و حتی CI (GitHub Actions، GitLab CI) در دسترس است. هر surface به همان موتور متصل می‌شود؛ به این معنی که CLAUDE.md، settings و MCP server ها همراه شما حرکت می‌کنند. positioning رسمی Anthropic در داخل تیم: «به‌جای اینکه شما کد بنویسید و از Claude بخواهید review کند، توصیف کنید چه می‌خواهید و Claude راه ساخت آن را پیدا می‌کند.»

این ابزار به‌صورت عمدی low-level و unopinionated طراحی شده است؛ یعنی هم به‌صورت یک REPL تعاملی استفاده می‌شود و هم به‌صورت یک building block در script های Unix-style.

مثال عملی

# interactive
claude
# one-shot, then exit
claude -p "explain what this project does"
# piped automation
tail -200 app.log | claude -p "Slack me if you see any anomalies"

اشتباهات رایج

ساختن wrapper پیچیده روی Claude Code: تیم engineering در Anthropic صریحاً توصیه می‌کند ابزار را مستقیم استفاده کنید و اجازه دهید تیم workflow خودش را پیدا کند.
استفاده از Claude Code برای کاری که autocomplete انجام می‌دهد (تک‌خط ساده) — overkill است.

Lecture 1.2 — Claude Code چگونه کار می‌کند

عنوان اصلی: How Claude Code works

هدف یادگیری: شرح agentic loop، context window، و دلیل تفاوت ماهیت Claude Code با autocomplete.

مفاهیم کلیدی: agentic loop, tool use, context window, auto-compaction, checkpoints.

Claude Code یک حلقه‌ی agentic اجرا می‌کند: ورودی را می‌خواند → تصمیم می‌گیرد چه tool ای فراخوانی شود → اجرا می‌کند (Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, Agent, Skill و غیره) → نتیجه را مشاهده می‌کند → دوباره تصمیم می‌گیرد. این حلقه آن‌قدر تکرار می‌شود تا کار تمام شود یا مدل توقف کند.

نکته‌ی حیاتی: کل مکالمه، هر فایلی که Claude خوانده، و خروجی هر فرمان همگی در یک context window مشترک هستند. هرچه این پنجره پر می‌شود، performance افت می‌کند؛ به همین دلیل اولین best practice رسمی Anthropic این جمله است: manage context aggressively.

وقتی پنجره به مرز ظرفیت نزدیک می‌شود، Claude Code فرایند auto-compaction را اجرا می‌کند: مکالمه خلاصه می‌شود و state کلیدی (فایل‌های ویرایش‌شده، تصمیم‌ها، CLAUDE.md ریشه پروژه) دوباره attach می‌شود. هر action در طول جلسه یک checkpoint می‌سازد که می‌توان با Esc + Esc یا فرمان /rewind به آن بازگشت.

مثال عملی

/clear       # reset context entirely
/compact     # manual summarization with optional focus
/rewind      # open the checkpoint menu

اشتباهات رایج

اجازه دادن یک session تبدیل به «kitchen-sink» شود — context آلوده می‌شود.
ادامه دادن یک session طولانی روی task های بی‌ربط بدون /clear.

Lecture 1.3 — اولین prompt شما

عنوان اصلی: Your first prompt

هدف یادگیری: گرفتن پاسخ مفید در همان نوبت اول با مشخص بودن خواسته و ارائه‌ی verification criteria.

مفاهیم کلیدی: verification criteria, @-references, screenshots, piped input, scoping.

پرکاربردترین توصیه‌ی صفحه‌ی best-practices این است: «test، screenshot یا expected output را همراه prompt بدهید تا Claude بتواند خودش را check کند.» یک prompt مبهم مثل «fix the login bug» را تبدیل کنید به «users report login fails after session timeout. Check the auth flow in src/auth/, especially token refresh. Write a failing test that reproduces the issue, then fix it.»

می‌توانید مستقیم image در prompt paste کنید، screenshot را drag-drop کنید، با @filename به یک فایل خاص ارجاع دهید (Claude قبل از پاسخ آن را می‌خواند) و با cat error.log | claude ورودی stdin بفرستید.

مثال عملی

what does this project do?
add a hello world function to the main file
there's a bug where users can submit empty forms - fix it
refactor the authentication module to use async/await instead of callbacks

اشتباهات رایج

توصیف فایل به‌جای ارجاع با @ («فکر کنم در پوشه‌ی auth یه فایلی هست…» — این یک tool call اضافی به Claude تحمیل می‌کند).
نگفتن معیار موفقیت؛ Claude نمی‌داند کِی کار «تمام» شده است.

Lecture 1.4 — نصب Claude Code

عنوان اصلی: Installing Claude Code

هدف یادگیری: نصب روی macOS / Linux / WSL / Windows، login و verify.

مفاهیم کلیدی: native installer (auto-updates), Homebrew cask, WinGet, Linux package managers, claude binary, /login.

مسیر پیشنهادی Anthropic، native installer است چون auto-update دارد. Homebrew و WinGet به‌صورت خودکار به‌روزرسانی نمی‌شوند؛ یعنی باید به‌صورت دوره‌ای brew upgrade claude-code یا winget upgrade Anthropic.ClaudeCode بزنید. روی Windows توصیه می‌شود Git for Windows نصب باشد تا Claude Code بتواند Bash tool را استفاده کند؛ بدون آن fallback به PowerShell می‌شود.

Authentication چند مسیر دارد: Claude Pro/Max/Team/Enterprise، Anthropic Console (با API credit)، Amazon Bedrock، Google Vertex AI و Microsoft Foundry.

مثال عملی

# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
# Homebrew
brew install --cask claude-code
# WinGet
winget install Anthropic.ClaudeCode

cd your-project
claude         # start; you'll be prompted to /login on first run

اشتباهات رایج

نصب با Homebrew و فراموش کردن upgrade ماهانه — نسخه‌ای قدیمی روی سیستم می‌ماند بدون اینکه متوجه شوید.
فراموش کردن نصب Git for Windows روی Windows.

Lecture 1.5 — Workflow روزمره: Explore → Plan → Code → Commit

عنوان اصلی: Daily Workflows: Explore → Plan → Code → Commit

هدف یادگیری: اجرای workflow کانونیک چهارفازی Anthropic.

مفاهیم کلیدی: Plan Mode, Normal Mode, Ctrl+G to edit a plan, Explore subagent, verification step, atomic commits.

Workflow کانونیک Anthropic چهار فاز دارد:

Explore — وارد Plan Mode شوید (با Shift+Tab بین mode ها سوییچ می‌شود). Claude فایل‌ها را می‌خواند و سوال‌ها را پاسخ می‌دهد بدون اینکه چیزی تغییر دهد.
Plan — از Claude بخواهید یک plan پیاده‌سازی مکتوب بنویسد. با Ctrl+G plan در editor باز می‌شود و می‌توانید قبل از اجرا مستقیم ویرایشش کنید.
Code — به Normal Mode سوییچ کنید و پیاده‌سازی را شروع کنید؛ نتیجه را با test یا screenshot تایید کنید.
Commit — از Claude بخواهید یک commit message توصیفی بنویسد و PR باز کند.

نقل قول مستقیم از best-practices: «Planning is most useful when you're uncertain about the approach, when the change modifies multiple files, or when you're unfamiliar with the code being modified. If you could describe the diff in one sentence, skip the plan.»

مثال عملی

# (Plan Mode)
read /src/auth and understand how we handle sessions and login.
also look at how we manage environment variables for secrets.

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

# (Normal Mode)
implement the OAuth flow from your plan. write tests for the
callback handler, run the test suite and fix any failures.

commit with a descriptive message and open a PR

اشتباهات رایج

ritualize کردن چهار فاز برای هر تغییر کوچک. برای rename یک متغیر یا اصلاح یک typo، plan لازم نیست.
skip کردن فاز Explore در پروژه‌ی ناآشنا — مستقیم رفتن به Code معمولاً منجر به کد نادرست می‌شود.

Lecture 1.6 — مدیریت context

عنوان اصلی: Context management

هدف یادگیری: استفاده از /clear, /compact, /rewind و subagent برای حفظ context تمیز.

مفاهیم کلیدی: context window, auto-compaction, manual /compact <focus>, /rewind checkpoints, /btw overlay, subagent delegation, status line token tracking.

پنج تکنیک به ترتیب اولویت:

/clear بین task های بی‌ربط — جلسه‌ی طولانی با context نامرتبط performance را خراب می‌کند.
/compact <focus> دستی — مثلاً /compact Focus on the API changes تا فقط همان بخش حفظ شود.
Esc + Esc یا /rewind — برگشت به checkpoint قبلی؛ می‌توانید فقط conversation، فقط code، یا هر دو را restore کنید.
/btw برای سوال جانبی — پاسخ در یک overlay قابل dismiss می‌آید و وارد تاریخچه‌ی مکالمه نمی‌شود (هزینه‌ی context صفر).
Delegate به subagent — research را به یک agent با context window جداگانه بسپارید؛ او فقط خلاصه را برمی‌گرداند.

مثال عملی

/clear
/compact Focus on the API changes
/rewind                 # or press Esc twice
/btw what is HSTS?      # quick side question, no context cost

اشتباهات رایج

نقل قول مستقیم Anthropic: «اگر بیش از دو بار در یک session مجبور به اصلاح Claude روی همان موضوع شدید، context با approach های شکست‌خورده آلوده شده است. /clear بزنید و با یک prompt دقیق‌تر شروع کنید که آنچه آموختید را در خود جای دهد.»

Lecture 1.7 — Code review

عنوان اصلی: Code review

هدف یادگیری: استفاده از Claude Code به‌عنوان reviewer (نه صرفاً writer)؛ پیاده‌سازی الگوی Writer/Reviewer.

مفاهیم کلیدی: fresh-context review, Writer/Reviewer split sessions, security-reviewer subagent, GitHub Code Review action, /review, /security-review.

یک session دوم Claude که کد session اول را review می‌کند خوب کار می‌کند؛ چون context تمیز است و bias به آنچه خودش نوشته ندارد. الگوی Writer/Reviewer رسمی Anthropic: Session A پیاده‌سازی می‌کند؛ Session B (معمولاً یک code-reviewer subagent) diff را می‌خواند و گزارش می‌دهد؛ Session A اصلاح می‌کند.

دستور /review و skill /security-review به‌صورت پیش‌فرض همراه هر نصب می‌آیند. برای PR ها هم می‌توان از GitHub Code Review action استفاده کرد که بدون trigger phrase روی هر PR review می‌نویسد.

مثال عملی

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling
Provide specific line references and suggested fixes.

اشتباهات رایج

review در همان session ای که پیاده‌سازی شد؛ خروجی self-confirming می‌شود — Claude کدی را که خودش نوشته نمی‌خواهد رد کند.

Lecture 1.8 — شخصی‌سازی: CLAUDE.md

عنوان اصلی: Customizing: CLAUDE.md

هدف یادگیری: نوشتن CLAUDE.md ای که Claude واقعاً پیروی کند؛ درک سلسله‌مراتب load.

مفاهیم کلیدی: project / user / managed / local CLAUDE.md, /init, @path imports, .claude/rules/ با paths: glob frontmatter, auto memory, claudeMdExcludes.

CLAUDE.md یک فایل markdown است که Claude در ابتدای هر مکالمه می‌خواند. تاکید می‌کنیم: این context است، نه enforced configuration. میزان پیروی Claude به کیفیت نوشتار شما بستگی دارد. فایل‌ها با walk کردن از cwd به سمت بالا load می‌شوند، بنابراین foo/bar/CLAUDE.md, foo/CLAUDE.md و هر CLAUDE.local.md همگی concat می‌شوند.

Scope	Location	Use case
Managed policy	`/Library/Application Support/ClaudeCode/CLAUDE.md` (mac), `/etc/claude-code/CLAUDE.md` (Linux), `C:\Program Files\ClaudeCode\CLAUDE.md` (Win)	استانداردهای org-wide
Project	`./CLAUDE.md` یا `./.claude/CLAUDE.md`	تیمی، در git
User	`~/.claude/CLAUDE.md`	شخصی، همه پروژه‌ها
Local	`./CLAUDE.local.md` (gitignored)	sandbox شخصی

هدف Anthropic این است که هر فایل زیر ۲۰۰ خط بماند. فایل طولانی‌تر باعث می‌شود Claude دستورهای واقعی شما را نادیده بگیرد. برای دستورهایی که فقط گاهی مهم هستند، از path-scoped rules در .claude/rules/*.md با YAML frontmatter paths: ["src/api/**/*.ts"] استفاده کنید. برای دستورهایی که فقط on-demand باید load شوند، از skill استفاده کنید.

مثال عملی

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

See @README for project overview and @package.json for available npm commands.
# Additional Instructions
- git workflow @docs/git-instructions.md

اشتباهات رایج

نقل قول مستقیم Anthropic: «Bloated CLAUDE.md files cause Claude to ignore your actual instructions!» تغییرات را با مشاهده‌ی رفتار واقعی Claude تست کنید؛ اگر دستور تاثیر نگذاشت، حذفش کنید. با /init شروع کنید و سپس refine.

Lecture 1.9 — Subagents (مرور اولیه)

عنوان اصلی: Subagents

هدف یادگیری: تشخیص اینکه چه زمانی delegate به subagent مفید است و چگونه context اصلی را حفظ می‌کند.

مفاهیم کلیدی: subagent, isolated context window, description-based delegation, built-in subagents (Explore, Plan, general-purpose), tools allowlist, model: haiku|sonnet|opus.

یک subagent در context window خودش با system prompt اختصاصی، tools محدودشده و permission مستقل اجرا می‌شود. کاربردش وقتی است که یک task جانبی در حال آلوده کردن مکالمه‌ی اصلی با log یا فایل‌هایی است که بعداً به آن برنگردید.

subagent های built-in: Explore (read-only، Haiku، بهینه برای جست‌وجو در codebase)، Plan (read-only، استفاده شده در Plan Mode) و general-purpose (همه‌ی tools). subagent اختصاصی در .claude/agents/ (project) یا ~/.claude/agents/ (user) تعریف می‌شود. Claude براساس مطابقت prompt شما با فیلد description تصمیم به delegate می‌گیرد؛ عبارت‌هایی مثل «use proactively» نرخ delegation را به‌شدت بالا می‌برد.

مثال عملی

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

اشتباهات رایج

انتظار اینکه subagent خودش subagent دیگری spawn کند (nesting وجود ندارد).
فرض اینکه subagent در parent با bypassPermissions می‌تواند permission سخت‌گیرانه‌تر بگذارد — child از parent ارث می‌برد و نمی‌تواند override کند.

Lecture 1.10 — Skills (مرور اولیه)

عنوان اصلی: Skills

هدف یادگیری: استفاده از SKILL.md برای بسته‌بندی یک playbook قابل استفاده مجدد که فقط در صورت نیاز load می‌شود.

مفاهیم کلیدی: SKILL.md, YAML frontmatter (name / description / disable-model-invocation / allowed-tools / paths / context: fork), /skill-name invocation, on-demand loading, $ARGUMENTS, !`shell` dynamic context, supporting files.

یک skill یک پوشه است شامل یک SKILL.md و فایل‌های جانبی اختیاری. Claude Code از استاندارد باز Agent Skills (agentskills.io) پیروی می‌کند. فیلد description در frontmatter به Claude می‌گوید چه زمانی به‌صورت خودکار invoke کند؛ بدنه همان playbook است.

تفاوت کلیدی با CLAUDE.md: بدنه‌ی یک skill فقط در زمان استفاده load می‌شود؛ یعنی reference docs طولانی تا قبل از trigger تقریباً هزینه‌ی صفر دارند. Custom commands با skill ادغام شده‌اند: یک فایل در .claude/commands/deploy.md و یک skill در .claude/skills/deploy/SKILL.md هر دو دستور /deploy را می‌سازند.

مثال عملی

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---
When explaining code, always include:
1. Start with an analogy
2. Draw an ASCII diagram
3. Walk through the code step-by-step
4. Highlight a gotcha

اشتباهات رایج

نوشتن SKILL.md با بیش از ۵۰۰ خط؛ توصیه‌ی رسمی: مرجع تفصیلی را به فایل‌های جداگانه ببرید.
داشتن تعداد زیاد skill با description کلی؛ توضیحات تا سقف ۱٪ context window (پیش‌فرض ~۸۰۰۰ کاراکتر) truncate می‌شوند. use case کلیدی را اول بگذارید.

Lecture 1.11 — MCP (مرور اولیه)

عنوان اصلی: MCP

هدف یادگیری: اتصال Claude Code به ابزارهای بیرونی (database, Figma, Slack, browser) از طریق Model Context Protocol.

مفاهیم کلیدی: MCP, stdio / HTTP / SSE / WebSocket transports, scopes (local / project / user), .mcp.json, claude mcp add, /mcp, MCP tools as mcp__server__tool in matchers.

MCP یک استاندارد باز برای اتصال ابزار AI به منابع داده‌ی بیرونی است. با MCP server ها، Claude Code می‌تواند design doc در Google Drive بخواند، تیکت Jira به‌روزرسانی کند، داده Slack بکشد، Postgres query کند، Playwright اجرا کند و غیره. server ها در .mcp.json (project، در git) یا با claude mcp add (local/user scope) تعریف می‌شوند. هر scope visibility متفاوت دارد: project-scoped server با repo می‌آید؛ user-scoped همراه شما در همه‌ی پروژه‌ها هست.

مثال عملی

# add a server (stdio)
claude mcp add playwright -- npx @playwright/mcp@latest
# list and authenticate servers
/mcp

// .mcp.json
{
  "mcpServers": {
    "playwright": { "type": "stdio", "command": "npx", "args": ["@playwright/mcp@latest"] },
    "github":     { "type": "http",  "url": "https://api.githubcopilot.com/mcp/" }
  }
}

اشتباهات رایج

توضیحات tool های MCP server همیشه context مصرف می‌کنند، حتی اگر استفاده نشوند. اگر یک server فقط برای یک subagent لازم است، آن را inline در فیلد mcpServers خود subagent تعریف کنید تا مکالمه‌ی parent بار اضافه نگیرد.

Lecture 1.12 — Hooks (مرور اولیه)

عنوان اصلی: Hooks

هدف یادگیری: اجرای deterministic فرمان‌های shell/HTTP/MCP در رویدادهای lifecycle برای automate، validate یا block.

مفاهیم کلیدی: hook events (PreToolUse, PostToolUse, Stop, SessionStart, UserPromptSubmit, SubagentStop, PreCompact, Notification, FileChanged)، matchers، JSON I/O over stdin/stdout، exit code 2 = blocking error، permissionDecision: "deny".

hook ها فرمان‌های shell، endpoint های HTTP، فراخوانی MCP tool، prompt یا agent هستند که در نقاط مشخصی از lifecycle (چرخه‌ی حیات) Claude Code اجرا می‌شوند. برخلاف CLAUDE.md که advisory است، hook ها deterministic هستند — harness خودش آنها را اجرا می‌کند، نه Claude.

config در ~/.claude/settings.json (user)، .claude/settings.json (project، shared) یا .claude/settings.local.json (محلی). ساختار سه‌لایه: event → matcher group → handler. Handler ها JSON روی stdin می‌گیرند و با exit code، stdout یا JSON پاسخ می‌دهند.

مثال عملی

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/format.sh" }
        ]
      }
    ]
  }
}

اشتباهات رایج

نقل قول رسمی: «Use hooks for actions that must happen every time with zero exceptions.» نکته‌ی امنیتی مهم: hook ها با privilege shell شما اجرا می‌شوند — یک hook مخرب در یک repo کلون‌شده می‌تواند کد دلخواه اجرا کند. .claude/settings.json را مثل package.json scripts review کنید.