Claude Code: اتوماسیون بازبینی کد بدون نظارت انسانی با پرچم -p

یک فلگ ساده در خط فرمان، Claude Code را از یک دستیار چت‌محور به یک عامل (Agent) برنامه‌ریزی‌شده تبدیل می‌کند که قادر به اجرای بدون نظارت است. طبق مستندات فنی منتشر شده در ۱۷ سپتامبر ۲۰۲۶، فلگ -p حالت «بدون سر» یا Headless را فعال می‌کند تا ابزار بتواند پرامپت‌های کامل را پردازش کرده و بدون نیاز به نظارت انسان بر ترمینال، به‌طور خودکار خارج شود.

این تحول در حالی رخ می‌دهد که تیم‌های عملیاتی با «گلوگاه تعاملی» دست‌وپنجه نرم می‌کنند. اکثر شکست‌های اتوماسیون هوش مصنوعی به این دلیل رخ می‌دهد که با ابزار مانند یک دستیار تحت نظارت برخورد می‌شود، در حالی که حجم کاری تولیدات صنعتی نیازمند اجرای کاملاً خودکار است. بسیاری از تیم‌ها جلسات تعاملی را داخل محیط‌های CI اجرا می‌کنند، پرامپت‌ها را به‌صورت دستی در پنجره‌های ترمینال می‌چسبانند یا بلوک‌های کد را از خروجی‌های گفتگویی کپی کرده و در اسکریپت‌های بیلد قرار می‌دهند. این روش زمانی که نیاز به اجرای تکرارپذیر، زمان‌بندی‌شده یا موازی در چندین مخزن باشد، به‌طور کامل فرو می‌پاشد. همان‌طور که در تحلیل قبلی ما درباره‌ی نحوه انتقال زمینه بین Cursor و Claude Code اشاره کردیم، این به‌روزرسانی ابزار را از یک «همکار کنار دست» به یک «زیرساخت اصلی» تبدیل می‌کند. این رویکرد در واقع تکامل همان فلسفه‌ی جایگزینی منطق صلب If/Else با استدلال هوشمند است که اجازه می‌دهد سیستم‌ها به‌جای دنبال کردن مسیرهای سخت، بر اساس تحلیل زمینه تصمیم بگیرند.

تصور کنید تغییری در ساختار داده‌ها (Schema) رخ داده و باید تست‌های ۵۰ میکروسرویس مختلف به‌روزرسانی شوند. در حالت تعاملی، یک انسان باید هر مرحله را نظارت کند. اما در حالت Headless، یک اسکریپت می‌تواند عامل را ۵۰ بار به‌صورت موازی فراخوانی کند، نتایج را بگیرد و به‌طور تمیز بسته شود. این مدل اجرا فراتر از گردش‌کار یک توسعه‌دهنده است و اجازه می‌دهد خط لوله‌ها شکست‌های تست را تحلیل کنند، مستندات را پس از تغییرات Schema به‌روز کنند یا فراخوانی‌های منسوخ‌شده API را در کل سازمان بدون دخالت دستی اصلاح نمایند. مسیر جایگزین، هر فراخوانی را از طریق فلگ -p با مدیریت صریح خروجی و کنترل جلسه هدایت می‌کند. سیستم به‌جای انتظار برای ورودی ترمینال، کل پرامپت را به‌عنوان آرگومان خط فرمان دریافت کرده، خروجی ساختاریافته را ثبت می‌کند و چه وظیفه با موفقیت انجام شود و چه با شکست، به‌طور تمیز خارج می‌شود.

مکانیسم‌های اجرای غیرتعاملی

هسته این قابلیت فلگ -p است. این فلگ رشته‌ای شامل متن کامل پرامپت را می‌پذیرد و Claude Code را بدون باز کردن جلسه تعاملی اجرا می‌کند. وقتی دستور اجرا می‌شود، مدل پرامپت را پردازش کرده، عملیات روی فایل‌ها یا تحلیل‌ها را انجام می‌دهد و با یک کد وضعیت (Status Code) که نشان‌دهنده موفقیت یا شکست است، خارج می‌شود. کل تعامل در یک فراخوانی واحد رخ می‌دهد.

برای کسانی که این قابلیت را در محیط‌های TypeScript ادغام می‌کنند، متدهای child_process.execSync یا spawn محرک‌های اصلی هستند. یک پیاده‌سازی رایج شامل قرار دادن دستور claude -p "[prompt]" در تابعی است که جریان‌های خروجی استاندارد (stdout) و جریان‌های خطا (stderr) را مدیریت می‌کند. برای مثال، می‌توان از تابعی که از execSync استفاده می‌کند برای بازسازی فایل‌های تست در tests/fixtures/users.json با خواندن یک مدل User به‌روزرسانی‌شده در src/models/user.ts استفاده کرد.

تفاوت اینجا حیاتی است. حالت تعاملی نیازمند انسانی است که خروجی را بخواند، تصمیم بگیرد آیا وظیفه با موفقیت انجام شده است یا خیر، و به‌صورت دستی جلسه را ببندد. اجرای Headless با Claude مانند یک تابع برخورد می‌کند: ورودی می‌گیرد، خروجی می‌دهد و پروسه به‌طور خودکار بسته می‌شود. این موضوع اهمیت دارد زیرا خط لوله‌های CI/CD نمی‌توانند به‌طور نامحدود منتظر ورودی کاربر بمانند و کارهای زمان‌بندی‌شده (Cron Jobs) زمانی اجرا می‌شوند که هیچ‌کس برای نظارت آنلاین نیست. این حذف اصطکاک تأیید دستی، مشابه همان تجربه‌ای است که افزونه Claude Auto-Accept در محیط VS Code برای توسعه‌دهندگان ایجاد کرد تا سرعت پذیرش تغییرات افزایش یابد.

مدیریت وضعیت با پایداری جلسه

به‌طور پیش‌فرض، Claude Code برای حفظ زمینه، سوابقی را در .claude/sessions/<session-id>.json ایجاد می‌کند. این جلسه تاریخچه گفتگو، ویرایش‌های فایل و زمینه را در فراخوانی‌های مختلف حفظ می‌کند. اگرچه این برای دیباگ تکرار شونده مفید است، اما در اتوماسیون باعث ایجاد «وضعیت پنهان» (Hidden State) می‌شود. یک شغل بازبینی شبانه نباید زمینه‌ای را از یک اجرای شکست‌خورده در ۲۴ ساعت قبل به ارث ببرد. اگر یک عامل Headless زمینه‌های قدیمی و منقضی‌شده را در طول اجراها جمع کند، می‌تواند نتایج متناقض تولید کند و دیباگ کردن آن نیازمند فرآیند هزینه‌بر بازسازی کل تاریخچه جلسه است.

برای حل این مشکل، فلگ --no-session-persistence اجرای بدون وضعیت (Stateless) را اجبار می‌کند. این کار ذخیره‌سازی جلسه را کاملاً غیرفعال می‌کند تا هر فراخوانی با زمینه صفر — به‌جز پرامپت ارائه شده و وضعیت فعلی مخزن — شروع شود. این جداسازی تضمین می‌کند که اجرای یک دستور مشابه، دو بار نتیجه یکسانی بدهد، به شرطی که کد منبع بین دو اجرا تغییر نکرده باشد.

• اجرای وضعیت‌دار (Stateful): بهترین گزینه برای بازبینی‌های چندمرحله‌ای که عامل باید تصمیمات قبلی را به یاد آورد، جلسات دیباگ تکرارشونده که هر دستور تلاش قبلی را اصلاح می‌کند، یا وظایف طولانی‌مدت عاملی که مخازن را در طول هفته‌ها نظارت می‌کند.
• اجرای بدون وضعیت (Stateless): اجباری برای تولید کد در زمان بیلد (مانند تعاریف تایپ TypeScript، خروجی‌های اسکیمای GraphQL، استخراج رشته‌های i18n)، مراحل خط لوله CI/CD که بازتولیدپذیری در آن‌ها مهم‌تر از زمینه است، و وظایف موازی که در آن چندین نمونه نباید در جلسات یکدیگر تداخل ایجاد کنند.

فرمت‌های خروجی برنامه‌ریزی‌شده

تجزیه متن ساده از یک هوش مصنوعی به‌شدت شکننده است. برای اتوماسیون قابل‌اعتماد، Claude Code سه فرمت خروجی متمایز را پشتیبانی می‌کند. این فرمت تعیین می‌کند که اسکریپت‌های پایین‌دستی چگونه داده‌های عملیاتی را از پاسخ Claude استخراج کنند:

۱. متن ساده (Plain Text): پیش‌فرض و مناسب برای لاگ‌های قابل خواندن توسط انسان، اما در برابر پاسخ‌هایی که حاوی توضیحات چندخطی، بلوک‌های کد یا داده‌های ساختاریافته هستند، مستعد شکست است.
۲. جی‌سون (--format json): استاندارد طلایی اتوماسیون. پاسخ را در یک اسکیمای پیش‌بینی‌پذیر قرار می‌دهد. یک رابط ClaudeJsonOutput معمولاً شامل response (رشته)، tokens_used (عدد)، model (رشته)، session_id (رشته اختیاری) و آرایه files_changed است. هر ورودی در files_changed مسیر (path)، عملیات (operation شامل 'created'، 'modified' یا 'deleted') و یک diff اختیاری را مشخص می‌کند.
۳. جریانی (--stream): تکه‌های JSON را با جداکننده خط جدید (newline-delimited) برای وظایف طولانی ارسال می‌کند. این حالت برای مهاجرت‌های مقیاس‌بزرگ، مانند تبدیل تمام کامپوننت‌های کلاس به کامپوننت‌های فانکشنال با هوک‌ها، که نیاز به بازخورد لحظه‌ای از پیشرفت دارند، ایده‌آل است. این فرمت نیازمند تجزیه مبتنی بر رویداد (event-based parsing) و مدیریت بافر است.

استفاده از خروجی JSON اجازه می‌دهد اسکریپت‌های بعدی بدون استفاده از «ژیمناستیک‌های Regex» (عبارات منظم پیچیده)، اقدامات خاصی را فعال کنند. برای مثال، یک خط لوله می‌تواند از آرایه files_changed استفاده کند تا بررسی نوع (Type-checking) را فقط روی فایل‌های TypeScript خاصی که عامل تغییر داده اجرا کند، کش‌های مربوط به پیکربندی‌های به‌روزرسانی‌شده را باطل کند یا فایل‌های خاصی را برای یک commit آماده (stage) کند. توازن در اینجا این است که در حالی که Streaming پیشرفت را نشان می‌دهد، JSON نتایج کامل را در یک عملیات تجزیه واحد ارائه می‌دهد که معمولاً تعادل درستی برای CI/CD است.

زمان‌بندی با Cron و CI/CD

اتوماسیون‌های تولیدی معمولاً وظایف Claude Code را از طریق Cron Jobs برای نگهداری دوره‌ای یا هوک‌های CI/CD برای اجرای رویداد-محور زمان‌بندی می‌کنند. الگو ساده است: فراخوانی -p را در یک اسکریپت شل قرار دهید، خروجی را برای لاگ‌گیری ثبت کنید و در صورت شکست، با یک وضعیت غیرصفر (non-zero status) خارج شوید تا سیستم ارکستراسیون متوجه شکست وظیفه شود.

پیاده‌سازی Cron:

• زمان‌بندی: یک ورودی crontab (مثلاً 0 2 * * * node /opt/automation/scripts/nightly-refactor.js) می‌تواند یک اسکریپت بازبینی شبانه را هر شب ساعت ۲ صبح به وقت سرور اجرا کند.
• لاگ‌گیری: اسکریپت‌ها می‌توانند نتایج را با برچسب‌های زمانی ISO در /var/log/claude-automation/refactor.log ضمیمه کنند تا تحلیل‌های پس از حادثه (post-mortem) در صورت بروز باگ در بازبینی تسهیل شود.
• مثال وظیفه: اسکن پوشه src/ برای متدهای منسوخ‌شده lodash و تبدیل آن‌ها به معادل‌های native ES2023، شامل به‌روزرسانی importها و اجرای تست‌ها.

ادغام در CI/CD:

• رویداد-محور: GitHub Actions می‌تواند پس از اینکه یک workflow_run با وضعیت 'failure' به پایان رسید، Claude را فعال کند.
• حلقه تحلیل: گردش‌کار می‌تواند لاگ‌های تست شکست‌خورده را از طریق gh run view ${{ github.event.workflow_run.id }} --log-failed > test-failures.txt دریافت کند، آن‌ها را از طریق -p به Claude بفرستد تا علت ریشه‌ای را تحلیل کند و پاسخ JSON حاصل را با استفاده از jq و gh pr comment به‌عنوان کامنت در Pull Request ارسال کند.
• مدیریت Timeout: به‌دلیل اینکه بازبینی‌های پیچیده که مخازن بزرگ را اسکن می‌کنند ممکن است از محدودیت‌های پیش‌فرض Runner فراتر روند، توسعه‌دهندگان باید از گزینه timeout در child_process.exec (مثلاً ۶۰۰,۰۰۰ میلی‌ثانیه برای تایم‌اوت ۱۰ دقیقه‌ای) یا دستور timeout-minutes در GitHub Actions استفاده کنند تا از معلق ماندن شغل‌ها جلوگیری شود. در صورت وقوع تایم‌اوت، این اتفاق باید به‌عنوان شکست تلقی شده و خروجی‌های ناقص لاگ شوند.

مقیاس‌دهی از طریق گردش‌کارهای چندعاملی

سیستم‌های تولیدی اکنون می‌توانند چندین جلسه Headless مستقل را به‌صورت موازی اجرا کنند. با استفاده از Promise.allSettled در TypeScript، توسعه‌دهندگان می‌توانند عامل‌ها را در دایرکتوری‌های کاری (cwd) مختلف هماهنگ کنند. این کار مانع از آن می‌شود که یک وظیفه شکست‌خورده، سایر وظایف موازی (sibling tasks) را مسدود کند و اجازه می‌دهد سیستم نتایج را تجمیع کرده و وضعیت خطای هر عامل را به‌طور مستقل مدیریت کند.

این الگو به تیم‌ها اجازه می‌دهد میان‌افزار احراز هویت را در کل معماری میکروسرویس‌ها به‌طور هم‌زمان بازبینی کنند (مثلاً در api-gateway ،user-service ،payment-service و notification-service). هر عامل در ایزولاسیون کامل با --no-session-persistence اجرا می‌شود تا نشت وضعیت بین سرویس‌ها رخ ندهد. گزینه cwd تضمین می‌کند که عملیات روی فایل‌ها دقیقاً مخزن درست را هدف قرار دهند.

برای جلوگیری از برخورد با محدودیت‌های نرخ API (Rate Limits)، الگوی توصیه‌شده «دسته‌بندی» (Batching) است. اجرای ۱۰ نمونه موازی، ۱۰ درخواست هم‌زمان به بک‌اند Anthropic ارسال می‌کند که زمان کل (wall-clock time) را کاهش می‌دهد اما سهمیه API را سریع‌تر مصرف می‌کند. به‌جای اجرای ۱۰۰ عامل به‌طور هم‌زمان، توسعه‌دهندگان می‌توانند آن‌ها را در دسته‌های کوچک (مثلاً ۵ تایی) با استفاده از یک تابع batching پردازش کنند. این کار زمان کل را کاهش داده و در عین حال به سهمیه API و محدودیت‌های منابع سیستم مانند CPU و حافظه احترام می‌گذارد.

مدیریت خطای سطح تولید

عامل‌های خودکار برای بقا در برابر شکست‌های گذرا در API یا وضعیت‌های غیرمنتظره مخزن، نیازمند تفکیک بین خطاهای «قابل تلاش مجدد» (Retriable) و «خطاهای نهایی» (Terminal) هستند. این الگو خطاهایی که با گذشت زمان حل می‌شوند را از خطاهایی که نیازمند تغییر دستی کد هستند جدا می‌کند.

طبقه‌بندی خطاها:

• خطاهای قابل تلاش: الگوهایی شامل /rate limit/i ،/timeout/i ،/network error/i ،/ECONNREFUSED/i ،/ETIMEDOUT/i و /503 Service Unavailable/i. این‌ها با استراتژی «عقب‌نشینی نمایی» (Exponential Backoff) مدیریت می‌شوند، با استفاده از یک تأخیر پایه (مثلاً ۱۰۰۰ میلی‌ثانیه) که در هر تلاش تا سقف حداکثری (مثلاً ۳۰۰۰۰ میلی‌ثانیه) دو برابر می‌شود.
• خطاهای نهایی: مشکلاتی مانند 'permission denied' یا پرامپت‌های بدساخت. این‌ها باید فوراً هشدار دهند و با process.exit(1) یا process.exit(2) خارج شوند تا شکست را به سیستم ارکستراسیون اعلام کنند، زیرا تلاش مجدد برای این خطاها فقط سهمیه API را بدون هیچ پیشرفتی می‌سوزاند.

نظارت و لاگ‌گیری:

• لاگ‌های ساختاریافته: استفاده از JSON برای لاگ‌ها (ثبت برچسب زمانی، وضعیت، شماره تلاش و طول پرامپت/خروجی) اجازه ادغام با سیستم‌های تجمیع لاگ مانند Elasticsearch یا Datadog را می‌دهد.
• آستانه هشدار: سه خطای متوالی Rate Limit نشان می‌دهد که آهنگ اتوماسیون از سهمیه API فراتر رفته است، در حالی که خطاهای Timeout مکرر در یک مخزن خاص، نشان‌دهنده این است که اندازه کد منبع نیازمند مقادیر Timeout بیشتر یا کاهش دامنه پرامپت است. خطاهای نهایی مانند عدم دسترسی (permission denied) نیازمند هشدار فوری هستند زیرا نشان‌دهنده مشکلات پیکربندی هستند که تمام اتوماسیون را مسدود می‌کنند.

مقایسه: حالت تعاملی در برابر Headless

این چرخش عملیاتی به این معناست که پیچیدگی از «نظارت دستی» به «مدیریت صحیح خطا و منطق تلاش مجدد» منتقل می‌شود. پرامپت‌هایی که فرض می‌کنند هوش مصنوعی سؤالات شفاف‌ساز می‌پرسد، در حالت Headless خروجی ناقص تولید می‌کنند. کدی که انتظار دارد توسعه‌دهنده diffها را قبل از ادامه بررسی کند، در صورت بروز خطا در میانه وظیفه، مخزن را در وضعیت ناسازگاری رها می‌کند. موفقیت در اتوماسیون Headless نیازمند پرامپت‌هایی است که مدیریت خطا، مراحل اعتبارسنجی و رویه‌های بازگشت (Rollback) را به‌طور صریح مشخص کنند.

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

با --no-session-persistence چه اتفاقی برای داده‌های جلسه می‌افتد؟
Claude نوشتن هرگونه تاریخچه روی دیسک را نادیده می‌گیرد و هر فراخوانی را با یک صفحه سفید شروع می‌کند. داده‌های جلسه پس از خروج پروسه کاملاً ناپدید می‌شوند و این امر نتایج بازتولیدپذیر را در اجراهای مختلف تضمین می‌کند.

آیا حالت Headless به فایل‌های خارج از مخزن دسترسی دارد؟
بله، با همان مجوزهای سیستم‌فایلی که پروسه فراخواننده دارد عمل می‌کند. اگر اسکریپت توسط کاربری با دسترسی به /etc یا دایرکتوری‌های سیستم اجرا شود، Claude می‌تواند آن فایل‌ها را بخواند و تغییر دهد، اما این کار ریسک‌های امنیتی شدیدی ایجاد می‌کند و باید در محیط تولید اجتناب شود.

پرامپت‌های طولانی‌تر از محدودیت شل چگونه مدیریت می‌شوند؟
توسعه‌دهندگان باید پرامپت را در یک فایل موقت نوشته و از جایگزینی دستور استفاده کنند: claude -p "$(cat prompt.txt)". برای استفاده برنامه‌ریزی‌شده، ارسال پرامپت از طریق stdin به‌جای -p محدودیت‌های طول آرگومان را به‌طور کامل دور می‌زند.

آیا تمام ابزارها در حالت Headless پشتیبانی می‌شوند؟
بله، به تمام ابزارها (عملیات فایل، دستورات شل، جست‌وجو) دسترسی دارد مگر اینکه با --allowedTools محدود شوند. اما چون نمی‌تواند در صورت شکست یک عملیات ابزاری سؤال شفاف‌ساز بپرسد، پرامپت‌ها باید شامل دستورالعمل‌های جایگزین (Fallback) باشند.

تأثیر موازی‌سازی بر عملکرد چیست؟
زمان کل (Wall-clock time) تا سقف Rate Limit به‌صورت تقریباً خطی کاهش می‌یابد، اما مصرف کل توکن‌ها و هزینه یکسان می‌ماند. توازن در بار زیرساختی است: ۱۰ پروسه هم‌زمان CPU و حافظه بیشتری نسبت به یک پروسه متوالی مصرف می‌کنند.

این گذار، نقش توسعه‌دهنده را از یک «خلبان» به یک «ارکستراتور» تغییر می‌دهد. هدف دیگر چت کردن با کد نیست، بلکه ساخت سیستمی است که تعامل هوش مصنوعی با کد را مدیریت کند. برای پیاده‌سازی این موضوع از امروز، با شناسایی یک وظیفه تکراری و کم‌ریسک — مانند به‌روزرسانی مستندات پس از تغییر Schema — شروع کنید و آن را در یک فراخوانی بدون وضعیت -p در خط لوله CI خود قرار دهید.

گام بعدی شما

• یک وظیفه تکراری و کم‌ریسک (مانند به‌روزرسانی مستندات پس از تغییر Schema) را شناسایی کنید.
• آن را در یک فراخوانی بدون وضعیت -p در خط لوله CI خود پیاده کنید.
• خروجی را به فرمت JSON تغییر دهید تا بتوانید تغییرات فایل‌ها را به‌طور خودکار اعتبارسنجی کنید.

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