۶ الگوی CLAUDE.md برای جلوگیری از تخریب کدهای مشترک توسط عامل‌های هوش مصنوعی

اگر تیمی از مهندسان را مدیریت می‌کنید که از ابزارهای کدنویسی هوش مصنوعی استفاده می‌کنند، احتمالاً متوجه شده‌اید که هرچه سرعت تولید کد بالا می‌رود، یکدستی پروژه کمتر می‌شود. این یک تله است؛ وقتی حجم درخواست‌های ادغام (PR) از ظرفیت بررسی انسانی پیشی می‌گیرد، مدل ذهنی مشترک از کدبیس فرو می‌پاشد.

به نقل از گزارش‌های داخلی Anthropic، در سال گذشته خروجی کد هر مهندس ۲۰۰٪ افزایش یافت، اما ظرفیت بررسی کدها ثابت ماند. این عدم توازن باعث شد تنها ۱۶٪ از PRها پیش از ارسال، نظرات اصلاحی جدی دریافت کنند. فعال کردن Claude Code و کاهش سخت‌گیری در باز کردن PRها، به‌سادگی تعداد تغییرات را بالا می‌برد، اما چالش واقعی این است که اجازه ندهیم کدبیس «عجیب» شود؛ اتفاقی که بسیاری از تیم‌ها شش هفته پس از شروع کار با عامل‌ها، به طور پنهانی اعتراف می‌کنند. این ابزار پتانسیل بالایی در اتوماسیون دارد، تا جایی که در بررسی‌های اخیر توانایی Claude Code در خودکارسازی نزدیک به نیمی از کارهای نگهداری کد به بحث گذاشته شده است.

تصور کنید پنج مهندس از Claude Code روی یک مخزن استفاده می‌کنند. هر کدام تنظیمات شخصی خود را برای نام‌گذاری متغیرها یا تست‌ها دارند. بدون یک لنگر مشترک، یک عامل (Agent) — شبیه دستیاری که فقط دستورات شخصی رئیسش را می‌فهمد و از قوانین شرکت بی‌خبر است — از camelCase استفاده می‌کند، دیگری از snake_case و سومی بر تست‌های یکپارچه‌سازی پافشاری می‌کند. نتیجه این است که کدبیس طوری به نظر می‌رسد که انگار توسط پنج شرکت مختلف نوشته شده است.

همان‌طور که در تحلیل‌های قبلی ما درباره‌ی امنیت مدل‌های بازمتن اشاره کردیم، مدیریت زمینه (Context) کلید ثبات در سیستم‌های هوشمند است. بر اساس گزارشی که در ۲۱ اوت ۲۰۲۶ منتشر شد، راهکار این مشکل، تبدیل فایل CLAUDE.md از یک پرامپت ساده به یک «قانون اساسی تیم» است. این رویکرد، منبع حقیقت را از ماشین محلی هر فرد به مخزن کد (Repository) منتقل می‌کند تا هر نمونه از کلود، قوانین یکسانی را بخواند.

معماری زمینه مشترک

اولین الگوی حیاتی، سیستم دو لایه است. تیم‌ها باید یک فایل ./CLAUDE.md در ریشه مخزن برای قوانین جهانی — مانند کنوانسیون‌های کدنویسی و چک‌لیست‌های بررسی — داشته باشند. این فایل، قانون اساسی تیم است که باید از طریق PR تایید شود. هم‌زمان، مهندسان یک فایل ~/.claude/CLAUDE.md در ماشین محلی خود برای ترجیحات شخصی (مثلاً «توضیحات را برای من طولانی‌تر بنویس چون در زبان Go تازه‌کار هستم») نگه می‌دارند.

در این ساختار، فایل ریشه باید صراحتاً اعلام کند: «اگر این فایل و فایل شخصی در تضاد بودند، اولویت با این فایل است». این کار باعث می‌شود استایل‌های شخصی به محصول نهایی نشت نکند و هر PR تبدیل به یک مذاکره کوچک بین پنج سلیقه مختلف نباشد.

برای جلوگیری از شلوغ شدن قوانین جهانی، می‌توان از «بازنویسی‌های هر ماژول» استفاده کرد. Claude Code فایل‌های CLAUDE.md را در هر سطحی از دایرکتوری می‌خواند. بنابراین می‌توان در پوشه‌های خاص، فلسفه‌های متفاوتی را اعمال کرد:

• بک‌اند (/packages/backend/CLAUDE.md): مثلاً «تست‌های واحد با Vitest و شبیه‌سازی دیتابیس با آداپتور در حافظه».
• فرانت‌اند (/packages/frontend/CLAUDE.md): مثلاً «تست‌های یکپارچه‌سازی با Playwright و بدون شبیه‌سازی».

از توصیفات متنی به اجرای اجباری

محدودیت‌های متنی «نرم» هستند و عامل‌ها در جلسات طولانی یا هنگام فشار زمانی، آن‌ها را نادیده می‌گیرند. برای حل این مشکل، این چارچوب از هوک‌های (Hooks) Anthropic استفاده می‌کند تا پیشنهادات را به الزامات سخت تبدیل کند:

• PreToolUse روی Bash: دستورات را پیش از اجرا تایید می‌کند تا از دستورات خطرناکی مثل rm -rf یا پوش کردن اجباری به شاخه main جلوگیری کند.
• PostToolUse روی Edit/Write: به‌طور خودکار Linterها و بررسی‌کننده‌های نوع (Type Checkers) را اجرا می‌کند. اگر خطایی رخ دهد، خطا به کلود بازگردانده می‌شود تا بدون دخالت انسان آن را اصلاح کند.

تفاوت بین درخواست از عامل برای «لطفاً تست‌ها را اجرا کن» و استفاده از هوک PostToolUse تفاوت بین ۹۰٪ و ۱۰۰٪ رعایت قوانین است. در مقیاس تیمی، همین ۱۰٪ شکاف است که اعتماد به فرآیند بررسی را از بین می‌برد.

مقیاس‌بندی فرآیند بررسی

برای اینکه بررسی‌کنندگان انسانی تبدیل به گلوگاه نشوند، این سیستم نقش «اجراکننده» و «بررسی‌کننده» را جدا می‌کند. با ایجاد یک فایل اختصاصی .claude/CLAUDE-reviewer.md به عامل یاد داده می‌شود که چگونه یک بررسی‌کننده سخت‌گیر باشد، نه یک دستیار چاپلوس. این فایل به عامل دستور می‌دهد:

• فرض کند اجراکننده باور دارد کدش درست است.
• به دنبال وابستگی‌های پنهان، لبه‌های خاص (Edge Cases) و تغییرات ناخواسته در API بگردد.
• از بازگویی تغییرات خودداری کرده و فقط روی مشکلات تمرکز کند.
• هر نظر را در دسته‌های «باید»، «باید-که» یا «جزئی» (Nit) طبقه‌بندی کند.

این تنظیمات در محیط ابری با استفاده از GitHub Action شرکت Anthropic (نسخه v1) که در اوت ۲۰۲۵ عرضه شد، پیاده‌سازی می‌شود. این اکشن تضمین می‌کند هر PR با یک نسخه تازه از کد و بر اساس قانون اساسی تیم بررسی شود.

پیکربندی صحیح این اکشن باید به شکل زیر باشد تا از خطاهای اعتبارسنجی ورودی جلوگیری شود:

name: Claude Code Review
on: pull_request:
  types: [opened, synchronize, reopened]
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: |
            REPO: ${{ github.repository }}
            PR NUMBER: ${{ github.event.pull_request.number }}
            Review this PR against the reviewer constitution.
          claude_args: |
            --system-prompt-file ./.claude/CLAUDE-reviewer.md
          track_progress: true

نگهداری قانون اساسی

در نهایت، فایل CLAUDE.md باید مانند کد تولیدی (Production Code) مدیریت شود. تغییر در قانون اساسی نیازمند بررسی PR و تایید مالکان کد (CODEOWNERS) است. برای جلوگیری از «اصلاحات سریع» در عصر جمعه که منجر به تضاد قوانین در دوشنبه می‌شود، باید قانونی در CI تعریف شود که اگر تغییرات در CLAUDE.md و فایل‌های منبع در یک PR باشند، آن را رد کند.

یک تجربه شکست‌خورده در این مسیر، استفاده از «تیم‌های عامل» (Agent Teams) بود — ایجاد زیر-عامل‌های موازی که با هم پیام رد و بدل می‌کنند. اگرچه این روش برای بازسازی‌های پیچیده لایه‌ای جذاب بود، اما هزینه توکن (Token) — تکه‌های کوچکی از متن که مدل می‌خورد — را ۳ تا ۴ برابر افزایش داد بدون اینکه کیفیت را به طور محسوسی بالا ببرد. در همین راستا، بهینه‌سازی مصرف منابع اهمیت زیادی دارد، چنان‌که به‌روزرسانی‌های جدید Claude Code توانست هزینه‌های API را تا ۳۵ درصد کاهش دهد.

این تغییر در رویکرد، بازتابی از یک بحران صنعتی است. گزارش مهندسی هوش مصنوعی ۲۰۲۶ با بررسی ۲۲,۰۰۰ توسعه‌دهنده نشان داد که زمان میانه در بررسی PRها ۴۴۱٪ افزایش یافته است. همچنین ۳۱٪ از PRها اکنون بدون هیچ بررسی انسانی ادغام می‌شوند، نه به دلیل سیاست شرکت، بلکه چون بررسی‌کنندگان نمی‌توانند با این حجم پیش بروند.

برای توسعه‌دهنده مدرن، مهارت اصلی دیگر نوشتن پرامپت نیست، بلکه مهندسی زمینه است. فایل CLAUDE.md تبدیل به حافظه جمعی تیم می‌شود تا هر بار در هر PR، بر سر استدلال‌های معماری تکراری بجنگند.

گام بعدی شما

• اگر تیمی بین ۱ تا ۵ نفر دارید، بهترین فایل CLAUDE.md شخصی را به ریشه مخزن منتقل کنید.
• اکشن claude-code-action را برای متوقف کردن صف‌های طولانی بررسی PR فعال کنید.
• قوانین سخت‌گیرانه برای تغییرات فایل قانون اساسی در CI تعریف کنید تا از تضاد قوانین جلوگیری شود.

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