אי אפשר ללחוץ על "pause" בפיתוח. זה הדבר הראשון שצריך לקבל. כרטיסים (tickets) ממשיכים להגיע, לקוחות מצפים למשלוחים, והקוד הקיים שלכם לא מפסיק לרוץ רק בגלל שהחלטתם לתעד אותו. אף מנהל הנדסה לא ייתן אור ירוק להקפאה של חודש שלם כדי שהצוות יוכל לכתוב את המפרט (specification) שהיה אמור להיות קיים מהיום הראשון. OpenSpec נבנה עבור המציאות, לא עבור פנטזיות של פרויקטים חדשים (greenfield). הוא עובד הכי טוב כשמחברים אותו למה שכבר יש לכם, כולל הלקוחות.
המטרה כאן היא לא כתיבה מחדש. זוהי ארכיאולוגיה כנה. אתם חופרים את מה שבאמת רץ בייצור (production), מתארים אותו במדויק, ומאפשרים לתיאור הזה להתפתח ככל שהקוד שלכם מתפתח. כאשר המפרט שלכם תואם למערכת שלכם, אתם מקלים על החיים של המהנדסים שיצטרפו ברבעון הבא ועל כלי ה-AI שיושבים עכשיו ב-IDE שלכם. הנה איך עושים זאת מבלי לפספס אף גרסה (release).
התחילו במה שאתם באמת עושים
פתחו את ה-repository שלכם ותראו תיקיות בשם controllers, models, services, ו-utils. אלו שכבות טכניות, והן משקרות לכם. הן לא מתארות מה המערכת שלכם עושה עבור העסק. תיקייה מלאה בקבצי JavaScript לא מסבירה איך הזמנה הופכת למשלוח. כדי לבצע retrofitting ל-OpenSpec, אתם צריכים לחשוב במונחים של יכולות (capabilities).
חפשו את הפעולות העסקיות היציבות ששורדות גם אם הייתם כותבים מחדש את כל ה-stack בשפה אחרת. ברוב חברות המוצר, אלו מופיעות שוב ושוב: הזמנות (Orders), חיוב (Billing), מלאי (Inventory), לקוחות (Customers), והתראות (Notifications). תנו שמות לחמישה עד שמונה מהיכולות הליבה הללו.
עבור כל אחת מהן, אילצו את עצמכם לענות על חמש שאלות ספציפיות. איזו בעיה בעולם האמיתי היכולת הזו פותרת? איפה הקוד באמת נמצא — בשירות אחד, בשלושה מיקרו-שירותים (microservices), או במודול ישן (legacy) שאף אחד לא רוצה לגעת בו? מה מפעיל אותה: לחיצת משתמש, משימת cron מתוזמנת, או inbound webhook? איזה נתונים נכנסים ואיזה נתונים יוצאים? ולבסוף, אילו מערכות אחרות תלויות בה, כלומר מה יישבר אם החלק הזה יפסיק לעבוד?
היו כנים בצורה ברוטלית. אם יכולת ה-"Customers" שלכם מפוזרת על פני Rails monolith, Node API, ו-CRM חיצוני, כתבו זאת בדיוק כך. המפה שלכם חייבת להיראות כמו השטח, לא כמו חלום של אדריכל.
כתבו את האמת, לא את רשימת המשאלות
המשפט המסוכן ביותר בכל מאמץ תיעוד הוא: "בזמן שאנחנו כותבים את זה, כדאי שגם נתקן את זה". עצרו. אתם לא מעצבים מחדש את תהליך התשלום (checkout flow). אתם מתארים את תהליך התשלום שגובה כרטיסי אשראי אמיתיים ברגע זה.
אם ביצוע הזמנה מפעיל לכידה מיידית של תשלום ואז שולח אימייל דרך background worker, תעדו את הרצף המדויק הזה. אל תכניסו תור אירועים (event queue) שאתם מתכננים להוסיף ברבעון הבא. אל תעמידו פנים שהולידציה (validation) מתבצעת בקצה ה-API אם היא למעשה נמצאת עמוק בתוך מחלקת שירות (service class). דיוק חשוב הרבה יותר משאיפות.
תיעוד שגוי גרוע יותר מאפס תיעוד. הוא מאמן עובדים חדשים לצפות להתנהגות שאינה קיימת. הוא שולח עוזרי קוד מבוססי AI לנתיבים דמיוניים המבוססים על מחשבות של "ככה היית רוצה שזה יהיה". כאשר המפרט שלכם תואם לייצור, אתם יוצרים בסיס אמין. הדיבאגינג (debugging) הופך למהיר יותר כי אתם מפסיקים לנחש לגבי הזרימה ה"מיועדת". הרפקטורינג (refactoring) הופך לבטוח יותר כי אתם יודעים שנקודת ההתחלה היא אמיתית.
חלצו חוזים (Contracts) מה-APIs שלכם
נקודות הקצה (endpoints) של ה-API שלכם כבר אוכפות חוקים. הן פשוט שומרות אותם במצב מרומז (implicit). ביצוע retrofitting ל-OpenSpec פירושו להביא את החוקים הללו אל האור.
התחילו עם קלטים (inputs) ואימות (validation). מה נקודת הקצה באמת מקבלת? תעדו את הסוגים (types), השדות הנדרשים, אורכים מקסימליים, ותלות בין שדות. לאחר מכן תארו את ההתנהגות העסקית. האם הקריאה הזו יוצרת רשומה, מפעילה תופעת לוואי (side effect), או פשוט מאמתת מצב (state) מול שירות אחר? היו ספציפיים.
לבסוף, קטלגו את התגובות (responses). מה ההצלחה מחזירה? מהם קודי השגיאה המדויקים ותחת אילו תנאים הם מופיעים? אל תכתבו "מחזיר שגיאה". כתבו "מחזיר 422 כאשר כתובת החיוב חסרה ו-409 כאשר המלאי כבר נשמר על ידי תהליך אחר". רמת דיוק כזו הופכת נתיב מעורפל לחוזה (contract) שצוותי פרונטנד, מהנדסי QA וכלים אוטומטיים יכולים לסמוך עליו.
צדו את החוקים הנסתרים
Some of the most expensive knowledge in your system lives in the gaps. It is buried in conditional blocks inside service classes, tucked into database triggers, or written into stored procedures that no one has touched in two years. These are your business rules, and they are usually rediscovered during outages or by cornering the one engineer who has been there since the beginning.
Pull them into daylight. Start with the ones you already know. Orders above a certain value need manager approval before they proceed. Inactive user accounts cannot create new orders. Refunds are only permitted before settlement completes. Write each rule next to the capability it governs, in language clear enough that a product manager could read it without a translator.
When you centralize these rules, you do more than document them. You expose duplication. You reveal conflicts. And you give the entire team a single place to debate policy before someone commits a one-line change that accidentally violates a constraint you forgot existed.
Map the Plumbing
Modern systems run on events. An action in one service ripples through half a dozen others before anything visible reaches the user. You need to chart those ripples. Map the flow from one event to the next for your core workflows. Order created leads to inventory reserved, which waits for payment confirmed. Draw the full chain, even if some links feel fragile or use different protocols.
Do not stop at internal traffic. External services are part of your system whether you treat them that way or not. For each integration, record its purpose, how your application authenticates, and how it fails. Does the payment gateway timeout after thirty seconds and return a generic 500? Does the shipping API return malformed JSON on weekends? Does the identity provider revoke refresh tokens earlier than its own documentation claims? These details look trivial