‏agent.md: ترفند یه برنامه‌نویس برای کد تمیزتر با AI

فابین سنگلار (Fabien Sanglard) می‌گه اولین بار وسط ۲۰۲۵ با LLM کدنویسی رو امتحان کرد و اصلاً راضی نبود؛ کدی که گرفت حتی کامپایل نمی‌شد. چند ماه بعد دوباره امتحان کرد و این بار مدل تونست یه باگ سخت رو تو یه کتابخونه‌ی Rust پیدا کنه، ولی کدی که می‌نوشت بدون کامنت و ساختار بود، یعنی سرعتی که به دست می‌آورد رو باید صرف تمیزکاری بعدی می‌کرد.

بعد که سراغ IDEهای عامل‌محور (agentic) مثل Antigravity و پلاگین Claude Code تو VS Code رفت، تونست کد رو مرحله‌به‌مرحله ریویو کنه و بهش بگه از عدد جادویی استفاده نکن یا اسم تابع رو کوتاه‌تر بنویس. کیفیت خیلی بهتر شد ولی هر سشن جدید باید همون نکاتو از اول تکرار می‌کرد که خسته‌کننده بود.

راه‌حلش agent.md بود؛ یه فایلی که هارنس کدنویسی (harness یعنی همون ابزار عامل‌محوری که کد می‌نویسه) اول هر سشن می‌خونه و خودکار توی پرامپت تزریقش می‌کنه. سنگلار نسخه‌ی خودشو گذاشته که شامل قوانینی مثل پرهیز از عدد جادویی، کوتاه نگه داشتن اسم تابع‌ها، خالی‌نگه‌داشتن سطر بین بلوک‌های کد، و قوانین دقیق برای پیام‌های commit (خط اول حداکثر ۵۰ کاراکتر، فعل امری، توضیح چرایی نه چگونگی) می‌شه. کافیه این فایل رو تو ریشه‌ی پروژه بذاری، یا با symlink از claude.md و gemini.md بهش وصلش کنی.

یه مشکل دیگه هم هست به اسم context dilution (یعنی وقتی حجم پرامپت زیاد می‌شه، مدل به دستورهای وسط متن کمتر توجه می‌کنه و بیشتر رو اول و آخرش تمرکز می‌کنه) که تو مقاله‌ی معروف Lost in the Middle هم بهش اشاره شده. سنگلار برای دورزدنش دو کار می‌کنه: برای هر فیچر یه سشن تازه شروع می‌کنه تا کانتکست کوتاه بمونه، و هر وقت کیفیت کد افت کرد صریح می‌گه agent.md رو دوباره بخون.

نکته‌ی آخر اینه که خود سنگلار الان به‌جای اینکه دستی agent.md رو ادیت کنه، از خود عامل می‌خواد فایل رو براش آپدیت کنه. با این‌حال تأکید می‌کنه این ترفند جادویی نیست و بازم باید کد رو بخونی، چون LLMها هنوز هالوسینیشن دارن و نمی‌شه بهشون صد در صد اعتماد کرد؛ فقط الان به‌جای تمرکز رو سبک کد، بیشتر رو معماری و طراحی تمرکز می‌کنه.

نکات کلیدی:

• یه فایل agent.md بساز که هارنس کدنویسی اول هر سشن خودکار می‌خونتش و قوانین سبک کدنویسیت توش ذخیره می‌مونه
• می‌شه با symlink از claude.md یا gemini.md به همون agent.md وصل شد تا همه‌جا فعال بمونه
• برای مشکل context dilution (کم‌توجهی مدل به وسط پرامپت‌های طولانی): سشن‌های کوتاه‌تر بساز و در صورت افت کیفیت صریحاً بگو agent.md رو دوباره بخونه
• حتی با agent.md بازم باید کد رو ریویو کرد؛ تمرکز فقط از سبک کد میره رو معماری و طراحی