راه‌اندازیِ Claude Code در مونوریپو یا کدبیسِ بزرگ

این یک ترجمهٔ غیررسمی از مستندات Claude Code است که توسط مسیر تهیه شده. نسخهٔ مرجع و معتبر، مستندات رسمی انگلیسی است.

یک کدبیسِ بزرگ می‌تواند یک مخزن با میلیون‌ها خط باشد یا یک مونوریپو با پکیج‌های بسیار. Claude Code در هر اندازه‌ای کار می‌کند، اما با رشدِ کدبیس، پیش‌فرض‌هایی که برای پروژه‌های کوچک‌تر تنظیم شده‌اند ممکن است کانتکست را با دستورالعمل‌ها و خواندنِ فایل‌هایی پر کنند که ربطی به تسک ندارند؛ این هم توکن هزینه می‌کند و هم عملکردِ Claude را افت می‌دهد.

این راهنما به توسعه‌دهندگانِ منفرد و تیم‌های مهندسی نشان می‌دهد که چطور Claude را به آن بخشی از کدبیس که تسک به آن دست می‌زند محدود کنند. هر بخش مشخص می‌کند که یک تنظیم شخصیِ ماشینِ خودت است یا در مخزن کامیت می‌شود.

این راهنما چه چیزی را پوشش می‌دهد

جدولِ زیر هر تنظیم و کارکردِ آن را فهرست می‌کند. درختِ فایلِ پس از آن همان مونوریپوی نمونه‌ای است که هر نمونه‌ی کدِ این صفحه به آن ارجاع می‌دهد.

تنظیماتِ این صفحه

هر تنظیمِ زیر مستقل است. آن‌ها روی هم لایه می‌شوند نه آن‌که جایگزینِ یکدیگر شوند، پس هر کدام که با مخزنِ تو سازگار است را اعمال کن. انتخابِ این‌که Claude را از کجا شروع کنی تعیین می‌کند فایل‌های تنظیماتت کجا قرار بگیرند، پس اول آن را بخوان. همه را کنار هم بگذار همه‌ی آن‌ها را به‌صورتِ ترکیبی نشان می‌دهد.

می‌خواهم	از این استفاده کن
فقط قراردادهای کدی که به آن دست می‌زنم بارگذاری شود، نه یک فایلِ ریشه‌ی واحد که هر زیرسیستم را پوشش می‌دهد	فایل‌های CLAUDE.md به‌تفکیکِ پوشه
فایل‌های CLAUDE.md پکیج‌هایی که هرگز در آن‌ها کار نمی‌کنم کنار گذاشته شود	claudeMdExcludes
Claude از بازکردنِ خروجیِ بیلد، کدِ تولیدشده و وابستگی‌های vendorشده منع شود	قواعدِ deny برای Read در permissions.deny
تعریف یا فراخوان‌های یک سمبل را از طریقِ language server پیدا کنم، نه با اسکنِ فایل‌ها	یک پلاگینِ هوشِ کد
وقتی Claude یک worktree می‌سازد، فقط پوشه‌هایی را که تسک لازم دارد checkout کنم	worktree.sparsePaths
از همان نشست یک پکیجِ خواهر یا مخزنِ دیگری را بخوانم و ویرایش کنم	--add-dir یا additionalDirectories
به Claude رویه‌هایی مخصوصِ یک حوزه بدهم که فقط وقتی مرتبط است بارگذاری شوند	skillهای به‌تفکیکِ پوشه
فایل‌های پرشمارِ CLAUDE.md به‌تفکیکِ پوشه را با یک مجموعه قراردادِ واحد که همه نصب می‌کنند جایگزین کنم	یک پلاگین در یک marketplaceِ داخلی

نکته

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

مونوریپوی نمونه

نمونه‌های سراسرِ این صفحه به یک مونوریپو با سه پکیج ارجاع می‌دهند. همین الگوها در یک کدبیسِ بزرگِ تک‌درختی هم کار می‌کنند: جایی که نمونه از packages/api/ استفاده می‌کند، پوشه‌ی زیرسیستمِ خودت مثلِ src/backend/ یا lib/core/ را جایگزین کن.

monorepo/
  CLAUDE.md                     # root instructions
  packages/
    api/
      CLAUDE.md                 # API-specific instructions
      .claude/skills/
      src/
    web/
      CLAUDE.md                 # frontend-specific instructions
      .claude/skills/
      src/
    shared/
      CLAUDE.md                 # shared library instructions
      src/

انتخابِ این‌که Claude را از کجا شروع کنی

جایی که claude را اجرا می‌کنی تعیین می‌کند که Claude کدام فایل‌ها را می‌تواند بدونِ اعطای دسترسیِ اضافه بخواند و ویرایش کند، کدام فایل‌های CLAUDE.md هنگامِ راه‌اندازی در کانتکست بارگذاری می‌شوند، و کدام تنظیماتِ پروژه اعمال می‌شوند.

شروع از	دسترسی به فایل	CLAUDE.md بارگذاری‌شده هنگامِ اجرا	استفاده وقتی
ریشه‌ی مخزن	هر فایل	فقط ریشه؛ فایل‌های زیرپوشه‌ها وقتی Claude در آن‌جا می‌خواند بنا به نیاز بارگذاری می‌شوند	تسک‌ها چند پکیج یا زیرسیستم را در بر می‌گیرند
یک زیرپوشه	فقط همان زیردرخت، تا وقتی دسترسیِ بیشتری بدهی	فایلِ همان پوشه به‌اضافه‌ی فایلِ همه‌ی نیاکانش	کار به یک پکیج یا زیرسیستم محدود است

تنظیماتِ پروژه در .claude/settings.json فقط از پوشه‌ی شروعِ تو بارگذاری می‌شوند و آن‌گونه که فایل‌های CLAUDE.md از پوشه‌های والد به ارث می‌رسند، به ارث نمی‌رسند: یک .claude/settings.json در ریشه‌ی مخزن تنها وقتی اعمال می‌شود که از ریشه شروع کنی.

هر بخشِ زیر مشخص می‌کند که فایلِ تنظیماتش به ریشه‌ی مخزن تعلق دارد یا به زیرپوشه‌ای که از آن شروع می‌کنی، و این‌که کامیت می‌شود یا محلی نگه داشته می‌شود.

لایه‌بندیِ فایل‌های CLAUDE.md به‌تفکیکِ پوشه

در یک کدبیسِ بزرگ، یک CLAUDE.md واحد در ریشه‌ی مخزن گرایش دارد یا آن‌قدر بزرگ شود که قراردادهای هر زیرسیستم را پوشش دهد — و کانتکست را روی دستورالعمل‌های نامربوط به تسکِ جاری هزینه کند — یا آن‌قدر کلی بماند که به‌دردنخور شود. تقسیمِ دستورالعمل‌ها بینِ فایل‌های به‌تفکیکِ پوشه یعنی Claude قواعدِ سراسرِ مخزن را به‌اضافه‌ی فقط قراردادهای کدی که در آن کار می‌کنی بارگذاری می‌کند.

Claude Code هنگامِ راه‌اندازی هر فایلِ CLAUDE.md را از پوشه‌ی کاریِ تو و همه‌ی پوشه‌های والد بارگذاری می‌کند، سپس فایلِ هر زیرپوشه را وقتی فایل‌هایی را در آن‌جا می‌خواند بنا به نیاز بارگذاری می‌کند. یک فایلِ ریشه قواعدِ سراسرِ مخزن را تعیین می‌کند و هر زیرپوشه قواعدِ خودش را می‌افزاید.

یک تقسیم‌بندیِ رایج، دو سطح است:

• CLAUDE.md ریشه: دستورالعمل‌هایی که همه‌جا اعمال می‌شوند، مثلِ استانداردهای کدنویسی، قراردادهای کامیت و چیدمانِ مخزن
• CLAUDE.md به‌تفکیکِ زیرپوشه: قراردادهای مخصوصِ استکِ آن حوزه. در یک مونوریپو یعنی یکی برای هر پکیج. در یک تک‌درختِ بزرگ یعنی یکی برای هر زیرسیستم مثلِ src/db/ یا src/api/

این فایل‌ها را در مخزن کامیت کن تا هم‌تیمی‌ها آن‌ها را به ارث ببرند. معمولاً مالکِ هر پوشه فایلِ آن را نگه‌داری می‌کند.

CLAUDE.md ریشه Claude را با ساختارِ مخزن آشنا می‌کند:

This is a monorepo with three packages under packages/:

- packages/api: Node.js REST API with Express, TypeScript, and PostgreSQL
- packages/web: React frontend with Vite, TypeScript, and TailwindCSS
- packages/shared: shared TypeScript utilities used by both api and web

Run commands from the package directory, not the monorepo root.
Each package has its own tsconfig.json, package.json, and test suite.

CLAUDE.md هر زیرپوشه — این‌جا packages/api/CLAUDE.md — کانتکستِ مخصوصِ استکِ آن حوزه را می‌افزاید:

This package is the REST API server.

- Run tests: `npm test` (uses Vitest)
- Run dev server: `npm run dev` (port 3001)
- Database migrations: `npm run migrate`
- Environment variables: copy `.env.example` to `.env`

API routes are in src/routes/. Each route file exports an Express router.
Database queries use Knex in src/db/. Never write raw SQL strings in route handlers.

وقتی Claude را از packages/api/ شروع می‌کنی، هم packages/api/CLAUDE.md و هم CLAUDE.md ریشه را بارگذاری می‌کند. Claude دستورالعمل‌های محلی را در کنارِ قواعدِ سراسرِ مخزن می‌بیند، بدونِ هیچ دستورالعملی از packages/web/ در کانتکست. همین برای هر زیرپوشه در یک درختِ غیرمونوریپو هم صادق است.

چند راه برای به‌روز نگه داشتنِ فایل‌ها با تغییرِ کدبیس و مدل‌ها:

• بازبینی در pull requestها: ویرایش‌های CLAUDE.md را مثلِ هر تغییرِ مستنداتِ دیگری بررسی کن تا قراردادها پا‌به‌پای کد بمانند
• بازنگری پس از انتشارهای بزرگِ مدل: دستورالعمل‌هایی که دورِ محدودیتِ یک مدلِ قدیمی‌تر را گرفته بودند ممکن است وقتی مدلِ تازه‌تری خودش از پسِ آن برمی‌آید، به سربار تبدیل شوند. برای مثال، قاعده‌ای که refactorِ تک‌فایلی را اجبار می‌کند، با رفعِ آن محدودیت می‌تواند حذف شود
• افزودنِ یک Stop hook که به‌روزرسانی پیشنهاد دهد: یک Stop hook وقتی Claude پاسخش را تمام می‌کند مسیرِ رونوشتِ نشست را دریافت می‌کند، پس یک اسکریپت می‌تواند نشست را بازبینی کند و به‌روزرسانی‌های CLAUDE.md را وقتی شکافی که نمایان شده هنوز تازه است پیشنهاد دهد

برای اطلاعاتِ بیشتر درباره‌ی نحوه‌ی بارگذاری و تعاملِ فایل‌های CLAUDE.md، به حافظه و دستورالعمل‌های پروژه نگاه کن.

انتخاب بینِ CLAUDE.md به‌تفکیکِ پوشه و قواعدِ مقیدشده به مسیر

هم فایل‌های CLAUDE.md به‌تفکیکِ پوشه و هم قواعدِ مقیدشده به مسیر زیرِ .claude/rules/ به تو امکان می‌دهند دستورالعمل‌ها را به بخشی از درخت هدف بگیری. تفاوتشان در جایی است که فایل قرار می‌گیرد و این‌که کِی بارگذاری می‌شود.

رویکرد	محلِ فایل	بارگذاری وقتی	استفاده وقتی
CLAUDE.md به‌تفکیکِ پوشه	درونِ پوشه، کنارِ کدش	هنگامِ اجرا اگر از آن پوشه شروع شود، یا بنا به نیاز وقتی Claude فایلی را در آن‌جا می‌خواند	مالکانِ پوشه قراردادهای خود را نگه می‌دارند؛ دستورالعمل‌ها با کد نسخه‌بندی می‌شوند
قاعده‌ی مقیدشده به مسیر در .claude/rules/	.claude/ مرکزی در ریشه‌ی مخزن	وقتی Claude با فایلی کار می‌کند که با glob مشخص‌شده در paths: قاعده تطبیق دارد	می‌خواهی همه‌ی قراردادها یک‌جا باشند، یا همان قاعده روی مسیرهای پراکنده‌ی بسیار اعمال می‌شود

برای مقایسه‌ای که skillها را هم پوشش می‌دهد، به مقایسه‌ی قابلیت‌های مشابه نگاه کن.

کنار گذاشتنِ فایل‌های نامرتبطِ CLAUDE.md

وقتی Claude را از ریشه‌ی مخزن شروع می‌کنی، CLAUDE.md هر زیرپوشه به‌محضِ آن‌که Claude فایلی را در آن پوشه می‌خواند بارگذاری می‌شود. تنظیمِ claudeMdExcludes فایل‌های مشخص را بر اساسِ مسیر یا الگوی glob رد می‌کند تا هرگز بارگذاری نشوند.

این را برای پوشه‌هایی به‌کار ببر که هرگز در آن‌ها کار نمی‌کنی، مثلِ پکیج‌های تیم‌های دیگر، کدِ قدیمی، یا زیردرخت‌های vendorشده. فهرستِ کنارگذاری ایستا است، نه یک کلیدِ به‌ازای هر تسک. برای آن‌که امروز روی یک پکیج و فردا روی پکیجِ دیگری تمرکز کنی، به‌جای ویرایشِ کنارگذاری‌ها Claude را از پوشه‌ی آن پکیج شروع کن.

اگر این کنارگذاری‌ها را فقط برای خودت می‌خواهی، تنظیم را در .claude/settings.local.json بگذار. Claude Code وقتی این فایل را می‌سازد آن را gitignore می‌کند؛ چون این‌جا تو خودت دستی می‌سازی‌اش، آن را به gitignore خودت اضافه کن. الگوها از سینتکسِ glob استفاده می‌کنند که با مسیرهای مطلقِ فایل تطبیق داده می‌شود، پس الگوهای سبکِ نسبی را با **/ شروع کن تا هر جای درخت تطبیق یابند. مثالِ زیر پکیج‌هایی را که تیم‌های دیگر مالکشان‌اند کنار می‌گذارد:

{
  "claudeMdExcludes": [
    "**/packages/admin-dashboard/**",
    "**/packages/legacy-*/**"
  ]
}

این هر CLAUDE.md و فایلِ rules زیرِ آن پکیج‌ها را رد می‌کند. CLAUDE.md ریشه و پکیج‌هایی که در آن‌ها کار می‌کنی همچنان عادی بارگذاری می‌شوند.

این الگوها موارد رایجِ دیگر را پوشش می‌دهند:

• "**/packages/*/CLAUDE.md": CLAUDE.md هر پکیج را کنار می‌گذارد ولی ریشه را نگه می‌دارد
• "**/packages/web/**": همه‌چیز زیرِ پکیجِ web را، از جمله rules، کنار می‌گذارد
• "/home/user/monorepo/legacy/CLAUDE.md": یک فایلِ مشخص را با مسیرِ مطلق کنار می‌گذارد

فایل‌های CLAUDE.md سیاستِ مدیریت‌شده (managed policy) را نمی‌توان کنار گذاشت، پس دستورالعمل‌های سراسرِ سازمان همیشه اعمال می‌شوند. می‌توانی claudeMdExcludes را در هر دامنه‌ی تنظیمات بگذاری: کاربر، پروژه، محلی، یا مدیریت‌شده. آرایه‌ها در سراسرِ دامنه‌ها ادغام می‌شوند، پس یک تیم می‌تواند پیش‌فرض‌های سطحِ پروژه بگذارد و در همان حال افراد override‌های محلی بیفزایند.

برای مستنداتِ کاملِ کنارگذاری، به کنار گذاشتنِ فایل‌های مشخصِ CLAUDE.md نگاه کن.

کاهشِ آنچه Claude می‌خواند

دستورالعمل‌ها تنها بخشی از چیزی هستند که در کانتکستِ Claude می‌نشیند. خواندنِ فایل‌ها هزینه‌ی دیگری است که با کدبیس رشد می‌کند. تنظیماتِ زیر خواندنِ مسیرهای نامربوط را مسدود می‌کنند و اسکنِ جامعِ فایل‌ها را با جست‌وجوی language server جایگزین می‌کنند.

مسدودکردنِ خواندنِ کدِ تولیدشده و vendorشده

جست‌وجوهای محتواییِ Claude به‌طورِ پیش‌فرض .gitignore را رعایت می‌کنند، پس مسیرهایی که از پیش آن‌جا فهرست شده‌اند — مثلِ node_modules/، dist/ و build/ — بدونِ پیکربندیِ اضافه از نتایجِ جست‌وجو بیرون می‌مانند.

برای مسیرهایی که کامیت شده‌اند، مثلِ یک SDKِ vendorشده یا کدِ تولیدشده‌ی کامیت‌شده، قواعدِ deny برای Read را در permissions.deny بیفزای تا Claude از بازکردنِ آن فایل‌ها — حتی وقتی جست‌وجو آن‌ها را فهرست می‌کند — منع شود.

برای اعمالِ این کنارگذاری‌ها برای هرکس که در مخزن کار می‌کند، آن‌ها را در .claude/settings.json کامیت کن. برای شخصی نگه داشتنشان، به‌جایش از .claude/settings.local.json استفاده کن. مثلِ سایرِ تنظیماتِ پروژه در این صفحه، این فایل‌ها تنها از پوشه‌ی شروعِ تو بارگذاری می‌شوند. اگر Claude را از آن‌جا شروع می‌کنی آن‌ها را در ریشه‌ی مخزن بگذار، یا اگر از زیرپوشه‌ها شروع می‌کنی در .claude/ هر پکیج. برای اعمالِ همان قواعدِ deny در هر نشست صرف‌نظر از پوشه‌ی شروع، آن‌ها را در managed settings بگذار که تنظیماتِ کاربر و پروژه نمی‌توانند override‌اش کنند.

مثالِ زیر آرتیفکت‌های بیلد و یک SDKِ vendorشده را مسدود می‌کند:

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/build/**)",
      "Read(./**/*.generated.*)",
      "Read(./vendor/**)"
    ]
  }
}

قواعدِ deny ابزارهای فایلیِ داخلیِ Claude و دستورهای فایلیِ شناخته‌شده‌ی Bash — از جمله cat، head، grep و find — را زمانی که یک مسیرِ منع‌شده به‌عنوانِ آرگومان پاس داده شود، پوشش می‌دهند. آن‌ها مسیرهای منع‌شده را از خروجیِ یک جست‌وجوی بازگشتی فیلتر نمی‌کنند، و زیرفرایندهای دلخواهی که خودشان فایل‌ها را باز می‌کنند را پوشش نمی‌دهند. برای سینتکسِ کاملِ الگو، به قواعدِ دسترسیِ Read و Edit نگاه کن.

کاهشِ خواندنِ فایل با هوشِ کد

در یک کدبیسِ بزرگ، یافتنِ این‌که یک سمبل کجا تعریف یا استفاده شده می‌تواند خواندنِ فایلِ بسیار و فراخوانِ grep ببرد. پلاگین‌های هوشِ کد Claude را به یک language server وصل می‌کنند تا به‌جای اسکنِ درخت، مستقیماً به تعریف‌ها بپرد، ارجاع‌ها را بیابد و خطاهای نوع را نمایان کند.

marketplaceِ رسمی پلاگین‌هایی برای TypeScript، Python، Go، Rust و دیگر زبان‌های رایج دارد. مثالِ زیر پلاگینِ TypeScript را نصب می‌کند:

/plugin install typescript-lsp@claude-plugins-official

برای فعال‌کردنِ یک پلاگین برای هرکس که در مخزن است به‌جای نصبِ آن توسطِ خودت، آن را به تنظیمِ پروژه‌ی enabledPlugins بیفزای.

پلاگین‌های هوشِ کد به باینریِ language serverِ آن زبان روی ماشینِ هر توسعه‌دهنده نیاز دارند. ببین هر زبان به کدام باینری نیاز دارد. نصب از marketplaceِ رسمی به دسترسیِ شبکه به GitHub نیاز دارد، جایی که marketplace میزبانی می‌شود. روی یک شبکه‌ی محدود، به‌جایش marketplace را از یک میزبانِ Gitِ داخلی یا مسیرِ محلی اضافه کن.

این با claudeMdExcludes و قواعدِ deny برای Read بالا خوب جفت می‌شود. آن‌ها محتوای نامربوط را بیرونِ کانتکست نگه می‌دارند، و هوشِ کد Claude را از خواندنِ آنچه باقی می‌ماند برای یافتنِ یک تعریف بازمی‌دارد.

مقیدکردنِ worktreeها و دسترسی به فایل

این تنظیمات کنترل می‌کنند چه چیزی در worktreeها روی دیسک باشد و Claude کدام پوشه‌ها را فراتر از نقطه‌ی شروعت می‌تواند بخواند و بنویسد.

Checkout کردنِ فقط پوشه‌هایی که نیاز داری

پرچمِ --worktree یک نشست را در یک git worktreeِ تازه شروع می‌کند تا تغییرات از checkoutِ اصلیِ تو جدا بماند. به‌طورِ پیش‌فرض کلِ مخزن را checkout می‌کند. در یک مخزنِ بزرگ، تنظیمِ worktree.sparsePaths از git sparse-checkout استفاده می‌کند تا فقط پوشه‌های فهرست‌شده به‌اضافه‌ی فایل‌های سطحِ ریشه را روی دیسک بنویسد، پس worktreeها سریع‌تر شروع می‌شوند و فضای کمتری می‌گیرند.

اگر هرکس که در این پوشه کار می‌کند به همان مسیرها نیاز دارد، تنظیم را در .claude/settings.json کامیت کن. برای افزودنِ مسیر برای خودت، از .claude/settings.local.json استفاده کن: فهرست‌ها در سراسرِ دامنه‌ها ادغام می‌شوند، پس یک فایلِ محلی می‌تواند مسیرهایی به فهرستِ کامیت‌شده بیفزاید ولی نمی‌تواند حذفشان کند. مثالِ زیر فایلِ کامیت‌شده را نشان می‌دهد:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ]
  }
}

وقتی Claude یک worktree می‌سازد، به‌جای کلِ درخت فقط .claude/، packages/api/ و packages/shared/ را checkout می‌کند. مسیرهای موجود در sparsePaths نسبت به ریشه‌ی مخزن‌اند، صرف‌نظر از این‌که Claude را از کدام زیرپوشه شروع می‌کنی. هر مسیرِ پوشه‌ای این‌جا کار می‌کند، نه فقط ریشه‌ی پکیج‌ها.

این به‌ویژه برای ایزوله‌سازیِ worktreeِ ساب‌ایجنت‌ها مفید است. ساب‌ایجنت‌ها نمونه‌های موازیِ Claude هستند که برای زیرتسک‌ها به‌وجود می‌آیند، و هر کدام که در یک worktree اجرا می‌شود به‌جای کلِ درخت یک checkoutِ سبک می‌گیرد. همه‌ی worktreeها در یک نشست همان sparsePaths را به اشتراک می‌گذارند، پس اگر یک ساب‌ایجنت به packages/api/ و دیگری به packages/web/ نیاز دارد، هر دو را فهرست کن.

پوشه‌ها را در sparsePaths فهرست کن، نه فایل‌های منفرد را. فایل‌های سطحِ ریشه مثلِ package.json، tsconfig.base.json و فایل‌های lock همیشه در کنارِ پوشه‌هایی که فهرست می‌کنی checkout می‌شوند. پوشه‌های سطحِ ریشه چنین نیستند، پس اگر .claude/settings.json، .claude/rules/ یا .claude/skills/ ریشه‌ی مخزن را درونِ worktree می‌خواهی، .claude را در فهرست بگنجان.

برای پرهیز از تکثیرِ پوشه‌های بزرگ مثلِ node_modules در worktreeها، sparsePaths را با symlinkDirectories در همان .claude/settings.json جفت کن:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  }
}

این به‌جای تکثیرِ آن روی دیسک، از node_modules/ هر worktree یک symlink به نسخه‌ی مخزنِ اصلی می‌سازد.

یادداشت

تنظیماتِ sparsePaths و symlinkDirectories پیش از ساخته‌شدنِ worktree از پوشه‌ی شروعِ تو خوانده می‌شوند. پس از ساخت، پوشه‌ی کاریِ نشست ریشه‌ی worktree است، نه زیرپوشه‌ای که از آن اجرا کردی. بنابراین تنظیماتِ پروژه درونِ worktree از .claude/settings.json ریشه‌ی worktree بارگذاری می‌شوند، یعنی نسخه‌ی checkout‌شده‌ی فایلِ ریشه‌ی مخزن. هر تنظیمِ دیگری که درونِ worktreeها نیاز داری — مثلِ قواعدِ دسترسی یا hookها — را در .claude/settings.json ریشه‌ی مخزن بگذار.

برای مرجعِ کاملِ تنظیماتِ worktree، به تنظیماتِ Worktree نگاه کن.

اعطای دسترسی در سراسرِ پکیج‌ها یا مخزن‌ها

این بخش وقتی کاربرد دارد که Claude را از یک زیرپوشه شروع کنی، یا وقتی یک تسک چند checkout را در بر می‌گیرد. اگر در یک تک‌درختِ بزرگ از ریشه‌ی مخزن شروع کنی، Claude از پیش به هر فایلی دسترسی دارد و می‌توانی از این بخش بگذری.

وقتی Claude را از packages/api/ شروع می‌کنی، می‌تواند فایل‌های درونِ آن پوشه را بخواند و بنویسد. اگر یک تسک به تغییراتی در سراسرِ پکیج‌ها نیاز دارد — مثلِ به‌روزرسانیِ یک نوعِ مشترک که هم api و هم web آن را import می‌کنند — باید به پوشه‌ی خواهر دسترسی بدهی. همین سازوکار به یک مخزنِ جداگانه‌checkout‌شده هم دسترسی می‌دهد.

تنظیمِ additionalDirectories در .claude/settings.json به Claude دسترسی به پوشه‌های بیرون از پوشه‌ی کاری می‌دهد. مثالِ زیر دسترسی به دو پکیجِ خواهر را اعطا می‌کند:

{
  "permissions": {
    "additionalDirectories": [
      "../shared",
      "../web"
    ]
  }
}

مسیرهای نسبی نسبت به پوشه‌ای که Claude را از آن شروع می‌کنی حل می‌شوند. با این پیکربندی، Claude می‌تواند ضمنِ کار از packages/api/، فایل‌های packages/shared/ و packages/web/ را بخواند و ویرایش کند.

می‌توانی بدونِ ویرایشِ تنظیمات هم در زمانِ اجرا دسترسی بدهی، با پاس‌دادنِ --add-dir هنگامِ شروعِ Claude:

claude --add-dir ../shared

هرطور که یک پوشه را اضافه کنی، Claude می‌تواند فایل‌های آن را بخواند و ویرایش کند. این‌که CLAUDE.md، فایل‌های .claude/rules/ و skillهای آن پوشه هم بارگذاری شوند یا نه، به نحوه‌ی افزودنِ آن بستگی دارد:

افزوده‌شده با	CLAUDE.md و rules را بارگذاری می‌کند	skillها را بارگذاری می‌کند
تنظیمِ additionalDirectories	هرگز	هرگز
پرچمِ --add-dir یا دستورِ /add-dir	فقط با متغیرِ محیطیِ زیر	بله

برای بارگذاریِ فایل‌های CLAUDE.md و rules از پوشه‌ای که با --add-dir یا /add-dir افزوده شده، متغیرِ محیطیِ CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD را تنظیم کن:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared

این متغیرِ محیطی روی پوشه‌های فهرست‌شده در تنظیمِ additionalDirectories اثری ندارد. برای جزئیات به بارگذاری از پوشه‌های اضافه نگاه کن.

برای پوشه‌های خواهری که هرکس در این حوزه نیاز دارد، additionalDirectories را در .claude/settings.json کامیت کن. برای انتخابی شخصی یا دسترسیِ یک‌باره، از .claude/settings.local.json استفاده کن یا --add-dir را هنگامِ اجرا پاس بده.

افزودنِ skillهای به‌تفکیکِ پوشه

هر زیرپوشه می‌تواند skillهایی مقیدشده به استکِ خودش تعریف کند. یک skill بنا به نیاز وقتی Claude تشخیص می‌دهد مرتبط است بارگذاری می‌شود، پس ابزارِ مخصوصِ API در حینِ کارِ frontend کانتکست مصرف نمی‌کند.

skillها زیرِ .claude/skills/ درونِ پوشه قرار می‌گیرند. آن‌ها را در کنارِ کدِ آن حوزه کامیت کن تا هرکس مخزن را clone می‌کند آن‌ها را بگیرد. در یک مونوریپو این می‌تواند یک مجموعه skill به‌ازای هر پکیج باشد. در یک کدبیسِ بزرگِ تک‌درختی یعنی یک مجموعه به‌ازای هر زیرسیستم مثلِ src/db/.claude/skills/.

یک پوشه‌ی skill درونِ زیرپوشه بساز:

mkdir -p packages/api/.claude/skills/api-testing

سپس SKILL.md را درونِ آن پوشه بنویس، این‌جا packages/api/.claude/skills/api-testing/SKILL.md. این مثال الگوهای تستِ پکیجِ API را به Claude می‌آموزد:

---
name: api-testing
description: Testing patterns for the API package. Use when writing or modifying tests in packages/api/.
---

## Test structure

Tests are in `src/__tests__/` mirroring the `src/` directory structure.
Each route file has a corresponding `.test.ts` file.

## Running tests

- All tests: `npm test`
- Single file: `npm test -- src/__tests__/routes/users.test.ts`
- Watch mode: `npm test -- --watch`

## Test utilities

- `src/__tests__/helpers/db.ts`: provides `setupTestDb()` and `teardownTestDb()` for database tests
- `src/__tests__/helpers/auth.ts`: provides `createTestUser()` and `getAuthToken()` for authenticated endpoints

## Patterns

- Use `supertest` for HTTP assertions, not raw fetch
- Always wrap database tests in a transaction that rolls back
- Mock external services in `src/__tests__/mocks/`

یک زیرپوشه‌ی دیگر به همین شیوه skillهای متفاوتی را در بر می‌گیرد: packages/web/.claude/skills/component-patterns/ به‌جای تست، قراردادهای کامپوننتِ frontend را توصیف می‌کند. وقتی Claude روی فایلی در packages/api/ کار می‌کند، skillِ api-testing را بارگذاری می‌کند. وقتی در packages/web/ کار می‌کند، به‌جایش component-patterns را بارگذاری می‌کند. skillهای هیچ‌کدام از این دو پوشه در حینِ تسک‌های دیگری بارگذاری نمی‌شوند.

می‌توانی یک skill را به‌جای محلِ قرارگیری، بر اساسِ الگوی فایل هم مقید کنی. فیلدِ frontmatterِ paths الگوهای glob می‌گیرد، و Claude آن skill را به‌طورِ خودکار فقط وقتی با فایل‌های منطبق کار می‌کند بارگذاری می‌کند. این را برای skillی به‌کار ببر که در .claude/skills/ ریشه‌ی مخزن زندگی می‌کند ولی فقط روی فایل‌های مشخصی هرجا که باشند اعمال می‌شود، مثلِ یک skillِ مهاجرتِ پایگاه‌داده که به **/migrations/** مقید شده.

برای اطلاعاتِ بیشتر درباره‌ی ساخت و سازمان‌دهیِ skillها، به Skills نگاه کن.

قابلِ‌کشف نگه داشتنِ skillها

با پخش‌شدنِ skillها در پوشه‌های بسیار، فهرستی که Claude از آن انتخاب می‌کند می‌تواند بزرگ شود. Claude یک skill را با خواندنِ نام و توضیحِ هر skillِ کشف‌شده انتخاب می‌کند، و فقط محتوای کاملِ skillِ انتخاب‌شده در کانتکست بارگذاری می‌شود. این بخش پوشش می‌دهد که چطور آن فهرست را کوچک نگه داری و توضیح‌هایی بنویسی که از کوتاه‌شدن جان به‌در ببرند.

این‌که کدام skillها در دامنه هستند به جایی که Claude را شروع می‌کنی بستگی دارد:

• از یک زیرپوشه مثلِ packages/api/: skillها از آن پوشه، هر والد تا ریشه‌ی مخزن، و سطوحِ کاربر و enterprise
• از ریشه‌ی مخزن: skillها از هر زیرپوشه‌ای که Claude در طولِ نشست به آن دست می‌زند، که می‌تواند به صدها مورد انباشته شود
• پس از افزودنِ یک خواهر با --add-dir: skillهای آن خواهر هم بارگذاری می‌شوند. تنظیمِ additionalDirectories فقط دسترسی به فایل می‌دهد و skill بارگذاری نمی‌کند

نام‌ها همیشه بارگذاری می‌شوند، اما توضیح‌ها وقتی موارد زیاد باشند کوتاه می‌شوند، که می‌تواند کلیدواژه‌هایی را که Claude برای تصمیم درباره‌ی اعمالِ یک skill استفاده می‌کند حذف کند. توضیح‌ها را کوتاه نگه دار و با کلماتی شروع کن که یک درخواست در خود دارد، مثلِ «نوشتن یا تغییرِ تست‌ها در packages/api/».

برای skillهایی که پوشه‌های بسیاری به اشتراک می‌گذارند، مثلِ قراردادهای PR یا یک چک‌لیستِ استقرار، آن‌ها را در .claude/skills/ ریشه‌ی مخزن بگذار تا از هر پوشه‌ی شروعی بارگذاری شوند. وقتی skillهای مشترک به تاریخچه‌ی نسخه‌ی خودشان نیاز دارند یا باید در سراسرِ مخزن‌ها کار کنند، آن‌ها را به‌جایش به‌صورتِ پلاگین بسته‌بندی کن. skillهای پلاگین از فضای نامِ plugin-name:skill-name استفاده می‌کنند، پس هرگز با skillهای به‌تفکیکِ پوشه تداخل نمی‌کنند. یک تیمِ پلتفرم می‌تواند آن‌ها را در یک جا نسخه‌بندی و به‌روزرسانی کند.

برای یافتنِ این‌که کدام skillها بی‌استفاده می‌مانند، logs exporter از OpenTelemetry را فعال کن و OTEL_LOG_TOOL_DETAILS=1 را تنظیم کن تا نام‌های skill به‌جای ویرایش‌شدن (redacted)، عیناً ثبت شوند. رویدادِ skill_activated هر فراخوانی را در ویژگیِ skill.name خود ثبت می‌کند، و invocation_trigger ثبت می‌کند که یک دستور، Claude، یا یک skillِ تودرتو آن را فراخوانده، که به تو می‌گوید چه چیزی را یکپارچه یا بازنشسته کنی.

متمرکزکردنِ قراردادها وقتی لایه‌بندی از مقیاس می‌افتد

فایل‌های CLAUDE.md به‌تفکیکِ پوشه می‌توانند با رشدِ کدبیس به‌سختی قابلِ حکمرانی شوند. قراردادها منحرف می‌شوند، فایل‌ها کهنه می‌شوند و کسی مالکِ ریشه نیست. حلِ این معمولاً به‌جای هر توسعه‌دهنده‌ای که در حوزه‌ی خودش کار می‌کند، بر دوشِ تیمی است که راه‌اندازیِ Claude Codeِ مخزن را نگه می‌دارد.

قراردادها و محتوای مرجع را از CLAUDE.md همیشه‌بارگذاری‌شونده بیرون ببر و به سازوکارهایی منتقل کن که بنا به نیاز بارگذاری می‌شوند:

• Skills: موادِ مرجعی که Claude فقط وقتی به تسک مرتبط است بارگذاری می‌کند
• Plugins: بسته‌های نسخه‌بندی‌شده‌ی skillها، hookها و دستورها که یک تیمِ پلتفرم مرکزی مالکشان است
• MCP servers: اگر سازمانت پیش‌تر یک جست‌وجوی کد یا ایندکسِ RAG روی مخزن اجرا می‌کند، آن را به‌صورتِ یک ابزارِ MCP عرضه کن تا Claude به‌جای خواندنِ مستقیمِ فایل‌ها از آن پرس‌وجو کند

برای این‌که تیم‌های پلتفرم چطور می‌توانند این‌ها را به‌صورتِ مرکزی اعمال کنند، به تنظیماتِ server-managed یا endpoint-managed نگاه کن.

توصیه‌ی پلاگینِ درست در شروعِ نشست

وقتی قراردادها در پلاگین‌ها زندگی کنند، هم‌تیمی‌ای که Claude را در بخشِ ناآشنایی از درخت شروع می‌کند هیچ نشانه‌ای ندارد که مالکانِ آن حوزه کدام پلاگین را نگه می‌دارند. یک SessionStart hook می‌تواند این شکاف را پر کند، چون هر چیزی که hook روی stdout چاپ می‌کند پیش از اولین پرامپت به کانتکستِ Claude افزوده می‌شود.

برای مثال، می‌توانی اسکریپتی بنویسی که پوشه‌ی اجرا را از ورودیِ hook می‌خواند، آن را در یک نگاشتِ مسیر-به-پلاگینِ کامیت‌شده در مخزن جست‌وجو می‌کند، و توصیه را چاپ می‌کند تا Claude در اولین پاسخش آن را منتقل کند. برای نوشتن و ثبتِ hook، به خودکارسازیِ اکشن‌ها با hookها نگاه کن.

همه را کنار هم بگذار

پیکربندیِ ترکیبیِ زیر از چیدمانِ مونوریپو استفاده می‌کند. همین فایل‌ها برای هر زیرپوشه در یک تک‌درختِ بزرگ کار می‌کنند. تنظیماتِ پروژه فقط از پوشه‌ای که Claude را در آن شروع می‌کنی بارگذاری می‌شوند، پس .claude/settings.json هر زیرپوشه باید خودبسنده باشد نه آن‌که روی یک فایلِ ریشه لایه شود.

این مثال worktree، additionalDirectories و قواعدِ deny برای Read را در .claude/settings.json کامیت می‌کند تا هر توسعه‌دهنده در packages/api/ همان دسترسیِ خواهر، sparse paths و کنارگذاری‌ها را بگیرد. فایلِ زیر تنظیماتِ کامیت‌شده‌ی به‌تفکیکِ حوزه برای packages/api/ است:

{
  "worktree": {
    "sparsePaths": [
      ".claude",
      "packages/api",
      "packages/shared"
    ],
    "symlinkDirectories": [
      "node_modules"
    ]
  },
  "permissions": {
    "additionalDirectories": [
      "../shared"
    ],
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/build/**)"
    ]
  }
}

چون این نشست از packages/api/ شروع می‌شود، فایل‌های CLAUDE.md پکیج‌های خواهر از پیش بیرون از دامنه‌اند، پس claudeMdExcludes این‌جا لازم نیست. اگر نشست‌ها را از ریشه هم شروع می‌کنی، به‌جایش آن را به .claude/settings.local.json ریشه‌ی مخزن بیفزای.

ورودیِ additionalDirectories وقتی Claude را مستقیماً از packages/api/ شروع می‌کنی اعمال می‌شود. درونِ worktreeای که از این نشست ساخته می‌شود، پوشه‌ی کاری ریشه‌ی worktree است، پس این فایلِ تنظیمات بارگذاری نمی‌شود. پکیج‌های خواهر درونِ worktree بدونِ آن هم از پیش در دسترس‌اند، اما قواعدِ deny به یک نسخه‌ی دوم در .claude/settings.json ریشه‌ی مخزن نیاز دارند تا نشست‌های worktree آن‌ها را بردارند، همان‌طور که یادداشتِ تنظیماتِ worktree توضیح می‌دهد:

{
  "permissions": {
    "deny": [
      "Read(./**/dist/**)",
      "Read(./**/build/**)"
    ]
  }
}

پس از راه‌اندازی، مخزن این چیدمان را دارد:

monorepo/
  CLAUDE.md
  .claude/settings.json                           # deny rules for worktree sessions
  packages/
    api/
      CLAUDE.md
      .claude/settings.json                       # worktree, additionalDirectories, deny rules
      .claude/skills/api-testing/SKILL.md
    web/
      CLAUDE.md
      .claude/skills/component-patterns/SKILL.md
    shared/
      CLAUDE.md

با این راه‌اندازی، شروعِ Claude از packages/api/:

• CLAUDE.md ریشه و packages/api/CLAUDE.md را بارگذاری می‌کند، packages/web/CLAUDE.md را رد می‌کند
• می‌تواند فایل‌های packages/api/ و packages/shared/ را بخواند و ویرایش کند
• خواندنِ خروجیِ بیلد زیرِ dist/ و build/ در packages/api/ را رد می‌کند
• skillِ api-testing را بنا به نیاز در دسترس دارد
• worktreeهایی می‌سازد که .claude/، packages/api/، packages/shared/ و فایل‌های سطحِ ریشه را در بر دارند، با قواعدِ deny که از فایلِ تنظیماتِ ریشه در سراسرِ worktree اعمال می‌شوند

مقیدکردن و طرح‌ریزیِ تغییراتی که چند پکیج را در بر می‌گیرند

پیکربندیِ بالا کنترل می‌کند که Claude چه می‌بیند. وقتی یک تغییرِ واحد چند پکیج را لمس می‌کند — مثلِ به‌روزرسانیِ یک نوعِ مشترک همراه با هر فراخوان‌گاهی که از آن استفاده می‌کند — نحوه‌ی مقیدکردن و توالیِ تسک هم بر نتیجه اثر می‌گذارد.

دو فن به یکدست ماندنِ یک تغییرِ بین‌پکیجی کمک می‌کنند:

• کلِ تغییر را در یک نشست به Claude بده: تحویلِ همزمانِ ویرایشِ مشترک و فراخوان‌گاه‌هایش، تصمیماتِ پشتِ هر ویرایش را یکدست نگه می‌دارد، به‌جای آن‌که به‌ازای هر پکیج دوباره استخراجشان کند
• طرح را پیش از ویرایش در یک فایل ذخیره کن: اول طرح بریز و از Claude بخواه طرح را در یک فایلِ markdown در مخزن بنویسد. یک نشستِ طولانیِ بین‌پکیجی در طولِ مسیر کانتکستش را فشرده می‌کند، و طرحِ ذخیره‌شده جایی جان به‌در می‌برد که تاریخچه‌ی گفت‌وگو ممکن است نبرد

گام‌های بعدی

وقتی این پیکربندی سرِ جایش قرار گرفت، می‌توانی پالایشش کنی:

• از hookها استفاده کن تا linterها یا type-checkerهای به‌تفکیکِ پوشه را پس از ویرایشِ فایل‌ها توسطِ Claude اجرا کنی
• مدیریتِ مؤثرِ هزینه‌ها را مرور کن تا بفهمی اندازه‌ی کدبیس چطور بر مصرفِ توکن اثر می‌گذارد و چطور پیش از یک پیاده‌سازیِ گسترده‌تر سقفِ خرج تعیین کنی
• نحوه‌ی کارِ Claude Code در کدبیس‌های بزرگ را در بلاگِ Claude بخوان تا الگوهای پیاده‌سازیِ سازمانی و مدل‌های مالکیت را ببینی که فراتر از پیکربندیِ به‌تفکیکِ مخزنِ این صفحه می‌نشینند