🚀 انتشار TeleScribe نسخه پیش‌نمایش

تلسکرایب ابزاریه برای تهیه خروجی‌های مختلف، گزارش و برچسب‌گذاری مبتنی بر LLM از محتوای کانال‌های تلگرامی.
اول یه اسکریپت پایتون بود که برای دیدن آمار کانال نوشتم (آمار خود تلگرام دیتایی که دوست داشتم از کانال ببینم رو ارائه نمی‌کرد) ولی الان یه اپلیکیشن جمع‌وجور کدباز دات‌نتیه که در صورت پیدا کردن فرصت آزاد، بهبودش خواهم داد.

امکانات:
- تهیه خروجی مارک‌دان از محتوای کانال تلگرامی
- به‌روزرسانی محتوای خروجی گرفته شده
- تهیه گزارش از محتوای سایت (مثال تک‌افترنون)
- ساخت سایت ایستا بر اساس محتوا (مثال تک‌افترنون)
- آپلود مطالب در وردپرس (هنوز کامل نشده و باگ داره)
- تهیه عنوان و هشتگ مطالب با LLM (هنوز کامل نشده و باگ داره)

📱 مخزن کد

⚙️ اگر باگ و مشکل دیدید، لطفا کامنت یا توی گیت‌هاب ثبت کنید. پیشنهاد و بهبود و... هم که بدیهیه که مزید امتنان است 🌱😊.

🎯 معرفی گیت‌وی اختصاصی هوش مصنوعی: AgentGateway چیه و چرا به وجود اومده؟

این روزها که گاهی عاقلانه و گاهی جوگیرانه، استفاده از agentها و MCPها رایج شده، و ارتباط و یکپارچگی نرم‌افزارها با مدل‌های هوش مصنوعی داغه، باید یه مشکل اساسی رو بررسی کنیم:

💡 چطوری این agentها بتونن ابزارهای مختلف رو کشف کنن، بهشون متصل بشن، احراز هویت کنن، نتیجه بگیرن و اگه لازم شد fallback بزنن؟ برای پاسخ به این نیاز، گیت‌وی‌هایی اختصاصی برای ارتباط با agents وارد می‌شن!

🛠 حالا AgentGateway چیه؟
پروژه AgentGateway یه پروژه متن‌بازه که agents هوش مصنوعی، سرورهای MCP و ارائه‌دهنده‌های LLM رو در هر محیطی به هم وصل می‌کنه. این اتصالات دوطرفه، امن، مقیاس‌پذیر و stateful هستن و امکانات لازم مثل امنیت سازمانی، observability، انعطاف‌پذیری و multi-tenancy رو ارائه می‌ده.

✅ وظایف کلیدی AgentGateway:

🔗 ارتباط یکپارچه:
- اتصال امن و مقیاس‌پذیر بین agentها و ابزارها
- پشتیبانی از پروتکل‌های agent مثل MCP و A2A
- تبدیل REST APIهای موجود به ابزارهای agent-native

🛡 امنیت و مدیریت:
- احراز هویت JWT و سیستم RBAC قدرتمند
- محافظت در مقابل حملات tool poisoning
- کنترل دسترسی در سطح agent، tool و tenant

⚡️ عملکرد سریع:
- با Rust نوشته شده تا کارایی بالا، تأخیر کم، قابلیت اطمینان و پایداری رو حفظ کنه
- مدیریت اتصالات طولانی‌مدت و الگوهای fan-out داره

📊 نظارت و مدیریت:
- از metrics و tracing داخلی برای رصد تعاملات پشتیبانی می‌کنه
- پورتال سلف‌سرویس برای توسعه‌دهنده ارائه می‌کنه

❓فرق اساسیش با API Gateway چیه؟

نوع درخواست‌ها:
- گیت‌وی API: عمدتاً REST/HTTP
- گیت‌وی Agent: تعاملات پیچیده مثل Agent ↔️ Tool، Agent ↔️ Agent، Agent ↔️ LLM

پروتکل ارتباطی:
- گیت‌وی API: HTTP
- گیت‌وی Agent: MCP و A2A که پروتکل‌های JSON-RPC برای ارتباط agents و tools هستن

مدیریت session:
- گیت‌وی API: درخواست‌های کوتاه‌مدت HTTP
- گیت‌وی Agent: می‌تونه sessionهای stateful که باید context جلسه رو حفظ کنن و پیام‌ها رو مداوماً ارسال و دریافت کنن رو ارائه کنه

پیچیدگی پردازش:
- گیت‌وی API: قادر به forward کردن ساده درخواست‌ها است
- گیت‌وی Agent: دسترسی به چندین سرور MCP، تجمیع پاسخ‌ها و بازگردوندن نتیجه منسجم رو داره

🚫 چرا گیت‌وی‌های سنتی کافی نیستند؟

گیت‌وی‌های سنتی برای معماری microservices RESTful طراحی شدن که درخواست‌های HTTP کوتاه‌مدت دریافت می‌کنن، backend رو انتخاب می‌کنن و درخواست رو forward می‌کنن. ولی:

🔴 مشکلات اساسی:
- عدم پشتیبانی از session awareness
- ضعف در مدیریت ارتباطات دوطرفه
- این الگوهای ارتباطی resource intensive هستند و می‌تونن گیت‌وی‌های سنتی رو مختل کنن
- نیاز به بازطراحی اساسی برای پشتیبانی از use caseهای agentic AI دارن

🚀 ویژگی‌های منحصربه‌فرد AgentGateway

ارائه data plane یکپارچه:
مدیریت اتصال agent با پشتیبانی از پروتکل‌های agent و قابلیت یکپارچه‌سازی REST APIهای موجود

امکان multiplexing و federation:
ارائه endpoint واحد برای federation چندین سرور MCP و مجازی‌سازی tool server بر اساس هر client

پشتیبانی از هر framework:
سازگاری با هر framework agentic که از پروتکل‌های MCP و A2A پشتیبانی می‌کنه، مثل LangGraph، AutoGen، kagent، Claude Desktop و OpenAI SDK

خصوصیت platform-agnostic:
قابلیت اجرا در هر محیطی از bare metal تا virtual machine، containers و Kubernetes

به‌روزرسانی پویا:
امکان به‌روزرسانی از طریق رابط xDS بدون downtime

🛡 سیاست‌های امنیتی و ترافیک:

مدیریت ترافیک:
- دستکاری headerها، redirect، rewrite
- پاسخ مستقیم بدون ارسال به backend

امنیت پیشرفته:
- تنظیمات CORS، احراز هویت MCP
- پشتیبانی از TLS برای backend، محدودیت نرخ محلی و توزیع شده
- پشتیبانی از JWT Auth و external authorization

انعطاف‌پذیری:
- قابلیت‌های request mirroring، timeout، retry logic

🎯 کی از AgentGateway استفاده کنه خوبه؟

- سازمان‌های بزرگ: مدیریت ارتباطات پیچیده بین agents
- توسعه‌دهنده‌های AI: یکپارچه‌سازی tools و agents
- تیم‌های DevOps: استقرار در محیط‌های مختلف
- محققین: آزمایش فریم‌ورک‌های جدید agent

مخزن گیت‌هاب
مستندات رسمی

🔥 🐘 انتشار PostgreSQL 18، و اهمیت تغییراتش!

طبق روال سال‌های گذشته حوالی سپتامبر ریلیز نسخه جدید PostgreSQL انجام شد. حالا چرا این نسخه برای برخی سیستم‌ها می‌تونه قابل توجه و مهم باشه؟

- تغییرات انقلابی در I/O (Asyn I/O):
بالاخره! این قابلیت اومد و سرعت عملیات Read رو «تا» ۳ برابر افزایش می‌ده! معطلی‌های CPU برای I/O خیلی کمتر می‌شه و برای کارهای مثل VACUUM و اسکن‌های بزرگ، تاثیرش چشمگیره (من روی نسخه‌های پیش‌نمایش تست کردم و عالی بود).

- پشتیبانی از UUIDv7:
برای توسعه‌دهنده‌ها این شاید خیلی مهم باشه! (اگر دوست دارید در مورد انواع UUIDها بیشتر توضیح بدم: 🤪)
پشتیبانی Native از UUIDv7 یعنی Primary Key‌ها به صورت گلوبال یونیک میشن و هم چون بر اساس زمان مرتب هستن، عملکرد ایندکس B-tree به شکل چشمگیری بهتر میشه. (یعنی Page Split بی مورد نداریم!)

- قابلیت Virtual Generated Columns:
حالا ستون‌های محاسباتی به‌صورت پیش‌فرض مجازی هستن، یعنی فقط موقع خوانش محاسبه میشن و فضای دیسک رو اشغال نمی‌کنن. (البته اگه لازم باشه، می‌تونید همچنان STORED هم تعریف کنین).

افزودن NOT NULL بدون Downtime: کابوس اضافه کردن NOT NULL به جدول‌های بزرگ تموم شد! حالا می‌شه قید NOT NULL رو به‌صورت NOT VALID اضافه کنیم و بلافاصله برای ردیف‌های جدید اعمال بشه. اعتبارسنجی ردیف‌های موجود رو هم می‌تونیم بعداً بدون قفل کامل جدول انجام بدیم.

- امکان Skip Scan برای B-tree:
یه بهبود عالی برای بهینه‌سازی کوئری؛ اگه توی ایندکس‌های چند ستونی، ستون اول رو در WHERE فیلتر نکرده باشیم، باز هم ایندکس کار می‌کنه و کوئری‌های تحلیلی/گزارش‌گیری خیلی سریع‌تر میشن.

- امکان RETURNING هوشمند:
حالا میشه توی یک دستور UPDATE یا DELETE به هر دو مقدار قدیمی (OLD) و جدید (NEW) یک ستون در بخش RETURNING دسترسی داشته باشیم.

- آپگرید آسون‌تر:
قابلیت حفظ Planner Statistics حین آپگرید با pg_upgrade باعث میشه دیتابیس جدید خیلی سریع‌تر به پرفورمنس دلخواه برگرده.

اگر جزو افرادی هستین که به مهاجرت به PostgreSQL فکر می‌کنید، یه تعداد کارت‌های شسته‌رُفته برای مهاجرت از SQL Server به PostgreSQL با هشتگ #MSSQL_to_PGSQL توی کانال داریم (کارت‌های قرمز رنگ از بخش تصاویر هم قابل پیدا کردنه)

⚙️ کمی در باب UUID

توی اکثر سیستم‌های اطلاعاتی، چه در مورد پیام‌های مورد تبادل بین سرویس‌های یک نرم‌افزار مبتنی بر مایکروسرویس صحبت کنیم، چه در مورد داده‌های دیتابیس، نیاز به یک روش مطمئن برای شناسایی منحصربه‌فرد داده‌ها وجود داره. استفاده از شناسه‌های ترتیبی (Sequential Integers) مثل Auto-Increment توی دیتابیس‌ها ساده و سریعه ولی توی محیط‌های توزیع‌شده که چندین سرور به طور همزمان ID تولید می‌کنن، برای جلوگیری از تکرار، نیاز به هماهنگی مرکزی دارن که خودش گلوگاه مقیاس‌پذیریه (Scalability).

برای پاسخ به این نیاز، UUID (Universally Unique Identifier) به وجود اومده. UUID‌ها شناسه‌های 128 بیتی (۳۶ کاراکتر) هستن که بدون نیاز به هماهنگی مرکزی، منحصر به فرد بودن رو در سطح جهانی تضمین می‌کنن. سال ۲۰۲۴، استاندارد رسمی RFC 9562 نسخه‌ی ۷ رو معرفی کرده: ۴۸ بیتِ اول «تایم‌استمپ یونیکس بر حسب میلی‌ثانیه»، بقیه بیت‌ها تصادفیِ امن. نتیجه؟ شناسه‌ها زمان‌مرتب و در عین حال یونیک هستن. چرا زمان‌مرتب بودن این شناسه‌ها مهمه؟ چون مثلا توی نسخه ۴، شناسه کاملا تصادفیه و اگر به ترتیب بخواهیم مرتب کنیم احتمال اینکه شناسه‌ای که الان تولید می‌کنید بعد از شناسه‌ای که دو ساعت پیش یا دو سال پیش تولید کردید قرار بگیره زیاده. این یعنی شروع مشکل. چه مشکلی؟ ایندکس جداول یا سری‌های زمانی.

فرض کنین یه کتاب دارید که شماره صفحاتش کاملا رندوم ولی یکتا باشه. در حالت عادی که شماره صفحات مرتب و دنبال هم هستن وقتی دنبال صفحه ۱۳۷ کتاب می‌گردید، اول یه جای کتاب رو باز می‌کنید و می‌بینید مثلا ۱۸۹ است، چون مطمئنید شماره ۱۳۷ قبلش است دیگه صفحات بعدی رو نگاه نمی‌کنید، یه جا قبل‌تر رو باز می‌کنید می‌بینید ۱۲۵ است، دیگه قبل‌تر و نمی‌گردید و چند صفحه جلوتر، ۱۳۷ رو پیدا می‌کنید. این یعنی پیدا کردن سریع‌تر مطالب. حالا اگر شماره صفحات رندوم باشه، هر بار که مرتبش کنیم با اولین مقدار جدید، نظم به هم می‌ریزه و پیدا کردن صفحات دشوار می‌شه.

مرور نسخه‌ها تا به امروز:

نسخه v1: مبتنی بر زمان و MAC Address » ترتیبی بر اساس زمان، یونیک جهانی » ولی افشای آدرس MAC (مشکل حریم خصوصی)

نسخه v2: مبتنی بر Domain محلی و Security » رزرو شده برای DCE Security » کاربری و استفاده بسیار محدود.

نسخه v3: مبتنی بر نام (MD5 Hashing) » همیشه برای یک "نام" و "دامین" مقدار یکسان تولید می‌شه. » از هش قدیمی MD5 استفاده می‌کنه که منسوخ شده.

نسخه v4: کاملاً تصادفی، یونیک جهانی با بالاترین میزان تصادفی بودن. » نامرتب؛ عملکرد ایندکس دیتابیس (B-tree) رو به شدت کاهش می‌دهه. » متاسفانه همچنان رایج، اما برای Primary Key نامناسب.

نسخه v5: مبتنی بر نام (SHA-1 Hashing) مشابه v3، اما از هش بهتر SHA-1 استفاده می‌کنه » فقط برای مواردی که نیاز به تکرارپذیری UUID است، مناسبه. » بهتر از v3، برای تولید شناسه‌های ثابت از URL یا نام.

نسخه v6: مشابه v1 ولی با ترتیب زمانی بهتر » مرتب زمانی، ولی بدون افشای MAC
» هنوز نسخه draft است، » کاربردش جایگزینی v1 در آینده

نسخه v7: مبتنی بر زمان یونیکس + مقدار تصادفی » مرتب بر اساس زمان و در عین حال یونیک جهانی + عملکرد بهینه دیتابیس » بهینه برای Primary Key خصوصا توی سیستم‌های توزیع‌شده و سری‌های زمانی » امکان افزودن کسریِ زیرِ میلی‌ثانیه و/یا کانتر هم برای تضمین مرتب‌بودن در همان میلی‌ثانیه پیش‌بینی شده.

نسخه v8: فضای سفارشی/تجربی برای نیازهای خاص.

📌 نسخه UUIDv7 به صورت بومی توی PostgreSQL 18 و SQL Server 2025 و پایتون ۳.۱۴ و دات‌نت ۹ و گو هم gofrs/uuid v5 پشتیبانی می‌شه ولی MySQL و MariaDB و جاوا هنوز نسخه بومی رو پیاده نکردن.

♻️ چرخه عمر نیروی انسانی (Employee Life Cycle) چیه؟

در بررسی ریشه‌های وضعیت فعلی توسعه نرم‌افزار در ایران، یکی از مهم‌ترین دلایل، ضعف فاحش در مدیریت چرخه عمر کارمند (Employee Life Cycle - ELC) است. این چرخه تمام مسیر یک فرد رو از پیش از جذب تا بعد از خروج پوشش می‌ده، توی شرکت‌ها و سازمان‌های ایرانی عموما جدی گرفته نمی‌شه یا به شوخی شبیهه. ELC یه مدل راهبردی توی مدیریت منابع انسانیه (HRM) که معمولا شامل ۶ مرحله کلیدی می‌شه.

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

مراحل ELC عموما:

➖ برنامه‌ریزی نیروی کار یا Workforce Planning
➖ جذب و گزینش یاRecruitment & Selection
➖ فرایند پذیرش و آشنایی یا Onboarding
➖ توسعه و آموزش یاDevelopment
➖ مدیریت عملکرد یا Performance Management
➖ نگهداشت یاRetention
➖ فرایند خروج یا Offboarding

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

🔗 در باب وضعیت امروز نرم‌افزار ایران، چند خطی رو در از منظر ELC نوشتم که اگر دوست داشتید مطالعه کنید و خوشحال می‌شم نظرتون رو به اشتراک بگذارین 😊

✨ آیا APIهای فعلی‌مون می‌تونن MCPهامون رو بسازن؟! (بخش ۱)

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

مقدمه:

اگر با مفهوم و ساختار MCP آشنایی دارید می‌تونید از روی بخش مقدمه بپرید و برید سراغ «✅ اصل مطلب»!

پروتکل MCP یا Model Context Protocol یک پروتکل باز و استاندارد برای شناسایی و به کارگیری منابع و ابزارها (منابع مثل دیتابیس‌ها، ابزارها هم مثل API و کامندها) توسط مدل‌های زبانیه که شرکت Anthropic (توسعه‌دهنده Claude) سال ۲۰۲۴ معرفی کرد.

💡 هدف و عملکرد
هدف اصلی MCP، ایجاد یه زبان مشترک برای تعامل مدل‌های زبان بزرگ (LLM) با برنامه‌ها و خدمات دنیای واقعیه. به بیان ساده‌تر، این پروتکل به هوش مصنوعی (LLM) اجازه می‌ده تا به‌جای اینکه فقط بر اساس داده‌های خودش متن تولید کنه، اقداماتی (Actions) رو در یک برنامه خارجی انجام بده (مثل فراخونی API یا کوئری گرفتن از دیتابیس یا...).

استانداردسازی: این پروتکل نحوه ارائه "ابزارها" و "قابلیت‌های" یک برنامه به LLM رو به شکل استاندارد تبیین می‌کنه.

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

🧱 اجزای کلیدی (MCP Server)
سرور MCP سه مفهوم اصلی رو به LLM (که نقش کلاینت رو داره) ارائه می‌ده:

۱: ابزارها یا Tools:
مهم‌ترین جزء هستن. در واقع همون عملیات (Actions) یا APIهای سطح بالایی هستن که LLM می‌تونه فراخونی کنه. مثال: "ایجاد پایگاه داده" یا "رزرو پرواز" یا "درج یه سفارش جدید".
یک LLM برای انجام وظایف بهینه، به تعداد محدودی از ابزارهایی که به خوبی تعریف‌شده باشن نیاز داره.

۲: منابع یا Resources:
داده‌ها یا اطلاعات جانبی مورد نیاز برای اجرای ابزارها (دیتابیس، فایل حاوی داده یا ...).

۳: دستورالعمل‌ها یا Prompts:
متن‌هایی که به LLM کمک می‌کنن تا درک کنه چه زمانی و چجوری از ابزارها استفاده کنه.

🐤 یه نمونه MCP ساده برای تبدیل واحد توی کامنت می‌گذارم

✅ اصل مطلب: آیا API شما برای ساخت MCP کافیه؟
اگر نرم‌افزار شما RESTful باشه، ابزارهای متعددی هستن که از روی OpenAPI Spec شما برای MCP سرور می‌سازن. این رو داشته باشید فعلا تا ۳ تا حالت ساخت MCP رو ببینیم:
۱: خودکار
با استفاده از ابزارهایی مثل Fast MCP از APIهای فعلی رو به عنوان ابزار توی MCP سرور معرفی می‌کنیم. خیلی سریع! (بررسی مشکلات در بخش دوم همین مطلب)

۲: دستی
متناظر با قابلیت‌هایی که می‌خواهیم با استفاده از هوش مصنوعی ارائه کنیم، APIهای اختصاصی برای هوش‌مصنوعی تولید می‌کنیم، طبیعتا تعداد محدوتر، و کلی‌تر (مثلا یک API برای کل یک فرایند)


«ادامه در بخش دوم، فردا»
(مشکلات روش خودکار + معرفی روش سوم یا همون هایبرید)

✨ آیا APIهای فعلی‌مون می‌تونن MCPهامون رو بسازن؟! (بخش دوم)

در بخش ۱ دو روش خودکار و دستی ساخت MCP رو فقط نام بردیم و تحلیل این دو روش و معرفی روش سوم باقی موند!

چهار مشکل اساسی تولید خودکار
۱. معضل انتخاب بیش از حد
یکی از موضوعات مهم در کار با LLMها اینه که این مدل‌ها زمانی که با تعداد زیادی گزینه روبرو می‌شن، خِنگ می‌شن! و پاسخ‌های دقیقی ارائه نمی‌کنن. تصور کنید یک API با ۷۵ تا ۱۰۰ endpoint رو به‌طور خودکار به MCP تبدیل کنید. LLM با کلی ابزارها روبرو می‌شه و تصمیم‌گیری برای انتخاب ابزار مناسب برای هر کار، به یه چالش جدی براش تبدیل می‌شه. نتیجه؟ سردرگمی، انتخاب‌های نادرست، و در نهایت تجربه کاربری ضعیف. (حالا تصور کنین توی یک سیستم بزرگ که چند هزار و یا توی انترپرایزها چند ده هزار API خیلی خیلی عادیه)

۲. توضیحات نامناسب برای LLM
عملا APIهای سنتی با توضیحات نوشته شده برای توسعه‌دهنده‌های انسانی طراحی شده‌ان (بگذریم که ۹۹درصد APIهای خیلی شرکت‌ها همون رو هم نداره!). انسان‌ها می‌تونن استنباط کنن و سوال بپرسن.اما LLMها به توضیحات مستقیم، دقیق و اغلب مثال‌محور نیاز دارن تا بفهمن چه زمانی و چجوری باید از یه ابزار استفاده کنن. توضیحات API موجود شما، صرف‌نظر از اینکه برای انسان‌ها چقدر واضحه، احتمالاً برای LLM بهینه نشده.

۳. عدم تطابق سطح انتزاع
بیشتر APIها برای کارهای سطح پایین طراحی شدن: مدیریت منابع، عملیات CRUD، و خودکارسازی‌های فنی. اما LLMها ماهیت انسان‌گونه‌تری دارن و باید کارهای سطح بالا رو انجام بدن. به‌عنوان مثال، به‌جای اینکه یک LLM رو مجبور کنین ده تا endpoint مختلف رو به‌صورت دستی فراخوانی کنه تا یک فرآیند کاری رو کامل کنه، چرا یه ابزار اختصاصی نسازین که کل این گردش کار رو توی یک فراخوانی به صورت هوشمندانه‌تر انجام بده؟

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

🙂 ۳: هایبرید
ترکیبی از هر دو، که نیازی نیست از صفر شروع کنیم. نوشتن یک سرور MCP از ابتدا می‌تونه کار سنگینی باشه (حتی نمونه‌های ساده). راه‌حل بهینه، یک رویکرد ترکیبیه که از نقاط قوت تولید خودکار بهره بگیره، اما با بهینه‌سازی دستی تکمیل بشه.
مراحل پیاده‌سازی راه‌حل هایبرید:
۳-۱. شروع با تولید خودکار
از ابزارهای موجود برای تولید اولیه سرور MCP از API خودمون استفاده می‌کنیم. این به ما یه پایه‌ی سریع می‌ده.

۲-۳: هَرَس کردن ابزارها
تعداد endpointهای اعلان شده رو بنا به نیاز کاهش می‌دیم. فقط مهم‌ترین و پرکاربردترین ابزارها رو نگه می‌داریم. کیفیت بر کمیت ارجحیت داره.

۳-۳. بازنویسی توضیحات
توضیحات ابزارها رو به‌گونه‌ای بازنویسی می‌کنیم که برای LLMها مستقیم و صریح و قابل فهم باشن و بین APIها به اشتباه نیوفتن. از مثال‌های واضح استفاده بشه و سناریوهای استفاده رو به‌طور دقیق توضیح بدید.

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

۵-۳. تست و بهینه‌سازی
تست‌های جامعی بنویسید تا اطمینان پیدا کنین LLMها به‌درستی از ابزارها استفاده می‌کنن. این مرحله حیاتیه! خیلی هم حیاتی. چون خیلی چیزها که تئوری کار می‌کنن، ممکنه در عمل نیاز به تنظیم داشته باشن تا مدل اشتباه نکنه و مزخرف تحویل نده.

«ادامه در بخش سوم، فردا»

✨ آیا APIهای فعلی‌مون می‌تونن MCPهامون رو بسازن؟! (بخش سوم و آخری)

در بخش ۱ و ۲ علاوه بر مرور MCP و روش‌های ساختن MCP سرور، مشکلات تولید خودکار و نحوه ایجاد هایبرید رو مرور کردیم، بریم سراغ بخش سوم و آخر این مطلب:

نتیجه‌گیری:

در واقع MCP فرصت خیلی خوبی برای ایجاد یکپارچگی عمیق بین LLMها و سرویس‌های موجود ماست. اما مثل خیلی از تکنولوژی‌های جدید، موفقیت در جزئیات نهفته است. API موجود شما یک شروع عالیه، اما به‌تنهایی کافی نیست. تولید فَله‌ای و چشم‌بسته می‌تونه علاوه بر یک محصول افتضاح، باعث مشکلات خیلی خیلی جدی بشه، می‌پرسید چه مشکلی؟ یا فکر می‌کنید فوق فوقش درست کار نمی‌کنه؟ نه جانم! خیلی راحت می‌تونه باعث بشه دیتای غیرمجاز رو به کاربر غیر مجاز افشا کنه!! خیلی راحت همین فَله‌ای تولید کردن‌ها می‌تونه باعث بشه از حساب یکی دیگه اعتبار کسر یا اضافه بشه! کافیه بدون کنترل دسترسی، بدون فرایندهای کنترلی مضاعف، فَله‌ای MCP تولید کنین و برید توی لینکدین و توییتر بنویسید «خسته از کد زدن بسیار ولی خرسند از کاویدن اعماق هوش مصنوعی» (عکس با قهوه یا ماچا فراموش نشود!). چند روز بعدش هم که افتضاحش علنی شد، برگردیم به همون بحث عمیقا علمی PHP بهتر است یا Go یا دوران شی‌گرایی به سر اومده!!

ولی با پذیرش یک رویکرد ترکیبی، شروع با تولید خودکار و بعدش با بهینه‌سازی هوشمندانه (هوشمندانه یعنی مرور تمام ابزارهای افشا شده در MCP و بررسی توضیحات، سناریوها و نکات امنیتی) می‌تونید سرورهای MCP بسازین که نه‌تنها کار می‌کنن، بلکه واقعاً قدرت LLM رو توی نرم‌افزار سنتی آزاد می‌کنن تا کارهای «معناداری» برای کاربرها انجام بدن.

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

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

💬 تجربه و نظرتون درباره تولید MCP و استفاده توی نرم‌افزارهای LOB چیه؟

✈️ معرفی Microsoft Agent Framework برای پایتون و دات‌نت؛ توسعه ساده‌تر سیستم‌های ایجنتیک

مایکروسافت اخیرا فریم‌ورک کدباز Agent Framework رو معرفی کرد که عملا با ترکیب ایده‌ها و قابلیت‌هایی که پیشتر به صورت مجزا در Semantic Kernel و AutoGen ارائه کرده بود، کمک می‌کنه تا توسعه‌دهنده بتونه ربات‌ها یا ایجنت‌های مورد نظرش رو با انعطاف، مقیاس‌پذیری و پایداری مورد انتظارش بسازه و مدیریت کنه.

چرا MAF مهمه؟ چون پایان یک دوراهیه!
تا الان یه دو راهی مهم جلو پای توسعه‌دهنده‌ها بود:

۱: استفاده از Semantic Kernel: که پایداری و آمادگی لازم برای محیط‌های سازمانی و پروداکشن رو داره.

۲: استفاده از AutoGen: که برای نوآوری، آزمایش و ساخت ایجنت‌هایی که با هم گفتگو و تعامل دارن مناسبه (یعنی Multi-Agent Orchestration؛ همچنین توسعه و نگهداریش هم با Microsoft Research’s AI Frontiers Lab است که از اسمش مشخصه تکنولوژی‌های نوآورانه و در دست توسعه رو دنبال می‌کنه).

ولی حالا هر دو رو در توی یک پکیج واحد داریم.

✅ استانداردهای باز و تعامل‌پذیری
از پروتکل‌هایی مثل MCP، Agent2Agent، و طراحی OpenAPI-first پشتیبانی می‌کنه؛ و امکان اتصال آسون به ابزارها و سرویس‌های مختلف بدون وابستگی به یک اکوسیستم خاص رو فراهم می‌کنه.

✅ پل بین جنبه تحقیقاتی و جنبه تولید محصول
الگوریتم‌ها و الگوهای چند ایجنتی (orchestration) که فعلا آزمایشی هستن (مثل Magetnic یا Group Chat) حالا توی یه محیط عملیاتی قابل استفاده شدن. و این یعنی قابلیت بهره‌گیری از نوآوری‌های خیلی جدید توی پروژه‌های واقعی.

✅ قابلیت گسترش (Extensibility)
ماژول‌های حافظه قابل انتخاب هستن (مثل Redis، Pinecone، Qdrant)، کانکتورهای سازمانی می‌شه براشون نوشت یا از نمونه‌های آماده استفاده کرد، تعریف ایجنت به‌صورت YAML یا JSON. می‌شه خیلی سرراست اجزا رو بر اساس نیاز پروژه تا حد زیادی سفارشی کرد.

✅ آمادگی برای تولید (Production-Ready)
امکانات مورد نیاز محیط پروداکشن مثل observability، کنترل خطا، checkpointing، امنیت و فلوهای CI/CD رو داره و می‌تونه توی پروژه‌های واقعی با الزامات سازمانی به کار بره. و Human-in-the-Loop رو داره؛ یعنی قابلیت "تایید توسط انسان" برای عملیات‌های حساس؛ ایجنت قبل از اقدام منتظر تأیید می‌مونه.

شروع کار:
این فریم‌ورک کاملاً متن‌بازه و برای Python و NET. در دسترسه و مثال‌های خیلی خوبی هم برای شروع داره.

مخزن گیت‌هاب
داکیومنتیشن و راهنمای نصب

💡 پیشنهاد می‌کنم بدون به دام حباب‌ و هیجان افتادن؛ هم این کاربردها رو یاد بگیرید، هم به استفاده ازشون فکر کنید، چون شاید خیلی زود دیر بشه! کاربری AI فقط سوال پرسیدن، توهمات ناشی از وایب‌کُدینگ و... نیست...

🐤 مطلب بعدی در مورد ۳ تا از بارزترین خصوصیات «بدترین برنامه‌نویس یا مهندس نرم‌افزار» خواهد بود!

به نظر شما به چه خصوصیاتی می‌شه گفت بدترین و افتضاح‌ترین؟ 🤔
کامنت کنید لطفا

حتی اگه نظرتونه که
- پنگوئن یا سیب یا پنجره دوست داشته|نداشته باشه 😅
- یا همه چیز رو آبجکت ببینه یا فانکشن ببینه!
- یا اینکه موقع کار، ماچا بخوره یا چایی‌شیرین!

🐊 بدترین مهندس نرم‌افزار دنیا چه شکلیه؟ شاید هم خودمونیم؟؟

این مطلب صرفا نظر و تجربه شخصیه؛ نسخه جهان‌شمول یا خط‌کش نیست. تجربه‌ی بیش از دو دهه تعامل و دقت در رفتارها و مسیر رشد آدم‌ها از نگاه یک نفر از ۸ میلیارد جمعیت زمین است! قطعا میشه متون دقیق‌تر، کامل‌تر و موشکافانه‌تری هم نوشت؛ ولی شاید مرورش خالی از لطف نباشه...

لیست معضلات رفتاری، فنی، اخلاقی و تیمی خیلی بلند و مفصله. اما بعضی ویژگی‌ها، نه‌فقط مشکل هستن، بلکه مانع یادگیری و ریشه‌ی معضلات دیگه هم می‌شن. من قبل از نوشتن این مطلب، سعی کردم رفتارها و خصوصیت‌هایی که در خودم «تصور» می‌کنم بهبود دادم رو مرور کنم، ببینم اگر چه خصوصتی داشتم، مانع جدی برای بهبود می‌شد؟! بعد این لیست رو اینقدر مرور کردم که چکیده‌ای از رذائل دربیارم که ریشه مشکلات باشن! به نظرم اون‌هایی واقعاً «افتضاح‌ترین» هستن که ترکیب خطرناکی از این ۳ ویژگی رو دارن:

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

✏️ مصداق‌ها:
- وانمود می‌کنه چیزی رو بلده ولی بلد نیست
- دروغ می‌گه که پیشرفت پروژه خوبه، در‌حالی‌که نیست (green shifting)
- عامدانه code review تقلبی می‌ده؛ فقط یه ابزار آنالیز خودکار باز کرده
- باگ‌ها رو قایم می‌کنه

😡 چرا بده؟ چون اعتماد تیم رو نابود می‌کنه. بدون اعتماد، حتی بهترین فرآیندها هم به لجن کشیده می‌شن. این افراد به خودشون هم دروغ می‌گن. تقلب می‌کنن و کار کردن با کسی که عامدانه دروغ می‌گه و بهش عادت کرده، دیگ داغیست از دیگ‌های داغ جهنم!

۲. بی‌سؤالی، تعصب، توقف رشد
بزرگ‌ترین ریسک صنعت ما توقف یادگیریه؛ نه نابلدی!

🧠 کسی که سوال نداره، انگار دیگه دنبال بهتر شدن نیست.
🔒 کسی که تعصب داره (فقط فلان زبان، فقط فلان ابزار)، راه اصلاح رو به خودش بسته؛ شاید فکر کنه داره یاد می‌گیره؛ ولی داره مهارتش در یاد نگرفتن و توجیه نادانی‌اش رو تقویت می‌کنه.
🙈 کسی که اشتباه می‌کنه، ولی فکر می‌کنه تقصیر دنیاست، یعنی از دورِ یادگیری خارج شده.

فرق کسی که رو به جلو می‌ره و کسی که رو به زواله توی همین چیزاست.

۳. بی‌مالکیتی و انفعال

"به من بگو چی‌کار کنم" ممکنه از دهن یه تازه‌کار قابل قبول باشه. ولی یه مهندس واقعی باید خودش دنبال معنی، مشکل، راه‌حل، و تبعات کارش باشه.

📡 نشونه‌ها:
- فقط همون کاری رو می‌کنه که دقیقاً بهش گفتن
- هیچ پیش‌فرضی رو به چالش نمی‌کشه (تفکر نقادانه نداره اساسا)
- تغییرات رو با مقاومت پاسخ می‌ده (فناوری، فرآیند، ابزار)
- کارش رو فقط "تا اینجا وظیفه‌م بود" می‌بینه

❓ چرا بده؟ چون تیم رو از یه گروه خلاق به یه کارخانه "دستور بگیر - خروجی بده" تبدیل می‌کنه. هیچ self-organization واقعی‌ای شکل نمی‌گیره. (توی پست نرم‌افزار و این روزهای ایران مفصل نوشتم)

💡 پشت همهٔ اینا یه چیزه...
ریشه همهٔ این‌ها، نداشتن principle (به فارسی پرنسیپ گفته می‌شه). یعنی کسی که هیچ چارچوب فکری و اخلاقی برای خودش نساخته. درسته که می‌شه چارچوب بد هم داشت ولی این کلمه در ذاتش بار مثبت اخلاقی داره. کسی که principle نداره نه از خودش نمی‌پرسه:
«این رفتار درسته؟»
«چرا دارم این کار رو اینجوری انجام می‌دم؟»
«اصلاً من دارم رشد می‌کنم یا درجا می‌زنم؟»
«آیا آدم‌ها از تعامل با من خوشحالن؟ آیا مفیدم؟ چجوری بهتر بشم؟»

یه آدم فاقد principle، بر اساس منفعت لحظه‌ای رفتار می‌کنه. یه بار پنهان می‌کنه، یه بار تقلب می‌کنه، یه بار مقاومت در برابر حرف صحیح، یه بار انفعاله... چون "راهنمای درونی" نداره.

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

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

💬 حالا نوبت شماست:
کامنت کنید؛ شاید کمک کنه فردا کمی بهتر از امروز باشیم 🌱

🧪 مفهوم و کاربرد API Mocking & Virtualization

خیلی از سردردها از نداشتن محیط اجرای مناسب نشأت می‌گیره؛ و خیلی از محیط خوب نداشتن‌ها از ترس پیچیده یا زمان‌بر بودنِ پیاده‌سازی. از طرف دیگه خیلی از integration ها با آسودگی و سرعت پیش نمی‌رن؛ چون API سیستمِ دیگه، شفاف نیست، یا محیط test نداره.

شنیدن جمله "منتظرم API شون آماده شه!" چیز غریب و نادری نیست! ولی واقعیت اینه که توی تیم‌های بالغ، منتظر نمی‌مونن، mock می‌کنن، یا قبل از توسعه API واقعی، اول API Spec رو می‌نویسن و در اختیار تیم‌های دیگه قرار می‌دن. اگر هم خیلی بالغ باشن که به جز API Spec ساز و کارkey management برای محیط‌های dev/test/stage/production رو هم محیا و ارائه می‌کنن.

بیاین در گام اول بیخیالِ میزان بلوغ تیم مقابل بشیم و خودمون رفتارهای بالغانه در تیم داشته باشیم:

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

🚦 چرا مهمه؟
- کاهش وابستگی‌ها: تیم‌ها می‌تونن موازی کار کنن.
- بهبود تست و استیجینگ: سناریوهای خطا و پاسخ‌های خاص قابل بازسازی هستن.
- تکرارپذیری: تست‌ها بدون وابستگی به داده‌های زنده انجام می‌شن.
- پیشرفت بدون صبر: تا backend آماده بشه، frontend یا consumer هم رشد می‌کنه.

🧰 ابزارها

۱: ابزار Mockoon
رایگانه، دسکتاپ اپلیکیشن با رابط گرافیکی خوب است (نسخه مک و ویندوز داره) نسخه CLI هم داره.

۲: ابزار WireMock
یکی از بهترین ابزارها بود تا اینکه نسخه رایگان و پولی منتشر کرد! هنوز هم از نظر قابلیت‌ها ابزار خیلی خوبیه و مثلا rule-based mock، یا fault simulation رو خیلی خوب پشتیبانی می‌کنه.

۳: ابزار Microcks
هنوز به بلوغ WireMock نرسیده ولی ابزار خیلی خوبیه، یه UI وب ساده هم داره ولی هنوز کامل نیست (مثلا اینکه بتونید با UI انواع payloadها رو تعریف کنید یا chain بسازید رو نداره.

۴: ابزار (سرویس) Postman Mock Server
خب پست‌من دیگه برای همه شناخته شده است، ولی سرویس‌ها انترپرایزش نیاز به لایسنس داره چون نسخه رایگان همین mock server فقط ۳ کاربر رو پشتیبانی می‌کنه و محدودیت‌های زیادی داره.

چجوری payload رو محیا کنیم؟

۱. استخراج از مستندات موجود
اگر تیم backend مستندات OpenAPI/Swagger داره، راحت‌ترین راهه:

curl https://api.company.com/openapi.json -o spec.json
mockoon-cli import --data spec.json

حتی اگر schema دقیق نباشه، حداقل مسیرها و ساختار پایه آماده‌ست.

۲. Sniff کردن درخواست‌ها در زمان کار
اگه endpointها در محیط تست یا staging یا جایی که بتونین حداقل یک بار صداشون کنین در دسترس هستن؛ ولی مستندات ندارن:
از Fiddler, Charles, یا mitmproxy یا ابزارهای مشابه استفاده کنید برای کپی کردن و استخراج درخواست‌ها و پاسخ‌ها. بعد اون‌ها رو به JSON تبدیل و برای mock استفاده کنین.
(یه snapshot واقعی از تعامل سیستم‌هاست)

۳. تولید خودکار مدل از JSON
وقتی چند تا نمونه JSON داری ولی model نه:
ابزارهای زیادی از جمله خود IDE های رایج سریع JSON رو به تایپ تبدیل می‌کنن و این کمک می‌کنه تا schema بسازین و بر اساس اون mock بنویسین.

۴. ساخت چند سناریو
فقط happy path رو mock نکن! یعنی اینکه همه چیز خیلی خوب و باب طبع باشه کافی نیست؛ سناریوهای مختلف مثل انواع خطاهای کد 4xx یا 5xx یا کندی‌ها یا تام‌اوت یا... رو هم در mock‌هات بسازین.

جمع‌بندی
فراموش نکنین که Mocking فقط یه کار “موقتی” نیست، یه مهارت توسعه‌ی تیمیه برای استقلال، سرعت و کیفیت. وقتی payloadها درست جمع‌آوری بشن، Mocking تبدیل میشه به پلی بین توسعه، تست و واقعیت سیستم.

💬 اگر موضوعاتی مثل Governance and Standardization یا API-First یا API Monitoring براتون جذاب بود حتمن بگید تا کمی در موردشون گپ بزنیم.

💡♻️ مفهوم و کاربرد API-First Development

توسعه‌ی نرم‌افزار رو میشه مثل ساختمون، بدون نقشه و طرح معماری ساخت! نگید نمیشه؛ چون خیلیا می‌سازن و شده! 😂 تیم‌ها شروع می‌کنن به دیوارکشی (توسعه فرانت‌اند و بک‌اند)، ولی وقتی می‌رسن به اتصالات (Integration)، می‌بینن لوله‌کشی و سیم‌کشی (API) شبیه خونه‌ی پت‌ومت در اومده که از پریز برق آب میاد، لوله برق داره یا درِ پارکینگ به جای کوچه، به پذیرایی همسایه باز می‌شه؛ ساختمونه هم بین ساختمون‌های مجاورش شبیه جوجه کلاغ وسط صد تا جوجه اردکه!

رویکرد سال‌های دور (دلار هزار تومنی) این بود که API یه "محصول جانبی" برای ارتباط با سایر سیستم‌ها محسوب می‌شد؛ یعنی اول بک‌اند نوشته می‌شد، بعد یه قسمتی از اون رو به‌صورت API در معرض استفاده قرار می‌دادن. ریشه‌های این روش، عموما توی خاک سیستم‌های داده‌محور (Data-First) رشد می‌کرد؛ و کمتر "مصرف‌کننده‌محور" (Consumer-Centric) بود.
از طرفی زیاد دیدیم که تیم‌ها معطل هم برای آماده شدن API می‌مونن! یا اعصابشون سر تغییراتی که تیم مقابل روی APIهاش بعد از تفاهم اولیه داده خورد می‌شه! فرانت می‌گه "API تون درست کار نمی‌کنه"، بکند می‌گه "شما درست صداش نمی‌زنین"، و QA هم وسط این دعوا نرخ تعیین می‌کنه! یه بخش بزرگ از این سردردها از نداشتن یه زبون مشترک و قرارداد واضح بین تیم‌هاست.

از طرف دیگه، خیلی وقت‌ها می‌بینیم که بکند کدش رو نوشته، بعد مستندات رو می‌نویسه، بعد معلوم می‌شه مصرف‌کننده یه چیز دیگه می‌خواسته! حالا برگردیم و دوباره بنویسیم؟ یا همینجوری با کثیف‌کاری وصلش کنیم؟ شنیدن جمله "ما بعداً مستندات رو کامل می‌کنیم!" چیز غریب و نادری نیست! ولی واقعیت اینه که توی تیم‌های بالغ، اول API Spec رو می‌نویسن، بعد کد. اگر هم خیلی بالغ باشن، این Spec رو به عنوان یه قرارداد (Contract) بین تیم‌ها در نظر می‌گیرن و با ابزارهای خودکار، صحت پیاده‌سازی و انطباق عینی با طرح و نقشه‌ی اولیه رو کنترل می‌کنن.

🧭 مفهوم API-First یعنی چی؟
مفهوم API-First یعنی قبل از نوشتن کد، اول API رو طراحی کنیم (عموما توسط معمار این اتفاق می‌افته) یعنی بشینیم، فکر کنیم، بنویسیم که چه endpointهایی داریم، چه input/output هایی، چه status codeهایی، چه headerهایی... و همه‌ی این‌ها رو توی یه فایل OpenAPI Spec یا مشابهش ثبت کنیم.
این یعنی API ما از ابتدا مستند شده، با بیزنس، با پروداکت، با تیم‌های همکار می‌شه سناریوسازی و مرور کرد؛ تغییر داد و منطبقش کرد با نیاز واقعی؛ و بعد به کد! بعتر هم برای تغییرات، اول API Spec تغییر می‌کنه و بعد کد. چه اتفاق میوفته؟

- پیش‌بینی‌پذیری: همه می‌دونن قراره چه داده‌ای رد و بدل بشه.
- موازی‌سازی توسعه: تیم‌های مختلف می‌تونن هم‌زمان پیش برن؛ یکی Mock بسازه، یکی پیاده‌سازی واقعی.
- مستندسازی خودکار: چون API از اول با استانداردهایی مثل OpenAPI تعریف میشه، مستندات همیشه با واقعیت هم‌راستا می‌مونن.
- کیفیت بالاتر: چون قبل از کدنویسی، درباره طراحی و naming و consistency فکر می‌کنی.

اینطوری API Spec شما اولا توی سورس‌کنترل نگهداری می‌شه، همواره نسخه تست، استیج رو به صورت live در دسترسی داریم، API Owner هر دامنه مشخصه؛ هر کی عشقش کشید به هر شکلی یه API نمی‌نویسه، breaking changeها و کانفلیکت‌ها قبل از تغییر در API آشکار می‌شن و کلی مزیت دیگه که از حوصله پست تلگرامی خارجه.

رویکرد API-First فقط یک روش نیست، یک تغییر فرهنگی در سازمان، و تغییر استراتژیک در توسعه نرم‌افزاره. این رویکرد، API رو از یک "افزونه" به یک "محصول اصلی" تبدیل می‌کنه که برای تجربه توسعه‌دهنده، سرعت و کیفیت نهایی خیلی حیاتیه. وقتی API-First باشیم، سیستم‌های ما در برابر تغییرات مقاوم‌تر، انعطاف‌پذیرتر و آماده‌تر برای Integration Economy خواهند بود. یکی از شرکت‌هایی که بر اساس رویکرد API First کار می‌کنه زالاندو است که اتفاقا خیلی سخاوتمندانه، یا به توصیف دقیق‌تر، هوشمندانه، دستورالعمل و راهنمای خودش رو سال‌هاست به صورت کدباز منتشر کرده و به نظر من بسیار مستند پخته و خوبیه.

پیشنهاد می‌کنم API رو با ساده‌سازی‌هایی که go, fastAPI, flask, .NET یه موضوع خیلی ساده نبینیم، طراحی و نگهداری بد، مصیبت‌های خودش رو در بلندمدت نشون می‌ده، موقع اینتگریشن‌های بعدی نشون می‌ده و اون وقته که متوجه می‌شیم ای کاش از ابتدا مشورت گرفته بودیم و صرف «کار کردن» API به خودمون نمره قبولی نمی‌دادیم! حتمن این روش پرهزینه‌تر و نیازمند زمان‌ آماده‌سازی و توسعه بیشتریه، ولی عملا سرمایه‌گذاری زمان رشد و اینتگریشن خواهد بود.

Zalando RESTful API and Event Guidelines

💡📡 اهمیت اندازه‌گیری بازگشت سرمایه (ROI) در Platform Engineering

چرا اندازه‌گیری ROI حیاتیه؟
طی چند سال اخیر Platform Engineering نه فقط به عنوان یک شغل یا تیم جدید اضافه شده، بلکه دیگه یک موضوع «اختیاری» نیست؛ یک قابلیت استراتژیک برای بقای رقابتی سازمان‌هاست که به صورت بومی یا خدمت باید داشته باشن. اما خیلی از مدیرهای تصمیم‌گیر در حوزه فنی و بودجه، هنوز توی توجیه دقیق برای سرمایه‌گذاری‌ روی مهندسی پلتفرم مشکل دارن. دلیل؟ نداشتن ماشین‌حسابی که بتونه هزینه‌های پنهان و بهبودها رو به شکل علمی و مستند منعکس کنه. یا به بیانی، عدم وجود یک مدل ROI پایه‌ای (Foundational ROI) که هم شفاف باشه، هم قابل اندازه‌گیری، و هم مستقل از فروشندگان ابزار و سرویس.

این مدل، برخلاف مدل‌های «تخصیصی» (Attributional) یا «محصولی» (Product ROI)، روی بهبودهای بنیادی در بهره‌وری تیم مهندسی تمرکز داره؛ نه فقط صرفه‌جویی در هزینه، بلکه افزایش سرعت تحویل، کیفیت کد، و نوآوری.

مثال واقعی:
شرکتی با ۱۰۰ مهندس، سالانه ۳۰٪ از ظرفیت تیم رو در کارهای دستی (manual toil) از دست می‌ده. با یک پلتفرم مهندسی مناسب، این عدد به ۱۵٪ کاهش پیدا می‌کنه »» یعنی معادل ۱۵ مهندس تمام‌وقت اضافی بدون استخدام جدید!

چهار لایه ROI در مهندسی پلتفرم

۱. پایه‌ای (Foundational)
با تمرکز روی بهره‌وری بنیادی تیم
مثل کاهش manual toil، استانداردسازی محیط

۲. محصولی (Product)
متمرکز روی اثرگذاری روی سرعت تحویل محصول
مثل کاهش MTTR، افزایش deployment frequency

۳. تخصیصی (Attributional)
با هدف نسبت دادن بهبود به ابزار خاص
مثل استفاده از ابزاری که ۲۰٪ سرعت یا حجم کار CI/CD رو بهبود بده

۴. استراتژیک (Strategic)
برای هم‌راستایی با اهداف کسب‌وکار
مثل تسریع ورود به بازار، کاهش ریسک

نکته:
مدل Foundational ROI باید اولین لایه باشد. بدون اون، مدل‌های بالاتر (مثل تخصیصی) دقت و اعتبار ندارن.

ورودی‌های اصلی مدل ROI پایه‌ای
برای محاسبه دقیق، باید ۷ ورودی کلیدی رو جمع‌آوری کرد:

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

۲. میانگین حقوق: حقوق سالانه پایه به ازای هر مهندس، ضرب در ۱.۳ برای در نظر گرفتن ۳۰٪ مزایا و هزینه‌های سربار. این ساده‌ترین معیار برای اضافه کردنه.

۳. ساعات کار روتین هفتگی: میانگین ساعات هفتگی به ازای هر مهندس که صرف وظایف دستی و تکراری می‌شه. این یک معیار تخمینی برای شروعه و می‌تونه در طول زمان بهتر شه.

۴. استفاده فعلی از هوش مصنوعی: فاکتور افزایش بهره‌وری پایه (هیچ = ۱.۰، پایه = ۱.۱۵، پیشرفته = ۱.۳۵، متخصص = ۱.۵). (به نظرم METR study منبع خوبیه؛ اینکه چقدر بهینگی ایجاد کرده که مثلا ۱ یعنی هیچی (یه نفر همون‌قدر کار می‌کنه که می‌کرد)، و ۱.۵ یعنی پنجاه درصد بهبود عملکرد، یا به عبارت ساده‌تر، با یک نفر معادل ۱.۵ نفر خروجی می‌گیرید که این طبق مطالعه METR عالی‌ترین حالته)

۵. آمادگی تیم برای هوش مصنوعی: ضریب ریسک (پایین، متوسط، بالا، متخصص) برای هزینه پیاده‌سازی. یک ضریب ریسک که نشون‌دهنده آمادگی تیم‌های شما برای پذیرش و بهره‌برداری مؤثر از هوش مصنوعیه.

۶. تناوب استقرار: چرخه انتشار ماهانه، هفتگی یا روزانه.بر اساس مدل مطالعاتی DORA، این یک شاخص از منظر بلوغ و کاراییه. تناوب استقرار بالاتر؛ با حلقه‌های بازخورد سریع‌تر، و در نهایت چابکی کسب‌وکار بالاتر همبستگی داره.

۷. صنعت: ضریب نظارتی (عمومی = ۱.۰، مالی = ۱.۳، مراقبت‌های بهداشتی = ۱.۴، استارتاپ = ۰.۸). بر اساس تجربیات، یک ضریب نظارتی برای در نظر گرفتن هزینه‌های سربار complience بر اساس حوزه فعالیت محاسبه می‌شه. صنایع عمومی دارای وزن خنثی هستند (۱.۰)، در حالی که خدمات مالی (۱.۳) و مراقبت‌های بهداشتی (۱.۴) بار سنگین‌تر complience و governcance رو همراه دارن.

۸. سطح بدهی فنی: ضریب تلاش مضاعف برای دست و پنجه نرم‌ کردن با بدهی فنی (پایین = ۰.۹، متوسط = ۱.۰، بالا = ۱.۳، بسیار بالا = ۱.۶). یک ضریب تلاش مرتبط با وضعیت کد و معماری شماست. نسبت بدهی پایین (۰.۹) یعنی تغییرات می‌تونن نسبتاً راحت انجام بشن، در حالی که نسبت بدهی بسیار بالا (۱.۶) نشون می‌ده تقریباً هر بهبودی با هزینه و پیچیدگی نامتناسبی همراهه (میزان بدبختی و فلاکت همراه با اعمال تغییرات).


💬 این یک مقدمه خیلی خیلی خلاصه بود برای سرنخ دادن. اگر به عنوان تک‌لید یا مدیرمهندسی یا ب صورت کلی به این مبحث علاقه‌دارید، حتمن بگید تا در ادامه این بحث، بریم سراغ نحوه محاسبه، خروجی‌هایی که چنین مدل‌هایی ارائه می‌دن و مسئولیت‌ها و استراتژی‌های یک سازمان نرم‌افزاری برای این موضوعات ⚙️

تا دقایق دیگه، رویداد ۳ روزه NET Conf 2025. شروع می‌شه و دات‌نت ۱۰ به صورت رسمی ارائه می‌شه.
مشاهده زنده رویداد
https://www.dotnetconf.net

💬 اگر دوست داشتید در مورد قابلیت‌های مورد انتظار یا حتی مورد نفرتتون 😁 بگید!