پیکربندیات را دیباگ کن
وقتی Claude یک دستورالعمل را نادیده میگیرد یا قابلیتی که پیکربندی کردهای ظاهر نمیشود، علت معمولاً این است که فایل بارگذاری نشده، از مکانی متفاوت از آنچه انتظار داشتی بارگذاری شده، یا فایلِ دیگری آن را بازنویسی (override) کرده است. این راهنما نشان میدهد چطور آنچه را Claude Code واقعاً بارگذاری کرده بازرسی کنی تا مشخص کنی کدام مورد صدق میکند.
برای مشکلاتِ نصب، احراز هویت، و اتصال، بهجایش عیبیابیِ نصب و ورود را ببین.
ببین چه چیزی به کانتکست بارگذاری شد
Section titled “ببین چه چیزی به کانتکست بارگذاری شد”دستورِ /context همهی چیزی را که کانتکستویندوی نشستِ جاری را اشغال کرده نشان میدهد، تفکیکشده بر اساسِ دسته: system prompt، فایلهای حافظه، skillها، ابزارهای MCP، و پیامهای گفتوگو. اول این را اجرا کن تا تأیید کنی آیا CLAUDE.md، rules، یا توضیحاتِ skillت اصلاً حاضرند یا نه.
برای جزئیاتِ یک دستهی خاص، با دستورِ اختصاصیِ آن دنبال کن:
| دستور | نشان میدهد |
|---|---|
/memory | کدام فایلهای CLAUDE.md و rules بارگذاری شدند، بهعلاوهی ورودیهای auto-memory |
/skills | skillهای در دسترس از منابعِ پروژه، کاربر، و plugin |
/agents | سابایجنتهای پیکربندیشده و تنظیماتشان |
/hooks | پیکربندیهای hookِ فعال |
/mcp | سرورهای MCPِ متصل و وضعیتشان |
/permissions | قواعدِ allow و denyِ حلشده که اکنون اعمالاند |
/doctor | تشخیصهای پیکربندی: کلیدهای نامعتبر، خطاهای schema، سلامتِ نصب |
/debug [issue] | لاگگیریِ دیباگ را برای نشست فعال میکند و از Claude میخواهد با خروجیِ لاگ و مسیرهای تنظیمات تشخیص بدهد |
/status | منابعِ تنظیماتِ فعال، از جمله اینکه آیا managed settings اعمالاند |
اگر یک فایلِ حافظه در /memory غایب است، مکانش را در برابرِ نحوهی بارگذاریِ فایلهای CLAUDE.md بررسی کن. فایلهای CLAUDE.mdِ زیرپوشهای بهمحضِ نیاز (on demand) بارگذاری میشوند، وقتی Claude فایلی را در آن دایرکتوری با ابزارِ Read میخواند، نه در آغازِ نشست.
اگر /memory تأیید کند فایل بارگذاری شده ولی Claude همچنان از دستورالعملِ خاصی پیروی نمیکند، مشکل احتمالاً نحوهی نوشتنِ دستورالعمل است نه اینکه بارگذاری شده یا نه. CLAUDE.md برای نوعِ راهنماییای که به یک همتیمیِ تازه میدهی خوب کار میکند، مثلِ قراردادهای پروژه، دستورهای build، و اینکه فایلها کجا تعلق دارند.
پایبندی وقتی افت میکند که یک دستورالعمل آنقدر مبهم باشد که چندجور تفسیر شود، وقتی دو فایل جهتگیریِ متناقض بدهند، یا وقتی فایل آنقدر بلند شده باشد که به قواعدِ تکتک توجهِ کمتری شود. نوشتنِ دستورالعملهای مؤثر الگوهای دقت، اندازه، و ساختار را که پایبندی را بالا نگه میدارند پوشش میدهد.
تنظیماتِ حلشده را بررسی کن
Section titled “تنظیماتِ حلشده را بررسی کن”تنظیمات در میانِ scopeهای managed، user، project، و local ادغام میشوند. managed settings وقتی حاضر باشند همیشه برندهاند. در بینِ بقیه، scopeِ نزدیکتر، گستردهتر را بازنویسی میکند، به این ترتیب: local، سپس project، سپس user. بعضی تنظیمات را میتوان با پرچمهای خطِ فرمان یا متغیرهای محیطی هم تنظیم کرد، که یک لایهی بازنویسیِ دیگرند. وقتی یک تنظیم بهنظر اعمال نمیشود، مقداری که تنظیم کردهای معمولاً توسطِ یک scopeِ دیگر یا یک متغیرِ محیطی بازنویسی میشود.
/doctor را اجرا کن تا فایلهای پیکربندیات اعتبارسنجی شوند و کلیدهای نامعتبر یا خطاهای schema آشکار شوند. وقتی /doctor مشکلی گزارش میکند، f را بزن تا گزارشِ تشخیصی به Claude فرستاده شود و او رفعاشکالها را با تو طی کند.
/status را اجرا کن تا ببینی کدام منابعِ تنظیمات فعالاند، از جمله اینکه آیا managed settings اعمالاند. برای فهمیدنِ اینکه کدام scope برای یک کلیدِ مشخص برنده میشود، نحوهی تعاملِ scopeها را ببین.
سرورهای MCP را بررسی کن
Section titled “سرورهای MCP را بررسی کن”/mcp را اجرا کن تا هر سرورِ پیکربندیشده، وضعیتِ اتصالش، و اینکه آیا برای پروژهی جاری تأییدش کردهای را ببینی. یک سرور میتواند درست تعریف شده باشد ولی به چند دلیلِ رایج همچنان ابزار ندهد:
- سرورهای project-scoped در
.mcp.jsonبه یک تأییدِ یکباره نیاز دارند. اگر آن درخواست رد شده باشد، سرور غیرفعال میماند تا وقتی از/mcpتأییدش کنی. - سروری که در شروع شکست بخورد در
/mcpبهصورتِ failed نشان داده میشود. مسیرهای فایلِ نسبی درcommandیاargsعلتی رایجاند، چون نسبت به دایرکتوریای که Claude Code را از آن راهاندازی کردهای حل میشوند، نه نسبت به محلِ.mcp.json. - سروری که connected نشان داده میشود ولی صفر ابزار فهرست میکند، با موفقیت شروع شده ولی فهرستِ ابزار برنمیگرداند. از
/mcpگزینهی Reconnect را انتخاب کن. اگر شمارش روی صفر بماند،claude --debug mcpرا اجرا کن تا خروجیِ stderrِ سرور را ببینی.
برای محلهای پیکربندی و قواعدِ scope، MCP را ببین.
hookها را بررسی کن
Section titled “hookها را بررسی کن”/hooks را اجرا کن تا هر hookِ ثبتشده برای نشستِ جاری را، گروهبندیشده بر اساسِ رویداد، فهرست کنی. اگر hookی که تعریف کردهای ظاهر نمیشود، خوانده نمیشود: hookها زیرِ کلیدِ "hooks" در یک فایلِ تنظیمات میروند، نه در یک فایلِ مستقل.
اگر hook ظاهر میشود ولی شلیک نمیکند، matcher علتِ معمول است. فیلدِ matcher یک رشتهی واحد است که از | برای تطبیق با چند نامِ ابزار استفاده میکند، برای مثال "Edit|Write". یک نامِ ابزارِ غلطاملایی بیصدا شکست میخورد چون matcher هرگز تطبیق نمییابد. یک مقدارِ آرایهای یک خطای schema است: Claude Code یک اعلانِ خطای تنظیمات نشان میدهد، /doctor شکستِ اعتبارسنجی را گزارش میکند، و آن ورودیِ hook حذف میشود پس در /hooks ظاهر نمیشود.
ویرایشهای settings.json پس از یک تأخیرِ کوتاهِ پایداریِ فایل در نشستِ در حالِ اجرا اعمال میشوند. لازم نیست ریاستارت کنی. اگر /hooks چند ثانیه پس از ذخیره همچنان تعریفِ قدیمی را نشان میدهد، /hooks را دوباره اجرا کن تا نما تازه شود.
اگر /hooks آن hook را نشان میدهد ولی همچنان شلیک نمیکند، گامِ بعدی تماشای زندهی ارزیابیِ hook است. یک نشست را با claude --debug hooks شروع کن و فراخوانیِ ابزار را تحریک کن. لاگِ دیباگ هر رویداد، اینکه کدام matcherها بررسی شدند، و کدِ خروج و خروجیِ hook را ثبت میکند. برای قالبِ لاگ دیباگِ hookها و برای الگوهای رایجِ شکست عیبیابیِ hookها را ببین.
در برابرِ یک پیکربندیِ تمیز تست کن
Section titled “در برابرِ یک پیکربندیِ تمیز تست کن”{/* min-version: 2.1.169 */}با claude --safe-mode شروع کن، که یک نشست را با همهی شخصیسازیها غیرفعال راهاندازی میکند، از جمله CLAUDE.md، skillها، plugins، hooks، سرورهای MCP، و دستورها و ایجنتهای سفارشی. احراز هویت، انتخابِ مدل، ابزارهای توکار، و permissions بهطورِ عادی کار میکنند. اگر مشکل در safe mode ناپدید شود، یکی از آن سطحها علت است؛ از وارسیهای هدفمندِ بالا استفاده کن تا بفهمی کدام. managed settingsی که سازمانت مستقر کرده همچنان تا حدی اعمال میشوند، پس hookها و status lineِ پیکربندیشده با سیاست حتی در safe mode هم اجرا میشوند.
اگر مشکل در safe mode باقی ماند، یا خودِ تنظیماتت مشکوکاند، در برابرِ نشستی مقایسه کن که هیچچیز از راهاندازیِ معمولت بارگذاری نمیکند. CLAUDE_CONFIG_DIR را به یک دایرکتوریِ خالی اشاره بده تا همهچیزِ زیرِ ~/.claude دور زده شود، و از دایرکتوریای راهاندازی کن که هیچ پوشهی .claude، فایلِ .mcp.json، یا CLAUDE.md ندارد تا پیکربندیِ پروژه هم رد شود.
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claudeنشستِ تمیز هیچ تنظیماتِ کاربری یا پروژهای، hook، سرورِ MCP، plugin، یا حافظهای ندارد.
- اگر سازمانت managed settings را مستقر کند همچنان اعمال میشوند، چون در یک مسیرِ سیستمیِ بیرون از
~/.claudeزندگی میکنند - روی Linux و Windows، از تو خواسته میشود دوباره وارد شوی چون اعتبارنامهها زیرِ دایرکتوریِ پیکربندی ذخیره میشوند
- روی macOS، اعتبارنامهها در Keychain هستند و به نشستِ تمیز منتقل میشوند
اگر مشکل اینجا ناپدید شود، علت جایی در ~/.claudeِ واقعی یا فایلهای .claudeِ پروژهات است. آنها را یکییکی دوباره وارد کن، با کپیکردنِ فایلها در دایرکتوریِ موقت یا با راهاندازی از پروژهات، تا بفهمی کدام. اگر در نشستِ تمیز باقی بماند، علت بیرون از پیکربندیِ کاربر و پروژهات است. /status را اجرا کن تا بررسی کنی آیا managed settings اعمالاند، دنبالِ متغیرهای محیطیی بگرد که روی Claude Code اثر میگذارند، سپس عیبیابی را ببین.
علتهای رایج را بررسی کن
Section titled “علتهای رایج را بررسی کن”اکثرِ غافلگیریهای پیکربندی به مجموعهی کوچکی از قواعدِ مکان و نحو برمیگردند. اینها را پیش از فرضِ باگ بررسی کن:
| علامت | علت | رفع |
|---|---|---|
| hook هرگز شلیک نمیکند | matcher بهجای رشته یک آرایهی JSON است | از یک رشتهی واحد با | برای تطبیق با چند ابزار استفاده کن، برای مثال "Edit|Write". الگوهای matcher را ببین. |
| hook هرگز شلیک نمیکند | مقدارِ matcher با حروفِ کوچک است، برای مثال "bash" | تطبیق به حروفِ کوچک و بزرگ حساس است. نامهای ابزار با حرفِ بزرگاند: Bash، Edit، Write، Read. |
| hook هرگز شلیک نمیکند | hookها بهجای settings.json در یک فایلِ مستقل تعریف شدهاند | برای پیکربندیِ پروژه یا کاربر هیچ فایلِ hookِ مستقلی وجود ندارد. hookها را زیرِ کلیدِ "hooks" در settings.json تعریف کن. فقط plugins یک hooks/hooks.jsonِ جدا بارگذاری میکنند. پیکربندیِ hook را ببین. |
| permissions، hooks، یا envِ تنظیمشده بهصورتِ سراسری نادیده گرفته میشوند | پیکربندی به ~/.claude.json اضافه شده | ~/.claude.json وضعیتِ اپ و تاگلهای UI را نگه میدارد. permissions، hooks، و env به ~/.claude/settings.json تعلق دارند. اینها دو فایلِ متفاوتاند. |
یک مقدارِ settings.json بهنظر نادیده گرفته میشود | همان کلید در settings.local.json تنظیم شده | settings.local.json، settings.json را بازنویسی میکند، و هر دو ~/.claude/settings.json را بازنویسی میکنند. تقدمِ تنظیمات را ببین. |
skill در /skills ظاهر نمیشود | فایلِ skill در .claude/skills/name.md است نه داخلِ یک پوشه | از یک پوشه با SKILL.md درونش استفاده کن: .claude/skills/name/SKILL.md. |
skill در /skills ظاهر میشود ولی Claude هرگز فراخوانش نمیکند | skill در frontmatterش disable-model-invocation: true دارد، یا توضیحش با نحوهی بیانِ درخواستت تطبیق ندارد | برچسبِ موجود در /skills را بررسی کن: برچسبِ «user-only» یعنی Claude خودش آن را تحریک نمیکند. فراخوانیِ skill را ببین. |
دستورالعملهای CLAUDE.mdِ زیرپوشهای بهنظر نادیده گرفته میشوند | فایلهای زیرپوشه بهمحضِ نیاز بارگذاری میشوند، نه در آغازِ نشست | وقتی Claude فایلی را در آن دایرکتوری با ابزارِ Read میخواند بارگذاری میشوند، نه در راهاندازی و نه هنگامِ نوشتن یا ساختنِ فایل در آنجا. نحوهی بارگذاریِ فایلهای CLAUDE.md را ببین. |
سابایجنت دستورالعملهای CLAUDE.md را نادیده میگیرد | ایجنتهای توکارِ Explore و Plan از CLAUDE.md صرفنظر میکنند. سابایجنتهای سفارشی آن را همانطورِ گفتوگوی اصلی بارگذاری میکنند | برای Explore یا Plan، دستورالعمل را در پرامپتِ واگذاریات بازگو کن. برای یک سابایجنتِ سفارشی، دستورالعملهای حیاتی را در بدنهی فایلِ ایجنت بگذار، که system promptِ ایجنت میشود. چه چیزی در راهاندازی بارگذاری میشود را ببین. |
| منطقِ پاکسازی هرگز در پایانِ نشست اجرا نمیشود | هیچ hookِ SessionEnd پیکربندی نشده | یک hookِ SessionEnd در settings.json اضافه کن. فهرستِ رویدادهای hook را ببین. |
سرورهای MCP در .mcp.json هرگز بارگذاری نمیشوند | فایل زیرِ .claude/ است یا از قالبِ پیکربندیِ Claude Desktop استفاده میکند | پیکربندیِ MCPِ پروژه در ریشهی مخزن بهصورتِ .mcp.json میرود، نه داخلِ .claude/. پیکربندیِ MCP را ببین. |
سرورهای MCPِ اضافهشده زیرِ mcpServers در settings.json هرگز ظاهر نمیشوند | settings.json کلیدِ mcpServers را نمیخواند | سرورهای پروژه را در .mcp.json در ریشهی مخزن تعریف کن، یا برای سرورهای user-scoped دستورِ claude mcp add --scope user را اجرا کن. پیکربندیِ MCP را ببین. |
| سرورِ MCPِ پروژه اضافه شد ولی ظاهر نمیشود | درخواستِ تأییدِ یکباره رد شده | سرورهای project-scoped به تأیید نیاز دارند. /mcp را اجرا کن تا وضعیت را ببینی و تأیید کنی. |
| سرورِ MCP از بعضی دایرکتوریها در شروع شکست میخورد | command یا args از یک مسیرِ فایلِ نسبی استفاده میکند | برای اسکریپتهای لوکال از مسیرهای مطلق استفاده کن. اجراشدنیهای روی PATHت مثلِ npx یا uvx همانطور که هستند کار میکنند. |
| سرورِ MCP بدونِ متغیرهای محیطیِ موردِانتظار شروع میشود | متغیرها در envِ settings.json هستند، که به فرایندهای فرزندِ MCP منتقل نمیشود | بهجایش envِ هر-سرور را داخلِ .mcp.json تنظیم کن. |
قاعدهی denyِ Bash(rm *) جلوی /bin/rm یا find -delete را نمیگیرد | قواعدِ prefix با رشتهی تحتاللفظیِ دستور تطبیق مییابند، نه با اجراشدنیِ زیرین | برای هر گونه الگوهای صریح اضافه کن، یا برای ضمانتِ قطعی از یک hookِ PreToolUse یا sandbox استفاده کن. |
منابعِ مرتبط
Section titled “منابعِ مرتبط”برای مرجعِ کامل روی هر سطحِ پیکربندی، صفحهی اختصاصی را ببین:
- مرجعِ دایرکتوریِ
.claude: محلِ هر فایلِ پیکربندی و اینکه چه چیزی آن را میخواند - Settings: ترتیبِ تقدم و فهرستِ کاملِ کلیدها
- مرجعِ Hooks: نامهای رویداد، payloadها، و قالبِ خروجیِ
--debug hooks - MCP: پیکربندیِ سرور، تأیید، و خروجیِ
/mcp - عیبیابیِ نصب و ورود: مشکلاتِ
command not found، PATH، و احراز هویت - عیبیابی: مشکلاتِ کارایی، هنگکردن، و جستوجو