ساخت اولین پروژه و انتخاب مدل در آشاکد

خب، فرض می‌کنیم آشاکد را نصب کرده‌اید و کلید API آشا هم سر جایش است. اگر هنوز نصبش نکرده‌اید، اول سری به این آموزش بزنید: نصب AshaCode دسکتاپ روی ویندوز و اجرای اولین ایجنت — آنجا قدم‌به‌قدم دانلود، نصب و گذاشتن کلید را توضیح داده‌ایم.

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

خلاصه مسیر: باز کردن آشاکد ← افزودن پوشه پروژه ← انتخاب مدل از لیست چت ← تنظیم reasoning ← انتخاب حالت plan یا build ← فرستادن پیام «کدبیس را بخوان و AGENTS.md بنویس» ← برگشتن به چت‌های قبلی با دکمه Home.

قبل از شروع چی لازم داریم؟

• آشاکد دسکتاپ نصب‌شده با کلید آشا — اگر موقع باز شدن برنامه خطای احراز هویت می‌بینید، یعنی هنوز قدم نصب را کامل نکرده‌اید.
• کیف پول شارژشده در app.asha-ai.ir — چون هر پیامی که به مدل می‌دهید از همین کیف پول کم می‌شود.
• یک پوشه پروژه — فرقی نمی‌کند پایتون باشد، ری‌اکت، وردپرس یا حتی یک پوشه شلوغ و قدیمی. اتفاقاً هرچه شلوغ‌تر باشد، این آموزش به دردش بیشتر می‌خورد.

گام ۱ — ورود به آشاکد و افزودن پروژه

آشاکد دسکتاپ را باز کنید. صفحه اولش خیلی خلوت است؛ عمداً. قرار نیست گیجتان کند. دنبال دکمه‌ای شبیه Add folder یا Open project بگردید و رویش بزنید. این همان نقطه‌ای است که به ایجنت می‌گویید «از اینجا به بعد، اینجا خانه‌ی توست».

گام ۲ — انتخاب پوشه درست پروژه

حالا پنجره انتخاب پوشه باز می‌شود. بروید سراغ همان پوشه‌ای که کدتان داخلش است و تأیید (Select Folder) را بزنید. دو تا نکته که خیلی‌ها اولش اشتباه می‌کنند:

• ریشه‌ی پروژه را انتخاب کنید، نه یک زیرپوشه‌ی تصادفی. یعنی جایی که فایل‌هایی مثل package.json یا requirements.txt یا .git هست. اگر یک پوشه بالاتر یا پایین‌تر را بدهید، ایجنت نصف فایل‌ها را نمی‌بیند.
• بعد از انتخاب، اسم پوشه باید بالای برنامه دیده شود. اگر اسمش را نمی‌بینید، یعنی هنوز پروژه ست نشده و هر دستوری بدهید به جایی وصل نیست.

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

گام ۳ — انتخاب مدل از لیست چت

پایین صفحه، همان کادر چت که قرار است داخلش تایپ کنید را نگاه کنید. بالاش یک منوی کشویی برای انتخاب مدل هست. روش بزنید؛ لیستی که می‌بینید همان ۴۰۰+ مدل آشاست که با کلید شما آمده. لازم نیست همه‌شان را بشناسید. فقط این منطق را داشته باشید:

• کار کوچک و روزمره (توضیح کد، تغییر متن ساده، نوشتن تست کوچک) ← یک مدل سبک و ارزان بردارید. سریع‌تر جواب می‌دهد و کیف پولتان هم نفس می‌کشد.
• کار سخت (معماری جدید، دیباگ عجیب، ریفکتور بزرگ) ← یک مدل قوی‌تر بردارید. گران‌تر است، ولی یک جواب درستش از ده جواب نصفه‌ی مدل ضعیف ارزان‌تر درمی‌آید.
• داخل لیست می‌توانید جست‌وجو کنید. اسم مدل را بنویسید و انتخابش کنید؛ لازم نیست اسکرول بی‌پایان بروید پایین.

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

گام ۴ — تنظیم reasoning (عمق فکر کردن مدل)

کنار انتخاب مدل، برای خیلی از مدل‌ها یک درجه یا گزینه‌ی reasoning هم هست. به زبان ساده یعنی «قبل از جواب دادن، چقدر فکر کن». هرچه بالاتر باشد، مدل بیشتر سناریوها را سبک‌سنگین می‌کند، خطاهای منطقی‌اش کمتر می‌شود — و خب، مصرف و هزینه هم بالاتر می‌رود.

• پایین (low): برای سؤال‌های ساده، خواندن فایل، تغییرهای سطحی. سریع و ارزان.
• متوسط (medium): حالت پیش‌فرض خوب برای بیشتر کارهای روزمره.
• بالا (high): فقط برای گره‌های واقعی — باگی که دو روز است پیدا نمی‌شود، یا تصمیم معماری که برگشتن از آن سخت است.

گام ۵ — حالت ایجنت: build یا plan؟

حالا مهم‌ترین انتخاب: ایجنت در چه حالتی کار کند؟ بالای کادر ورودی، سوییچی شبیه plan / build هست. این دو تا زمین تا آسمان فرق دارند:

• حالت plan: ایجنت فقط فکر می‌کند و برنامه می‌دهد. کد را می‌خواند، قدم‌ها را لیست می‌کند، ریسک‌ها را می‌گوید — ولی به هیچ فایلی دست نمی‌زند. مثل مشاوری که نقشه می‌کشد ولی آچار دست نمی‌گیرد. وقتی پروژه را نمی‌شناسید یا تغییر بزرگ در راه است، همیشه اول با همین شروع کنید.
• حالت build: اینجا دیگر ایجنت دست به کار می‌شود: فایل می‌سازد، ویرایش می‌کند، دستور اجرا می‌کند، تست می‌گیرد. وقتی از نقشه راضی هستید، به این حالت سوییچ کنید و بگویید «حالا اجراش کن».

تجربه‌ام می‌گوید عجله‌نکن‌ها اول plan می‌گیرند و بعد می‌روند سراغ build، و آخرش هم وقت کمتری تلف می‌شود. برعکسش — مستقیم رفتن روی build در یک پروژه‌ی ناآشنا — معمولاً می‌شود چند فایل نصفه‌تغییرکرده که باید دستی برگردانید.

گام ۶ — فرستادن اولین پیام: «کدبیس را بخوان و AGENTS.md بنویس»

همه‌چیز آماده است. مدل را انتخاب کردید، reasoning را تنظیم کردید، حالت را هم فعلاً بگذارید روی plan یا build — برای این تسک خاص فرقی ندارد، چون قرار است فقط بخواند و یک فایل بنویسد. حالا این پیام را دقیقاً همین‌طور در کادر چت بنویسید و Enter بزنید:

Review the codebase and write the file AGENTS.md

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

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

این AGENTS.md اصلاً چی هست؟

AGENTS.md یک فایل متنی ساده در ریشه‌ی پروژه است؛ مثل یک «راهنمای خوش‌آمد برای ایجنت‌ها». داخلش نوشته می‌شود پروژه چیست، ساختار پوشه‌ها چطور است، با چه دستوری اجرا و تست می‌شود، و موقع تغییر کد باید چه قراردادهایی را رعایت کند.

نکته‌ی جادویی‌اش اینجاست: دفعه‌های بعد که به آشاکد (یا هر ایجنت Opencode-محور دیگری) پیامی می‌دهید، ایجنت خودش این فایل را می‌خواند. یعنی لازم نیست هر بار از اول توضیح بدهید «این پروژه جنگوست، تستش با فلان دستور است، فلان پوشه را دست نزن». یک‌بار درست ساخته شود، همه‌ی جواب‌های بعدی دقیق‌تر، کم‌غلط‌تر و ارزان‌تر می‌شوند. یک جور حافظه‌ی دائمی برای پروژه است.

و یک پیشنهاد: بعد از اینکه AGENTS.md آماده شد، آن را کامیت کنید و در گیت نگهش دارید. هم‌تیمی‌هایتان هم وقتی از ایجنت استفاده کنند، همان راهنما را می‌بینند و همه با یک زبان با ایجنت حرف می‌زنند.

گام ۷ — برگشتن به چت‌های قبلی و ادامه دادن آن‌ها

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

برای این کار روی دکمه‌ی Home بالای صفحه بزنید — همان آیکون خانه. اگر دستتان روی کیبورد است، میان‌بر Ctrl + B هم همین کار را می‌کند و سریع‌تر است.

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

اگر چیزی درست پیش نرفت

پوشه‌ی اشتباه را باز کردم

اشکالی ندارد. سشن را ببندید، یک سشن تازه با پوشه‌ی درست باز کنید و دوباره همان پیام AGENTS.md را بدهید. سعی نکنید وسط یک سشن پروژه را عوض کنید؛ تمیز درنمی‌آید.

لیست مدل‌ها خالی است یا مدل خطا می‌دهد

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

ایجنت AGENTS.md نساخت یا نصفه ساخت

گاهی مدل ضعیف روی پروژه‌ی بزرگ کم می‌آورد. یک مدل قوی‌تر انتخاب کنید، reasoning را یک پله بالا ببرید، و پیام را کمی مشخص‌تر کنید؛ مثلاً: «ساختار پوشه‌ها، نحوه‌ی اجرا و تست، و قراردادهای کدنویسی را در AGENTS.md بنویس».

جمع‌بندی

تمام شد. پروژه را به آشاکد اضافه کردید، یاد گرفتید مدل را از لیست چت انتخاب کنید، فهمیدید reasoning را کی بالا و کی پایین ببرید، فرق plan و build را می‌دانید، و مهم‌تر از همه، با یک پیام ساده یک فایل AGENTS.md ساختید که از اینجا به بعد دستیار همیشگی ایجنت شماست. قدم بعدی؟ یک تسک کوچک واقعی به ایجنت بدهید — مثلاً «یک تست برای فلان تابع اضافه کن» — و ببینید چقدر فرق می‌کند وقتی ایجنت پروژه را می‌شناسد. و اگر فردا برگشتید، با دکمه‌ی Home یا Ctrl + B سر همان گفت‌وگو برگردید و ادامه‌اش بدهید؛ لازم نیست چیزی را از اول توضیح بدهید. برای انتخاب مدل‌های بعدی هم سری به صفحه مدل‌های آشا بزنید و قیمت‌ها را مقایسه کنید.