تصور کنید یک برنامه نویس ارشد را استخدام کرده‌اید که کد می‌زند، اما وقتی از او می‌خواهید معماری سیستم را مستند کند، فقط چند خط توضیح ساده می‌دهد و تمام جزئیات حیاتی را فراموش می‌کند. این دقیقاً همان نقطه‌ای است که اکثر عامل‌های کدنویسی فعلی در آن شکست می‌خورند. خروجی‌های رایج عامل‌های امروزی، طرح‌های پایگاه‌داده «تنبل» و نقاط انتهایی API هستند که فاقد جزئیات حیاتی محیط عملیاتی (Production) می‌باشند.
طبق اعلام توسعه‌دهندگان این پروژه در ۱۶ ژوئیه ۲۰۲۶، کتابخانه engineering-docs برای حل این مشکل معرفی شد. این ابزار با ارائه ۲۱ مهارت تخصصی، ساختار سخت‌گیرانه مستندات مهندسی ارشد را مستقیماً به جریان‌های کاری عامل (Agent) تزریق می‌کند تا خلأ موجود بین کدنویسی سریع و مستندسازی اصولی پر شود.
روتین کارهای تکراری
بسیاری از توسعه‌دهندگان با حجم تکراری مستندسازی دست‌وپنجه نرم می‌کنند. برای بسیاری، شروع یک قابلیت جدید با یک روتین کلافه‌کننده همراه است: باز کردن یک سند خالی، تلاش برای به یاد آوردن بخش‌های یک مشخصات فنی (Technical Spec) درست و کپی کردن یک قالب قدیمی ADR از پروژه‌های قبلی، که در نهایت مجبورند بخش‌های نامرتبط آن را پاک کنند.
در شتاب توسعه، بسیار رایج است که توسعه‌دهندگان در میانه‌ی مسیر متوجه شوند عناصر حیاتی فراموش شده‌اند؛ مواردی مانند مراحل بازگشت (Rollback)، کنترل دسترسی (Access Control) یا پروتکل‌های شکست برای قطعی‌های ساعت ۳ صبح. این «فرهنگ میان‌بر» باعث می‌شود ویژگی‌هایی عرضه شوند که هیچ رکورد تصمیم معماری (ADR) شفاف، هیچ مدل تهدیدی و هیچ برنامه بازیابی از فاجعه‌ای ندارند. نتیجه این است که شش ماه بعد، تیم اغلب مطمئن نیست که چرا یک تصمیم خاص در معماری گرفته شده است. این وضعیت دقیقاً با چالش رانش مستندات همسو است که در آن ناسازگاری میان کد و مستندات قدیمی به منشأ بروز باگ‌های جدی در خروجی‌های هوش مصنوعی تبدیل می‌شود.
پر کردن شکاف دانش در هوش مصنوعی
همان‌طور که در تحلیل‌های قبلی ما درباره‌ی محدودیت‌های استدلال در مدل‌های زبانی اشاره کردیم، عامل‌ها با وجود توانایی در پیش‌نویس کد، معمولاً فاقد دانش درونی استانداردهای صنعتی هستند. وقتی از یک مدل زبانی بزرگ (LLM) — مثل کتابخانه‌داری که میلیاردها صفحه را خوانده و حالا با همان لحن کتاب‌ها جواب می‌دهد — می‌خواهید «پایگاه‌داده این قابلیت را طراحی کند»، معمولاً فقط چند دستور CREATE TABLE می‌دهد. او به ندرت استراتژی ایندکس‌گذاری، بازگشت مهاجرت (Migration Rollback) یا استدلال پشت یک انتخاب نرمال‌سازی خاص را در نظر می‌گیرد.
به همین ترتیب، پیش‌نویس‌های API اغلب با نقاط انتهایی (Endpoints) ارائه می‌شوند اما بدون قرارداد خطا (Error Contract)، بدون استراتژی نسخه‌بندی (Versioning) و بدون اشاره‌ای به محدودیت نرخ درخواست‌ها (Rate Limiting).
بر اساس مستندات این پروژه در dev.to، مشکل این نیست که عامل‌ها تنبل هستند؛ بلکه آن‌ها صرفاً در حال تطبیق الگو (Pattern-matching) بر اساس مشخصات نیمه‌کاره‌ای هستند که در داده‌های آموزشی دیده‌اند. آن‌ها ذاتاً نمی‌دانند که یک سند معماری واقعی سیستم شکل خاصی دارد، یک مدل تهدید خوب باید از متد STRIDE پیروی کند، یا طراحی API مناسب باید به مدل بلوغ ریچاردسون (Richardson Maturity Model) ارجاع دهد. engineering-docs با تبدیل مستندات به مجموعه‌ای از مهارت‌های مجزا و قابل بارگذاری، به جای استفاده از یک پرامپت سیستمی غول‌پیکر و مبهم، این خلأ را پر می‌کند. این رویکرد ماژولار برای جلوگیری از از دست رفتن جزئیات فنی هنگام انتقال مهارت‌ها طراحی شده تا اطمینان حاصل شود که استانداردهای مهندسی در حین انتقال بین عامل‌ها تخریب نمی‌شوند.
چارچوب مهارت‌های پنج مرحله‌ای
این کتابخانه ۲۱ مهارت خود را در پنج فاز عملیاتی سازماندهی کرده است تا بازتابی از چرخه حیات واقعی نرم‌افزار باشد:
- کشف و برنامه‌ریزی (Discovery and Planning): این فاز برای ایده‌های اولیه است. شامل مهارت‌هایی برای ساخت پرسونای کاربر بر اساس «کارهای مورد نیاز» (Jobs-to-be-done) و معیارهای موفقیت واقعی است تا از جایگذاری‌های کلی و توخالی اجتناب شود. همچنین ابزارهایی برای طرح‌های پروژه، نقاط عطف (Milestones)، ماتریس RACI و ساختار شکست کار (WBS) ارائه می‌دهد.
- مشخصات و امکان‌سنجی (Specification and Feasibility): پیش از نوشتن کد، یک مهارت مخصوص، مشخصات نرم‌افزاری (SRS) را طبق استاندارد ISO/IEC/IEEE 29148 و با استفاده از سینتکس EARS تولید می‌کند. یک مهارت مجزای «مطالعه امکان‌سنجی رسمی» نیز به توسعه‌دهندگان اجازه می‌دهد تا پیش از تخصیص منابع، منطق ایده را بررسی کنند.
- معماری و طراحی محصول (Architecture and Product Design): این بزرگ‌ترین گروه است و بیشترین ارزش روزمره را فراهم می‌کند. از مدل C4 برای معماری سیستم و طراحی پایگاه‌داده با ERDهای واقعی و لغت‌نامه داده‌های مناسب (شامل ایندکس‌ها و قوانین Cascade) استفاده می‌کند. طراحی API با OpenAPI 3.1 و مدیریت خطای RFC 7807 همسو است. رکوردهای تصمیم معماری (ADR) به گونه‌ای نوشته می‌شوند که پس از پذیرش تغییرناپذیر باشند و به‌طور مشخص جایگزین‌ها و سبک-سنگین کردن‌های (Trade-offs) فنی را شرح دهند.
- ریسک و کیفیت (Risk and Quality): پیاده‌سازی مدل‌سازی تهدید از طریق STRIDE و OWASP برای شناسایی حفره‌های امنیتی پیش از حسابرسی‌های رسمی. این فاز همچنین شامل اسناد استراتژی تست و طرح‌های پیاده‌سازی است که ترتیب کارها را بر اساس وابستگی‌ها (Dependency) تعیین می‌کند، نه صرفاً به صورت یک لیست ساده از وظایف.
- استقرار و عملیات (Deployment and Operations): ارائه طرح‌های استقرار با گیت‌های صریح «اجرا/توقف» (Go/No-go gates). این بخش شامل اسناد SLO و بودجه خطا (Error Budget)، دفترچه‌های راهنمای (Runbook) بر اساس فرمت SRE گوگل (که هشدارها را به تشخیص و سپس به ارجاع متصل می‌کند) و طرح‌های بازیابی از فاجعه با اهداف واقعی RTO و RPO است. در نهایت، یک مهارت «پست‌مورتم بدون سرزنش» (Blameless Postmortem) با استفاده از متد «پنج چرا» (Five Whys) برای اصلاح سیستم‌ها به جای مقصر دانستن افراد وجود دارد.
مکانیسم ارکستراسیون و مصاحبه
یک مهارت ارکستراتور مرکزی به نام using-engineering-docs به‌عنوان رابط اصلی عمل می‌کند. به‌جای اجرای فوری دستور، عامل ابتدا ۳ تا ۵ سؤال شفاف‌کننده از کاربر می‌پرسد؛ دقیقاً همان‌گونه که یک مهندس ارشد پیش از کدنویسی، روی یک تیکت مبهم بازخواست می‌کند و آن را به چالش می‌کشد.
برای مثال، اگر کاربر طراحی پایگاه‌داده را بدون ذکر حجم مورد انتظار خواندن و نوشتن (Read/Write Volume) بخواهد، عامل این معیارها را مطالبه می‌کند. اگر طراحی یک API درخواست شود اما ذکر نشود که آیا باید از کلاینت‌های موبایل با اتصالات ناپایدار پشتیبانی کند یا خیر، عامل برای شفاف‌سازی سؤال می‌پرسد.
برای جلوگیری از توهم (Hallucination) — یعنی زمانی که اسناد کامل به نظر می‌رسند اما حاوی فرض‌های ناگفته و پنهان هستند — این کتابخانه از نشانگرهای بصری خاص استفاده می‌کند:
- فرض‌ها با لوزی نارنجی (🔶) علامت‌گذاری می‌شوند.
- پرسش‌های باز با دایره آبی (🔵) مشخص می‌شوند.
این سیستم اجازه می‌دهد بازبین‌ها فوراً تصمیمات فنی تأییدشده را از بخش‌هایی که هنوز نیاز به تصمیم‌گیری دارند، تشخیص دهند و از پذیرش ناخودآگاه فرض‌های غلط جلوگیری شود.
یکپارچگی و سازگاری
این کتابخانه برای استقرار سریع از طریق npx engineering-docs طراحی شده است. نصب‌کننده، محیط را شناسایی کرده و می‌پرسد که از کدام چارچوب عامل (Agent Harness) استفاده می‌شود. این ابزار از چندین چارچوب اصلی پشتیبانی می‌کند:
- Claude Code: پشتیبانی از نصب مستقیم پلاگین از طریق مارکت‌پلیس با دستور
/plugin marketplace add fattain-naime/engineering-docsو/plugin install engineering-docs@engineering-docs. - Cursor و Windsurf: مدیریت از طریق فایل‌های قوانین .mdc.
- GitHub Copilot، Kimi Code و Codex.
- Gemini: یکپارچگی از طریق Antigravity.
برای کسانی که ترجیح می‌دهند از npx استفاده نکنند، مخزن پروژه اسکریپت‌های ساده Shell و PowerShell را فراهم کرده تا کاربر دقیقاً ببیند چه چیزی کپی می‌شود. فرآیند نصب کاملاً غیرتخریبی است؛ یعنی هرگز فایل‌های موجود مثل AGENTS.md ،GEMINI.md یا CLAUDE.md را بازنویسی نمی‌کند و در صورت وجود این فایل‌ها، یک پیام Skip ثبت می‌کند تا پیکربندی‌های فعلی کاربر محافظت شود.
چرا مهارت‌های ماژولار بر پرامپت‌های غول‌پیکر پیروز می‌شوند؟
نویسنده پروژه از طریق تجربه دریافت که پرامپت‌های سیستمی واحد و عظیم اغلب باعث می‌شوند عامل‌ها محدودیت‌های خاص را نادیده بگیرند یا بیش از حد کلی صحبت کنند تا مفید باشند. پرامپتی که سعی کند همزمان یک ADR، یک طراحی پایگاه‌داده و یک پست‌مورتم حادثه را پوشش دهد، یا جزئیات لازم را از دست می‌دهد یا از توانایی عامل در ردیابی تمام الزامات فراتر می‌رود.
با تقسیم منطق به ۲۱ مهارت متمرکز، عامل فقط محدودیت‌های مرتبط با آن تکلیف خاص را بارگذاری می‌کند. یک مهارت طراحی پایگاه‌داده فقط باید در طراحی دیتابیس متخصص باشد، نه در برنامه‌ریزی بازیابی از فاجعه. این ماژولار بودن اجازه می‌دهد یک گردش کار ترکیب‌پذیر ایجاد شود که در آن ارکستراتور فقط مهارت‌های ضروری را برای یک پروژه خاص توالی‌بندی می‌کند. این امر از «خستگی چک‌لیست» (Checklist Fatigue) جلوگیری می‌کند، جایی که هر پروژه مجبور است از یک فرآیند صلب و نامرتبط عبور کند. این توازن میان انعطاف‌پذیری و سخت‌گیری، یادآور بحث‌های حاکمیت AI است که بر لزوم تفکیک میان آگاهی عامل از قوانین و اجرای سخت‌گیرانه آن‌ها تأکید دارد.
از دیدگاه کاربردی، این رویکرد نقش توسعه‌دهنده را از یک «مهندس پرامپت» به یک «بازبین فنی» تغییر می‌دهد. به‌جای جنگیدن با هوش مصنوعی برای گنجاندن یک طرح بازگشت (Rollback plan)، توسعه‌دهنده صرفاً طرحی را بازبینی می‌کند که عامل به دلیل وجود مهارت در کتابخانه، مجبور به تولید آن بوده است.
نقشه راه آینده و مشارکت‌ها
کتابخانه مهارت‌ها یک پروژه در حال تکامل است. نویسنده قصد دارد کتابخانه را در دو حوزه خاص گسترش دهد:
۱. مهندسی داده: افزودن عمق بیشتر به طراحی خط لوله داده (Data Pipeline) و طراحی ETL.
۲. مهاجرت سیستم‌های قدیمی (Legacy Migration): ایجاد یک مهارت تخصصی برای برنامه‌ریزی مهاجرت هنگام خروج از زیرساخت‌های قدیمی، مانند محیط‌های اشتراکی (Shared Hosting) قدیمی.
توسعه‌دهندگان می‌توانند تحت لایسنس MIT در گیت‌هاب (github.com/fattain-naime/engineering-docs) به این پروژه کمک کنند. راهنمای مشارکت توضیح می‌دهد که Frontmatterهای YAML و بلوک‌های کوچینگ (Coaching blocks) چگونه ساختار یافته‌اند، به این معنی که افزودن یک مهارت جدید از یک الگوی تثبیت‌شده پیروی می‌کند و نیازی به مهندسی معکوس ندارد.
اگر تا به حال اتفاق افتاده که قابلیتی را عرضه کنید و هفته‌ها بعد متوجه شوید هیچ‌کس به یاد نمی‌آورد چرا یک سبک-سنگین کردن معماری خاص انجام شد، پیاده‌سازی این نرینگ‌های حفاظتی (Guardrails) ممکن است تنها راه برای تضمین بقای حافظه سازمانی در سرعت توسعه AI باشد.
گام بعدی شما
- اگر از Cursor یا Claude Code استفاده می‌کنید، کتابخانه را با دستور npx نصب کنید و تفاوت خروجی‌های معماری را بسنجید.
- در مستندات خود از نشانگرهای 🔶 و 🔵 برای تفکیک فرض‌ها از واقعیت‌ها استفاده کنید تا نرخ خطای بازبینی کاهش یابد.
- مهارت‌های مربوط به مدل‌سازی تهدید STRIDE را در گردش کار امنیت خود بگنجانید.
اما داستان سخت‌افزاری اجرای این عامل‌های پیچیده حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.
گفتگو