چگونه ساختار دایرکتوری‌محور، اتوماسیونِ کد را در Claude Code متحول می‌کند؟

تصور کنید تمام استانداردهای سخت‌گیرانه‌ی معماری تیم شما، به‌جای اینکه در یک فایل PDF فراموش‌شده بخوابند، توسط یک ربات در هر commit اجرا شوند. اگر برنامه‌نویس هستید و از بازبینی‌های دستی و پراکنده خسته‌اید، سیستم جدید Skills در Claude Code دقیقاً برای حل این هرج‌ومرج طراحی شده است. بازبینی‌های دستی کد اغلب نامنظم و ناسازگار هستند، اما مهارت‌های Claude Code یک فرآیند تکرارپذیر و مبتنی بر قانون را ممکن می‌سازد. با کدگذاری رویه‌های عملیاتی استاندارد (SOPs) در یک عامل مبتنی بر ترمینال، تیم‌ها تضمین می‌کنند که هر Pull Request پیش از آنکه توسط انسان دیده شود، با استانداردهای معماری خاص مطابقت داشته باشد. Claude Code به‌جای اینکه صرفاً به عنوان یک تولیدکننده‌ی کد عمل کند، به عنوان یک عامل کدنویسی در محیط ترمینال عمل می‌کند که برای خودکارسازی بخش‌های تکراری گردش کار توسعه طراحی شده است.

این تغییر، نشان‌دهنده‌ی گذار از «پرامپت‌نویسی ساده» به «اتوماسیون ساختارمند گردش کار» است. همان‌طور که در تحلیل قبلی ما درباره‌ی چارچوب 4D برای تسلط بر هوش مصنوعی اشاره کردیم، هدف نهایی عبور از تعاملات ساده و رسیدن به قابلیت‌های نسخه‌کنترل‌شده است که مستقیماً در ریپازیتوری Git پروژه قرار می‌گیرند. در این مدل، «قانون‌ها» (Rules) مانند اسناد سیاست‌گذاری (Policy Documents) هستند، اما «مهارت‌ها» (Skills) — شبیه به دستورالعمل‌های گام‌به‌گام یک آشپزخانه صنعتی که هر کس باید دقیقاً طبق آن عمل کند — نقش SOPها یا رویه‌های عملیاتی استاندارد را ایفا می‌کنند. این رویکرد باعث می‌شود توسعه‌دهندگان بتوانند سرعت بازبینی کد خود را تا ۳ برابر افزایش دهند، چرا که تمرکز مدل از حدس زدن به دنبال کردن دستورالعمل‌های دقیق تغییر می‌کند.

بر اساس مستنداتی که در جولای ۲۰۲۶ به‌روزرسانی شد، Claude Code ساختار ذخیره‌سازی خود را تغییر داد. این سیستم از فایل‌های تک‌فایلی .md که پیش‌تر در پوشه‌ی .claude/commands/ قرار داشتند، فاصله گرفت و به ساختار دایرکتوری‌محور مبتنی بر استاندارد باز agentskills.io منتقل شد. این حرکت باعث می‌شود دانش رویه‌ای تیم‌ها در یک ابزار اختصاصی و مالکیتی زندانی نشود و قابلیت جابجایی داشته باشد. اگرچه دستورات قدیمی در مسیر .claude/commands/*.md هنوز کار می‌کنند، اما فرمت دایرکتوری‌محور اکنون توصیه می‌شود زیرا از فایل‌های کمکی پشتیبانی می‌کند، کنترل بهتری بر فراخوانی‌ها دارد و دارای Frontmatter غنی‌تری است. همچنین، اگر یک دستور (Command) و یک مهارت (Skill) نام یکسانی داشته باشند، اولویت با Skill خواهد بود.

کالبدشناسی یک Skill

اکنون مهارت‌ها به‌جای فایل‌های متنی ساده، در قالب دایرکتوری تعریف می‌شوند. مکان ذخیره‌سازی دایرکتوری، محدوده اثرگذاری (Scope) آن‌ها را تعیین می‌کند:

• محدوده شخصی (Personal Scope): در مسیر ~/.claude/skills/<name>/SKILL.md قرار دارد و برای تمام پروژه‌های موجود روی آن ماشین اعمال می‌شود.
• محدوده پروژه (Project Scope): در مسیر .claude/skills/<name>/SKILL.md قرار دارد و فقط برای آن پروژه خاص اعمال می‌شود (و از طریق Git بین اعضای تیم به اشتراک گذاشته می‌شود).
• محدوده پلاگین (Plugin Scope): در مسیر <plugin>/skills/<name>/SKILL.md قرار دارد و هر جا که آن پلاگین فعال باشد، اعمال می‌گردد.

هر دایرکتوری باید فایلی داشته باشد که نام آن دقیقاً SKILL.md باشد. نام خودِ دایرکتوری، دستور slash مربوطه را تعریف می‌کند؛ برای مثال، دایرکتوری .claude/skills/code-review/SKILL.md دستور /code-review را می‌سازد. مهارت‌های پلاگین دارای فضای نام (Namespace) هستند، مانند /my-plugin:review.

برای پایین نگه داشتن هزینه‌ها و بالا بردن عملکرد، راهنما توصیه می‌کند که بدنه اصلی فایل SKILL.md زیر ۵۰۰ خط باشد. دلیل این امر آن است که بدنه فایل پس از بارگذاری در Context جلسه باقی می‌ماند و هر خط آن هزینه توکن‌های تکرار شونده را به همراه دارد. برای مدیریت این حجم و بهینه‌سازی هزینه استنتاج (Inference Cost)، توسعه‌دهندگان باید از یک چیدمان ساختارمند در دایرکتوری استفاده کنند:

• SKILL.md: هسته اصلی و الزامی شامل Frontmatter و دستورالعمل‌ها.
• references/: مستندات مفصلی که فقط در صورت نیاز و بر اساس تقاضا (On-demand) بارگذاری می‌شوند.
• scripts/: کمکی‌های اجرایی که اجرا می‌شوند اما در پرامپت بارگذاری نمی‌شوند.
• assets/: منابع استاتیک و قالب‌ها.

قدرت اصلی یک Skill در YAML frontmatter آن است که فیلدهای هسته قابل حمل و افزونه‌های خاص Claude را تعریف می‌کند. فیلدهای کلیدی عبارتند از:

• name: نام نمایشی (که به‌صورت پیش‌فرض همان نام دایرکتوری است).
• description: محرک اصلی برای فراخوانی خودکار. این بخش باید حداکثر ۱۰۲۴ کاراکتر باشد و شامل کلمات کلیدی واضح و قابل جستجو باشد تا Claude بتواند درخواست‌هایی مانند "review my code" را به مهارت صحیح متصل کند.
• argument-hint: راهنمای تکمیل خودکار (Autocomplete) که پس از تایپ دستور slash به کاربر نمایش داده می‌شود.
• allowed-tools: ابزارهایی که با فاصله یا کاما جدا شده‌اند و عامل می‌تواند بدون درخواست اجازه از کاربر از آن‌ها استفاده کند (مانند Read ،Glob ،Grep یا Bash(git *)).
• disable-model-invocation: یک کلید ایمنی حیاتی. برای گردش کارهای دارای اثر جانبی (مانند Deploy یا Commit کردن)، این مقدار باید true باشد تا Claude نتواند آن‌ها را به‌طور خودکار و بدون نظارت فعال کند.
• user-invocable: اگر روی false تنظیم شود، مهارت از منوی / مخفی شده و تنها به عنوان دانش پس‌زمینه برای مدل عمل می‌کند.
• context: fork: باعث می‌شود مهارت در یک محیط زیر-عامل (subagent) ایزوله اجرا شود.

مکانیزم‌های پیشرفته اتوماسیون

پس از ژانویه ۲۰۲۶، دو ویژگی خاص معرفی شد که به Skills اجازه می‌دهد محیط‌های پویای پروژه را مدیریت کنند. اول، متغیر $ARGUMENTS است که اجازه می‌دهد یک مهارت واحد، دامنه‌های مختلفی را هدف قرار دهد. متنی که کاربر پس از دستور تایپ می‌کند، جایگزین این متغیر در بدنه مهارت می‌شود. برای مثال، دستور /code-review می‌تواند به روش‌های مختلفی استفاده شود:

• /code-review src/user/: هدف قرار دادن یک دایرکتوری خاص.
• /code-review --staged: انجام بررسی نهایی روی تغییراتی که در Stage هستند، پیش از Commit.
• /code-review --branch: مقایسه شاخه فعلی با شاخه main پیش از ارسال PR.
• /code-review --staged --fix: شناسایی و اصلاح خودکار مشکلات تشخیص داده شده.
• استفاده از فلگ‌هایی مانند --head ،--last یا --today برای تعریف محدوده بازبینی.

دوم، استفاده از تزریق زمینه پویا (Dynamic Context Injection) از طریق دستورات ! است. این قابلیت به کلاینت Claude Code اجازه می‌دهد اسکریپت‌های شل را در مرحله پیش‌پردازش اجرا کند. خروجی این اسکریپت‌ها پیش از آنکه مدل دستورالعمل‌ها را ببیند، جایگزین مکان‌نمای (Placeholder) مربوطه می‌شود. برای مثال، یک مهارت می‌تواند از دستورات زیر استفاده کند:

• !find .claude/rules -name "*.md" | sort برای فهرست کردن تمام قوانین پروژه.
• !git diff --name-only --cached برای لیست کردن فایل‌های Stage شده.

این مکانیزم باعث حذف یک دسته رایج از خطاها می‌شود؛ جایی که مدل فراموش می‌کند فایل‌های تغییر یافته خاصی را بررسی کند یا برخی از اسناد قوانین را نادیده بگیرد.

پیاده‌سازی عملی: مهارت بازبینی کد

در یک سناریوی واقعی تولید، یک مهارت /code-review سیاست‌ها را به‌صورت سخت‌کد (Hardcode) نمی‌کند. در عوض، قوانین را به‌صورت پویا از مسیر .claude/rules/ بارگذاری می‌کند. این کار تضمین می‌کند که با تکامل معماری پروژه، اتوماسیون بدون نیاز به بازنویسی خودِ مهارت، همگام باقی بماند. این پیاده‌سازی، مهارت عمومی /code-review که به صورت پیش‌فرض توسط Claude Code ارائه شده را بازنویسی (Override) می‌کند.

این پیاده‌سازی خاص بر اساس یک فرآیند اجرای صریح پنج‌مرحله‌ای و چک‌لیست‌های مبتنی بر قانون است. خروجی حاصل، یافته‌ها را در سه سطح شدت دسته‌بندی می‌کند:

• 🚨 بحرانی (CRITICAL): نقض‌های معماری (مانند Importهای مستقیم ریپازیتوری در لایه API یا نشت منطق تجاری/Business Logic به لایه Router). برای مثال، اگر ابزار عبارت from src.user.repositories.user_repository import UserRepository را در خط ۴۵ یک فایل Router پیدا کند، آن را بحرانی علامت زده و پیشنهاد می‌دهد از لایه Service استفاده شود.
• ⚠️ هشدار (WARNING): مشکلات مربوط به قراردادها و کنوانسیون‌ها (مانند نمونه‌سازی دستی یک سرویس به‌جای استفاده از تزریق وابستگی یا Dependency Injection).
• 💡 پیشنهاد (SUGGESTION): بهبودهای جزئی (مانند افزودن Type Hintهای گم‌شده برای مقادیر بازگشتی).

این رویکرد باعث می‌شود برنامه‌نویسان توسط مسائل جزئی Linting غرق نشوند و در عین حال، نقض‌های معماری فوراً شناسایی شوند.

امنیت و حاکمیت

از آنجا که مهارت‌ها می‌توانند دستورات شل را از طریق !command اجرا کنند و ابزارها را در Frontmatter پیش‌تأیید نمایند، یک بردار حمله (Attack Vector) جدید ایجاد می‌کنند. مهارت‌ها در واقع تعاریف گردش کار اجرایی هستند، نه مستندات غیرفعال. راهنما هشدار می‌دهد که هر مهارت که در یک ریپازیتوری ناشناس قرار دارد، باید پیش از اعطای اعتماد به فضای کاری (Workspace Trust)، مورد بازرسی قرار گیرد.

برای کاهش ریسک، توسعه‌دهندگان باید اقدامات زیر را انجام دهند:

• استفاده از مجوزهای محدود: به‌جای استفاده از یک دسترسی کلی مانند Bash(*), از Bash(git *) استفاده کنند تا عامل تنها به عملیات Git محدود شود.
• بازرسی ابزارهای مجاز: تنها ابزارهایی را لیست کنند که آن رویه خاص واقعاً به آن‌ها نیاز دارد.
• غیرفعال‌سازی پیش‌پردازش: در صورت نیاز، از تنظیم disableSkillShellExecution برای خاموش کردن کامل اجرای شل استفاده کنند.

تحلیل تحریریه: حرکت به سوی «فرآیند به عنوان کد» (Process as Code)

برای یک توسعه‌دهنده حرفه‌ای، این تغییر نقش هوش مصنوعی را از یک «کمک‌خلبان» (Copilot) که صرفاً کد پیشنهاد می‌دهد، به یک «هماهنگ‌کننده» (Orchestrator) تبدیل می‌کند که یک فرآیند را تحمیل و اجرا می‌کند. با تبدیل SOPها به دارایی‌های نسخه‌کنترل‌شده در Git، شرکت‌ها می‌توانند به‌طور مؤثر توسعه‌دهندگان جونیور را وارد پروژه کنند، زیرا آن‌ها از همان نرده‌های حفاظتی (Guardrails) اتوماتیکی استفاده می‌کنند که معماران ارشد به کار می‌برند. این رویکرد به‌ویژه برای توسعه‌دهندگان مستقل جذاب است؛ همان‌طور که در بررسی نحوه استفاده توسعه‌دهندگان ایندی از Skills برای ساخت پروژه‌های تک‌فایلی مشاهده کردیم، اتوماسیون می‌تواند جایگزین یک تیم کامل عملیاتی شود.

کاربردهای واقعی این سیستم در الگوهای متنوعی دیده می‌شود. فراتر از بازبینی کد، توسعه‌دهندگان در حال پیاده‌سازی مهارت‌هایی مانند موارد زیر هستند:

• /commit-push: برای Stage کردن فایل‌ها، تولید پیام‌های Commit استاندارد (Conventional Commit) و Push کردن.
• /create-post: برای ایجاد ساختار پست‌های وبلاگی با رعایت دقیق قوانین Slug، تصویر و Frontmatter.
• /feature-image: برای برش (Crop) و تبدیل تصاویر به فرمت WebP با نسبت ۱۶:۹ در قالب یک بودجه حجمی مشخص.
• /review-skill: یک مهارت «متا» که برای بازرسی سایر فایل‌های SKILL.md بر اساس استاندارد باز استفاده می‌شود.

این معماری همچنین مشکل «مالیات پنجره زمینه» (Context Window Tax) را حل می‌کند. با انتقال مطالب مرجع سنگین به یک دایرکتوری مجزا و بارگذاری آن‌ها فقط هنگام نیاز، توسعه‌دهندگان می‌توانند اتوماسیون‌های پیچیده را بدون افزایش سرسام‌آور هزینه‌های توکن مدیریت کنند. حرکت به سمت استاندارد باز در agentskills.io نشان می‌دهد که صنعت در حال حرکت به سوی یک اکوسیستم Plug-and-play از عامل‌های هوش مصنوعی است.

نکات کلیدی در طراحی مهارت‌ها

برای به حداکثر رساندن اثربخشی این ابزارها، این اصول طراحی را در نظر بگیرید:

• توضیحات دقیق: هم چیستی و هم زمانی که مهارت باید استفاده شود را توصیف کنید (مثلاً «بازبینی کد برای انطباق با Clean Architecture» بسیار بهتر از «بازبینی کد» است).
• چک‌لیست‌های صریح: دستورات مبهم مانند «این کد را بررسی کن» را با مراحل مشخصی مانند «این ۵ مورد را بررسی کن» جایگزین کنید.
• مراحل تأیید: همیشه یک مرحله نهایی برای تأیید اینکه کد تغییر یافته Build می‌شود یا از Linting عبور می‌کند، قرار دهید.
• لینک به قوانین: از .claude/rules/ به عنوان تنها منبع حقیقت (Single Source of Truth) استفاده کنید تا از تکرار سیاست‌ها جلوگیری شود.

در گام بعدی، توسعه‌دهندگان باید بررسی کنند که چگونه این مهارت‌ها را با سرورهای Model Context Protocol (MCP) ترکیب کنند. برای مثال، دستورالعمل‌هایی مانند «پیش از نوشتن کد، Schema پایگاه داده را استعلام کن» می‌تواند در یک مهارت ادغام شود و به گردش کارهای خودکار اجازه دهد تا برای دسترسی به زمینه عمیق‌تر، با پایگاه‌های داده خارجی یا Issueهای گیت‌هاب تعامل داشته باشند.

گام بعدی شما

• ساختار دایرکتوری .claude/skills/ را در پروژه‌ی فعلی خود ایجاد و اولین SOP تیم را در آن تعریف کنید.
• از متغیر $ARGUMENTS برای ایجاد دستورات تخصصی مانند /lint --severity=high استفاده کنید.
• تمام دسترسی‌های allowed-tools را به کمترین سطح ممکن تقلیل دهید تا امنیت محیط توسعه حفظ شود.

اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — برای درک لایه‌های زیرین این پردازش‌ها، به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.