نوشتن مستند معماری با هوش مصنوعی
مسیر یک قابلیت را در کد دنبال کنید و مسوولیت ماژولها، محل ثبت داده و وابستگیهایی را بنویسید که برای تغییر یا تحویل پروژه اهمیت دارند.
نوشتن مستند معماری با هوش مصنوعی وقتی ارزش دارد که کسی بتواند بعد از خواندنش یک تغییر واقعی را با خیال روشنتری شروع کند. مثلا سفارش از پنل ثبت میشود اما وضعیت پرداخت را سرویس دیگری تغییر میدهد. اگر مستند فقط فهرست پوشهها را تکرار کند، همکار تازه هنوز نمیداند موقع اصلاح یک سفارش کدام قسمت باید بررسی شود. اسکیل architecture-docs از ایجنتتون میخواهد این مسیر را از روی کد و تنظیمات دنبال کند.
اول ببینید در پروژه سند قابل اعتمادی وجود دارد یا نه. شاید به جای ساخت فایل جدید، اضافه کردن یک توضیح به راهنمای موجود کافی باشد. اگر بخشی هنوز ساخته نشده، فقط تصمیمی را که تیم واقعا تایید کرده با وضعیت درست بنویسید. برای بخشی که اجرا میشود میتوانید از نقطه ورود، فراخوانیها و محل ثبت تغییر شواهد بیاورید و هر اختلاف میان طرح و پیادهسازی را برای بررسی نگه دارید.
کاربردها
- مستند معماری موجود را با یک پرسش واقعی امتحان کنید تا معلوم شود خواننده پیش از دست بردن در کد چه چیزی کم دارد.
- مرز ماژول را با کاری که انجام میدهد و دادهای که مالک آن است توضیح بدهید، نه فقط با اسم مسیر فایل.
- مسیر داده را از درخواست اولیه تا نوشتن نتیجه دنبال کنید و جایی را که سرویس دیگری وارد میشود مشخص کنید.
- هر تصمیم طراحی را با وضعیت تاییدشده یا در حال بررسی نگه دارید تا پیشنهاد آینده با رفتار فعلی نرمافزار اشتباه نشود.
- برای تحویل به همکار بعدی توضیح بدهید تغییر در یک قسمت چه بخشهای دیگری را نیازمند بازبینی میکند.
نصب و استفاده
- بسته رسمی docs-governance با راهنماهای مشترک و مخزن مجاز پروژه لازم است. برای بررسی سابقه Git و برای ابزارهای محلی اختیاری Python 3 را آماده کنید.
- مثلا بگویید «مسیر تغییر وضعیت سفارش را پیدا کن. بنویس چه بخشی درخواست را میگیرد، کدام بخش وضعیت را عوض میکند و کجا هنوز مدرک کافی نداریم.»
- متن را با صاحب همان قسمت بازبینی کنید و اختلافهای حلنشده را قبل از معرفی سند به عنوان راهنمای جاری مشخص نگه دارید.
سوالات متداول
منبع
ساخته qshanx. نام اصلی: architecture-docs، منتشرشده در GitHub با مجوز MIT.
مشاهده در GitHub