‏Guardian: معماری رو به قانونِ اجرایی تبدیل می‌کنه

به گفتهٔ مخزن (ساختهٔ arman-jalili)، Guardian معماری نرم‌افزار رو به محدودیت‌های اجراشدنی تبدیل می‌کنه. به‌جای اینکه برای جلوگیری از انحرافِ معماری به مستندات و code review و دانشِ سینه‌به‌سینه تکیه کنه، پیوسته تأیید می‌کنه که پیاده‌سازی‌ها تو کل مسیر توسعه با تصمیم‌های معماری هم‌خون بمونن. مثلاً اگه معماری بگه بخشِ Payment نباید به Authentication وابسته بشه، Guardian این وابستگی رو تو CI پیدا می‌کنه و قبل از merge جلوش رو می‌گیره.

همه‌چیز حول یه پوشهٔ .pi/ می‌چرخه که منبع حقیقتِ معماریه. از همین مدل، Guardian یه‌سری خروجیِ ملموس تولید می‌کنه: مشخصات معماری (مرز ماژول‌ها، قواعد وابستگی، قراردادهای interface)، سندهای تصمیم معماری (ADR)، epicهای پیاده‌سازی، سیاست‌های اجرای CI، ۲۱ قالبِ prompt برای workflow، و خروجی‌های مخصوص ابزار مثل .claude/ و .github/. اگه تیمی با domain modeling کار کنه، مفاهیمی مثل bounded context و domain event رو هم پشتیبانی می‌کنه، ولی برای بقیه بدون پیش‌زمینهٔ DDD هم مستقیم از ماژول‌ها و ADRها کار می‌کنه.

اجرا از طریق ۷ دستهٔ validator انجام می‌شه که خودکار بر اساس دامنهٔ تغییر (از Simple تا Critical، بر اساس تعداد فایل و خط) انتخاب می‌شن. این validatorها buildو test و lint، مرزهای ماژول و جهت وابستگی، امنیت (نشتِ راز، injection، پیمایش مسیر، دور زدن auth)، تست‌ها، اتصال کامپوننت‌ها و مسائل عملیاتی رو چک می‌کنن. برای تغییرات بحرانی، تأیید انسانی هم لازم می‌شه.

نویسنده می‌گه لنگرگاهِ اصلی، validatorِ «canonical»ه: هر فایلِ پیاده‌سازی یه هدر داره که به یه بخش مشخص از معماری ارجاع می‌ده. وقتی کد و معماری از هم فاصله بگیرن، این ارجاع می‌شکنه و CI فِیل می‌شه. نمونهٔ این هدر این‌شکلیه:

/**
 * Canonical Reference: .pi/architecture/modules/auth-system.md#token-validation
 * Implements: AC-1, AC-2
 * Issue: #42
 * Last Sync: 2026-06-28
 */

طبق مخزن، Guardian تو عمل هم تست شده: باهاش Rigorix ساخته شده، یه runtimeِ قطعی برای coding-agent با حدود ۱۴۶ هزار خط کد Rust تو ۳۰ ماژول و ۵۸۰ کامیت، که یه توسعه‌دهنده تو ۱۱ روزِ فعال نوشته. تو اون پروژه ۱۸ تا ADR معماری رو تعریف کردن و ۷ تا validator روی هر merge اجرا می‌شد و نقض‌های معماری تو CI گرفته می‌شد تا وابستگی به بازبینیِ دستی کم بشه.

نصبش با npx guardian-framework init یا نصب به‌عنوان بستهٔ pi انجام می‌شه و پیش‌نیازش Bun نسخهٔ ۱ به بالاست. از زبون‌های TypeScript، Rust، Python، Go و Java پشتیبانی می‌کنه، یه‌سری مکانیزم برای کم کردن مصرف توکنِ agentها داره و تحت لایسنس MIT منتشر شده.

نکات کلیدی:

• Guardian معماری رو به محدودیت‌های اجرایی تبدیل می‌کنه و نقض رو تو CI به fail شدن merge می‌رسونه
• منبع حقیقت یه پوشهٔ .pi/ه که ازش validatorها، ADRها و سیاست‌های CI ساخته می‌شه
• ۷ دسته validator بر اساس دامنهٔ تغییر (Simple تا Critical) خودکار انتخاب می‌شن
• validatorِ canonical هر فایل رو به یه بخش معماری گره می‌زنه؛ فاصله گرفتن یعنی fail شدن CI
• باهاش Rigorix (۱۴۶K خط Rust) ساخته شده؛ متن‌باز با لایسنس MIT و پشتیبانی از چند زبون