آموزش و راهنما

پرامپت‌نویسی برای برنامه‌نویسی با هوش مصنوعی؛ آموزش کامل همراه با مثال

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

کیفیت کدی که از هوش مصنوعی دریافت می‌کنید فقط به قدرت مدل وابسته نیست. نحوه تعریف مسئله، Context پروژه، محدودیت‌ها، معیار پذیرش و روش ارزیابی خروجی نیز تأثیر مستقیمی بر نتیجه دارد.

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

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

در این مقاله یاد می‌گیرید:

پرامپت برنامه‌نویسی چیست؟
یک پرامپت کدنویسی حرفه‌ای چه اجزایی دارد؟
چگونه برای Coding Agentها دستور بنویسیم؟
چگونه از هوش مصنوعی برای تولید کد، Debug و تست استفاده کنیم؟
چه اطلاعاتی را باید به مدل بدهیم؟
چگونه خروجی مدل را ارزیابی کنیم؟
چگونه یک دستیار برنامه‌نویسی با API درواره بسازیم؟

پرامپت برنامه‌نویسی چیست؟

پرامپت برنامه‌نویسی دستوری است که یک مسئله نرم‌افزاری را برای مدل هوش مصنوعی تعریف می‌کند.

این دستور ممکن است برای یکی از وظایف زیر نوشته شود:

تولید یک تابع
ساخت API
ایجاد رابط کاربری
توضیح کد
رفع خطا
نوشتن تست
بازآرایی کد
بهینه‌سازی Query
تبدیل زبان برنامه‌نویسی
بررسی Pull Request
تولید مستندات
طراحی ساختار پروژه
مهاجرت به نسخه جدید یک کتابخانه

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

چرا پرامپت‌های کوتاه معمولاً کد ضعیف‌تری تولید می‌کنند؟

فرض کنید این درخواست را به مدل می‌دهید:

یک API ثبت‌نام کاربر بنویس.

مدل برای پاسخ باید موارد زیادی را حدس بزند:

زبان برنامه‌نویسی چیست؟
از چه فریم‌ورکی استفاده شود؟
پایگاه داده چیست؟
رمز عبور چگونه ذخیره شود؟
فیلدهای ورودی کدام‌اند؟
ایمیل تکراری چه خطایی برگرداند؟
قرارداد پاسخ چیست؟
پروژه چه معماری‌ای دارد؟
چه تست‌هایی لازم است؟
آیا کتابخانه جدید مجاز است؟

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

نسخه بهتر:

در پروژه FastAPI موجود، Endpoint ثبت‌نام کاربر را پیاده‌سازی کن.

مسیر:
POST /api/v1/users/register

ورودی:
- email: ایمیل معتبر
- password: حداقل ۸ نویسه
- full_name: بین ۲ تا ۱۰۰ نویسه

رفتار مورد انتظار:
- ایمیل پیش از ذخیره trim و lowercase شود.
- اگر ایمیل قبلاً وجود دارد، پاسخ 409 برگردد.
- رمز عبور با تابع hash_password موجود هش شود.
- پاسخ موفق شامل id، email و full_name باشد.
- رمز عبور یا password_hash در پاسخ نمایش داده نشود.

محدودیت‌ها:
- از Repository و Serviceهای موجود استفاده کن.
- Route مستقیماً با Database کار نکند.
- کتابخانه جدید اضافه نکن.
- Migration ایجاد نکن.

معیار پذیرش:
- تست ثبت‌نام موفق
- تست ایمیل تکراری
- تست رمز کوتاه
- اجرای موفق pytest و ruff

ابتدا فایل‌های مرتبط را بررسی و Plan ارائه کن.
تا قبل از تأیید من هیچ فایلی را تغییر نده.

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

اجزای یک پرامپت حرفه‌ای برای کدنویسی

یک پرامپت حرفه‌ای معمولاً از هشت بخش تشکیل می‌شود.

بخش	پرسشی که پاسخ می‌دهد
هدف	دقیقاً چه نتیجه‌ای می‌خواهیم؟
Context	پروژه اکنون چگونه کار می‌کند؟
محدوده	کدام فایل‌ها یا بخش‌ها قابل تغییرند؟
رفتار مورد انتظار	خروجی صحیح چگونه رفتار می‌کند؟
محدودیت‌ها	مدل چه کاری نباید انجام دهد؟
معیار پذیرش	از کجا بفهمیم کار کامل شده است؟
روش اعتبارسنجی	چه تست یا دستوری باید اجرا شود؟
شکل گزارش	مدل در پایان چه اطلاعاتی بدهد؟

هدف

هدف باید نتیجه موردنظر را به‌صورت روشن تعریف کند:

هدف: اضافه‌کردن جست‌وجوی صفحه‌بندی‌شده محصولات به API موجود.

هدف مبهم:

جست‌وجوی سایت را بهتر کن.

Context

Context اطلاعاتی است که مدل برای درک وضعیت فعلی نیاز دارد:

پروژه با Python 3.12، FastAPI، SQLAlchemy 2 و PostgreSQL ساخته شده است.
Routeها در app/api، منطق کسب‌وکار در app/services و Queryها در
app/repositories قرار دارند.

محدوده تغییر

مشخص کنید مدل کجا می‌تواند تغییر ایجاد کند:

فقط فایل‌های زیر قابل تغییرند:
- app/api/products.py
- app/services/product_service.py
- app/repositories/products.py
- tests/test_product_search.py

اگر هنوز فایل‌ها را نمی‌شناسید:

ابتدا فایل‌های مرتبط را پیدا کن و قبل از هر تغییری فهرست آن‌ها را گزارش بده.

رفتار مورد انتظار

رفتار را از دید کاربر یا مصرف‌کننده API تعریف کنید:

اگر q کمتر از دو نویسه باشد، پاسخ 422 برگردد.
محصول غیرفعال نباید در نتایج نمایش داده شود.
نتایج بر اساس relevance و سپس created_at مرتب شوند.

محدودیت‌ها

محدودیت‌ها جلوی تغییرات غیرضروری را می‌گیرند:

- Dependency جدید اضافه نکن.
- قرارداد Endpointهای فعلی را تغییر نده.
- Migration نساز.
- نام فیلدهای موجود را تغییر نده.
- کد نامرتبط را Refactor نکن.

بهتر است محدودیت‌ها مشخص و قابل بررسی باشند. عبارت‌هایی مانند «هیچ اشتباهی نکن» کاربرد عملی ندارند.

معیار پذیرش

معیار پذیرش باید قابل آزمایش باشد:

کار زمانی کامل است که:
- تست‌های جدید نوشته شده باشند.
- تمام تست‌های products پاس شوند.
- Type Check بدون خطا اجرا شود.
- API قبلی تغییری نکرده باشد.

روش اعتبارسنجی

دستورهای دقیق پروژه را ارائه کنید:

pytest tests/products -q
ruff check app tests
mypy app

برای JavaScript:

npm run lint
npm run typecheck
npm test
npm run build

شکل گزارش نهایی

از مدل بخواهید نتیجه را خلاصه کند:

در پایان فقط این موارد را گزارش بده:
1. علت مسئله
2. فایل‌های تغییرکرده
3. خلاصه تغییر هر فایل
4. تست‌های اجراشده و نتیجه آن‌ها
5. ریسک یا محدودیت باقی‌مانده

قالب استاندارد پرامپت برنامه‌نویسی

قالب زیر را می‌توانید برای بیشتر وظایف توسعه استفاده کنید:

## هدف

[نتیجه دقیق موردنظر]

## وضعیت فعلی

[معماری، زبان، فریم‌ورک و رفتار فعلی]

## رفتار مورد انتظار

- [رفتار اول]
- [رفتار دوم]
- [رفتار سوم]

## محدوده تغییر

- [فایل یا ماژول مجاز]
- [فایل یا ماژول مجاز]

## محدودیت‌ها

- [کار غیرمجاز]
- [قراردادی که نباید تغییر کند]
- [وابستگی یا الگوی ممنوع]

## معیار پذیرش

- [نتیجه قابل‌اندازه‌گیری]
- [تست موردنیاز]
- [رفتار Edge Case]

## اعتبارسنجی

این دستورات را اجرا کن:
- [فرمان Build]
- [فرمان Lint]
- [فرمان Test]

## نحوه اجرا

ابتدا پروژه را بررسی کن و یافته‌ها و Plan را ارائه بده.
تا قبل از تأیید من کدی را تغییر نده.
پس از تأیید، کمترین تغییر لازم را اعمال کن.
در پایان Git Diff و نتیجه تست‌ها را خلاصه کن.

این قالب برای ChatGPT، OpenCode، Cline، Aider، Continue، Claude Code، Codex و سایر Coding Agentها قابل استفاده است.

پرامپت‌نویسی برای Chat با پرامپت‌نویسی برای Agent چه تفاوتی دارد؟

مدل داخل یک چت معمولی معمولاً امکان خواندن فایل، اجرای تست یا تغییر Repository را ندارد. بنابراین باید کد مرتبط را داخل پیام قرار دهید.

Coding Agent می‌تواند به ابزارهای زیر دسترسی داشته باشد:

خواندن فایل
جست‌وجو در پروژه
ویرایش کد
اجرای ترمینال
مشاهده Git Diff
اجرای تست
استفاده از مرورگر
ارتباط با MCP Server

به همین دلیل پرامپت Agent باید سطح اختیار و نقطه توقف را نیز تعیین کند.

پرامپت مناسب برای چت‌بات

کد زیر را بررسی کن و فقط علت خطا را توضیح بده.
نسخه اصلاح‌شده تابع را نیز به‌صورت یک Code Block کامل ارائه کن.

[CODE]

پرامپت مناسب برای Coding Agent

خطای ثبت‌شده در Issue شماره ۱۲۸ را در محیط محلی بازتولید کن.

مراحل:
1. فایل‌های مرتبط را پیدا کن.
2. تست شکست‌خورده را اجرا کن.
3. علت ریشه‌ای را توضیح بده.
4. کوچک‌ترین اصلاح ممکن را اعمال کن.
5. تست مرتبط را اجرا کن.
6. Git Diff را بررسی کن.

محدودیت:
- Dependency جدید اضافه نکن.
- تست موجود را حذف یا ضعیف نکن.
- فایل‌های نامرتبط را تغییر نده.
- هیچ Commit یا Push انجام نده.

بهترین پرامپت‌ها برای برنامه‌نویسی با هوش مصنوعی

پرامپت شناخت پروژه

هنگامی که وارد یک پروژه جدید می‌شوید:

این Repository را بررسی کن، اما هیچ تغییری ایجاد نکن.

در پاسخ موارد زیر را توضیح بده:
1. هدف کلی پروژه
2. زبان‌ها و فریم‌ورک‌های اصلی
3. نقطه ورود برنامه
4. ساختار پوشه‌ها
5. مسیر یک درخواست از ورودی تا Database
6. روش مدیریت Configuration
7. روش اجرای Build، Lint و Test
8. بخش‌هایی که برای یک توسعه‌دهنده جدید مبهم یا پرریسک‌اند

برای هر ادعا، مسیر فایل مرتبط را ذکر کن.
اگر چیزی را از روی کد نمی‌توانی اثبات کنی، آن را به‌عنوان فرض بنویس.

پرامپت پیدا کردن فایل‌های مرتبط

می‌خواهم قابلیت بازیابی رمز عبور را تغییر دهم.

قبل از هر تغییری تمام فایل‌های مرتبط را پیدا کن:
- Route
- Schema
- Service
- Repository
- Email Template
- Token Logic
- Configuration
- Unit Test
- Integration Test

ارتباط این فایل‌ها را توضیح بده و مشخص کن تغییر احتمالی در هرکدام چیست.
هنوز کدی تولید یا ویرایش نکن.

پرامپت طراحی قابلیت جدید

برای اضافه‌کردن قابلیت «ذخیره محصول در علاقه‌مندی‌ها» یک Plan فنی بنویس.

نیازمندی‌ها:
- کاربر باید وارد حساب شده باشد.
- یک محصول فقط یک بار ذخیره شود.
- امکان حذف از علاقه‌مندی وجود داشته باشد.
- فهرست علاقه‌مندی‌ها صفحه‌بندی شود.
- محصول حذف‌شده در پاسخ نمایش داده نشود.

Plan باید شامل این موارد باشد:
- تغییرات Database
- Endpointها
- Schemaهای ورودی و خروجی
- منطق Service
- مجوز دسترسی
- تست‌ها
- ترتیب اجرای تغییرات
- ریسک‌های مهاجرت

فعلاً هیچ فایل یا Migration ایجاد نکن.

پرامپت تولید تابع

یک تابع TypeScript برای محاسبه قیمت نهایی سفارش بنویس.

ورودی:
- subtotal: number
- discountPercent: number
- taxPercent: number

قواعد:
- تمام مبالغ بر حسب ریال‌اند.
- discountPercent بین ۰ تا ۱۰۰ باشد.
- taxPercent نمی‌تواند منفی باشد.
- ابتدا تخفیف و سپس مالیات محاسبه شود.
- نتیجه به نزدیک‌ترین عدد صحیح گرد شود.
- در ورودی نامعتبر خطای TypeError ایجاد شود.
- تابع Pure باشد.

خروجی:
{
  subtotal: number,
  discountAmount: number,
  taxableAmount: number,
  taxAmount: number,
  total: number
}

همراه تابع، تست‌های Vitest برای حالت عادی، بدون تخفیف،
تخفیف کامل و ورودی نامعتبر بنویس.

پرامپت ساخت REST API

در پروژه NestJS موجود یک Endpoint برای تغییر وضعیت سفارش ایجاد کن.

مسیر:
PATCH /api/orders/:id/status

ورودی:
{
  "status": "processing | shipped | delivered | cancelled"
}

قواعد:
- فقط کاربر دارای نقش admin یا operator مجاز است.
- وضعیت delivered قابل بازگشت نیست.
- سفارش cancelled قابل تغییر نیست.
- وضعیت جدید در جدول order_events ثبت شود.
- پاسخ با DTOهای فعلی سازگار باشد.

محدودیت‌ها:
- Controller مستقیماً با Prisma کار نکند.
- از Guard موجود استفاده کن.
- Dependency جدید اضافه نکن.
- نام جدول یا Enum موجود را تغییر نده.

تست‌ها:
- تغییر موفق
- کاربر غیرمجاز
- سفارش ناموجود
- تغییر وضعیت delivered
- تغییر سفارش cancelled

ابتدا نمونه مشابه موجود را پیدا و Plan ارائه کن.

پرامپت ساخت Component در React

یک Component قابل استفاده مجدد برای نمایش وضعیت Job تولید ویدئو بساز.

فناوری:
- React 19
- TypeScript
- Tailwind CSS
- TanStack Query

Props:
- jobId: string
- onCompleted(videoUrl: string): void
- onFailed(message: string): void

رفتار:
- هر ۵ ثانیه وضعیت را از GET /api/videos/:id دریافت کند.
- در وضعیت completed، Polling متوقف شود.
- در وضعیت failed، پیام خطا نمایش داده شود.
- هنگام Unmount درخواست‌ها متوقف شوند.
- درصد پیشرفت فقط در صورت وجود نمایش داده شود.
- رابط RTL و قابل استفاده با Keyboard باشد.

خروجی:
1. Component کامل
2. Hook موردنیاز
3. تست‌های اصلی
4. توضیح کوتاه درباره توقف Polling

پرامپت تولید فرم

با React Hook Form و Zod یک فرم ثبت محصول بساز.

فیلدها:
- name: بین ۳ تا ۱۰۰ نویسه
- price: عدد مثبت
- stock: عدد صحیح صفر یا بیشتر
- description: حداکثر ۲۰۰۰ نویسه
- categoryId: الزامی

رفتار:
- خطاها به فارسی نمایش داده شوند.
- فرم RTL باشد.
- هنگام ارسال دکمه غیرفعال شود.
- از ارسال دوباره جلوگیری شود.
- خطای 422 سرور کنار فیلد مربوط نمایش داده شود.
- بعد از موفقیت فرم پاک نشود و کاربر به صفحه جزئیات هدایت شود.

از Componentهای موجود پروژه استفاده کن و Style System جدید نساز.

پرامپت‌های رفع خطا و Debugging

پرامپت استاندارد رفع خطا

خطای زیر را بررسی کن:

[ERROR OR STACK TRACE]

قبل از تغییر کد:
1. محل دقیق وقوع خطا را پیدا کن.
2. شرایط بازتولید را مشخص کن.
3. علت ریشه‌ای را از نشانه‌های ثانویه جدا کن.
4. فایل‌های مرتبط را فهرست کن.
5. کوچک‌ترین اصلاح ممکن را پیشنهاد بده.

پس از تأیید:
- یک تست ایجاد کن که قبل از اصلاح شکست بخورد.
- اصلاح را اعمال کن.
- همان تست و تست‌های مرتبط را اجرا کن.
- تست را برای عبور مصنوعی ضعیف نکن.

پرامپت خطای Frontend

در صفحه ویرایش کاربر، بعد از ذخیره موفق، اطلاعات قدیمی تا زمان Refresh
نمایش داده می‌شود.

پروژه از React، TypeScript و TanStack Query استفاده می‌کند.

بررسی کن:
- Query Key
- Mutation
- Cache Invalidation
- Optimistic Update
- داده اولیه فرم
- زمان Reset شدن فرم

ابتدا علت را با اشاره به فایل و جریان داده توضیح بده.
سپس کوچک‌ترین اصلاح سازگار با الگوی فعلی پروژه را انجام بده.
تست رفتاری برای نمایش داده جدید اضافه کن.

پرامپت خطای Backend

Endpoint زیر در برخی درخواست‌ها پاسخ 500 می‌دهد:

POST /api/orders

Stack Trace:
[STACK TRACE]

نمونه ورودی شکست‌خورده:
[REQUEST BODY]

نمونه ورودی موفق:
[REQUEST BODY]

ابتدا تفاوت دو ورودی را تحلیل کن.
مسیر درخواست از Route تا Database را دنبال کن.
حدس تأییدنشده را به‌عنوان واقعیت گزارش نکن.
پس از یافتن علت، Regression Test و کوچک‌ترین اصلاح را ایجاد کن.

پرامپت خطای SQL

Query زیر در داده‌های زیاد کند شده است:

[QUERY]

Schema جدول‌ها:
[SCHEMA]

خروجی EXPLAIN ANALYZE:
[OUTPUT]

این موارد را بررسی کن:
- Sequential Scan
- Indexهای موجود
- ترتیب شرط‌ها
- Joinها
- Sort
- Pagination
- تعداد ردیف تخمینی و واقعی

ابتدا علت را توضیح بده.
سپس Query و Index پیشنهادی را جداگانه ارائه کن.
تأثیر منفی احتمالی Index روی Write را نیز توضیح بده.

پرامپت‌های تست نرم‌افزار

تولید Unit Test

برای تابع زیر Unit Test بنویس:

[FUNCTION]

Framework تست: pytest

سناریوها:
- مسیر عادی
- مقدار مرزی
- ورودی خالی
- ورودی نامعتبر
- خطای Dependency
- نتیجه غیرمنتظره Dependency

قواعد:
- رفتار عمومی تابع را تست کن.
- به جزئیات داخلی وابسته نشو.
- فقط مرزهای خارجی را Mock کن.
- تست‌ها مستقل و قابل تکرار باشند.
- برای هر تست نام توصیفی انتخاب کن.

تولید Integration Test

برای Endpoint ثبت سفارش Integration Test بنویس.

موارد لازم:
- Database آزمایشی واقعی
- ثبت سفارش موفق
- محصول ناموجود
- موجودی ناکافی
- کاربر احرازنشده
- جلوگیری از سفارش تکراری با idempotency key
- بررسی ایجاد Order و OrderItem
- Rollback داده بعد از هر تست

Mock فقط برای درگاه پرداخت مجاز است.
Repository و Service را Mock نکن.

بررسی کیفیت تست‌های موجود

فایل‌های تست این ماژول را بررسی کن، اما فعلاً تغییر نده.

مشخص کن:
- کدام رفتارهای اصلی پوشش ندارند؟
- کدام تست فقط پیاده‌سازی داخلی را بررسی می‌کند؟
- کدام Mock بیش از حد گسترده است؟
- کدام Assertion ضعیف است؟
- آیا تستی بدون بررسی نتیجه پاس می‌شود؟
- آیا حالت خطا و Boundary پوشش داده شده است؟

یافته‌ها را بر اساس اهمیت مرتب کن و برای هر مورد یک تست پیشنهادی بنویس.

پرامپت‌های Refactoring

بازآرایی تابع بزرگ

تابع process_payment بیش از ۲۵۰ خط دارد.

هدف:
- کاهش پیچیدگی
- جداسازی اعتبارسنجی، قیمت‌گذاری، پرداخت و ثبت نتیجه
- حفظ کامل رفتار فعلی

مراحل:
1. ابتدا رفتارهای قابل مشاهده تابع را استخراج کن.
2. Characterization Test بنویس.
3. نقاط جداسازی را پیشنهاد بده.
4. Refactor را در چند مرحله کوچک اجرا کن.
5. بعد از هر مرحله تست‌ها را اجرا کن.

محدودیت:
- Signature عمومی تابع تغییر نکند.
- نوع خطاها تغییر نکند.
- Dependency جدید اضافه نشود.
- Refactor با تغییر رفتار ترکیب نشود.

حذف کد تکراری

در فایل‌های زیر منطق اعتبارسنجی شماره موبایل تکرار شده است:

[FILES]

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

قبل از Refactor، تست‌های موجود را بررسی کن.
پس از تغییر، تمام مصرف‌کنندگان تابع را پیدا و تست کن.
نام یا قرارداد عمومی APIها را تغییر نده.

بازآرایی کد Legacy

این ماژول Legacy فاقد تست است و چند بخش دیگر پروژه به آن وابسته‌اند.

هدف نهایی:
[GOAL]

فعلاً قابلیت جدید اضافه نکن.

ابتدا:
- ورودی‌ها و خروجی‌های عمومی را مشخص کن.
- Side Effectها را پیدا کن.
- وابستگی‌های بیرونی را فهرست کن.
- Characterization Test طراحی کن.
- بخش‌های پرریسک را مشخص کن.

سپس یک Plan مرحله‌ای ارائه بده که در هر Commit رفتار قبلی حفظ شود.

پرامپت‌های Code Review

بررسی Pull Request

Git Diff فعلی را مانند یک Senior Developer بررسی کن.

تمرکز:
- صحت منطق
- Edge Caseها
- سازگاری با معماری
- مدیریت خطا
- تغییر ناخواسته قرارداد API
- Queryهای پرهزینه
- Race Condition
- تست‌های ناکافی
- کد تکراری
- پیچیدگی غیرضروری

برای هر یافته بنویس:
- شدت: Blocker، High، Medium یا Low
- فایل و محل
- دلیل فنی
- سناریوی شکست
- اصلاح پیشنهادی

موارد صرفاً سلیقه‌ای را از ایرادهای واقعی جدا کن.
هیچ فایلی را تغییر نده.

بررسی تغییرات تولیدشده توسط هوش مصنوعی

تغییرات فعلی توسط یک Coding Agent ایجاد شده‌اند.

بررسی کن آیا Agent:
- فایل نامرتبطی را تغییر داده است.
- تست را برای عبور کد ضعیف کرده است.
- رفتار موجود را بدون درخواست تغییر داده است.
- Dependency غیرضروری اضافه کرده است.
- کد موقت یا TODO باقی گذاشته است.
- خطا را پنهان کرده است.
- API یا Schema را ناخواسته تغییر داده است.
- ادعای اجرای تست بدون شواهد دارد.

فقط بر اساس Git Diff و فایل‌های پروژه نتیجه‌گیری کن.

پرامپت‌های مستندسازی

تولید README

بر اساس کد واقعی پروژه، README را تکمیل کن.

بخش‌ها:
- معرفی پروژه
- پیش‌نیازها
- نصب
- متغیرهای محیطی بدون مقدار حساس
- اجرای Development
- اجرای تست
- Build
- ساختار پوشه‌ها
- Endpointهای اصلی
- خطاهای رایج

هیچ فرمان یا قابلیتی را حدس نزن.
هر فرمان باید از package.json، Makefile یا فایل‌های پروژه قابل اثبات باشد.

تولید مستندات API

برای Endpoint زیر مستندات فنی بنویس:

[ROUTE OR CODE]

شامل:
- Method و Path
- هدف
- احراز هویت
- پارامترهای مسیر
- Query Parameterها
- Body
- نمونه درخواست
- نمونه پاسخ موفق
- خطاهای ممکن
- محدودیت نرخ
- نکات Idempotency

مقادیر و Status Codeها را فقط از روی کد استخراج کن.

پرامپت‌های Docker و استقرار

تولید Dockerfile

برای این پروژه FastAPI یک Dockerfile چندمرحله‌ای Production بنویس.

نیازمندی:
- Python 3.12
- نصب وابستگی از requirements.txt
- اجرای برنامه با کاربر غیر root
- عدم کپی فایل‌های .env و تست
- Health Check
- حداقل حجم منطقی Image
- اجرای Uvicorn روی پورت 8000

ابتدا ساختار پروژه و دستور اجرای فعلی را بررسی کن.
فایل .dockerignore نیز ایجاد کن.
پس از ساخت، دستور docker build را اجرا و نتیجه را گزارش بده.

تولید GitHub Actions

یک Workflow برای Pull Request ایجاد کن.

مراحل:
- نصب Node.js مطابق نسخه پروژه
- Cache وابستگی‌ها
- npm ci
- Lint
- Type Check
- Unit Test
- Build

محدودیت:
- Secret جدید تعریف نکن.
- Deploy انجام نده.
- Permissionها را حداقلی نگه دار.
- نسخه Node را از فایل موجود پروژه استخراج کن.

استفاده از نمونه ورودی و خروجی در پرامپت

مستندات رسمی GitHub پیشنهاد می‌کنند برای روشن‌ترشدن درخواست، نمونه ورودی، خروجی یا پیاده‌سازی مورد انتظار ارائه شود.

برای مثال:

تابعی برای تبدیل وضعیت سفارش به برچسب فارسی بنویس.

نمونه‌ها:
pending → در انتظار بررسی
processing → در حال پردازش
shipped → ارسال‌شده
delivered → تحویل‌شده
cancelled → لغوشده

ورودی ناشناخته:
unknown → وضعیت نامشخص

خروجی فقط string باشد.

نمونه‌ها ابهام را کاهش می‌دهند؛ اما باید حالت‌های مرزی و رفتار نامعتبر نیز مشخص شوند.

چگونه Context مناسب در اختیار مدل قرار دهیم؟

Context بیشتر همیشه به معنی نتیجه بهتر نیست. هدف، ارائه اطلاعات مرتبط است.

اطلاعات مفید عبارت‌اند از:

فایل فعلی
Interface یا Typeهای مرتبط
تست موجود
Error Message
Stack Trace
Schema پایگاه داده
قرارداد API
نمونه مشابه در پروژه
نسخه زبان و کتابخانه
دستور Build و Test
قواعد معماری

اطلاعات نامرتبط می‌تواند توجه مدل را از مسئله اصلی منحرف و هزینه را افزایش دهد.

Context نامناسب

تمام Repository را بخوان و این تابع را اصلاح کن.

Context هدفمند

مشکل در محاسبه تخفیف است.

ابتدا این فایل‌ها را بررسی کن:
- src/pricing/calculateDiscount.ts
- src/pricing/types.ts
- tests/pricing/calculateDiscount.test.ts

اگر وابستگی مرتبط دیگری پیدا کردی، پیش از خواندن آن دلیل ارتباط را توضیح بده.

استفاده از فایل دستور دائمی پروژه

به‌جای تکرار قواعد در تمام پرامپت‌ها، آن‌ها را در فایل‌هایی مانند AGENTS.md ذخیره کنید.

نمونه:

# Project Instructions

## Stack

- Node.js 22
- TypeScript
- NestJS
- Prisma
- PostgreSQL
- Vitest

## Architecture

- Controllers only handle HTTP concerns.
- Business logic belongs in Services.
- Database access goes through Repositories.
- Public responses use DTOs.

## Commands

- Lint: `npm run lint`
- Type check: `npm run typecheck`
- Test: `npm test`
- Build: `npm run build`

## Rules

- Do not add dependencies without approval.
- Do not change public API contracts without approval.
- Add a regression test for every bug fix.
- Prefer the smallest correct change.
- Do not edit generated files.
- Ask before running destructive commands.

سپس در پرامپت می‌توان نوشت:

این وظیفه را مطابق قواعد AGENTS.md انجام بده.

برای مطالعه بیشتر به مقاله AGENTS.md چیست؟ مراجعه کنید.

ساخت دستیار تولید پرامپت برنامه‌نویسی با API درواره

می‌توان یک ابزار داخلی ساخت که توضیح کوتاه توسعه‌دهنده را به یک Ticket فنی ساختاریافته تبدیل کند.

نصب کتابخانه‌ها

pip install openai pydantic python-dotenv

فایل .env:

DARVAREH_API_KEY=YOUR_DARVAREH_API_KEY
DARVAREH_MODEL=kwaipilot/kat-coder-pro-v2.5

کد Python

import os
from typing import Literal

from dotenv import load_dotenv
from openai import OpenAI
from pydantic import BaseModel, Field

load_dotenv()

client = OpenAI(
    api_key=os.environ["DARVAREH_API_KEY"],
    base_url="https://api.darvareh.ir/v1",
)


class AcceptanceCriterion(BaseModel):
    description: str
    verification: str


class CodingTask(BaseModel):
    title: str
    task_type: Literal[
        "feature",
        "bugfix",
        "refactor",
        "test",
        "documentation",
    ]
    goal: str
    current_behavior: str | None
    expected_behavior: list[str]
    constraints: list[str]
    likely_files: list[str]
    acceptance_criteria: list[AcceptanceCriterion]
    validation_commands: list[str]
    unanswered_questions: list[str]
    agent_prompt: str = Field(
        description="پرامپت نهایی قابل ارسال به Coding Agent"
    )


def create_coding_prompt(
    request: str,
    project_context: str,
) -> CodingTask:
    response = client.chat.completions.create(
        model=os.environ["DARVAREH_MODEL"],
        temperature=0.1,
        response_format={"type": "json_object"},
        messages=[
            {
                "role": "system",
                "content": """
شما تحلیلگر ارشد نیازمندی نرم‌افزار هستید.

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

قواعد:
- اطلاعات موجود را تکرار کنید، اما چیزی را حدس نزنید.
- ابهام‌ها را در unanswered_questions قرار دهید.
- معیارهای پذیرش باید قابل آزمایش باشند.
- محدودیت‌های معماری پروژه را حفظ کنید.
- agent_prompt باید شامل هدف، Context، رفتار مورد انتظار،
  محدودیت‌ها، معیار پذیرش و دستورهای اعتبارسنجی باشد.
- خروجی فقط JSON معتبر باشد.
""",
            },
            {
                "role": "user",
                "content": f"""
درخواست خام:
{request}

Context پروژه:
{project_context}

ساختار JSON باید با این فیلدها سازگار باشد:
- title
- task_type
- goal
- current_behavior
- expected_behavior
- constraints
- likely_files
- acceptance_criteria
- validation_commands
- unanswered_questions
- agent_prompt
""",
            },
        ],
    )

    content = response.choices[0].message.content

    if not content:
        raise ValueError("پاسخی از مدل دریافت نشد.")

    return CodingTask.model_validate_json(content)


task = create_coding_prompt(
    request=(
        "جست‌وجوی محصول اضافه کن. محصول غیرفعال نشان داده نشود "
        "و نتایج صفحه‌بندی شوند."
    ),
    project_context="""
Python 3.12
FastAPI
SQLAlchemy 2
PostgreSQL
Routes: app/api
Services: app/services
Repositories: app/repositories
Tests: pytest
Lint: ruff check .
""",
)

print(task.agent_prompt)

این خروجی را می‌توان پس از بازبینی توسعه‌دهنده به OpenCode، Cline، Aider یا سایر Coding Agentها ارسال کرد.

چرا خروجی ساختاریافته مهم است؟

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

فیلدهای ضروری کنترل شوند.
ابهام‌ها جداگانه نمایش داده شوند.
معیارهای پذیرش استخراج شوند.
Prompt نهایی ذخیره و نسخه‌بندی شود.
خروجی نامعتبر قبل از استفاده رد شود.

برای آشنایی بیشتر می‌توانید مقاله Structured Outputs چیست؟ را مطالعه کنید.

انتخاب مدل مناسب برای پرامپت برنامه‌نویسی

برای وظایف مختلف می‌توان مدل‌های متفاوت انتخاب کرد.

وظیفه	ویژگی مهم
توضیح کد	سرعت و هزینه
تولید تابع	کیفیت Code Generation
Debug	استدلال و تحلیل خطا
Refactoring	Context و حفظ رفتار
Coding Agent	Tool Calling و پیروی از دستور
Code Review	دقت و تشخیص Edge Case
تولید تست	درک رفتار و حالت‌های مرزی
پروژه بزرگ	Context Management

شناسه مدل را در متغیر محیطی نگه دارید تا بدون تغییر کد قابل تعویض باشد:

DARVAREH_MODEL=YOUR_CODING_MODEL_ID

مدل‌های مختلف را روی مجموعه ثابتی از وظایف واقعی خود ارزیابی کنید. راهنمای انتخاب مدل برای Coding Agent روش مقایسه را توضیح می‌دهد.

اشتباهات رایج در پرامپت‌نویسی برای کدنویسی

درخواست بسیار کلی

پروژه را بهینه کن.

«بهینه‌سازی» می‌تواند به سرعت، خوانایی، مصرف حافظه یا ساختار معماری اشاره داشته باشد. معیار دقیق را مشخص کنید.

ترکیب چند وظیفه بزرگ

اضافه‌کردن قابلیت، Refactoring، ارتقای Dependency و بازطراحی رابط کاربری را در یک Prompt ترکیب نکنید.

ندادن معیار پذیرش

اگر مدل نداند موفقیت چگونه سنجیده می‌شود، ممکن است با تولید ظاهری کد، کار را کامل تلقی کند.

ندادن نمونه مشابه

اگر پروژه الگوی مشخصی دارد، مسیر نمونه را معرفی کنید:

Endpoint جدید را مطابق الگوی app/api/orders.py پیاده‌سازی کن.

اعتماد به ادعای مدل

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

درخواست بازنویسی کامل

برای رفع یک خطا معمولاً بازنویسی کامل ماژول لازم نیست. درخواست «کمترین تغییر صحیح» ریسک را کاهش می‌دهد.

محدودکردن بیش از حد روش حل

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

استفاده از Prompt ثابت برای تمام مدل‌ها

مدل‌ها از نظر Tool Calling، طول Context و نحوه پیروی از دستور متفاوت‌اند. Prompt پایه را حفظ و جزئیات آن را با مدل و ابزار تطبیق دهید.

چک‌لیست پرامپت برنامه‌نویسی

پیش از ارسال Prompt بررسی کنید:

هدف دقیق نوشته شده است.
زبان و فریم‌ورک مشخص‌اند.
رفتار فعلی توضیح داده شده است.
رفتار مورد انتظار قابل فهم است.
فایل‌ها یا ماژول‌های مرتبط معرفی شده‌اند.
محدودیت تغییر مشخص است.
قراردادهایی که نباید تغییر کنند نوشته شده‌اند.
Edge Caseها ذکر شده‌اند.
معیار پذیرش قابل آزمایش است.
دستور Build و Test مشخص است.
سطح اختیار Agent تعیین شده است.
نقطه توقف برای تأیید انسان وجود دارد.
شکل گزارش نهایی مشخص شده است.

پرسش‌های متداول

بهترین پرامپت برای برنامه‌نویسی چیست؟

پرامپتی که هدف، Context، رفتار مورد انتظار، محدودیت‌ها، معیار پذیرش و روش تست را روشن کند. یک Prompt واحد برای تمام پروژه‌ها وجود ندارد.

چگونه از هوش مصنوعی بخواهیم کد دقیق‌تری بنویسد؟

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

آیا پرامپت فارسی برای کدنویسی مناسب است؟

بله. مدل‌های جدید می‌توانند دستور فارسی و کد انگلیسی را پردازش کنند. نام فنی فایل‌ها، توابع، Typeها و پیام خطا را بدون ترجمه وارد کنید.

برای رفع خطا چه اطلاعاتی به مدل بدهیم؟

پیام خطا، Stack Trace، شرایط بازتولید، ورودی شکست‌خورده، رفتار مورد انتظار، نسخه کتابخانه‌ها و فایل‌های مرتبط را ارائه کنید.

آیا باید کل پروژه را برای مدل ارسال کنیم؟

خیر. ابتدا Context مرتبط را انتخاب کنید. Coding Agent می‌تواند در صورت نیاز فایل‌های دیگر را جست‌وجو کند.

چگونه جلوی تغییرات اضافی مدل را بگیریم؟

محدوده فایل‌ها، عملیات غیرمجاز و عبارت «کمترین تغییر لازم» را در Prompt بنویسید و قبل از اعمال، Plan بخواهید.

آیا کد تولیدشده توسط هوش مصنوعی به تست نیاز دارد؟

بله. کد تولیدشده باید Build، Lint، Type Check و Test شود و Git Diff آن توسط توسعه‌دهنده بازبینی شود.

آیا می‌توان Promptهای برنامه‌نویسی را ذخیره کرد؟

بله. Promptهای پرتکرار را می‌توان در فایل، Template، دستور اختصاصی ابزار یا کتابخانه داخلی تیم ذخیره و نسخه‌بندی کرد.

آیا می‌توان دستیار کدنویسی اختصاصی ساخت؟

بله. با API مدل‌های هوش مصنوعی می‌توان ابزار تولید کد، تحلیل خطا، ساخت تست، بررسی Pull Request یا تبدیل نیازمندی به Ticket فنی ایجاد کرد.

چگونه از API درواره برای برنامه‌نویسی استفاده کنیم؟

یک کلید API بسازید، base_url را روی https://api.darvareh.ir/v1 قرار دهید و شناسه مدل کدنویسی موردنظر را ارسال کنید. API درواره با SDKهای سازگار با OpenAI قابل استفاده است.

جمع‌بندی

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

برای دریافت خروجی بهتر:

هدف را دقیق تعریف کنید.
Context مرتبط پروژه را ارائه دهید.
رفتار فعلی و مورد انتظار را جدا کنید.
محدوده تغییر را مشخص کنید.
محدودیت‌های معماری را بنویسید.
Edge Caseها را فراموش نکنید.
معیار پذیرش قابل آزمایش تعریف کنید.
دستورهای Build، Lint و Test را مشخص کنید.
ابتدا تحلیل و Plan بخواهید.
تغییرات را مرحله‌ای انجام دهید.
Git Diff را بازبینی کنید.
تست‌ها را مستقل از مدل اجرا کنید.

مدل هوش مصنوعی زمانی به یک همکار مؤثر برای برنامه‌نویس تبدیل می‌شود که مسئله دقیق، Context کافی و بازخورد قابل‌اندازه‌گیری داشته باشد.

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

مقالات مرتبط

منابع

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