כל פרויקט פונד-טק, ללא קשר לסקופ, יוצא עם לפחות Architecture Decision Record אחד. ADRs הם מסמכים קצרים שמתעדים החלטה, את האלטרנטיבות שנשקלו, ואת השיקולים. אנחנו כותבים אותם תשע שנים. זו הפרקטיקה הכי משעממת שיש לנו, והיא חוסכת יותר זמן מכל תהליך אחר.
התבנית
אנחנו משתמשים בפורמט של ארבעה סעיפים שנכנס לעמוד מודפס:
- Context: מה המצב, אילו אילוצים קיימים
- Decision: מה אנחנו עומדים לעשות, במשפט אחד
- Alternatives: מה עוד שקלנו, למה דחינו כל אחד
- Consequences: מה נהיה קשה יותר, מה נהיה קל יותר, מה נצטרך לבחון מחדש
זהו. בלי טקסי תבניות, בלי דיאגרמות חובה, בלי תהליכי אישור. הכותב עושה commit ל-ADR ב-repo. הצוות סוקר אותו כמו כל PR אחר.
מתי לכתוב אחד
שלושה טריגרים, כל אחד מספיק.
ראשון, כשההחלטה משפיעה על יותר ממערכת אחת או יותר מצוות אחד. בחירת DB לשירות יחיד היא code review. בחירת DB שלושה שירותים ישתמשו בו היא ADR.
שני, כשההחלטה קשה להפיכה. אימוץ ספק, בחירת סכמת אימות, החלטה על מודל מולטי-טננט — כל אלה משנים את עלות כל פרויקט עתידי. מהנדסים עתידיים ירצו לדעת למה.
שלישי, כשההחלטה הייתה במחלוקת. אם שני אנשים סניורים התווכחו שעה, תכתבו את התוצאה כדי שלא תתווכחו שוב בעוד שישה חודשים כשאחד מהם עזב.
מה זה לא
ADRs הם לא מסמכי עיצוב. מסמך עיצוב מסביר איך תבנו משהו. ADR מסביר למה תבנו אותו כך ולא אחרת. קהל שונה, מדף חיים שונה.
ADRs הם לא מסמכים חיים. אנחנו לא מעדכנים אותם כשההחלטה משתנה — אנחנו כותבים חדש שגובר על הישן, ומקשרים בין השניים. ה-git log של תיקיית docs/adr/ הוא היסטוריית השיקולים של הפרויקט.
מה זה באמת חוסך
הערך לא בולט בשבוע הראשון. הוא בולט בחודש התשיעי, כשמהנדס חדש שואל ״למה בחרנו Postgres במקום DynamoDB״, והתשובה נמצאת בקובץ של ארבעה פסקאות שלקח עשר דקות לכתוב. תכפילו את זה בכל onboarding לכל אורך חיי המערכת.
לעבודת הייעוץ שלנו, ADRs הם איך שאנחנו משאירים בסיס קוד שצוות הלקוח באמת יכול להחזיק. אנחנו לא נעלמים אחרי המסירה. ה-ADRs כן.