עקרונות להוספת פיצ’ר לסטיקי-נוטס

הפיצ’ר של הפתקים הדביקים צובר משטחים לאורך זמן — קובץ ב-CodeKeeper ← לוח ← רינדור מארקדאון ← קובץ בריפו ממורר. כל תוספת כזו נוטה לגלות מחדש את אותן מלכודות, כי הן אינן בקוד של פיצ’ר בודד אלא בחוזה המשותף. העמוד הזה מרכז אותן, כדי שהפיצ’ר הבא (או סוכן AI שממש אותו) יקרא אותן פעם אחת במקום לגלות אותן שוב בפרודקשן.

זהו עמוד כוונה — הוא מסביר למה הדברים בנויים כפי שהם. הסמכות היא תמיד הקוד; אם עמוד זה סותר את הקוד, הקוד צודק והסתירה היא ממצא לדיווח.

התיעוד מחולק לעמודים לפי השכבה שבה חי הקוד, ולא לפי פיצ’ר, כי הכללים שחוזרים בכמה פיצ’רים שייכים לשכבה:

  • עמוד השרת — מה נשמר במסד, מי אוכף, ומה עובר בין הוובאפ, שרת ה-MCP והדפדפן.

  • עמוד מנוע המארקדאון — איך טקסט הפתק הופך לתצוגה שורה אחר שורה, בלי לאבד את המיפוי למקור.

  • עמוד הממשק — איך הפתק ממוקם, נגלל, נצבע ומגיב למשתמש.

נושא שחוצה שכבות מפוצל לפי השכבה, ובכל צד יש קישור לצד השני; תת-סעיף קטן שמשלים חוזה של שכבה אחרת נשאר ליד החוזה שלו, כמו הבורר בסעיף הצבע. הגעתם לכאן מכתובת ישנה של סעיף שעבר? הוא רשום ב-סעיפים שעברו לעמודים אחרים, עם קישור למקום החדש.

התיעוד למשתמש הוא חלק מהפיצ’ר

חשוב

כל פיצ’ר חדש בפתקים, וכל שינוי בהתנהגות קיימת, מעדכן את פתקים דביקים (Sticky Notes) באותו PR.

העמוד הזה מתאר איך לבנות — מלכודות, חוזים בין שכבות, מה לבדוק ובמה. העמוד למשתמש מתאר מה קורה — מה רואים, מה ברירת המחדל, איפה יש מתג ואיפה אין. שינוי בהתנהגות שייך לשם, גם כשהוא נראה קטן.

מה נחשב שינוי בהתנהגות: ברירת מחדל שמתהפכת, מצב מיקום שמתחיל או מפסיק להיות זמין, יעד חדש לפתק, מגבלה או מכסה שמשתנה, ותוספת לתת-קבוצת המארקדאון. שינוי פנימי שאינו נראה מבחוץ — ריפקטור, אינדקס, סדר קריאות — אינו מצריך עדכון.

בלי כפילות בין שני העמודים. עובדה שכתובה בשניהם מתיישנת באחד מהם, ואז שניהם אומרים דברים שונים על אותו קוד. הכלל הוא הפרדה לפי שאלה: התנהגות נראית נכתבת בעמוד המשתמש בלבד, והנימוק ההנדסי — למה זה בנוי ככה, מה נשבר בלי זה — נכתב כאן בלבד. כשצריך את שניהם, כותבים כל חצי במקומו ומקשרים ביניהם ב-:doc:, כפי שעמוד המשתמש כבר עושה בכל מקום שבו הוא נוגע בנימוק הנדסי.

התיעוד אינו סמכות על הקוד. אם בזמן העדכון מתגלה שמה שכתוב בעמוד המשתמש כבר אינו נכון — זה ממצא לתקן, לא רקע להתעלם ממנו. פסקת העיגון בפתקי ריפו שרדה כך סבב שלם אחרי שההתנהגות השתנתה תחתיה.

סעיפים שעברו לעמודים אחרים

העמוד הזה פוצל (What’s New), וכל הסעיפים שלו, חוץ מהפתיח ומ-התיעוד למשתמש הוא חלק מהפיצ’ר, עברו עם התוויות שלהם לעמודים שבראשו. :ref: לתווית כזו ממשיך להגיע לסעיף שלה, אבל כתובת ישנה מהצורה sticky_notes_extending.html#<תווית> נפתחת עכשיו בראש העמוד הזה, כי התווית כבר אינה בו. אלה כל התוויות שעברו, בסדר אלפביתי, וכל אחת היא קישור למקום שבו היא נמצאת היום. כתובת שבסופה מספר רץ, כמו #id12, אינה תווית, ולכן אינה ברשימה.