درس ۳ از ۵

ه — مرجع: Decision matrix جامع و خلاصه‌ی stack

این بخش یک مرجع متراکم است برای زمانی که در حین کار واقعی نمی‌دانید کدام primitive درست است.

الف. canon یعنی Explore → Plan → Code → Commit

نقل قول رسمی: «Letting Claude jump straight to coding can produce code that solves the wrong problem. Use Plan Mode to separate exploration from execution.»

فازها: 1. Explore — Plan Mode، read-only. 2. Plan — plan مکتوب، با Ctrl+G ویرایش کنید. 3. Code — Normal Mode، پیاده‌سازی + verify. 4. Commit — commit message توصیفی + PR.

ب. سلسله‌مراتب CLAUDE.md

ترتیب load (specific ترین برنده، همگی concat می‌شوند): 1. CLAUDE.md Managed policy (قابل exclude نیست). 2. User: ~/.claude/CLAUDE.md. 3. ancestor walk پروژه: …/CLAUDE.md، …/CLAUDE.local.md از cwd به بالا. 4. subdirectory CLAUDE.md (on-demand وقتی Claude در آن subdir فایل می‌خواند).

قواعد کیفیت (verbatim): - هدف: زیر ۲۰۰ خط. - «Keep it concise. For each line, ask: 'Would removing this cause Claude to make mistakes?' If not, cut it.» - از @path برای organization استفاده کنید (هزینه‌ی context کم نمی‌شود ولی فایل تمیزتر می‌شود). - از .claude/rules/*.md با frontmatter paths: برای rule های path-scoped استفاده کنید. - «Bloated CLAUDE.md files cause Claude to ignore your actual instructions!»

ج. Decision matrix کامل: Subagent vs Skill vs Hook vs MCP vs CLAUDE.md vs Rule vs Team

Primitive محل Trigger Context loaded بهترین کاربرد
CLAUDE.md فایل‌های CLAUDE.md همیشه (هر session) بدنه‌ی کامل، هر session fact های ثابت، convention
Path-scoped rule .claude/rules/*.md با paths: auto وقتی فایل‌های تطابق خوانده می‌شوند بدنه‌ی کامل، on match convention مخصوص ناحیه‌ای از کد
Skill .claude/skills/<name>/SKILL.md model-invoked (auto از description) یا /skill-name بدنه فقط هنگام استفاده playbook قابل استفاده مجدد، procedure on-demand
Subagent .claude/agents/<name>.md تطابق description، @agent-name, --agent context window خودش research، worker تخصصی، کنترل هزینه با Haiku
Hook settings.json رویداد lifecycle (PreToolUse و غیره) N/A — اجرای deterministic automation که حتماً باید رخ دهد، validation، block کردن
MCP .mcp.json یا claude mcp add فراخوانی tool به mcp__<server>__<tool> توضیحات tool در context سیستم بیرونی (DB, Figma, browser, Jira)
Agent team config در agent-teams/ team lead سشن‌ها را spawn می‌کند یک context per teammate همکاری موازی، cross-session

د. لیست کانونیک hook event ها

  • Per-session: SessionStart, SessionEnd.
  • Per-turn: UserPromptSubmit, Stop, StopFailure.
  • Per-tool-call: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, PermissionDenied.
  • Async: FileChanged, CwdChanged, ConfigChange, Notification, WorktreeCreate, WorktreeRemove, InstructionsLoaded, PreCompact, PostCompact, Elicitation, ElicitationResult, SubagentStart, SubagentStop, PostToolBatch, TaskCreated, TaskCompleted, TeammateIdle, UserPromptExpansion, Setup.

رویدادهای block-capable با exit code 2 یا decision: "block" / permissionDecision: "deny" پاسخ می‌دهند. PostToolUse نمی‌تواند block کند (action قبلاً اجرا شده)؛ برای block از PreToolUse استفاده کنید.

ه. مرجع SDK — Claude Agent SDK

یادآوری: نام قبلی Claude Code SDK بود؛ rename به Claude Agent SDK.

  • نصب: pip install claude-agent-sdk (Python) / npm install @anthropic-ai/claude-agent-sdk (TS).
  • دو entrypoint: query() async iterator برای task یک‌بار مصرف؛ ClaudeSDKClient برای agent stateful چندنوبتی.
  • شکل options (Python ClaudeAgentOptions / TS options): allowed_tools / allowedTools, disallowed_tools / disallowedTools, max_turns / maxTurns, model, permission_mode / permissionMode (default|acceptEdits|auto|dontAsk|bypassPermissions|plan), system_prompt, mcp_servers / mcpServers, agents, hooks, setting_sources / settingSources, resume (session_id).
  • hook اختصاصی Python callable / TS callback است که (input_data, tool_use_id, context) می‌گیرد و یک dict با شکل JSON برمی‌گرداند.
  • subagent ها از طریق AgentDefinition (Python) یا object inline (TS) declare می‌شوند؛ Agent را در allowedTools parent بگذارید.
  • session ها به‌صورت JSONL روی filesystem persist می‌شوند؛ session_id را از SystemMessage اولیه capture کنید و با resume=session_id ادامه دهید.
  • مقایسه: Agent SDK = library در فرایند خودتان، file-system sandboxing؛ Managed Agents = REST API، sandbox میزبانی‌شده توسط Anthropic per session.

و. الگوهای custom slash command (که حالا skill هستند)

هر دوی .claude/commands/<name>.md و .claude/skills/<name>/SKILL.md دستور /name می‌سازند. skill ها توصیه می‌شوند چون از فایل‌های جانبی، frontmatter و auto-invocation پشتیبانی می‌کنند. الگوهای رایج:

# /commit — manual, side effects
---
name: commit
description: Stage and commit the current changes
disable-model-invocation: true
allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)
---

# /fix-issue 1234 — args via $ARGUMENTS
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS following our coding standards.

# /migrate-component SearchBar React Vue — positional args
---
name: migrate-component
description: Migrate a component from one framework to another
---
Migrate the $0 component from $1 to $2.

خلاصه فصل

سه ایده‌ی کلیدی این فصل را به ذهن بسپارید:

  1. Claude Code agentic است، نه autocomplete. هدف نهایی را توصیف کنید، معیار موفقیت بدهید (test، screenshot، expected output)، و اجازه دهید حلقه‌ی agentic مسیر را پیدا کند. context را به‌صورت aggressive مدیریت کنید.
  2. چهار primitive قابل توسعه را بدانید چه زمانی کدام را انتخاب کنید. CLAUDE.md برای fact ثابت؛ skill برای playbook on-demand؛ subagent برای worker تخصصی با context مستقل؛ hook برای دستوری که باید اجرا شود؛ MCP server برای ابزار بیرونی. این تمایز، خط بین advisory و deterministic است.
  3. دو gotcha کلیدی را در ذهن داشته باشید. اول، rename از Claude Code SDK به Claude Agent SDK (نام package جدید). دوم، CLAUDE.md صرفاً context است نه enforcement؛ اگر correctness به یک action وابسته است، آن را به hook ببرید.

این فصل پایه‌ی شماست برای فصل‌های بعدی. در فصل ۴ (Building with the Claude API) به‌صورت کامل tool use را بررسی می‌کنیم؛ در فصل ۵ روی MCP عمیق می‌شویم؛ و در فصل ۷ چارچوب AI Fluency و الگوهای کار با agent را پوشش می‌دهیم.

تمرین‌های پیشنهادی

  1. روی یک پروژه‌ی موجود claude و سپس /init اجرا کنید. خروجی CLAUDE.md را با چشم بحرانی بخوانید: کدام خط واقعاً اگر حذف شود باعث اشتباه می‌شود؟ بقیه را prune کنید تا فایل به زیر ۲۰۰ خط برسد.
  2. یک skill ساده‌ی /changelog بنویسید که با !`git log --oneline -20` آخرین کامیت‌ها را به prompt تزریق کند و یک خلاصه‌ی فارسی بسازد. آن را در .claude/skills/changelog/SKILL.md بگذارید و تست کنید.
  3. یک subagent به نام security-reviewer با مدل opus و tool های Read, Grep, Glob, Bash بسازید (الگوی Lecture 1.7 را استفاده کنید). با @agent-security-reviewer آن را روی یک diff واقعی اجرا کنید و گزارش را با review انسانی مقایسه کنید.
  4. یک hook بنویسید که قبل از هر Bash که شامل rm -rf است، آن را block کند (الگوی Lecture 2.12). در .claude/settings.json config کنید و با اجرای یک فرمان آزمایشی تست کنید.
  5. یک GitHub Action با anthropics/claude-code-action@v1 روی یک repo شخصی نصب کنید و config کنید که روی هر PR یک review امنیتی بنویسد (الگوی Lecture 2.9). --max-turns 5 و concurrency: را فراموش نکنید.
  6. یک script Python با claude-agent-sdk بنویسید که یک bug در یک repo را پیدا و fix کند (الگوی Lecture 2.16). با permission_mode="acceptEdits" اجرا کنید و session را با capture کردن session_id resume کنید.
  7. چالش design: یک رفتار «همیشه بعد از edit، prettier اجرا شود» را یک‌بار با CLAUDE.md پیاده کنید و یک‌بار با hook. تفاوت قابلیت اطمینان را در ۱۰ session مشاهده کنید — این تمرین تفاوت advisory و deterministic را عمیقاً جا می‌اندازد.

منابع تکمیلی