یک عامل کدنویسی (coding agent) با نظرات و عقاید قاطع وارد مخزن (repository) شما نمی‌شود. او آنچه را که از قبل وجود دارد می‌خواند، منطق را جذب می‌کند و الگوهایی را که می‌یابد تکرار می‌کند. اگر لایه دسترسی به داده‌های شما مجموعه‌ای درهم‌پیچیده از SQL خام و کوئری‌های تکراری باشد، عامل با خوشحالی گره دیگری به آن اضافه خواهد کرد. اگر پوشش تست شما ضعیف باشد، تست‌های ضعیفی تولید خواهد کرد. این از تنبلی یا بی‌کفایتی نیست؛ بلکه عملکرد دقیق الگویابی (pattern matching) است.

پر کردن شکاف بین آنچه تصور می‌کنید و آنچه عامل می‌سازد، نیازمند زمینه (context) و محدودیت‌ها (constraints) است، نه دستورات (prompts) بلندتر یا آرزوی داشتن مدلی هوشمندتر. شما با مهندسی کردن محیطی که ابزار در آن کار می‌کند، آن را همسو می‌کنید. در اینجا شsix روش عملی برای انجام این کار آورده شده است.

بازنویسی برای تقلید

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

در عوض، یک مرجع تمیز به او بدهید. ماژولی را انتخاب کنید که نشان‌دهنده ساختار ایده‌آل شما باشد. آن را از نویزهای غیرضروری پاک کنید تا معماری آن آشکار شود. وقتی درخواست ویژگی جدیدی دارید، مستقیماً به آن فایل ارجاع دهید: "از الگوی موجود در /src/orders/repository.py پیروی کن." یک مثال خوش‌ساخت، بیش از یک پاراگراف قوانین انتزاعی را منتقل می‌کند، زیرا کد جایی برای تفسیر باقی نمی‌گذارد. اگر مخزن شما فاقد یک مثال تمیز واحد است، یکی بنویسید. یک پیاده‌سازی مرجع (reference implementation) مختصر، سرمایه‌گذاری یک‌باره‌ای است که در هر درخواست بعدی سودمند خواهد بود. عامل، ساختار، سبک مدیریت خطا و جداسازی دغدغه‌ها (separation of concerns) را کپی خواهد کرد، زیرا این تنها نقشه‌ای است که شما قابل مشاهده کرده‌اید.

ابتدا از حالت برنامه‌ریزی (Plan Mode) استفاده کنید

قبل از ایجاد یا تغییر هر فایلی، از Claude بخواهید یک برنامه پیشنهاد دهد. آن را ملموس کنید: کدام فایل‌ها تغییر خواهند کرد، چه توابعی اضافه خواهند شد، چه وابستگی‌هایی (dependencies) وارد خواهند شد و قطعات جدید چگونه در گراف موجود جای می‌گیرند.

این مرحله به عنوان یک آشکارساز تضاد رایگان عمل می‌کند. اگر برنامه Claude پیشنهاد اضافه کردن یک مهاجرت پایگاه داده (database migration) در داخل خط لوله استقرار (deployment pipeline) اپلیکیشن را بدهد، در حالی که تیم شما مهاجرت‌ها را از طریق یک کار هماهنگ‌شده (orchestrated job) جداگانه اجرا می‌کند، شما این عدم تطابق را در عرض چند ثانیه متوجه می‌شوید، نه در طول بازبینی کد (code review). اگر برنامه‌ریزی کند از یک ابزار منسوخ (deprecated utility) استفاده کند، می‌توانید قبل از اینکه نیمی از ویژگی نوشته شود، مسیر را به او نشان دهید. برنامه، مدل را مجبور می‌کند تا فرضیات خود را درباره معماری شما آشکار کند. همان‌طور که طرح یک توسعه‌دهنده جونیور را به چالش می‌کشید، با برنامه هم برخورد کنید. این کار تنها چند دقیقه زمان می‌برد و به طور منظم از یک ساعت زمان برای باز کردن کدهای بد جلوگیری می‌کند.

زمینه کامل را از همان ابتدا ارائه دهید

بیشتر شکست‌های همسویی (alignment failures) نه به این دلیل رخ می‌دهند که عامل وظیفه را اشتباه متوجه شده است، بلکه به این دلیل است که او در حال بهینه‌سازی برای محدودیت‌های اشتباه بوده است. یک راه حل می‌تواند از نظر فنی بی‌نقص باشد اما همچنان غیرقابل استفاده باشد، اگر بودجه، الزامات تأخیر (latency) یا مرزهای انطباق (compliance) را که فراموش کرده‌اید ذکر کنید، نقض کند.

محدودیت‌های خود را در اولین دستور (prompt) بیان کنید. اگر نقطه انتهایی (endpoint) شما باید در صدک ۹۹ زیر ۲۰۰ میلی‌ثانیه باقی بماند، آن را بگویید. اگر تحت قوانین HIPAA، GDPR یا یک رژیم حسابرسی داخلی خاص فعالیت می‌کنید، آن را صریح بیان کنید. اگر صورت‌حساب زیرساخت شما حساس است و نمی‌توانید یک کلاستر کش مدیریت‌شده (managed cache cluster) اضافی راه اندازی کنید، سقف هزینه را مشخص کنید. Claude Code نمی‌تواند بر سر امتیازاتی (trade-offs) که از وجودشان بی‌خبر است، مذاکره کند. هرچه زودتر این مرزها را تزریق کنید، عامل آن‌ها را در پایه و اساس راه حل خود می‌سازد، به جای اینکه با آن‌ها مانند مسائل فرعی برخورد کند که بعداً باید اصلاح شوند.

حافظه را کدگذاری کنید

تکرار یک اصلاح مشابه، اتلاف وقت و پنجره زمینه (context window) شماست. وقتی متوجه شدید که بیش از یک بار به Claude می‌گویید از کتابخانه خاصی اجتناب کند، از یک wrapper خاص استفاده کند یا از یک قرارداد نام‌گذاری (naming convention) پیروی کند، متوقف شوید. آن اصلاح را به حافظه پروژه تبدیل کنید.

یک فایل CLAUDE.md در ریشه مخزن خود ایجاد کنید. این دفترچه راهنمای خانه شماست. آن را با قوانینی که اهمیت دارند پر کنید: به جای unittest از pytest استفاده کنید؛ تمام فراخوانی‌های HTTP خروجی باید از طریق circuit-breaker در /lib/http عبور کنند؛ هرگز مستقیماً از فایل قدیمی utils.py وارد (import) نکنید؛ همیشه ورودی‌ها را قبل از رسیدن به handler با لایه schema اعتبارسنجی کنید. وقتی Claude Code پروژه شما را بارگذاری می‌کند، این فایل را به طور خودکار می‌خواند. با گذشت زمان، CLAUDE.md به یکی از پربازده‌ترین دارایی‌های شما تبدیل می‌شود، زیرا استانداردهای شما را بدون نیاز به تایپ مجدد آن‌ها در هر جلسه، مقیاس‌پذیر می‌کند. اصلاحاتی که زمانی دستورات گذرا بودند، به اجزای دائمی کدbase تبدیل می‌شوند.

قوانین را با استفاده از Hookها مکانیزه کنید

مستندات کمک می‌کنند، اما ممکن است نادیده گرفته شوند. وقتی قانونی واقعاً حیاتی است، آن را از حالت توصیه به حالت اجبار تغییر دهید. از هوک‌ها (hooks)، بررسی‌های pre-commit، گیت‌های CI یا اسکریپت‌های اعتبارسنجی سفارشی استفاده کنید تا شکستن قوانین سخت را غیرممکن کنید.

اگر هر ماژول جدید باید تست‌های واحد (unit tests) متناظر داشته باشد، فقط به آن در CLAUDE.md اشاره نکنید. یک گیت پوشش (coverage gate) پیکربندی کنید که اگر فایلی در /src بدون تست متناظر اضافه شد، بیلد (build) را با خطا مواجه کند. اگر سیاست امنیتی شما ارسال (commit) اطلاعات حساس (secrets) را ممنوع می‌کند، اسکنری اجرا کنید که جلوی push را بگیرد. اگر تیم شما ترتیب خاصی برای importها یا قوانین lint می‌خواهد، اصلاح آن را با یک pre-commit hook خودکار کنید. این مکانیزم‌ها خروجی Claude را همان‌طور که خروجی شما را شناسایی می‌کنند، می‌گیرند. آن‌ها احتمال خطای انسانی یا انحراف مدل (model drift) را از بین می‌برند و «لطفاً به خاطر بسپار» را با «امکان ادامه نیست» جایگزین می‌کنند. قانونی که اجرا نشود، صرفاً یک پیشنهاد است.

استفاده از بازبین‌های مستقل

خودبازبینی (Self-review) غیرقابل اعتماد است. وقتی Claude کار خودش را بررسی می‌کند، اغلب فرضیات خودش را تأیید می‌کند، چون خودش آن‌ها را ایجاد کرده است. راه حل این است که چشم‌های تازه‌ای وارد کنید، حتی اگر آن چشم‌ها متعلق به همان مدلی باشد که تحت یک دستورالعمل (charter) متفاوت در حال اجراست.

عامل‌های بازبین (reviewer agents) مجزا با تمرکز محدود و مشخص ایجاد کنید. از یکی بخواهید صرفاً از نظر امنیتی حسابرسی (audit) انجام دهد: آیا خطرات تزریق (injection)، نقاط انتهایی (endpoints) داخلیِ در معرض خطر، یا سریال‌سازی‌های (deserializations) ناامن وجود دارد؟ از دیگری بخواهید پوشش تست و موارد خاص (edge cases) را ارزیابی کند. سومی ممکن است بررسی کند که تغییرات، قوانین تعریف شده در CLAUDE.md را رعایت کرده‌اند یا خیر. این بازبین‌ها نیازی به مدل‌های سفارشی پیچیده ندارند. آن‌ها فقط به استقلال از مرحله تولید اولیه نیاز دارند. اصطکاکِ درخواست از کسی — یا چیزی — دیگر برای نگاه کردن به کد، فرضیاتی را که برای سازنده بدیهی به نظر می‌رسیدند، شناسایی می‌کند. هزینه اضافی توکن‌ها در مقایسه با قیمت رسیدن یک باگ به محیط تولید (production)، ناچیز است.

چرخه (The Loop)

هم‌راستایی (Alignment) پروژه‌ای نیست که آن را تمام کنید؛ بلکه چرخه‌ای است که باید حفظ کنید. هر بار که خروجی Claude را اصلاح می‌کنید، از خود بپرسید آیا آن اصلاح می‌تواند به یک ورودی جدید در CLAUDE.md یا یک گیت جدید در ابزارهای شما تبدیل شود؟ اگر یک اصلاح را دو بار انجام دادید، یعنی شکافی در سیستم خود پیدا کرده‌اید. آن را برای همیشه پر کنید.

با گذشت هفته‌ها، این تمرین اثر خود را چند برابر می‌کند. عامل (agent) دیگر حدس نمی‌زند و شروع به دنبال کردن مسیرهایی می‌کند که شما ایجاد کرده‌اید. کدبیس (codebase) طوری به نظر می‌رسد که انگار خودش کد می‌زند، زیرا محدودیت‌ها شفاف، مثال‌ها تمیز و قوانین مکانیکی (اجباری) هستند. وظیفه شما از اصلاح کردن به مدیریت و سازماندهی (curation) تغییر می‌کند.

Source: https://dev.to/az365ai/how-to-align-claude-code-with-your-codebase-6-techniques-2026-3k28

Optional learning community: https://t.me/GyaanSetuAi