https://virgool.ir/feed/@FarshidRoohiSenior Software Engineerfa2026-11-11 05:43:42https://files.virgool.ir/upload/users/10719/avatar/VqPc5V.jpghttps://virgool.ir/@FarshidRoohihttps://virgool.ir/@FarshidRoohi/ai-agents-kq9j3bp66p1yپیش از شروعاستفاده از AI برای برنامه‌نویسی دیگه به کپی کردن یک پیام خطا در پنجره چت و پرسیدن «چطور این مشکل را برطرف کنم؟» محدود نمی‌شود.ایجنت‌های کدنویسی مدرن می‌توانند یک Repository را بررسی کنند، دستورالعمل‌های پروژه را بخوانند، چندین فایل را تغییر دهند، تست‌ها را اجرا کنند، دلیل خطاها را پیدا کنند و نتیجه نهایی را اعتبارسنجی کنند. بااین‌حال، صرفاً دادن دسترسی به Codebase کافی نیست. بدون دستورالعمل‌های شفاف، Context مناسب و ابزارهای کارآمد، حتی یک ایجنت قدرتمند نیز ممکن است زمان و Token زیادی مصرف کند و تغییراتی انجام دهد که با معماری پروژه هماهنگ نیستند.در این مقاله بررسی می‌کنیم که چگونه می‌توان یک Workflow مؤثرتر برای کار با Coding Agentها ساخت. برای این کار از فایل‌های AGENTS.md، تنظیمات سطح پروژه و سطح ایجنت و ابزارهایی مانند Caveman، RTK و Codebase Memory MCP استفاده می‌کنیم. همچنین می‌بینیم که چگونه می‌توان همین Workflow را در Codex، Claude Code و Hermes Agent اجرا کرد.هدف ساده است: به‌جای استفاده از هوش مصنوعی صرفاً به‌عنوان یک ابزار پرسش‌وپاسخ، آن را به بخشی قابل‌اعتماد از فرایند توسعه نرم‌افزار تبدیل کنیم.نکات کلیدیاز ایجنت‌های کدنویسی برای انجام کامل تسک‌ها استفاده کنید، نه صرفاً پاسخ دادن به پرسش‌ها.به ایجنت اجازه دسترسی به Repository، ترمینال، تست‌ها، مستندات و تاریخچه Version Control را بدهید.دستورالعمل‌های دائمی پروژه را در فایل‌هایی مانند AGENTS.md، CLAUDE.md یا فایل‌های قوانین اختصاصی هر ایجنت نگهداری کنید.قوانین مشترک پروژه را از ترجیحات شخصی مربوط به ایجنت جدا کنید.از Codebase Memory MCP برای درک ساختار Repository بدون اسکن مداوم تمام فایل‌ها استفاده کنید.از RTK برای کاهش خروجی‌های شلوغ ترمینال، پیش از ورود آن‌ها به Context مدل استفاده کنید.از Caveman برای حذف توضیحات غیرضروری از پاسخ‌های ایجنت استفاده کنید.معیارهای پایان تسک را شفاف تعریف کنید: پیاده‌سازی، تست، اعتبارسنجی، مستندسازی و گزارش نهایی.فایل‌های دستورالعمل را کوتاه و کاربردی نگه دارید. یک بیانیه ۹۰۰ خطی درباره نام‌گذاری متغیرها باعث باهوش‌تر شدن ایجنت نمی‌شود؛ فقط سردرگمی گران‌تری تولید می‌کند.تمام تغییرات تولیدشده را با تست، Static Analysis، Build و بازبینی انسانی بررسی کنید.گفت‌وگو را متوقف کنید و تسک واگذار کنیدگفت‌وگو با یک LLM زمانی مفید است که به توضیح، مثال یا یک پاسخ سریع نیاز دارید.برای نمونه ممکن است بپرسید:چگونه این Exception را برطرف کنم؟این کلاس چه کاری انجام می‌دهد؟برای این تابع یک Unit Test بنویس.آیا این معماری درست است؟این سؤال‌ها می‌توانند پاسخ‌های مفیدی تولید کنند، اما مدل همچنان بیرون از فرایند واقعی توسعه قرار دارد. مدل معمولاً نمی‌تواند کل Repository را با اطمینان بررسی کند، پیاده‌سازی‌های مرتبط را ببیند، پروژه را اجرا کند، فرضیات خود را اعتبارسنجی کند یا مطمئن شود که کد پیشنهادی واقعاً کامپایل می‌شود.یک Coding Agent به شکل متفاوتی کار می‌کند.به‌جای اینکه بپرسید:How should I fix timeout handling in this API client?یک تسک کامل به ایجنت بدهید:Inspect the networking module, identify the current timeout behavior, implement typed timeout errors, update the affected tests, run the networking test suite, and report any remaining risks.در این حالت، ایجنت کدنویسی می‌تواند یک چرخه کامل را اجرا کند:دستورالعمل‌های Repository را بخواند.معماری مرتبط را بررسی کند.کلاس‌ها و Call Chainهای تحت‌تأثیر را پیدا کند.یک برنامه کوتاه تهیه کند.کد را تغییر دهد.تست‌ها و ابزارهای Static Analysis را اجرا کند.خطاها را بررسی کند.پیاده‌سازی را اصلاح کند.Diff نهایی را بازبینی کند.تغییرات انجام‌شده را خلاصه کند.برای مثال، Claude Code برای خواندن Codebase، ویرایش فایل‌ها، اجرای دستورات و ارتباط با ابزارهای توسعه طراحی شده است. بنابراین برخلاف یک رابط گفت‌وگوی ساده، می‌تواند مستقیماً داخل فرایند توسعه فعالیت کند.تفاوت اصلی ساده است:یک پاسخ چتی به شما پیشنهاد می‌دهد. یک ایجنت تغییر را انجام می‌دهد و آن را اعتبارسنجی می‌کند.یک محیط کاری مناسب برای ایجنت بسازیدحتی یک مدل قدرتمند نیز در صورت دریافت Context ضعیف، خروجی ضعیفی تولید می‌کند؛ فقط با اعتمادبه‌نفس بیشتر و واژه‌های گران‌تر.یک محیط مناسب برای Coding Agent به چهار لایه نیاز دارد:دستورالعمل‌ها: پروژه چگونه باید تغییر کند؟شناخت Codebase: Repository چه ساختاری دارد؟ابزارها: ایجنت چگونه فایل‌ها را می‌خواند، ویرایش می‌کند، Build می‌گیرد و تست اجرا می‌کند؟اعتبارسنجی: ایجنت چگونه ثابت می‌کند که تسک کامل شده است؟سه ابزاری که در این مقاله بررسی می‌شوند، بخش‌های مختلفی از این محیط را بهبود می‌دهند:Caveman: حجم توضیحات ایجنت را کاهش می‌دهد.RTK: خروجی دستورات ترمینال را فشرده می‌کند.Codebase Memory MCP: نیاز به جست‌وجو و بررسی تکراری Repository را کاهش می‌دهد.این ابزارها جایگزین یکدیگر نیستند. یکی پاسخ‌های ایجنت را کوتاه می‌کند، دیگری نویز دستورات ترمینال را کاهش می‌دهد و سومی از کشف مکرر ساختار Codebase جلوگیری می‌کند.از AGENTS.md به‌عنوان قرارداد پروژه استفاده کنیدنام استاندارد این فایل AGENTS.md و به‌صورت جمع است. مگر اینکه ابزار خاصی به‌طور مشخص از AGENT.md پشتیبانی کند، از نام مفرد استفاده نکنید.Codex پیش از شروع کار، فایل‌های AGENTS.md را به‌صورت خودکار پیدا و بارگذاری می‌کند.یک فایل AGENTS.md در سطح پروژه باید شامل موارد زیر باشد:معماری پروژهمرزهای مهم ماژول‌هادستورات Buildدستورات اجرای تستقواعد کدنویسیالزامات امنیتیانتظارات مربوط به مستندسازیDefinition of Doneفایل‌ها یا دایرکتوری‌هایی که نباید تغییر کنندمراحل ضروری بازبینیبرای مثال:# AGENTS.md ## Architecture - UI modules depend on domain modules. - Domain modules must not depend on Android APIs. - Data modules implement repository interfaces defined in domain. - Use Kotlin Coroutines and Flow for asynchronous operations. ## Implementation Rules - Keep changes limited to the requested feature. - Do not introduce a new dependency without approval. - Preserve backward compatibility for public APIs. - Add tests for changed behavior. - Do not suppress compiler or lint warnings without documenting the reason. ## Validation Run the following before completing a task: ```bash ./gradlew test ./gradlew lint ./gradlew assembleDebug ``` ## Completion Report Include: - Files changed - Tests added or updated - Commands executed - Remaining risks دستورالعمل‌های تو‌در‌توی پروژهRepositoryهای بزرگ می‌توانند داخل هر ماژول، دستورالعمل‌های اختصاصی‌تری داشته باشند:project/ ├── AGENTS.md ├── app/ ├── core/ └── features/ └── payment/ └── AGENTS.override.md Codex دستورالعمل‌ها را از ریشه پروژه تا دایرکتوری جاری بارگذاری می‌کند. فایل‌هایی که به دایرکتوری کاری نزدیک‌تر هستند، اولویت بیشتری دارند.Codex از موارد زیر پشتیبانی می‌کند:فایل سراسری AGENTS.mdفایل AGENTS.md در سطح Repositoryفایل‌های تو‌در‌توی AGENTS.override.mdبه این ترتیب، فایل ریشه می‌تواند قوانین عمومی پروژه را تعریف کند و ماژول پرداخت قوانین سخت‌گیرانه‌تری داشته باشد:# features/payment/AGENTS.override.md - Never log card, token, or payment-response data. - All payment-result states must be represented with typed models. - Run `./gradlew :features:payment:test` after each behavioral change. - Do not modify callback URLs without explicit approval. دستورالعمل‌های سطح پروژه و سطح ایجنت را جدا کنیدقوانین پروژه باید همراه Repository نگهداری شوند. ترجیحات شخصی توسعه‌دهنده باید در تنظیمات محلی ایجنت باقی بمانند.سطحکاربردنمونه‌هاسطح پروژهمعماری مشترک، دستورات و قوانین کیفیتAGENTS.md، فایل CLAUDE.md پروژه، .claude/rules/سطح ماژولقوانین مربوط به یک Feature یا دایرکتوریفایل‌های تو‌در‌توی AGENTS.md و AGENTS.override.mdسطح ایجنتترجیحات شخصی مربوط به Workflow~/.codex/AGENTS.md و ~/.claude/CLAUDE.mdتنظیمات ابزارMCP Serverها، Hookها، Permissionها و مدل‌هاconfig.toml، settings.json، config.yaml و .mcp.jsonSkillهافرایندهای قابل استفاده مجدد برای تسک‌های مشخصدایرکتوری Skillهای ایجنتCodexCodex از ساختار زیر پشتیبانی می‌کند:~/.codex/AGENTS.md ~/.codex/AGENTS.override.md ~/.codex/config.toml project/AGENTS.md project/module/AGENTS.override.md از فایل سراسری برای ترجیحات شخصی و قابل استفاده در پروژه‌های مختلف استفاده کنید:# ~/.codex/AGENTS.md - Inspect existing implementations before introducing abstractions. - Prefer small, reviewable changes. - Run targeted tests before the entire test suite. - Do not modify generated files manually. - Keep final reports concise. اطلاعات خاص هر پروژه باید در فایل AGENTS.md همان Repository قرار بگیرد.Claude CodeClaude Code از CLAUDE.md برای نگهداری دستورالعمل‌های دائمی استفاده می‌کند.این ابزار از Scopeهای مختلف پشتیبانی می‌کند:پروژهکاربرسازمانهمچنین می‌توان از .claude/rules/ برای تعریف قوانینی استفاده کرد که فقط به فایل‌ها، زبان‌ها یا بخش‌های مشخصی از پروژه مربوط هستند.Claude این فایل‌ها را به‌عنوان Context در نظر می‌گیرد، نه یک محدودیت تضمین‌شده. بنابراین برای قوانینی که باید همیشه اجرا یا مسدود شوند، بهتر است از Hookها استفاده کنید.یک ساختار کاربردی می‌تواند به شکل زیر باشد:~/.claude/CLAUDE.md project/CLAUDE.md project/.claude/rules/kotlin.md project/.claude/rules/testing.md ~/.claude/settings.json از CLAUDE.md برای دستورالعمل‌ها و از settings.json برای Permissionها، Hookها، Pluginها و تنظیمات ابزارها استفاده کنید.Hermes AgentHermes از Workspace Instruction، Skillهای قابل استفاده مجدد، Pluginها، حافظه و فایل تنظیمات کاربر پشتیبانی می‌کند.Skillها در مسیر زیر نگهداری می‌شوند:~/.hermes/skills/ این Skillها فقط هنگام نیاز بارگذاری می‌شوند. Hermes از رویکرد Progressive Disclosure استفاده می‌کند؛ یعنی تنها دستورالعمل مرتبط با تسک جاری وارد Context می‌شود.یک ساختار کاربردی برای Hermes:project/AGENTS.md ~/.hermes/config.yaml ~/.hermes/skills/ ~/.hermes/plugins/کاربرد هر بخش:AGENTS.md برای قوانین Repositoryconfig.yaml برای تنظیمات ایجنت و Pluginهاskills/ برای Workflowهای قابل استفاده مجددحافظه Hermes برای نگهداری دانشی که طی Sessionهای مختلف آموخته شده استHermes همچنین از Subagentها، حافظه دائمی، Tool Use، چندین Model Provider و ساخت Skill از کارهای قبلی پشتیبانی می‌کند.۱. از Caveman برای کاهش حجم پاسخ‌های ایجنت استفاده کنیدCoding Agentها معمولاً بسیار بیشتر از مقدار لازم توضیح می‌دهند.از آن‌ها می‌خواهید نام یک تابع را تغییر دهند، اما در پاسخ تاریخچه ادبی نام‌گذاری، تأملی درباره Maintainability و سه پاراگراف تبریک به خودشان بابت تغییر دوازده کاراکتر تحویل می‌دهند.Caveman یک Skill و Plugin است که ایجنت‌های کدنویسی را وادار می‌کند پاسخ‌هایی فشرده و مستقیم ارائه دهند، بدون اینکه کدها، دستورات، مسیر فایل‌ها و پیام‌های خطا حذف شوند.Caveman از ابزارهای مختلفی پشتیبانی می‌کند، از جمله:Claude CodeCodexHermes Agentبسیاری از ابزارهای کدنویسی دیگرچرا باید از Caveman استفاده کنیم؟Caveman در موارد زیر مفید است:کوتاه‌تر شدن پاسخ‌های ایجنتکاهش مصرف Output Tokenحذف توضیحات و تعارف‌های غیرضروریبررسی سریع‌تر روند انجام کارکوچک‌تر شدن فایل‌های دائمی دستورالعمل و حافظهباقی ماندن فضای بیشتر در Context Window برای کد واقعیCaveman فقط نحوه ارتباط ایجنت را فشرده می‌کند. این ابزار توانایی استدلال، شناخت Repository یا کیفیت پیاده‌سازی مدل را افزایش نمی‌دهد.این تفاوت مهم است. کوتاه‌تر کردن یک پاسخ اشتباه، آن را درست نمی‌کند؛ فقط باعث می‌شود زمان کمتری برای خواندن همان پاسخ اشتباه تلف شود.نصببرای Claude Code:claude plugin marketplace add JuliusBrussee/caveman claude plugin install caveman@cavemanبرای Codex:npx skills add JuliusBrussee/caveman -a codexبرای فعال کردن آن در یک Session مربوط به Codex:/cavemanبرای Hermes Agent:npx -y github:JuliusBrussee/caveman -- --only hermesنصب Hermes از سیستم Skill بومی آن استفاده می‌کند و Skill هنگام بارگذاری فعال می‌شود.بهترین موارد استفادهاز Caveman در موارد زیر استفاده کنید:خلاصه پیاده‌سازیگزارش روند انجام کارکامنت‌های Code Reviewتولید Commit MessageDebug روزمرهتسک‌های طولانی با گزارش‌های متعدد ایجنتدر شرایط زیر، فشرده‌سازی بیش از حد مناسب نیست:توضیح معماریتحلیل Incidentگزارش مشکلات امنیتیمستندات Migrationبررسی Trade-offهای مهمهدف این نیست که پاسخ ایجنت مبهم و رمزآلود شود. هدف، حذف توضیحات اضافی است.۲. از RTK برای کاهش نویز ترمینال استفاده کنیدبخش بزرگی از Context ایجنت ممکن است توسط خروجی دستورات ترمینال مصرف شود:هزاران خط مربوط به تست‌های موفقفهرست‌های بسیار بزرگ دایرکتوری‌هاخروجی‌های طولانی Git Diffلاگ‌های تکراری BuildStack Traceهایی با Frameهای تکراریپیام‌های پیشرفت Package Managerخروجی Docker با ستون‌های غیرضروریRTK دستورات Shell را رهگیری می‌کند و خروجی آن‌ها را پیش از رسیدن به Coding Agent فیلتر می‌کند.این ابزار می‌تواند:Directory Treeها را فشرده کند.نتیجه Searchها را گروه‌بندی کند.خروجی Git را کاهش دهد.تست‌های موفق را جمع کند.جزئیات Failureها را نگه دارد.برای مثال:git statusممکن است به این دستور تبدیل شود:rtk git statusهمچنین اجرای دستور زیر:./gradlew testمی‌تواند به‌جای ارسال تمام تست‌های موفق به مدل، یک خروجی کوتاه و متمرکز بر Failureها تولید کند.چرا باید از RTK استفاده کنیم؟RTK به ایجنت کمک می‌کند:Token کمتری برای خواندن خروجی ترمینال مصرف کند.خطاها را سریع‌تر پیدا کند.Context Window را با لاگ تست‌های موفق پر نکند.Sessionهای طولانی را قابل استفاده نگه دارد.دستورات اعتبارسنجی بیشتری را با بودجه Context یکسان اجرا کند.درصد کاهش خروجی Shell که RTK گزارش می‌کند، الزاماً برابر با همان درصد کاهش هزینه کل API نیست.Promptها، تاریخچه Conversation، پاسخ‌های مدل و سایر Tool Resultها نیز Token مصرف می‌کنند. مستندات RTK نیز کاهش خروجی Bash را از کاهش کل هزینه استفاده از مدل جدا می‌کند.نصبدر macOS:brew install rtkبرای Codex:rtk init --global --codexاین دستور، راهنمای استفاده از RTK را به فایل سراسری AGENTS.md مربوط به Codex اضافه می‌کند.Codex برخلاف برخی ایجنت‌های دیگر، Hook شفافی برای بازنویسی خودکار تمام دستورات ندارد. بنابراین این روش به رعایت دستورالعمل‌ها توسط مدل وابسته است.برای Claude Code:rtk init --globalClaude Code از Hook مربوط به PreToolUse استفاده می‌کند و می‌تواند دستورات Bash پشتیبانی‌شده را به‌صورت خودکار بازنویسی کند.ابزارهای داخلی Claude مانند موارد زیر از Hook مربوط به Bash عبور نمی‌کنند:ReadGrepGlobبرای Hermes Agent:rtk init --agent hermesاین دستور یک Plugin برای Hermes در مسیر زیر ایجاد می‌کند:~/.hermes/plugins/rtk-rewrite/سپس Plugin از طریق تنظیمات Hermes فعال می‌شود و دستورات پشتیبانی‌شده ترمینال را پیش از اجرا تغییر می‌دهد.در صورت نیاز از خروجی خام استفاده کنیدRTK عمداً خروجی‌ها را فیلتر، گروه‌بندی، کوتاه و Deduplicate می‌کند.در موارد زیر بهتر است RTK را دور بزنید و خروجی خام را بررسی کنید:Parse کردن JSON خاممقایسه خروجی در سطح Byteبررسی مشکلات مربوط به ترتیب داده‌هامشاهده Stack Trace کاملارسال خروجی به Parser دیگربررسی مشکلی که احتمال دارد خود RTK خروجی آن را تغییر داده باشدبهره‌وری باید نویز را حذف کند، نه شواهد را.۳. از Codebase Memory MCP برای شناخت Repository استفاده کنیدبدون ابزارهای Code Intelligence، یک ایجنت معمولاً Repository را به این شکل بررسی می‌کند:دایرکتوری‌ها را فهرست می‌کند.نام یک کلاس را جست‌وجو می‌کند.چند فایل را باز می‌کند.محل استفاده از کلاس را جست‌وجو می‌کند.فایل‌های بیشتری باز می‌کند.Interfaceها را جست‌وجو می‌کند.پس از Context Compaction تمام مراحل را دوباره تکرار می‌کند.در Session بعدی نیز دوباره همین کار را انجام می‌دهد، چون ظاهراً کشف مجدد معماری به یک سنت معتبر مهندسی نرم‌افزار تبدیل شده است.Codebase Memory MCP یک Repository را Index کرده و آن را به یک Knowledge Graph دائمی تبدیل می‌کند.این Graph می‌تواند موارد زیر را نمایش دهد:FunctionهاClassهاCall ChainهاRouteهاDependencyهاارتباط میان سرویس‌هابه‌جای بررسی مداوم فایل‌ها به‌صورت جداگانه، ایجنت می‌تواند این ساختار را Query کند.چرا باید از Codebase Memory MCP استفاده کنیم؟این ابزار می‌تواند به پرسش‌هایی مانند موارد زیر پاسخ دهد:چه کلاس‌هایی این تابع را فراخوانی می‌کنند؟چه کلاس‌هایی این Interface را پیاده‌سازی کرده‌اند؟تغییر این Method چه بخش‌هایی را تحت‌تأثیر قرار می‌دهد؟کدام Route به این Service می‌رسد؟این Data Model در کجا تبدیل می‌شود؟آیا این Function بدون استفاده است؟چه ماژول‌هایی به این Component وابسته‌اند؟چه فایل‌هایی بخشی از این Call Chain هستند؟این ابزار به‌خصوص در شرایط زیر مفید است:Repositoryهای Legacy و بزرگپروژه‌های چندماژوله AndroidMonorepoهاسیستم‌های Microserviceپروژه‌هایی با چند Coding AgentRefactorهای طولانیRepositoryهایی با مستندات محدوداین Server از Codex، Claude Code، Hermes و بسیاری از Clientهای دیگر پشتیبانی می‌کند.Installer آن می‌تواند فایل‌های تنظیمات MCP، دستورالعمل‌ها، Skillها و Lifecycle Hookهای مربوط به ایجنت‌های شناسایی‌شده را پیکربندی کند.نصبدر macOS یا Linux:curl -fsSL \ https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh \ | bashپس از نصب، Coding Agent را مجدداً اجرا کنید و از آن بخواهید:Index this project.Installer می‌تواند موارد زیر را تنظیم کند:Codex از طریق config.tomlClaude Code از طریق تنظیمات MCPHermes از طریق config.yamlپیش از خواندن فایل‌ها، Graph را Query کنیدیک Workflow مناسب برای ایجنت:Graph را Query کند تا مسیر احتمالی کد مشخص شود.فایل‌های Source معرفی‌شده توسط Graph را مستقیماً بررسی کند.ارتباط‌های مهم را با خواندن کد واقعی تأیید کند.تغییر را انجام دهد.دوباره Impact تغییر را Query کند.تست‌ها و Static Analysis را اجرا کند.نتیجه Graph را حقیقت قطعی در نظر نگیرید.موارد زیر می‌توانند باعث ایجاد نقص در Index شوند:کدهای تولیدشدهSyntaxهای پشتیبانی‌نشدهدایرکتوری‌های IgnoreشدهIndex قدیمیرفتارهای Dynamicاین پروژه سطح‌هایی مانند Scout، Verify و Auditor تعریف می‌کند که شواهد Graph را با بررسی مستقیم Source Code و پوشش Index ترکیب می‌کنند.از Graph برای Navigation و Impact Analysis استفاده کنید. Source Code و تست‌ها باید شواهد نهایی باشند.یک Workflow عملی با Codex، Claude Code و Hermesفرض کنید تسک زیر را داریم:Add typed timeout handling to an Android networking module. Preserve the public API, add unit tests, and verify all call sites.مرحله اول: اضافه کردن دستورالعمل‌های پروژهفایل زیر را در ریشه Repository ایجاد کنید:# AGENTS.md ## Project Context - This is a multi-module Android project. - Networking code is located under `core/networking`. - Repository interfaces belong in domain modules. - Data modules implement domain repository interfaces. - Kotlin is the primary language. - Minimum Android SDK is 21. ## Coding Rules - Preserve source and binary compatibility for public APIs. - Use sealed interfaces for typed networking failures. - Do not expose Ktor-specific exceptions outside the networking module. - Use Coroutines for asynchronous code. - Do not add dependencies without approval. ## Agent Workflow 1. Query Codebase Memory MCP before broad repository searches. 2. Verify graph results by reading the relevant source files. 3. Use RTK for noisy shell commands. 4. Use raw commands when exact output is required. 5. Add or update unit tests for behavioral changes. 6. Review the final Git diff before completion. ## Validation Run: ```bash ./gradlew :core:networking:test ./gradlew lint ./gradlew assembleDebug ``` ## Completion Criteria Report: - Root cause - Files changed - API compatibility - Tests executed - Remaining risksبرای Claude Code می‌توانید همین اطلاعات را از طریق یک فایل کوتاه CLAUDE.md بازاستفاده کنید یا قوانین اختصاصی Claude را در .claude/rules/ قرار دهید.مرحله دوم: نصب ابزارهای مشترکbrew install rtk curl -fsSL \ https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh \ | bashمرحله سوم: پیکربندی Codexnpx skills add JuliusBrussee/caveman -a codex rtk init --global --codexCodex را اجرا کنید:codexسپس Prompt زیر را وارد کنید:/caveman Index this project using Codebase Memory MCP. Implement typed timeout handling in core/networking. First identify the public API, implementations, callers, and existing tests. Then provide a short plan. Preserve compatibility, implement the change, add tests, run the required validation commands, inspect the final diff, and report remaining risks. Do not stop after suggesting code.مرحله چهارم: پیکربندی Claude Codeclaude plugin marketplace add JuliusBrussee/caveman claude plugin install caveman@caveman rtk init --globalClaude Code را داخل Repository اجرا کنید:claudeاز همان تسک استفاده کنید:Use Codebase Memory MCP to map the timeout-related call chain before editing. Implement typed timeout handling in core/networking. Preserve the public API, update unit tests, run the commands from AGENTS.md, review the diff, and finish only when the completion criteria are satisfied.Claude Code از دستورالعمل‌های پروژه، ابزارهای MCP، دسترسی ترمینال و Hookهای خود استفاده می‌کند.Caveman پاسخ‌های Claude را کوتاه می‌کند و RTK خروجی دستورات Bash پشتیبانی‌شده را پیش از ورود به Context مدل کاهش می‌دهد.مرحله پنجم: پیکربندی Hermes Agentnpx -y github:JuliusBrussee/caveman -- --only hermes rtk init --agent hermesHermes را داخل Repository اجرا کنید:hermesسپس Prompt زیر را وارد کنید:Use the repository AGENTS.md as the task contract. Use Codebase Memory MCP to find the timeout implementation, its callers, repository boundaries, and related tests. Implement typed timeout handling without exposing networking-library exceptions. Add tests, execute the validation commands, review the final diff, and provide a concise completion report.Hermes می‌تواند Caveman را به‌عنوان Skill بارگذاری کند، از Plugin ترمینال RTK استفاده کند، به تنظیمات MCP دسترسی داشته باشد و دانش مفید را از طریق سیستم Skill و حافظه خود نگهداری کند.برای ایجنت‌ها قرارداد تکمیل تسک تعریف کنیدیک Prompt ضعیف:Fix the timeout problem.یک Prompt بهتر:Investigate the timeout problem in core/networking. Before editing: - Identify the public API. - Find all implementations and callers. - Find current timeout tests. - Explain the root cause in no more than five lines. Implementation: - Add typed timeout handling. - Preserve API compatibility. - Do not expose Ktor exceptions outside the module. - Add tests for timeout, cancellation, and non-timeout failures. Validation: - Run the networking tests. - Run lint. - Build the debug application. - Review the final Git diff. Finish with: - Files changed - Commands executed - Test results - Compatibility impact - Remaining risksاین Prompt هم خود تسک و هم شواهد موردنیاز برای کامل در نظر گرفتن آن را مشخص می‌کند.پیشنهادهای نهاییعملکرد یک Coding Agent را فقط بر اساس جذاب یا حرفه‌ای بودن توضیحاتش ارزیابی نکنید.این موارد را بررسی کنید:آیا مسیر درست کد را پیدا کرده است؟آیا معماری پروژه را رعایت کرده است؟آیا پیاده‌سازی کامپایل می‌شود؟آیا رفتار تغییرکرده توسط تست‌ها پوشش داده شده است؟آیا Diff نهایی محدود و متمرکز است؟آیا تصمیم‌های مهم مستند شده‌اند؟آیا ایجنت می‌تواند برای نتیجه‌گیری‌های خود مدرک ارائه کند؟از ابزارها و فایل‌ها به شکل زیر استفاده کنید:AGENTS.md برای تعریف انتظارات پروژهفایل‌های سطح ایجنت برای تعریف Workflow شخصیSkillها برای بسته‌بندی فرایندهای قابل استفاده مجددCodebase Memory MCP برای پیمایش ساختار RepositoryRTK برای کاهش نویز ترمینالCaveman برای کاهش نویز پاسخ‌های ایجنتتست، Build، Lint و بازبینی برای اعتبارسنجی نتیجهبهترین Workflow برای Coding Agent، یک گفت‌وگوی طولانی‌تر نیست.بهترین Workflow یک سیستم تکرارپذیر است که در آن ایجنت:Context مناسب را دریافت می‌کند.از ابزارهای درست استفاده می‌کند.تسک را انجام می‌دهد.نتیجه را اعتبارسنجی می‌کند.فقط اطلاعات مهم را گزارش می‌دهد.ممنون که خواندیدایجنت‌های کدنویسی زمانی واقعاً کاربردی می‌شوند که آن‌ها را بخشی از فرایند مهندسی نرم‌افزار بدانیم، نه فقط یک ابزار چت باهوش‌تر.کار را با یک فایل AGENTS.md شفاف شروع کنید، ابزارهایی را اضافه کنید که پروژه واقعاً به آن‌ها نیاز دارد و مشخص کنید هر تسک چگونه باید اعتبارسنجی شود. فرایند را ساده نگه دارید، نتایج را بررسی کنید و به‌مرور Workflow خود را بهبود دهید.ممنون که این مقاله را خواندید؛ امیدوارم تجربه بهتر و مؤثرتری از کار با ایجنت‌های کدنویسی داشته باشید.فرشید روحیفرشید روحیWed, 29 Jul 2026 13:03:25 +0330https://virgool.ir/@FarshidRoohi/چرا-درگیر-کد-کثیف-و-پروژه-اسپاگتی-میشیم-i9fg2tjblmy3تو این مقاله سعی دارم راجب نکاتی صحبت کنم که باعث میشه کد کثیف زده بشه و در نهایت پروژه نرم‌افزاریمون تبدیل به یه پروژه اسپاگتی بشه و در نهایت باهم راه‌حل‌های احتمالی رو بررسی میکنیم.در ادامه به این چندتا سوال میخوایم جواب بدیم:کد کثیف به چه کدی گفته میشه؟پروژه نرم‌افزاری اسپاگتی؟راه حل چیه؟کد کثیف به چه کدی گفته میشه؟غیرقابل فهم بودن: پیچیدگی غیرضروری و معماری نامناسبکدهای تکراری: عدم توجه به قابل استفاده بودن کدها(متدها، کلاس‌ها، ...)نبود تست: امکان نوشتن تست وجود نداشته باشه یا زمانی برای تست نویسی گذاشته نشود.غیرقابل اعتماد: وجود اشکالات مختلف و سخت بودن دیباگ و رفع مشکل.خیلی از برنامه‌نویس‌ها زمانی که یک پروژه جدید رو شروع میکنن، حساسیت خیلی زیادی برای نوشتن کدهای تمیز، قابل نگه داری و قابل توسعه دارن، ولی چی میشه که اون حساسیت‌ها به مرور کم میشه و به یکسال نکشیده پروژه تبدیل به یک اسپاگتی بزرگ میشه؟متاسفانه دلایل زیادی وجود داره که منجر به این اتفاقات میوفته که به بعضی از اون موارد اشاره میکنم:کمبود مهارت برنامه‌نویس: کمبود مهارت یا عدم درک کافی به اندازه و آینده پروژه نرم‌افزاری(نمیدونیم قراره چقدر بزرگ بشه این پروژه).عدم مدیریت مناسب زمان: انتخاب ددلاین‌های نزدیک بدون توجه به عمق کار و نادیده گرفتن نقاط تاریک هر پروژه یا تسک.عدم وجود قرارداد برای سبک کدنویسی: وقتی یک استاندارد یا قرارداد تیمی برای یک پروژه وجود نداشته باشه احتمال زیادی وجود داره که هر برنامه‌نویس به سبک شخصی خودش کد بنویسه و این باعث بی نظمی و یکپارچه نبودن کدهای پروژه میشه.تغییرات زیاد: خیلی مواقع درگیر پروژه‌هایی میشیم که خود مدیر محصول هم تعریف درستی از پروژه نداره و شفاف نیست براش، بخاطر این موضوع، ناخواسته مجبور به تغییرات زیاد با بازه زمانی کم میشیم که باعث بوجود اومدن بدهی‌های فنی زیادی میشیم.مدیریت ضعیف: عدم وجود مستندات کافی، عدم وجود ارتباطات مناسب بین هم تیمی و بین تیمیپروژه نرم‌افزاری اسپاگتی؟خروجی موارد بالا میشه یک پروژه نرم‌افزاری به شکل اسپاگتی که ساختار درستی نداره و اجزای پروژه در هم و بر هم و پیچیده شده.اشکالات پروژه‌های اسپاگتی:دشوار شدن توسعه: پیاده سازی هر امکان جدید به شدت زمان‌بر و سخت میشه، و بجایی میرسه که ساخت پروژه جدید هزینه زمانی خیلی کمتری برامون داره تا توسعه پروژه کثیف و اسپاگتی.دشوار شدن نگهداری: هر پروژه نرم‌افزاری نیاز به نگهداری و اصطلاحا باگ فیکس داره، ولی در این مدل از پروژه‌ها پیدا کردن و حل یک مشکل نرم‌افزاری به شدت دشوار میشه و عملا بازنویسی یک کلاس یا ماژول منطقی تر از پیدا کردن یک مشکل از هزارتو به وجود اومده است.افزایش هزینه: توسعه و نگهداری یک پروژه اسپاگتی میتونه بسیار پر هزینه‌تر از پروژه‌های با ساختار مناسب باشه.کاهش کیفیت: متاسفانه در این نوع پروژه‌ها، کیفیت کد نویسی به حداقل رسیده و احتمالا خروجی خوبی هم نخواهد داشت.راه حل؟اولین و آسون‌ترین تصمیم معمولا ایجاد یک پروژه دیگه‌س که خیلی از برنامه‌نویس‌ها این تصمیم رو میگیرن.ولی آیا راه حل بهتری هم هست؟ بنظر من بله هست، طبق تجربه‌های مختلفی که توی پروژه‌های نرم‌افزاری داشتم راه حل ساخت یک پروژه مجدد با رویکرد کد تمیز بدون در نظر گرفتن نقاط ضعف پروژه قبلی هم منجر به شکست شده(تبدیل شدن به اسپاگتی در طولانی مدت)، تاکید من روی زمان طولانی مدته چون در کوتاه مدت هم باز حساسیت زیادی به خرج میدیم، تو ریویوها سختگیری بیشتری داریم، ولی به مرور زمان باز شاهد کدهای کثیف هستیم که گاهی این حس به وجود میاد که باز برگشتیم سر نقطه اول.من زمانی راه حل ساخت یک پروژه جدید با رویکرد کد تمیز رو پیشنهاد میدم که ساعت‌ها راجب پروژه کثیف قبلی جلسه گذاشته بشه، عیب یابی بشه، از نقاط ضعف و چرایی پروژه کثیف مستند تهیه بشه و در نهایت شفافیتی شکل بگیره که امکان تکرار اشتباه وجود نداشته باشه و درصد خوبی از موارد بالا که بهش اشاره شد رو پوشش بده.راه حل دوم تمیز کردن پروژه کثیف فعلی میتونه چالش های زیادی برامون داشته باشه بعلاوه هزینه زمانی و مالی زیادی برای صاحب پروژه، ولی مزیت‌هایی داره که بد نیست مرور کنیم:تجربه: بزرگترین مزیت ریفکتور کردن پروژه‌های نرم‌افزاری تجربه کردن میتونه باشه که کمک شایانی از لحاظ فنی به تیم میکنه.امکان یادگیری فنی: خیلی از بدهی‌های فنی رو میشه به دید یک موضوع یادگیری و تجربه نگاه کرد که در نهایت باعث رشد فنی تیم و فرد میشه.امکان تغییر: خیلی از بازنویسی‌هایی ک اتفاق میوفته دست برنامه‌نویس رو باز میزاره که درگیر تکنولوژی‌های جدید بشه و از کدبیس‌های قدیمی فاصله بگیریم.رشد مهارت تیمی: حل بدهی‌های فنی نیاز به ارتباط بین تیمی و درون تیمی، پوشش نقطه ضعف‌های موجود رو داره که همین موضوع باعث پیشرفت تیم میشه.جمع‌بندی:بدهی‌های فنی، کد کثیف و پروژه‌های اسپاگتی جز مواردی هستن که باهاشون به صورت روزانه سرکار داریم، این خوبه بشناسیم و بدونیم که چه مشکلاتی تو پروژه داریم و مطمئن بشیم که همه تیم در جریان هستن، برنامه کوتاه و بلند مدت برای رفع این مشکلات داشته باشیم، چون اگه برنامه‌ای برای حل این مشکلات وجود نداشته باشه، هم تیم درگیر توسعه فرسایشی میشه که در طولانی مدت آثار مخربی مانند جدا شدن برنامه‌نویس از تیم و عقب افتادن فرد از رشد فنی میشه و هم صاحب محصول یا پروژه هزینه‌های گذافی رو باید متقبل بشه برای توسعه و نگهداری پروژه.در مورد بدهی‌های فنی اینجا بیشتر توضیح دادم: نگاهی به بدهی فنی پروژه های نرم‌افزاریمنابع:https://en.wikipedia.org/wiki/Technical_debthttps://en.wikipedia.org/wiki/Don%27t_repeat_yourselfhttps://en.wikipedia.org/wiki/Code_smellhttps://stackoverflow.blog/2023/12/27/stop-saying-technical-debt/https://en.wikipedia.org/wiki/Spaghetti_codeفرشید روحیفرشید روحیFri, 23 Feb 2024 20:33:55 +0330https://virgool.ir/@FarshidRoohi/technical-debts-axbzjjqvrrzqتو این مقاله سعی دارم بدهی فنی رو توضیح بدم و مشکلات و سودهای احتمالیش رو باهم بررسی کنیم که در طولانی مدت میتونه چه مشکلاتی برامون ایجاد کنه و در کوتاه مدت چه سودی میتونه برامون داشته باشه.بدهی فنی چیه و به چه دلایلی ایجاد میشن؟مزایا و معایب؟اصطلاح این کد بو میده یعنی چی؟چطوری میتونیم با بدهی فنی کنار بیایم؟بدهی فنی چیست و به چه دلایلی ایجاد میشن؟فرض کنید روی پروژه‌ای کار میکنید که اضافه کردن فیچر جدید زمان‌بر شده، دیباگ کردن یه باگ بسیار سخت شده، اصطلاحا توسعه پذیر و یا قابل بهبود نیست یا زمان زیادی برای بهبود نیار داره.مواردی که در بالا بهش اشاره شد نتایج بدهی‌های فنی ساختاریه که به مرور زمان باعث کند شدن پروسه توسعه محصول میشه.ما میتونیم بدهی‌های فنی داشته باشیم که مشکلی برای توسعه پروژه ایجاد نکنه و به طور مثال خروجی به درستی داره کار میکنه ولی بهینه نیست و میشه بهترش رو نوشت و احتمالا اتفاق فورسی براش پیش نمیاد.بدهی فنی میتونه علل‌های مختلفی داشته باشه ولی معمولا میتونه تو این دوتا دسته جا بگیره:محدودیت زمانیبی‌تجربه بودن تیم یا فردمحدودیت زمانی: با یک مثال این مورد رو توضیح میدم فرض کنید پیاده کردن یه پروژه نرم افزاری به اسم X با فیچرهای a, b, c طبق بررسی نیازمندی‌ها و توان نیروها ۶ ماه زمان برآورد شده، ولی مدیر پروژه با توجه به محدودیت ها و از دست ندادن زمان عرضه در مارکت درخواست انجام این پروژه را در ۳ ماه دارد، یعنی نصف زمان برآورد شده است.بی‌تجربه بودن تیم یا فرد: زمانی اتفاق میوفتد که تقریبا همه چیز متناسب با زمانش پیش میرود، ولی در حین پیاده سازی پروژه بخاطر عدم تجربه کافی، تصمیم های غلط گرفته میشود، این تصمیم‌های غلط میتواند انتخاب اشتباه معماری یا حتی انتخاب تکنولوژی یا فریمورک اشتباهی برای آن پروژه خاص باشد که در بلند مدت میتوان آثارش را مشاهده کرد.بدهی فنی، مزایا و معایببدهی فنی میتونه مزیت های کوتاه مدتی برای محصول داشته باشه که حتی میتونه نقش برگ برنده برای تیم محصول رو بازی کنه، فرض کنید که یک ایده‌ای وجود دارد که در این بازه زمانی امکان درآمد زایی برای شرکت داشته باشه، با فرض این موضوع اگر تیم برنامه نویسی در زمان ایده آل خود بخواهد این فیچر یا پروژه را توسعه دهد احتمالا تیم محصول با یک فرصت سوزی بزرگ روبرو خواهد شد، و بخاطر این موضوع مدیر تیم فنی با قبول عواقب بدهی فنی که در آینده احتمالا گریبان گیر تیم فنی خواهد شد توسعه نرم افزار را جلو ببرد.معمولا مشکلات بدهی فنی در طولانی مدت و در روند توسعه محصول خودشان را نشان میدهند که هزینه‌های زیادی هم با خودشون میارن، به طور مثال وقتی روی معماری یک پروژه نرم‌افزاری وقت زیادی گذاشته نشود و انتخاب درستی در پیاده سازی نداشته باشیم احتمالا در آینده هزینه خیلی زیاد برای توسعه محصول خواهیم داشت که با بزرگ شدن پروژه روند کارها کندتر و کندتر از قبل پیش میرود، یا موردی رو فرض کنید که شخص جدیدی وارد تیم یا پروژه شده است، چون پروژه بدهی‌های فنی زیادی دارد، از جمله تست خوبی نوشته نشده، وقت زیادی برای معماری، دیزاین پترن‌ها گذاشته نشده، ... در این شرایط هم سرعت توسعه تحت تاثیر قرار گرفته میشه، هم به پیچیده‌تر شدن Code base پروژه اضافه میشه.بدهی‌های فنی میتونه موارد زیادی رو در بر بگیره با اولویت‌های کم یا زیاد و شرایط خاص و غیر خاص، به طور مثال معمولا در پروژه‌های برنامه‌نویسی اولین چیزی که به عنوان بدهی فنی پیش میاد نوشتن Unit Test، استفاده از دیزاین پترن‌ها برای بهینه‌سازی یا قابلیت استفاده مجدد یا پیروی از اصول های توسعه نرم افزار مانند ۵ اصل SOLID یا DRY و خیلی از موارد دیگه که در توسعه پذیر بودن پروژه نرم‌افزاری نقش‌های مهمی دارن.اصطلاح این کد بو میده یا Code Smellدر مهندسی نرم‌افزار، به ویژگی‌ها یا نشانه‌هایی در کد یک برنامه که حاکی از وجود مشکلاتی در عمق برنامه باشند، Code Smell گفته می‌شود. بوهای کد خطا نیستند، اما می‌توانند کد را برای نگهداری، درک و گسترش دشوارتر کنند.بوی کد به ۳ سطح از پروژه نرم افزاری اشاره میکنه:بوهای بد کد در سطح برنامهبوهای بد کد در سطح کلاسبوهای بد کد در سطح متدهر کدوم از موارد بالا یک لیستی از اشتباهات رایج رو شامل میشه که عدم رعایت اون موارد تو پروژه نرم افزاری حکایت از بوی بد کد داره.اینجا به چندتا از موارد خیلی عمومی اشاره میکنم:کد تکراری: کدی که در چندین مکان در پروژه تکرار می‌شود.کد مرده: کدی که استفاده نمیشه ولی داخل پروژه وجود داره.متدهای طولانی: متدهایی که بیش از حد طولانی و پیچیده هستند.لیست‌های پارامتر طولانی: متدهای با تعداد زیادی پارامتر، راه حلش این میتونه باشه که بجای پارامترهای زیاد یک کلاس یا مدل پاس بدیم.تغییر واگرا: کلاس‌هایی که به‌طور مکرر و به روش‌های مختلف تغییر می‌کنند.جراحی تفنگ ساچمه‌ای: کلاس‌هایی که برای یک تغییر واحد در چندین مکان تغییر می‌کنند.چطوری میتونیم بدهی‌های فنی رو صاف کنیم؟راه حل دقیق برای همه تیم های برنامه نویسی و پروژه ها وجود نداره و خیلی بستگی به نوع پروژه و وضعیت پروداکت داره، ولی دو راه حل مشترک وجود داره که بیشترین مشکلات رو پوشش میده:ساخت پروژه جدید و درس گرفتن از اشتباهات گذشتهریفکتور کردن بخش های مختلف پروژه به مرور زمانمورد اول زمانی اتفاق میوفته که پروژه به حدی از پیچیدگی و بدهی‌های فنی رسیده که دیگه قابل توسعه نیست و راه حل کم هزینه میتونه گزینه ساخت پروژه جدید و توجه زیاد به نقطه ضعف های پروژه قبلی باشه.مورد دوم ریفکتور کردن بخش‌های مختلف پروژه در کنار انجام نیازمندی‌های پروداکت، با یک مثال توضیح بیشتری میدم:فرض کنید روی یک پروژه کار میکنید که بدهی فنی در رابطه با معماری و ساختار پروژه وجود داره و تستی برای قسمت‌های مختلف پروژه نوشته نشده، در همین حین، تیم پروداکت فیچرهایی رو برای توسعه نیاز داره. تو این شرایط احتمالا امکان ساخت پروژه جدید وجود نداره و از طرفی هم بدهی‌فنی های زیادی هم وجود داره، یکی از راه حل‌های موجود میتونه این باشه که تیم برنامه‌نویسی واقعیت بدهی فنی رو به تیم پروداکت یا مدیر پروژه شرح بده و ازشون وقت برای حل کردن این مشکلات بگیره و شرح کار به این شکل میشه که در هر دوره(ماه، هفته، هر اسپرینت اسکرام، ...) چند درصد از زمان رو برای ریفکتور کردن و حل کردن بدهی‌های فنی اختصاص داده بشه، و چند درصد از زمان تیم رو به پیاده کردن نیازمندی‌های تیم پروداکت اختصاص دهیم.با این راه حل احتمالا حل کردن تمام بدهی‌های فنی امری زمان بر باشه، ولی میتونیم با این شرایط، هم کدهای موجود رو ریفکتور کنیم، هم به نیاز مندی‌های بیزینس برسیم که معمولا باعث روند پیشرفت تدریجی پروژه و بیزینس میشه.نتیجه‌گیریبدهی‌فنی لزوما خیلی بد یا خیلی خوب نیست، پروژه های برنامه نویسی میتونه بدهی‌های فنی متعددی داشته باشه ولی تا زمانی که توسعه محصول رو تحت تاثیر قرار نده میتونیم باهاشون کنار بیایم و درگیر موارد با اولویت بالاتر بشیم، از جمله حل مشکلات مهم و ریفکتور کردن، یا حتی استفاده از تکنولوژی جدیدتر.اگه در حال شروع یک پروژه هستید و از لحاظ زمانی محدودیت دارید، باید دونسته هزینه‌های بدهی فنی در آینده رو انتخاب کنید.همیشه ساخت پروژه جدید بهترین راه حل برای حل کردن بدهی فنی های زیاد نیست و میتونیم به صورت خرد موارد مهم رو انجام بدیم در حالی که نیازمندی های بیزینس هم رفع بشه.همیشه باید به Code smell توجه داشته باشیم تا بدهی های فنی پروژه روز به روز بیشتر نشه و کدهای کثیف باعث ایجاد کدهای کثیف بیشتر نشه.منابعhttps://en.wikipedia.org/wiki/Code_smellhttps://en.wikipedia.org/wiki/Shotgun_surgeryhttps://martinfowler.com/bliki/CodeSmell.htmlhttps://www.youtube.com/watch?v=w9YhmMPLQ4Uhttps://en.wikipedia.org/wiki/SOLIDhttps://en.wikipedia.org/wiki/Don%27t_repeat_yourselfفرشید روحیفرشید روحیWed, 01 Nov 2023 15:12:13 +0330