دردسر: چرا کدنویسی با هوش مصنوعی همیشه یک‌جا لنگ می‌زند

هر کسی با Cursor، Windsurf یا Claude Code پروژه زده، یک خرد شدن مشترک را تجربه کرده: هوش مصنوعی یک تکه کد تحویل می‌دهد، کپی‌پیست می‌کنی، اجرا می‌گیری — بیلد خطا می‌دهد، تست قرمز می‌شود، وابستگی‌ها جای اشتباه نصب می‌شوند. مشکل هوش هوش مصنوعی نیست؛ مشکل این است که اصلاً «قوانین نانوشته» پروژه‌ات را نمی‌داند.

AGENTS.md یک فایل Markdown در ریشه پروژه است که مخصوص چشم هوش مصنوعی نوشته می‌شود: چطور بیلد کند، چطور تست بزند، از چه قواعدی پیروی کند. README.md برای آدمیزاد است؛ پر است از معرفی پروژه، راهنمای مشارکت، داستان برند. وقتی هوش مصنوعی این‌ها را می‌خواند، مثل کارمند تازه‌واردی است که روز اول یک کاتالوگ تبلیغاتی شرکت به دستش داده‌اند و فوراً از او کد می‌خواهند — می‌داند شرکت چه کار می‌کند، ولی نمی‌داند فرمان بیلد چیست، تست کجا اجرا می‌شود، قانون ESLint کدام است. نتیجه؟ هر بار باید در چت تکرار کنی: «از pnpm استفاده کن نه npm»، «تست‌ها زیر packages/web هستند»، «lint را یادت نرود». صد بار تکرارشان کنی، پروژه هنوز بهم‌ریخته است.

ضرر در پروژه‌های فریلنسری مستقیم‌تر است: یک پروژه برون‌سپاری Next.js + Prisma گرفته‌ای، Cursor را برای سرعت فعال کرده‌ای، ولی هوش مصنوعی با npm install وابستگی‌ها را نصب می‌کند و تنظیمات workspace در pnpm از کار می‌افتد؛ مسیر schema دیتابیس را نمی‌شناسد و فایل migration تولیدشده خطا می‌دهد. مشتری تحویل فوری می‌خواهد، تو سه ساعت صرف دیباگ کد تولیدی هوش مصنوعی می‌کنی — این پول سخت درمی‌آید.

سه سناریوی تکراری خرابکاری: ① اشتباه در مدیر بسته (پروژه با pnpm است، هوش مصنوعی پیش‌فرض npm install می‌زند)، وابستگی‌ها جای اشتباه می‌نشینند، workspace می‌شکند؛ ② پیدا نکردن ورودی تست (تست‌ها زیر packages/web هستند، هوش مصنوعی در ریشه pnpm test می‌زند و می‌گوید «فایل تست پیدا نشد»؛ ③ بی‌نظمی در سبک کد (پروژه با ESLint + Prettier است، کد تولیدی هوش مصنوعی تورفتگی و کوتیشن را خراب می‌کند و CI قرمز می‌شود).

فرصت: AGENTS.md مرز بین «مستندات انسانی» و «مستندات ماشینی» را مشخص می‌کند

پروژه متن‌باز AGENTS.md در گیت‌هاب (آدرس: github.com/agentsmd/agents.md، تا ۲۵-۰۸-۲۰۲۶ حدود ۲۴ هزار ستاره) دقیقاً همین مشکل را حل می‌کند. ایده‌اش ساده است: یک فایل Markdown در ریشه پروژه بگذار که به هوش مصنوعی بگوید چطور بیلد کند، چطور تست بزند، از چه سبک کدی پیروی کند.

این فایل جایگزین README نیست، مکمل آن است. README برای مشارکت‌کننده انسانی است، AGENTS.md برای عامل هوش مصنوعی. وظایفشان از هم جداست و با هم قاطی نمی‌شود.

طبق پست منبع، AGENTS.md در ده‌ها هزار پروژه متن‌باز به‌کار گرفته شده (عدد دقیق نیاز به تأیید دارد) و ابزارهای اصلی برنامه‌نویسی با هوش مصنوعی مثل VS Code، Cursor، Windsurf، Aider و GitHub Copilot از آن پشتیبانی می‌کنند (تأیید شده). طبق بازخورد جامعه، OpenAI Codex و Google Jules هم پشتیبانی ارائه می‌دهند (⚠️ تأیید نشده). اگر الان یاد نگیری، یعنی داری با لهجه با هوش مصنوعی حرف می‌زنی.

مسیر اول: دستی یک AGENTS.md حداقلی بنویس

هزینه نزدیک صفر. یک فایل بساز، سه بخش بنویس، تمام.

پیش‌نیاز ذهنی: مثال‌های زیر با pnpm کار می‌کنند (نسبت به npm دیسک کمتری می‌گیرد و از monorepo workspace پشتیبانی می‌کند)، turbo ابزار ارکستراسیون وظایف monorepo است، و پارامتر --filter مشخص می‌کند فقط روی یک زیربسته اجرا شود تا کل مخزن تحت تأثیر قرار نگیرد.

بخش اول «Dev environment tips»: به هوش مصنوعی بگو از چه مدیر بسته‌ای استفاده کند، چطور به زیربسته بپرد، چطور ماژول جدید بسازد. مثلاً در نمونه رسمی:

• pnpm dlx turbo run where <project_name> — مستقیم به پوشه زیربسته می‌رود، بدون ls پشت سر هم
• pnpm install --filter <project_name> — فقط وابستگی‌های یک زیربسته را نصب می‌کند، کل monorepo را تکان نمی‌دهد
• pnpm create vite@latest <project_name> -- --template react-ts — یک زیربسته React + Vite با بررسی TypeScript می‌سازد

این فرمان‌ها را هوش مصنوعی خودش حدس نمی‌زند، ولی وقتی بنویسی‌شان، عیناً اجرا می‌کند.

بخش دوم «Testing instructions»: به هوش مصنوعی بگو تست چطور اجرا شود، پایپ‌لاین CI کجاست، قبل از کامیت چه چک‌هایی اجباری است. نمونه رسمی شامل:

• pnpm turbo run test --filter <project_name> — تمام چک‌های یک زیربسته را اجرا می‌کند
• pnpm vitest run -t "<test name>" — فقط یک تست منطبق با نام مشخص را اجرا می‌کند
• «Fix any test or type errors until the whole suite is green» — تا سبز نشده، دست برندار
• «Add or update tests for the code you change, even if nobody asked» — این جمله کلیدی است؛ اگر ننویسی، هوش مصنوعی تنبلی می‌کند و تست نمی‌نویسد

بخش سوم «PR instructions»: قالب عنوان کامیت را مشخص کن، اجبار به اجرای lint و test. نمونه رسمی: Title format: [<project_name>] <Title> و «Always run pnpm lint and pnpm test before committing».

این سه بخش روی‌هم کمتر از ۵۰ خط است، ولی نرخ موفقیت اولین اجرای کد تولیدی هوش مصنوعی را حسابی بالا می‌برد (طبق بازخورد جامعه، عدد دقیق نیاز به تأیید دارد).

مسیر دوم: استفاده تو در تو در monorepoهای بزرگ

اگر پروژه سازمانی گرفته‌ای و کدبیس ساختار monorepo دارد (چند پروژه مرتبط در یک مخزن گیت، مثلاً فرانت‌اند، بک‌اند و کد اشتراکی هر کدام یک زیرپوشه)، یک AGENTS.md کافی نیست. AGENTS.md از حالت تو در تو پشتیبانی می‌کند: در هر زیرپوشه یک AGENTS.md اختصاصی بگذار، هوش مصنوعی خودش «نزدیک‌ترین» فایل را می‌خواند.

روش اجرایی: AGENTS.md ریشه بنویس قواعد سراسری (مدیر بسته، فرآیند CI، نکات امنیتی)، بعد در packages/web/، packages/api/ و packages/shared/ هر کدام یک فایل جدا بنویس که فرمان‌های بیلد، ورودی تست و وابستگی‌های خاص آن زیربسته را توضیح دهد. مثلاً بسته فرانت‌اند باید بنویسد «کتابخانه کامپوننت shadcn، استایل Tailwind، آیکون lucide-react»؛ بسته بک‌اند باید بنویسد «migration دیتابیس با Prisma، روت‌های API زیر src/routes، احراز هویت JWT».

وقتی هوش مصنوعی داخل یک زیرپوشه کار می‌کند، نزدیک‌ترین AGENTS.md را بارگذاری می‌کند و اولویت آن بالاتر از فایل ریشه است. یعنی در یک پروژه، دستیار فرانت‌اند و دستیار بک‌اند دستورهای کاملاً متفاوت می‌گیرند و با هم قاطی نمی‌شوند.

مسیر سوم: تبدیلش به مزیت رقابتی در پروژه‌های فریلنسری

بازار فریلنسری هوش مصنوعی الان قرمز شده — همه با Cursor کار می‌کنند، ولی کیفیت تحویل فرق دارد. اگر در پروپوزال بنویسی «این پروژه با استاندارد AGENTS.md پیکربندی شده و توسعه با کمک هوش مصنوعی از قواعد پروژه پیروی می‌کند»، نرخ برد نسبت به رقبایی که فقط می‌گویند «من با هوش مصنوعی کد می‌زنم» بالاتر می‌رود.

اجرای عملی: بعد از گرفتن پروژه، ۳۰ دقیقه وقت بگذار ساختار پروژه مشتری را بفهمی، بعد یک AGENTS.md سفارشی بنویس. خود این فایل بخشی از تحویل است — مشتری بعداً خودش برای نگهداری کد با هوش مصنوعی از آن استفاده می‌کند.

سرویس پیکربندی AGENTS.md را جداگانه قیمت‌گذاری کن (قیمت‌ها مرجع هستند، با بازار محلی تطبیق بده): نسخه پایه ۷۰ دلار (پیکربندی تک‌فایلی + یک فایل README توضیحی)، نسخه سازمانی ۴۵۰ دلار (ساختار monorepo تو در تو + قواعد امنیتی + آموزش تیم). اقلام تحویل: ① فایل AGENTS.md سفارشی ② پشتیبانی ۳۰ روزه ③ یک ویدیوی آموزشی ۱۰ دقیقه‌ای. مناسب برای: مشتریانی که اشتراک Cursor/Windsurf دارند ولی نتیجه نمی‌گیرند. نامناسب برای: مشتریانی که هنوز کاملاً دستی کار می‌کنند و ابزار هوش مصنوعی ندارند.

نمونه واقعی: خندق سازگاری AGENTS.md

AGENTS.md تحت مجوز MIT منتشر شده (تأیید شده) و توسط جامعه نگهداری می‌شود (ساختار حکمرانی دقیق نیاز به بررسی دارد). سایت رسمی: agents.md.

سازگاری بزرگ‌ترین خندق آن است: تأیید شده که VS Code، Cursor، Windsurf، Aider و GitHub Copilot همگی از خواندن AGENTS.md پشتیبانی می‌کنند؛ طبق بازخورد جامعه، OpenAI Codex، Claude Code، Gemini CLI و Google Jules هم پشتیبانی ارائه می‌دهند (⚠️ تأیید نشده). یعنی یک فایل می‌نویسی، تمام دستیارهای اصلی از آن استفاده می‌کنند — لازم نیست برای هر ابزار پیکربندی جدا بنویسی.

مقایسه با راه‌حل‌های دیگر: .cursorrules در Cursor فقط داخل خود Cursor کار می‌کند، به محض مهاجرت به Windsurf از کار می‌افتد؛ CLAUDE.md در Claude Code فقط سرویس‌دهنده Claude است؛ سیستم دستوری GitHub Copilot هم مجموعه جداگانه خودش را دارد. ویژگی «یک‌بار بنویس، همه‌جا اجرا کن» در AGENTS.md دلیل اصلی پذیرش سریع آن است.

هزینه مهاجرت بین ابزارها صفر می‌شود. امروز با Cursor کار می‌کنی، فردا مهاجرت می‌کنی به Windsurf، AGENTS.md مستقیم قابل استفاده است و لازم نیست قواعد را از نو بنویسی.

فراخوان اقدام: امشب یک راهنمای ماشین به پروژه‌ات اضافه کن

چک‌لیست ۵ دقیقه‌ای: ① ریشه پروژه را باز کن ② فایل AGENTS.md بساز ③ قالب رسمی را از github.com/agentsmd/agents.md کپی کن ④ سه فرمان (بیلد، تست، lint) را پر کن ⑤ دفعه بعد که از هوش مصنوعی کد خواستی، نتیجه را ببین.

اگر monorepo داری، امشب ۲۰ دقیقه اضافه‌تر بگذار و برای هر زیربسته یک پیکربندی تو در تو اضافه کن. فردا صبح که سر کار برگردی، می‌بینی کد تولیدی هوش مصنوعی دیگر نیازی به اصلاح مکرر ندارد.

AGENTS.md الان بالاترین ROI را در پیکربندی برنامه‌نویسی با هوش مصنوعی دارد — ۳۰ دقیقه وقت، در ازای چند ساعت دیباگ ماهانه.