آموزش جامع وایب کدینگ

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

تبارشناسی و ماهیت نظری وایب کدینگ

اصطلاح «وایب کدینگ» نخستین بار در اوایل فوریه ۲۰۲۵ توسط آندری کارپاتی (Andrej Karpathy)، از بنیان‌گذاران OpenAI و مدیر سابق هوش مصنوعی تسلا، بر سر زبان‌ها افتاد. کارپاتی با اشتراک‌گذاری ویدیویی از جریان کاری خود نشان داد که چگونه با ترکیب ابزار تایپ صوتی Superwhisper و محیط کدنویسی هوشمند Cursor، کدهای یک پروژه کامل را بدون لمس پی‌درپی کیبورد و تنها با هدایت صوتی پیش برده است.

این رویکرد تجسم عملی همان پیش‌بینی معروفی بود که کارپاتی در سال ۲۰۲۳ مطرح کرد: «داغ‌ترین زبان برنامه‌نویسی جدید، زبان انگلیسی است.» نفوذ این پدیده به قدری سریع و عمیق بود که در پایان سال ۲۰۲۵، فرهنگ لغت کالینز آن را به عنوان یکی از برجسته‌ترین مفاهیم فناوری معرفی کرد.

تفاوت بنیادین با برنامه‌نویسی سنتی، دستیارهای کد و ابزارهای بدون کد

برای درک درست وایب کدینگ، باید مفهوم «مالکیت مشخصات پیاده‌سازی» (Specification Ownership) را بررسی کنیم:

• در برنامه‌نویسی سنتی: توسعه‌دهنده هم معماری را در ذهن دارد و هم شخصاً تمام جزئیات نحوی را تایپ می‌کند.

• در ابزارهای تکمیل خودکار (مانند نسخه‌های اولیه Copilot): هوش مصنوعی صرفاً چند کلمه یا خط بعدی را حدس می‌زند، اما هدایت خط‌به‌خط کماکان بر دوش انسان است.

• در پلتفرم‌های بدون کد (No-Code): کاربر در محیط‌های گرافیکی و بسته محصور است و کدی در اختیار ندارد؛ بنابراین خروجی مستقل نیست و وابستگی شدید به ارائه‌دهنده سرویس (Vendor Lock-in) ایجاد می‌شود.

• در وایب کدینگ: شما قصد و منطق مدنظر را بیان می‌کنید، اما مدل در پس‌زمینه کدهای استاندارد، ماژولار و واقعی (مثل React، TypeScript، Python یا Go) تولید می‌کند که می‌توانید آن‌ها را به هر سروری منتقل کنید، در گیت نگه دارید و خط‌به‌خط بازبینی نمایید.

گذار از «پذیرش کورکورانه» به «مهندسی ایجنتیک»

رویکرد اولیه وایب کدینگ که بر پذیرش بی‌قیدوشرط تغییرات (Accept All) و نادیده‌گرفتن بازبینی کد استوار بود، تنها برای پروتوتایپ‌های تفریحی یا هکاتون‌های ۲۴ ساعته جواب می‌دهد. در نرم‌افزارهای تجاری و سازمانی، چنین رویکردی به سرعت به بن‌بست معماری و فجایع امنیتی ختم می‌شود.

از این رو، صنعت نرم‌افزار به سمت «مهندسی ایجنتیک» (Agentic Engineering) حرکت کرده است؛ پارادایمی که در آن مهندس نرم‌افزار نه یک تماشاگر منفعل، بلکه هدایت‌کننده ارتشی از ایجنت‌های تخصصی (معمار، توسعه‌دهنده، تستر و ممیز امنیتی) است.

جعبه‌ابزار وایب کدینگ: انتخاب محیط توسعه مناسب

محیط‌های توسعه وایب کدینگ به دو دسته عمده تقسیم می‌شوند: ویرایشگرهای بومی مبتنی بر دسکتاپ و پلتفرم‌های ابری در مرورگر.

راهبرد پیشنهادی: فاز ایده‌پردازی و آزمون اولیه پروتوتایپ را در ابزارهایی مانند Bolt.new یا Lovable استارت بزنید، اما به محض اعتبارسنجی ایده، مخزن را به گیت متصل کرده و توسعه اصلی و مقاوم‌سازی را درون Cursor یا Windsurf ادامه دهید.

مهندسی زمینه (Context Engineering) و ساختار پروژه

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

۱. تدوین سند مشخصات محصول (SPEC.md)

پیش از نوشتن اولین پرامپت کد، یک فایل به نام SPEC.md در ریشه پروژه بسازید. این سند باید شامل موارد زیر باشد:

• شرح مسئله و اهداف تجاری نرم‌افزار

• نهادهای دیتابیس و روابط میان آن‌ها

• چارچوب‌های احراز هویت و دسترسی کاربران

• قراردادهای سیستم طراحی (رنگ‌ها، تایپوگرافی، پدینگ‌ها)

• رفتارهای سیستمی و سناریوهای مدیریت خطا

این سند قطب‌نمای ایجنت در تمام طول پروژه است و از تصمیم‌گیری‌های سلیقه‌ای جلوگیری می‌کند.

۲. تکامل قوانین پروژه: از cursorrules. تا ساختار مدرن mdc.

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

امروزه استاندارد معماری بر استفاده از پوشه .cursor/rules/ و فایل‌های ماژولار .mdc متمرکز است. هر فایل .mdc با هدر متادیتای YAML تنظیم می‌شود و مشخص می‌کند که در چه شرایطی باید فعال شود:

1. اعمال دائمی (alwaysApply: true): قوانینی که در تمام درخواست‌ها بارگذاری می‌شوند (مانند استانداردهای عمومی کدنویسی). حجم این بخش نباید از ۲,۰۰۰ توکن بیشتر شود.

2. الگوی نام فایل‌ها (globs): فراخوانی شرطی قانون با باز شدن فایل‌های منطبق (مثلاً اعمال قوانین فقط روی فایل‌های مسیر src/app/api/**/*.ts).

3. تطبیق معنایی و هدف ایجنت (description): مدل بر اساس شرح وظیفه خود تشخیص می‌دهد که آیا به این فایل نیاز دارد یا خیر.

4. فراخوانی دستی: با نوشتن کاراکتر @ و انتخاب مستقیم نام فایل قانون در محیط چت.

علاوه بر این، در ابزارهای مبتنی بر ترمینال نظیر Claude Code از فایل CLAUDE.md و برای سازگاری هم‌زمان میان چندین ایجنت از استاندارد باز AGENTS.md استفاده می‌شود.

نمونه فایل استاندارد .cursor/rules/api-standards.mdc

--- description: قوانین لایه سرور، مدیریت خطا و استانداردهای اعتبارسنجی داده‌ها globs: ["src/server/**/*.ts", "src/app/api/**/*.ts"]
alwaysApply: false --- # استانداردهای پیاده‌سازی لایه سرور و کنترلرها - انطباق اکید با تایپ‌اسکریپت: کامپایلر باید در حالت Strict باشد. استفاده از نوع `any` اکیداً ممنوع است و تمامی ورودی‌ها و خروجی‌ها باید دارای اینترفیس صریح باشند. - اعتبارسنجی ورودی‌ها: تمام بدنه درخواست‌های ورودی (Request Body) باید از طریق شِمای Zod اعتبارسنجی شوند. - ساختار یکپارچه خطاها: تمامی پاسخ‌های خطای سرور باید فرمت یکدست زیر را دنبال کنند: `{ success: false, error: { code: string, message: string, details?: unknown } }` - جداسازی لایه منطق: کنترلرها فقط وظیفه دریافت، ولیدیشن و بازگرداندن پاسخ را دارند. کلیه منطق‌های محاسباتی و تراکنش‌ها باید در پوشه `src/server/services` مستقر شوند. - واکشی داده‌ها: استفاده از کوئری‌های عام مانند `SELECT *` مجاز نبوده و فقط باید فیلدهای مورد نیاز پروژه انتخاب گردند. 

چرخه عملیاتی پرامپت‌نویسی در وایب کدینگ (۴ فاز عملیاتی)

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

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

یکی از چالش‌های فرساینده در وایب کدینگ، «لوپ تکراری خطای هوش مصنوعی» است؛ وضعیتی که در آن یک باگ رخ می‌دهد، شما متن کامل ترمینال را در چت کپی می‌کنید، مدل سعی می‌کند آن را رفع کند اما با دستکاری فایل‌های مجاور، ۳ باگ جدید ایجاد می‌نماید! برای فرار از این چرخه، ۴ گام زیر را به خاطر بسپارید:

1. انضباط در کامیت‌های گیت (Micro-commits): پیش از محول کردن هر تسک جدید به ایجنت، کد را کامیت کنید. اگر ایجنت پس از ۲ بار تلاش نتوانست باگ را حل کند، ادامه ندهید! دستور git checkout . یا git reset را بزنید و به نقطه پایدار بازگردید.

2. شستشوی حافظه چت (Context Reset): چت‌های طولانی هوش مصنوعی را کند، کم‌دقت و مستعد توهم می‌کنند. وقتی گیر کردید، پنجره چت را ببندید، یک چت جدید باز کنید و صرفاً فایل SPEC.md و فایل معیوب را به آن ارجاع دهید.

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

import { describe, it, expect } from 'vitest';
import { evaluateTaskPriority } from './taskEngine';

describe('اعتبارسنجی تابع محاسبه اولویت', () => {
  it('در صورتی که مهلت تسک کمتر از ۲۴ ساعت باشد باید اولویت بحرانی برگرداند', () => {
    const mockDeadline = new Date(Date.now() + 12 * 3600 * 1000);
    const result = evaluateTaskPriority({ deadline: mockDeadline, isBlocked: false });
    expect(result).toBe('CRITICAL');
  });
});

4. پالایش لاگ‌های ترمینال: کل ۵۰۰ خط لاگ کنسول را برای هوش مصنوعی کپی نکنید. فقط پشته خطای اصلی (Stack Trace) و خطی که ارور در آن رخ داده را برای ایجنت ارسال نمایید.

تحلیل آسیب‌پذیری‌های امنیتی و بردار حمله نوظهور: اسلوپ‌اسکواتینگ (Slopsquatting)

وقتی کدهای تولیدشده توسط مدل‌های زبانی را بدون نظارت در محیط‌های واقعی استفاده می‌کنید، سیستم شما با مخاطرات جدی نظیر افشای کلیدهای API در فرانت‌اند، کوئری‌های فاقد اعتبارسنجی و پیکربندی سست دیتابیس روبه‌رو می‌شود. اما یک تهدید بسیار خطرناک‌تر در زنجیره تأمین نرم‌افزار وجود دارد: اسلوپ‌اسکواتینگ.

اسلوپ‌اسکواتینگ چیست؟

این واژه از تلفیق اصطلاحات AI Slop (محتوای نامرغوب هوش مصنوعی) و Typosquatting (سوءاستفاده از غلط‌های املایی انسان) پدید آمده است. مدل‌های هوش مصنوعی وقتی با یک پرامپت مواجه می‌شوند، بر اساس احتمالات آماری ممکن است نام پکیج‌هایی را اختراع کنند که وجود خارجی ندارند، اما اسامی آن‌ها بسیار منطقی به نظر می‌رسد (توهم بسته‌های نرم‌افزاری).

مهاجمان با ارسال پرامپت‌های گسترده به مدل‌های هوش مصنوعی، اسامی بسته‌های توهم‌شده پرتکرار را شناسایی کرده و سپس پکیج‌های مخربی با همان نام‌ها در مخازن عمومی مانند npm یا PyPI ثبت می‌کنند! زمانی که یک وایب‌کدر بدون تحقیق دستور پیشنهادی ترمینال را اجرا می‌کند، در حقیقت اسکریپت آلوده مهاجم را در محیط سیستم خود اجرا کرده است.

بررسی صدها هزار قطعه کد تولیدشده توسط هوش مصنوعی نشان می‌دهد که مدل‌ها بیش از ۲۰۰,۰۰۰ بسته موهوم تولید کرده‌اند. با توجه به تکرارپذیری ۴۳ درصدی این بسته‌ها، هکرها به راحتی بسته‌های جعلی را آماده کرده و منتظر می‌مانند تا کاربران دستور npm install یا pip install را بدون بازبینی اجرا کنند.

راهکار مقابله: استراتژی دفاع در عمق

• سلب اختیار اجرای خودکار از ایجنت: اجازه ندهید ابزارهایی مانند Cursor یا Claude Code پکیج‌ها را بدون اجازه شما از ترمینال نصب کنند.

• فایروال پکیج‌ها (مانند SafeChain): ابزارهایی را به کار بگیرید که تاریخ ثبت پکیج، تعداد دانلودها و هویت نویسنده را بررسی می‌کنند و مانع از دانلود بسته‌هایی با طول عمر کمتر از چند هفته می‌شوند.

• بررسی دستی در npm: هر کتابخانه ناآشنایی که مدل پیشنهاد می‌دهد را ابتدا در سایت رسمی پکیج‌منیجر جستجو کنید.

• قفل‌گذاری هش‌ها: همیشه از فایل‌های package-lock.json و دستور npm ci استفاده کنید.

خط لوله اعتبارسنجی کیفی، کانتینرسازی و استقرار ابری (CI/CD)

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

۱. فایل داکر چندمرحله‌ای (Multi-stage Dockerfile)

این Dockerfile استاندارد Next.js تضمین می‌کند که کدهای موقت هوش مصنوعی و داده‌های آزمایشی در ایمیج نهایی حضور نداشته باشند و نرم‌افزار با دسترسی کاربر غیرریشه (non-root) اجرا شود:

# مرحله اول: واکشی و قفل‌گذاری پکیج‌ها FROM node:20-alpine AS dependencies
WORKDIR /workspace RUN apk add --no-cache libc6-compat COPY package.json package-lock.json ./ RUN npm ci # مرحله دوم: کامپایل کدها و بیلد نهایی FROM node:20-alpine AS builder
WORKDIR /workspace COPY --from=dependencies /workspace/node_modules ./node_modules COPY . . ENV NEXT_TELEMETRY_DISABLED=1 RUN npm run build # مرحله سوم: ایمیج ایزوله نهایی برای اجرا FROM node:20-alpine AS runtime
WORKDIR /workspace ENV NODE_ENV=production
ENV PORT=3000 # اعمال اصل حداقل دسترسی با کاربر سیستمی غیر ریشه RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 appuser COPY --from=builder /workspace/public ./public COPY --from=builder --chown=appuser:appgroup /workspace/.next/standalone ./ COPY --from=builder --chown=appuser:appgroup /workspace/.next/static ./.next/static USER appuser
EXPOSE 3000 CMD ["node", "server.js"] 

۲. پایپ‌لاین اعتبارسنجی GitHub Actions

این فایل گردش کار در مسیر .github/workflows/deploy.yml قرار می‌گیرد و وظیفه تست سلامت کد، خطایابی زنجیره تأمین و بیلد را قبل از دیپلوی بر عهده دارد:

name: Production Delivery Pipeline on: push: branches: [main]
  pull_request: branches: [main]

jobs: code-quality-and-security: runs-on: ubuntu-latest steps: - name: دریافت مخزن سورس‌کد uses: actions/checkout@v4 - name: تنظیم نسخه نود uses: actions/setup-node@v4 with: node-version: 20 cache: 'npm' - name: نصب وابستگی‌های قفل‌شده run: npm ci - name: بررسی خطاهای تایپ‌اسکریپت run: npx tsc --noEmit - name: اجرای لینتر run: npm run lint - name: ممیزی پکیج‌های آلوده و توهمات زنجیره تأمین run: |
          npm audit --audit-level=high
          npx osv-detector --action=fail --parse-package-lock package-lock.json
 - name: اجرای تست‌های انتها به انتها (E2E) run: npx playwright test - name: صدور مجوز استقرار در کلود if: github.ref == 'refs/heads/main' && github.event_name == 'push' run: echo "کدها با موفقیت ارزیابی شدند؛ آماده استقرار نهایی در زیرساخت ابری." 

اقتصاد مهندسی، بدهی فنی و نقشه راه مقاوم‌سازی (Hardening)

وایب کدینگ ساختار هزینه‌های سنتی نرم‌افزار را واژگون کرده است:

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

• در وایب کدینگ مهارنشده: هزینه تغییر اول تقریباً صفر است و ظرف ۲ ساعت یک پروتوتایپ کامل بالا می‌آید! اما هزینه اعمال تغییر دهم به صورت تصاعدی بالا می‌رود؛ چون پروژه پر از کدهای زائد، توابع تکراری و تداخل‌های ناخواسته شده است. این وضعیت پدیده‌ای را رقم می‌زند به نام «تورم کد هوش مصنوعی» (AI Code Bloat)؛ یعنی مدل به جای فراخوانی توابع قبلی، در هر فایل یک تابع جدید با منطق مشابه تولید می‌کند.

نقشه راه ۴ مرحله‌ای برای مقاوم‌سازی سیستم

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

1. یکپارچه‌سازی تایپ‌ها: تمام انواع داده‌ای مبهم یا ساختارهای any را حذف کرده و مدل داده‌ها را با تایپ‌اسکریپت اکید قفل کنید.

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

3. ممیزی زنجیره تأمین: عمر و اعتبار تمام پکیج‌های ثبت‌شده در package.json را بررسی کرده و اطمینان یابید هیچ کتابخانه ناشناخته‌ای در مخزن وجود ندارد.

4. تست و بهینه‌سازی دیتابیس: سناریوهای بحرانی (مثل ثبت سفارش یا پرداخت) را با تست‌های Playwright پوشش دهید و استخرهای اتصال دیتابیس (Connection Pools) و قوانین RLS را ممیزی کنید.

سند مشخصات و معماری سیستم» (SPEC.md)

این سند «سند مشخصات و معماری سیستم» (SPEC.md) به عنوان تک‌مرجع حقیقت (Single Source of Truth) برای کل چرخه توسعه عمل می‌کند. قرار دادن این فایل در ریشه مخزن (Root) به ایجنت‌های هوش مصنوعی (مانند Cursor، Windsurf، Claude Code و Bolt) دیکته می‌کند که هیچ کدی را خارج از این چارچوب تولید نکنند، از تصمیم‌گیری‌های سلیقه‌ای بپرهیزند و دچار توهم ابزار یا معماری نشوند.

می‌توانید محتوای داخل کادر زیر را مستقیماً در فایلی با نام SPEC.md ذخیره کرده و متغیرهای داخل براکت‌ها [...] را متناسب با پروژه خود تکمیل کنید:

# 📄 معماری پروژه و سند مشخصات فنی (SPEC.md) > این سند مرجع اصلی معماری، مدل داده و قوانین پیاده‌سازی برای مهندسان و ایجنت‌های هوش مصنوعی است. هرگونه تغییر در معماری یا افزودن پکیج جدید مستلزم به‌روزرسانی صریح این سند است.

---

## ۱. نمای کلی و اهداف تجاری (Project Overview & Intent) * **نام پروژه:** [نام پروژه - مثال: FlowTask SaaS]
* **هدف اصلی (Core Intent):** [سیستم در یک یا دو پاراگراف کوتاه دقیقاً چه مشکلی را حل می‌کند و چه رفتاری دارد؟]
* **مخاطبان هدف:** [کاربر نهایی، سازمان‌ها، ادمین سیستم و ...]
* **نبایدها و مرزهای سیستم (Non-Goals):**   - [ویژگی‌هایی که نباید در این نسخه پیاده‌سازی شوند؛ مثلاً: عدم پیاده‌سازی سیستم چندزبانه در فاز MVP، عدم پشتیبانی از پرداخت با رمزارز و ...]

---

## ۲. پشته فنی و قفل فناوری‌ها (Tech Stack & Invariants)
ایجنت هوش مصنوعی اجازه جایگزینی، حذف یا معرفی کتابخانه‌های جایگزین بدون هماهنگی صریح را ندارد.

* **زبان:** TypeScript (Strict Mode فعال، نوع `any` ممنوع)
* **فریم‌ورک فرانت‌اند:** Next.js 15 (App Router با React 19)
* **استایل‌دهی:** Tailwind CSS v4 + پیکربندی متغیرهای CSS
* **کامپوننت‌های پایه:** Radix UI / shadcn/ui
* **مدیریت وضعیت:** Zustand (برای استیت‌های کلاینت) + TanStack React Query (در صورت نیاز به کش سرور)
* **پایگاه داده و احراز هویت:** PostgreSQL + Supabase (همراه با RLS و Supabase Auth)
* **اعتبارسنجی داده‌ها:** Zod (در تمام مرزهای ورودی کلاینت و سرور)
* **محیط تست:** Vitest (تست‌های واحد) + Playwright (تست‌های رفتاری E2E)
* **پکیج منیجر:** `npm` (همیشه اجرای دستورات بیلد با قفل هماهنگ `npm ci`)

---

## ۳. ساختار پوشه‌ها و مرزبندی لایه‌ها (Project Architecture & Boundaries)
تمام فایل‌ها باید دقیقاً در لایه مرتبط مستقر شوند؛ قرار دادن منطق دیتابیس در کامپوننت‌های فرانت‌اند نقض مستقیم معماری است.

```text
├── .cursor/
│   └── rules/                  # قوانین ماژولار و شرطی ایجنت (.mdc)
├── public/                     # فایل‌های استاتیک، فونت‌ها و تصاویر
├── src/
│   ├── app/                    # مسیرهای صفحات و اندپوینت‌های Next.js App Router
│   │   ├── (auth)/             # صفحات ایزوله ورود و ثبت‌نام
│   │   ├── (dashboard)/        # پنل کاربری محافظت‌شده با احراز هویت
│   │   └── api/                # اندپوینت‌های Route Handler سرور
│   ├── components/
│   │   ├── ui/                 # کامپوننت‌های اتمیک بصری فاقد منطق تجاری (Button, Modal, Input)
│   │   └── features/           # ماژول‌های رفتاری و تعاملی اختصاصی هر قابلیت
│   ├── lib/                    # کلاینت‌های ثالث، کانفیگ Supabase، هلپرهای عمومی
│   ├── server/
│   │   ├── services/           # هسته منطق محاسباتی و تجاری (Business Logic)
│   │   └── db/                 # توابع مستقیم دسترسی به داده‌ها، کوئری‌ها و ترنزکشن‌ها
│   ├── types/                  # تایپ‌ها و اینترفیس‌های مشترک کل پروژه
│   └── schemas/                # شِماهای اعتبارسنجی Zod
├── supabase/
│   └── migrations/             # مایگریشن‌های ساخت‌یافته و برگشت‌پذیر پایگاه داده
├── SPEC.md                     # سند مرجع معماری پروژه (همین فایل)
└── package.json

۴. مدل داده و پایگاه داده (Data Models & Supabase Schema)

۴.۱. تعاریف جداول و روابط

• جدول profiles:

  • id: UUID (کلید اصلی، ارجاع به auth.users.id با ON DELETE CASCADE)

  • email: TEXT (یکتا، غیرقابل نال)

  • full_name: TEXT

  • role: ENUM (‘admin’, ‘member’, ‘viewer’) پیش‌فرض ‘member’

  • created_at: TIMESTAMPTZ (پیش‌فرض now())

• جدول [نام جدول دیگر - مثال: tasks]:

  پیشنهاد محصول

  اشتراک Canva PRO کانوا پرو

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

  مشاهده محصول

  بیشتر مطالعه کنید

  راهنمای خرید اکانت GPT-6.1 Sol

  تنها یک هفته پس از رونمایی Claude Opus 5.5 توسط شرکت Anthropic، معرفی نسخه ۶.۱ مدل Sol بازار رقابت زیرساخت‌های هوش مصنوعی را دستخوش دگرگونی کرد. هدف محوری این سیستم، دستی...

  مطالعه کنید

  • id: UUID (کلید اصلی، gen_random_uuid())

  • user_id: UUID (کلید خارجی به profiles.id)

  • title: TEXT (غیر نال)

  • status: ENUM (‘todo’, ‘in_progress’, ‘completed’)

  • priority: ENUM (‘low’, ‘medium’, ‘high’, ‘urgent’)

  • created_at: TIMESTAMPTZ

۴.۲. الزامات امنیت در سطح ردیف (Row Level Security – RLS)

• RLS بر روی ۱۰۰٪ جداول فعال است (ALTER TABLE ... ENABLE ROW LEVEL SECURITY;).

• هیچ کاربری نباید به ردیف‌های خارج از سشن جاری (auth.uid()) دسترسی خواندن، ویرایش یا حذف داشته باشد مگر با تعریف صریح در سیاست‌های دسترسی سازمانی.

• نوشتن کوئری‌های فاقد محدودیت یا نادیده‌گرفتن RLS به کمک service_role در لایه کلاینت کاملاً غیرمجاز است.

۵. قراردادهای ارتباطی API و اعتبارسنجی (API Contracts & Zod)

۵.۱. ساختار یکپارچه پاسخ‌های سرور

تمامی پاسخ‌های API باید قالب استاندارد JSON زیر را به صورت تضمین‌شده بازگردانند:

// موفقیت:
{
  success: true,
  data: T,
  meta?: { page?: number; total?: number }
}

// شکست:
{
  success: false,
  error: {
    code: "VALIDATION_FAILED" | "UNAUTHORIZED" | "NOT_FOUND" | "INTERNAL_ERROR",
    message: string,
    details?: unknown
  }
}

۵.۲. شِمای اعتبارسنجی ورودی‌ها (مثال)

// src/schemas/taskSchema.ts import { z } from 'zod';

export const CreateTaskSchema = z.object({
  title: z.string().min(3, "عنوان باید حداقل ۳ کاراکتر باشد").max(120),
  description: z.string().max(1000).optional(),
  priority: z.enum(['low', 'medium', 'high', 'urgent']),
  dueDate: z.string().datetime().optional()
});

export type CreateTaskInput = z.infer<typeof CreateTaskSchema>;

۶. سیستم طراحی و قراردادهای رابط کاربری (Design System)

• پالت رنگ: استایل مینیمال، مدرن و مونوکروم (طیف سیاه، خاکستری تیره، سفید و یک رنگ تاکیدی مانند آبی نفتی یا ایندیگو).

• شعاع گوشه‌ها (Border Radius): استفاده استاندارد از گردی ملایم rounded-2xl یا کلاس‌های یکدست تعریف‌شده در کانفیگ.

• رندرهای کلاینت و سرور:

  • صفحات در حالت پیش‌فرض باید Server Component باشند.

  • کلمه کلیدی 'use client' صرفاً به لایه‌های تعاملی، ورودی‌های فرم و هوک‌های لوکال محدود شود.

• حالات تعاملی: برای تمامی اقدامات ناهمگام (Async)، حتماً سه حالت Loading (استفاده از Skeleton)، Error State (پیام قابل بازیابی) و Empty State طراحی شود.

۷. پروتکل امنیتی و ممانعت از توهم کتابخانه‌ها (Anti-Slopsquatting Protocol)

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

1. ممنوعیت نصب خودکار پکیج: ایجنت نباید بدون دستور صریح انسان دستور npm install یا npm add اجرا کند.

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

3. متغیرهای محرمانه: تمام کلیدهای محرمانه (API Keys، سکرت‌های دیتابیس) باید در فایل .env.local قرار گیرند. درج هرگونه کلید در کدهای فرانت‌اند با پیشوند نامعتبر غیرمجاز است.

۸. دستورات اعتبارسنجی و تعریف تکمیل وظیفه (Definition of Done)

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

# ۱. اعتبارسنجی تایپ‌ها بدون خطا
npm run typecheck # یا npx tsc --noEmit # ۲. بازرسی استایل و خطاهای کدنویسی
npm run lint

# ۳. اجرای تست‌های ایزوله
npm run test:unit

# ۴. تضمین بیلد موفقیت‌آمیز
npm run build

۹. پروتکل عملیاتی ایجنت هوش مصنوعی (Agent Workflow Rules)

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

1. طرح‌ریزی پیش از اقدام (Plan First): قبل از تغییر هر فایل، در چت خلاصه تغییرات، فایل‌های تحت تأثیر و فرضیات را بنویسید و منتظر تایید بمانید.

2. ویرایش اتمیک (Atomic Edits): در هر مرحله فقط یک ماژول یا فایل را ویرایش کنید؛ تغییرات دسته‌جمعی در ده‌ها فایل هم‌زمان اکیداً ممنوع است.

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

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

---

### نحوه اتصال این سند به ابزارهای وایب کدینگ

* **در Cursor و Windsurf:** این فایل را در مسیر اصلی پروژه ذخیره کنید. در اولین پرامپت خود در چت بنویسید:
  > `@SPEC.md لطفاً سند مشخصات را مطالعه کن و به عنوان معماری مرجع پروژه در تمام مراحل از آن تبعیت نما.`
* **در Claude Code (ترمینال):** دستور دهید:
  > `claude "Read SPEC.md thoroughly and establish the project scaffolding according to the Tech Stack section without adding unapproved libraries."`
* **قفل‌گذاری قواعد:** می‌توانید در پوشه `.cursor/rules/main-rules.mdc` بنویسید: `alwaysApply: true` و در متنش قید کنید: «همواره تمامی تصمیمات طراحی و کدهای خروجی باید با ضوابط فایل `SPEC.md` مطابقت داشته باشند.»

---

<ElicitationsGroup message="گام بعدی برای پیاده‌سازی و اجرای پروژه شما چیست؟">
  <Elicitation label="ایجاد فایل‌های قوانین MDC متناسب با این SPEC" query="بر اساس همین سند SPEC.md، سه فایل قانون mdc برای لایه سرور، فرانت‌اند و امنیت در پوشه cursor/rules بساز."/>
  <Elicitation label="تکمیل مدل داده و کدهای مایگریشن Supabase" query="کدهای SQL کامل مایگریشن Supabase شامل جداول، روابط، ایندکس‌ها و سیاست‌های RLS را بر اساس این مشخصات بنویس."/>
  <Elicitation label="تنظیم ساختار اسکلت اولیه با Next.js 15" query="دستورات مرحله‌به‌مرحله راه‌اندازی داربست اولیه پروژه با Next.js 15 و shadcn/ui را مطابق ساختار پوشه‌های این سند به من بده."/>
</ElicitationsGroup>