diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index 5d3b674..101243b 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -57,12 +57,22 @@ const config: Config = { onBrokenLinks: 'warn', - // Even if you don't use internationalization, you can use this field to set - // useful metadata like html lang. For example, if your site is Chinese, you - // may want to replace "en" with "zh-Hans". + // Internationalization configuration for English and Hebrew i18n: { defaultLocale: 'en', - locales: ['en'], + locales: ['en', 'he'], + localeConfigs: { + en: { + label: 'English', + direction: 'ltr', + htmlLang: 'en-US', + }, + he: { + label: 'עברית', + direction: 'rtl', + htmlLang: 'he', + }, + }, }, markdown: { @@ -138,7 +148,7 @@ const config: Config = { require.resolve('@easyops-cn/docusaurus-search-local'), { hashed: true, - language: ['en'], + language: ['en', 'he'], highlightSearchTermsOnTargetPage: true, explicitSearchResultPath: true, indexBlog: false, @@ -205,6 +215,10 @@ const config: Config = { position: 'left', label: 'FAQ', }, + { + type: 'localeDropdown', + position: 'right', + }, { href: 'https://github.com/agenticoding/agenticoding.github.io', label: 'GitHub', diff --git a/website/i18n/he/code.json b/website/i18n/he/code.json new file mode 100644 index 0000000..65d2ac1 --- /dev/null +++ b/website/i18n/he/code.json @@ -0,0 +1,540 @@ +{ + "theme.ErrorPageContent.title": { + "message": "הדף קרס.", + "description": "The title of the fallback page when the page crashed" + }, + "theme.BackToTopButton.buttonAriaLabel": { + "message": "גלול חזרה למעלה", + "description": "The ARIA label for the back to top button" + }, + "theme.blog.archive.title": { + "message": "ארכיון", + "description": "The page & hero title of the blog archive page" + }, + "theme.blog.archive.description": { + "message": "ארכיון", + "description": "The page & hero description of the blog archive page" + }, + "theme.blog.paginator.navAriaLabel": { + "message": "רשימת דפי הבלוג", + "description": "The ARIA label for the blog pagination" + }, + "theme.blog.paginator.newerEntries": { + "message": "הכי חדש", + "description": "The label used to navigate to the newer blog posts page (previous page)" + }, + "theme.blog.paginator.olderEntries": { + "message": "ישן יותר", + "description": "The label used to navigate to the older blog posts page (next page)" + }, + "theme.blog.post.paginator.navAriaLabel": { + "message": "רשימת חדשות של הבלוג", + "description": "The ARIA label for the blog posts pagination" + }, + "theme.blog.post.paginator.newerPost": { + "message": "חדש יותר", + "description": "The blog post button label to navigate to the newer/previous post" + }, + "theme.blog.post.paginator.olderPost": { + "message": "ישן יותר", + "description": "The blog post button label to navigate to the older/next post" + }, + "theme.tags.tagsPageLink": { + "message": "כל התגיות", + "description": "The label of the link targeting the tag list page" + }, + "theme.colorToggle.ariaLabel.mode.system": { + "message": "מצב מערכת", + "description": "The name for the system color mode" + }, + "theme.colorToggle.ariaLabel.mode.light": { + "message": "מצב בהיר", + "description": "The name for the light color mode" + }, + "theme.colorToggle.ariaLabel.mode.dark": { + "message": "מצב כהה", + "description": "The name for the dark color mode" + }, + "theme.colorToggle.ariaLabel": { + "message": "החלף בין מצב כהה לבהיר (כרגע {mode})", + "description": "The ARIA label for the color mode toggle" + }, + "theme.docs.breadcrumbs.navAriaLabel": { + "message": "נתיב ניווט", + "description": "The ARIA label for the breadcrumbs" + }, + "theme.docs.DocCard.categoryDescription.plurals": { + "message": "פריט אחד|{count} פריטים|{count} פריטים|{count} פריטים", + "description": "The default description for a category card in the generated index about how many items this category includes" + }, + "theme.docs.paginator.navAriaLabel": { + "message": "רשימת דוקומנטאציה", + "description": "The ARIA label for the docs pagination" + }, + "theme.docs.paginator.previous": { + "message": "הקודם", + "description": "The label used to navigate to the previous doc" + }, + "theme.docs.paginator.next": { + "message": "הבא", + "description": "The label used to navigate to the next doc" + }, + "theme.docs.tagDocListPageTitle.nDocsTagged": { + "message": "מסמך אחד מתויג|{count} מסמכים מתויגים|{count} מסמכים מתויגים|{count} מסמכים מתויגים", + "description": "Pluralized label for \"{count} docs tagged\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.docs.tagDocListPageTitle": { + "message": "{nDocsTagged} עם התגית \"{tagName}\"", + "description": "The title of the page for a docs tag" + }, + "theme.docs.versions.unreleasedVersionLabel": { + "message": "דוקומנטאציה שעדיין לא יצאה לאוויר ל {siteTitle} {versionLabel} גרסא.", + "description": "The label used to tell the user that he's browsing an unreleased doc version" + }, + "theme.docs.versions.unmaintainedVersionLabel": { + "message": "דוקומנטאציה זו {siteTitle} {versionLabel}, כבר לא נתמכת.", + "description": "The label used to tell the user that he's browsing an unmaintained doc version" + }, + "theme.docs.versions.latestVersionSuggestionLabel": { + "message": "לדוקומנטאציה עדכנית, ראה {latestVersionLink} ({versionLabel}).", + "description": "The label used to tell the user to check the latest version" + }, + "theme.docs.versions.latestVersionLinkLabel": { + "message": "גרסא אחרונה", + "description": "The label used for the latest version suggestion link label" + }, + "theme.docs.versionBadge.label": { + "message": "גרסה: {versionLabel}" + }, + "theme.common.editThisPage": { + "message": "ערוך דף זה", + "description": "The link label to edit the current page" + }, + "theme.common.headingLinkTitle": { + "message": "קישור ישיר אל {heading}", + "description": "Title for link to heading" + }, + "theme.lastUpdated.atDate": { + "message": " בתאריך {date}", + "description": "The words used to describe on which date a page has been last updated" + }, + "theme.lastUpdated.byUser": { + "message": " על ידי {user}", + "description": "The words used to describe by who the page has been last updated" + }, + "theme.lastUpdated.lastUpdatedAtBy": { + "message": "עודכן{atDate}{byUser}", + "description": "The sentence used to display when a page has been last updated, and by who" + }, + "theme.navbar.mobileVersionsDropdown.label": { + "message": "גרסאות", + "description": "The label for the navbar versions dropdown on mobile view" + }, + "theme.NotFound.title": { + "message": "דף לא נמצא", + "description": "The title of the 404 page" + }, + "theme.tags.tagsListLabel": { + "message": "תגיות:", + "description": "The label alongside a tag list" + }, + "theme.admonition.caution": { + "message": "זהירות", + "description": "The default label used for the Caution admonition (:::caution)" + }, + "theme.admonition.danger": { + "message": "סכנה", + "description": "The default label used for the Danger admonition (:::danger)" + }, + "theme.admonition.info": { + "message": "מידע", + "description": "The default label used for the Info admonition (:::info)" + }, + "theme.admonition.note": { + "message": "הערה", + "description": "The default label used for the Note admonition (:::note)" + }, + "theme.admonition.tip": { + "message": "טיפ", + "description": "The default label used for the Tip admonition (:::tip)" + }, + "theme.admonition.warning": { + "message": "אזהרה", + "description": "The default label used for the Warning admonition (:::warning)" + }, + "theme.AnnouncementBar.closeButtonAriaLabel": { + "message": "סגור", + "description": "The ARIA label for close button of announcement bar" + }, + "theme.blog.sidebar.navAriaLabel": { + "message": "מעבר לרשומות אחרונות בבלוג", + "description": "The ARIA label for recent posts in the blog sidebar" + }, + "theme.DocSidebarItem.expandCategoryAriaLabel": { + "message": "הרחב קטגוריה '{label}'", + "description": "The ARIA label to expand the sidebar category" + }, + "theme.DocSidebarItem.collapseCategoryAriaLabel": { + "message": "כווץ קטגוריה '{label}'", + "description": "The ARIA label to collapse the sidebar category" + }, + "theme.IconExternalLink.ariaLabel": { + "message": "(נפתח בטאב חדש)", + "description": "The ARIA label for the external link icon" + }, + "theme.NavBar.navAriaLabel": { + "message": "ראשי", + "description": "The ARIA label for the main navigation" + }, + "theme.NotFound.p1": { + "message": "אנחנו לא מוצאים את מה שאתה מנסה לחפש.", + "description": "The first paragraph of the 404 page" + }, + "theme.NotFound.p2": { + "message": "הקישור אינו תקין, אנא פנה למנהל האתר ממנו קיבלת קישור זה.", + "description": "The 2nd paragraph of the 404 page" + }, + "theme.navbar.mobileLanguageDropdown.label": { + "message": "שפות", + "description": "The label for the mobile language switcher dropdown" + }, + "theme.TOCCollapsible.toggleButtonLabel": { + "message": "בעמוד זה", + "description": "The label used by the button on the collapsible TOC component" + }, + "theme.blog.post.readMore": { + "message": "קרא עוד...", + "description": "The label used in blog post item excerpts to link to full blog posts" + }, + "theme.blog.post.readMoreLabel": { + "message": "קרא עוד על {title}", + "description": "The ARIA label for the link to full blog posts from excerpts" + }, + "theme.blog.post.readingTime.plurals": { + "message": "דקת קריאה|{readingTime} דקות קריאה|{readingTime} דקות קריאה|{readingTime} דקות קריאה", + "description": "Pluralized label for \"{readingTime} min read\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.CodeBlock.copy": { + "message": "העתק", + "description": "The copy button label on code blocks" + }, + "theme.CodeBlock.copied": { + "message": "הועתק", + "description": "The copied button label on code blocks" + }, + "theme.CodeBlock.copyButtonAriaLabel": { + "message": "העתק קוד לקליפבורד", + "description": "The ARIA label for copy code blocks button" + }, + "theme.CodeBlock.wordWrapToggle": { + "message": "החלף גלישת שורות", + "description": "The title attribute for toggle word wrapping button of code block lines" + }, + "theme.docs.breadcrumbs.home": { + "message": "דף הבית", + "description": "The ARIA label for the home page in the breadcrumbs" + }, + "theme.docs.sidebar.collapseButtonTitle": { + "message": "סגור", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.collapseButtonAriaLabel": { + "message": "סגור", + "description": "The title attribute for collapse button of doc sidebar" + }, + "theme.docs.sidebar.navAriaLabel": { + "message": "סרגל צד", + "description": "The ARIA label for the sidebar navigation" + }, + "theme.docs.sidebar.closeSidebarButtonAriaLabel": { + "message": "סגור סרגל ניווט", + "description": "The ARIA label for close button of mobile sidebar" + }, + "theme.navbar.mobileSidebarSecondaryMenu.backButtonLabel": { + "message": "← חזרה לתפריט הראשי", + "description": "The label of the back button to return to main menu, inside the mobile navbar sidebar secondary menu (notably used to display the docs sidebar)" + }, + "theme.docs.sidebar.toggleSidebarButtonAriaLabel": { + "message": "החלף סרגל ניווט", + "description": "The ARIA label for hamburger menu button of mobile navigation" + }, + "theme.navbar.mobileDropdown.collapseButton.expandAriaLabel": { + "message": "הרחב את התפריט", + "description": "The ARIA label of the button to expand the mobile dropdown navbar item" + }, + "theme.navbar.mobileDropdown.collapseButton.collapseAriaLabel": { + "message": "כווץ את התפריט", + "description": "The ARIA label of the button to collapse the mobile dropdown navbar item" + }, + "theme.docs.sidebar.expandButtonTitle": { + "message": "פתח", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.docs.sidebar.expandButtonAriaLabel": { + "message": "פתח", + "description": "The ARIA label and title attribute for expand button of doc sidebar" + }, + "theme.SearchBar.noResultsText": { + "message": "אין תוצאות" + }, + "theme.SearchBar.seeAllOutsideContext": { + "message": "ראה את כל התוצאות מחוץ ל-\"{context}\"" + }, + "theme.SearchBar.searchInContext": { + "message": "ראה את כל התוצאות בתוך \"{context}\"" + }, + "theme.SearchBar.seeAll": { + "message": "ראה את כל התוצאות" + }, + "theme.SearchBar.label": { + "message": "חיפוש", + "description": "The ARIA label and placeholder for search button" + }, + "theme.SearchPage.existingResultsTitle": { + "message": "תוצאות חיפוש עבור \"{query}\"", + "description": "The search page title for non-empty query" + }, + "theme.SearchPage.emptyResultsTitle": { + "message": "חפש בתיעוד", + "description": "The search page title for empty query" + }, + "theme.SearchPage.searchContext.everywhere": { + "message": "בכל מקום" + }, + "theme.SearchPage.documentsFound.plurals": { + "message": "נמצא מסמך אחד|נמצאו {count} מסמכים|נמצאו {count} מסמכים|נמצאו {count} מסמכים", + "description": "Pluralized label for \"{count} documents found\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.SearchPage.noResultsText": { + "message": "לא נמצאו מסמכים", + "description": "The paragraph for empty search result" + }, + "theme.Playground.liveEditor": { + "message": "עורך חי", + "description": "The live editor label of the live codeblocks" + }, + "theme.Playground.result": { + "message": "תוצאה", + "description": "The result label of the live codeblocks" + }, + "theme.blog.post.plurals": { + "message": "רשומה אחת|{count} רשומות|{count} רשומות|{count} רשומות", + "description": "Pluralized label for \"{count} posts\". Use as much plural forms (separated by \"|\") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)" + }, + "theme.blog.tagTitle": { + "message": "{nPosts} עם התגית \"{tagName}\"", + "description": "The title of the page for a blog tag" + }, + "theme.blog.author.pageTitle": { + "message": "{authorName} - {nPosts}", + "description": "The title of the page for a blog author" + }, + "theme.blog.authorsList.pageTitle": { + "message": "כותבים", + "description": "The title of the authors page" + }, + "theme.blog.authorsList.viewAll": { + "message": "הצג את כל הכותבים", + "description": "The label of the link targeting the blog authors page" + }, + "theme.blog.author.noPosts": { + "message": "כותב זה עדיין לא כתב רשומות.", + "description": "The text for authors with 0 blog post" + }, + "theme.contentVisibility.unlistedBanner.title": { + "message": "דף לא רשום", + "description": "The unlisted content banner title" + }, + "theme.contentVisibility.unlistedBanner.message": { + "message": "דף זה אינו רשום. מנועי חיפוש לא יאנדקסו אותו, ורק משתמשים עם קישור ישיר יוכלו לגשת אליו.", + "description": "The unlisted content banner message" + }, + "theme.contentVisibility.draftBanner.title": { + "message": "טיוטה", + "description": "The draft content banner title" + }, + "theme.contentVisibility.draftBanner.message": { + "message": "דף זה הוא טיוטה. הוא יהיה גלוי רק בסביבת פיתוח ולא ייכלל בבניית הפרודקשן.", + "description": "The draft content banner message" + }, + "theme.ErrorPageContent.tryAgain": { + "message": "נסה שוב", + "description": "The label of the button to try again rendering when the React error boundary captures an error" + }, + "theme.common.skipToMainContent": { + "message": "דלג לתוכן הראשי", + "description": "The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation" + }, + "theme.tags.tagsPageTitle": { + "message": "תגיות", + "description": "The title of the tag list page" + }, + "homepage.layout.title": { + "message": "שליטה בקידוד אגנטי", + "description": "The browser tab title for the homepage" + }, + "homepage.layout.description": { + "message": "שלטו בקידוד אגנטי עם מתודולוגיה מובנית שהוכיחה את עצמה על מונו-ריפּו ארגוניים. חינמי, רישיון MIT, עם פודקאסטים, מצגות ופרומפטים מוכנים לפרודקשן.", + "description": "The meta description for the homepage" + }, + "homepage.hero.badge.openSource": { + "message": "קוד פתוח", + "description": "The 'Open Source' label in the hero badge" + }, + "homepage.hero.title": { + "message": "שליטה בקידוד אגנטי", + "description": "The main hero heading" + }, + "homepage.hero.subtitle": { + "message": "מתודולוגיה מובנית שהוכיחה את עצמה על מונו-ריפּו ארגוניים עם מיליוני שורות קוד", + "description": "The hero subtitle" + }, + "homepage.hero.cta.startLearning": { + "message": "להתחיל ללמוד", + "description": "The primary CTA button in the hero" + }, + "homepage.hero.cta.browsePrompts": { + "message": "לעיין בפרומפטים", + "description": "The secondary CTA button in the hero" + }, + "homepage.hero.stats.faq": { + "message": "שאלות נפוצות", + "description": "The FAQ link label in the hero stats bar" + }, + "homepage.hero.stats.lessons": { + "message": "{count} שיעורים", + "description": "The lesson count in the hero stats bar" + }, + "homepage.hero.stats.prompts": { + "message": "{count} פרומפטים לפרודקשן", + "description": "The prompt count in the hero stats bar" + }, + "homepage.terminal.link": { + "message": "← מספריית הפרומפטים", + "description": "The link at the bottom of the terminal window (arrow direction flipped for RTL)" + }, + "homepage.modules.title": { + "message": "מה לומדים", + "description": "The 'What You'll Learn' section heading" + }, + "homepage.modules.subtitle": { + "message": "{count} שיעורים שמכסים מחקר, תכנון, ביצוע ותבניות אימות", + "description": "The subtitle under the modules section heading" + }, + "homepage.modules.moduleLabel": { + "message": "מודול {number}", + "description": "The module number label on each module card" + }, + "homepage.modules.1.title": { + "message": "יסודות", + "description": "Module 1 title: Fundamentals" + }, + "homepage.modules.1.topic1": { + "message": "מאחורי הקלעים של LLM: קונטקסט, קשב, מגבלות טוקנים", + "description": "Module 1 topic 1" + }, + "homepage.modules.1.topic2": { + "message": "מה נשבר: הזיות, סחף קוד, ריפקטור", + "description": "Module 1 topic 2" + }, + "homepage.modules.1.topic3": { + "message": "ניהול קונטקסט ואינטגרציית RAG", + "description": "Module 1 topic 3" + }, + "homepage.modules.2.title": { + "message": "מתודולוגיה", + "description": "Module 2 title: Methodology" + }, + "homepage.modules.2.topic1": { + "message": "מבנה Prompting: אילוצים, דוגמאות, שרשרת חשיבה", + "description": "Module 2 topic 1" + }, + "homepage.modules.2.topic2": { + "message": "עיגון: הטמעת קונטקסט שנשאר איתנו", + "description": "Module 2 topic 2" + }, + "homepage.modules.2.topic3": { + "message": "תבניות איטרציה: תכנון, ביצוע, אימות", + "description": "Module 2 topic 3" + }, + "homepage.modules.3.title": { + "message": "טכניקות מעשיות", + "description": "Module 3 title: Practical Techniques" + }, + "homepage.modules.3.topic1": { + "message": "אינטגרציית CI ותבניות סקירה אוטומטית", + "description": "Module 3 topic 1" + }, + "homepage.modules.3.topic2": { + "message": "יצירת בדיקות ואסטרטגיות כיסוי", + "description": "Module 3 topic 2" + }, + "homepage.modules.3.topic3": { + "message": "סשני דיבאג: כש-AI מחמיר את המצב", + "description": "Module 3 topic 3" + }, + "homepage.formats.title": { + "message": "ללמוד בדרך שלך", + "description": "The 'Learn Your Way' section heading" + }, + "homepage.formats.subtitle": { + "message": "כל שיעור, שלושה פורמטים", + "description": "The subtitle under the formats section heading" + }, + "homepage.formats.docs.title": { + "message": "מסמכים לרפרנס", + "description": "The Reference Docs format card title" + }, + "homepage.formats.docs.description": { + "message": "לסמן. לחזור כשצריך.", + "description": "The Reference Docs format card description" + }, + "homepage.formats.podcasts.title": { + "message": "פודקאסטים", + "description": "The Podcasts format card title" + }, + "homepage.formats.podcasts.description": { + "message": "בדרך לעבודה, חדר כושר, טיול עם הכלב.", + "description": "The Podcasts format card description" + }, + "homepage.formats.presentations.title": { + "message": "מצגות", + "description": "The Presentations format card title" + }, + "homepage.formats.presentations.description": { + "message": "לשתף עם הצוות.", + "description": "The Presentations format card description" + }, + "homepage.ecosystem.title": { + "message": "מערכת אקולוגית בקוד פתוח", + "description": "The 'Open Source Ecosystem' section heading" + }, + "homepage.ecosystem.subtitle": { + "message": "כלים מוכנים לפרודקשן שמיישמים את מתודולוגיית הקורס", + "description": "The subtitle under the ecosystem section heading" + }, + "homepage.ecosystem.chunkhound.tagline": { + "message": "אל תחפשו את הקוד שלכם. חקרו אותו.", + "description": "ChunkHound project tagline" + }, + "homepage.ecosystem.arguseek.tagline": { + "message": "מחקר רחב, לא דוחות עמוקים", + "description": "ArguSeek project tagline" + }, + "homepage.ecosystem.toolbox.title": { + "message": "ארגז כלים נבחר", + "description": "The Curated Toolbox card title" + }, + "homepage.ecosystem.toolbox.tagline": { + "message": "כלי CLI מודרניים לפיתוח AI-first", + "description": "The Curated Toolbox card tagline" + }, + "homepage.ecosystem.integrationNote": { + "message": "שכבת המחקר שמעגנת את הסוכנים שלכם במציאות", + "description": "The integration note below the ecosystem grid" + }, + "homepage.ecosystem.disclosureNote": { + "message": "ChunkHound ו-ArguSeek נוצרו על ידי מחבר הקורס.", + "description": "The author disclosure note in the ecosystem section" + } +} diff --git a/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current.json b/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current.json new file mode 100644 index 0000000..1f39ff8 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current.json @@ -0,0 +1,6 @@ +{ + "version.label": { + "message": "הבא", + "description": "The label for version current" + } +} diff --git a/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current/cli-coding-agents.md b/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current/cli-coding-agents.md new file mode 100644 index 0000000..1f585a2 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current/cli-coding-agents.md @@ -0,0 +1,218 @@ +--- +title: סוכני קידוד CLI +sidebar_position: 1 +--- + +# סוכני קידוד CLI + +**סוכני קידוד CLI הם שכבת התזמור (orchestration) לפיתוח מרובה סוכנים.** בעוד ש[טרמינלים](/developer-tools/terminals) מספקים את הסביבה ו[כלי CLI](/developer-tools/cli-tools) מאפשרים פעולות יעילות, סוכני קידוד הם מה שבפועל כותב, עורך ומבצע refactor לקוד שלך. הם משלבים יכולות של מודל שפה עם גישה למערכת קבצים, הרצת shell והבנה של ה-codebase. + +עמוד זה מכסה סוכנים שפועלים בעיקר משורת הפקודה (command line) - שונים מעוזרים משובצי IDE כמו Cursor או Windsurf. סוכני CLI מציעים יתרונות למהנדסים בכירים: יכולת סקריפטינג, תאימות SSH, פחות אוברהד משאבים (resource overhead), ואינטגרציה חלקה עם תהליכי עבודה מרובי worktree. + +## Claude Code + +[**Claude Code**](https://claude.com/product/claude-code) הוא סוכן ה-CLI הרשמי של Anthropic, שיצא בפברואר 2025. הוא מניע את זרימות העבודה לאורך הקורס הזה ומייצג גישת "tool use first" - הסוכן פועל דרך קריאות כלים מפורשות במקום יצירת קוד אוטונומית. + +**מאפיינים מבדלים עיקריים:** + +- **CLAUDE.md היררכי:** קבצי קונטקסט מרובי-רמות (גלובלי ← פרויקט ← תת-תיקייה) ש[מתמזגים אוטומטית בהתאם לתיקיית העבודה](/docs/practical-techniques/lesson-6-project-onboarding) - הגדר סטנדרטים בשורש הפרויקט, דרוס לכל מודול, והגדר העדפות אישיות גלובלית +- **תת-סוכנים דרך Task(...):** הפעל מופעי סוכן מבודדים למחקר מקביל, חקירת קוד או משימות מתמחות מבלי לזהם את הקונטקסט הראשי +- **מצב תכנון:** תהליך עבודה מפורש של תכנן-לפני-ביצוע לשינויים מורכבים - התאם גישה לפני שקבצים משתנים +- **מערכת hooks:** כללים דטרמיניסטיים לפני/אחרי ביצוע לוולידציה, פורמט או תהליכי עבודה מותאמות שמופעלות בנקודות ספציפיות +- **אינטגרציית MCP:** הרחב יכולות דרך [שרתי Model Context Protocol](/developer-tools/mcp-servers) למחקר קוד, עיגון לאינטרנט (web grounding) ואוטומציית דפדפן +- **פקודות slash:** קיצורי דרך מותאמים לפעולות תכופות (`/commit`, `/pr`, `/test`) מוגדרים לכל מאגר + +**מתאים במיוחד ל:** מהנדסים שבונים תהליכי עבודה מורכבים מרובי סוכנים שצריכים שליטה מפורשת על התנהגות הסוכן. צוותים שדורשים קונפיגורציות סוכן שניתנות לשחזור בין מפתחים באמצעות קבצי CLAUDE.md שנשמרו ב-git. מפתחים שעובדים עם בסיסי קוד גדולים (50k+ שורות) שבהם בידוד קונטקסט של תת-סוכנים מונע בלבול. + +**פשרות (trade-offs):** רק מודלים של Anthropic - אין תמיכה ב-OpenAI, Google או מודלים מקומיים. עקומת למידה לפיצ'רים מתקדמים (hooks, MCP, תת סוכנים). + +**תמחור:** מנוי Max ב-$100/חודש (5x שימוש Pro) או $200/חודש (20x שימוש Pro) - עלויות צפויות ללא חיוב לפי טוקן. אלטרנטיבה: מבוסס-שימוש דרך Anthropic API - Sonnet 4 ב-$3/$15 לכל MTok (קלט/פלט), Opus 4.5 ב-$5/$25 לכל MTok. + +**התקנה:** + +```bash +# npm (recommended) +npm install -g @anthropic-ai/claude-code + +# Requires Node.js 18+ +# Authenticate via Claude Max subscription or set ANTHROPIC_API_KEY +``` + +### כלי Status Line + +הגדרת `statusLine` של Claude Code מאפשרת תצוגות סטטוס בר מותאמות דרך פקודות חיצוניות. כלים קהילתיים מספקים מעקב עלויות בזמן אמת, אינטגרציית git וניטור סשן. + +**[CCometixLine (ccline)](https://github.com/Haleclipse/CCometixLine)** - statusline מבוסס Rust עם אינטגרציית git, תצוגת מודל, מעקב שימוש ותצורת TUI. כולל patches להשבתת אזהרות קונטקסט והפעלת מצב verbose. התקנה: `npm install -g @cometix/ccline` + +**[ccusage](https://github.com/ryoppippi/ccusage)** - ניטור שימוש בטוקנים ועלויות המציג עלות סשן, סיכומים יומיים, מעקב בלוקים של 5 שעות וקצב צריכה בזמן אמת. התקנה: `npx ccusage@latest statusline` + +**אפשרויות נוספות:** [claude-statusline](https://github.com/ersinkoc/claude-statusline) (Python, 100+ ערכות נושא), [CCStatusLine](https://github.com/sirmalloc/ccstatusline) (פירוט טוקנים מרובה-שורות) + +## OpenAI Codex CLI + +[**Codex CLI**](https://developers.openai.com/codex/cli/) הוא סוכן שורת הפקודה הרשמי של OpenAI, שיצא באפריל 2025. הוא מספק אינטגרציה נייטיבית עם האקוסיסטם של מודלי OpenAI כולל סדרת GPT-5-Codex שמותאמת לקידוד אגנטי. + +**מאפיינים מבדלים עיקריים:** + +- **אינטגרציית אקוסיסטם OpenAI:** תמיכה נייטיבית במודלי GPT-5-Codex (ברירת מחדל ב-macOS/Linux) עם פקודת `/model` למעבר בין GPT-5.1, GPT-5-Codex-Max ומודלי reasoning +- **הרצה בסנדבוקס:** סביבת הרצת קוד מובנית לבדיקת קוד שנוצר לפני יישום שינויים +- **קונטקסט מרובה-קבצים (multi-file context):** מבין מבנה פרויקט ומתחזק עריכות קוהרנטיות בין קבצים +- **פקודות בשפה טבעית:** המר תיאורים בשפה טבעית ישירות לפקודות shell ושינויי קוד + +**מתאים במיוחד ל:** צוותים שכבר מושקעים באקוסיסטם של OpenAI (מפתחות API, חיובים, היכרות). מפתחים שרוצים גישה למודלי OpenAI האחרונים ברגע שהם יוצאים. מהנדסים שמעדיפים כלים רשמיים של הספק עם ערוצי תמיכה ייעודיים. + +**פשרות:** רק מודלים של OpenAI - אין תמיכה ב-Anthropic, Google או מודלים מקומיים. כלי חדש יותר עם קהילה קטנה יותר בהשוואה ל-Aider. תיעוד פחות מקיף מאלטרנטיבות מבוססות יותר. דורש גישה ל-OpenAI API ועלויות נלוות. + +**תמחור:** כלול במנוי ChatGPT Plus ($20/חודש), Pro, Team ו-Enterprise עם מגבלות שימוש מדורגות. אלטרנטיבה: מבוסס-שימוש דרך מפתח OpenAI API בתעריפים סטנדרטיים. + +**התקנה:** + +```bash +# npm +npm install -g @openai/codex + +# Requires Node.js 18+ +# Set OPENAI_API_KEY environment variable +``` + +## Gemini CLI + +[**Gemini CLI**](https://geminicli.com/) הוא סוכן שורת הפקודה של Google למשפחת מודלי Gemini, שיצא ביוני 2025. הוא מציע את חלון הקונטקסט הגדול ביותר (מיליון טוקנים) בין סוכני CLI וגישה ל-Gemini 3 Pro. + +**מאפיינים מבדלים עיקריים:** + +- **חלון קונטקסט עצום (context window):** קונטקסט של מיליון טוקנים (2 מיליון בקרוב) - נתח בסיסי קוד שלמים בפרומפט אחד +- **Gemini 3 Pro:** גישה למודל ה-reasoning האחרון של Google עם יכולות מולטימודליות חזקות +- **אינטגרציית Google Cloud:** תאימות נייטיבית עם Vertex AI, שירותי Google Cloud ו-Google Workspace +- **MCP והרחבות:** הרחב יכולות דרך Model Context Protocol או הרחבות מובנות; עגן פרומפטים עם Google Search + +**מתאים במיוחד ל:** צוותים שמנתחים בסיסי קוד גדולים שחורגים ממגבלות הקונטקסט של סוכנים אחרים. מפתחים שכבר משתמשים בתשתית Google Cloud. מהנדסים שצריכים יכולות מולטימודליות (ניתוח תמונה, וידאו, אודיו לצד קוד). + +**פשרות:** קריאת כלים (tool calling) ומעקב אחר הוראות פחות מלוטשים מ-Claude Code או Codex - טוב יותר לניתוח מאשר קידוד אוטונומי מרובה-שלבים. הטייר החינמי (free tier) מוגבל מאוד (דצמבר 2025) - מגבלות API צומצמו לכמעט אפס עבור 2.5 Pro. שיקולי פרטיות - התנאים של Google מאפשרים איסוף נתונים (טיירים של enterprise מציעים הגנה). + +**תמחור:** מנויי Google AI Pro/Ultra ל-rate limits עדיפים. מבוסס-שימוש דרך Vertex AI - Gemini 3 Pro ב-$2/$12 לכל MTok (קלט/פלט). הטייר החינמי מוגבל להתנסות קלה בלבד. + +**התקנה:** + +```bash +# npm +npm install -g @google/gemini-cli + +# Requires Node.js 18+ +# Set GOOGLE_API_KEY or configure Google Cloud credentials +``` + +## GitHub Copilot CLI + +[**GitHub Copilot CLI**](https://github.com/features/copilot/cli) הוא סוכן הקידוד הנייטיבי לטרמינל של GitHub, שנכנס ל-public preview בספטמבר 2025. לצוותים עם רישיונות Copilot Business/Enterprise קיימים, זוהי נקודת הכניסה עם החיכוך הנמוך ביותר לתהליכי עבודה אגנטיים - אפס רכש נוסף, גישה מיידית. + +**מאפיינים מבדלים עיקריים:** + +- **יכולות אגנטיות מלאות:** קרא, כתוב והרץ קוד באופן אוטונומי - לא רק הצעות פקודות +- **אינטגרציית GitHub:** גישה נייטיבית למאגרים, issues ו-pull requests דרך שאילתות בשפה טבעית +- **תמיכה בשרתי MCP:** ניתן להרחבה עם כלים מותאמים ומקורות קונטקסט דרך Model Context Protocol +- **backend מרובה-מודלים:** ממנף מודלים של OpenAI, Anthropic ו-Google דרך התשתית של GitHub + +**מתאים במיוחד ל:** צוותים ארגוניים שבודקים תהליכי עבודה אגנטיים עם רישיונות Copilot קיימים. דפוסי שימוש קלים עד בינוניים שבהם תמחור מבוסס-בקשות נשאר כלכלי. תהליכי עבודה ממוקדי-GitHub שבהם אינטגרציית repo/issue/PR native מוסיפה ערך. + +**פשרות:** תמחור מבוסס-בקשות יוצר עקומת עלות לא שגרתית - זול להתחיל ($10/חודש flat), אבל יקר בסקייל. ב-300 בקשות premium/חודש (טייר Pro), שימוש יומי מתון מכלה את ההקצאה במהירות; חריגות ב-$0.04/בקשה מצטברות מהר. Power users באופן טבעי עוברים לכלים מבוססי טוקן כמו [Claude Code](#claude-code) או [Codex CLI](#openai-codex-cli) שבהם העלויות עולות בצורה ליניארית יותר. באגים ידועים באינטראקציה עם הטרמינל - הסוכן לא יכול לזהות באופן אמין מתי פקודות הסתיימו, מה שמוביל למצבי stuck ובקשות מבוזבזות. + +**תמחור:** מבוסס-בקשות, כלול במנויי Copilot. + +| Plan | Cost | Premium Requests | Overage | +| ---------- | -------------- | ---------------- | ------------- | +| Pro | $10/month | 300/month | $0.04/request | +| Pro+ | $39/month | 1,500/month | $0.04/request | +| Business | $19/user/month | 300/user/month | $0.04/request | +| Enterprise | $39/user/month | 1,000/user/month | $0.04/request | + +מודלים כלולים (GPT-5 mini, GPT-4.1, GPT-4o) לא צורכים בקשות premium. למודלים מתקדמים יש מכפילים - Claude Opus 4.1 עולה 10x לכל אינטראקציה. + +**התקנה:** + +```bash +# npm (requires Node.js 18+) +npm install -g @github/copilot + +# Requires active GitHub Copilot subscription (Pro/Business/Enterprise) +# For Business/Enterprise: admin must enable preview features +``` + +## Aider + +[**Aider**](https://aider.chat) הוא סוכן CLI בקוד פתוח שמתמקד בתהליכי עבודה native ל-git וגמישות מודלים. יצא במאי 2023, הוא הבשיל לסוכן הקידוד בקוד הפתוח הנפוץ ביותר עם 38.9k כוכבי GitHub, 3.9M הורדות PyPI ו-15 מיליארד טוקנים מעובדים שבועית. + +**מאפיינים מבדלים עיקריים:** + +- **תהליך עבודה native ל-git:** commits אוטומטיים אחרי כל שינוי עם הודעות תיאוריות - היסטוריה נקייה וניתנת לסקירה ללא staging ידני +- **Provider agnostic:** תומך ב-OpenAI, Anthropic, Google, DeepSeek, Groq ומודלים מקומיים דרך Ollama או LiteLLM - אזן איכות מול עלות לכל משימה +- **מיפוי מאגר (repository mapping):** Tree-sitter בונה גרף תלויות של סימבולים (מחלקות, מתודות, חתימות) - אלגוריתם דירוג גרפים בוחר קונטקסט רלוונטי ללא embeddings או חיפוש סמנטי +- **מצבים מרובים:** מצב code (עריכות ישירות), מצב architect (תכנון ועיצוב), מצב ask (שאילתות ללא שינויים) +- **קלט מולטימודלי (multimodal input):** הוסף תמונות ודפי אינטרנט לצ'אט לקונטקסט ויזואלי, צילומי מסך או תיעוד ייחוס +- **קול-לקוד:** פקודת `/voice` לקידוד ללא ידיים - דבר בקשות לפיצ'רים, בדיקות או תיקוני באגים +- **Polyglot benchmark:** מתחזק [לוח מובילים LLM](https://aider.chat/docs/leaderboards) שבודק מודלים על 225 תרגילי Exercism ב-C++, Go, Java, JavaScript, Python ו-Rust +- **ניטור עלויות:** תצוגה בזמן אמת של טוקנים שנשלחו/התקבלו ועלויות הודעה - זהה מודלים זולים יותר לתהליך העבודה שלך +- **משתפר באופן עצמאי:** ~70% מהקוד האחרון של Aider נכתב על ידי Aider עצמו + +**מתאים במיוחד ל:** מפתחים שרוצים גמישות בבחירת מודל - השתמש ב-Claude לשכתובים מורכבים, מודלים זולים יותר לתיקונים מהירים, מודלים מקומיים לקוד רגיש. מהנדסים שמעדיפים היגיינת git עם משמעת commit אוטומטית. צוותים עם מגבלות תקציב שיכולים לערבב מודלים יקרים וזולים באופן אסטרטגי. פריסות enterprise שדורשות תשתית מאוחסנת עצמאית לחלוטין ללא נעילה לספק. + +**פשרות:** auto-commits של git יכולים ליצור היסטוריה רועשת אם לא מוגדר בזהירות. אין ארכיטקטורת תת-סוכנים מובנית - מודל ביצוע single-threaded. ממשק דפדפן ניסיוני ופחות מלוטש מ-CLI. חלק מהמשתמשים מדווחים על תוצאות לא עקביות עם מודלים מקומיים. + +**תמחור:** חינם וקוד פתוח. שלם רק עבור טוקני API לספק שבחרת - ללא שכבת מנוי. + +**התקנה:** + +```bash +# pip (recommended) +pip install aider-chat + +# Or with pipx for isolation +pipx install aider-chat + +# Requires Python 3.9+ +# Set API keys for your chosen provider (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) +``` + +## OpenCode + +[**OpenCode**](https://opencode.ai) הוא סוכן CLI בקוד פתוח עם עיצוב TUI-first, בנוי ב-Go על ידי חובבי neovim. עם 38k+ כוכבי GitHub ו-375 תורמים, הוא מדגיש אינטגרציית LSP וארכיטקטורה privacy-first לפריסות enterprise. + +**מאפיינים מבדלים עיקריים:** + +- **אינטגרציית LSP:** מפעיל אוטומטית שרתי שפה לפרויקט שלך - ה-AI מקבל דיאגנוסטיקת קומפיילר ושגיאות טיפוס בזמן אמת (יכולות LSP מלאות כמו rename/go-to-definition עדיין לא חשופות) +- **סוכנים מובנים:** סוכן `build` (גישה מלאה לפיתוח), סוכן `plan` (ניתוח קריאה-בלבד שדורש אישור לפקודות bash), תת-סוכן `general` (חיפושים מורכבים מרובי-שלבים דרך `@general`) +- **ארכיטקטורת client/server:** ליבת הסוכן רצה על מכונה אחת בעוד שנשלט מרחוק - TUI הוא אפשרות קליינט אחת; מאפשר שליטה מאפליקציית מובייל והפעלה headless +- **תמיכת MCP:** אינטגרציית Model Context Protocol לכלים חיצוניים - התחבר ל-Playwright לאוטומציית דפדפן, שרתים מותאמים לתהליכי עבודה מתמחים +- **75+ ספקים:** OpenAI, Anthropic, Google, GitHub Copilot, AWS Bedrock, Groq, Azure OpenAI, OpenRouter ומודלים מקומיים דרך Ollama - או השתמש ב-OpenCode Zen להמלצות מודל מאוצרות +- **Privacy-first:** ללא אחסון קוד או קונטקסט - מתאים לבסיסי קוד רגישים ודרישות compliance של enterprise +- **מרובה-סשנים:** הרץ סוכנים מרובים במקביל על אותו פרויקט עם שיתוף סשן דרך קישורים +- **פקודות מותאמות:** צור פרומפטים לשימוש חוזר באמצעות קבצי Markdown עם ארגומנטים בעלי שם + +**מתאים במיוחד ל:** צוותים מודעי-פרטיות שדורשים פריסות on-premise. משתמשי Neovim שרוצים מצוינות TUI. מפתחים שרוצים הבנה משופרת-LSP של ה-AI לבסיס הקוד שלהם. סביבות enterprise שצריכות audit trails ו-data residency compliance. + +**פשרות:** במקור פרויקט שהועבר לארכיון (archived), כעת מתוחזק על ידי SST - כדאי לוודא מחויבות לתחזוקה לטווח ארוך. קהילה קטנה יותר מ-Aider. + +**תמחור:** חינם וקוד פתוח. שלם רק עבור טוקני API LLM לספק שבחרת. + +**התקנה:** + +```bash +# Quick install +curl -fsSL https://opencode.ai/install | bash + +# Or via npm +npm i -g opencode-ai@latest + +# Or Homebrew (macOS/Linux) +brew install opencode + +# Requires provider API keys or OpenCode Zen subscription +``` + +--- + +**קשור:** + +- [כלי מפתח: טרמינלים](/developer-tools/terminals) - אמולטורי טרמינל מותאמים לסשנים מרובי-סוכנים +- [כלי מפתח: כלי CLI מודרניים](/developer-tools/cli-tools) - כלי shell שמשלימים תהליכי עבודה של סוכנים +- [כלי מפתח: שרתי MCP](/developer-tools/mcp-servers) - הרחב סוכני CLI עם מחקר קוד ועיגון לאינטרנט diff --git a/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current/cli-tools.md b/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current/cli-tools.md new file mode 100644 index 0000000..3089d2b --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current/cli-tools.md @@ -0,0 +1,416 @@ +--- +title: כלי CLI מודרניים +sidebar_position: 3 +--- + +# כלי CLI מודרניים לתהליכי עבודה מרובי סוכנים + +[טרמינלים מודרניים](/developer-tools/terminals) בשילוב עם כלי CLI מגיעים לאותן יכולות (feature parity) של IDEs מסורתיים - ripgrep + fzf לחיפוש גלובלי, yazi לחקירת קבצים, tmux/Zellij לניהול panes, lazygit לפעולות git. לפיתוח מרובה סוכנים, סטאק (stack) זה הופך לתשתית קריטית: persistence של סשנים לאורך ניתוקים, מעבר קונטקסט מהיר בין worktrees, ופעולות קבצים יעילות מבלי לשבור תהליך העבודה. + +**שבע קטגוריות:** חיפוש וגילוי (ripgrep, fd), עריכת טקסט ובדיקה (micro, bat), ניווט קבצים (eza, yazi, fzf, zoxide), ניהול סשנים (tmux, Zellij), היסטוריית shell (Atuin), פעולות git (lazygit), ואוטומציית דפדפן (agent-browser) מטפלות במשימות CLI התכופות ביותר בתהליכי עבודה של פיתוח מרובה סוכנים. + +## כלי חיפוש וגילוי + +### ripgrep + +![תוצאות חיפוש ripgrep עם התאמות תבנית צבעוניות ומספרי שורות](https://burntsushi.net/stuff/ripgrep1.png) + +[**ripgrep**](https://github.com/BurntSushi/ripgrep) הוא כלי חיפוש מוכוון-שורות מבוסס Rust שמשלב את המהירות של כלים מתמחים עם הגמישות של grep. binary יחיד, ללא תלויות, תמיכה חוצת-פלטפורמות. + +**מאפיינים מבדלים עיקריים:** מהיר פי 10-20 מ-grep כברירת מחדל, קריטי כש סוכנים מבצעים עשרות חיפושים למשימה בודדת. מכבד קבצי `.gitignore`, `.ignore` ו-`.hgignore` כברירת מחדל, מסנן אוטומטית node_modules, artifacts של build ותלויות מנוהלות-גרסאות - מפחית התאמות לא רלוונטיות ושגיאות פרסור. חיפוש רקורסיבי בתיקיות הוא ברירת מחדל (`rg pattern` מחפש מהתיקייה הנוכחית כלפי מטה) במקום לדרוש flags מפורשים של `-r`. תמיכת regex באמצעות מנוע regex של Rust עם lookahead/lookbehind, מודעות Unicode ושוויון תכונות PCRE. תומך בחיפוש מרובה-שורות עם flag של `--multiline-dotall`. מוכן לאינטגרציה עם fzf, ripgrep-all (`rga`) לחיפוש PDFs/archives/קבצים דחוסים, ופורמטים מרובים של פלט (JSON, CSV, טקסט רגיל). + +**מתאים במיוחד ל:** מפתחים שמבצעים מחקר מהיר מרובה סוכנים על פני בסיסי קוד, שבהם ביצועי חיפוש מצטברים על פני עשרות שאילתות מקבילות. מהנדסים שמנהלים מאגרים גדולים (100k+ קבצים) שבהם grep נהיה איטי באופן מורגש. צוותים שמשתמשים ב-ripgrep לאורך סקריפטי פיתוח, Makefiles ו-pipelines של CI/CD שבהם מודעות ל-`.gitignore` מפחיתה false positives. + +**פשרות:** הבדלים במנוע regex של Rust משמעותם שכמה תבניות regex מתקדמות של Perl עשויות לא לעבוד (אם כי הכיסוי נרחב). כיבוד ברירת המחדל של `.gitignore` יכול להפתיע משתמשים שמצפים לחיפוש אוניברסלי של grep - דורש flag של `--no-ignore` לעקיפה, מוסיף עומס קוגניטיבי למקרי קצה. מוגבל לפלט מוכוון-שורות; חיפוש בתוך קבצים בינאריים או מבנים מקוננים עמוקות דורש flags נוספים או כלים משלימים. + +**התקנה:** + +```bash +# macOS +brew install ripgrep + +# Cargo (Rust) +cargo install ripgrep + +# Linux package managers +sudo apt install ripgrep # Debian/Ubuntu +sudo pacman -S ripgrep # Arch +``` + +### fd + +![חיפוש קבצים fd עם פלט צבעוני המציג תיקיות וסוגי קבצים](https://github.com/sharkdp/fd/raw/master/doc/screencast.svg) + +[**fd**](https://github.com/sharkdp/fd) הוא תחליף ל-find מבוסס Rust מותאם לפשטות וביצועים. binary יחיד, אפס תלויות, תמיכה חוצת-פלטפורמות. + +**מאפיינים מבדלים עיקריים:** פלט צבעוני לתיקיות, symlinks ו-executables כברירת מחדל ללא עומס flags. תמיכה משתמעת בקבצי `.gitignore` ו-`.ignore` מדלגת על תיקיות מוסתרות ותבניות מתעלמות אוטומטית (השתמשו ב-`--no-ignore` לעקיפה). ביצוע מקביל על פני ליבות CPU לסריקות תיקיות גדולות (4 workers ברירת מחדל, ניתן להגדרה דרך `--threads`). תחביר תבנית regex-first מנצח את הביטויים המסובכים של find של `-name` ו-`-type`. piping נקי ל-xargs/parallel/ripgrep ללא צורך בעקיפות `-print0`. ברירות מחדל הגיוניות (case-insensitive ב-macOS, קבצים מוסתרים מוחרגים, תמיכת צבע) לא דורשות תצורה. + +**מתאים במיוחד ל:** מהנדסים שבונים סקריפטים מרובי-סוכנים שסורקים worktrees גדולים ללא ניהול ignore ידני. מפתחים שמגלים תבניות קבצים לאינטגרציית ripgrep - פלט fd מזין באופן טבעי ripgrep לתהליכי עבודה של חיפוש קוד. משתמשים שעובדים על פני git worktrees שצריכים מיקום קבצים מיידי ללא תחביר find מורכב. + +**פשרות:** תחביר שונה מ-POSIX find משמעו שסקריפטים דורשים תרגום כשמעבירים בין מערכות. כמה אפשרויות find מתקדמות (שרשראות פעולה מורכבות, `-exec` עם מספר תנאים) לא נתמכות ישירות - fallback מזדמן ל-find עדיין נדרש. פלט צבעוני מוסיף רעש ב-pipes אלא אם כן מושבת מפורשות (אם כי fd מזהה אוטומטית כשמעובר ב-pipe ומשבית צבעים). + +**התקנה:** + +```bash +# macOS +brew install fd + +# Cargo (Rust) +cargo install fd-find + +# Linux package managers +sudo apt install fd-find # Debian/Ubuntu +sudo pacman -S fd # Arch +``` + +## עריכת טקסט ובדיקה + +### micro + +![עורך micro עם ערכת נושא solarized המציגה הדגשת תחביר וסרגל מצב](https://github.com/zyedidia/micro/raw/master/assets/micro-solarized.png) + +[**micro**](https://micro-editor.github.io/) הוא עורך טקסט בטרמינל (terminal text editor) מבוסס Go שמביא keybindings דמויי-GUI לשורת הפקודה. binary יחיד, ללא תלויות, תמיכה חוצת-פלטפורמות. + +**מאפיינים מבדלים עיקריים:** Ctrl+S לשמירה, Ctrl+Q ליציאה, Ctrl+F לחיפוש - לא נדרשת עריכה מודאלית או שינון. הדגשת תחביר ל-130+ שפות מהקופסה. תמיכה מרובת-cursors (בסגנון Sublime) לעריכה מקבילה. מערכת plugins של Lua להרחבה. טרמינל משולב ותמיכת עכבר לתהליכי עבודה היברידיים של מקלדת/עכבר. + +**מתאים במיוחד ל:** מפתחים שצריכים עריכות מהירות בקונטקסט סוכן מבלי לעבור ל-IDE. מהנדסים שרואים את העריכה המודאלית של Vim כ-overkill לשינויי שורה אחת. משתמשים שרוצים עריכה טרמינלית עם keybindings מוכרים של עורך מודרני (שמגיעים מ-VSCode, Sublime או עורכי GUI דומים). + +**פשרות:** מינימלי בתכונות בהשוואה ל-IDEs - ללא אינטגרציית LSP, כלי refactoring מוגבלים, ניווט בסיסי. לא חזק כמו Vim/Neovim לפעולות מורכבות מרובות-קבצים או מניפולציית text objects מתקדמת. לקבצים גדולים (1000+ שורות) או חקירת קוד עמוקה, IDE נשאר בחירת כלי עדיפה. + +**התקנה:** + +```bash +# macOS +brew install micro + +# Linux (binary) +curl https://getmic.ro | bash + +# Cross-platform (Go) +go install github.com/zyedidia/micro/cmd/micro@latest +``` + +דרישות: אין (binary סטטי). אופציונלי: תמיכת clipboard דרך xclip/xsel ב-Linux. + +### Fresh + +![עורך Fresh בטרמינל המציג command palette לגילוי תכונות](https://sinelaw.github.io/fresh/docs/assets/palette.png) + +[**Fresh**](https://sinelaw.github.io/fresh/) הוא עורך טרמינלי מבוסס Rust שתוכנן לגילוי ומהירות. מביא שימושיות דמוית-GUI (keybindings סטנדרטיים, תמיכת עכבר, command palette) לטרמינל עם אינטגרציית LSP. + +**מאפיינים מבדלים עיקריים:** עריכה לא-מודאלית עם keybindings מוכרים (Ctrl+S, Ctrl+Z, Ctrl+F) - לא נדרשת עקומת למידה של Vim. תמיכת עכבר מלאה עם סרגל תפריטים ו-command palette לגילוי תכונות. אינטגרציית LSP מספקת go-to-definition, diagnostics inline, תיעוד hover ו-code actions. מטפל בקבצים של 10GB+ מיידית דרך piece tree עם lazy-loading (~36MB זיכרון לקובץ 2GB לעומת ~2GB ל-Neovim). מערכת plugins של TypeScript/Deno רצה בסביבה sandboxed להרחבה מאובטחת ומודרנית. סייר קבצים מובנה וטרמינל משולב. + +**מתאים במיוחד ל:** מפתחים שרוצים עריכה טרמינלית דמוית-IDE ללא עומס עריכה מודאלית. מהנדסים שעובדים עם קבצי log גדולים או קבצי נתונים שבהם עורכים אחרים נאבקים או קורסים. משתמשים שרוצים את הנגישות של micro בשילוב עם אינטליגנציית קוד מונעת-LSP. צוותים שצריכים הרחבה דרך מערכת TypeScript מוכרת במקום Lua או Vimscript. + +**פשרות:** פרויקט חדש יותר עדיין מתבגר - קהילה ומערכת אקולוגית של plugins קטנות יותר מעורכים מבוססים. דורש Deno runtime לפיתוח plugins. פחות מבוסס ומוכח (battle-tested) מ-micro למשימות עריכה פשוטות. כמה תהליכי עבודה מתקדמים של Vim/Neovim (מקרואים מורכבים, שרשראות plugins נרחבות) עדיין לא משוכפלים. + +**התקנה:** + +```bash +# macOS +brew tap sinelaw/fresh && brew install fresh-editor + +# Cargo (Rust) +cargo install fresh-editor + +# npm (cross-platform) +npm install -g @fresh-editor/fresh-editor + +# Linux package managers +yay -S fresh-editor # Arch (AUR) +``` + +דרישות: אין (binary סטטי). אופציונלי: Deno לפיתוח plugins. + +### bat + +![bat מציג קוד עם הדגשת תחביר, מספרי שורות ואינטגרציית git](https://camo.githubusercontent.com/46b1d63d8c4a647bcfc34eef014232fce5125c03f0aa94b2a06d6765a2f1c6bb/68747470733a2f2f692e696d6775722e636f6d2f326c53573452452e706e67) + +[**bat**](https://github.com/sharkdp/bat) הוא תחליף ל-cat מבוסס Rust עם הדגשת תחביר מובנית ואינטגרציית git. binary יחיד, חוצה-פלטפורמות, מתוחזק באופן פעיל. + +**מאפיינים מבדלים עיקריים:** הדגשת תחביר ל-100+ שפות מונעת אובדן קונטקסט (context loss) כשסוכנים מתייחסים לקטעי קוד. אינטגרציית git מציגה שינויי שורות (מצב `--diff` משווה מול git index). מספרי שורות וגלישת עמודות ללא צורך ב-pager less. אינטגרציה עם הגדרות תחביר חיצוניות דרך תצורת DRY (Don't Repeat Yourself). ניתן להגדרה דרך משתנה סביבה `BAT_CONFIG_PATH` להתאמת ערכת נושא וסגנון. מכבד צבעי מערכת והעדפות ערכת נושא לאורך אמולטורי טרמינל. + +**מתאים במיוחד ל:** מפתחים שבודקים קבצים במהלך תהליכי עבודה של סוכנים מבלי לשבור קונטקסט (lookups מהירים נשארים בטרמינל לעומת מעבר קונטקסט ל-IDE). מהנדסים שסוקרים שינויי git להבנת מה השתנה לפני עיבוד סוכן. משתמשים שמשלבים bat עם previewer של yazi או חלון preview של fzf לניווט קבצים עם הדגשת תחביר. + +**פשרות:** מעט איטי יותר מ-cat רגיל בגלל עומס הדגשת תחביר (זניח לשימוש טיפוסי). דורש Nerd Font או גופן תואם לתמיכת אייקונים בכמה הגדרות טרמינל. מדגיש התחביר הוא דעתני - הגדרות שפה מותאמות דורשות תצורה במקום הרחבה מובנית. + +**התקנה:** + +```bash +# macOS +brew install bat + +# Cargo (Rust) +cargo install bat + +# Linux package managers +sudo apt install bat # Debian/Ubuntu +sudo pacman -S bat # Arch +``` + +## פעולות Git + +### lazygit + +![TUI של lazygit המציג תהליך עבודה של staging, committing ו-pushing](https://github.com/jesseduffield/lazygit/raw/assets/demo/commit_and_push-compressed.gif) + +[**lazygit**](https://github.com/jesseduffield/lazygit) הוא TUI (ממשק משתמש טרמינלי) ל-Git מבוסס Go לניהול branches ויזואלי, staging אינטראקטיבי וניווט commits. חוצה-פלטפורמות עם אפשרויות התאמה אישית נרחבות. + +**מאפיינים מבדלים עיקריים:** עץ branches ויזואלי מציג טופולוגיית מאגר ללא שינון פקודות. staging אינטראקטיבי תומך בבחירת hunks ו-staging של שורות בודדות. ניווט commits גולש בהיסטוריה עם diffs inline. keybindings ניתנים להתאמה דרך config YAML. תמיכת עכבר ללחיצה לבחירה, גלילה דרך commits. מודעות מרובת-worktrees לפיתוח branches מקביל. + +**מתאים במיוחד ל:** מפתחים שמנהלים תהליכי עבודה מרובי-worktrees שצריכים קונטקסט branches ויזואלי. מהנדסים שעושים rebases אינטראקטיביים מורכבים, cherry-picks ו-merges. משתמשים שרוצים discoverability של git דרך ממשק מונחה-תפריטים במקום שינון פקודות. + +**פשרות:** ביצועים נפגעים במאגרים מסיביים (Linux kernel: 57 שניות זמן טעינה, 2.6GB שימוש RAM). לא תחליף לכל פקודות git - כמה פעולות מהירות יותר דרך CLI גולמי. עקומת למידה ל-keybindings, אם כי ניתן לגילוי דרך תפריט עזרה מובנה. + +**התקנה:** + +```bash +# macOS +brew install lazygit + +# Go +go install github.com/jesseduffield/lazygit@latest + +# Windows +scoop install lazygit + +# Linux package managers +sudo apt install lazygit # Debian/Ubuntu +sudo pacman -S lazygit # Arch +``` + +דרישות: git. אופציונלי: config מותאם ב-`~/.config/lazygit/config.yml`. + +## ניווט קבצים + +### eza + +![רשימת תיקיות eza עם אייקונים, צבעים ומטא-נתוני קבצים](https://github.com/eza-community/eza/raw/main/docs/images/screenshots.png) + +[**eza**](https://eza.rocks/) הוא תחליף ל-ls מבוסס Rust, fork מתוחזק באופן פעיל של פרויקט exa הלא-מתוחזק. מהיר, עשיר בתכונות, עם ברירות מחדל טובות יותר מ-ls מסורתי. + +**מאפיינים מבדלים עיקריים:** צבעים לסוגי קבצים והרשאות כברירת מחדל. אינטגרציית git מציגה סטטוס לכל-קובץ (`--git`) או מצב מאגר לכל-תיקייה (`--git-repos`). גדלי קבצים קריאים-לאדם בפורמט long ללא flags. תצוגת עץ (`--tree`), תמיכת אייקונים (`--icons`) ותמיכת hyperlinks לאמולטורי טרמינל. מתקן Grid Bug מ-exa שגרם לבעיות rendering. + +**מתאים במיוחד ל:** מפתחים שעובדים על פני git worktrees שצריכים נראות סטטוס branch מיידית. מהנדסים שרוצים ברירות מחדל טובות יותר ל-ls ללא עומס תצורה כבד. משתמשים נוחים עם מערכת אקולוגית של כלי Rust מודרניים ומוכנים להתקין תלויות נוספות. + +**פשרות:** יותר תלויות מ-ls (binary Rust, Nerd Fonts אופציונלי לאייקונים). כמה תכונות דורשות תצורה (תמיכת אייקונים דורשת גופנים תואמים). עקומת למידה מעט ארוכה יותר לאפשרויות מתקדמות, אם כי ברירות מחדל עובדות טוב מיד. + +**התקנה:** + +```bash +# macOS +brew install eza + +# Cargo (Rust) +cargo install eza + +# Linux package managers +sudo apt install eza # Debian/Ubuntu +sudo pacman -S eza # Arch +``` + +### yazi + +![מנהל קבצים טרמינלי yazi עם layout מרובה-panes ותצוגה מקדימה של קבצים](https://yazi-rs.github.io/webp/full-border.webp) + +[**yazi**](https://yazi-rs.github.io/) הוא מנהל קבצים טרמינלי מבוסס Rust עם I/O אסינכרוני מלא והפצת משימות CPU מרובות-threads. כרגע בגרסת beta ציבורית, מתאים לשימוש יומיומי. + +**מאפיינים מבדלים עיקריים:** ארכיטקטורה אסינכרונית מלאה שומרת על UI רספונסיבי במהלך פעולות כבדות (תיקיות גדולות, filesystems מרוחקים). תמיכת preview עשירה לתמונות (פרוטוקולי Kitty, Sixel, iTerm2, WezTerm), וידאו, PDFs, archives וקוד עם הדגשת תחביר דרך אינטגרציה מובנית. מערכת plugins מבוססת Lua עם מנהל חבילות להרחבה. keybindings בסגנון Vim עם מצב visual, תמיכה מרובת-tabs ו-auto-completion. ארכיטקטורת client-server עם מודל pub-sub מאפשרת תקשורת בין מופעים. משתלב עם ripgrep, fd, fzf ו-zoxide לתהליכי עבודה משופרים. + +**מתאים במיוחד ל:** מפתחים שמנווטים מבני תיקיות מורכבים שצריכים previews קבצים עשירים מבלי לעזוב את הטרמינל. מהנדסים שעובדים עם filesystems מרוחקים שבהם רספונסיביות חשובה (I/O אסינכרוני מונע קפיאת UI). משתמשים שרוצים ניהול קבצים בסגנון Vim עם התאמה אישית נרחבת (plugins Lua, ערכות נושא, previewers מותאמים). + +**פשרות:** כרגע בגרסת beta ציבורית - יציב מספיק לשימוש יומיומי אבל מתפתח במהירות. מורכב יותר מכלים פשוטים יותר כמו nnn (שהוא זעיר, כמעט אפס-config). עקומת למידה ל-keybindings של Vim אם מגיעים ממנהלי קבצים מסורתיים. חסר תכונת "undo" ש-Vifm מספק. + +**התקנה:** + +```bash +# macOS +brew install yazi + +# Cargo (Rust) +cargo install --locked yazi-fm yazi-cli + +# Linux package managers +sudo pacman -S yazi # Arch +``` + +### fzf + +![fzf fuzzy finder עם חלון preview המציג תוכן קבצים](https://raw.githubusercontent.com/junegunn/i/master/fzf-preview.png) + +[**fzf**](https://junegunn.github.io/fzf/) הוא fuzzy finder מבוסס Go שמעבד מיליוני פריטים מיידית. binary יחיד, בוגר 11+ שנים (מאז 2013), מאומץ רחבות ככלי fuzzy CLI סטנדרטי. + +**מאפיינים מבדלים עיקריים:** אינטגרציית shell מספקת Ctrl+R (חיפוש היסטוריה), Ctrl+T (חיפוש קבצים), Alt+C (ניווט תיקיות) ו-`**` (fuzzy completion לכל פקודה). אינטגרציית Vim/Neovim דרך plugins של fzf.vim ו-fzf-lua. אינטגרציית tmux דרך wrapper של fzf-tmux לחלונות popup. תמיכת חלון preview מציגה תוכן קבצים או git diffs במהלך בחירה. ניתן להתאמה גבוהה דרך משתני סביבה (FZF_DEFAULT_OPTS, FZF_DEFAULT_COMMAND). ארכיטקטורה ידידותית-pipe עובדת עם כל פלט פקודה. + +**מתאים במיוחד ל:** מפתחים שמנווטים בסיסי קוד גדולים שצריכים מיקום קובץ/symbol מיידי ללא מעברי קונטקסט ל-IDE. מהנדסים עם שימוש shell כבד לחיפוש היסטוריית פקודות ובחירת סקריפטים. משתמשים שרוצים בחירת fuzzy בכל מקום - git branches, docker containers, kubernetes pods, רשימות תהליכים. + +**התקנה:** + +```bash +# macOS +brew install fzf +$(brew --prefix)/opt/fzf/install # Shell integration + +# Git clone +git clone --depth 1 https://github.com/junegunn/fzf.git ~/.fzf +~/.fzf/install + +# Linux package managers +sudo apt install fzf # Debian/Ubuntu +sudo pacman -S fzf # Arch +``` + +:::tip אינטגרציית Shell של fzf +עוצמה מלאה של fzf דורשת אינטגרציית shell. אחרי התקנה, הריצו: + +```bash +$(brew --prefix)/opt/fzf/install # macOS Homebrew +~/.fzf/install # Git installation +``` + +מאפשר: Ctrl+R (היסטוריה), Ctrl+T (קבצים), Alt+C (cd), `**` (completion) +::: + +### zoxide + +![zoxide קופץ לתיקיות עם התאמת שם חלקית](https://github.com/ajeetdsouza/zoxide/raw/main/contrib/tutorial.webp) + +[**zoxide**](https://github.com/ajeetdsouza/zoxide) הוא תחליף ל-cd מבוסס Rust שלומד דפוסי ניווט תיקיות. binary יחיד, אפס תלויות, תמיכה חוצת-פלטפורמות. + +**מאפיינים מבדלים עיקריים:** אלגוריתם frecency (שקלול תדירות + עדכניות) לומד אוטומטית אילו תיקיות אתם מבקרים בהן הכי הרבה. קפיצה לכל תיקייה עם התאמת שם חלקית (`z proj` מנווט ל-`/path/to/project`). קיצורי דרך לתת-תיקיות עם `zi` לבחירה אינטראקטיבית. תחליף חלק ל-`cd` - alias drop-in ללא שינויי תהליך העבודה. אינטגרציה עם מנהלי קבצים (yazi, lf) ו-fzf לגילוי משופר. למידת paths מהירה מפחיתה זמן סריקת תיקיות ב-60-80% אחרי שדפוסי שימוש התחלתיים נקבעים. + +**מתאים במיוחד ל:** מהנדסים שמנהלים worktrees או תיקיות פרויקטים מרובים שמבזבזים זמן על מעבר קונטקסט בין מיקומים. מפתחים עם מבני פרויקט עמוקים שבהם פקודות `cd` מרובות קורות באופן חוזר יומית. צוותים שמשתמשים ב-mono-repos או ארכיטקטורות microservices שבהם קפיצה בין תיקיות services תכופה. + +**פשרות:** שלב למידה נדרש - אלגוריתם frecency לוקח ימים להתייצב כש-zoxide בונה סטטיסטיקות paths. התאמת שם חלקית יכולה מדי פעם להתממש לתיקיות לא צפויות אם paths מרובים מתאימים (מצב אינטראקטיבי `zi` מקל). דורש תצורת shell להחלפת `cd` לחלוטין (הוספת alias היא טריוויאלית, אבל לא אוטומטית). דורש ללמוד שמות פקודות חדשים (אם כי `z` הופך לזיכרון שרירים מהר). + +**התקנה:** + +```bash +# macOS +brew install zoxide + +# Cargo (Rust) +cargo install zoxide + +# Linux package managers +sudo apt install zoxide # Debian/Ubuntu +sudo pacman -S zoxide # Arch +``` + +דרישות: הוסיפו ל-config shell (`~/.bashrc`, `~/.zshrc`, `~/.config/fish/config.fish`): `eval "$(zoxide init bash)"` או שווה ערך ל-shell שלכם. אופציונלי: fzf לבחירה אינטראקטיבית `zi`. + +## ניהול סשנים + +**קריטי לתהליכי עבודה מקבילים של סוכנים:** הרצת 4-6 מופעי Claude Code בו-זמנית דורשת terminal multiplexing. סעיף זה מכסה את הכלים שמאפשרים פיתוח מרובה סוכנים. דרישה מוקדמת: נוחות עם כלי ניווט הקבצים למעלה. + +### tmux + +![tmux עם שני panes מפוצלים שמריצים סשני טרמינל שונים](https://hamvocke.com/_astro/tmux_split.b845PJCE_Z2bALRv.webp) + +[**tmux**](https://github.com/tmux/tmux) הוא terminal multiplexer (מרבב טרמינלים) מבוסס C שמאפשר persistence של סשנים, פיצול חלונות וביצוע panes מקביל על שרתים מקומיים ומרוחקים. מבוסס ומוכח (battle-tested) לשימוש production מאז 2007, מומלץ לשרתים מרוחקים ותהליכי עבודה קריטיים שבהן ניתוקי טרמינל לא מקובלים. + +**מאפיינים מבדלים עיקריים:** סשנים ניתנים לניתוק שורדים ניתוקי SSH - התנתקו מכל מקום, התחברו מחדש מכל מקום, עם מצב מלא נשמר. ארכיטקטורת server-client שומרת על סשנים רצים בצד השרת גם אחרי יציאת client. פיצול panes (אופקי/אנכי) מריץ סוכנים מרובים זה-לצד-זה בחלון בודד ללא מעבר קונטקסט. ניהול חלונות מארגן תהליכי עבודה ל-tabs, כל אחד עם layouts panes עצמאיים. תצורה ניתנת לסקריפט דרך ~/.tmux.conf מאפשרת keybindings persistent וניהול plugins. plugin tmux-resurrect שומר סשנים לאורך reboot מערכת - הפעילו מחדש את המחשב, הריצו `tmux-resurrect restore`, ו-worktrees + מצב עורך משוחזרים במלואם. keybindings בסגנון Vim (עם התאמה אישית) משתלבים באופן טבעי בתהליכי עבודה של vim/nvim. + +**מתאים במיוחד ל:** מפתחים שמריצים 4-6 מופעי Claude Code בו-זמנית - השתמשו בחלונות מרובים (אחד לכל git worktree) או panes מפוצלים (סוכנים זה לצד זה) בהתאם לתהליך העבודה. מהנדסים שעובדים על שרתים מרוחקים שבהם ניתוקי SSH תכופים ואובדן סשן לא מקובל. צוותי DevOps/SRE שמנטרים תהליכים ארוכי-טווח שחייבים לשרוד הפרעות רשת. משתמשים שמשלבים עורכי טרמינל (vim, micro) עם tmux לפיתוח מונחה-מקלדת לחלוטין ללא IDE. + +**פשרות:** עקומת למידה התחלתית תלולה - ניווט panes, ניהול חלונות והמודל המנטלי של סשנים דורשים 1-2 שבועות עד שזה נכנס. מורכבות תצורה יכולה להסלים (plugins, keybindings, ניהול ערכות נושא) אם לא ממושמעים לגבי מינימליזם. debugging של מצב pane/session דורש הבנת ארכיטקטורת server; מצב "תקוע" לפעמים דורש הריגת server ואובדן סשנים. + +**לעומת tabs של אמולטור טרמינל:** tabs של טרמינל נמצאים בצד ה-client ומתים בניתוק. סשני tmux נשארים בצד השרת ללא הגבלת זמן - reboots, כשל רשת או שינה של לפטופ לא הורגים את העבודה שלכם. פשרה: tmux מוסיף עומס קוגניטיבי; tabs הם מודל מנטלי פשוט יותר לתהליכי עבודה של מכונה יחידה. + +**לעומת Zellij:** חדש יותר, עקומת למידה ידידותית יותר, keybindings ברירת מחדל טובים יותר וליטוש UI. tmux מחליף קצת ליטוש UX על 15+ שנים של ניסיון מוכח בשטח, footprint קטן יותר ונפוצות בשרתים מרוחקים שבהם אי אפשר להתקין Zellij. + +**התקנה:** + +```bash +# macOS +brew install tmux + +# Linux +sudo apt install tmux # Debian/Ubuntu +sudo pacman -S tmux # Arch +sudo yum install tmux # RedHat/CentOS + +# Build from source +git clone https://github.com/tmux/tmux.git +cd tmux +sh autogen.sh && ./configure && make +sudo make install +``` + +דרישות: libevent ו-ncurses (מותקנים מראש ברוב המערכות). אופציונלי: plugin tmux-resurrect ל-persistence סשנים (`git clone https://github.com/tmux-plugins/tmux-resurrect ~/.tmux/plugins/tmux-resurrect`). אופציונלי: tpm (Tmux Plugin Manager) לניהול plugins דרך config. + +### Zellij + +![workspace של Zellij בטרמינל עם panes מרובים וחלונות צפים](https://raw.githubusercontent.com/zellij-org/zellij/main/assets/demo.gif) + +[**Zellij**](https://zellij.dev/) הוא terminal multiplexer מבוסס Rust עם UI מודרני, ברירות מחדל עשירות שעובדות מהקופסה (batteries-included) ומערכת plugins של WASM. פיתוח פעיל, מתאים לשימוש יומיומי אבל מתפתח במהירות. שקלו tmux לשרתים מרוחקים או תהליכי עבודה קריטיים-למשימה. + +**מאפיינים מבדלים עיקריים:** מערכת layouts עם סידורי preset מובנים (tiled, floating, stacked) - פרודוקטיביות מיידית ללא תצורה. auto-tabbing מאפשר פיצול panes ללא ניהול חלונות מפורש. מערכת plugins מבוססת WASM מאפשרת plugins בכל שפה (Rust, JavaScript, Python דרך binding). UI מספק mode ויזואלי/תפריט מקשים - גלו תכונות ללא שינון. keybindings ברירת מחדל טובים יותר (ניווט ctrl+arrow אינטואיטיבי) בהשוואה למערכת prefix של tmux. buffer scrollback עם חיפוש מובנה ב-UI. תמיכת עכבר לבחירת panes, שינוי גודל וגלילה. + +**מתאים במיוחד ל:** מפתחים שמשתמשים ב-Zellij בעיקר לפיתוח מקומי על מכונות יחידות. מהנדסים שרוצים ברירות מחדל מודרניות ללא תצורה נרחבת (בסגנון tmux) להשגת פונקציונליות בסיסית. תהליכי עבודה מרובי סוכנים שדורשים מעבר קונטקסט תכוף בין משימות מקבילות בתוך מערכת יחידה. משתמשים נוחים עם כלים מתפתחים ומוכנים להסתגל לשינויי keybindings כשהפרויקט מתבגר. + +**פשרות:** keybindings עדיין מתפתחים - עדכונים עשויים לשבור זיכרון שרירים מבוסס. תמיכת שרתים מרוחקים ניסיונית; persistence סשני ssh לא מבוסס ומוכח (battle-tested) כמו tmux. מערכת אקולוגית של plugins קטנה משמעותית מ-tmux - פחות הרחבות למשתמשי power זמינות. לא מומלץ לעבודה מרוחקת ב-production או סשני SSH ארוכי-טווח שבהם יציבות tmux חיונית. תצורה דורשת למידת YAML/KDL במקום גישת הסקריפטינג של tmux. + +**לעומת tmux:** ברירות מחדל טובות יותר ועקומת למידה לתהליכי עבודה של פיתוח מקומי. Zellij מעדיף נגישות; tmux מתגמל השקעת תצורה עמוקה. פשרה: Zellij פחות יציב לעבודה מרוחקת, מערכת אקולוגית plugins קטנה יותר, keybindings עדיין מתפתחים. + +**לעומת splits של אמולטור טרמינל מסורתי (iTerm2, WezTerm):** splits native לטרמינל לא נשמרים לאורך SSH - רק multiplexers (tmux, Zellij) מאפשרים סשנים ניתנים לניתוק. splits של טרמינל חיים ב-GUI; סשני multiplexer חיים על השרת/מכונה. + +**התקנה:** + +```bash +# macOS +brew install zellij + +# Cargo (Rust) +cargo install zellij + +# Linux package managers +sudo pacman -S zellij # Arch +# Others: check https://zellij.dev/documentation/installation +``` + +## אוטומציית דפדפן + +### agent-browser + +[**agent-browser**](https://agent-browser.dev/) הוא CLI מבוסס Rust לאוטומציית דפדפן שתוכנן במיוחד לסוכני AI. binary native, תמיכה חוצת-פלטפורמות, עובד עם כל סוכן שמריץ פקודות shell. + +**מאפיינים מבדלים עיקריים:** מערכת עץ נגישות מבוססת-ref מחזירה snapshots קומפקטיים עם references אלמנטים דטרמיניסטיים (`@e1`, `@e2`) - סוכנים לוחצים לפי ref במקום CSS selectors שבירים או XPath. פלט יעיל בטוקנים (200-400 טוקנים ל-snapshot לעומת 5,000-15,000 ל-DOM מלא) שומר על ה-context window של הסוכן. מעל 50 פקודות מכסות ניווט, forms, screenshots, בדיקת רשת ואחסון. תמיכת sessions מאפשרת מופעי דפדפן מבודדים מרובים עם מצבי אימות נפרדים. CLI native ב-Rust מספק פרסור פקודות מיידי ללא עומס runtime של Node.js או Python. + +**מתאים במיוחד ל:** תהליכי עבודה בסיוע-AI שבהן סוכנים צריכים לתקשר עם UI אינטרנט - בדיקת שינויים בדפדפן, מילוי forms, שליפת נתונים, אימות deployments. מהנדסים שמשתמשים בסוכנים מבוססי CLI (Claude Code, Cursor, Copilot) שצריכים אוטומציית דפדפן ללא הגדרת שרת MCP. מפתחים שרוצים בחירת אלמנטים דטרמיניסטית על פני פרסור ויזואלי מבוסס-screenshot או אסטרטגיות selector שבירות. + +**פשרות:** בחירה מבוססת-ref דורשת snapshot לפני אינטראקציה (מינימום שתי פקודות). מסתמך על עץ נגישות, שעשוי לפספס תוכן שמורנדר דינמית ללא ARIA attributes מתאימים - ודאו שלאפליקציות יעד יש markup סמנטי. + +**דוגמת תהליך עבודה:** + +```bash +agent-browser open example.com +agent-browser snapshot -i # Returns refs: [ref=@e1] "Example Domain", [ref=@e2] "More information..." +agent-browser click @e2 # Click by ref—deterministic, no selector fragility +agent-browser screenshot page.png +agent-browser close +``` + +**התקנה:** + +```bash +# npm (recommended) +npm install -g agent-browser + +# Verify installation +agent-browser --version +``` + +דרישות: Node.js 18+ להתקנת npm. דפדפן מבוסס Chromium (מצורף או Chrome מערכת). + +:::tip למה אוטומציה מבוססת-Ref מנצחת +הגישה מבוססת-ref של agent-browser (`@e1`, `@e2`) מייצרת בחירת אלמנטים דטרמיניסטית שעולה על אלטרנטיבות מבוססות-selector. ה-snapshot של עץ הנגישות לוכד מבנה סמנטי, לא layout ויזואלי - סוכנים מבינים מה אלמנטים *הם* ולא איפה הם מופיעים על המסך. זה מוביל לאוטומציה אמינה יותר ששורדת שינויי UI. +::: + +--- + +**תוכן קורס קשור:** + +- [שיעור 7: תכנון וביצוע](/docs/practical-techniques/lesson-7-planning-execution) - תהליכי עבודה מרובי-worktree שממנפות כלי CLI אלה +- [כלי מפתח: טרמינלים](/developer-tools/terminals) - המלצות טרמינל להרצת כלי CLI אלה ביעילות +- [כלי מפתח: שרתי MCP](/developer-tools/mcp-servers) - הרחיבו סוכני CLI עם מחקר קוד והארקה באינטרנט diff --git a/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current/mcp-servers.md b/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current/mcp-servers.md new file mode 100644 index 0000000..25662a8 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current/mcp-servers.md @@ -0,0 +1,95 @@ +--- +title: שרתי MCP +sidebar_position: 4 +--- + +# שרתי MCP + +[Model Context Protocol (MCP)](https://modelcontextprotocol.io) מרחיב סוכני CLI עם יכולות מתמחות - מחקר קוד, עיגון (grounding) לאינטרנט, אוטומציית דפדפן. בעוד שעוזרים מבוססי IDE כמו Cursor ו-Windsurf לרוב כוללים תכונות אלה מובנות, סוכני CLI כמו Claude Code, Copilot CLI ו-Aider מסתמכים על שרתי MCP כדי להוסיף פונקציונליות מעבר לפעולות בסיסיות על קבצים. + +שרתי MCP אלה מטפלים בפערים הקריטיים בתהליכי עבודה של פיתוח בסיוע AI. + +## מחקר קוד + +### ChunkHound + +[ChunkHound](https://chunkhound.github.io) מספק חיפוש קוד סמנטי ומחקר מובנה באמצעות תת-סוכנים (sub-agents) עבור בסיסי קוד גדולים. + +**מה הוא עושה:** + +- חיפוש סמנטי multi-hop דרך קשרים בקוד +- חיפוש היברידי סמנטי + סימבולי (גילוי קונספטואלי, ואז regex ממצה) +- סינתזה בגישת map-reduce עם קשרים ארכיטקטוניים וציטוטי `file:line` + +**מתי להשתמש בו:** + +- **10,000-100,000 שורות קוד:** שימושי כשמחברים רכיבים שוב ושוב ברחבי בסיס הקוד +- **100,000+ שורות קוד:** בעל ערך רב כאשר סוכנים אוטונומיים מחזירים תוצאות חלקיות +- **1,000,000+ שורות קוד:** חיוני - הגישה היחידה עם אגרגציה פרוגרסיבית (progressive aggregation) בסקייל קיצוני + +**Trade-off מרכזי:** עלות טוקנים גבוהה יותר (1-2x) לעומת חיפוש אוטונומי, אבל שומר על דיוק כבר באיטרציה הראשונה הודות לבידוד קונטקסט. + +**התקנה:** + +```bash +uv tool install chunkhound +``` + +דורש Python 3.10+ ומנהל החבילות uv. ראה [ChunkHound ב-GitHub](https://github.com/chunkhound/chunkhound) להגדרת מפתח API ופרטי הגדרה. + +**למד עוד:** [שיעור 5: עיגון](/docs/methodology/lesson-5-grounding#deep-dive-chunkhound-architecture) מכסה את הארכיטקטורה של ChunkHound, עיצוב pipeline והנחיות סקייל בפירוט. + +## מחקר אינטרנט + +### ArguSeek + +[ArguSeek](https://github.com/ArguSeek/arguseek) הוא תת-סוכן למחקר אינטרנט עם קונטקסט מבודד וניהול state סמנטי. + +**מה הוא עושה:** + +- Google Search API (איכות לעומת Bing/אלטרנטיבות קנייניות) +- פירוק שאילתות (query decomposition) - 3 וריאציות במקביל לכל שאילתה (docs + קהילה + security advisories) +- חיסור סמנטי (semantic subtraction) - שאילתות המשך מדלגות על תוכן שכבר כוסה ומקדמות את המחקר +- זיהוי הטיה (bias detection) - מסמן שיווק של ספקים ומפעיל מחקר נגדי + +**מתי להשתמש בו:** + +- מחקר best practices וגישות מתחרות +- מציאת security advisories ו-CVEs +- לימוד טכנולוגיות חדשות עם מידע עדכני (post-training) +- מחקר מרובה-מקורות (מעבד 12-30 מקורות לכל קריאה, מתרחב ל-100+ מקורות למשימה) + +**יתרון מרכזי:** שומר state בין שאילתות - בונה על מחקר קודם במקום להסביר שוב את הבסיס, ושומר על הקונטקסט של ה-orchestrator שלך נקי. + +**התקנה:** + +```bash +brew install arguseek +``` + +דורש Go 1.23+ ו-credentials של Google API. ראה [ArguSeek ב-GitHub](https://github.com/ArguSeek/arguseek) להוראות הגדרה מפורטות ואפשרויות תצורה. + +**למד עוד:** [שיעור 5: עיגון](/docs/methodology/lesson-5-grounding#deep-dive-arguseek-architecture) מסביר את הארכיטקטורה של ArguSeek, חיסור סמנטי ודפוסי מחקר. + +## אוטומציית דפדפן + +אוטומציית דפדפן לסוכני AI מטופלת על ידי **agent-browser CLI** - כלי ייעודי שמספק באופן עקבי תוצאות טובות יותר מאלטרנטיבות מבוססות MCP. + +ראה [agent-browser בכלי CLI](/developer-tools/cli-tools#agent-browser) להתקנה ושימוש. + +**למה CLI ולא MCP לאוטומציית דפדפן:** +- **תוצאות טובות יותר:** עץ נגישות (accessibility tree) מבוסס ref מייצר בחירת אלמנטים דטרמיניסטית ואמינה +- **יעיל בטוקנים:** 500-2000 טוקנים לכל snapshot לעומת 5,000-15,000 ב-DOM dumps של MCP +- **הגדרה פשוטה יותר:** ללא קונפיגורציית MCP, עובד עם כל סוכן שמסוגל להריץ shell +- **איטרציה מהירה יותר:** CLI נייטיב ב-Rust עם פרסור פקודות מיידי + +:::note Deprecated: שרתי MCP לדפדפן +המלצות קודמות כללו Playwright MCP ו-Chrome DevTools MCP. כלים אלה כעת deprecated עבור תהליכי עבודה אגנטיים - הגישה מבוססת-ref של agent-browser מספקת אוטומציה אמינה יותר עם פחות overhead של טוקנים. שרתי MCP עדיין זמינים לאינטגרציות legacy אבל לא מומלצים לפרויקטים חדשים. +::: + +--- + +**תוכן קורס קשור:** + +- [שיעור 5: עיגון](/docs/methodology/lesson-5-grounding) - ארכיטקטורה מפורטת ומקרי שימוש עבור ChunkHound ו-ArguSeek +- [שיעור 7: תכנון וביצוע](/docs/practical-techniques/lesson-7-planning-execution) - תהליכי עבודה מרובי סוכנים שמנצלים יכולות MCP diff --git a/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current/terminals.md b/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current/terminals.md new file mode 100644 index 0000000..621194a --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-developer-tools/current/terminals.md @@ -0,0 +1,105 @@ +--- +title: טרמינלים +sidebar_position: 2 +--- + +# טרמינלים מודרניים לעבודה עם מספר סוכנים + +**השקיעו בהתאמה אישית של סביבת הטרמינל שלכם בדיוק כמו שהייתם עושים עם ה-IDE שלכם.** עבודה עם מספר סוכנים במקביל דורשת ניהול סשנים מקבילים, מעבר קונטקסט (context switching) בין מופעי סוכנים, ומעקב אחר תהליכים ארוכי-טווח. הטרמינל שלכם הופך לתשתית קריטית, לא רק שורת פקודה. + +הטרמינל הוא הבסיס - כשמשלבים אותו עם [כלי CLI מודרניים](/developer-tools/cli-tools) מקבלים סביבת פיתוח מלאה עם יכולות ברמת IDE. דף זה מכסה בחירה והגדרה של טרמינל, ודף כלי CLI מפרט את המערכת האקולוגית שהופכת את הטרמינל שלכם לסביבת עבודה מלאת תכונות. + +## למה טרמינלים מודרניים חשובים + +טרמינלים מודרניים מציעים תכונות ברמת IDE - האצת GPU, layouts ניתנים לתכנות, סקריפטינג עשיר והתאמה אישית נרחבת - שטרמינלים ישנים לא יכולים להתחרות בהם. בעבודה עם מספר סוכנים, יכולות אלה מתורגמות ישירות לפרודוקטיביות: טיפול חלק בזרמי פלט מהירים, ניהול סשנים ניתן לתכנות, והתאמה ויזואלית למעקב אחר קונטקסטים שונים. + +:::tip מחקר להתאמה אישית +השתמשו ב-ArguSeek כדי לחקור best practices לטרמינל שבחרתם - ניהול סשנים, keybindings ואינדיקטורים ויזואליים לקונטקסטים שונים של סוכנים. +::: + +## Ghostty + +[**Ghostty**](https://ghostty.org) הוא טרמינל native עם האצת GPU שנכתב ב-Zig על ידי Mitchell Hashimoto (מייסד-שותף של HashiCorp), ששוחרר לציבור בדצמבר 2024. הוא עוקב אחר פילוסופיית "zero configuration" - עובד מהקופסה בלי הגדרות, אבל מאפשר התאמה אישית נרחבת דרך קבצי config פשוטים של key-value. + +**יתרונות עיקריים:** multiplexing מובנה (tabs, splits) מפחית תלות ב-multiplexers חיצוניים כמו tmux. אינטגרציה native באמצעות SwiftUI/AppKit ב-macOS ו-GTK ב-Linux. אינטגרציית shell אוטומטית לטיפול בפרומפטים מורכבים. Command palette לגישה מהירה לפעולות. ממוקד-פרטיות ללא telemetry או תכונות ענן - פועל לחלוטין offline. + +**מתאים במיוחד ל:** מפתחים שרוצים להחליף tmux בתכונות טרמינל native. צוותים שמעדיפים פרטיות ותהליכי עבודה local-first. מהנדסים שמעריכים אינטגרציית פלטפורמה native וזמני הפעלה מתחת ל-100ms. + +**חסרונות:** פרויקט חדש יחסית (שוחרר לציבור בדצמבר 2024) עם קהילה הולכת וגדלה - חזק במיוחד ב-macOS - אבל אקוסיסטם קטן יותר מטרמינלים ותיקים. תמיכת Windows מוגבלת. מותאם לעומסי עבודה נפוצים (גלילת plaintext, מעט שינויי סגנון) - עלול להיות איטי יותר ב-stress tests סינתטיים עם שינויי סגנון מהירים. + +## Kitty + +[**Kitty**](https://sw.kovidgoyal.net/kitty/) הוא טרמינל עם האצת GPU שנוצר על ידי Kovid Goyal (יוצר Calibre) שהיה חלוץ בפיתוח פרוטוקול גרפיקה משלו לרינדור תמונות ואנימציות ישירות בטרמינל. חוצה-פלטפורמות (Linux, macOS, BSD) עם סט תכונות נרחב. + +**יתרונות עיקריים:** פרוטוקול גרפיקה ייחודי שמאפשר תמונות inline, GIFs ותצוגת מדיה עשירה. "Kittens" - סקריפטי Python להרחבת פונקציונליות. tabs, splits ו-layouts ניתנים לתכנות. גלילה בהיסטוריית פקודות או בפלט הפקודה האחרונה ב-pagers/editors. בחירה ויזואלית וקלט בו-זמני במספר חלונות. + +**מתאים במיוחד ל:** מפתחים שצריכים יכולות מדיה עשירה (ויזואליזציית נתונים, תצוגות מקדימות של תמונות במנהלי קבצים). מהנדסים שכותבים סקריפטים ב-Python. צוותים שבונים כלי טרמינל מותאמים עם פרוטוקול הגרפיקה של Kitty. + +**חסרונות:** latency גבוה יותר בקלט בהשוואה ל-Alacritty וטרמינלים מינימליסטיים אחרים. ריבוי התכונות עלול להרגיש מכביד למי שמעדיף מינימליזם. פרויקט ותיק (2017) עם פיתוח פעיל וקהילה גדולה. + +## WezTerm + +[**WezTerm**](https://wezterm.org) הוא טרמינל ו-multiplexer עם האצת GPU, חוצה-פלטפורמות, מיושם ב-Rust. מוגדר לחלוטין דרך סקריפטינג Lua לתכנותיות מקסימלית. + +**יתרונות עיקריים:** קונפיגורציה ב-Lua מאפשרת הגדרות סשן דינמיות, layouts אוטומטיים ולוגיקה מותנית. multiplexer משולב עם סשנים persistent, panes, tabs וחלונות. אינטגרציית SSH מעולה שמתייחסת לשרתים מרוחקים כמו טרמינלים מקומיים. קיבוץ workspaces למעבר קונטקסט מבוסס-פרויקט. hot-reload של קונפיגורציה ללא הפעלה מחדש. + +**מתאים במיוחד ל:** מפתחים שעובדים על מספר פלטפורמות שצריכים סביבות עקביות. מהנדסים עם תהליכי עבודה מרוחקות מורכבות. צוותים שכותבים סקריפטים להגדרת סביבת הפיתוח שלהם. משתמשי Neovim שרוצים אינטגרציה הדוקה בין טרמינל לעורך. + +**חסרונות:** עקומת למידה ל-Lua בהתאמה אישית מתקדמת. שמירת סשנים (session persistence) לא חזקה כמו השחזור האוטומטי של tmux. מתוחזק באופן פעיל עם פיתוח יציב ובסיס משתמשים חוצה-פלטפורמות נאמן. + +## Alacritty + +[**Alacritty**](https://alacritty.org) הוא טרמינל מינימליסטי עם האצת OpenGL שנכתב ב-Rust עם פילוסופיית "ביצועים קודם". מינימלי בתכונות בכוונה. + +**יתרונות עיקריים:** input latency הנמוך ביותר בין טרמינלים עם האצת GPU (ממוצע של כ-7ms). קונפיגורציה מבוססת טקסט (YAML/TOML). מערכת "hints" מתקדמת שמשתמשת בתבניות regex להפיכת טקסט בטרמינל לקליק (למשל, לחצו על filename:line לפתיחה בעורך). שואף לקצב פריימים מקסימלי, ומציג מצבי ביניים לצורך מעקב ויזואלי. + +**מתאים במיוחד ל:** מי שמעדיף ביצועים מקסימליים ומהירות גולמית. מפתחים שכבר משתמשים ב-tmux או Zellij ל-multiplexing. מהנדסים שמעדיפים את פילוסופיית Unix (עשה דבר אחד טוב) ומרכיבים תכונות מכלים חיצוניים. + +**חסרונות:** אין tabs, splits או multiplexing מובנים - דורש כלים חיצוניים. אין תמיכה בתמונות inline או פרוטוקול גרפיקה. קונפיגורציה מוגבלת לקבצי טקסט (ללא סקריפטינג). המינימליזם מצריך יותר הגדרה ידנית לתהליכי עבודה מתקדמות. מאומץ באופן רחב כמדד הביצועים (benchmark) בין טרמינלים מודרניים, עם אקוסיסטם בוגר (2017) ותחזוקה פעילה. + +## iTerm2 + +[**iTerm2**](https://iterm2.com) הוא אמולטור טרמינל עשיר בתכונות ל-macOS, ונחשב לטרמינל צד-שלישי הפופולרי ביותר בפלטפורמה. למרות שאין לו האצת GPU, הוא מציע פונקציונליות נרחבת שהפכה אותו לבחירת ברירת המחדל של מפתחי macOS במשך יותר מעשור. + +**יתרונות עיקריים:** ניהול מרובה-panes עם קלט בו-זמני לכל ה-panes. תכונת AI Chat חדשה להסבר פלט פקודות והוספת הערות. אינטגרציית shell עם היסטוריה סמנטית - לחצו על שמות קבצים לפתיחה בעורכים. theming נרחב עם ערכות צבעים, גופנים, שקיפות ותמונות רקע. אינטגרציית SSH חזקה עם profiles ניתנים להגדרה והורדות קבצים ישירות. + +**מתאים במיוחד ל:** מפתחי macOS שרוצים טרמינל בוגר ומוכח בקרב. צוותים שמעדיפים יציבות ותיעוד נרחב על פני תכונות חדשניות. מהנדסים שכבר מושקעים באקוסיסטם של macOS ולא צריכים תאימות חוצת-פלטפורמות. + +**חסרונות:** macOS בלבד - אין תמיכה ב-Linux או Windows. אין האצת GPU, אם כי הביצועים מספיקים לרוב תהליכי העבודה. צריכת משאבים גבוהה יותר מטרמינלים מינימליסטיים כמו Alacritty. פרויקט בוגר (2006) עם קהילה רחבה ופיתוח פעיל. + +## Warp + +[**Warp**](https://www.warp.dev) הוא טרמינל מבוסס Rust עם האצת GPU ואינטגרציית AI native. נבנה לתהליכי עבודה של פיתוח מודרני עם תכונות שיתוף פעולה מובנות וסיוע מונע-AI. חוצה-פלטפורמות (macOS, Windows, Linux). + +**יתרונות עיקריים:** עוזר AI native משולב ישירות בטרמינל - מספק הצעות פקודות, עזרה ב-debugging ויצירת פקודות בשפה טבעית באמצעות מודלים מתקדמים (OpenAI, Anthropic, Google). ממשק מוכוון-blocks שמארגן פקודות ופלטים ליחידות נפרדות שניתן לשתף. תכונות שיתוף פעולה דרך "Warp Drive" לשיתוף תהליכי עבודה של פקודות ו-notebooks בין צוותים. מערכת credits AI (150 credits AI/חודש ל-2 החודשים הראשונים, אחר כך 75/חודש בתוכנית החינמית). Command palette ו-UX מודרני עם דגש על גילוי תכונות. + +**מתאים במיוחד ל:** מפתחים שמעדיפים תהליכי עבודה מונעות-AI ואינטגרציה הדוקה עם הטרמינל. צוותים שמשתפים פעולה על תהליכי עבודה בשורת פקודה וסשני debugging. מהנדסים שמעריכים ארגון מבוסס-blocks למעקב אחר סשנים עם מספר סוכנים. משתמשים שמוכנים לוותר על עקרונות קוד פתוח ופרטיות לטובת תכונות פרודוקטיביות AI. + +**חסרונות:** מודל freemium/מסחרי - תוכנית חינמית מוגבלת ל-75 credits AI/חודש; תוכניות בתשלום מתחילות ב-$20/חודש (Build: 1,500 credits) ועולות ל-$50+/משתמש/חודש לתכונות Business/Enterprise. קוד סגור - codebase קנייני; החברה הצהירה "כנראה אף פעם לא יהיה קוד פתוח" (2025). אי אפשר לעשות audit לאבטחה או לתקן באופן עצמאי. חששות פרטיות - telemetry ואחסון ענן אופציונליים לתכונות AI; תוכן הטרמינל, קלטים/פלטים של AI עשויים להיות מאוחסנים בשרתי GCP כשמשתמשים בתכונות ענן (תואם SOC 2 עם הצפנה at rest/transit). התחברות אופציונלית מנובמבר 2024, אבל נדרשת לתכונות ענן (AI, Drive, סנכרון היסטוריה). תלות באינטרנט לתכונות AI - פונקציונליות offline מוגבלת בהשוואה לטרמינלים מסורתיים. פיתוח פעיל עם קהילה הולכת וגדלה, במיוחד בקרב מפתחים שמשלבים AI בתהליכי עבודה. + +## Windows Terminal + +[**Windows Terminal**](https://aka.ms/terminal) הוא אפליקציית הטרמינל המודרנית עם האצת GPU של Microsoft עבור Windows. מותקן מראש ב-Windows 11 ו-Windows Server 2025, הוא משמש כחוויית הטרמינל המודרנית המוגדרת כברירת מחדל למערכת האקולוגית של Windows. + +**יתרונות עיקריים:** תמיכה במספר shells - מארח Command Prompt, PowerShell, Azure Cloud Shell והפצות WSL בממשק מאוחד. tab tearout לגרירת tabs בין חלונות. רינדור טקסט עם האצת GPU. התאמה אישית נרחבת כולל ערכות נושא, תמונות רקע ו-keybindings. אינטגרציית Windows native עם אפליקציית Settings ומנהל החבילות WinGet. + +**מתאים במיוחד ל:** מפתחי Windows ומנהלי מערכת. צוותים שעובדים עם WSL לפיתוח Linux על Windows. מהנדסים בסביבות ממוקדות-Microsoft שצריכים גישה ל-PowerShell, Azure CLI ו-CMD. + +**חסרונות:** Windows בלבד - אין תמיכה ב-macOS או Linux. פחות תכונות מתקדמות מאלטרנטיבות חוצות-פלטפורמות (אין multiplexing מובנה מעבר ל-tabs). מחזור עדכונים קשור לשחרורי Windows, אם כי זמין דרך Microsoft Store. פרויקט בוגר עם פיתוח פעיל ואימוץ נרחב כטרמינל הסטנדרטי של Windows. + +## Wave Terminal + +[**Wave Terminal**](https://www.waveterm.dev) הוא אמולטור טרמינל בקוד פתוח, AI-native עם האצת GPU. חוצה-פלטפורמות (macOS, Windows, Linux), הוא מציע תכונות מונעות-AI ללא ויתורים על הפרטיות שמאפיינים אלטרנטיבות קוד סגור. + +**יתרונות עיקריים:** צ'אט AI משולב שתומך במודלים מרובים (OpenAI, Anthropic, מודלים מקומיים דרך Ollama). Command Blocks לבידוד, ניטור וסגירה אוטומטית של פקודות בודדות. עורך מובנה לקבצים מקומיים ומרוחקים. תצוגה מקדימה של קבצים - Markdown, תמונות ווידאו. דפדפן אינטרנט inline. לא נדרשת התחברות - עובד לחלוטין עם מפתחות API שאתם מספקים. + +**מתאים במיוחד ל:** מפתחים שרוצים תהליכי עבודה AI-native ללא החששות של Warp לגבי קוד סגור ופרטיות. צוותים שדורשים כלים בקוד פתוח בשביל compliance או auditability. מהנדסים שמעדיפים להביא מפתחות API משלהם במקום מודלי מנוי. + +**חסרונות:** פרויקט חדש יחסית (2024) עם קהילה קטנה יותר מטרמינלים ותיקים. תכונות AI דורשות מפתחות API חיצוניים ועלויות נלוות. ממשק מורכב יותר מטרמינלים מסורתיים - עקומת למידה תלולה יותר. פיתוח פעיל עם אימוץ גדל בקרב מפתחים שמודעים לפרטיות. + +--- + +**קשור:** + +- [כלי מפתח: כלי CLI מודרניים](/developer-tools/cli-tools) - האקוסיסטם שמשלים את סביבת הפיתוח מבוססת-הטרמינל שלכם +- [שיעור 7: תכנון וביצוע](/docs/practical-techniques/lesson-7-planning-execution) - תהליכי עבודה מרובי worktree שמנצלות טרמינלים מודרניים diff --git a/website/i18n/he/docusaurus-plugin-content-docs-prompts/current.json b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current.json new file mode 100644 index 0000000..f04dc72 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current.json @@ -0,0 +1,34 @@ +{ + "version.label": { + "message": "הבא", + "description": "The label for version current" + }, + "sidebar.promptsSidebar.category.Testing": { + "message": "טסטים", + "description": "The label for category 'Testing' in sidebar 'promptsSidebar'" + }, + "sidebar.promptsSidebar.category.Code Review": { + "message": "קוד ריביו", + "description": "The label for category 'Code Review' in sidebar 'promptsSidebar'" + }, + "sidebar.promptsSidebar.category.Pull Requests": { + "message": "Pull Requests", + "description": "The label for category 'Pull Requests' in sidebar 'promptsSidebar'" + }, + "sidebar.promptsSidebar.category.Debugging": { + "message": "דיבאגינג", + "description": "The label for category 'Debugging' in sidebar 'promptsSidebar'" + }, + "sidebar.promptsSidebar.category.Onboarding": { + "message": "אונבורדינג", + "description": "The label for category 'Onboarding' in sidebar 'promptsSidebar'" + }, + "sidebar.promptsSidebar.category.Specifications": { + "message": "ספציפיקציות", + "description": "The label for category 'Specifications' in sidebar 'promptsSidebar'" + }, + "sidebar.promptsSidebar.doc.Overview": { + "message": "סקירה כללית", + "description": "The label for the doc item 'Overview' in sidebar 'promptsSidebar', linking to the doc index" + } +} diff --git a/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/code-review/comprehensive-review.md b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/code-review/comprehensive-review.md new file mode 100644 index 0000000..7b82b1f --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/code-review/comprehensive-review.md @@ -0,0 +1,25 @@ +--- +title: סקירת קוד מקיפה +sidebar_position: 1 +--- + +import ComprehensiveReview from '@site/shared-prompts/\_comprehensive-review.mdx'; + + + +### סקירה כללית (Overview) + +**למה framework ארבע-קטגוריות עובד:** [הנחיית Persona](/docs/methodology/lesson-4-prompting-101#assigning-personas) ("סוקר קוד מומחה") מכוונת את אוצר המילים לניתוח ביקורתי במקום סיכום תיאורי—"מפר single responsibility" מול "הפונקציה הזו עושה כמה דברים." תיאור שינויים מפורש (`$DESCRIBE_CHANGES`) מעגן את ה[גראונדינג (Grounding)](/docs/methodology/lesson-5-grounding#grounding-anchoring-agents-in-reality) דרך הגדרת הכוונה, ומאפשר לזהות פערים בין מטרות לביצוע (התכוונו להוסיף caching, בפועל נוספו side effects). מבנה רציף וממוספר מיישם חשיבה מסוג [Chain-of-Thought](/docs/methodology/lesson-4-prompting-101#chain-of-thought-paving-a-clear-path) על פני ממדי הסקירה, ומונע מסקנות מוקדמות—אי אפשר להעריך maintainability בלי להבין קודם את הארכיטקטורה. הנחיית הגראונדינג ("Use ChunkHound") מכריחה חקירה אמיתית של בסיס הקוד במקום הזיה (hallucination) של דפוסים מנתוני אימון. ה[אילוץ](/docs/methodology/lesson-4-prompting-101#constraints-as-guardrails) "DO NOT EDIT" שומר על הפרדה בין שלבי סקירה ומימוש, ומונע תיקונים מוקדמים לפני ניתוח מקיף. ארבע קטגוריות מבטיחות כיסוי שיטתי: ארכיטקטורה (נכונות מבנית, התאמת דפוסים, גבולות מודולים), איכות קוד (קריאות, עקביות סגנון, עמידה ב-KISS), תחזוקתיות (Maintainability) (הבנת LLM עתידית, סנכרון תיעוד, בהירות כוונה), UX (שיפורים משמעותיים, איזון פשטות-ערך). + +**מתי להשתמש—דרישה קריטית לקונטקסט טרי:** תמיד הריצו ב[קונטקסט טרי](/docs/fundamentals/lesson-2-how-agents-work#the-stateless-advantage) נפרד מהמקום שבו נכתב הקוד—סוכנים שסוקרים את העבודה שלהם באותה שיחה נוטים להגן על החלטות קודמות במקום לספק ניתוח אובייקטיבי (confirmation bias מקונטקסט מצטבר). השתמשו לאחר השלמת המימוש (שלב Execute הסתיים), לאחר refactoring (שינויי ארכיטקטורה), לפני הגשת PR ([שלב Validate](/docs/methodology/lesson-3-high-level-methodology#the-four-phase-workflow)). קריטי: היו ספציפיים עם `$DESCRIBE_CHANGES`—תיאורים מעורפלים ("תקן באגים", "עדכן קוד") מונעים ניתוח של ההתאמה בין כוונה למימוש; תיאורים יעילים מציינים את המטרה הארכיטקטונית ("הוסף שכבת Redis caching ל-user service", "שכתב authentication לשימוש בטוקני JWT"). סקירה היא איטרטיבית: סקור בקונטקסט טרי → תקן בעיות → הרץ בדיקות → סקור מחדש בשיחה חדשה → חזור עד green light או diminishing returns (תועלת פוחתת). הפסיקו לחזור כשהבדיקות עוברות והמשוב הנותר הוא מינורי (3-4 מחזורים מקסימום)—איטרציה מוגזמת גורמת לרגרסיות שנובעות מהסקירה עצמה, כשתיקונים עונים לביקורת אבל לא באמת משפרים את הפונקציונליות. + +**דרישות קדם (Prerequisites):** [יכולות מחקר קוד](https://chunkhound.github.io/) (חיפוש סמנטי על פני בסיס הקוד, גילוי דפוסים ארכיטקטוניים, קריאת מימוש), גישה לשינויי git working tree (`git diff`, `git status`), תיעוד ארכיטקטורת הפרויקט (CLAUDE.md, AGENTS.md, README). דורש תיאור מפורש של שינויים מתוכננים (`$DESCRIBE_CHANGES`), גישה הן לקבצים שהשתנו והן לקונטקסט המקיף לצורך התאמת דפוסים. הסוכן מספק משוב מובנה לפי קטגוריה עם נתיבי קבצים, מספרי שורות, בעיות ספציפיות והמלצות ישימות ([דרישות ראיות](/docs/practical-techniques/lesson-7-planning-execution#require-evidence-to-force-grounding)). [התאימו את הדפוס לסקירות מתמחות](/docs/practical-techniques/lesson-9-reviewing-code#mechanisms-at-work): אבטחה (מיפוי attack surface/גבולות אימות קלט/זרימות authentication/טיפול ב-credentials/OWASP Top 10), ביצועים (מורכבות אלגוריתמית/יעילות שאילתות DB/הקצאת זיכרון/פעולות I/O/אסטרטגיית caching), נגישות (מבנה HTML סמנטי/ניווט מקלדת/ARIA labels/תאימות קורא מסך/יחסי ניגוד צבעים), עיצוב API (מוסכמות REST/תגובות שגיאה/versioning/תאימות לאחור). + +### שיעורים קשורים + +- **[שיעור 3: מתודולוגיה ברמה גבוהה](/docs/methodology/lesson-3-high-level-methodology#the-four-phase-workflow)** ← תהליך עבודה בארבעה שלבים (Research > Plan > Execute > Validate) — סקירה היא שלב ה-Validate +- **[שיעור 4: Prompting 101](/docs/methodology/lesson-4-prompting-101)** ← [הנחיות Persona](/docs/methodology/lesson-4-prompting-101#assigning-personas), [Chain-of-Thought](/docs/methodology/lesson-4-prompting-101#chain-of-thought-paving-a-clear-path), [אילוצים](/docs/methodology/lesson-4-prompting-101#constraints-as-guardrails), פרומפטינג מובנה +- **[שיעור 5: גראונדינג](/docs/methodology/lesson-5-grounding#grounding-anchoring-agents-in-reality)** ← ChunkHound למחקר בסיס קוד, מניעת הזיות (hallucinations) +- **[שיעור 7: תכנון וביצוע](/docs/practical-techniques/lesson-7-planning-execution#require-evidence-to-force-grounding)** ← דרישות ראיות, טכניקות גראונדינג +- **[שיעור 8: בדיקות כמעקות בטיחות](/docs/practical-techniques/lesson-8-tests-as-guardrails#the-three-context-workflow)** ← ולידציה בקונטקסט טרי, מניעת confirmation bias דרך תהליך עבודה של שלושה קונטקסטים +- **[שיעור 9: סקירת קוד](/docs/practical-techniques/lesson-9-reviewing-code#mechanisms-at-work)** ← מחזורי סקירה איטרטיביים, diminishing returns, בסיסי קוד מעורבים מול קוד בסיוע סוכן בלבד diff --git a/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/debugging/evidence-based-debug.md b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/debugging/evidence-based-debug.md new file mode 100644 index 0000000..9531951 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/debugging/evidence-based-debug.md @@ -0,0 +1,23 @@ +--- +title: דיבוג מבוסס-ראיות +sidebar_position: 1 +--- + +import EvidenceBasedDebug from '@site/shared-prompts/\_evidence-based-debug.mdx'; + + + +### סקירה כללית + +**למה דרישות ראיות מונעות הזיות (hallucinations):** "ספק ראיות (נתיבי קבצים, מספרי שורות, ערכים בפועל)" היא [הנחיית גראונדינג (grounding)](/docs/methodology/lesson-5-grounding#grounding-anchoring-agents-in-reality) מפורשת—סוכנים לא יכולים לספק את הראיות האלה בלי לשלוף אותן מבסיס הקוד. בלי דרישות ראיות, סוכנים מייצרים השלמת דפוסים מנתוני אימון ("כנראה timeout של מסד נתונים"), ולא ניתוח אמיתי. ראיות מכריחות קריאת קוד, מעקב ביצוע, וציטוטים קונקרטיים. הצעדים הממוספרים INVESTIGATE/ANALYZE/EXPLAIN מיישמים [Chain-of-Thought](/docs/methodology/lesson-4-prompting-101#chain-of-thought-paving-a-clear-path), ומכריחים ניתוח רציף (אי אפשר לקפוץ ישר ל"שורש הבעיה" בלי לבחון קודם את הקונטקסט של השגיאה). "Use the code research" היא הנחיית אחזור מפורשת—שמונעת הסתמכות על דפוסי אימון. בלוק קוד מגודר משמר את פורמט השגיאות ומונע מה-LLM לפרש הודעות כישלון כהוראות. ראיות טובות כוללות נתיבי קבצים עם מספרי שורות, ערכים בפועל של משתנים וקונפיגורציה, שמות פונקציות ספציפיים, ו-stack traces מלאים—לא טענות מעורפלות. + +**מתי להשתמש—דרישת קונטקסט טרי (fresh context):** שגיאות פרודקשן עם stack traces/logs, התנהגות לא צפויה בתרחישים ספציפיים, כשלים שקטים שדורשים מעקב אחרי נתיב הקוד, צווארי בקבוק בביצועים שדורשים ניתוח profiling, בעיות ארכיטקטוניות שמשתרעות על מספר קבצים. קריטי: השתמשו בשיחה נפרדת מהמימוש כדי לקבל ניתוח לא מוטה. הדפוס הזה מונע "מעגל של הונאה עצמית" שבו סוכנים מגנים על המימוש שלהם. הרצה ב[קונטקסט טרי](/docs/fundamentals/lesson-2-how-agents-work#the-stateless-advantage) נותנת ניתוח אובייקטיבי בלי הנחות קודמות. תמיד ספקו פלט שגיאה מלא—logs חתוכים מונעים אבחון מדויק. תאתגרו את ההסברים של הסוכן כשהם לא מסתדרים עם ההתנהגות בפועל: "אמרת ש-X גורם ל-timeout, אבל ה-logs מראים שהחיבור הוקם. תסביר את הפער הזה עם ראיות." דחו ניחושים בלי ציטוטים: "תראה לי את הקובץ ומספר השורה שבהם זה קורה." + +**דרישות קדם:** [יכולות מחקר קוד](https://chunkhound.github.io/) (חקירה עמוקה של בסיס הקוד דרך חיפוש סמנטי multi-hop, הרחבת שאילתות ומעקבים איטרטיביים), גישה למערכת קבצים לקריאת מימוש וקונפיגורציה, הודעות שגיאה/stack traces/logs מלאים (לא פלט חתוך), אופציונלי: נתיבי קבצים או שמות פונקציות אם ידועים. תוודאו את כל נתיבי הקבצים ומספרי השורות שצוטטו—סוכנים יכולים להמציא מיקומים. השתמשו בשיקול דעת הנדסי לאימות ההיגיון—LLMs משלימים דפוסים, לא לוגיקה. [התאימו את הדפוס לאבחונים אחרים](/docs/practical-techniques/lesson-10-debugging#the-closed-loop-debugging-workflow): בעיות ביצועים (מדדים/thresholds/נתוני profiling), פגיעויות אבטחה (וקטורי תקיפה/גבולות/פערי קונפיגורציה), כשלי deployment (logs של תשתית/מצב צפוי מול בפועל), בעיות אינטגרציה (חוזי API/זרימת נתונים/שגיאות גבולות). + +### שיעורים קשורים + +- **[שיעור 4: Prompting 101](/docs/methodology/lesson-4-prompting-101#chain-of-thought-paving-a-clear-path)** ← Chain-of-Thought, אילוצים, חשיבה מובנית +- **[שיעור 5: גראונדינג (Grounding)](/docs/methodology/lesson-5-grounding#grounding-anchoring-agents-in-reality)** ← הנחיות גראונדינג, RAG, כפיית אחזור +- **[שיעור 7: תכנון וביצוע](/docs/practical-techniques/lesson-7-planning-execution#require-evidence-to-force-grounding)** ← דרישות ראיות, אתגור הלוגיקה של הסוכן +- **[שיעור 10: דיבוג](/docs/practical-techniques/lesson-10-debugging#the-closed-loop-debugging-workflow)** ← תהליך עבודה closed-loop, סקריפטי reproduction, גישה מבוססת-ראיות diff --git a/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/index.md b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/index.md new file mode 100644 index 0000000..a635a77 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/index.md @@ -0,0 +1,30 @@ +--- +title: ספריית פרומפטים +sidebar_position: 0 +--- + +# ספריית פרומפטים + +תבניות פרומפט מוכנות לפרודקשן לתהליכי עבודה נפוצים של SDLC. + +## מדריך מהיר + +| שלב SDLC | פרומפט | מתי להשתמש | +| ------------------ | ---------------------------------------------------------------------- | ------------------------------------------------ | +| **Onboarding** | [צור AGENTS.md](/prompts/onboarding/generate-agents-md) | יצירת קבצי קונטקסט לפרויקט באופן אוטומטי | +| **Specifications** | [צור System Spec](/prompts/specifications/generate-spec) | לפני שינוי מערכות מורכבות או תכנון פיצ'רים | +| **Specifications** | [תבנית Spec](/prompts/specifications/spec-template) | כתיבת specs מאפס לפיצ'רים חדשים או design docs | +| **Planning** | [גילוי Edge Cases](/prompts/testing/edge-case-discovery) | לפני יישום פיצ'רים או כתיבת בדיקות | +| **Implementation** | [Debug מבוסס-ראיות](/prompts/debugging/evidence-based-debug) | כשמדבגים בעיות או התנהגות לא צפויה | +| **Testing** | [אבחון כישלון בדיקות](/prompts/testing/test-failure-diagnosis) | כשבדיקות נכשלות במהלך פיתוח או CI/CD | +| **Review** | [סקירת קוד מקיפה](/prompts/code-review/comprehensive-review) | לפני commit לשינויים או הגשת PRs | +| **Pull Requests** | [מחולל תיאור PR](/prompts/pull-requests/dual-optimized-pr) | כשיוצרים pull requests לסקירה | +| **Pull Requests** | [סקירת PR בסיוע AI](/prompts/pull-requests/ai-assisted-review) | כשסוקרים pull requests שהוגשו על ידי אחרים | + +## שימוש + +התאימו placeholders ודוגמאות domain-specific לקונטקסט שלכם. וודאו את הפלט של הסוכן באמצעות ראיות. + +## תרומה + +הפרומפטים האלה מתפתחים על בסיס שימוש אמיתי. נשמח לקבל תרומות לשיפורים או התאמות domain-specific. diff --git a/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/onboarding/generate-agents-md.md b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/onboarding/generate-agents-md.md new file mode 100644 index 0000000..4bdbaa3 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/onboarding/generate-agents-md.md @@ -0,0 +1,23 @@ +--- +title: צור AGENTS.md +sidebar_position: 1 +--- + +import GenerateAgentsMD from '@site/shared-prompts/\_generate-agents-md.mdx'; + + + +### סקירה כללית + +**למה גראונדינג (grounding) מרובה-מקורות עובד:** [ChunkHound](/docs/methodology/lesson-5-grounding#code-grounding-choosing-tools-by-scale) מספק קונטקסט ספציפי לקוד-בייס (פטרנים, קונבנציות, ארכיטקטורה) בעוד [ArguSeek](/docs/methodology/lesson-5-grounding#arguseek-isolated-context--state) מספק ידע אקוסיסטם עדכני (best practices של פריימוורק, הנחיות אבטחה)—זה מיישם [גראונדינג מרובה-מקורות](/docs/methodology/lesson-5-grounding#production-pattern-multi-source-grounding) כדי לשלב מציאות פרויקט אמפירית עם best practices של אקוסיסטם. [פורמט אאוטפוט מובנה](/docs/methodology/lesson-4-prompting-101#applying-structure-to-prompts) עם סעיפים מפורשים מבטיח כיסוי מקיף על ידי כפיית מעבר שיטתי על כל הסעיפים במקום טקסט חופשי. [אילוץ תמציתיות](/docs/methodology/lesson-4-prompting-101#constraints-as-guardrails) של ≤200 שורות מכריח תעדוף—בלעדיו, סוכנים מייצרים תיעוד מנופח שבסוף מתעלמים ממנו. הנחיית אי-כפילות שומרת פוקוס על פרטים תפעוליים ספציפיים ל-AI שסוכנים לא יכולים להסיק בקלות מהקוד לבד (הגדרת סביבה, התאמות לפקודות שרצות ללא אינטראקציה, gotchas של דיפלוימנט). זה מיישם את [שלב הריסרץ׳](/docs/methodology/lesson-3-high-level-methodology#phase-1-research-grounding) של [הוורקפלואו בארבעה שלבים](/docs/methodology/lesson-3-high-level-methodology#the-four-phase-workflow), ומאפשר לסוכנים לבנות בסיס משלהם לפני שמתחילים במשימות מימוש. + +**מתי להשתמש בפטרן הזה:** אונבורדינג לפרויקט חדש (בנו קונטקסט בסיסי לפני משימת האימפלמנטציה הראשונה), תיעוד פרויקטי legacy (תיעוד שיטתי של ידע שבטי - tribal knowledge), רענון קונטקסט אחרי שינויים ארכיטקטוניים (הריצו מחדש אחרי מיגרציות, שדרוגי פריימוורק, או ריפקטורים גדולים). הריצו מוקדם בתחילת עבודה עם פרויקט כדי לבסס [קבצי קונטקסט](/docs/practical-techniques/lesson-6-project-onboarding#the-context-file-ecosystem) בסיסיים, הריצו מחדש אחרי שינויים משמעותיים, ואז הוסיפו ידנית ידע שבטי (תקריות פרודקשן, קונבנציות צוות, gotchas לא-ברורים) ש-AI לא מסוגל לגלות מהקוד. בלי גראונדינג של קונטקסט התחלתי, סוכנים מהזים (hallucinate) קונבנציות על בסיס פטרנים מהטריינינג במקום לקרוא את הקוד-בייס האמיתי שלכם—זה מתבטא בהפרות סגנון, הנחות שגויות על ארכיטקטורה, והתעלמות מאילוצים ספציפיים לפרויקט. + +**דרישות קדם:** [ריסרץ׳ קוד ChunkHound](https://chunkhound.github.io/) (חקירה עמוקה של קוד-בייס דרך חיפוש סמנטי multi-hop, הרחבת queries ומעקבים איטרטיביים), [ריסרץ׳ ווב ArguSeek](https://github.com/ArguSeek/arguseek) (תיעוד אקוסיסטם ו-best practices עדכניים), הרשאות כתיבה ל-root של הפרויקט. נדרש קוד-בייס קיים עם קבצי מקור ו-README או תיעוד בסיסי כדי להימנע מכפילויות. אחרי יצירה, [ולדטו על ידי בדיקה עם משימה טיפוסית](/docs/methodology/lesson-3-high-level-methodology#phase-4-validate-the-iteration-decision)—אם הסוכן לא עוקב אחרי קונבנציות מתועדות, קובץ הקונטקסט צריך איטרציה נוספת. בלי ולידציה, אתם מסתכנים בהטמעת הנחות שגויות בקונטקסט הפרויקט שיצטברו ויחמירו במשימות עתידיות. + +### שיעורים קשורים + +- **[שיעור 3: מתודולוגיה ברמה גבוהה](/docs/methodology/lesson-3-high-level-methodology#the-four-phase-workflow)** ← וורקפלואו בארבעה שלבים (Research > Plan > Execute > Validate), החלטות איטרציה +- **[שיעור 4: Prompting 101](/docs/methodology/lesson-4-prompting-101#applying-structure-to-prompts)** ← Prompting מובנה, אילוצים כגארדריילס, צפיפות מידע +- **[שיעור 5: גראונדינג](/docs/methodology/lesson-5-grounding#production-pattern-multi-source-grounding)** ← גראונדינג מרובה-מקורות (ChunkHound + ArguSeek), חיפוש סמנטי, תת-סוכנים +- **[שיעור 6: אונבורדינג לפרויקט](/docs/practical-techniques/lesson-6-project-onboarding#the-context-file-ecosystem)** ← קבצי קונטקסט (AGENTS.md, CLAUDE.md), קונטקסט היררכי, ידע שבטי (tribal knowledge) diff --git a/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/pull-requests/ai-assisted-review.md b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/pull-requests/ai-assisted-review.md new file mode 100644 index 0000000..ca86e86 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/pull-requests/ai-assisted-review.md @@ -0,0 +1,24 @@ +--- +title: סקירת PR בסיוע AI +sidebar_position: 2 +--- + +import AIAssistedReview from '@site/shared-prompts/\_ai-assisted-review.mdx'; + + + +### סקירה כללית + +**למה תהליך עבודה דו-שלבי עם אימות אנושי:** שלב 1 מייצר ניתוח מובנה באמצעות חשיבת [Chain of Draft (CoD)](/docs/practical-techniques/lesson-9-reviewing-code#mechanisms-at-work)—עד 5 מילים לכל צעד חשיבה, מפחית צריכת טוקנים ב-60-80% תוך שמירה על איכות ההיסק. אינטגרציית GitHub CLI (`gh pr view --comments`) מספקת [גראונדינג (Grounding) ממקורות מרובים](/docs/methodology/lesson-5-grounding#grounding-anchoring-agents-in-reality) מעבר ל-code diff: metadata של PR, threads של דיון, issues מקושרים, כוונת המחבר. [הנחיית persona](/docs/methodology/lesson-4-prompting-101#assigning-personas) ("maintainer") מטה לכיוון ניתוח ביקורתי במקום אישור גנרי. דרישת ראיות ("never speculate...investigate files") מכריחה מחקר קוד לפני טענות, ומונעת הזיות (hallucinations). **בין השלבים, אתם מאמתים ממצאים**—LLMs יכולים להיות בטוחים בטעות לגבי הפרות ארכיטקטוניות. בדקו הפניות file:line, הטילו ספק בביקורות מעורפלות. שלב 2 הופך ניתוח מאומת לפלט לשני קהלים: HUMAN_REVIEW.md (תמציתי, אקשנבילי) ו-AGENT_REVIEW.md (קונטקסט טכני יעיל). זה משקף את דפוס [מחולל תיאור PR](/prompts/pull-requests/dual-optimized-pr)—המשך של אותו קונטקסט, לא ניתוח מאפס. + +**מתי להשתמש—מקרי שימוש עיקריים:** סקירת PR שיטתית לשינויים ארכיטקטוניים שנוגעים במודולי ליבה, הצגת patterns חדשים, או refactoring משמעותי. הכי יעיל עם תיאור מותאם-AI מ-[מחולל תיאור PR](/prompts/pull-requests/dual-optimized-pr) (נתיבי קבצים מפורשים, גבולות מודולים, breaking changes). מומלץ לשימוש pre-merge כאימות סופי ב[שלב Validate](/docs/methodology/lesson-3-high-level-methodology#the-four-phase-workflow), לא במהלך פיתוח פעיל (השתמשו ב[סקירה מקיפה](/prompts/code-review/comprehensive-review) לשינויי worktree). קבצי הפלט הכפול מאפשרים: HUMAN_REVIEW.md לדיון maintainer (1-3 פסקאות, שבחים + מיקוד אקשנבילי), AGENT_REVIEW.md לכלי AI ב-downstream שעשויים לעבד את הסקירה. פחות יעיל ל-PRs טריוויאליים (תיעוד בלבד, עדכוני dependencies, תיקוני באגים פשוטים) שבהם ה-overhead של הסקירה עולה על התועלת. + +**דרישות קדם:** [GitHub CLI](https://cli.github.com/) (`gh`) מותקן ומאומת (`gh auth status`), [ChunkHound](https://chunkhound.github.io/) לחיפוש סמנטי בקודבייס, [ArguSeek](https://github.com/ofrivera/ArguSeek) ללימוד דפוסי אופטימיזציה לאדם/LLM בשלב 2. דורש קישור PR (URL או מספר), תיאור מותאם-AI מתהליך העבודה של [מחולל תיאור PR](/prompts/pull-requests/dual-optimized-pr). פלטים: שלב 1 מייצר verdict מובנה (Summary/Strengths/Issues/Decision), שלב 2 מייצר קבצי HUMAN_REVIEW.md ו-AGENT_REVIEW.md. [התאימו Critical Checks למיקוד מתמחה](/docs/practical-techniques/lesson-9-reviewing-code#mechanisms-at-work): אבטחה (input validation, בדיקות auth, טיפול ב-credentials, וקטורי injection), ביצועים (complexity, שאילתות N+1, memory patterns, caching), נגישות (HTML סמנטי, ניווט מקלדת, ARIA, contrast). + +### שיעורים קשורים + +- **[שיעור 3: מתודולוגיה ברמה גבוהה](/docs/methodology/lesson-3-high-level-methodology#the-four-phase-workflow)** ← תהליך עבודה בארבעה שלבים (Research > Plan > Execute > Validate)—סקירת PR היא שלב Validate +- **[שיעור 4: Prompting 101](/docs/methodology/lesson-4-prompting-101#assigning-personas)** ← [הנחיות Persona](/docs/methodology/lesson-4-prompting-101#assigning-personas), [Chain-of-Thought](/docs/methodology/lesson-4-prompting-101#chain-of-thought-paving-a-clear-path), [אילוצים](/docs/methodology/lesson-4-prompting-101#constraints-as-guardrails), פלט מובנה +- **[שיעור 5: גראונדינג (Grounding)](/docs/methodology/lesson-5-grounding#grounding-anchoring-agents-in-reality)** ← גראונדינג מרובה-מקורות (GitHub CLI + מחקר קוד + תיאורים מותאמים-ל-AI), הנחיות גראונדינג מפורשות +- **[שיעור 7: תכנון וביצוע](/docs/practical-techniques/lesson-7-planning-execution#require-evidence-to-force-grounding)** ← דרישות ראיות מכריחות ציטוטי file:line, מאתגרות טענות מעורפלות +- **[שיעור 9: סקירת קוד](/docs/practical-techniques/lesson-9-reviewing-code#mechanisms-at-work)** ← יעילות Chain of Draft (CoD), וורקפלואו של dual-optimized PR, התאמות סקירה מתמחות diff --git a/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/pull-requests/dual-optimized-pr.md b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/pull-requests/dual-optimized-pr.md new file mode 100644 index 0000000..d000d32 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/pull-requests/dual-optimized-pr.md @@ -0,0 +1,28 @@ +--- +title: מחולל תיאור PR +sidebar_position: 1 +--- + +import DualOptimizedPR from '@site/shared-prompts/\_dual-optimized-pr.mdx'; + + + +### סקירה כללית + +**למה אופטימיזציה לשני קהלים עובדת:** [תת-סוכנים](/docs/fundamentals/lesson-2-how-agents-work#the-stateless-advantage) משמרים קונטקסט על ידי הפעלת סוכנים נפרדים לחקירת היסטוריית git—ללא האצלה זו, 20-30 שינויי קבצים צורכים 40K+ טוקנים, דוחפים אילוצים קריטיים לתוך [האמצע שמתעלמים ממנו בעקומת ה-attention](/docs/methodology/lesson-5-grounding#the-scale-problem-context-window-limits). [גראונדינג (grounding) מרובה-מקורות](/docs/methodology/lesson-5-grounding#production-pattern-multi-source-grounding) משלב ArguSeek (best practices של PR מתיעוד GitHub ובלוגי הנדסה) עם ChunkHound (דפוסי ארכיטקטורה ספציפיים לפרויקט, אחריויות מודולים), ומונע עצות גנריות מנותקות מהמציאות של בסיס הקוד שלכם. מסגור [פרסונה (persona)](/docs/methodology/lesson-4-prompting-101#assigning-personas) של "עמית לעבודה" עם [אילוצי](/docs/methodology/lesson-4-prompting-101#constraints-as-guardrails) סגנון מפורשים (ישיר, תמציתי, הנח שהקורא מבין, דלג על המובן מאליו) מונע הסברים מיותרים שמבזבזים את תשומת הלב של הסוקרים. אילוצים כפולים מאזנים בין הקהלים: "1-3 פסקאות מקסימום" לאנשים מונע הצפת maintainers בקירות של טקסט, בעוד "הסבר ביעילות" שומר על קונטקסט AI מקיף אך מובנה—קריטי כי [סוקרי AI](/prompts/pull-requests/ai-assisted-review) צריכים קונטקסט ארכיטקטוני (יחסי קבצים, גבולות מודולים) שאנשים מסיקים מניסיון. + +**מתי להשתמש—אינטגרציה בתהליך עבודה:** לפני הגשת PRs עם changesets מורכבים (10+ קבצים, מודולים מרובים שהשתנו, cross-cutting concerns) או שיתוף פעולה בין-צוותי שבו לסוקרים אין היכרות עמוקה עם המודול. שלבו ב[תהליך עבודה בארבעה שלבים](/docs/methodology/lesson-3-high-level-methodology#the-four-phase-workflow): השלימו מימוש → אמתו עם טסטים → self-review לבעיות → תקנו בעיות שהתגלו → צרו תיאורים כפולים → הגישו PR עם שני הקבצים. היו ספציפיים עם `$CHANGES_DESC`—תיאורים מעורפלים ("תקן באגים", "עדכן לוגיקה") מייצרים פלט גנרי כי [גראונדינג](/docs/methodology/lesson-5-grounding#grounding-anchoring-agents-in-reality) דורש כוונה קונקרטית. ללא תיאור שינויים ספציפי, לסוכן אין עוגן להעריך "מה חשוב" ב-git diff. קריטי: אם אתם עורכים ידנית תיאורים שנוצרו, צרו מחדש את שני הקבצים—קונטקסט מיושן בתיאור המותאם ל-AI גורם [להזיות (hallucinations) במהלך סקירה](/docs/practical-techniques/lesson-9-reviewing-code) כשהסברים ארכיטקטוניים סותרים את השינויים בפועל. לצוותים שעדיין לא משתמשים בסוקרי AI, הפלט המותאם לאנשים לבדו מספק סיכומים תמציתיים שמכבדים את זמן הסוקר. + +**דרישות קדם:** [כלי תת-סוכן/משימה](/docs/methodology/lesson-5-grounding#solution-2-sub-agents-for-context-isolation) ([Claude Code CLI](/developer-tools/cli-coding-agents#claude-code) מספק כלי Task מובנה—פלטפורמות אחרות דורשות ניהול קונטקסט ידני דרך פרומפטים רצופים), [ArguSeek](https://github.com/ofrivera/ArguSeek) (מחקר רשת ל-best practices של PR), [ChunkHound](https://chunkhound.github.io/) (מחקר בסיס קוד דרך חיפוש סמנטי multi-hop וחקירה איטרטיבית), גישה להיסטוריית git עם שינויים ב-commit על feature branch. דורש base branch להשוואה (בדרך כלל `main` או `develop`), תיעוד ארכיטקטורה ([קונטקסט פרויקט CLAUDE.md](/docs/practical-techniques/lesson-6-project-onboarding#the-context-file-ecosystem), AGENTS.md לתהליכי עבודה אגנטיים). הסוכן מייצר שני קבצי markdown: **מותאם לאנשים** (1-3 פסקאות המכסות מה השתנה, למה זה חשוב, breaking changes אם יש, והערך שנמסר) ו**מותאם ל-AI** (נתיבי קבצים עם מספרי שורות, אחריויות מודולים, דפוסי ארכיטקטורה שיושמו, שינויי גבולות, כיסוי טסטים, edge cases שטופלו). [התאימו דפוס זה](/docs/practical-techniques/lesson-7-planning-execution) לצרכי תיעוד אחרים: release notes (פיצ'רים מוכווני-משתמש מול changelog טכני), postmortems של תקריות (סיכום מנהלי מול ניתוח root cause טכני), design docs (סקירה ל-stakeholders מול deep-dive של מימוש). + +**לסקירה בפועל**, השתמשו בפרומפטים אלה עם התוצרים שנוצרו: + +- **[סקירת PR בסיוע AI](/prompts/pull-requests/ai-assisted-review)** ← סקרו PRs באמצעות התיאור מותאם-ל-AI עם אינטגרציית GitHub CLI +- **[סקירת קוד מקיפה](/prompts/code-review/comprehensive-review)** ← סקרו שינויי worktree לפני commit (שלב pre-PR) + +### שיעורים קשורים + +- **[שיעור 2: הסרת המסתורין מסוכנים](/docs/fundamentals/lesson-2-how-agents-work#the-stateless-advantage)** ← תת-סוכנים, האצלת משימות, שימור קונטקסט +- **[שיעור 4: Prompting 101](/docs/methodology/lesson-4-prompting-101#assigning-personas)** ← Persona, אילוצים, עקומות attention +- **[שיעור 5: גראונדינג (Grounding)](/docs/methodology/lesson-5-grounding#production-pattern-multi-source-grounding)** ← גראונדינג מרובה-מקורות, מניעת הזיות +- **[שיעור 9: סקירת קוד](/docs/practical-techniques/lesson-9-reviewing-code)** ← אופטימיזציה לשני קהלים, תהליכי עבודה של PR, סקירה בסיוע AI diff --git a/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/specifications/generate-spec.md b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/specifications/generate-spec.md new file mode 100644 index 0000000..b2000b1 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/specifications/generate-spec.md @@ -0,0 +1,22 @@ +--- +title: יצירת מפרט מערכת (System Specification) +sidebar_position: 1 +--- + +import GenerateSpec from '@site/shared-prompts/_generate-spec.mdx'; + + + +### סקירה כללית + +**למה חילוץ שיטתי עובד:** כלי מחקר קוד ([ChunkHound](/docs/methodology/lesson-5-grounding#code-grounding-choosing-tools-by-scale)) מחלצים ידע ארכיטקטוני מקוד מקור באופן דינמי. תבנית ה-spec מתרגמת מידע גולמי זה לחשיבה מובנית—מודולים, גבולות, contracts, state, כשלים—שחושפת אילוצים לפני תחילת המימוש. זה מיישם [גראונדינג (Grounding) מרובה-מקורות](/docs/methodology/lesson-5-grounding#production-pattern-multi-source-grounding) להבנה ארכיטקטונית: מחקר קוד מספק את העובדות, והתבנית מספקת את המבנה לחשיבה עליהן. + +**מתי להשתמש בדפוס הזה:** שינויים ב-brownfield (תבינו לפני שתשנו), חקירה ארכיטקטונית (איך המערכת הזו עובדת?), תכנון מקדים (pre-planning) לפיצ'רים מורכבים (פרקו לפני prompting), onboarding לקודבייסים לא מוכרים (חלצו את המודל המנטלי). הכי שימושי כששינויים משתרעים על מספר מודולים או נוגעים בקוד לא מוכר. דלגו על תיקוני באגים מבודדים—שם חלון הקונטקסט משמש כ-spec מספיק. + +**דרישות מקדימות:** [מחקר קוד ChunkHound](https://chunkhound.github.io/) לחקירת קודבייס, וקוד קיים לניתוח. למערכות חדשות (greenfield), השתמשו בתבנית ישירות ככלי דיזיין במקום יעד לחילוץ. לאחר החילוץ, וודאו טענות עם ראיות file:line—סוכנים נוטים להזות (hallucinate) מבנים שלא קיימים. מחקו specs לאחר המימוש; הקוד הופך למקור האמת ([שיעור 12](/docs/practical-techniques/lesson-12-spec-driven-development)). + +### שיעורים קשורים + +- **[שיעור 5: גראונדינג (Grounding)](/docs/methodology/lesson-5-grounding)** ← כלי מחקר קוד, חיפוש סמנטי, דרישות ראיות +- **[שיעור 12: פיתוח מונחה-Spec](/docs/practical-techniques/lesson-12-spec-driven-development)** ← מחזור החיים של Spec, קוד כמקור אמת, מחיקה לאחר המימוש +- **[שיעור 13: חשיבת מערכות ל-Specs](/docs/practical-techniques/lesson-13-systems-thinking-specs)** ← שימוש בתבנית כשלד חשיבה, התאמת פורמליות למורכבות diff --git a/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/specifications/spec-template.md b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/specifications/spec-template.md new file mode 100644 index 0000000..2717a0d --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/specifications/spec-template.md @@ -0,0 +1,32 @@ +--- +title: תבנית System Specification +sidebar_position: 2 +--- + +import SpecTemplate from '@site/shared-prompts/_spec-template.mdx'; + +## תבנית System Specification + +תבנית מובנית לכתיבת specifications למערכות מאפס. השתמשו בה כשמעצבים פיצ'רים חדשים, מתכננים שינויים ארכיטקטוניים, או מתעדים מערכות קיימות לצורך שינוי. + +ל**חילוץ** specs מבסיס קוד קיים אוטומטית, השתמשו +בפרומט [צור System Spec](/prompts/specifications/generate-spec) במקום. + +### התבנית + + + +### איך להשתמש + +1. התחילו עם Architecture + Interfaces + State, ואז הוסיפו סעיפים כשהקוד דורש אותם + (ראו [Converge, Don't Count Passes](/docs/practical-techniques/lesson-13-systems-thinking-specs#converge-dont-count-passes)) +2. מלאו עם הספציפיקה של הדומיין שלכם — דלגו על סעיפים שלא רלוונטיים +3. השתמשו כקונטקסט לסוכן שמממש את הקוד, או כ-design document לסקירת צוות +4. מחקו לאחר המימוש — קוד הוא מקור האמת + ([שיעור 12](/docs/practical-techniques/lesson-12-spec-driven-development)) + +### ראו גם + +- [שיעור 13: חשיבה במערכות](/docs/practical-techniques/lesson-13-systems-thinking-specs) ← מסביר את ההגיון מאחורי כל סעיף +- [שיעור 12: Spec-Driven Development](/docs/practical-techniques/lesson-12-spec-driven-development) ← מחזור החיים של spec +- [צור System Spec](/prompts/specifications/generate-spec) ← חילוץ אוטומטי של specs מקוד diff --git a/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/testing/edge-case-discovery.md b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/testing/edge-case-discovery.md new file mode 100644 index 0000000..ac5ce04 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/testing/edge-case-discovery.md @@ -0,0 +1,23 @@ +--- +title: גילוי מקרי קצה +sidebar_position: 2 +--- + +import EdgeCaseDiscovery from '@site/shared-prompts/\_edge-case-discovery.mdx'; + + + +### סקירה כללית (Overview) + +**למה דפוס דו-שלבי מונע עצות גנריות:** שלב 1 טוען אילוצים קונקרטיים—הסוכן מחפש פונקציה, קורא את המימוש, מוצא בדיקות קיימות. זה מאכלס את הקונטקסט עם מקרי קצה אמיתיים מבסיס הקוד שלכם ("משתמשי OAuth מדלגים על אימות email," "משתמשי admin עוקפים rate limits"). שלב 2 מזהה פערים—עם המימוש בקונטקסט, הסוכן מנתח מה לא נבדק במקום לרשום קטגוריות בדיקה גנריות. [הנחיות גראונדינג (grounding)](/docs/methodology/lesson-5-grounding#grounding-anchoring-agents-in-reality) מכריחות חיפוש בבסיס הקוד לפני הצעת בדיקות. בדיקות קיימות חושפות דפוסי כיסוי ומקרי קצה ספציפיים לדומיין. פרטי המימוש חושפים מצבי כשל אמיתיים, לא היפותטיים. מונע [specification gaming](/docs/practical-techniques/lesson-8-tests-as-guardrails#the-three-context-workflow) על ידי גילוי מקרי קצה בנפרד מהמימוש—דומה ל[דרישת קונטקסט טרי](/docs/fundamentals/lesson-2-how-agents-work#the-stateless-advantage) לניתוח אובייקטיבי. + +**מתי להשתמש—גישת research-first:** לפני יישום פיצ'רים חדשים (גלו דפוסים קיימים), פיתוח TDD (זהו מקרי קצה לפני המימוש), הגדלת כיסוי (מצאו פערים ב-test suites קיימים), שכתוב קוד legacy (הבינו טיפול מקרי קצה מרומז), code review (וודאו ש-PRs כוללים בדיקות רלוונטיות). קריטי: אל תדלגו על שלב 1—לשאול ישירות "אילו מקרי קצה צריך לבדוק?" מייצר עצות גנריות ללא גראונדינג בבסיס הקוד. היו ספציפיים בשלב 2 עם קטגוריות רלוונטיות לדומיין (ראו דוגמאות בפרומפט). אם אתם מייצרים מקרי קצה ומימוש באותה שיחה, הבדיקות יתאימו להנחות המימוש—השתמשו בדפוס זה ב[קונטקסט טרי](/docs/fundamentals/lesson-2-how-agents-work#the-stateless-advantage) או לפני המימוש. ללא [גראונדינג](/docs/methodology/lesson-5-grounding#grounding-anchoring-agents-in-reality), סוכנים מייצרים הזיות (hallucinations) על בסיס דפוסי אימון במקום לנתח את הקוד האמיתי שלכם. + +**דרישות מוקדמות (Prerequisites):** [יכולות מחקר קוד](https://chunkhound.github.io/) (חקירה עמוקה של בסיס הקוד דרך חיפוש סמנטי multi-hop, הרחבת queries ומעקבים איטרטיביים), גישה לקבצי המימוש ו-test suites קיימים, שם פונקציה/מודול לניתוח. לאחר שלב 1, הסוכן מספק סיכום מימוש עם נתיבי קבצים, מקרי קצה שנבדקים כרגע עם ראיות מקבצי בדיקה, לוגיקת טיפול מיוחדת וענפים מותנים (conditional branches). לאחר שלב 2, הסוכן מזהה נתיבי קוד לא נבדקים עם מספרי שורות, כיסוי מקרי קצה חסר עם דוגמאות קונקרטיות מהדומיין שלכם, מצבי כשל פוטנציאליים על בסיס ניתוח המימוש. + +### שיעורים קשורים (Related Lessons) + +- **[שיעור 4: Prompting 101](/docs/methodology/lesson-4-prompting-101#chain-of-thought-paving-a-clear-path)** ← Chain-of-Thought, פרומפטים מובנים עם שלבים רצופים +- **[שיעור 5: גראונדינג (Grounding)](/docs/methodology/lesson-5-grounding#grounding-anchoring-agents-in-reality)** ← טעינת קונטקסט של בסיס הקוד לפני יצירה, מניעת הזיות (hallucinations) +- **[שיעור 7: תכנון וביצוע](/docs/practical-techniques/lesson-7-planning-execution#require-evidence-to-force-grounding)** ← גישת research-first, דרישות ראיות +- **[שיעור 8: בדיקות כגארדריילס (Guardrails)](/docs/practical-techniques/lesson-8-tests-as-guardrails#the-three-context-workflow)** ← three-context workflow, מניעת specification gaming diff --git a/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/testing/test-failure-diagnosis.md b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/testing/test-failure-diagnosis.md new file mode 100644 index 0000000..92ce668 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs-prompts/current/testing/test-failure-diagnosis.md @@ -0,0 +1,23 @@ +--- +title: אבחון כישלון בדיקות +sidebar_position: 1 +--- + +import TestFailureDiagnosis from '@site/shared-prompts/\_test-failure-diagnosis.mdx'; + + + +### סקירה כללית + +**למה אבחון שיטתי מונע הזיות (hallucinations):** בלוק קוד מגודר שומר על פורמט השגיאות ומונע מה-LLM לפרש הודעות כישלון כהוראות. "Use the code research" היא [הנחיית grounding](/docs/methodology/lesson-5-grounding#grounding-anchoring-agents-in-reality) מפורשת—מאלצת חיפוש בבסיס הקוד במקום להמציא מדפוסי אימון. השלבים הממוספרים של DIAGNOSE מיישמים [Chain-of-Thought](/docs/methodology/lesson-4-prompting-101#chain-of-thought-paving-a-clear-path), ומאלצים ניתוח שלב-אחר-שלב (אי אפשר לקפוץ ישר ל"שורש הבעיה" בלי לבחון קודם את מטרת הבדיקה). "Understand the intention" (שלב 2) מבטיח שהסוכן מנסח למה הבדיקה קיימת, לא רק מה היא עושה—קריטי להבחנה בין באגים לדרישות לא עדכניות. ההחלטה הבינארית של DETERMINE [מגבילה את הפלט](/docs/methodology/lesson-4-prompting-101#constraints-as-guardrails) ל"באג מול בדיקה לא עדכנית" במקום מסקנות פתוחות. "Provide evidence" דורש נתיבי קבצים ומספרי שורות—הוכחה קונקרטית, לא טענות מעורפלות. + +**מתי להשתמש—דרישה לקונטקסט טרי:** כשלונות בדיקות במהלך refactoring (לקבוע אם הבדיקות צריכות עדכון או שיש באגים בקוד), כשלונות ב-CI/CD pipeline (ניתוח שיטתי של שורש הבעיה), לאחר הוספת פיצ'רים חדשים (ניתוח כשלונות ב-suites קיימים). קריטי: השתמשו בשיחה נפרדת מהמימוש כדי לקבל ניתוח אובייקטיבי. הדפוס הזה מונע "מעגל של הטעיה עצמית" שבו הסוכן מגן על המימוש שלו. הרצה ב[קונטקסט טרי](/docs/fundamentals/lesson-2-how-agents-work#the-stateless-advantage) נותנת ניתוח אובייקטיבי בלי הנחות מוקדמות. הקפידו לכלול stack traces והודעות שגיאה מלאים—פלט חתוך מונע אבחון מדויק. בלי [הנחיית grounding](/docs/methodology/lesson-5-grounding#grounding-anchoring-agents-in-reality), סוכנים ממציאים מידע על סמך דפוסי האימון שלהם במקום לקרוא את בסיס הקוד האמיתי שלכם. + +**דרישות מקדימות:** [יכולות מחקר קוד](https://chunkhound.github.io/) (חקירה מעמיקה של בסיס הקוד באמצעות חיפוש סמנטי multi-hop, הרחבת שאילתות ומעקבים איטרטיביים), גישה לקבצי הבדיקה ולקוד המימוש, פלט של כשלונות בדיקות (stack traces, שגיאות assertion, logs), נתיבים לקבצים רלוונטיים. [ניתן להתאים את הדפוס לאבחונים אחרים](/docs/practical-techniques/lesson-10-debugging#the-closed-loop-debugging-workflow): בעיות ביצועים (מדדים/סַפים/צווארי בקבוק), פגיעויות אבטחה (וקטורי תקיפה/גבולות/פערים), כשלונות deployment (logs/זרימה צפויה/אי-התאמות בקונפיגורציה). + +### שיעורים קשורים + +- **[שיעור 3: מתודולוגיה ברמה גבוהה](/docs/methodology/lesson-3-high-level-methodology#the-four-phase-workflow)** ← תהליך עבודה בארבעה שלבים (Research > Plan > Execute > Validate) +- **[שיעור 4: מבוא ל-Prompting](/docs/methodology/lesson-4-prompting-101#chain-of-thought-paving-a-clear-path)** ← Chain-of-Thought, אילוצים (constraints), פורמט מובנה +- **[שיעור 7: תכנון וביצוע](/docs/practical-techniques/lesson-7-planning-execution#require-evidence-to-force-grounding)** ← דרישות לראיות, טכניקות grounding +- **[שיעור 8: בדיקות כגדרות בטיחות](/docs/practical-techniques/lesson-8-tests-as-guardrails#test-failure-diagnosis-agent-driven-debug-cycle)** ← תהליך עבודה עם שלושה קונטקסטים, אבחון כשלונות בדיקות diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current.json b/website/i18n/he/docusaurus-plugin-content-docs/current.json new file mode 100644 index 0000000..efa6e25 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current.json @@ -0,0 +1,18 @@ +{ + "version.label": { + "message": "הבא", + "description": "The label for version current" + }, + "sidebar.tutorialSidebar.category.Fundamentals": { + "message": "יסודות", + "description": "The label for category 'Fundamentals' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Methodology": { + "message": "מתודולוגיה", + "description": "The label for category 'Methodology' in sidebar 'tutorialSidebar'" + }, + "sidebar.tutorialSidebar.category.Practical Techniques": { + "message": "טכניקות מעשיות", + "description": "The label for category 'Practical Techniques' in sidebar 'tutorialSidebar'" + } +} diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/faq.md b/website/i18n/he/docusaurus-plugin-content-docs/current/faq.md new file mode 100644 index 0000000..f8d166e --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/faq.md @@ -0,0 +1,215 @@ +--- +slug: faq +title: 'שאלות נפוצות' +description: 'שאלות נפוצות על מתודולוגיית קידוד אגנטי, תהליכי עבודה של פיתוח אגנטי, והנחיית סוכני קידוד AI להנדסת תוכנה בסביבת פרודקשן.' +keywords: [agentic coding, agentic development, AI coding agents, vibe coding, vibe engineering, Claude Code, Copilot, prompt engineering, LLM programming] +--- + +import SchemaMarkup from '@site/src/components/SchemaMarkup'; + +export const faqData = { + questions: [ + { question: "מהו קידוד אגנטי?", answer: "קידוד אגנטי הוא פיתוח תוכנה באמצעות סוכני AI שיכולים לתפוס את בסיס הקוד שלכם, להסיק לגבי משימות, לבצע פעולות (לכתוב קוד, להריץ בדיקות, לבצע פקודות), ולחזור על התהליך בהתבסס על משוב. בניגוד לממשקי צ'אט מסורתיים, סוכנים פועלים באופן אוטונומי בתוך מעקות בטיחות שאתם מגדירים. הקורס הזה מלמד מתודולוגיה מובנית—מחקר, תכנון, ביצוע, אימות—שהופכת קידוד אגנטי לאמין עבור מערכות פרודקשן." }, + { question: "מהו פיתוח אגנטי?", answer: "פיתוח אגנטי מרחיב קידוד אגנטי על פני מחזור חיי פיתוח התוכנה המלא—מאיסוף דרישות ועד פריסה ותחזוקה. בעוד שקידוד אגנטי מתמקד בפעולת כתיבה ובדיקת קוד עם סוכני AI, פיתוח אגנטי מקיף את ה-pipeline הרחב יותר: תכנון מונחה-spec, בדיקות אוטומטיות, אינטגרציית CI/CD וניטור פרודקשן. בעוד שהמונחים האלה חופפים קונספטואלית, ספרות התעשייה בדרך כלל שומרת על הבחנת היקף." }, + { question: "למי מיועד הקורס הזה?", answer: "מהנדסי תוכנה בכירים עם 3+ שנות ניסיון פרודקשן שניסו עוזרי קידוד AI ונתקלו בנקודות תסכול. אתם צריכים יסודות חזקים בארכיטקטורה, design patterns ועיצוב מערכות כי קידוד אגנטי מעביר את העבודה שלכם למעלה בסטאק—אתם מקבלים החלטות ומאמתים תוצאות, לא כותבים כל שורה." }, + { question: "איך מתחילים עם קידוד אגנטי?", answer: "התחילו עם היסודות: הבינו איך LLMs עובדים (התאמת דפוסים סטטיסטית שמאפשרת הסקה), למדו את לולאת הסוכן (perceive-reason-act-observe-verify), ואז תרגלו את הוורקפלואו בארבעת השלבים על משימה אמיתית. התחילו במצב מפוקח עד שאתם סומכים על תהליך הגראונדינג והאימות שלכם." }, + { question: "מהו vibe coding?", answer: "Vibe coding, שנטבע על ידי Andrej Karpathy (פברואר 2025), מתאר פיתוח בסיוע AI שבו אתם 'נכנעים לחלוטין לאווירה' ומקבלים קוד שנוצר ללא סקירה. אתם מתארים מה שאתם רוצים, מדביקים הודעות שגיאה כשדברים נשברים, וחוזרים עד שזה עובד—ללא הבנת הקוד. זה יעיל לאבות-טיפוס זמניים אבל מייצר קוד לא ניתן לתחזוקה, פוטנציאלית לא מאובטח, לא מתאים לפרודקשן." }, + { question: "מה ההבדל בין קידוד אגנטי ל-vibe coding?", answer: "ההבדל הוא אחריותיות. Vibe coding פירושו קבלת פלט AI ללא הבנתו—אתם נוסעים. קידוד אגנטי פירושו הנחיית סוכני AI דרך תהליך עבודה מובנה תוך בעלות על כל החלטה. אתם מאמתים פלטים, מבינים מה נשלח, ומתחזקים את בסיס הקוד. שניהם משתמשים ב-AI ליצירת קוד, אבל קידוד אגנטי מתייחס לאדם כמהנדס האחראי, לא כנוסע." }, + { question: "מהו vibe engineering?", answer: "Vibe engineering, שנטבע על ידי Simon Willison (אוקטובר 2025), מתאר קידוד בסיוע AI שבו אתם סוקרים ומבינים לעומק קוד שנוצר לפני שליחה. זו גישה ממושמעת שמגבירה שיטות הנדסת תוכנה מבוססות: בדיקות אוטומטיות, תיעוד, סקירת קוד ואימות. קידוד אגנטי חולק את עקרון האחריותיות הזה אבל מוסיף מבנה מפורש: תהליך העבודה בארבעת השלבים (מחקר, תכנון, ביצוע, אימות) שהופכת פיתוח בסיוע AI לצפוי וחוזר." }, + { question: "אילו כלי קידוד AI תומכים בקידוד אגנטי?", answer: "הקורס הזה ממליץ על סוכני קידוד CLI—Claude Code, Aider, או Codex CLI—כי כלים מבוססי-טרמינל מאפשרים מקביליות: הרצת מופעי סוכן מרובים על פני tabs טרמינל שונים או git worktrees בו-זמנית. סוכני IDE (Cursor, Copilot) עובדים אבל צמודים לחלונות בודדים, מה שמגביל תהליכי עבודה במקביל. המתודולוגיה חלה באופן רחב, אבל סוכני CLI פותחים את מודל הביצוע המקבילי שהקורס הזה מלמד." }, + { question: "האם קידוד אגנטי טוב יותר מ-prompt engineering?", answer: "Prompt engineering ממטב פרומפטים בודדים. קידוד אגנטי הוא מתודולוגיה שלמה: מחקר, תכנון, ביצוע, אימות. אתם עדיין כותבים פרומפטים, אבל בתוך וורקפלואו מובנה שכולל עיגון של סוכנים בבסיס הקוד שלכם, סקירת תוכניות לפני ביצוע, ואימות פלט מול המודל המנטלי שלכם." }, + { question: "למה כלי כוח במקום מפתח ג'וניור?", answer: "כלי כוח לא 'מבין' מה אתם בונים—הוא מבצע בהתאם לאיך שאתם מפעילים אותו. אתם לא מתעצבנים כשמסור עגול חותך בזווית הלא נכונה; אתם מתאימים את ההגדרה והטכניקה שלכם. אותו דבר עם סוכני AI. אתם בעלי התוצאות, מאמתים דרך בדיקות, ומדבגים את הקלט שלכם כשהפלט נכשל." }, + { question: "מהו הוורקפלואו של קידוד אגנטי?", answer: "ארבעה שלבים: מחקר (עשו גראונדינג לסוכנים בדפוסי בסיס הקוד שלכם וידע דומיין חיצוני), תכנון (בחרו אסטרטגיית חקירה או תכנון מדויק, קבלו החלטות ארכיטקטוניות), ביצוע (האצילו לסוכנים במצב מפוקח או אוטונומי), אימות (החליטו לחזור או לייצר מחדש בהתאם להתאמה למודל המנטלי שלכם ובדיקות אוטומטיות). דילוג על כל שלב מעלה דרמטית את שיעור הכישלון." }, + { question: "למה חלק מהמפתחים מדווחים שהם איטיים יותר עם כלי AI?", answer: "מחקרים מראים שמפתחים מנוסים לעתים קרובות איטיים יותר במשימות בודדות עם AI—למרות שהם מאמינים שהם מהירים יותר. מהירות לכל משימה היא המדד הלא נכון. המתודולוגיה הזו מלמדת שהרווח האמיתי בפרודוקטיביות מגיע ממקביליות: הרצת סוכנים מרובים על משימות שונות בזמן שאתם משתתפים בפגישות, סוקרים PRים, או מטפלים בעבודה אחרת. מהנדס בכיר עם שלושה סוכנים מקביליים משחרר יותר מאחד שמשגיח על שיחה אחת." }, + { question: "למה סוכן ה-AI שלי ממציא קוד לא נכון?", answer: "סוכנים לא יודעים שבסיס הקוד שלכם קיים. ללא עיגון (grounding), הם מייצרים מדפוסי נתוני אימון שקפואים ב-knowledge cutoff שלהם. התיקון: הזריקו את דפוסי הקוד האמיתיים שלכם, אילוצים ארכיטקטוניים ותיעוד נוכחי לקונטקסט לפני שמבקשים יצירה. עיגון מפחית משמעותית הזיות על ידי עיגון יצירה בבסיס הקוד האמיתי שלכם." }, + { question: "למה סוכן ה-AI שלי שוכח קונטקסט באמצע משימה?", answer: "LLMs הם סטייטלס (stateless)—הם יודעים רק מה שבחלון הקונטקסט הנוכחי. כשהשיחות גדלות, קונטקסט ישן יותר נגלל החוצה. זה לא באג; זה יסודי לאיך מודלי transformer עובדים. התיקון: טענו קונטקסט במתכוון לפני כל שלב משימה. שאלו שאלות חקירתיות ('איך עובד X?') כדי להפעיל קריאות קבצים שמאכלסות את החלון. השתמשו בקבצי הוראות היררכיים (CLAUDE.md) כדי לשמר אילוצים ארכיטקטוניים. גראונדינג (grounding) הוא לא צעד חד-פעמי—זו הנדסת קונטקסט מתמשכת." }, + { question: "איך אני עוצר סוכני AI משכפול קוד?", answer: "סוכנים מגבירים דפוסים קיימים—הם לא ממציאים כפילות. אם בבסיס הקוד שלכם יש דפוסים לא עקביים, סוכנים משכפלים אותם. לפני בקשת מימושים חדשים, הראו קיימים. כפו על הסוכן לחפש דפוסים קיימים קודם. עיגון בקוד האמיתי שלכם מונע המצאה מחדש." }, + { question: "האם סוכני AI יכולים לסקור קוד שהם עצמם יצרו?", answer: "לא באותו קונטקסט. סוכנים שסוקרים את העבודה שלהם מגנים על החלטות קודמות—הטיית אישור (confirmation bias). הם מגנים על בעיות במקום לזהות אותן. לניתוח אובייקטיבי, סקרו בקונטקסט טרי (שיחה אחרת) שבה לסוכן אין זיכרון של החלטות המימוש." }, + { question: "איך אני מאמת קוד שנוצר על ידי AI ביעילות?", answer: "השתמשו בוורקפלואו של שלושה קונטקסטים: צרו קוד בקונטקסט A, כתבו בדיקות בקונטקסט טרי B (הסוכן לא יכול להגן על המימוש שלו), ובצעו triage לכישלונות בקונטקסט C (ניתוח אובייקטיבי). השתמשו בבדיקות sociable שמפעילות קוד אמיתי—mock רק מערכות חיצוניות. בדיקות מגדירות את גבולות התפעול שסוכנים לא יכולים לחצות." }, + { question: "איך סוכני קידוד AI מטפלים בבסיסי קוד גדולים?", answer: "הם לא טוענים הכל—הם מאצילים מחקר לתת-סוכנים (sub-agents). גם חלונות קונטקסט של מיליון טוקנים לא יכולים להחזיק monorepos ארגוניים, ומילוי הקונטקסט פוגע באיכות (תשומת לב בצורת U פירושה שהאמצע מתעלם). הפתרון מתרחב עם גודל בסיס הקוד: מתחת ל-10K שורות, חיפוש אגנטי (Grep, Read, Glob) עובד בסדר. ב-10-100K שורות, הוסיפו חיפוש סמנטי או תת-סוכנים. מעל 100K שורות, אתם צריכים מחקר קוד—כלים כמו ChunkHound מייצרים דוחות ארכיטקטוניים שממפים רכיבים, יחסים ודפוסים על פני מיליוני שורות." }, + { question: "איך סוכני AI מטפלים בבאגים עמומים וגרסאות חבילה אחרונות?", answer: "ל-LLMs יש knowledge cutoffs—הם מאומנים על datasets סטטיים שקפואים בנקודת זמן. הם לא יודעים על CVEs אחרונים, שינויים שוברים בגרסאות חבילה חדשות יותר, APIs שהוצאו משימוש, או best practices נוכחיות. התיקון: עשו עיגון לסוכנים עם מחקר אינטרנט בזמן אמת לפני יצירה. במקום לנחש מנתוני אימון ישנים, סוכנים מתשאלים תיעוד נוכחי, changelogs ודיונים קהילתיים. ArguSeek הוא שרת MCP למחקר רחב—מסנתז במהירות מקורות רבים כך שסוכנים עובדים עם עובדות נוכחיות במקום להמציא מדפוסים מיושנים." } + ] +}; + + + +## תחילת העבודה + +### מהו קידוד אגנטי? + +קידוד אגנטי הוא פיתוח תוכנה באמצעות סוכני AI שיכולים לתפוס את בסיס הקוד שלכם, להסיק לגבי משימות, לבצע פעולות (לכתוב קוד, להריץ בדיקות, לבצע פקודות), ולחזור על התהליך בהתבסס על משוב. בניגוד לממשקי צ'אט מסורתיים, סוכנים פועלים באופן אוטונומי בתוך מעקות בטיחות שאתם מגדירים. + +הקורס הזה מלמד מתודולוגיה מובנית—מחקר, תכנון, ביצוע, אימות—שהופכת קידוד אגנטי לאמין עבור מערכות פרודקשן. + +*למדו עוד ב-[שיעור 2: איך סוכנים עובדים](/docs/fundamentals/lesson-2-how-agents-work).* + +### מהו פיתוח אגנטי? + +פיתוח אגנטי מרחיב קידוד אגנטי על פני מחזור חיי פיתוח התוכנה המלא—מאיסוף דרישות ועד פריסה ותחזוקה. בעוד שקידוד אגנטי מתמקד בפעולת כתיבה ובדיקת קוד עם סוכני AI, פיתוח אגנטי מקיף את ה-pipeline הרחב יותר: תכנון מונחה-spec, בדיקות אוטומטיות, אינטגרציית CI/CD וניטור פרודקשן. + +בעוד שהמונחים האלה חופפים קונספטואלית, ספרות התעשייה בדרך כלל שומרת על הבחנת היקף. + +*למדו עוד ב-[שיעור 3: תהליך העבודה בארבעת השלבים](/docs/methodology/lesson-3-high-level-methodology).* + +### למי מיועד הקורס הזה? + +מהנדסי תוכנה בכירים עם 3+ שנות ניסיון פרודקשן שניסו עוזרי קידוד AI ונתקלו בנקודות תסכול. אתם צריכים יסודות חזקים בארכיטקטורה, design patterns ועיצוב מערכות כי קידוד אגנטי מעביר את העבודה שלכם למעלה בסטאק—אתם מקבלים החלטות ומאמתים תוצאות, לא כותבים כל שורה. + +*למדו עוד ב-[מבוא לקורס](/docs/).* + +### איך מתחילים עם קידוד אגנטי? + +התחילו עם היסודות: הבינו איך LLMs עובדים (התאמת דפוסים סטטיסטית שמאפשרת הסקה), למדו את לולאת הסוכן (perceive-reason-act-observe-verify), ואז תרגלו את הוורקפלואו בארבעת השלבים על משימה אמיתית. התחילו במצב מפוקח עד שאתם סומכים על תהליך העיגון והאימות שלכם. + +*התחילו עם [שיעור 1: איך LLMs עובדים](/docs/fundamentals/lesson-1-how-llms-work).* + +--- + +## Vibe Coding מול קידוד אגנטי + +### מהו vibe coding? + +Vibe coding, [שנטבע על ידי Andrej Karpathy](https://x.com/karpathy/status/1886192184808149383) (פברואר 2025), מתאר פיתוח בסיוע AI שבו אתם "נכנעים לחלוטין לאווירה" ומקבלים קוד שנוצר ללא סקירה. אתם מתארים מה שאתם רוצים, מדביקים הודעות שגיאה כשדברים נשברים, וחוזרים עד שזה עובד—ללא הבנת הקוד. + +זה יעיל לאבות-טיפוס זמניים וסקריפטים אישיים, אבל מייצר קוד לא ניתן לתחזוקה, פוטנציאלית לא מאובטח, לא מתאים למערכות פרודקשן. + +*ראו [שיעור 3: תהליך העבודה בארבעת השלבים](/docs/methodology/lesson-3-high-level-methodology) להסבר למה זה חשוב.* + +### מה ההבדל בין קידוד אגנטי ל-vibe coding? + +ההבדל הוא אחריותיות. Vibe coding פירושו קבלת פלט AI ללא הבנתו—אתם נוסעים. קידוד אגנטי פירושו הנחיית סוכני AI דרך תהליך עבודה מובנה תוך בעלות על כל החלטה. אתם מאמתים פלטים, מבינים מה נשלח, ומתחזקים את בסיס הקוד. + +שניהם משתמשים ב-AI ליצירת קוד, אבל קידוד אגנטי מתייחס לאדם כמהנדס האחראי, לא כנוסע. + +| | Vibe Coding | קידוד אגנטי | +|---|---|---| +| **תפקיד אנושי** | נוסע | מפעיל/מפקח | +| **סקירת קוד** | אין | כל פלט מאומת | +| **ארכיטקטורה** | AI מחליט | מהנדס מחליט | +| **אחריותיות** | אין | בעלות מלאה | +| **מקרה שימוש** | אבות-טיפוס | מערכות פרודקשן | + +*למדו עוד ב-[שיעור 3: תהליך העבודה בארבעת השלבים](/docs/methodology/lesson-3-high-level-methodology).* + +### מהו vibe engineering? + +Vibe engineering, [שנטבע על ידי Simon Willison](https://simonwillison.net/2025/Oct/7/vibe-engineering) (אוקטובר 2025), מתאר קידוד בסיוע AI שבו אתם סוקרים ומבינים לעומק קוד שנוצר לפני שליחה. זו גישה ממושמעת שמגבירה שיטות הנדסת תוכנה מבוססות: בדיקות אוטומטיות, תיעוד, סקירת קוד ואימות. + +קידוד אגנטי חולק את עקרון האחריותיות הזה אבל מוסיף מבנה מפורש: תהליך העבודה בארבעת השלבים (מחקר, תכנון, ביצוע, אימות) שהופכת פיתוח בסיוע AI לצפוי וחוזר. + +*למדו עוד ב-[שיעור 3: תהליך העבודה בארבעת השלבים](/docs/methodology/lesson-3-high-level-methodology).* + +--- + +## מונחון מהיר + +| מונח | מקור | היקף | תפקיד אנושי | +|------|--------|-------|------------| +| **Vibe Coding** | Karpathy, פברואר 2025 | רמת משימה | נוסע (ללא סקירה) | +| **Vibe Engineering** | Willison, אוקטובר 2025 | רמת משימה | סוקר אחראי | +| **קידוד אגנטי** | תעשייה, 2024-2025 | רמת משימה | מפעיל שמנחה סוכנים | +| **פיתוח אגנטי** | תעשייה, 2024-2025 | SDLC מלא | ארכיטקט על פני pipeline | + +**שני צירים:** +- **אחריותיות:** Vibe coding (אין) ← Vibe engineering / קידוד אגנטי (מלא) +- **היקף:** קידוד אגנטי (הפעולה) ← פיתוח אגנטי (מחזור החיים) + +בעוד ש"קידוד אגנטי" ו"פיתוח אגנטי" חופפים קונספטואלית, ספרות התעשייה בדרך כלל שומרת על הבחנת היקף זו. + +--- + +## כלים ומתודולוגיה + +### אילו כלי קידוד AI תומכים בקידוד אגנטי? + +הקורס הזה ממליץ על **סוכני קידוד CLI**—Claude Code, Aider, או Codex CLI—כי כלים מבוססי-טרמינל מאפשרים מקביליות: הרצת מופעי סוכן מרובים על פני tabs טרמינל שונים או git worktrees בו-זמנית. + +סוכני IDE (Cursor, Copilot) עובדים אבל צמודים לחלונות בודדים, מה שמגביל תהליכי עבודה במקביל. ממשקי צ'אט (ChatGPT, Copilot Chat) מאפסים קונטקסט בין שיחות—הם שימושיים לסיעור מוחות, לא לביצוע אוטונומי. + +המתודולוגיה חלה על כל סוכן, אבל סוכני CLI פותחים את מודל הביצוע המקבילי שהקורס הזה מלמד. + +*למדו עוד ב-[שיעור 2: הסרת המסתורין מסוכנים](/docs/fundamentals/lesson-2-how-agents-work) ו-[שיעור 7: תכנון וביצוע](/docs/practical-techniques/lesson-7-planning-execution).* + +### האם קידוד אגנטי טוב יותר מ-prompt engineering? + +Prompt engineering ממטב פרומפטים בודדים. קידוד אגנטי הוא מתודולוגיה שלמה: מחקר, תכנון, ביצוע, אימות. אתם עדיין כותבים פרומפטים, אבל בתוך וורקפלואו מובנה שכולל עיגון של סוכנים בבסיס הקוד שלכם, סקירת תוכניות לפני ביצוע, ואימות פלט מול המודל המנטלי שלכם. + +*למדו עוד ב-[שיעור 4: Prompting 101](/docs/methodology/lesson-4-prompting-101).* + +### למה "כלי כוח" במקום "מפתח ג'וניור"? + +כלי כוח לא 'מבין' מה אתם בונים—הוא מבצע בהתאם לאיך שאתם מפעילים אותו. אתם לא מתעצבנים כשמסור עגול חותך בזווית הלא נכונה; אתם מתאימים את ההגדרה והטכניקה שלכם. אותו דבר עם סוכני AI. אתם בעלי התוצאות, מאמתים דרך בדיקות, ומדבגים את הקלט שלכם כשהפלט נכשל. + +*למדו עוד ב-[שיעור 1: איך LLMs עובדים](/docs/fundamentals/lesson-1-how-llms-work).* + +### מהו הוורקפלואו של קידוד אגנטי? + +ארבעה שלבים: מחקר (עשו עיגון לסוכנים בדפוסי בסיס הקוד שלכם וידע דומיין חיצוני), תכנון (בחרו אסטרטגיית חקירה או תכנון מדויק, קבלו החלטות ארכיטקטוניות), ביצוע (האצילו לסוכנים במצב מפוקח או אוטונומי), אימות (החליטו לחזור או לייצר מחדש בהתאם להתאמה למודל המנטלי שלכם ובדיקות אוטומטיות). דילוג על כל שלב מעלה דרמטית את שיעור הכישלון. + +*למדו עוד ב-[שיעור 3: תהליך העבודה בארבעת השלבים](/docs/methodology/lesson-3-high-level-methodology).* + +### למה חלק מהמפתחים מדווחים שהם איטיים יותר עם כלי AI? + +[מחקרים מראים](https://arxiv.org/abs/2507.09089) שמפתחים מנוסים לעתים קרובות איטיים יותר במשימות בודדות עם AI—למרות שהם מאמינים שהם מהירים יותר. מהירות לכל משימה היא המדד הלא נכון. המתודולוגיה הזו מלמדת שהרווח האמיתי בפרודוקטיביות מגיע ממקביליות: הרצת סוכנים מרובים על משימות שונות בזמן שאתם משתתפים בפגישות, סוקרים PRים, או מטפלים בעבודה אחרת. מהנדס בכיר עם שלושה סוכנים מקביליים משחרר יותר מאחד שמשגיח על שיחה אחת. + +*למדו עוד ב-[שיעור 3: תהליך העבודה בארבעת השלבים](/docs/methodology/lesson-3-high-level-methodology).* + +--- + +## בעיות נפוצות + +### למה סוכן ה-AI שלי ממציא קוד לא נכון? + +סוכנים לא יודעים שבסיס הקוד שלכם קיים. ללא עיגון (grounding), הם מייצרים מדפוסי נתוני אימון שקפואים ב-knowledge cutoff שלהם. התיקון: הזריקו את דפוסי הקוד האמיתיים שלכם, אילוצים ארכיטקטוניים ותיעוד נוכחי לקונטקסט לפני שמבקשים יצירה. עיגון מפחית משמעותית הזיות על ידי עיגון יצירה בבסיס הקוד האמיתי שלכם. + +*למדו עוד ב-[שיעור 5: גראונדינג](/docs/methodology/lesson-5-grounding).* + +### למה סוכן ה-AI שלי שוכח קונטקסט באמצע משימה? + +LLMs הם סטייטלס (stateless)—הם יודעים רק מה שבחלון הקונטקסט הנוכחי. כשהשיחות גדלות, קונטקסט ישן יותר נגלל החוצה. זה לא באג; זה יסודי לאיך מודלי transformer עובדים. + +התיקון: **טענו קונטקסט במתכוון** לפני כל שלב משימה. שאלו שאלות חקירתיות ("איך עובד ה-auth middleware שלנו?") כדי להפעיל קריאות קבצים שמאכלסות את החלון עם קוד רלוונטי. ההסבר של הסוכן עכשיו קיים בקונטקסט לצעדי המימוש הבאים. + +השתמשו בקבצי הוראות היררכיים (CLAUDE.md ברמות repo ותיקייה) כדי לשמר אילוצים ארכיטקטוניים ודפוסים שתמיד צריכים להיות זמינים. עיגון הוא לא צעד חד-פעמי מקדים—זו הנדסת קונטקסט מתמשכת לאורך הסשן. + +*למדו עוד ב-[שיעור 5: גראונדינג](/docs/methodology/lesson-5-grounding) ו-[שיעור 7: תכנון וביצוע](/docs/practical-techniques/lesson-7-planning-execution#prompt-to-explain-loading-context-into-the-window).* + +### איך אני עוצר סוכני AI משכפול קוד? + +סוכנים מגבירים דפוסים קיימים—הם לא ממציאים כפילות. אם בבסיס הקוד שלכם יש דפוסים לא עקביים, סוכנים משכפלים אותם. לפני בקשת מימושים חדשים, הראו קיימים. כפו על הסוכן לחפש דפוסים קיימים קודם. עיגון בקוד האמיתי שלכם מונע המצאה מחדש. + +*למדו עוד ב-[שיעור 11: כתיבת קוד ידידותי-לסוכן](/docs/practical-techniques/lesson-11-agent-friendly-code).* + +### האם סוכני AI יכולים לסקור קוד שהם עצמם יצרו? + +לא באותו קונטקסט. סוכנים שסוקרים את העבודה שלהם מגנים על החלטות קודמות—הטיית אישור (confirmation bias). הם מגנים על בעיות במקום לזהות אותן. לניתוח אובייקטיבי, סקרו בקונטקסט טרי (שיחה אחרת) שבה לסוכן אין זיכרון של החלטות המימוש. + +*למדו עוד ב-[שיעור 9: סקירת קוד](/docs/practical-techniques/lesson-9-reviewing-code).* + +### איך אני מאמת קוד שנוצר על ידי AI ביעילות? + +השתמשו בוורקפלואו של שלושה קונטקסטים: צרו קוד בקונטקסט A, כתבו בדיקות בקונטקסט טרי B (הסוכן לא יכול להגן על המימוש שלו), ובצעו triage לכישלונות בקונטקסט C (ניתוח אובייקטיבי). השתמשו בבדיקות sociable שמפעילות קוד אמיתי—mock רק מערכות חיצוניות. בדיקות מגדירות את גבולות התפעול שסוכנים לא יכולים לחצות. + +*למדו עוד ב-[שיעור 8: בדיקות כמעקות בטיחות](/docs/practical-techniques/lesson-8-tests-as-guardrails).* + +### איך סוכני קידוד AI מטפלים בבסיסי קוד גדולים? + +הם לא טוענים הכל—הם מאצילים מחקר לתת-סוכנים (sub-agents). גם חלונות קונטקסט של מיליון טוקנים לא יכולים להחזיק monorepos ארגוניים, ומילוי הקונטקסט פוגע באיכות (תשומת לב בצורת U פירושה שהאמצע מתעלם). + +הפתרון מתרחב עם גודל בסיס הקוד: מתחת ל-10K שורות, חיפוש אגנטי (Grep, Read, Glob) עובד בסדר. ב-10-100K שורות, הוסיפו חיפוש סמנטי או תת-סוכנים. מעל 100K שורות, אתם צריכים מחקר קוד—כלים כמו [ChunkHound](https://chunkhound.github.io/code-research/) מייצרים דוחות ארכיטקטוניים שממפים רכיבים, יחסים ודפוסים על פני מיליוני שורות. + +*למדו עוד ב-[שיעור 5: גראונדינג](/docs/methodology/lesson-5-grounding).* + +### איך סוכני AI מטפלים בבאגים עמומים וגרסאות חבילה אחרונות? + +ל-LLMs יש knowledge cutoffs—הם מאומנים על datasets סטטיים שקפואים בנקודת זמן. הם לא יודעים על CVEs אחרונים, שינויים שוברים בגרסאות חבילה חדשות יותר, APIs שהוצאו משימוש, או best practices נוכחיות. + +התיקון: עשו עיגון לסוכנים עם מחקר אינטרנט בזמן אמת לפני יצירה. במקום לנחש מנתוני אימון ישנים, סוכנים מתשאלים תיעוד נוכחי, changelogs ודיונים קהילתיים. + +[ArguSeek](https://github.com/ArguSeek/arguseek) הוא שרת MCP למחקר רחב—מסנתז במהירות מקורות רבים כך שסוכנים עובדים עם עובדות נוכחיות במקום להמציא מדפוסים מיושנים. בשילוב עם עיגון של בסיס קוד, זה מעגן יצירה גם בדפוסים הקיימים שלכם וגם במציאות הנוכחית. + +*למדו עוד ב-[שיעור 5: גראונדינג](/docs/methodology/lesson-5-grounding).* + +--- + +**מוכנים להתחיל?** התחילו עם [שיעור 1: איך LLMs עובדים](/docs/fundamentals/lesson-1-how-llms-work) או חקרו את [ספריית הפרומפטים](/prompts). diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/fundamentals/lesson-1-how-llms-work.md b/website/i18n/he/docusaurus-plugin-content-docs/current/fundamentals/lesson-1-how-llms-work.md new file mode 100644 index 0000000..2a9250b --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/fundamentals/lesson-1-how-llms-work.md @@ -0,0 +1,134 @@ +--- +sidebar_position: 1 +sidebar_label: 'שיעור 1: הקסם מאחורי המודלים' +title: 'שיעור 1: הקסם מאחורי המודלים' +--- + +ברוכים הבאים לעתיד הנדסת התוכנה. הקורס הזה מלמד אתכם **לתפעל סוכני AI** שמבצעים באופן אוטונומי משימות פיתוח מורכבות - מ-specification ועד deployment. + +## שינוי הפרדיגמה + +הנדסת תוכנה עוברת טרנספורמציה יסודית, דומה לאיך שכלים חשמליים חוללו מהפכה בבנייה. + +**טרנספורמציה בבנייה:** + +- **עידן הכלים הידניים:** נגרים עיצבו כל חלק ידנית דרך אומנות +- **עידן הכלים האוטומטיים:** בעלי מקצוע מעצבים פרויקטים, מפעילים מכונות, מאמתים פלט +- **תוצאה:** רווחים משמעותיים ברוחב פס, חזרתיות ודיוק + +**טרנספורמציה בהנדסת תוכנה:** + +- **מסורתי:** מהנדסים כותבים קוד שורה-אחרי-שורה, מתמקדים בתחביר ופרטי המימוש +- **מונחה-סוכן:** מהנדסים מתזמרים (orchestrate) סוכני AI שמבצעים משימות באופן אוטונומי, מתמקדים בארכיטקטורה ואימות +- **תוצאה:** אותם רווחים - רוחב פס, חזרתיות, דיוק דרך תצורה + +**רווח ברוחב פס ויצירתיות, לא איבוד שליטה.** + +## עקרונות ראשוניים: הבנת המכונה + +לפני שנדון במה סוכני AI יכולים לעשות, בואו נבסס מה הם בעצם - כי הטרמינולוגיה גורמת להם להישמע הרבה יותר קסומים ממה שמגיע להם. + +### LLM = מוח (מנוע חיזוי טוקנים) + +Large Language Model או "מודל שפה גדול" הוא מתאם דפוסים סטטיסטי (Statistical Pattern Matcher) שבנוי על [ארכיטקטורת transformer](). הוא: + +- **מנחש את הטוקן הסביר הבא** (מילה/תת-מילה) ברצף +- **מעבד כ-200 אלף טוקנים** של קונטקסט (זיכרון עבודה) +- **דוגם מהתפלגויות הסתברות** שנלמדו מנתוני אימון +- **בעל אפס תודעה, כוונה או רגשות** + +:::tip[מהו טוקן?] +**טוקן**, +מילה או תת-מילה; מילולית: "אסימון", + הוא היחידה האטומית של LLM - ה"פיקסל" של עיבוד טקסט. ממוצע כ-3-4 תווים, אבל משתנה מאוד: מילים קצרות נפוצות הן טוקנים בודדים (`"the"`, `"is"`), בעוד מילים ארוכות או נדירות מתפצלות לתת-מילים באמצעות אלגוריתמים כמו [Byte-Pair Encoding](https://en.wikipedia.org/wiki/Byte-pair_encoding). + +**למה זה חשוב:** + +- **עלות:** ספקי LLM מחייבים לפי טוקן (קלט + פלט) +- **מגבלות קונטקסט:** חלון הכ-200 אלף טוקנים הוא תקציב זיכרון העבודה שלכם +- **ביצועים:** פרומפטים יעילים בטוקנים = תגובות מהירות ועלויות נמוכות יותר + +כלל אצבע: +טוקן אחד הוא בערך ¾ מילה באנגלית. + הפסקה הזו היא כ-150 טוקנים. קובץ מקור טיפוסי מכיל 3-15 אלף טוקנים. +::: + +חשבו על זה כמו autocomplete מתוחכם להפליא - כזה שקרא את רוב האינטרנט ויכול לייצר המשכים משכנעים לכל תבנית טקסט שראה קודם. + +**מציאות טכנית מול שפה שיווקית:** + +| אנחנו אומרים (מטאפורה) | מה באמת קורה | +| ----------------------- | --------------------------------------------------------------------------------- | +| "הסוכן חושב" | LLM מייצר חיזויי טוקנים דרך שכבות multi-head attention | +| "הסוכן מבין" | התאמת דפוסים (Pattern Matching) מול נתוני אימון מייצרת פלט סביר בהקשר הנתון | +| "הסוכן לומד" | משקולות סטטיסטיות מתעדכנות במהלך אימון (לא במהלך השיחה שלכם) | +| "הסוכן מסיק" | פירוק בעיות לחיזויי טוקנים רצופים שנבנים אחד על השני | + +### תוכנת סוכן = גוף (שכבת ביצוע - Execution Layer) + +ה-LLM לבדו יכול רק לייצר טקסט. תוכנת סוכן רגילה, **דטרמיניסטית**, עוטפת את ה-LLM כדי לאפשר **פעולה**: + +- **פעולות על קבצים:** Read, Write, Edit +- **הרצת פקודות:** Bash, git, npm, pytest +- **חיפוש קוד:** Grep, Glob +- **קריאות API:** Fetch docs, משאבים חיצוניים + +**ה-LLM הוא המוח. ה-framework של הסוכן הוא הגוף.** + +כשסוכן "מיישם פיצ'ר," הנה מה שבאמת קורה: + +1. LLM מנחש "אני צריך לקרוא את ה-auth middleware הקיים" ← סוכן מבצע `Read(src/auth.ts)` +2. LLM מנחש שינויי קוד ← סוכן מבצע `Edit(file, old, new)` +3. LLM מנחש "הרץ בדיקות" ← סוכן מבצע `Bash("npm test")` +4. LLM מנתח פלט בדיקות ← מנחש תיקונים ← הלולאה ממשיכה + +בלי קסם. בלי תודעה. רק **התפלגויות הסתברות שמניעות הפעלת כלים.** + +### למה זה חשוב לכם כמפעילים + +הבנת המכונה מונעת שלוש שגיאות קריטיות: + +**שגיאה 1: הנחה שהסוכן "יודע" דברים** + +- מציאות: הוא רואה רק קונטקסט נוכחי (כ-200 אלף טוקנים) +- התיקון שלכם: ספקו קונטקסט מפורש (עקרון 1, מכוסה בשיעור 3) + +**שגיאה 2: ציפייה שהסוכן "יאכפת לו" מתוצאות** + +- מציאות: הוא מבצע את ההוראה המילולית שלכם עד הסוף +- התיקון שלכם: היו מדויקים וכללו אילוצים (עקרון 2, מכוסה בשיעור 3) + +**שגיאה 3: התייחסות אליו כחבר צוות במקום ככלי** + +- מציאות: הוא מכשיר דיוק שמדבר אנגלית +- התיקון שלכם: שמרו על Tool Mindset - גישה של כלי (עקרון 3, מכוסה בשיעור 3) + +**אנלוגיה: LLMs הם מכונות אוטומציה לקוד** + +מכונה אוטומטית לא "מבינה" מה אתם בונים. היא מבצעת בהתאם לאיך שאתם מפעילים אותה. אתם לא מאשימים מסור שולחן על חיתוך גרוע—אתם מתאימים את הטכניקה וההגדרה שלכם. + +אותו דבר עם LLMs. הם כלים שמבצעים הוראות מבוססות-שפה עם שטף מרשים אבל אפס הבנה. + +### הכוח (והמגבלה) של "Autocomplete מתוחכם" + +זה אולי נשמע מצמצם, אבל זה משחרר: + +- **כוח:** מנועי חיזוי טוקנים אלה טובים להפליא בלחזור על דפוסי קוד שראו +- **מגבלה:** אין להם מודל של נכונות, רק הסתברות +- **השלכה:** העבודה שלכם היא ליצור מערכות אימות (Verification) - בדיקות, טיפוסים, לינטינג - שתופסות שגיאות הסתברותיות + +אתם לא מנהלים מפתח ג'וניור. אתם מפעילים כלי יצירת קוד מתוחכם שצריך **מעקות בטיחות ארכיטקטוניים (Architectural Guardrails)**. + +עכשיו שהבנו איך המכונה עובדת, בואו נדון בעקרונות ההפעלה ובתהליכי העבודה. + +## סיכום + +אתם לומדים **לתפעל מכשירי דיוק**, לא לנהל חברי צוות. הבנת מה הם בעצם סוכני AI - LLMs (מנועי חיזוי טוקנים) עטופים בתוכנת סוכן (שכבת ביצוע) - היא יסודית לשימוש יעיל בהם. + +שלוש שגיאות המפעיל שכוסו למעלה נובעות מייחוס תכונות אנושיות לכלים האלה. הימנעו מהנחה שהם "יודעים" דברים, "אכפת להם" מתוצאות, או מתפקדים כחברי צוות. הם מכשירים מתוחכמים שמבצעים הוראות מבוססות-שפה. + +השיעור הבא מכסה ארכיטקטורת סוכנים, תהליכי עבודה של ביצוע, ואיך התפקיד שלכם כמהנדסים מתפתח למפעיל. + +--- + +**הבא:** [שיעור 2: הקסם מאחורי הסוכנים](./lesson-2-how-agents-work.md) diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/fundamentals/lesson-2-how-agents-work.md b/website/i18n/he/docusaurus-plugin-content-docs/current/fundamentals/lesson-2-how-agents-work.md new file mode 100644 index 0000000..683970a --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/fundamentals/lesson-2-how-agents-work.md @@ -0,0 +1,262 @@ +--- +sidebar_position: 2 +sidebar_label: 'שיעור 2: הקסם מאחורי הסוכנים' +title: 'שיעור שיעור 2: הקסם מאחורי הסוכנים' +--- + +import AbstractShapesVisualization from '@site/src/components/VisualElements/AbstractShapesVisualization'; + +בשיעור 1, הבססנו ש**LLMs הם מוחות** (מנועי חיזוי טוקנים) ו**frameworks של סוכנים הם גופים** (שכבות ביצוע). עכשיו בואו נבין איך הרכיבים האלה עובדים יחד ליצירת סוכני קידוד אוטונומיים שיכולים להשלים משימות מורכבות. + +## לולאת הביצוע של הסוכן + +סוכן הוא לא רק LLM שמגיב לפרומפטים. זו **לולאת משוב** שמשלבת הסקה עם פעולה, מאפשרת ל-LLM לעבוד איטרטיבית לעבר מטרה. + +### לולאה בסיסית: Perceive → Reason → Act → Verify → Iterate +**להבחין ← לנתח ← לפעול ← לאמת ← לחזור** + +```mermaid +flowchart TD + Start([User Task]) --> Perceive[Perceive
Read context: files, state, history] + Perceive --> Reason[Reason
LLM generates plan and next action] + Reason --> Act[Act
Execute tool: Read, Edit, Bash, etc.] + Act --> Observe[Observe
Process tool output] + Observe --> Verify{Verify
?Goal achieved} + Verify -->|No| Iterate[Iterate] + Iterate --> Perceive + Verify -->|Yes| Complete([Complete]) + + classDef workflow fill:#a78bfa,stroke:#7c3aed,stroke-width:2px,color:#fff + classDef decision fill:#8b5cf6,stroke:#6d28d9,stroke-width:2px,color:#fff + classDef endpoint fill:#7c3aed,stroke:#6d28d9,stroke-width:3px,color:#fff + + class Perceive,Reason,Act,Observe,Iterate workflow + class Verify decision + class Start,Complete endpoint +``` + +**הבחנה מרכזית:** ממשק צ'אט דורש מכם לבצע פעולות ידנית בין פרומפטים. סוכן **רץ בלופ אוטונומי** דרך המחזור הזה. + +### דוגמה: יישום פיצ'ר + +**תהליך עבודה של ממשק צ'אט:** + +1. אתם: "איך אני צריך להוסיף authentication ל-API הזה?" +2. LLM: "הנה הקוד..." +3. **אתם עורכים קבצים ידנית** +4. אתם: "קיבלתי את השגיאה הזו..." +5. LLM: "נסו את התיקון הזה..." +6. **אתם עורכים שוב ידנית** + +**תהליך עבודה של סוכן:** + +1. אתם: "הוסף authentication ל-API הזה" +2. סוכן: [Perceive] קורא קבצי API קיימים ← [Reason] מתכנן ← [Act] עורך קבצים ← [Observe] מריץ בדיקות ← [Verify] בדיקות נכשלות ← [Reason] מנתח שגיאה ← [Act] מתקן קוד ← [Observe] מריץ בדיקות ← [Verify] בדיקות עוברות ← סיום + +הסוכן **סוגר את הלולאה** אוטומטית, מבצע את המחזור המלא ללא צורך בהתערבות ידנית בכל שלב. + +## מתחת למכסה: הכל רק טקסט + +הנה האמת היסודית שמבהירה מה הם סוכני קידוד AI: **הכל רק טקסט שזורם דרך חלון הקונטקסט (context window).** + +ללא קסם, ללא מנוע הסקה נפרד, ללא מצב נסתר. כשאתם מתקשרים עם סוכן, אתם צופים בשיחה שמתגלגלת בבאפר טקסט גדול אחד. + +### הזרימה הטקסטואלית + +כל אינטראקציה עם סוכן עוקבת אחר התבנית הזו: + +```mermaid +sequenceDiagram + participant U as User + participant A as Agent (LLM) + participant T as Tools + + Note over A: System Prompt
Sets up agent behavior, defines tools + U->>A: User Prompt
"Add input validation to registration" + Note over A: Decides to use Grep tool + A->>T: Grep + T->>A: Tool Result
Grep results added to context as text + Note over A: Decides to Read file + A->>T: Read + T->>A: Tool Result
File contents added to context as text + Note over A: Decides to Edit file + A->>T: Edit + T->>A: Tool Result
"Edit successful" added to context + Note over A: Decides to run tests via Bash + A->>T: Bash + T->>A: Tool Result
Test output added to context + A->>U: Agent Response
"Task complete" +``` + +:::tip[הסקה היא רק טקסט] +הסוכן לא "חושב" בנפרד מהפלט שלו. כשאתם רואים את הסוכן מסיק ("אני צריך לבדוק את לוגיקת הוולידציה..."), זו לא מחשבה פנימית - זה טקסט שמיוצר בקונטקסט, גלוי גם לכם וגם ל-LLM עצמו. + +**מצבי extended thinking מסבכים את זה עוד יותר:** ספקים כמו Anthropic ו-OpenAI מציעים עכשיו "extended thinking" שבו המודל מייצר טוקני הסקה נסתרים לפני שהוא מייצר פלט גלוי. מה שאתם רואים בקונטקסט הוא _סיכום_ של chain-of-thought הפנימי, לא תהליך ההסקה המלא. אתם מחויבים על טוקני ההסקה הנסתרים המלאים, אבל אתם רואים רק גרסה מקוצרת. ההסקה האמיתית היא אטומה - לא ניתן לבחון או לדבג אותה. +::: + +### דוגמה קונקרטית: איך הקונטקסט באמת נראה + +כשאתם מבקשים מ-Claude Code "להוסיף email validation לקונטרולר של ההרשמה," חלון הקונטקסט מכיל זרם טקסט רציף אחד. הנה בדיוק מה שזורם דרך הקונטקסט של הסוכן - הוראות מערכת, המשימה שלכם, קריאות כלים, תוצאות ותגובות הכל כטקסט: + +``` +SYSTEM: You are Claude Code, an AI coding assistant. You have access to these tools: +- Read(file_path): Read a file +- Edit(file_path, old_string, new_string): Edit a file +- Bash(command): Run a shell command +- Grep(pattern, path): Search for pattern in files +[... more tool descriptions ...] + +USER: Add email validation to the registration endpoint + +ASSISTANT: I'll search for the registration endpoint first. + + Grep + + register + **/*.ts + + + +TOOL_RESULT: Found in: +- src/routes/auth.ts:12: router.post('/register', userHandler.register) +- src/handlers/user.ts:45: export async function register(req, res) { + +ASSISTANT: Found the endpoint. Let me read the handler to see current validation. + + Read + + src/handlers/user.ts + + + +TOOL_RESULT: [file contents showing no email validation] + +ASSISTANT: No validation present. I'll add email validation using Zod. + + Edit + + src/handlers/user.ts + export async function register(req, res) { + const { email, password } = req.body; + await db.users.create({ email, password }); + const registerSchema = z.object({ + email: z.string().email(), + password: z.string().min(8) +}); + +export async function register(req, res) { + const { email, password } = registerSchema.parse(req.body); + await db.users.create({ email, password }); + + + +TOOL_RESULT: Edit successful + +ASSISTANT: Validation added. Running tests to verify. + + Bash + + npm test user.test.ts + + + +TOOL_RESULT: PASS src/handlers/user.test.ts + ✓ rejects invalid email (12ms) + ✓ rejects short password (8ms) + +ASSISTANT: Email validation successfully added to the registration endpoint. +``` + +השיחה הזו בשלמותה - הוראות מערכת, המשימה שלכם, קריאות כלים, תוצאות ותגובות - קיימת כ**זרם טקסט רציף אחד** בחלון הקונטקסט של ה-LLM. + +### למה זה חשוב + +הבנת הטבע הטקסטואלי של סוכנים עוזרת לכם: + +1. **לצפות התנהגות** - הסוכן יודע רק מה שבקונטקסט +2. **לדבג בלבול** - אם הסוכן שוכח משהו, זה כנראה כי זה נגלל מחוץ לקונטקסט +3. **לבנות פרומפטים טובים יותר** - אתם מוסיפים טקסט לשיחה, לא מוציאים פקודות +4. **לזהות מגבלות** - חלונות קונטקסט סופיים; משימות מורכבות עלולות לאבד פרטים + +### היתרון של סטייטלס (Stateless) + +הנה תובנה קריטית שמשנה איך אתם עובדים עם סוכני קידוד AI: **ה-LLM הוא לחלוטין סטייטלס.** ה"עולם" היחיד שלו הוא חלון הקונטקסט הנוכחי. + +ה-LLM לא "זוכר" שיחות קודמות. אין לו סטייט (state) פנימי נסתר. כל תגובה מיוצרת אך ורק מהטקסט שנמצא כרגע בקונטקסט. כשהשיחה ממשיכה, ה-LLM רואה את התגובות הקודמות שלו כטקסט בקונטקסט, לא כזיכרונות שהוא נזכר בהם. + +**זה יתרון עצום, לא מגבלה.** אתם שולטים במה הסוכן יודע על ידי שליטה במה שבקונטקסט. + +**חקירה מדף נקי:** התחילו שיחה חדשה, ולסוכן אין הטיה (bias) מהחלטות קודמות. בקשו ממנו לממש authentication עם JWT בקונטקסט אחד, sessions באחר - כל גישה נבחנת לגופה ללא צורך להגן על בחירות קודמות. + +**Code review ללא הטיה:** הסוכן יכול לבקר באופן ביקורתי את העבודה של עצמו. אל תגלו מי כתב את הקוד, והוא יבחן אותו בקפדנות מלאה ללא bias הגנתי. + + + +אותו קוד שמקבל "נראה בסדר בכללי" בקונטקסט אחד מפעיל "בעיות אבטחה קריטיות: localStorage חושף טוקנים להתקפות XSS" בקונטקסט טרי. זה מאפשר workflows של Generate → Review → Iterate שבהן הסוכן כותב קוד ואז בודק אותו באופן אובייקטיבי, או ניתוח רב-פרספקטיבי (סקירת אבטחה בקונטקסט אחד, ביצועים באחר). + +**איך אתם מהנדסים קונטקסט קובע את התנהגות הסוכן.** מניפולציה זו קורית דרך "כלים" - המנגנונים שסוכנים משתמשים בהם כדי לקרוא קבצים, להריץ פקודות ולצפות בתוצאות. + +## כלים: מובנים מול חיצוניים + +סוכנים הופכים שימושיים דרך **כלים (tools)** - פונקציות שה-LLM יכול לקרוא להן כדי לתקשר עם העולם. + +### כלים מובנים: ממוטבים למהירות + +סוכני קידוד CLI מגיעים עם כלים שנבנו במיוחד לתהליכי עבודה נפוצים: + +**Read, Edit, Bash, Grep, Write, Glob** - אלה לא רק wrappers סביב פקודות shell. הם מהונדסים עם טיפול במקרי קצה, פורמטי פלט ידידותיים-ל-LLM, מעקות בטיחות ויעילות טוקנים. + +### כלים חיצוניים: פרוטוקול MCP + +**MCP (Model Context Protocol)** הוא מערכת plugins סטנדרטית להוספת כלים מותאמים. השתמשו בו כדי לחבר את הסוכן שלכם למערכות חיצוניות: + +- לקוחות מסדי נתונים (Postgres, MongoDB) +- אינטגרציות API (Stripe, GitHub, Figma) +- פלטפורמות ענן (AWS, GCP, Azure) + +הגדירו שרתי MCP בהגדרות שלכם, והסוכן מגלה את הtools שלהם בזמן ריצה: + +```json +// ~/.claude/mcp_settings.json +{ + "servers": { + "postgres": { + "command": "npx", + "args": [ + "@modelcontextprotocol/server-postgres", + "postgresql://localhost/mydb" + ] + } + } +} +``` + +## סוכני קידוד CLI: למה הם מנצחים + +בעוד ממשקי צ'אט (ChatGPT, Copilot Chat) מצטיינים בתשובות לשאלות וסיעור מוחות, **סוכני קידוד CLI מספקים חוויית מפתח עדיפה** לעבודת מימוש בפועל. + +### יתרון העבודה במקביל + +**מספר לשוניות בטרמינל = מספר סוכנים שעובדים על פרויקטים שונים בו-זמנית.** + +פתחו שלושה tabs, הריצו סוכנים על פרויקטים שונים (refactoring ב-`project-a`, debugging ב-`project-b`, implementing ב-`project-c`). עשו context-switch בחופשיות. כל סוכן ממשיך לעבוד באופן עצמאי. + +**סוכני IDE כמו Cursor, Copilot** צמודים היטב לחלון בודד ופרויקט בודד. אתם חסומים עד שהסוכן מסיים או שאתם מבטלים ומאבדים קונטקסט. + +**ממשקי צ'אט** מאפסים קונטקסט עם כל שיחה. אתם מעתיקים-מדביקים קוד ידנית ומבצעים שינויים. + +**סוכני CLI מאפשרים מיקבול (parallelism)** ללא ניהול threads שיחה או instances של IDE מרובים. + +:::tip תצוגה מקדימה: שיעור 7 +נצלול לעומק לאסטרטגיות **תכנון וביצוע** בשיעור 7, כולל איך לבנות עבודה במקביל על פני מספר סוכנים, מתי למקבל ומתי לעבוד בטור, ואיך לתאם תהליכי עבודה מורכבים על פני מספר פרויקטים. +::: + +## Context Engineering ו-Steering + +עכשיו שאתם מבינים סוכנים כמערכות טקסטואליות ו-LLMs כסטֶייטלס, האמת המרכזית עולה: **קידוד יעיל בסיוע AI הוא על הנדסת קונטקסט כדי לנווט התנהגות**. חלון הקונטקסט הוא כל-העולם-כולו של הסוכן - כל מה שהוא יודע מגיע מהטקסט שזורם דרכו. אתם שולטים בטקסט הזה: פרומפטי system, ההוראות שלכם, תוצאות ריצה של כלים, היסטוריית שיחה. קונטקסט מעורפל מייצר התנהגות משוטטת; קונטקסט מדויק וממוקד מנווט את הסוכן בדיוק לאן שאתם צריכים. אתם יכולים לנווט מראש עם פרומפטים ממוקדים, או דינמית באמצע-שיחה כשהסוכן סוטה. הטבע הסטֶייטלסי אומר שאתם יכולים אפילו לנווט את הסוכן לסקור באופן אובייקטיבי את הקוד שלו עצמו בשיחה טרייה. + +זו חשיבת system design מיושמת לטקסט - אתם כבר טובים בעיצוב ממשקים וחוזים (contracts). שאר הקורס הזה מלמד איך ליישם את הכישורים האלה להנדסת קונטקסט ולניווט של סוכנים על פני תרחישי קידוד אמיתיים. + +--- + +**הבא:** [שיעור 3: מתודולוגיה כללית](../methodology/lesson-3-high-level-methodology.md) diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/intro.md b/website/i18n/he/docusaurus-plugin-content-docs/current/intro.md new file mode 100644 index 0000000..1ddd3c7 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/intro.md @@ -0,0 +1,94 @@ +--- +sidebar_position: 1 +slug: / +title: 'מבוא' +--- + +## המציאות + +עוזרי קידוד AI הם סטנדרט פרודקשן ב-2025—[מעל 77,000 ארגונים](https://github.com/newsroom/press-releases/github-universe-2024) אימצו את GitHub Copilot, ו-[51% מהמפתחים](https://survey.stackoverflow.co/2025/) משתמשים בכלי AI מדי יום. חברות משחררות פיצ'רים מהר יותר. מחקר עמיתים מראה [יעילות משופרת של מעל 55%](https://arxiv.org/abs/2302.06590) כבסיס—מיישמים עם מתודולוגיה נכונה מדווחים על 10x, כולל מחבר הקורס הזה. הטכנולוגיה עובדת—אבל [66% מהמפתחים](https://survey.stackoverflow.co/2025/ai/) אומרים שפתרונות AI הם "כמעט נכונים, אבל לא לגמרי," ו-[רק 3%](https://survey.stackoverflow.co/2025/ai/) סומכים מאוד על הפלט. + +**הבעיה היא לא הכלים. זה מודל התפעול.** + +אתם מתייחסים לסוכני AI כמו מפתחים ג'וניורים: מחכים שהם "יבינו," מתקנים את הקוד שלהם שורה-אחרי-שורה, נלחמים במגבלות קונטקסט. זה המודל המנטלי הלא נכון. סוכני AI הם לא חברי צוות—הם **כלים עוצמתיים**. אתם צריכים ללמוד לתפעל אותם. + +מחקרים מראים זאת: מפתחים ללא מתודולוגיה נכונה הם [למעשה איטיים ב-19%](https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/) עם כלי AI—בעוד ש"מיישמים", כלומר מפתחים שמשתמשים בגישות שיטתיות מדווחים על יעילות משופרת עד 10x. ההבדל הוא מיומנות המפעיל. + +## מה זה הקורס הזה + +הקורס הזה הוא **אימון מפעילים (operator training)** לסוכני קידוד AI. תלמדו את הגישה השיטתית שנמצאת בשימוש בסביבות פרודקשן: + +- **מחקר** - עגנו (Ground) את הסוכנים בדפוסי הקוד הרלוונטיים ובידע הדומיין לפני שהם פועלים +- **תכנון** - תכננו שינויים בצורה אסטרטגית—חקרו כשלא בטוחים, תנו הנחיות ברורות כשהמצב ברור +- **ביצוע** - הריצו סוכנים במצב מפוקח (supervised) או אוטונומי בהתאם לרמת האמון ולקריטיות המשימה +- **אימות** - ודאו שהתוצאה תואמת למודל המנטלי שלכם, ואז שפרו איטרטיבית או צרו מחדש + + +בלי לאחוז לכם ביד. בלי דוגמאות צעצוע. הקורס הזה מניח שאתם יודעים לפתח תוכנה—אנחנו מלמדים אתכם איך **לתזמר (orchestrate) סוכנים שמבצעים את העבודה באופן אוטונומי**. + +## מה הקורס הזה לא + +- **לא תיאוריית AI** - אנחנו מכסים מספיק את אחורי הקלעים כדי לתפעל ביעילות, לא יותר +- **לא תבניות פרומפט** - העתקת פרומפטים לא עובדת; הבנת עקרונות כן +- **לא תחליף ליסודות** - אתם עדיין צריכים לדעת ארכיטקטורה, דפוסי עיצוב (design patterns) ועיצוב מערכות +- **לא למתחילים** - אם אין לכם ניסיון בפרודקשן, התחילו שם קודם + +## למי מתאים הקורס + +אתם קהל היעד אם אתם: + +- בעלי 3+ שנות ניסיון הנדסי מקצועי +- כבר ניסיתם עוזרי קידוד AI ונתקלתם בנקודות תסכול +- רוצים לנוע מהר יותר מבלי להקריב איכות קוד +- צריכים להבין בסיסי קוד, לדבג בעיות, או לתכנן פיצ'רים ביעילות רבה יותר +- אכפת לכם ממה ראוי לפרודקשן, ולא מדֶמוֹאים + +## איך להשתמש בקורס + +זהו מדריך ש**נועד לעיון** (reference manual), לא קורס מסורתי עם תרגילים. + +**גישה מומלצת:** קראו ברצף קודם, ואז חזרו לשיעורים ספציפיים לפי הצורך: + +1. מודול 1: יסודות - מודלים מנטליים וארכיטקטורה +2. מודול 2: מתודולוגיה - prompting, grounding, עיצוב תהליכי עבודה +3. מודול 3: טכניקות מעשיות - היכרות עם קוד חדש (Onboarding), תכנון, בדיקות, סקירה, דיבוג + +יישמו את הקונספטים על פרויקטים אמיתיים כשאתם נתקלים במצבים רלוונטיים. הערך מגיע מלהחזיק את המודלים המנטליים הנכונים כשאתם צריכים אותם. + +## מה תרוויחו + +לאחר השלמת הקורס, תוכלו: + +- **להתמצא בקוד לא מוכר** מהר פי 5-10 באמצעות מחקר אגנטי +- **לשכתב פיצ'רים מורכבים** באופן אמין עם אימות מבוסס-בדיקות +- **לדבג בעיות פרודקשן** על ידי האצלת ניתוח לוגים/מסד נתונים לסוכנים +- **לסקור קוד באופן שיטתי** עם סיוע AI תוך שמירה על שיקול דעת ביקורתי +- **לתכנן ולבצע פיצ'רים** עם האצלה מקבילית לתת-סוכנים + +## דרישות קדם + +- **ניסיון:** 3+ שנות הנדסת תוכנה מקצועית +- **כלים:** גישה לסוכן קידוד בטרמינל (Claude Code, OpenAI Codex, Copilot CLI, וכו'). אם עדיין לא בחרתם, Claude Code מומלץ בזמן כתיבה זו (plan mode, sub-agents, slash commands, CLAUDE.md היררכי, תמיכה בסרגל סטטוס). +- **מיינדסט (Mindset):** נכונות לשכוח "AI כחבר צוות" ולאמץ "AI ככלי" + +## על פיתוח הקורס הזה + +**הקורס הזה מיישם מה שהוא מלמד.** כל תכני הלימוד—מבנה תוכן, התקדמות שיעורים, דוגמאות קוד ותיעוד—פותחו באמצעות אותן טכניקות ותהליכי עבודה בסיוע AI שתלמדו כאן. + +כל מודול תוכנן, נחקר, נכתב ושופר דרך prompting שיטתי, מחקר אגנטי ואימות איטרטיבי. התהליך עקב אחר המתודולוגיה המדויקת המתוארת בקורס: פירוק עבודה למשימות מתאימות לסוכן, עיגון (grounding) בקונטקסט ארכיטקטוני, ואימות פלט באופן ביקורתי. + +**גרסת הפודקאסט של כל שיעור** נוצרה באמצעות Claude Code ו-Gemini API של Google—המרת תוכן טכני לדיאלוג שיחתי, ואז סינתזת אודיו רב-דוברים. הקולות ששומעים (אלכס וסם) נוצרו ב-AI, כמו גם התסריט שלהם. אפילו הכרה זו קיימת כי יישמנו את עקרון השקיפות בעבודה בסיוע AI. + +זה לא שיווק. זה אימות. אם הטכניקות האלה יכולות לייצר חומר הדרכה ברמת-פרודקשן על היישום שלהן עצמן, הן חזקות מספיק לבסיס הקוד שלכם. + +## האמת העמוקה יותר + +הקורס הזה לא על AI. הוא על הנדסה קפדנית עם כלים שבמקרה הם מערכות סטוכסטיות (אקראיות). + +סוכני AI הם **מגברים**—של הבהירות הארכיטקטונית שלכם, משמעת הבדיקות שלכם, דפוסי הקוד שלכם. לטוב או לרע, הם מגבירים מה שקיים. [מחקר מראה](https://leaddev.com/technical-direction/how-ai-generated-code-accelerates-technical-debt) שקוד AI מכיל 8x יותר כפילויות—לא בגלל שסוכנים יוצרים את זה, אלא בגלל שהם מגבירים דפוסים קיימים. + +**אתם מפסק הבטיחות (circuit breaker).** כל שורה שמתקבלת הופכת לקונטקסט (pattern context) לסוכנים עתידיים. שיקול הדעת ההנדסי שלכם—בסקירה, בארכיטקטורה, בעיצוב דפוסים—קובע לאיזה כיוון העקומה האקספוננציאלית מתכופפת. הכלים השתנו. היסודות לא. + +--- + +**מוכנים להתחיל?** התחילו עם [שיעור 1: הקסם מאחורי המודלים](/docs/fundamentals/lesson-1-how-llms-work). diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/methodology/lesson-3-high-level-methodology.md b/website/i18n/he/docusaurus-plugin-content-docs/current/methodology/lesson-3-high-level-methodology.md new file mode 100644 index 0000000..30c9a5d --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/methodology/lesson-3-high-level-methodology.md @@ -0,0 +1,256 @@ +--- +sidebar_position: 1 +sidebar_label: 'שיעור 3: תהליך עבודה בארבעה שלבים' +title: 'תהליך עבודה בארבעה שלבים' +--- + +import WorkflowCircle from '@site/src/components/VisualElements/WorkflowCircle'; +import PlanningStrategyComparison from '@site/src/components/VisualElements/PlanningStrategyComparison'; + +החלק הקשה ביותר בעבודה עם סוכני AI הוא לא ללמוד כלים חדשים או לכתוב פרומפטים טובים יותר. החלק הקשה הוא לשחרר. + +לאורך כל הקריירה שלכם, הערך שלכם היה בפרטים. בניתם את המוניטין שלכם על כתיבת קוד נקי, איתור באגים עדינים, הבנת כל שורה ששולחים לפרודקשן. הפנמתם שמהנדסים טובים מבינים את הקוד שלהם לעומק, לוקחים בעלות על המימוש שלהם, וגאים באומנות שלהם. + +סוכני AI מכריחים אתכם לפעול אחרת. אתם לא יכולים להבין כל שורה בסקייל שבו סוכנים מייצרים קוד. אתם לא יכולים לקרוא, לאמת ולהחזיק מנטלית 2,000 שורות של מימוש שנוצר באותו אופן שהחזקתם 200 שורות שכתבתם בעצמכם. אם תנסו, תשחקו או תהפכו לצוואר הבקבוק ששולל כל רווח פרודוקטיביות שהסוכן מספק. + +השינוי הנדרש הוא פסיכולוגי לא פחות מאשר מתודולוגי. אתם עוברים מ**אומן** ל**מפעיל**, מ**מיישם למתזמר**, מ**כתיבת קוד להנחיית מערכות**. הערך שלכם עולה בסטאק—מתחביר למבנה, מלולאות ללוגיקה, מפרטי אימפלמנטציה להחלטות ארכיטקטוניות. + +זה לא אומר שמפסיק להיות לכם אכפת מאיכות. זה אומר שאתם מבטיחים איכות אחרת. אתם מפסיקים לאמת נכונות על ידי קריאת כל שורה ומתחילים לאמת נכונות על ידי חשיבה שיטתית: האם זה מתאים לארכיטקטורה? האם זה עוקב אחר הדפוסים שלנו? האם זה מטפל בסיכונים שזיהיתי? האם ההתנהגות תואמת את המודל המנטלי שלי לאיך המערכת הזו צריכה לעבוד? + +המיקוד שלכם עובר מהקוד עצמו לשתי דאגות ברמה גבוהה יותר: **הקונטקסט (context) שאתם מספקים** (אילו דפוסים, אילוצים ודוגמאות מנחים את הסוכן) ו**הפרומפטים שאתם יוצרים** (אילו דרישות ארכיטקטוניות ונקודות אינטגרציה אתם מציינים). עשו את אלה נכון, ותוכלו בביטחון לשלוח אלפי שורות של קוד שנוצר. עשו אותם לא נכון, ותבזבזו זמן על תיקון, שכתוב והטלת ספק. + +השיעור הזה מלמד את תהליך העבודה השיטתי שהופך את שינוי המיינדסט הזה למעשי: Research -> Plan -> Execute -> Validate או מחקר -> תיכנון -> ביצוע -> אימות. ככה אתם שומרים שליטה ארכיטקטונית בזמן שמאצילים את המימוש, ככה אתם מבטיחים איכות בלי לקרוא כל תו, וזה כיצד אתם מרחיבים את ההשפעה שלכם מעבר למה שיכולתם להקליד באופן אישי. + +## מיינדסט המפעיל + +לפני שצוללים לתהליך העבודה, בואו נהיה מפורשים לגבי שינוי התפקיד. כשעובדים עם סוכני AI בסקייל, אתם לא עושים את אותה עבודה מהר יותר—אתם עושים עבודה אחרת. + +**תהליך עבודה של מפתח מסורתי:** + +- כתוב קוד +- טסטים לקוד +- ריוויו לקוד +- דבג קוד +- שכתב קוד + +**תהליך עבודה של מפעיל:** + +- מפה את המערכת (מודולים, גבולות, זרימת הנתונים) +- חקור דפוסים חוזרים ואילוצים קיימים +- תכנן את השינוי ברמה הארכיטקטונית +- הנחֶה את הסוכן עם קונטקסט מדויק +- אמת התנהגות מול המודל המנטלי שלך + +שימו לב מה חסר ברשימה השנייה: כתיבת קוד, קריאת כל שורה, דיבוג שגיאות תחביר. הסוכן מטפל באלה. העומס הקוגניטיבי שלכם עובר לחלוטין לחשיבה ברמת-מערכת—גבולות ואחריויות מודולים, קלטים ופלטים, ניהול state, והחוזים בין רכיבים. + +זה לא אומר שאתם לעולם לא קוראים קוד. זה אומר שאתם קוראים _באופן סלקטיבי_. כשסוכן מייצר 50 קבצים, אתם לא עושים להם ריוויו שורה-אחרי-שורה. אתם מבצעים ריוויו ברמת המערכת: האם אחריויות המודולים נכונות? האם קלטים ופלטים תואמים לציפיות? האם state מנוהל איפה שצריך? האם נקודות האינטגרציה עובדות? אתם בודקים נקודתית איפה שהמודל המנטלי שלכם אומר "זה מסוכן" או "זה מורכב מדי." + +הנה המציאות הלא-אינטואיטיבית: **קוד שנוצר על ידי AI עם prompting נכון לעתים קרובות קל יותר לקריאה מקוד שנכתב ביד**. LLMs עוקבים אחר דפוסים עם דיוק מכני על פני אלפי שורות. כשאתם מספקים דפוסים איכותיים ואילוצים ברורים, הם משכפלים אותם בצורה מושלמת. אתם לא מקריבים איכות על ידי האצלה לסוכנים—אתם משיגים עקביות מבנית בסקייל שאומנות ידנית לא יכולה להשיג. העבודה שלכם עוברת מהבטחה שכל פרט במימוש נכון להבטחה שהדפוסים עצמם נכונים. + +המודל המנטלי שלכם הוא התכנית שלכם. תהליך העבודה המוצג למטה הוא התהליך שלכם להבטחת איכות מבלי לטבוע בפרטים. + +**דבר אחד לא משתנה: אתם הבעלים של התוצאות.** מכונות לא יכולות להיות אחראיות—הן מבצעות הוראות. כל שורת קוד שנוצרה על ידי סוכן נשלחת תחת השם שלכם. זו אחריות המהנדס|ת, והיא נשארת שלכם ללא קשר לאיזה כלי כותב את המימוש. + +## תהליך העבודה בארבעה שלבים + +כל אינטראקציה משמעותית עם סוכן צריכה לעקוב אחר התבנית החזרתית של "מחקר -> תיכנון -> ביצוע -> אימות": + + +כל שלב מוביל לזה שאחריו במחזור רציף. לאחר האימות, חוזרים למחקר לפי הצורך כדי לדייק ולשפר. לכל שלב יש מטרה מובחנת, ודילוג על כל אחד מהם מעלה דרמטית את שיעור הכישלון שלכם. בואו נעבור על כל שלב בפירוט. + +## שלב 1: מחקר ועיגון (Grounding) + +לא הייתם מתחילים לקודד בבסיס קוד חדש בלי ללמוד קודם את הארכיטקטורה, הדפוסים והקונבנציות. וכנראה אתם משאירים את Google ו-Stack Overflow פתוחים בזמן שאתם עובדים. הסוכן שלכם צריך את אותו קונטקסט. + +זהו **עיגון (grounding)**—הגשר בין הידע והדפוסים הכלליים המוטבעים במודל לבין הקונטקסט של העולם האמיתי שהוא צריך לפעול בו. ללא עיגון, סוכנים הוזים (hallucinate) דפוסים, ממציאים APIs לא עקביים, ומפספסים את האימפלמנטציות הקיימות שלכם. + +### מחקר לתוך הקוד: [ChunkHound](https://chunkhound.github.io/) + +לקונטקסט של קוד, אתם צריכים חיפוש קוד סמנטי. [ChunkHound](https://chunkhound.github.io/) מבצע **מחקר קוד עמוק**—עונה על שאלות ארכיטקטוניות כמו "איך authentication מטופל?" או "מהו דפוס הטיפול בשגיאות?" במקום רק התאמת מילות מפתח. הוא מאחזר את הדפוסים והאימפלמנטציות הרלוונטיות מבסיס הקוד שלכם. + +### מחקר של דומיין: [ArguSeek](https://github.com/ArguSeek/arguseek) + +לידע דומיין, ArguSeek שולף מידע מ-Google ישירות ובצורה יעילה לתוך הקונטקסט שלכם. צריכים את ה-API docs האחרונים? Best practices מ-framework ספציפי? אלגוריתם קבור ב-PDF של מחקר בן 50 עמודים? +פתרון מאוסף המידע שחבוי בGitHub Issues? + +ArguSeek מאחזר את המידע הזה והופך אותו לזמין לסוכן שלכם—ללא מעבר ידני בין טאבים, העתקה-הדבקה, או שחזור קונטקסט. + +**נכנס לשני הכלים האלו בפירוט בשיעור 5.** לעת עתה, הבינו את העיקרון: עגנו את הסוכן שלכם גם בבסיס הקוד שלכם וגם בידע דומיין לפני תכנון שינויים. + +## שלב 2: תכנון (החלטה אסטרטגית) + +עם השלמת המחקר, עכשיו אתם מתכננים את השינוי. תכנון הוא לא גישה אחת—זו בחירה אסטרטגית המבוססת על השאלה האם אתם יודעים את הפתרון או צריכים לגלות אותו. +שתי גישות עיקריות הן + +**Exploration חקירה**: +מתאימה למצבים שבהם הפתרון לא מוגדר היטב — מצריכה עלות גבוהה יותר כדי להשיג תובנות טובות יותר דרך למידה וטיוב מתמשך. + +**Exact דיוק**: +מתאימה כאשר הפתרון כבר ידוע — אופטימלית לביצוע מהיר, אך מחייבת רמת ודאות מראש. + + +שתיהן גישות לגיטימיות — הבחירה תלויה ברמת הבהירות ובאי־הוודאות של הבעיה. + + +**תכנון בגישת החקירה:** השתמשו בזה כשמרחב הפתרון לא ברור או שאתם צריכים לגלות את הגישה הטובה ביותר. במקום להכתיב פתרון, מסגרו את מרחב הבעיה ונווטו את הסוכן לחקור את דפוסי בסיס הקוד שלכם (דרך ChunkHound) וידע דומיין (דרך ArguSeek), לחקור אלטרנטיבות, ולחזור איתכם דרך מחזורי reasoning-action. אתם מגלים את הגישה יחד. + +לגישה זו יש עלות וזמן השקעה גבוהים יותר, אבל היא מגלה פתרונות טובים יותר, תופסת בעיות ארכיטקטוניות מוקדם, ועוזרת לכם לבנות מודל מנטלי ברור יותר לפני התחייבות למימוש. + +```markdown +Our Express API has inconsistent error handling—some endpoints return raw errors, +others JSON, and stack traces leak to production. Use ChunkHound to search for +"error handling patterns" and "error response format" in our codebase. +Use ArguSeek to research Express error handling best practices and RFC 7807. +Analyze what you find, propose 2-3 standardization approaches with trade-offs, +and recommend one. +``` + +**תכנון מדויק:** השתמשו בזה כשאתם יודעים את הפתרון ויכולים לנסח אותו במדויק. היו הנחייתיים. הגדירו את המשימה בצורה ספציפית, ציינו נקודות אינטגרציה ודפוסים לעקוב אחריהם, ספקו אילוצים ודרישות מפורשים, רשמו מקרי קצה שזיהיתם, והגדירו קריטריוני קבלה ברורים. הסוכן יבצע לאורך נתיב קבוע מראש. + +גישה זו מהירה וחסכונית יותר, אבל דורשת בהירות מראש וודאות ארכיטקטונית—אם התוכנית שלכם שגויה או לא שלמה, הקוד שנוצר יהיה שגוי. השתמשו בתכנון מדויק כשכבר עשיתם את החשיבה הארכיטקטונית ופשוט צריכים מימוש אמין ועקבי. + +```markdown +Add rate limiting middleware to /api/\* using Redis. +Follow the pattern in src/middleware/auth.ts. +Authenticated users: 1000 req/hour, anonymous: 100 req/hour, admins unlimited. +Return 429 with Retry-After header. +Fail open if Redis is down - log warning but allow request through. +``` + +### בניית המודל המנטלי שלכם + +בזמן שאתם מתכננים, אתם משכללים את המודל המנטלי שלכם של המערכת. אתם לא משננים קוד—אתם מבינים יחסים: + +- איך authentication זורם דרך middleware +- היכן data validation קורה מול business logic +- איך שגיאות מדווחות לצד הלקוח +- היכן עלולים להופיע צווארי בקבוק בביצועים +- אילו גבולות אבטחה קיימים + +המודל המנטלי הזה הוא מה שמאפשר לכם לאמת קוד שנוצר במהירות. כשהסוכן מסיים, אתם לא קוראים כל שורה. אתם בודקים: "האם זה מתאים למודל המנטלי שלי של איך המערכת הזו עובדת?" אם כן, אז זה כנראה נכון. אם לא, אז או שהמודל שלכם שגוי (עדכנו אותו) או שהקוד שגוי (צרו מחדש). + +:::tip Plan Mode בכלים שונים + +**Claude Code:** לחצו `Shift+Tab` כדי להיכנס למצב תכנון ייעודי לעריכת דיון אסטרטגי לפני ביצוע. + +**כלים אחרים (Copilot CLI, Codex, Cursor, וכו'):** לרוב עוזרי הקידוד מבוססי הAI אין plan mode מובנה. השתמשו בתבנית הפרומפט הבסיסית הזו כדי לדמות אותו: + +
+לחץ להרחבה: תבנית פרומפט Plan Mode גנרית + +```markdown +# PLANNING MODE - READ ONLY + +You are in planning mode. DO NOT make any code edits or modifications. + +## Your Task + +Analyze the following request and create a comprehensive execution plan: + +[USER REQUEST HERE] + +## Instructions + +1. **Think deeply** about the problem before responding. Consider: + - What is the actual goal vs. stated request? + - What are potential edge cases or complications? + - What assumptions am I making? + +2. **Ask clarifying questions** if ANY of these are unclear: + - Requirements or expected behavior + - Scope boundaries (what's in/out of scope) + - Success criteria + - Technical constraints or preferences + - Existing architecture or patterns to follow + +3. **Draft a structured execution plan** with: + + **SCOPE** + - What will be changed + - What will NOT be changed + - Affected components/files + + **REQUIREMENTS** + - Functional requirements + - Non-functional requirements (performance, security, etc.) + - Dependencies or prerequisites + + **תוכנית המימוש** + - Step-by-step breakdown + - For each step, specify: + - File(s) to modify + - Type of change (add/modify/delete) + - Key logic or patterns to implement + + **VALIDATION** + - How to verify success + - Test cases or scenarios to cover + - Potential risks or rollback plan + +## Output Format + +- Use clear headers and bullet points +- Be specific about file paths and function names +- Flag any uncertainties or assumptions + +Ask your clarifying questions first, then provide the plan. +``` + +
+ +תבנית זו מספקת בסיס מוצק לכל משימת תכנון. ב-[שיעור 4: Prompting 101](./lesson-4-prompting-101.md), תלמדו את עקרונות הprompt engineering מאחורי המבנה הזה כדי שתוכלו לבנות פרומפטים לתכנון מותאמים משלכם במקום להסתמך על תבניות. + +::: + +## שלב 3: ביצוע (שני מצבי ביצוע) + +עם התוכנית שלמה, אתם מבצעים—אבל הדרך בה אתם מתקשרים עם הסוכן במהלך הביצוע משנה באופן יסודי את הפרודוקטיביות שלכם. יש שני מצבים: מצב מפוקח (צופים ומנווטים באופן פעיל) ומצב אוטונומי (שגר ושכח). רוב המהנדסים מתחילים במצב מפוקח כדי לבנות אמון, ואז עוברים בהדרגה למצב אוטונומי ככל שהם מפתחים מיומנויות עיגון ותכנון חזקות יותר. הנה האמת הלא-אינטואיטיבית: הרווח האמיתי בפרודוקטיביות הוא לא מסיום משימות בודדות מהר יותר. הרווח מגיע מעבודה על פרויקטים מרובים בו-זמנית ושמירה על פרקי עבודה ארוכים מאוד. שם ה"פרודוקטיביות פי 10" באמת מסתתרת. + +### מצב מפוקח ("Babysitting") + +במצב מפוקח, אתם מנטרים באופן פעיל את הסוכן בזמן שהוא עובד. אתם צופים בכל פעולה, סוקרים פלטי ביניים, מנווטים כשהוא סוטה, ומתערבים כשהוא עושה טעויות. זה נותן לכם שליטה ודיוק מקסימליים—אתם תופסים בעיות מיד ומנחים את הסוכן לפתרון הנכון בזמן אמת. העלות היא עצומה: התפוקה שלכם צונחת כי אתם חסומים בזמן שהסוכן עובד. אתם לא יכולים לעשות context-switch למשימה אחרת, אתם לא יכולים להתרחק, ואתם שורפים את המשאב היקר ביותר שלכם (תשומת לב) על פרטי המימוש. השתמשו במצב זה כשאתם לומדים איך סוכנים מתנהגים, כשעובדים על קוד רגיש-מבחינת-אבטחה או קריטי, או כשמתמודדים עם בעיות מורכבות שבהן אתם צריכים לבנות את המודל המנטלי שלכם בזמן שהסוכן חוקר. זו קרקע האימון שלכם לפיתוח האמון והאינטואיציה שבסופו של דבר מאפשרים לכם לשחרר. + +### מצב אוטונומי ("Autopilot" / "YOLO") + +במצב אוטונומי, אתם נותנים לסוכן משימה מוגדרת היטב מהתוכנית שלכם, נותנים לו לרוץ, ובודקים את התוצאות כשהוא מסיים. אתם לא צופים בו עובד. אתם עושים דברים אחרים—עובדים על פרויקט אחר, משתתפים בפגישה, מבשלים ארוחת ערב, יוצאים לסידורים. אתם אולי בודקים את הטלפון מדי פעם כדי לראות אם הוא תקוע או צריך הבהרה, אבל בעיקר אתם לא שם. כאן קורה השינוי האמיתי בפרודוקטיביות, וזה לא מה שרוב האנשים חושבים. כן, לפעמים הסוכן מסיים משימה מהר יותר ממה שהייתם עושים ידנית. אבל זו לא הנקודה. הנקודה היא **עבודה מקבילה** ו**פלט מתמשך**. יכולים להיות לכם שלושה סוכנים שרצים בו-זמנית על פרויקטים שונים. אתם יכולים לשמור על 8 שעות של פלט פרודוקטיבי בזמן שאתם מבלים רק שעתיים ליד המקלדת. אתם יכולים באמת לעשות מולטי-טאסקינג בפיתוח תוכנה בפעם הראשונה בהיסטוריה. גם אם יכולתם לקודד משהו ביד ב-20 דקות ולסוכן לוקח 30, מצב אוטונומי מנצח אם זה אומר שאתם מבשלים ארוחת ערב במקום להיות חסומים. מצב זה תלוי לחלוטין בעיגון מצוין (שלב 1) ותכנון (שלב 2). אם אתם מדלגים על השלבים האלה, הסוכן יסטה, יהזה (hallucinate), ויייצר זבל. אם אתם עושים אותם טוב, אתם יכולים לסמוך על הסוכן לבצע נכון ללא פיקוח. המטרה שלכם היא למקסם את הזמן בו האייג'נט רץ במצב אוטונומי—שם אתם הופכים לפרודוקטיביים באמת, לא רק מהירים מעט יותר. + +:::tip רווח הפרודוקטיביות האמיתי פי 10 +מצב אוטונומי לא מתהדר במהירות לכל משימה. הוא מתבסס על עבודה על משימות מרובות בו-זמנית בזמן שאתם חיים את החיים שלכם. מהנדסת בכירה שמריצה שלושה סוכנים אוטונומיים במקביל בזמן שהיא משתתפת בפגישות או מבשלת ארוחת ערב מדלְבֶרת יותר קוד ממהנדס שמשגיח על סוכן אחד שמבצע משימה אחת. עבודה במקביל היא שובר השוויון + האמיתי. +::: + +## שלב 4: אימות (החלטת האיטרציה) + +הסוכן סיים. הנה המציאות: **LLMs הם מכונות הסתברותיות שכמעט אף פעם לא מייצרות פלט מושלם ב-100% במעבר ראשון.** זה לא כישלון—זו התנהגות צפויה. + +מטרת האימות שלכם היא לא לוודא שלמות מוחלטת. המטרה היא לזהות במדויק מה שגוי או חסר, ואז לקבל החלטה קריטית: **לחזור עם תיקונים או לייצר מחדש מאפס?** + +זה יותר אמנות מאשר מדע, אבל זכרו: יצירת קוד היא זולה. אל תיקשרו לפלט. כללי אצבע: + +**עשו איטרציה נוספת כש**הפלט מיושר עם הציפיות שלכם אבל יש פערים—מקרי קצה חסרים, קצת tech debt, טיפול בשגיאות לא שלם, או חוסר עקביות בדפוסים. הבסיס נכון; זה רק צריך שיפור. + +**צרו מחדש (regenerate) כש**משהו בבסיס שגוי—הארכיטקטורה לא תואמת את המודל המנטלי שלכם, הסוכן הבין לא נכון את הדרישות, או הגישה עצמה פגומה. אל תנסו לתקן קוד שבור ביסודו. *תקנו את הקונטקסט* וצרו מחדש. + +**העיקרון המרכזי:** בדרך כלל קל יותר לתקן את הקונטקסט שלכם (הפרומפט, דוגמאות, אילוצים) מאשר לתקן את הקוד שנוצר. חשבו על עצמכם כמדבגים את הקלט שלכם, לא את הפלט. + +### הריצו את הקוד שלכם + +שום דבר לא מנצח להריץ בפועל את המימוש שלכם. היו המשתמש. בדקו את ה-happy path, נסו לשבור את זה, בדקו מקרי קצה. האם זה מטפל בשגיאות בצורה חלקה? האם הביצועים מקובלים? חמש דקות של בדיקה ידנית חושפות יותר משעה של קוד ריוויו. + +### השתמשו בסוכן עצמו + +הסוכן טוב יותר במציאת בעיות בקוד מאשר ביצירת קוד מושלם בפעם הראשונה. השתמשו בו כדי לסקור את העבודה שלו עצמו—נכסה את טכניקת הבדיקה העצמית הזו ב-[שיעור 9](../practical-techniques/lesson-9-reviewing-code.md). באופן דומה, בקשו מהסוכן ליצור בדיקות כמעקות בטיחות—מכוסה ב[שיעור 8](../practical-techniques/lesson-8-tests-as-guardrails.md). + +**בדיקות אוטומטיות עדיין חשובות:** הריצו את הבילד, הטסטים והלינטינג שלכם. אם אלה נכשלים זה סימן ברור שצריך איטרציה או יצירה מחדש. אם הם עוברים, ודאו ידנית שההתנהגות תואמת את התוכנית והמודל המנטלי שלכם. + +## סגירת הלולאה + +תהליך העבודה הזה הוא לא ליניארי—הוא איטרטיבי. אימות לעתים קרובות חושף פערים במחקר שלכם או פגמים בתוכנית שלכם. זה צפוי. הערך הוא לא בביצוע מושלם של כל שלב בפעם הראשונה; הערך מגיע מקיום פריימוורק שיטתי שתופס בעיות לפני שהן מצטברות. + +מיינדסט המפעיל עליו דיברנו בשיעור הפתיחה חשוב כאן: אתם לא מאמתים על ידי קריאת כל שורה. אתם מאמתים מול המודל המנטלי שלכם. האם הארכיטקטורה תואמת את התוכנית שלכם? האם הדפוסים מיושרים עם העיגון שלכם? האם ההתנהגות מספקת את הדרישות שלכם? אם כן, דלברו את זה. אם לא, זַהו האם הבעיה היא בקונטקסט (צרו מחדש) או רק שיפור (עשו איטרציה). + +תהליך העבודה הזה הוא ה-framework האסטרטגי. אבל אסטרטגיה לא אומרת כלום בלי ביצוע, וביצוע קורה דרך תקשורת. כל שלב—שאילתות מחקר, פרומפטי תכנון, הוראות ביצוע, סקירות אימות—תלוי בכמה מדויק אתם מתקשרים עם הסוכן. תהליך העבודה אומר לכם _מה_ לעשות. פרומפטינג אומר לכם _איך_ לעשות את זה ביעילות. + +--- + +**הבא:** [שיעור 4: Prompting 101](./lesson-4-prompting-101.md) - למדו את הטכניקות הספציפיות ליצירת פרומפטים יעילים שמחזירים תוצאות אמינות. diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/methodology/lesson-4-prompting-101.md b/website/i18n/he/docusaurus-plugin-content-docs/current/methodology/lesson-4-prompting-101.md new file mode 100644 index 0000000..ae74706 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/methodology/lesson-4-prompting-101.md @@ -0,0 +1,298 @@ +--- +sidebar_position: 2 +sidebar_label: 'שיעור 4: Prompting 101' +title: 'Prompting 101' +--- + +עוזרי קידוד AI כמו קופיילוט הם לא שותפי שיחה—הם מנועי השלמת דפוסים (pattern completion engines) מתוחכמים. הבנת ההבחנה היסודית הזו משנה איך אתם כותבים פרומפטים. + +חשבו על prompting כציור התחלה של תבנית או דפוס. המודל מנחש ומשלים מה שבא אחרי בהתבסס על דפוסים סטטיסטיים מנתוני האימון שלו. הפרומפט שלכם הוא לא בקשה; זו התחלת רצף שהמודל ישלים. + +## Prompting ברור מבוסס הוראות + +דלגו על נימוסים. מודלי AI לא צריכים "please" או "thank you"—טוקנים אלה מדללים את הכוונה שלכם מבלי להוסיף בהירות. + +### פקודות ציווי + +התחילו את הדפוס שאתם רוצים שיושלם. השתמשו בשפה ישירה ומוכוונת-פעולה. + +**לא יעיל:** + +``` +Could you help me write a function to validate email addresses? +Thanks in advance! +``` + +**יעיל:** + +``` +Write a TypeScript function that validates email addresses per RFC 5322. +Handle edge cases: +- Multiple @ symbols (invalid) +- Missing domain (invalid) +- Plus addressing (valid) + +Return { valid: boolean, reason?: string } +``` + +הפרומט היעיל מצייר התחלת דפוס מדויק: חתימת פונקציית TypeScript, כללי validation, return type. המודל משלים דפוס זה עם קוד מתאים. + +### הבנת השלמת דפוסים + +כשאתם כותבים "Write a TypeScript function that validates...", אתם לא שואלים שאלה. אתם מתחילים דפוס של קטע קוד. תפקיד המודל הוא לחזות מה באופן טבעי עוקב בהתבסס על דפוסים דומים בנתוני האימון שלו. + +**התחלת דפוס:** + +```typescript +// Write a secure authentication middleware for Express +function authMiddleware( +``` + +**המודל משלים:** + +```typescript + req: Request, + res: Response, + next: NextFunction +) { + // המימוש עוקב אחר הדפוס... +} +``` + +ככל שהתחלת הדפוס שלכם יותר ספציפית, מרחב ההשלמה יותר מוגבל. + +### פעלים חזקים וספציפיות + +פעלים חזקים מבססים דפוסים ברורים: + +| חלש | חזק | +| --------------------- | --------------------------------------------------------- | +| "תעשה פונקציה" | "כתוב פונקציה" | +| "תקן את הבאג" | "דבג את ה-null-pointer-exception ב-UserService.ts:47" | +| "עדכן את הדוקומנטציה" | "הוסף JSDoc לכל הפונקציות הexported ב-auth.ts" | +| "שפר ביצועים" | "שפר את השאילתה להשתמש בעמודות מאונדקסות" | + +**ספציפיות מצטברת ביעילות:** + +``` +Refactor UserRepository to use dependency injection: +1. Extract database connection to IDatabaseAdapter interface +2. Inject adapter via constructor +3. Update all 7 query methods to use adapter.execute() +4. Add unit tests mocking the adapter +``` + +זה מגדיר את דפוס הריפקטורינג לחלוטין. לא צריך ניחושים. + +### אילוצים כגארדריילס (Constraints as Guardrails) +גארדריילס הם מעקות הבטיחות ששומרים על המודל שלא יפול. +ללא אילוצים, המודל ממלא פערים עם הנחות. הגדירו גבולות במפורש. + +**ללא אילוצים:** + +``` +Add authentication to the API +``` + +איזה authentication? JWT? OAuth? טוקני Session? אילו endpoints? + +**עם אילוצים:** + +``` +Add JWT authentication to the API: +- Do NOT modify existing session middleware +- Use jsonwebtoken library +- Protect all /api/v1/* endpoints except /api/v1/auth/login +- תוקף טוקן: 24 שעות +- שמור user ID ו-role ב-payload +- החזר 401 לטוקנים חסרים/לא-תקפים +``` + +עכשיו מרחב ההשלמה מוגדר היטב. + +## הקצאת דמויות + + **השתמשו בפרסונות** (personas) או **דמויות** - כשטרמינולוגיה ספציפית לדומיין חשובה (אבטחה, ביצועים, נגישות) או כשאתם צריכים אוצר מילים עקבי לאורך משימות קשורות. **דלגו על דמויות כש**המשימה פשוטה והוספת קונטקסט של דמות מבזבזת טוקנים בלי להוסיף ערך. + +דמויות עובדות על ידי הטיית התפלגות אוצר מילים. כתיבת "You are a security engineer" מגדילה את ההסתברות שמונחים ספציפיים לאבטחה כמו "threat model", "attack surface", "least privilege" יופיעו בתגובה. מונחים אלה פועלים כשאילתות סמנטיות במהלך תשומת לב, ומאחזרים דפוסי אימון שונים ממונחים גנריים כמו "check for issues". ה-persona הוא קיצור דרך לאוצר מילים—במקום לרשום כל מונח אבטחה במפורש, אתם מפעילים את אשכול המילים המשויך ל-"security engineer". + +**דוגמה: פרומט גנרי** + +``` +Review this authentication code for issues. +``` + +תוצאה: עצות גנריות כמו "Check for proper validation and error handling" + +**דוגמה: פרומט ממוקד-אבטחה** + +``` +You are a security engineer conducting a code review. +Review this authentication code. Flag vulnerabilities: +SQL injection, XSS, auth bypasses, secrets in code. +Assume adversarial input and untrusted networks. +``` + +תוצאה: ניתוח אבטחה ממוקד שמזהה פגיעויות ספציפיות עם אסטרטגיות מיטיגציה + +השימוש בדמות לא הוסיף ידע—הוא שינה _איזה_ ידע מאוחזר על ידי הזזת אוצר מילים. עיקרון זה חל באופן אוניברסלי: אוצר מילים הוא ממשק הבקרה לאחזור סמנטי (semantic retrieval). אותו קונספט קובע איך אתם שולחים שאילתות לכלי חיפוש בסיס קוד (ChunkHound), לסוכני מחקר אינטרנט (ArguSeek), למסדי נתונים וקטוריים, או איך אתם מנחים תת-סוכנים. "Authentication middleware patterns" מאחזר chunks של קוד שונים מ-"login code". "Rate limiting algorithms" מוצא מחקרים שונים מ-"slow down requests". בחרו מונחים שמאחזרים את הדפוסים שאתם צריכים. (ראו [שיעור 5: עיגון Grounding](./lesson-5-grounding.md) לכלי חיפוש סמנטי.) + +## Chain-of-Thought: סלילת נתיב ברור + +כשמשימות דורשות צעדים מרובים, לעתים קרובות אתם צריכים שליטה על נתיב הביצוע. Chain-of-Thought (CoT), חוט או שרשרת מחשבה, מספק זאת על ידי הגדרה מפורשת של כל צעד שהמודל חייב לעקוב—כמו לתת הוראות נסיעה צעד-אחרי-צעד במקום רק את היעד. אתם שולטים במסלול, מבטיחים דיוק בכל שלב, והופכים את תהליך החשיבה לשקוף. + +### הוראות צעד-אחר-צעד מפורשות + +CoT מגדיר כל צעד שהמודל חייב לבצע ברצף. אתם לא מבקשים נימוקים—אתם מכתיבים את הנתיב. + +**ללא CoT:** + +``` +Debug the failing test in UserService.test.ts +``` + +**עם CoT:** + +``` +Debug the failing test in UserService.test.ts: + +1. Read the test file, identify which test is failing +2. Analyze test assertion: expected vs actual values +3. Trace code path through UserService to find the bug +4. Explain root cause +5. Propose fix + +Provide your conclusions with evidence. +``` + +**למה CoT נותן לכם שליטה:** + +- **אתם מכתיבים את הרצף**—המודל לא יכול לדלג על צעדים או לקחת קיצורים. כל צעד חייב להסתיים לפני שהבא מתחיל. +- **אימות בכל שלב**—שגיאות עולות מוקדם במקום להצטבר על פני צעדים מרובים. +- **ביצוע שקוף**—אתם רואים בדיוק מה קרה בכל צעד, מה שהופך דיבוג לפשוט. +- **חיוני לפעולות מורכבות**—מודלים מודרניים מטפלים במשימות פשוטות ללא CoT, אבל פעולות מרובות-שלבים (5+ צעדים) דורשות הנחיה מפורשת לדיוק. + +CoT חזק במיוחד לביצוע עבודות QA שבהן אתם צריכים ביצוע שיטתי. ראו [שיעור 8: בדיקות כמעקות בטיחות](../practical-techniques/lesson-8-tests-as-guardrails.md) לדוגמאות פרודקשן של שימוש בבדיקות כגארדריילס בעבודה של של סוכנים. + +## יישום מבנה לפרומפטים + +מבנה מארגן מידע ומכוון את תשומת הלב של המודל. Markdown, JSON ו-XML יעילים במיוחד לארגון מידע כי הם פורמטים צפופי-מידע שמיוצגים היטב בנתוני האימון של המודלים. + +### צפיפות מידע חשובה + +לפורמטים שונים יש צפיפות מידע שונה—כמה משמעות מועברת לכל טוקן. Markdown צפוף מאוד במידע: כותרות, רשימות וקטעי קוד מספקים מבנה סמנטי ברור עם overhead מינימלי. + +זה חשוב ליעילות טוקנים ולעיגון (grounding). פרומפטים מובנים היטב עוזרים למודל לנתח כוונה ולהגיב עם מבנה מתאים. + +### Markdown לארגון היררכי + +```markdown +# Task: Implement OAuth 2.0 Client Credentials Flow + +## Requirements + +- Support multiple authorization servers (configurable) +- שמור טוקנים במטמון עד פקיעה (Redis) +- נסה שוב אוטומטית על 401 עם רענון טוקן +- Expose as Express middleware + +## שלבי המימוש + +1. Create OAuthClient class with getToken() method +2. Implement caching של טוקנים with TTL +3. Add retry logic with exponential backoff +4. Write middleware injecting טוקן into req.context + +## Testing + +- Unit tests for OAuthClient +- Integration tests against mock OAuth server +- Error cases: network failure, invalid credentials, טוקנים שפג תוקפם + +## Constraints + +- Use axios for HTTP requests +- Use ioredis for caching +- No global state—client must be instantiated +``` + +המבנה הופך דרישות לקלות לסריקה ומושך תשומת לב לסעיפים נפרדים: מה לבנות, איך לבנות, איך לבדוק, וממה להימנע. + +## דברים להימנע מהם + +למודלי AI יש מצבי כשל צפויים. הבנת מצבים אלה עוזרת לכם לכתוב פרומפטים באופן דפנסיבי. + +### בעיות שלילה + +LLMs מתקשים עם שלילה כי מנגנוני תשומת לב מתייחסים ל-"NOT" כסתם עוד טוקן שמתחרה על משקל. כש-"NOT" מקבל תשומת לב נמוכה במהלך עיבוד, המודל מתמקד בקונספטים שהוזכרו ("passwords", "plain text") במקום בשלילה שלהם—תופעה שנקראת "affirmation bias" (הטיית אישור). יצירת טוקנים של המודל באופן יסודי נוטה לבחירה חיובית (מה לכלול) ולא להחרגה שלילית (ממה להימנע). + +**מסוכן:** + +``` +Write a user registration endpoint. +Do NOT store passwords in plain text. +``` + +המודל עלול לפספס את ה"NOT" ולייצר אחסון סיסמאות בטקסט רגיל כי תשומת הלב מתמקדת ב-"passwords" + "plain text" תוך התעלמות מהשלילה. + +**עדיף—שלילה ואז ההיפך החיובי:** + +``` +Write a user registration endpoint. + +Password handling: +Do NOT store passwords in plain text. +Instead, always store passwords as hashed values. +Use bcrypt with 10 salt rounds before storing. +``` + +דפוס זה עובד על ידי: + +1. **שלילה מפורשת קודם**: "Do NOT store passwords in plain text" מציין בבירור את האילוץ +2. **ההיפך החיובי מיד אחרי**: "Instead, always store passwords as hashed values" מספק את ה-NOT הלוגי בצורה חיובית +3. **פרטי אימפלמנטציה**: הוראות קונקרטיות (bcrypt, salt rounds) מחזקות את הדפוס הנכון + +### מגבלות מתמטיקה + +LLMs הם מנבאי טקסט הסתברותיים, לא מחשבונים. הם גרועים בחשבון. + +**אל תסתמכו על LLMs למתמטיקה:** + +``` +Calculate the optimal cache size for 1M users with 2KB average data per user, +assuming 80% hit rate and 4GB available memory. +``` + +המודל ייצר מספרים שנשמעים סבירים שעלולים להיות לחלוטין שגויים. + +**במקום זאת, בקשו מהמודל לכתוב קוד:** + +``` +Write a Python function that calculates optimal cache size. + +Inputs: +- user_count: number of users +- avg_data_per_user_kb: average data size in KB +- hit_rate: cache hit rate (0.0 to 1.0) +- available_memory_gb: available memory in GB + +Return optimal cache size in MB with reasoning. + +Include unit tests validating the calculation. +``` + +## נקודות מפתח + +- **Prompting הוא השלמת דפוסים, לא שיחה**—ציירו את התחלת הדפוס שאתם רוצים שהמודל ישלים +- **דלגו על נימוסים**—"please" ו-"thank you" מדללים את המידע בלי להוסיף ערך +- **שמויות משפיעות על אוצר מילים, לא על יכולת**—השתמשו בהן להטות לכיוון מונחים ספציפיים לדומיין שמשפרים עיגון +- **CoT סולל נתיב ברור**—השתמשו בהוראות צעד-אחר-צעד מפורשות למשימות מורכבות כשאתם צריכים שליטה ודיוק; יעיל במיוחד לעבודה של QA (ראו [שיעור 8](../practical-techniques/lesson-8-tests-as-guardrails.md)) +- **מבנה מכוון את תשומת הלב**—Markdown, JSON, XML הם פורמטים צפופי-מידע ומיוצגים היטב בנתוני אימון של המודלים +- **הימנעו משלילה**—נסחו מה אתם רוצים במפורש; קל לפספס שלילה +- **LLMs לא יכולים לעשות מתמטיקה**—בקשו מהם לכתוב קוד שעושה מתמטיקה במקום + +Prompting יעיל הוא הנדסת דיוק. אתם לא מנהלים שיחה—אתם מאתחלים מנוע השלמת דפוסים. היו ספציפיים, היו מובנים, היו מפורשים. + +--- + +**הבא:** [שיעור 5: עיגון Grounding](./lesson-5-grounding.md) diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/methodology/lesson-5-grounding.md b/website/i18n/he/docusaurus-plugin-content-docs/current/methodology/lesson-5-grounding.md new file mode 100644 index 0000000..4224391 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/methodology/lesson-5-grounding.md @@ -0,0 +1,381 @@ +--- +sidebar_position: 3 +sidebar_label: 'שיעור 5: עיגון - Grounding' +title: 'Grounding: עיגון סוכנים למציאות' +--- + +import UShapeAttentionCurve from '@site/src/components/VisualElements/UShapeAttentionCurve'; +import GroundingComparison from '@site/src/components/VisualElements/GroundingComparison'; + +אתם מבקשים מהסוכן שלכם לתקן באג באותנטיקציה. הוא מייצר בביטחון פתרון באמצעות JWT verification patterns... שלא קיימים בבסיס הקוד שלכם. אתם משתמשים ב-sessions, לא ב-JWTs. הסוכן פשוט המציא מימוש סביר המבוסס על תבניות נפוצות מהחומר עליו הוא אומן. + +הנה הבעיה הבסיסית: **הסוכן לא יודע שבסיס הקוד שלך קיים.** הוא לא מכיר את הארכיטקטורה שלך, את דפוסי הפיתוח שלך, או את המגבלות שלך. כפי שכוסה ב[שיעור 2 על הסוכנים](/docs/fundamentals/lesson-2-how-agents-work), חלון הקטנטקסט הוא העולם כולו של הסוכן—כל השאר לא קיים. ללא grounding, או "⚓עיגון" מפורש אל הקוד האמיתי שלך ואל התיעוד הנוכחי, סוכנים מייצרים פתרונות סבירים סטטיסטית שעשויים להיות שגויים לחלוטין עבור המערכת שלך. + +**עיגון הוא האופן שבו מזריקים מציאות לחלון הקונטקסט.** אתם משיגים מידע חיצוני רלוונטי — דפוסים שחוזרים בקוד הבסיס שלכם, תיעוד עדכני, best practices—ומזינים אותו לסוכן לפני הביצוע. שיעור זה מכסה את טכניקות ההנדסה שמעגנות סוכנים למערכת האמיתית שלכם במקום להיפותזות. +המילה grounding באנגלית מתורגמת לעיתים כ"קרקוע" או "הארקה" ואף "ביסוס". הכוונה היא לחבר את הסוכן לקרקע המציאות. + + + + + + + +**ללא Grounding:** + +- עובד מ-patterns אימון גנריים שהוקפאו בינואר 2025 +- מנחש את הארכיטקטורה והספריות שלך +- יוצר hallucinations של מימושים שנראים סבירים אבל לא תואמים את ה-codebase שלך +- מפספס פגיעויות אבטחה עדכניות ושינויי API +- פתרונות שגויים בביטחון הבנויים מ-patterns סטטיסטיים + +**עם Grounding:** + +- עובד מה-codebase האמיתי שלך (ChunkHound משיג קוד אמיתי) +- משתמש בתיעוד עדכני (ArguSeek מביא מסמכי API עדכניים) +- מודע ל-security advisories עדכניות ו-breaking changes +- עוקב אחר ה-patterns והארכיטקטורה הקיימים שלך +- פתרונות שמשתלבים בצורה נקייה במערכת שלך + + +:::info גילוי נאות +גם [ChunkHound](https://chunkhound.github.io/) וגם [ArguSeek](https://github.com/ArguSeek/arguseek) הם פרויקטים בקוד פתוח שנבנו על ידי מחבר הקורס. הם מופיעים לאורך כל הקורס כי הם מיישמים בדיוק את הרעיונות שהקורס מלמד — בידוד, sub-agents, חיפוש סמנטי, ניהול קונטקסט. + +העקרונות חלים באופן אוניברסלי. חלופות לכלים האלו קיימות ומתועדות. השתמשו במה שמתאים לצורת העבודה שלכם. המתודולוגיה נשארת עקבית ללא קשר לכלים. +::: + +## Grounding: עיגון סוכנים אל המציאות + +**עיגון הוא האופן שבו אתה מזריק מציאות לחלון הקונטקסט.** אתם משיגים מידע חיצוני רלוונטי — דפוסים שחוזרים בקוד הבסיס שלכם, תיעוד עדכני, best practices—ומזינים אותו לסוכן לפני הביצוע. שיעור זה מכסה את טכניקות ההנדסה שמעגנות סוכנים למערכת האמיתית שלכם במקום להיפותזות. + +## בעיית החיפוש הסוכני-Discovery: + +כשנותנים פרומפט כמו "תקן את באג האימות", הסוכן מתחיל עם אפס ידע על ה-codebase. הוא לא יודע איפה נמצא קוד האימות, באילו ספריות משתמשים פה, או איך הקוד בנוי. + +**חיפוש אייגנטי הוא האופן שבו הסוכן מגלה את ה-codebase שלך באופן אוטונומי.** הסוכן קורא לכלים בעצמו—Glob מוצא קבצים התואמים לGrep ספציפי, מחפש מילות מפתח. Read בוחן קוד. הסוכן מחליט מה לחפש, מפרש תוצאות, וקובע את הצעדים הבאים. + +**דוגמה לפלואו:** + +``` +Task: "Fix JWT expiration validation" + +Agent: I'll search for JWT-related code +← Grep("JWT", "**/*.ts") + +Tool result: Found in: + - src/auth/jwt.ts:45: export function verifyToken(טוקן: string) + - src/middleware/auth.ts:12: import { verifyToken } from '../auth/jwt' + - tests/auth.test.ts:8: describe('JWT verification') + +Agent: Let me read the verification logic +← Read("src/auth/jwt.ts") + +Tool result: [verification logic shows expiration check missing] + +Agent: Found it - the verifyToken function doesn't check exp claim +``` + +בבסיסי קוד קטנים (פחות מ-10,000 שורות), זה עובד יפה. שניים או שלושה חיפושים מחזירים 5-10 קבצים. בסך הכל 15,000 טוקנים. הסוכן קורא אותם, בונה מודל מנטלי, ופותר את הבעיה. הקונטקסט נשאר נקי. + +**בסקייל גדול, חיפוש אייגנטי קורס.** חיפוש של "authentication" בפרויקט של 100,000 שורות יחזיר 80+ קבצים. קריאתם צורכת מעל 60,000 טוקנים לפני שהסוכן מסיים את ה-discovery—חצי מחלון הקונטקסט האפקטיבי נעלם. מידע קריטי שסיפקת מראש נדחף לאמצע, שם הוא נעלם מעיני הסוכן, ככל שתוצאות החיפוש מציפות אותו. + +## בעיית הסקֶייל: מגבלות חלון הקונטקסט + +Claude Sonnet 4.5 מפרסם תמיכה ב-200,000 טוקנים. והמציאות? טווח תשומת הלב האמין משתרע על 60,000-120,000 טוקנים (30-60% מהמפורסם)—**אשליית חלון הקונטקסט**. + + + +**U-shaped attention הוא האופן שבו transformers באמת עובדים.** ההתחלה והסוף של הקונטקסט שלך מקבלים תשומת לב חזקה. האמצע מקבל התייחסות שטחית או מדולג עליו לחלוטין. זה לא באג—זו ארכיטקטורת transformer תחת אילוצים ריאליסטיים. + +**קונטקסט מלא מוביל לאיבוד שליטה.** הגבולות והאילוצים הקריטיים שפרטת נדחפים לאמצע—לאזור שהמודל מתעלם ממנו ולעולם לא רואה. + +**חיפוש אייגנטי מעצים את הבעיה הזו כשהסקייל גדל.** שלושה חיפושי Grep מחזירים 18,000 טוקנים. קריאת חמישה קבצים מוסיפה עוד 22,000 טוקנים. אתם ב-40,000 טוקנים והסוכן עוד לא סיים את ה-discovery. איפה ההגבלות והדרישות הראשוניים שלך? קבורים באמצע, והמודל מתעלם מהם. + +### פתרון 1: חיפוש סמנטי + +**חיפוש סמנטי מאפשר לך לחפש לפי משמעות, לא לפי מילות מפתח.** חיפוש כמו "authentication middleware that validates user credentials" ימצא קוד רלוונטי גם אם הוא לא מזכיר את המונחים המדויקים האלה. + +:::tip איך חיפוש סמנטי עובד + +**Vector embeddings:** הקוד שלך מומר לוקטורים רב-ממדיים (768-1536 ממדים) שלוכדים משמעות סמנטית. קונספטים דומים מתקבצים יחד ב-vector space. + +**Similarity matching:** cosine similarity מוצא צ'אנקים רלוונטיים. "auth middleware", "login verification", ו-"JWT validation" ממופים ל-וקטורים קרובים—המודל מבין שהם קשורים סמנטית למרות שהם משתמשים במילים שונות. + +**Infrastructure:** vector databases (ChromaDB, pgvector, Qdrant) בתוספת אלגוריתמי approximate nearest neighbor (ANN) מאפשרים חיפוש מהיר. rerankers משפרים תוצאות. אתם קוראים ל-`()code_research`, לא ל-APIs ברמה נמוכה. + +**הבדל עקרוני:** embedding models עם vector similarity מחפשים לפי קונספט, לא טקסט. זה שונה מהותית מהשוואת מילות מפתח. +::: + +**זמינות תלויה בכלי שלך:** + +**עוזרים מבוססי IDE** כמו Cursor, Windsurf, Cline בדרך כלל כוללים חיפוש סמנטי מובנה. העורך מטפל ב-indexing ו-vector search באופן אוטומטי. + +**סוכני CLI** (Claude Code, Copilot CLI, Codex) צריכים שרתי MCP כדי להוסיף חיפוש סמנטי. [Model Context Protocol (MCP)](https://modelcontextprotocol.io) מאפשר לך להרחיב סוכני CLI עם tools כמו חיפוש סמנטי, web research, וגישה ל-databases. + +**שרתי MCP לחיפוש קוד סמנטי:** + +- [Claude Context](https://github.com/zilliztech/claude-context) חיפוש סמנטי מבוסס RAG +- [Serena](https://github.com/oraios/serena) - גשר מבוסס LSP (קל יותר, מוגבל ל-LSP symbol scope) +- [ChunkHound](https://chunkhound.github.io) - תהליך מובנה מובנה עם חיפוש היברידי + +ברגע שיש לך חיפוש סמנטי (מובנה או דרך MCP), הסוכן שלך משלב אותו עם Grep ל-hybrid discovery: conceptual search למציאת האזור הנכון, keyword matching מדויק לאיתור מימושים מדויקים. + +**חיפוש סמנטי מרחיב את הסקייל שלך למעלה מ-100,000 שורות קוד.** אפשר למצוא קוד רלוונטי מהר יותר עם פחות תוצאות שגויות. + +**אבל עדיין יש מגבלה:** חיפוש סמנטי עדיין ממלא את הקונטקסט של הסוכן הראשי, הסוכן המתזמר (orchestrator). עשרה צ'אנקים סמנטים (15,000 טוקנים) בתוספת קריאת קבצים (25,000 טוקנים) בתוספת חקירת דפוסים רלוונטים (10,000 טוקנים) אומר שהגעת ל-50,000 טוקנים - חצי מהקונטקסט האפקטיבי שלך נצרך עוד לפני שהסוכן בכלל מתחיל לחשוב על המשימה האמיתית. + +## פתרון 2: Sub-Agents לבידוד קונטקסט + +**תת-סוכן** הוא סוכן שמופעל על ידי סוכן אחר—כמו קריאה לפונקציה, אבל לסוכנים. הסוכן המתזמר כותב פרומפט (פרמטרי הפונקציה) המתאר את משימת המחקר: "מצא את כל קוד אימות ה-JWT והסבר את המימוש הנוכחי." התת-סוכן מבצע בקונטקסט מבודד משלו, מריץ חיפושים וקורא קבצים. עם השלמה, הוא מחזיר סיכום תמציתי (הערך המוחזר מהפונקציה): "מימוש JWT נמצא ב-src/auth/jwt.ts משתמש ב-Passport.js..." סיכום זה נטען לקונטקסט של המתזמר — בדרך כלל 2,000-5,000 טוקנים לעומת 50,000-150,000 הטוקנים שתת-הסוכן עיבד פנימית. + +**איך זה עובד בפועל:** + +``` +Your orchestrator (clean context with your task and constraints): + "I need to understand how JWT authentication is implemented. + Delegate research to code sub-agent." + +Code sub-agent spawns (fresh isolated context): + - Runs semantic search: "JWT authentication patterns" → 12,000 tokens of results + - Reads 3 files: src/auth/jwt.ts, middleware/auth.ts, config/jwt.ts → 18,000 tokens + - Searches related patterns: "token validation" → 7,000 tokens + - Total consumed in sub-agent context: 37,000 tokens + +Sub-agent synthesizes and returns to orchestrator: + "JWT authentication implementation found: + - Location: src/auth/jwt.ts:45-67 + - Library: Passport.js with JWT strategy + - Pattern: Express middleware → Passport strategy → token validation + - Algorithm: RS256 with public key verification + - Current issue: Missing expiration check in verifyToken()" + +Your orchestrator receives: 180 tokens instead of 37,000 +``` + +**הפשרה היא עלות טוקנים, לא דיוק.** משלמים על עיבוד טוקנים בשני הקונטקסטים, מגדילים את העלות הכוללת באופן משמעותי, אבל ה-orchestrator שלך שומר על קונטקסט נקי לאורך כל הדרך. זה אומר דיוק באיטרציה הראשונה, שבדרך כלל חוסך טוקנים בהשוואה למחזורי תיקון מרובים הנובעים מקונטקסט עמוס. + +**ללא תת-סוכנים, עדיין אפשר להסתדר.** נצלו את ה-U-curve: שימו אילוצים קריטיים בהתחלה, שימו משימות בסוף. מידע תומך הולך באמצע—שם המודל יכול לסרוק אותו במידת הצורך, אבל הוא עדיין נגיש. + +### שתי ארכיטקטורות תת-סוכן + +**Autonomous architecture:** נותנים לתת-סוכן כלים (Grep, Read, Glob) ו-system prompt שמגדירה את אסטרטגיית המחקר שלו. הסוכן מחליט באופן אוטונומי מה לחפש, מה לקרוא, ואיך לסנתז. + +דוגמה: Explore agent של Claude Code. אתה שולח לו שאלת מחקר, הוא בוחר באופן אוטונומי כלים ורצפים, ואז מסנתז תוצאות. פשוט יותר לבנות, זול יותר להפעיל, גמיש למשימות מחקר שונות. + +**Structured architecture:** את בונה מישור בקרה דטרמיניסטי שמגדיר את אלגוריתם החיפוש המדויק (breadth-first traversal, hybrid semantic + symbol search). ה-LLM מקבל החלטות טקטיות בתוך המבנה שלך ("האם להרחיב את הסימבול הזה?" "האם הצ'אנק הזה רלוונטי?"). + +דוגמה: ChunkHound משתמש ב-multi-hop pipeline קבוע שבו המערכת שולטת באסטרטגיית המעבר וה-LLM מדרג שייכות בנקודות החלטה. מורכב יותר לבנות, עלות גבוהה יותר, אבל שומר על אחידות רמת התוצאות בסקייל קיצוני. + +**ה-architectural trade-off:** סוכנים אוטונומיים עובדים היטב אבל מתדרדרים בבסיסי קוד גדולים שבהם הם עושים בחירות חיפוש לא אופטימליות. סוכנים מובנים מתרחבים באופן אמין אבל עולים יותר לבנות ולהפעיל. + + + +**השוואת ארכיטקטורות תת-סוכן - שתי הגישות תקפות בהתאם לסקייל של ה-codebase. השתמש ב-styling ניטרלי.** + +| גישה A (Autonomous) | גישה B (Structured) | +| ------------------------------------------ | --------------------------------------------- | +| סוכן מחליט search strategy באופן אוטונומי | Control plane דטרמיניסטי מגדיר algorithm | +| פשוט יותר לבנות ולתחזק | מתרחב באופן אמין למיליוני שורות קוד | +| עובד היטב למשימות research מגוונות | LLM מקבל החלטות טקטיות בתוך structure | +| מתדרדר ב-codebases גדולים מאוד | עלות ומורכבות גבוהות יותר לבנייה | + + + +### זמינות תת-סוכנים + +**זמינות תלויה בפלטפורמת הסוכן שלך:** + +**Claude Code** כולל את סוכן הExplore המובנה—תת-סוכן אוטונומי למחקר לתוך הקוד שעובד ישר מהקופסה. + +**סוכני CLI אחרים** (Copilot CLI, Aider, וכו') ו**לרוב עוזרי ה-IDE** אין פונקציונליות תת-סוכן מובנית למחקר בקוד. לפלטפורמות אלה, [ChunkHound](https://chunkhound.github.io) דרך MCP היא כרגע האפשרות היחידה להוסיף יכולות מחקר לתוך הקוד מבוססות תת-סוכנים. + +**עוזרי IDE** (Cursor, Windsurf, Cline) בדרך כלל לא חושפים ארכיטקטורות תת-סוכן ישירות, אם כי לחלקם עשויות להיות יכולות פנימיות למחקר לתוך הקוד. כדאי לבדוק את התיעוד של ה-IDE שלך כדי לראות מה זמין. + +## Code Grounding: בחירת כלים לפי סקייל + +גודל +בסיס הקוד שלך קובע איזו גישת עיגון עובדת. כך לבחור: + +### טבלת עזר לבחירת הכלי המתאים + +| סקייל | כלים מומלצים | נקודת השבירה | למה | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **< 10k שורות קוד** | חיפוש אייגנטי (Grep, Read, Glob) | N/A - עובד באופן אמין בסקייל זה | מהיר, זול, כיסוי מספיק. ללא indexing overhead. | +| **10-100K שורות קוד** | **Claude Code:** סוכן Explore
**סוכני CLI אחרים:** ChunkHound מחקר לתוך הקוד (MCP)
**חלופה:** חיפוש סמנטי (Claude Context, Serena דרך MCP) | חיפושים המחזירים 50+ קבצים מתחילים להציף את הקונטקסט | תת-סוכנים מבודדים מחקר בקונטקסטים נפרדים. חיפוש סמנטי מרחיב חיפוש אייגנטי עם שאילתות על משמעות. ChunkHound היא אפשרות התת-סוכן MCP היחידה. | +| **100K+ שורות קוד** | ChunkHound code research מחקר לתוך הקוד (תת-סוכן מובנה) | חיפוש אייגנטי מפספס הקשרים ארכיטקטונים בין מודולים | חיוני ב-1M+ שורות קוד. הגישה היחידה עם progressive aggregation על פני בסיסי קוד גדולים. | + +:::tip מדידת שורות קוד + +השתמש|י ב-[`cloc`](https://github.com/AlDanial/cloc) למדידת גודל בסיס הקוד שלך: ` . cloc` מחזיר פירוט לפי שפה. התמקדו בעמודת "Code" לספירות שורות קוד מדויקות. +::: + +### Deep Dive: ארכיטקטורת ChunkHound + +[ChunkHound](https://chunkhound.github.io)—structured pipeline למחקר לתוך קוד בסקייל גדול. + +**מיצוב עיקרי:** ChunkHound הוא כרגע התת-סוכן המבוסס-MCP היחיד למחקר לתוך הקוד. לסוכני CLI מלבד Claude Code (שיש לו Explore מובנה), ChunkHound דרך MCP היא הדרך היחידה להוסיף פונקציונליות תת-סוכן. + +**ה-Pipeline:** + +1. **Multi-hop BFS traversal** דרך semantic relationships +2. **Hybrid semantic + symbol search**—conceptual discovery, ואז exhaustive regex לכל סימבול +3. **Map-reduce synthesis**—architectural relationships עם תוצאות של `שם-קובץ:שורה` + +**הנחיות לסקייל:** + +- **מתחת ל-10,000 שורות קוד:** סוכן Explore זול יותר (ChunkHound מוסיף עלות ו-latency של 1-2x) +- **בערך 10,000 שורות קוד:** Inflection point—ChunkHound הופך בעל ערך אם אתה שוב ושוב מחבר components לאורך בסיס הקוד +- **100,000+ שורות קוד:** Highly valuable—סוכנים אוטונומיים מתחילים להראות תוצאות לא שלמות +- **1,000,000+ שורות קוד:** Essential—הגישה היחידה עם progressive aggregation + +**שימוש:** `Research our authentication middleware architecture` + +**מחזיר:** מיקומי components, architectural patterns, relationships בין modules עם ציטוטים. + +**שימושי עבור:** הכנה למימוש feature, complex debugging, refactoring analysis, code archaeology, כאשר Explore מחזיר תוצאות לא שלמות. + +**Alternatives:** [Claude Context](https://github.com/zilliztech/claude-context)—semantic search via RAG. [Serena](https://github.com/oraios/serena)—LSP bridge instead of full semantic search (faster, lighter, but limited to language server symbol scope). Neither implements structured multi-hop traversal. + +## Web Grounding: אותו רעיון, מקורות שונים + +אנחנו צריכים יותר מרק את בסיס הקוד שלנו. אנחנו צריכים ידע עדכני לגבי האקוסיסטם שלנו:: API docs, best practices, security advisories, research. + +**עיגון באינטרנט סובל מאותה התנהגות כמו עיגון לקוד:** כלים פשוטים עובדים בהתחלה, ואז פוגעים במגבלות הקונטקסט, ואז צריכים פתרונות מתוחכמים. + +### חיפוש אינטרנט מובנה + +רוב העוזרים (Claude Code, Copilot, Cursor) כוללים חיפוש אינטרנט בסיסי. זה עובד לשאילתות פשוטות. + +**המגבלה:** אותה בעיית זיהום קונטקסט. כל חיפוש צורך 8,000-15,000 טוקנים. כל עמוד שמתווסף מוסיף 3,000-10,000 טוקנים. דיאגרמת ה-U עדיין חלה— אם הקונטקסט שלך מתמלא עם תוצאות חיפוש האילוצים וההנחיות המקוריים שלך נדחפים לאמצע שהמודל מתעלם ממנו. + +### כלי סינתזה (Perplexity) + +:::tip Synthesis Tools +כלי סינתזה הם רכיבים במערכת GenAI שמאחדים ומעבדים מידע קיים כדי ליצור תוצר חדש ובעל ערך גבוה יותר. +הם משלבים תוצאות של סוכנים, מסמכים או שלבי חשיבה לכדי סיכום, החלטה, תכנית או פלט מובנה אחד. +כלי סינתזה לא מביאים מידע חדש, אלא מחברים ומזקקים את מה שכבר קיים. +::: + +Perplexity וכלים דומים מחפשים, מביאים, מאחדים ומסנתזים לפני החזרת התוצאות אליך. + +**השיפור:** הבאה גולמית הייתה עולה 15,000-30,000 טוקנים. סינתזה דוחסת זאת ל-3,000-8,000 טוקנים לכל שאילתה. + +**המגבלות:** + +- משתמש באינדקסים מותאמים אישית (Bing) במקום Google, כך שאיכות החיפוש סובלת +- אתה פוגע במגבלות הקונטקסט אחרי 3-5 שאילתות +- ללא ניהול מצב—שאלות המשך מכריחות את הכלי להסביר מחדש יסודות במקום לבנות על מחקר קודם + +### ArguSeek: קונטקסט מבודד + ניהול מצב + +[ArguSeek](https://github.com/ArguSeek/arguseek) הוא תת-סוכן מחקר אינטרנט עם קונטקסט מבודד וניהול מצב סמנטי. + +**יתרון הסקייל:** ArguSeek מעבד 12-30 מקורות לכל קריאה. אפשר לבצע עשרות קריאות לכל משימה, לסרוק 100+ מקורות בסך הכל תוך שמירת קונטקסט המתזמר שלך נקי. + +**איך זה עובד:** + +1. **Google Search API** מספק איכות חיפוש במקום חלופות Bing/Brave +2. **פירוק שאילתות** (דרך Gemini) מריץ 3 וריאציות שאילתות במקביל: תיעוד רשמי + דיונים קהילתיים + התראות אבטחה +3. **חיסור סמנטי** אומר ששאילתות המשך מדלגות על תוכן שכבר כוסה ומקדמות את המחקר שלך במקום לחזור על יסודות + +**רצף מחקר לדוגמה:** + +``` +Q1: "Passport.js JWT authentication best practices?" + → Processes 15 sources + → Returns 2,800 tokens to your orchestrator + +Q2: "Known security vulnerabilities in Passport JWT?" (builds on Q1 context) + → Processes 20 sources, skipping duplicate content from Q1 + → Returns 3,600 tokens (no repeated basics) + +Q3: "RS256 vs HS256 implementation trade-offs?" (builds on Q1+Q2 context) + → Processes 18 sources, skipping already-covered territory + → Returns 2,900 tokens (advances research) + +Total research: 53 sources processed +Total cost to your orchestrator: 9,300 tokens instead of 42,000+ from raw fetching +``` + +### צלילה לעומק: ארכיטקטורת ArguSeek + +[ArguSeek](https://github.com/ArguSeek/arguseek)—צינור מובנה למחקר אינטרנט עם ניהול מצב סמנטי. + +**מבדילים עיקריים:** + +1. **Google Search API**—איכות לעומת Bing/proprietary +2. **חיסור סמנטי**—חסר מצב אבל מודע לקונטקסט. שאילתות המשך מדלגות על תוכן שכבר כוסה, מקדמות מחקר במקום להסביר מחדש +3. **פירוק שאילתות**—3 וריאציות במקביל לכל שאילתה (תיעוד + קהילה + התראות) +4. **זיהוי הטיה**—מסמן שיווק ספקים, מפעיל מחקר נגדי +5. **סינתזת PDF**—חילוץ ויזואלי של Gemini + +
+**Tools כלים:** +- `research_iteratively`—multi-source synthesis with citations +- `fetch_url`—targeted page extraction +
+ +**שימושי עבור:** מחקר שיטות עבודה מומלצות, גישות מתחרות, התראות אבטחה, לימוד טכנולוגיות חדשות, אימות הטיה. + +**חלופות:** [Perplexity](https://perplexity.ai) (Bing), [OpenAI Deep Research](https://platform.openai.com/docs/guides/deep-research), [Consensus](https://consensus.app), [Elicit](https://elicit.com). לרובם חסר שילוב Google API + חיסור סמנטי. + +## תבנית פרודקשן: עיגון מרובה מקורות + +בכתיבה לפרודקשן, בדרך כלל נשלב עיגון לקוד עם עיגון לאינטרנט: + +``` +Task: "Implement OAuth2 client credentials flow for our API" + +1. Code research: How does existing authentication work? (ChunkHound) + → Returns: Current session-based auth architecture, middleware patterns, + where auth config lives (3,200 tokens) + +2. Web research: What are current OAuth2 best practices and known CVEs? (ArguSeek) + → Returns: RFC 6749 implementation guidance, security considerations, + recent vulnerabilities in popular libraries (4,800 tokens) + +3. Implementation: Synthesize both sources + → Follows your existing architecture patterns (code-grounded) + → Uses 2025 security standards (web-grounded) + → Avoids known vulnerabilities (web-grounded) + → Integrates cleanly with your middleware (code-grounded) +``` + +גישה מרובת מקורות זו מונעת שני מצבי כשל: + +- עיגון לקוד בלבד מונע הזיות אבל מסתכן בשימוש בתבניות מיושנות +- עיגון לאינטרנט בלבד נותן לך שיטות עבודה מומלצות עדכניות אבל לא מתאים לארכיטקטורה שלך + +שילוב של שניהם נותן לך פתרונות שעובדים למערכת הספציפית שלך תוך שימוש בתקנים עדכניים. + +## נקודות מפתח + +**הסוכן יודע רק מה שבחלון הקונטקסט** +ללא עיגון, סוכנים יוצרים הזיות—פתרונות שנראים סבירים אבל מבוססים על תבניות נתוני אימון בלבד. אנחנו מעגנים סוכנים על ידי הזרקת מידע חיצוני (בסיס הקוד שלך, תיעוד עדכני, מחקר) לקונטקסט לפני הייצור. + +**חיפוש אייגנטי הוא גילוי אוטונומי מבוסס כלים** +הסוכן קורא ל-Grep, Read, ו-Glob בעצמו לחקור את בסיס הקוד שלך. זה עובד יפה לפרויקטים קטנים (מתחת ל-10,000 שורות). בסקייל גדול, תוצאות חיפוש מציפות את חלון הקונטקסט ודוחפות את האילוצים שלך לאמצע—לאזור שהמודל מתעלם ממנו. + +**אשליית חלון הקונטקסט: הקיבולת המפורסמת ≠ תשומת הלב האפקטיבית** +מודלים מפרסמים תמיכה ב200,000 טוקנים אבל מעבדים באופן אמין 60,000-120,000 טוקנים (30-60%). עקומת תשומת הלב בצורת U אומרת שההתחלה והסוף מקבלים תשומת לב חזקה, בעוד האמצע מקבל התייחסות שטחית או מדולג עליו. זו ארכיטקטורת transformer תחת אילוצים ריאליסטיים, לא באג. + +**חיפוש סמנטי מחפש לפי משמעות במקום מילות מפתח** +הטמעות וקטוריות מאפשרות לך לחפש לפי קונספט: "authentication middleware" מוצא קוד רלוונטי גם ללא התאמות מדויקות של מילות מפתח. זה מרחיב את הסקייל שלך ל-100,000+ שורות קוד. + +**תת-סוכנים מבודדים מחקר בקונטקסטים נפרדים** +אתה מאציל מחקר לתת-סוכן עם קונטקסט משלו. הוא מעבד 50,000-150,000 טוקנים של תוצאות חיפוש ומחזיר סינתזה של 2,000-5,000 טוקנים. זה עולה יותר טוקנים אבל מספק דיוק באיטרציה ראשונה דרך קונטקסט מתזמר נקי. + +**שתי ארכיטקטורות תת-סוכן משרתות סקיילים שונים** +סוכנים אוטונומיים (Explore של Claude Code) מחליטים על אסטרטגיה משלהם—פשוטים וגמישים. סוכנים מובנים (ChunkHound) עוקבים אחר אלגוריתמים דטרמיניסטיים—יקרים יותר אבל מתרחבים באופן אמין למיליוני שורות. + +**ביחרו כלי עיגון לפי סקייל בסיס הקוד** - +מתחת ל-10,000 שורות קוד: חיפוש אייגנטי עובד באופן אמין. 10,000-100,000 שורות קוד: הוסיפו חיפוש סמנטי או סוכן Explore. מעל 100,000 שורות קוד: השתמשו בכלי מחקר קוד מובנה (ChunkHound).הכלי שאתם צריכים תלוי בסקייל שלכם. + +**עיגון לאינטרנט - אותו רעיון**: +חיפוש מובנה עובד לשאילתות פשוטות. כלי סינתזה (Perplexity) דוחסים תוצאות. תת-סוכנים (ArguSeek) שומרים מצב על פני 100+ מקורות תוך שמירת הקונטקסט שלך נקי. + +**מערכות פרודקשן משלבות עיגון לקוד + לאינטרנט** +עגן בבסיס הקוד שלך למניעת הזיות והתאמה לארכיטקטורה שלך. עגן במקורות אינטרנט עדכניים לקבלת שיטות עבודה מומלצות ולהימנעות מתבניות מיושנות. שילוב של שניהם מונע פתרונות שעובדים בתיאוריה אבל לא מתאימים למערכת שלך. + +--- + +**הבא:** מודול המתודולוגיה הושלם. כעת יש לך את תהליכי העבודה הבסיסיים (Plan > Execute > Validate), תבניות תקשורת (Prompting 101), ואסטרטגיות ניהול קונטקסט (עיגון) להפעלת סוכני AI ביעילות בסביבות פרודקשן. diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-10-debugging.md b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-10-debugging.md new file mode 100644 index 0000000..bc87cfd --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-10-debugging.md @@ -0,0 +1,103 @@ +--- +sidebar_position: 5 +sidebar_label: 'שיעור 10: דיבאג עם AI' +title: 'שיעור 10: דיבאג עם סוכני AI' +--- + +import EvidenceBasedDebug from '@site/shared-prompts/\_evidence-based-debug.mdx'; + +דיבאג עם סוכני AI לא עוסק בלתאר סימפטומים ולקוות לפתרונות. במקום זה המיקוד הוא בדרישת ראיות בכל שלב. העיקרון המרכזי: **לעולם אל תקבל|י תיקון ללא הוכחה ניתנת לשחזור שהוא עובד**. + +## תמיד לדרוש ראיות + +השינוי המחשבתי היסודי ב-debugging עם AI הוא מעבר מלשאול "מה לדעתך לא בסדר?" ל"הוכח שהבאג קיים, ואז הוכח שהתיקון שלך עובד." סוכני AI מצטיינים בזיהוי דפוסים וחקירה שיטתית כשניתנים להם נתונים קונקרטיים, אבל נכשלים באופן מרהיב כשמאלצים אוצם לנחש. + +**Anti-pattern:** תיאור באג ובקשה מהסוכן לתקן אותו בעיניים עצומות. + +**דפוס העבודה הנכון לפרודקשן:** ספקו צעדים לשחזור, תנו לסוכן גישה לכלי אבחון, ודרשו ראיות לפני/אחרי. + +
+ +
+ +## ניתוח שורש הבעיה: הבנה לפני תיקון + +לפני שצוללים ללוגים או מנסים לשחזר, התחילו עם **ניתוח שורש הבעיה (RCA - root cause analysis)**—התהליך השיטתי של זיהוי סיבות יסודיות במקום טיפול בסימפטומים. בקשו מהסוכן להסביר את הארכיטקטורה וזרימת הקוד בזמן ריצה. השתמשו בניתוח השיחה כדי לזילזהות אי-התאמות בין המודל המנטלי שלכם להתנהגות האמיתית של המערכת. בקשו מהסוכן לעקוב אחר נתיבי הבקשות, להסביר את זרימת הנתונים, ולזהות נקודות כשל פוטנציאליות על סמך מבנה הקוד. + +הכוונה היא לא שהסוכן יקרא כל שורת קוד. השתמשו בחיפוש קוד סמנטי וכלי מחקר למציאת רכיבים רלוונטיים, ואז מקדו את השיחה בנתיבים קריטיים. החילו את **[טכניקת "חמש שאלות מדוע"](https://he.wikipedia.org/wiki/%D7%97%D7%9E%D7%A9_%D7%A9%D7%90%D7%9C%D7%95%D7%AA_%D7%9E%D7%93%D7%95%D7%A2)**: אין לעצור בתשובה הראשונה אלא להמשיך לתהות ולהקשות "מדוע". לדוגמה: +
+Trace the authentication flow from API request to database query. +1. Where could a race condition occur? +2. _Why_ would that race condition happen? +3. _Why_ isn't it handled? +4. _Why_ ... +
+ההסבר של הסוכן לעתים קרובות חושף מקרי קצה או הנחות שפספסתם — ושאלות "מדוע" חוזרות ונשנות חושפות את שורש הבעיה במקום סימפטומים שיטחיים. + +## ניתוח לוגים: כוח העל של הAI + +סוכני AI מצטיינים בקריאת הלוגים המבולגנים שבני אדם מתקשים איתם. stack traces ארוכים מפוזרים על פני אלפי רשומות? פורמטים לא עקביים משירותים שונים? פלט דיבאג גולמי ללא שדות מובנים? שם ל-AI יש את היתרון הגדול ביותר—עיבוד כאוס שבני אדם לא יכולים לפרסר ידנית. + +מה שלוקח למהנדסים בכירים ימים של קורלציה ידנית קורה בדקות. AI מזהה דפוסים על פני פורמטי לוגים: שגיאות במיקרו-סרביסים עם סגנונות לוגים שונים, דפוסים חוזרים של תזמון שמצביעים על race conditions קבורים בפלט מפורט, קבוצות משתמשים ספציפיות שחוות כשלים על פני לוגים מפוצלים. ככל שהלוגים מבולגנים יותר, כך זיהוי הדפוסים של AI עולה על היכולת האנושית. + +תנו לסוכנים גישה בכל דרך שעובדת: הדביקו פלט grep, העבירו פלט סקריפטים בצינור, העלו קבצי לוג גולמיים, גישת CLI ישירה לאגרגטורי לוגים. AI לא צריך JSON עם correlation IDs כדי להיות אפקטיבי—הוא מפרסר מה שיש לכם. עם זאת, לוגים מובנים (timestamps עקביים, request IDs, פורמט JSON) הם פרקטיקה הנדסית טובה והופכים ניתוח **גם** אנושי וגם AI לקל יותר. אבל אין להמתין לתשתית לוגים מושלמת לפני שממנפים את הAI—החוזק שלו הוא עבודה עם מה שכבר יש לכם. + +כששולטים ב-הודעות ללוג, הוסיפו משפטי אבחון ממוקדים מראש כשחוקרים באגים. חמש עשרה דקות של כתיבת פלט לוג ספציפי מנצחות שעות של ספקולציות. הסוכן יכול להנחות מה לכתוב ללוג בהתבסס על ההיפותזה שלו—ואז לנתח את הפלט החדש מיד. + +התובנה הזו משנה את הכלכלה של דיבאג עם AI והופכת את זה להרבה יותר קל להוסיף לוגים אבחוניים בעשרות נקודות אסטרטגיות—הרבה יותר נפח ממה שבני אדם אי פעם היו עושים ידנית—כי הסוכן יכול לייצר ולמקם אותם בדקות. ברגע שהבאג מאומת כמתוקן, אותו סוכן מסיר באופן שיטתי את כל קריאות הלוג הזמניות שנועדו לאבחון, משחזר היגיינת קוד ופרקטיקות כתיבה ללוג בסיסיות. מה שהיה אינסטרומנטציה מייגעת מדי לבני אדם (הוסיפו לוגים, נתחו, הסירו לוגים) הופך לחלק שגרתי מחקירה בסיוע AI, ומעביר את הדיבאג מביצוע "אינסטרומנטציה מינימלית" ל"חקירה עשירה בראיות." + +## סקריפטים לשחזור: קוד הוא זול + +כשבדיקת קוד וניתוח לוגים לא מספיקים—כשנדרשות ראיות חזקות או כשחייבים לשחזר תנאי state/timing מורכבים—סקריפטי שחזור הופכים לכלי חיוני. כאן יכולות יצירת הקוד העצומות של סוכני AI באות לידי ביטוי: סביבות שלוקחות לבני אדם שעות להגדיר (K8s, קונפיגורציות Docker, סנאפשוטים של בסיסי נתונים, שירותי mock, אתחול state) לוקחות ל-AI דקות לייצר. + +סקריפטי שחזור מבטלים עמימות ויוצרים מקרי בדיקה שניתנים לאימות. הם לוכדים קונטקסט מלא: state של מסד נתונים, תגובות API חיצוניים, קונפיגורציה, וקלטי משתמש. הסוכן מייצר סביבות שחזור מקיפות בקלות, והופך מה שהיה עבודה ידנית מייגעת לפרומפט פשוט. בקשו מהסוכן לסמלץ את התנאים המדויקים שבהם הבאג מתרחש, והוא ייצר את השלד לפי דרישה. + +למערכות מורכבות, השתמשו ב-Docker ליצירת סביבות שחזור מבודדות. קחו סנשפשוט של מסד הנתונים בפרודקשן, הגדירו שירותים עם הגדרות דומות לפרודקשן, וכתבו סקריפט שמשחזר את הבאג באופן אמין. ברגע שיש לכם שחזור אמין, הסוכן יכול לבצע איטרציות על תיקונים ולאמת כל ניסיון. + +## סגירת הלולאה: מקמו סוכנים בתוך סביבות כושלות + +עם עיגון טוב, סוכנים תמיד יכולים לחקור את הקודבייס שלכם ולחקור בעיות אונליין—זה מה ש[שיעור 5](/docs/methodology/lesson-5-grounding) מלמד. **אבל סגירת הלולאה אומרת שהסוכן יכול לבדוק את התיקונים שלו ולאמת שהפתרון שלו באמת עובד.** ללא גישה לסביבה, הסוכן מציע פתרונות שהוא לא יכול לאמת. עם גישה בלולאה סגורה, הוא מחיל תיקונים, מריץ מחדש שחזור, ומוכיח שהם עובדים—או מבצע איטרציות על היפותזות חדשות כשהם לא עובדים. + +ההבדל: סוכן בלולאה פתוחה חוקר את הקוד שלכם ובעיות אונליין, ואז מדווח: "The bug is likely missing RS256 signature verification at jwt.ts:67—try adding algorithm validation." סוכן בלולאה סגורה עושה את אותו מחקר, ואז **מחיל את התיקון הזה, מריץ מחדש את הבקשה הכושלת, צופה שהיא עכשיו מחזירה 401 נכון, ומדווח: "Fixed and verified—RS256 validation added at jwt.ts:67, reproduction now passes."** + +### תהליך עבודת Debugging בלולאה סגורה + +**1. בניה (BUILD)** - צרו סביבה ניתנת לשחזור (Docker, סקריפטים, מצב מסד נתונים) שגורמת לבאג לקרות באופן עקבי + +**2. שחזור (REPRODUCE)** - ודאו שהבאג מתבטא באופן עקבי עם ראיות קונקרטיות (לוגים, קודי סטטוס, פלט שגיאה) + +**3. מיקום (PLACE)** - תנו לסוכן גישה לכלים בתוך הסביבה—לא רק קוד, אלא יכולות ביצוע בזמן הריצה + +:::tip סוכני CLI ל-Debugging בלולאה סגורה +כאן סוכני CLI (Claude Code, Codex, Copilot CLI) מתעלים על עוזרי IDE. סוכני CLI יכולים לרוץ **בכל מקום שיש לכם גישת shell**: בתוך Docker containers, על שרתים מרוחקים, ב-CI/CD pipelines, על production instances בעייתיים. סוכני IDE קשורים למכונת הפיתוח המקומית שלכם. +::: + +**4. חקירה (INVESTIGATE)** - סוכן ממנף טכניקות עיגון ליצירת היפותזות על ידי קורלציה: + +- **התנהגות runtime**: בצעו פקודות אבחון, בדקו תגובות, נתחו לוגים +- **בסיס הקוד**: השתמשו בChunkHound לחקירה מקיפה של הקוד עם קונטקסט ארכיטקטוני ויחסים בין-מודוּלים. לבסיסי קוד קטנים יותר, [חיפוש אג'נטי](/docs/methodology/lesson-5-grounding#the-discovery-problem-agentic-search) (Grep, Read) עובד היטב. ראו [שיעור 5](/docs/methodology/lesson-5-grounding#code-grounding-choosing-tools-by-scale) להנחיות על סקייל. +- **בעיות ידועות**: חקרו דפוסי שגיאות, בעיות ונקודות חולשה מוכרות או CVEs, ובאגים דומים באמצעות כלים כמו ArguSeek + +**5. וידוא (VERIFY)** - סוכן מחיל את התיקון, מריץ מחדש שחזור, ומאשר שהבאג נפתר—או יוצר היפותזה חדשה ומבצע איטרציות + +תהליך עבודה זה הופך את תהליך הדיבאג מ"חקור ונחש" ל"חקור, תקן, בדוק, והוכח"—לולאת משוב סגורה שבה הסביבה מאמתת או מפריכה את ההיגיון של הסוכן. + +## אבחון מרחוק: סקריפטים על פני גישה + +כשלא ניתן לשחזר באגים מקומית או לגשת לסביבה הכושלת—התקנות אצל לקוחות, תשתית קצה, פרודקשן נעול—מתמודדים עם מידע מוגבל וללא מחזור איטרציה. כאן **היגיון הסתברותי** של סוכני AI הופך לתכונה, לא למגבלה. בשילוב עם יכולות יצירת הקוד שלהם, סוכנים הופכים אבחון מרחוק מ"שלח לי לוגים ותחכה" לתהליך עבודת חקירה אקטיבי. + +תהליך העבודה עוקב אחר דפוס ה-research-first מ[שיעור 5](/docs/methodology/lesson-5-grounding): עגנו את עצמכם בבסיס הקוד (הבינו את הארכיטקטורה סביב הרכיב הכושל באמצעות מחקר קוד) ובבעיות ידועות (חפשו בעיות דומות באקוסיסטם). עם הקונטקסט הזה, הסוכן מייצר היפותזות מדורגות המבוססות על ראיות—לא דפוסים גנריים. ואז הוא מייצר סקריפטי אבחון ממוקדים שאוספים ראיות לכל היפותזה: מצבי קונפיגורציה, אי-התאמות גרסאות, נתוני תזמון, מה שנדרש לאימות או הפרכה של כל תיאוריה. + +הרעיון הוא החלפת זמן מפתח|ת בזמן מחשוב. כתיבת סקריפט אבחון מקיף לוקחת לבני אדם ימים אבל לסוכנים 30 דקות. חשוב מכך, סוכנים מייצרים אבחונים יסודיים בקלות—סקריפטים שבודקים עשרות בעיות פוטנציאליות, מצליבים קונפיגורציות, ומוציאים נתונים מובנים. שלחו את הסקריפט ללקוח, טענו את הפלט לקונטקסט של הסוכן, והוא מתאם ראיות עם היפותזות לזיהוי שורש הבעיה. מה שהיה עבודה ידנית מייגעת הופך לפרומפט פשוט. + +## נקודות מפתח + +- **ראיות על פני ספקולציות** - לעולם אין לקבל תיקונים ללא הוכחה ניתנת לשחזור שהם עובדים +- **בדיקת קוד קודם** - הבינו ארכיטקטורה וריצה של הקוד לפני צלילה לתיקונים +- **ניתוח לוגים הוא כוח העל של AI** - עבּדו אלפי שורות לוג לזיהוי דפוסים, קורלציות, ובעיות תזמון שבני אדם מפספסים +- **קוד הוא זול, כתבו אותו בחופשיות** - סקריפטי שחזור, כלי אבחון, ותהליכי אימות קלים לייצור על ידי AI +- **דיבאג בלולאה סגורה** - מקמו סוכנים בתוך סביבות כושלות עם תהליך העבודה בניה ← שחזור ← מיקום ← חקירה ← וידוא +- **סוכני CLI ניגשים לכל סביבה** - בניגוד לעוזרי IDE, סוכני CLI עובדים ב-Docker, שרתים מרוחקים, CI/CD, וריצות של פרודקשן +- **אבחון מרחוק דורש סקריפטים** - צרו סקריפטי אבחון מקיפים כשגישה ישירה אינה אפשרית + +דיבאג עם סוכני AI עוסק ב**בניית סביבות אבחון** שבהן יש שפע ראיות ואימות שיטתי. הסוכן הוא החוקר הבלתי נלאה שלכם—תנו לו את הכלים ודרשו הוכחה. diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-11-agent-friendly-code.md b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-11-agent-friendly-code.md new file mode 100644 index 0000000..5e42dcb --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-11-agent-friendly-code.md @@ -0,0 +1,208 @@ +--- +sidebar_position: 6 +sidebar_label: 'שיעור 11: קוד ידידותי לסוכנים' +title: 'שיעור 11: כתיבת קוד ידידותי לסוכנים' +--- + +import CompoundQualityVisualization from '@site/src/components/VisualElements/CompoundQualityVisualization'; + +סוכנים מגבירים דפוסים—טובים או רעים. קוד נקי מייצר עוד קוד נקי. לוגיקה מפוזרת מייצרת עוד לוגיקה מפוזרת. מחקר מאשר זאת: קוד שנוצר על ידי AI מכיל **פי 8 יותר בלוקים משוכפלים** מקוד שנכתב על ידי בני אדם[^1]. סוכנים לא יוצרים שכפול—הם מגבירים דפוסים קיימים שהם רואים במהלך מחקר קוד. + +**אזהרה קריטית:** גם עם דפוסים מושלמים, סוכנים הם מערכות סטוכסטיות (אקראיות) —יצירת טוקנים של LLM היא הסתברותית, לא דטרמיניסטית. קונפבולציות, הזיות, ושגיאות עדינות מתרחשות באקראי, ללא קשר לאיכות הדפוסים. מצבי אנטרופיה גבוהה (ריפקטורים מורכבים, שינויים רוחביים) מגדילים הסתברות לשגיאות. התפקיד שלך הוא לא למנוע את כל השגיאות—זה בלתי אפשרי עם מערכות הסתברותיות—התפקיד שלך הוא **לעשות ריג'קט לשגיאות באופן פעיל במהלך סקירה** כדי למנוע מהן להיכנס למחזור ההצטברות. + +כל חתיכת קוד שמקבלים היום הופכת לקונטקסט של הדפוסים המקובלים לסוכנים של מחר. זה יוצר עקומות איכות אקספוננציאליות—למעלה או למטה. אתם שולטים בכיוון. + +## מנגנון ההצטברות + +במהלך מחקר קוד ([שיעור 5](/docs/methodology/lesson-5-grounding)), סוכנים עושים grep לדפוסים, קוראים יישומים, וטוענים דוגמאות לקונטקסט. הקוד שהם מוצאים הופך לקונטקסט הדפוסים לפרודקשן. + +
+ +
+ +### שני גורמים לסטייה באיכות + +איכות הקוד שלך מתדרדרת בשתי דרכים שונות מהותית כשעובדים עם AI: + +**1. אפקט מכונת הצילום (הגברה צפויה)** + +סוכנים מוצאים קוד קיים ומשתמשים בו כדוגמאות. אם בבסיס הקוד שלך יש שכפול, הסוכן לומד "כך אנחנו עושים דברים כאן" ויוצר עוד שכפול. אם בדיקות חסרות בקבצים דומים, הסוכן מייצר קוד ללא בדיקות. אם טיפול בשגיאות לא עקבי, הסוכן מייצר טיפול בשגיאות לא עקבי. + +זה צפוי: תראו לסוכן דפוסים מבולגנים, תקבלו קוד מבולגן בחזרה. הסוכן לא יצירתי—הוא עושה pattern matching למה שכבר קיים. + +**2. הטלת קוביה (שגיאות AI אקראיות)** + +LLMs הם מערכות הסתברותיות—הם מייצרים קוד דרך אקראיות משוקללת, לא היגיון לוגי. גם כשבסיס הקוד שלך מושלם, ה-AI מייצר שגיאות באקראי: + +- **המצאת דברים:** מתייחס לפונקציה `()getUserProfile` שלא קיימת, מייבא מקבצים שאינם קיימים +- **מורכבות מתפרקת:** משימות פשוטות עובדות יפה, אבל ריפקטורים על פני הרבה קבצים או ניהול state מורכב מגדילים סיכוי לטעויות +- **מוזרויות מודל:** גרסאות מודל שונות, מגבלות קונטקסט, ודפוסי תשומת לב מלאכותית יוצרים שוֹנוּת בלתי צפויה + +לא ניתן לבטל שגיאות אקראיות אלה עם פרומפטים טובים יותר או דפוסים נקיים יותר—הן טבועות באופן פעולת LLMs. + +**למה זה חשוב:** + +שתי הבעיות מזינות את אותה עקומה אקספוננציאלית. כשמאשרים שגיאת AI אקראית במהלך סקירת קוד, היא הופכת לדפוס שמועתק. קריאת API אחת שהומצאה באיטרציה 1 הופכת לתבנית עבור 5 הזיות דומות באיטרציה 3. + +**התפקיד הקריטי שלך:** סקירת קוד ([שיעור 9](/docs/practical-techniques/lesson-9-reviewing-code)) הוא המקום שבו שוברים את המחזור. עשו ריג'קט לדפוסים רעים לפני שהם מתרבים. תקנו שגיאות אקראיות לפני שהן הופכות לדפוסים. כל החלטת accept/reject משפיעה על כל פרודקשן עתידי. + +## למקם יחד אילוצים קשורים + +מ[שיעור 5](/docs/methodology/lesson-5-grounding) ראינו שסוכנים מגלים את בסיס הקוד שלנו דרך **חיפוש אג'נטי**—Grep, Read, Glob. **סוכנים רואים רק קוד שהם מוצאים באופן מפורש.** כשאילוצים מפוזרים על פני קבצים, החיפוש קובע מה הסוכן רואה ומה הוא מפספס. + +**Anti-pattern - אילוצים מפוזרים:** + +```typescript +// File: services/auth.ts +function createUser(email: string, password: string) { + return db.users.insert({ email, password: hashPassword(password) }) +} + +// File: config/validation.ts +const MIN_PASSWORD_LENGTH = 12 // ← Agent never searches for this file +``` + +**מה קורה:** הסוכן מחפש באמצעות `Grep("createUser")` ← קורא את הקובץ `services/auth.ts` ← ואז מייצר קוד שמקבל סיסמאות של 3 תווים כי הוא מעולם לא ראה את ה `MIN_PASSWORD_LENGTH` בקובץ האחר. + +**דפוס נכון - האילוצים ממוקמים זה לצד זה:** + +```typescript +// File: services/auth.ts +const MIN_PASSWORD_LENGTH = 12 // ← Agent sees this in same file + +function createUser(email: string, password: string) { + if (password.length < MIN_PASSWORD_LENGTH) { + throw new Error(`Password must be at least ${MIN_PASSWORD_LENGTH} characters`) + } + return db.users.insert({ email, password: hashPassword(password) }) +} +``` + +**מה קורה כאן:** הסוכן מחפש באמצעות `Grep("createUser")` ← קורא את הקובץ `services/auth.ts` ← רואה את `MIN_PASSWORD_LENGTH` באותה קריאה ← מייצר קוד שאוכף את האילוץ. + +### גשרים סמנטיים כשנדרשת הפרדה + +כשאילוצים חייבים להיות משותפים בין מודולים (לפי עקרון DRY למשל), צרו **גשרים סמנטיים**—הערות עם מילות מפתח סמנטיות קשורות שמאפשרות לחיפוש סמנטי וכלי מחקר קוד ([שיעור 5](/docs/methodology/lesson-5-grounding#solution-1-semantic-search)) לגלות יחסים: + +```typescript +// File: shared/constants.ts +// Password strength requirements: minimum character length enforcement +export const MIN_PASSWORD_LENGTH = 12 + +// File: services/auth.ts +import { MIN_PASSWORD_LENGTH } from '@/shared/constants' + +// User credential validation: enforce security constraints +function createUser(email: string, password: string) { + return db.users.insert({ email, password: hashPassword(password) }) +} +``` + +**איך גשרים סמנטיים עובדים:** חיפוש סמנטי מתאים משמעות, לא מילים מדויקות. שאילתת "password validation requirements" מוצאת את שני הקבצים כי embeddings מזהים דמיון סמנטי: +- "password" ≈ "credential" +- "requirements" ≈ "constraints" +- "strength" ≈ "security" + +ההערות משתמשות במילים שונות עם משמעות חופפת—מראה מקום סמנטי שמחבר קונספטים קשורים בין קבצים. + +### אוטומציה דרך Prompting + +במקום לנהל ידנית אסטרטגיות יכולת גילוי כאלה, הגדירו לסוכן שלכם לטפל בזה אוטומטית. הוסיפו הוראות כמו `"Document inline when necessary"` ו-`"Match surrounding patterns and style"` ל-`CLAUDE.md` או `AGENTS.md` שלכם ([שיעור 6](/docs/practical-techniques/lesson-6-project-onboarding)). ביטויים אלה גורמים לסוכנים להוסיף אוטומטית הערות עם גשרים סמנטיים במהלך יצירת הקוד, לעקוב אחר קונבנציות קוד קיימות, ולשמור על עקביות ללא פיקוח מפורש. הסוכן קורא את האילוצים הממוקמים זה לצד זה ואת הגשרים הסמנטיים שלכם במהלך מחקר קוד, ואז מייצר קוד חדש שעוקב אחר אותם דפוסים—הופך את יכולת הגילוי למערכת חיזוק חיובי אוטומטית במקום עבודת ארגון ידנית. + +**הערה:** יתכן שיהיה צורך להזכיר לסוכן את ההוראות האלה בפרומפטים הספציפיים למשימה. עקב [עקומת הקשב בצורת U](/docs/methodology/lesson-5-grounding#the-scale-problem-context-window-limits), הוראות שקבורות בקבצי קונפיגורציה יכולות ליפול לאמצע הנשכח של חלון הקונטקסט במהלך אינטראקציות ארוכות. תזכורת מהירה כמו "document inline where necessary and match surrounding style" בסוף הפרומפט שלכם מבטיחה שהאילוצים האלה נשארים באזור הקשב הגבוה. + +## הערות עבור הנדסת קונטקסט: Critical Sections לסוכנים + +**טכניקה מתקדמת—להשתמש במְשׂוֹרה.** בתכנות מקבילי או מרובה ת'רדים, critical sections מגנים על משאבים משותפים וקטעי קוד רגישים. הערות יכולות לשרת תפקיד דומה לסוכני AI, ליצור "agent-critical sections" ששומרים על קוד רגיש משינוי מקרי. יש להחיל זאת **רק** על קוד בסיכון אמיתי גבוה: אימות/הרשאה, פעולות קריפטוגרפיות, עיבוד תשלומים, מיגרציות מסד נתונים, רישום ביקורת, טיפול ב-PII. אין להשתמש בטכניקה הזו ללוגיקה כללית, פעולות CRUD, או קוד שמשתנה לעתים קרובות. מה המחיר?: הגנה יוצרת חיכוך. אם לכל פונקציה יש אזהרות "CRITICAL", הסיגנל הופך לרעש ועבודת סוכן לגיטימית מואטת. + +כשסוכנים חוקרים את בסיס הקוד שלכם ([שיעור 5](/docs/methodology/lesson-5-grounding)), הם קוראים קבצים וטוענים כל הערה לחלון הקונטקסט שלהם. זה אומר שהערות הופכות לפרומפטים. כתבו אותן כמו פרומפטים באמצעות טכניקות מ[שיעור 4](/docs/methodology/lesson-4-prompting-101): הנחיות ציווי (NEVER, MUST, ALWAYS), דפוסי שלילה מפורשים ("Do NOT X. Instead, always Y"), צעדים ממוספרים לפעולות מורכבות (Step 1, Step 2), והשלכות קונקרטיות. כשהסוכן מייצר קוד לטיפול בסיסמאות וקורא "NEVER store passwords in plain text" בצירוף חלופות ליישום נכון, ההפרה הזו הופכת הרבה פחות סבירה. אתם מנצלים prompt injection—מהסוג הטוב. + +```typescript +// Standard comment +// Validates password before storing +function createUser(password: string) { + return db.users.insert({ password }) +} + +// Critical section (agent barrier) +// === CRITICAL SECURITY SECTION === +// C-001: NEVER store passwords in plain text or weak hashing (MD5, SHA1) +// MUST hash with bcrypt (10+ rounds) BEFORE persistence +// Do NOT modify hashing algorithm without security review +// Violations create CVE-level vulnerabilities +function createUser(password: string) { + if (password.length < 12) { + throw new Error('Password must be at least 12 characters') + } + const hashed = bcrypt.hashSync(password, 10) + return db.users.insert({ password: hashed }) +} +``` + +ההערה המפחידה בקוד הנ"ל יוצרת חיכוך מכוון. סוכן שמקבל משימה "add OAuth login" יעבוד לאט יותר סביב קוד hashing של סיסמאות עם אילוצים כבדים—הוא חייב לנווט בזהירות בין כל ההנחיות של NEVER/MUST. זה מנגנון ההגנה: זהירות כפויה לנתיבים קריטיים. אבל שימוש יתר יפגום בתוצאות. אם מסמנים יותר מדי פונקציות כ-CRITICAL, סוכנים יתקשו עם עבודה שגרתית, ויאטו שינויים לגיטימיים באותה מידה כמו שינויים מסוכנים. שמרו את הטכניקה הזו לקוד שבו שינוי מקרי באמת עולה יותר מההאטה בפיתוח. + +בדוגמת הקוד הנ"ל מוזכר C-001 שהוא שם או ID של אילוץ שמגיע מ[טבלאות spec](/docs/practical-techniques/lesson-13-systems-thinking-specs#constraints-and-invariants-defining-correctness) ומחלחל לקוד במהלך היישום. ברגע שהמזהים האלה מוטמעים בתוך הקוד, הקוד נושא את האילוץ—לא רק האימפלמנטציה, אלא ה*כלל* שהיא אוכפת. זה מה שהופך את [מחיקת ה-spec](/docs/practical-techniques/lesson-12-spec-driven-development) לבטוחה אחרי יישום: ה-WHY חילחל לבסיס הקוד. + +## Knowledge Cache Anti-Pattern + +חילצת ידע ארכיטקטוני מבסיס הקוד שלך עם סוכן—דיאגרמות נקיות, תיעוד API מקיף, יחסי קומפוננטות מפורטים. שמרת את זה כ-`ARCHITECTURE.md` ועשית קומיט. עכשיו יש לך בעיית cache invalidation: קוד משתנה (תמיד), תיעוד לא (בדרך כלל), וסוכנים עתידיים מוצאים את שניהם במהלך מחקר קוד ([שיעור 5](/docs/methodology/lesson-5-grounding)). הדיאגרמה למטה מראה את הסטייה. + +
+```mermaid +sequenceDiagram + participant KB as 🗄️ Codebase
(Persistent) + participant Agent as ⚡ Agent
(Stateless) + + rect rgb(167, 139, 250, 0.1) + Note over Agent: 1. RESEARCH + Agent->>KB: Read source code + KB->>Agent: Knowledge extracted + end + + alt ✅ Good Path + Note over Agent: Knowledge stays in context + rect rgb(167, 139, 250, 0.1) + Note over Agent: 2. PLAN + Note over Agent: 3. EXECUTE + Agent->>KB: Edit code + Note over KB: Code changes + end + Note over Agent: Done ✓ + Note over KB: Code = source of truth + else ❌ Bad Path: Cache Research + Agent->>KB: Save ARCHITECTURE.md + Note over KB: Cache committed + rect rgb(167, 139, 250, 0.1) + Note over Agent: 2. PLAN + Note over Agent: 3. EXECUTE + Agent->>KB: Edit code + Note over KB: Code changes
⚠️ Cache now stale! + end + + Note over Agent: Future agent spawns + Agent->>KB: Research (read KB) + KB->>Agent: Finds BOTH:
① Current code
② Outdated cache + Note over Agent: Confusion! + end +``` +
+ +ברגע שמבצעים קומיט לידע שחולץ, כל שינוי קוד דורש עדכוני תיעוד שנשכח. קוד מקור הוא ה-single source of truth שלכם—כלי מחקר קוד (ChunkHound, חיפוש סמנטי, Explore) מחלצים ידע ארכיטקטוני באופן דינמי בכל פעם, טרי ומדויק. ההבחנה: ידע של **איך** (פרטי אימפלמנטציה, data flows, יחסי קומפוננטות) מופיע מאליו בקוד—מחקר קוד מייצר אותו מחדש כשצריך. ידע של **למה** (חלופות שנדחו, רציונל עסקי, דרישות compliance) לא ניתן לביטוי בקוד עצמו. יש לבצע קומיט גם ל-"למה", לשמור מסמכים קצרים שמתעדים מה הוחלט, למה, ואילו חלופות נדחו. תנו לכלי החיפוש ומחקר הקוד לטפל גם ב-"למה". + +## נקודות מפתח + +- **סוכנים מגבירים דפוסים וגם מייצרים שגיאות אקראיות** - דפוסים טובים מצטברים לקוד טוב יותר. דפוסים רעים מצטברים ל-technical debt. **אבל גם עם דפוסים מושלמים, LLMs מייצרים שגיאות הסתברותיות** (הזיות, כשלים שמקורם באנטרופיה) שמצטברים אם עושים להם accept. מחקר מראה שלקוד AI יש פי 8 שכפול-קוד כי סוכנים מגבירים דפוסי שכפול-קוד קיימים. כל PR שקיבל אישור הופך לקונטקסט ה"איך עובדים פה" לסוכנים עתידיים—כולל שגיאות אקראיות שפספסתם. + +- **למקם יחד אילוצים, ליצור גשרים סמנטיים כשנדרש** - קוד מפוזר מצטבר לבסיסי קוד קשים יותר לניווט. כשנדרשת הפרדה (עקרון DRY), יש להשתמש בהערות מפורשות שמצביעות לקבצים רלוונטים. + +- **הערות כ-agent-critical sections (להשתמש במשׂורה)** - לקוד בסיכון אמיתי גבוה (אותנטיקציה, קריפטוגרפיה, תשלומים, PII), כתבו הערות כפרומפטים עם הנחיות ציווי (NEVER, MUST, ALWAYS) ליצירת חיכוך מכוון. מנגנון הגנה זה שומר על קוד רגיש משינוי מקרי. **שימוש יתר פוגם בתוצאות**—אם הכל מסומן CRITICAL, הסיגנל הופך לרעש ועבודה לגיטימית מואטת. + +- **שילוב IDs של אילוצים ודרישות ממסמכי המפרט** — כשהspecs משתמשים במזהים כמו "REQ-001" ([שיעור 13](/docs/practical-techniques/lesson-13-systems-thinking-specs#constraints-and-invariants-defining-correctness)), סוכנים מטמיעים אותם בהערות בקוד במהלך הכתיבה. אז הקוד נושא בקירבו את כלל האילוצים, ואז ניתן למחוק את הspec בבטחה ([שיעור 12](/docs/practical-techniques/lesson-12-spec-driven-development)). + +- **אנחנו שומרי הסף של האיכות** - סקירת קוד ([שיעור 9](/docs/practical-techniques/lesson-9-reviewing-code)) מונעת הצטברות שלילית. לחיצה על accept של דפוסים רעים נותנת להם להיכנס לקונטקסט הדפוסים "המצופים" לסוכנים עתידיים. דחייתם (כפתור הreject) שוברת את ה-negative feedback loop. + +- **הימנעו מ-knowledge cache anti-pattern** - כלי מחקר קוד (Explore, ChunkHound, חיפוש סמנטי) מחלצים ידע ארכיטקטוני באופן דינמי מקוד מקור בכל פעם שצריכים אותו. שמירת ידע שחולץ לקבצי `md` יוצרת caches מיותרים שמאבדים רלוונטיות, מזהמים את העיגון העתידי עם מידע כפול, ויוצרים בעיות cache invalidation בלתי אפשריות. סמכו על תהליך העיגון ([שיעור 5](/docs/methodology/lesson-5-grounding)) לחלץ מחדש ידע לפי הצורך ממקור מידע יחיד (single source of truth). + +--- + +[^1]: GitClear (2025) - ניתוח של 211 מיליון שורות קוד (2020-2024) המראה עלייה פי 8 בבלוקי קוד משוכפלים בקוד שנוצר על ידי AI. מקור: [LeadDev: How AI-generated code accelerates technical debt](https://leaddev.com/technical-direction/how-ai-generated-code-accelerates-technical-debt) diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-12-spec-driven-development.md b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-12-spec-driven-development.md new file mode 100644 index 0000000..d4689ab --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-12-spec-driven-development.md @@ -0,0 +1,126 @@ +--- +sidebar_position: 7 +sidebar_label: 'שיעור 12: פיתוח מונחה Spec' +title: 'שיעור 12: פיתוח מונחה Spec' +--- + +import KnowledgeExpansionDiamond from '@site/src/components/VisualElements/KnowledgeExpansionDiamond'; + +**עקרון DRY. מקור אמת יחיד (Single Source of Truth).** אלה לא סתם מילים ריקות—אלה פרקטיקות הנדסה שמשמרות שפיות. כשאותו מידע קיים במספר מקומות, הוא מתפזר ומאבד עקביות. מקור אחד אומר X, אחר אומר Y. זה מוביל לבאגים. + +בסיס הקוד שלך הוא בסיס ידע. כל פונקציה, טסט ואילוץ מקודדים ידע על דרישות, כללים עסקיים והחלטות יישום. אותם כללים חלים: אין לשכפל ידע, יש לשמור על מקור סמכותי אחד. + +פיתוח מונחה Spec או **SDD** - Spec Driven Development היא טכניקה להוספה או שינוי ידע בבסיס הקוד שלך תוך כיבוד עקרונות אלה. + +## הרחבת הידע של SDLC + +פיתוח תוכנה מסורתי עוקב אחר דפוס של הרחבת ידע: + +
+ +
+ +כל שלב מוסיף ידע חדש. הhigh-level-spec לוכד את ה"מה" וה"למה". העיצוב המפורט חוקר את ה"איך"—מקרי קצה, אילוצים, טיפול בשגיאות, זרימת הנתונים. הקוד מכיל פרטי אימפלמנטציה, אופטימיזציות לביצועים, ואת ההבנה המלאה המזוקקת של הבעיה. + +זה משקף waterfall מסורתי, אבל עם סוכני AI, זה קורה בשעות במקום שבועות. התובנה המרכזית היא: **כל שכבה היא הרחבת ידע של השכבה שמעליה**. + +## בעיית הידע הכפול + +ברגע שהאימפלמנטציה הושלמה והקוד עובר בדיקות ([שיעור 8](/docs/practical-techniques/lesson-8-tests-as-guardrails)) וסקירה ([שיעור 9](/docs/practical-techniques/lesson-9-reviewing-code)), יש לך בעיה: אותו ידע קיים בשלושה מקומות—הspec, הדיזיין, והקוד. + +מה הגרסה הנכונה? + +הspec אומר "users can have at most 5 active sessions." הקוד מיישם מגבלה של 10. מסמך הדיזיין מדבר על "configurable session limits." שלושה מקורות, שלוש אמיתות שונות. + +זה בדיוק ה[knowledge cache anti-pattern](/docs/practical-techniques/lesson-11-agent-friendly-code#the-knowledge-cache-anti-pattern) משיעור 11. מסמכי spec שנשמרו הופכים מיושנים ברגע שהקוד משתנה. סוכנים עתידיים שחוקרים את בסיס הקוד שלך מוצאים גם את הspec המיושן וגם את הקוד הנוכחי, מה שמוביל לבלבול ויישומים סותרים. + +הנה התובנה המרכזית מ[שיעור 5](/docs/methodology/lesson-5-grounding): **כלי עיגון כבר מבצעים חילוץ ידע.** כש[מחקר קוד](https://chunkhound.github.io/code-research) של ChunkHound מעבד 50,000 טוקנים של קוד גולמי ומחזיר סינתזה של 3,000 טוקנים, אותה סינתזה היא spec שחולץ לפי דרישה ממקור האמת. לא צריך לתחזק קבצי spec כי ניתן לייצר אותם מחדש מהקוד מתי שצריך. + +אבל לא כל ידע שמגיע מהspec דינו אותו דבר. ידע ה**איך** של פרטי אימפלמנטציה, זרימות נתונים, ושל מקרי קצה מקודד במלואו בקוד במהלך היישום. ברגע שהקוד קיים, ה"איך" של ה-spec הוא מיותר. ידע ה**למה** - חלופות שנדחו, רציונל עסקי לאילוץ, דרישות compliance—לא ניתנים לביטוי בקוד. הערת אילוץ כמו `C-001: NEVER process duplicate webhook //` ([שיעור 11](/docs/practical-techniques/lesson-11-agent-friendly-code#comments-as-context-engineering-critical-sections-for-agents)) אומרת לסוכן *מה* לאכוף (התעלמות מהרצה כפולה), אבל לא *למה* בחרת לאכוף התעלמות מהרצה כפולה ע"י שמירתה בבסיס הנתונים על פני שהיא תאכף דרך שמירה בcache למשל. הרציונל הזה הוא ה**שארית** - החלק מהspec שלא מגיע לקוד. + +**הפתרון: יש למחוק את הspec של ה"איך" אחרי האימפלמנטציה.** הקוד הוא מקור האמת היחיד לאימפלמנטציה. לגבי שארית ה"למה" הקטנה (חלופות שנדחו, קונטקסט עסקי שהניע אילוצים), יש לבקש מהסוכן לעשות diff בין ה-spec המקורי לקוד הסופי—מה שמבוטא בקוד הוא עכשיו מיותר. השארית נכנסת לקומיט כחלק ממסמך החלטות קטן (decision record, [שיעור 11](/docs/practical-techniques/lesson-11-agent-friendly-code#the-knowledge-cache-anti-pattern)). כל השאר ניתן לייצר מחדש מקוד דרך כלי עיגון. + +## SDD רגיל לעומת גישה זו + +כלים כמו [GitHub Spec Kit](https://github.com/github/spec-kit), [Amazon Kiro](https://kiro.dev/), ו-[Tessl](https://tessl.io/) מבינים את זה הפוך. הם מתייחסים ל-specifications כ"תוצרים חיים קבועים" שמתפתחים לצד הקוד—הspec הוא מקור האמת, הקוד הוא התוצר שנוצר. + +**זה מפר את העקרון של "[מקור אמת יחיד](https://en.wikipedia.org/wiki/Single_source_of_truth)".** ברגע שיש לך שני ייצוגים של אותו ידע—בspec ובקוד—יש לך בעיית עקביות. זו לא תובנה חדשה. זו הסיבה בגינה ביטלנו קבצי header איפה שאפשר, זה למה אנחנו מייצרים מסמכי API מקוד, למה אנחנו מייצרים specs של OpenAPI מהערות קוד. + +מודל ה"spec המתעדכן" מניח סנכרון דו-כיווני מושלם: שינויי קוד מעדכנים specs, שינויי spec מעדכנים קוד. בפועל, מפתחים משנים קוד ישירות. היחס spec-קוד לא "מתפזר"—הוא שבור מהותית כי נוצרו שני מקורות אמת לאותו ידע. + +**הגישה הנכונה:** +- קוד הוא מקור האמת—נקודה +- Specs הם שלד זמני לתהליך היצירה +- יש למחוק specs אחרי יישום +- יש לייצר מחדש specs לפי דרישה חזרה מהקוד אם וכשצריך + +חיפוש אייג'נטי, חיפוש סמנטי, [מחקר קוד](https://chunkhound.github.io) של ChunkHound—אלה לא רק כלי גילוי. הם **מנועי חילוץ ודחיסת ידע**. אותם 50,000 טוקנים של קוד יכולים להידחס לצורות שונות בהתאם לשאלה: + +- "What does this module do?" ← Spec ברמה גבוהה (~100 שורות) +- "How is authentication implemented?" ← עיצוב מפורט (~1k שורות) +- "What's the API contract?" ← תיעוד ממשק +- "What are the architectural boundaries?" ← דיאגרמת רכיבים + +אותו מקור אמת, יעדי דחיסה שונים. תהליך העיגון ([שיעור 5](/docs/methodology/lesson-5-grounding)) מחלץ בדיוק מה שצריך, מתי שצריך—ללא caches מיושנים, ללא מקורות סותרים. + +## שינוי קוד קיים + +כשמשנים קוד קיים, הידע כבר נמצא ביישום. התפקיד שלך הוא לחלץ אותו, לעצב אותו מחדש למי שצריך לאשר או להבין את השינוי, לשנות אותו, ואז ליישם מחדש. + +**יש לשחזר את ה-spec מהקוד.** יש להשתמש ב[טכניקות עיגון](/docs/methodology/lesson-5-grounding) כדי להציף את היישום הנוכחי ל-spec. הצורה של אותו spec תלויה במי צריך אותו: + +- **סטייקהולדרים של המוצר** צריכים specs התנהגותיים: מה משתמשים יכולים לעשות, אילו כללים עסקיים חלים, אילו תוצאות לצפות – `Users can have up to 5 concurrent sessions. When exceeded, the oldest session is terminated` + +- **מהנדסים** צריכים specs של מערכות: איך רכיבים מתקשרים, זרימות נתונים, אילוצים ארכיטקטוניים – `SessionManager enforces MAX_SESSIONS=5 via Redis sorted set with TTL. Eviction uses LRU via ZREMRANGEBYRANK` + +- **QA** צריכים specs של האילוצים: גבולות, מקרי קצה, תנאי שגיאה – `Boundary: exactly 5 sessions allowed. Edge: 6th login evicts oldest. Constraint: session TTL is 24h. Error: Redis unavailable returns 503` + +אותו קוד מקור, יעדי דחיסה שונים. צרו את הצורה הנכונה לקהל שלכם. + +**יש לשנות את ה-spec, ואז לבצע ניתוח פערים.** לאחר עריכת ה-spec עם השינויים הרצויים, יש לבצע ניתוח פערים: להשוות את ה-spec המעודכן ליישום הנוכחי. מה קיים? מה חסר? מה מתנגש? זה מגשר בין "איפה אנחנו" ל"לאן אנחנו רוצים להגיע." + +**יש לעבוד לפי תהליך ארבעת השלבים.** עם הפער מזוהה, יש לעבוד בתהליך הסטנדרטי של [מחקר ← תכנון ← ביצוע ← אימות](/docs/methodology/lesson-3-high-level-methodology). ה-spec המעודכן מזין את שלב התכנון שלך; ניתוח הפערים אומר לך בדיוק מה צריך לשנות. + +**ניקוי.** יש למחוק קבצי spec זמניים וכל שלד של בדיקות. הקוד הוא עכשיו שוב מקור האמת. + +## חלון הקונטקסט כ-Spec עובד + +אם עקבתם אחרי קורס זה, תרגלתם SDD כל הזמן. בכל פעם ש: + +- ביצעתם עיגון בבסיס הקוד לפני שינוי (זה למעשה חילוץ ה-spec) +- תיארתם דרישות בפרומפט שלכם (עדכון ה-spec) +- גרמתם לסוכן ליישם מאותן דרישות (קידוד מ-spec) +- סגרתם את השיחה כשסיימתם (הspec שירת את מטרתו) + +...אז כבר עשיתם פיתוח מונחה spec. הspec נמצא בחלון הקונטקסט שלכם—בRAM, לא בדיסק. + +מה שהופך את זה לבטוח הוא [הגירת אילוצים (constraint migration)](/docs/practical-techniques/lesson-11-agent-friendly-code#comments-as-context-engineering-critical-sections-for-agents): במהלך יישום, הסוכן מטמיע אילוצי spec יחד עם הIDs שלהם בהערות קוד. ה"למה" עובר מהspec לקוד. כשסוגרים את השיחה, שום דבר לא אבד. + +### מתי לשמור Specs + +למשימות שנסגרות תוך סשן אחד, חלון הקונטקסט הוא ה-spec שלך. אבל משימות גדולות יותר צריכות תיאום בין סשנים נפרדים: + +**יש לשמור specs כש:** +- העבודה משתרעת על ימים או סשנים מרובים +- הההיקף חורג ממגבלות הקונטקסט הסביר (~100k טוקנים) +- סוכנים או אנשים שונים צריכים לתאם ביניהם +- החלטות ארכיטקטוניות שצריכות זמן להבשיל + +**יש להשאיר specs כזמניים (ephemeral) כש:** +- המשימה מסתיימת בסשן אחד +- עושים איטרציות מהירות (שעות, לא ימים) +- ההיקף נכנס בנוחות לקונטקסט + +זיכרו: specs הם השלד, לא הארכיטקטורה. + +## נקודות מפתח + +- **בסיס הקוד הוא בסיס ידע** — כל שורה מקודדת ידע על דרישות, אילוצים והחלטות. יש לשמור על עקביות וללא קונפליקטים. + +- **SDD מוסיף ידע באופן שיטתי** — high-level-spec ← דיזיין מפורט ← קוד. כל שלב מרחיב ידע תוך שמירה על קוהרנטיות. + +- **ל-specs יש מחזור חיים** — עבודת סשן יחיד משתמשת בחלון הקונטקסט כ-spec. פרויקטים מרובי סשנים צריכים קבצים שמורים. כך או כך, יש למחוק specs אחרי יישום—הקוד הוא מקור האמת. + +- **לשינויים: חלץ ← שנה ← יישם ← מחק** — יש להציף ידע קיים כ-specs, לשנות אותם, ואז לעקוב אחר התהליך הרגיל. + +- **ייצר מחדש specs לפי דרישה** — כלי מחקר קוד מחלצים ידע ארכיטקטוני באופן דינמי. אין צורך לתחזק תיעוד סטטי. diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-13-systems-thinking-specs.md b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-13-systems-thinking-specs.md new file mode 100644 index 0000000..486f628 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-13-systems-thinking-specs.md @@ -0,0 +1,385 @@ +--- +sidebar_position: 8 +sidebar_label: 'שיעור 13: חשיבה מערכתית' +title: 'שיעור 13: חשיבה מערכתית' +--- + +import SystemFlowDiagram from '@site/src/components/VisualElements/SystemFlowDiagram'; +import SystemBoundaryDiagram from '@site/src/components/VisualElements/SystemBoundaryDiagram'; +import SpecCodeZoomDiagram from '@site/src/components/VisualElements/SpecCodeZoomDiagram'; + +[שיעור 12](/docs/practical-techniques/lesson-12-spec-driven-development) קבע ש-specs הם פיגומים—כלי חשיבה זמניים שנמחקים לאחר המימוש. אבל מה הופך spec ל*טוב מספיק* כדי לייצר קוד איכותי? + +חשבו על spec כעדשת זום. בזום-אאוט, רואים ארכיטקטורה—מודולים, גבולות, התכונות הקבועות של המערכת (invariants) . בזום-אין, רואים מימוש—מקרי קצה, טיפול בשגיאות, מקביליות. קופצים הלוך ושוב בין דרכי ההסתכלות, וה-spec מתחדד דרך המעבר במימוש[^5]. + +## דיוק דרך איטרציה + +specs מעורפלים מייצרים קוד מעורפל. דיוק מצמצם את מרחב הפתרונות: + +| מעורפל | מדויק | +|-------|---------| +| "תעשה אימות ל webhook" |
`C-001: NEVER process unsigned webhook — Signature validation on line 1 of handler`
| +| "אחסן נתוני תשלום" |
`I-001: SUM(transactions) = account.balance — Verified by: generate 1K transactions, check sum after each batch`
| + +אבל דיוק לא מושג דרך התבוננות בלבד—הוא מתגלה דרך איטרציה[^4]. כל מעבר דרך המימוש חושף אילוצים שה-spec החמיץ: מעבר בין מצבים שלא צפיתם, מקרה קצה של עבודה במקביל, תקציב ביצועים לא ריאליסטי. צוואר הבקבוק עבר מ"פרודקשן" ל"אורקסטרציה (Orchestration) + ולידציה (Verification)"[^1]—אתם מתזמרים מה נבנה ומוודאים שזה תואם לכוונה. + +לזה יש השלכה מעשית על תהליך הדיבאג. כשהמימוש סוטה מהכוונה, שאלו: **האם הארכיטקטורה תקינה?** אם כן, תקנו את הקוד—הסוכן עשה שגיאה מכנית. אם המודל או הגבולות שגויים, תקנו את ה-spec וחוללו מחדש. + +## תהליך העבודה האיטרטיבי +
+ +
+ +התחילו עם שלושה חלקים: **ארכיטקטורה**, **ממשקים**, ו**סטייט**—מספיק כדי לייצר מעבר ראשון. ה-spec הוא היפותזה. הקוד הוא ניסוי. המימוש חושף מה ה-spec החמיץ: מעבר בין מצבים שלא צפיתם, אילוץ של מקביליוּת, תקציב ביצועים לא ריאליסטי. זום-אאוט—חלצו את ההבנה המעודכנת מהקוד באמצעות [ChunkHound code research](https://chunkhound.github.io/code-research). תקנו את הארכיטקטורה. זום-אין—ייצרו מחדש. חזרו עד התכנסות, ואז [מחקו את ה-spec](/docs/practical-techniques/lesson-12-spec-driven-development). + +זהו [מחזור ארבעת השלבים של שיעור 3](/docs/methodology/lesson-3-high-level-methodology#the-four-phase-workflow) מיושם באופן "פרקטלי". ברמת ה-spec: עשו מחקר על הדומיין, תכננו ארכיטקטורה, כתבו spec, ולידציה לרמה של שלמות. ברמת הקוד: עשו מחקר על בסיס הקוד, תכננו שינויים, בצעו, ודאו שהטסטים עוברים. כל מעבר זום—spec←קוד או קוד←spec—הוא בעצמו לולאת "מחקר->תיכנון->ביצוע->אימות". עומק האיטרציה מותאם למורכבות: פיצ'ר פשוט מתכנס במעבר אחד; שינוי ארכיטקטוני מורכב עשוי לקחת חמישה. + +הסעיפים למטה מייצגים את השאלות שתהליך זה מעלה. אתם לא תענו על כולן מראש— אתם תגלו אילו מהן חשובות כי הקוד חושף פערים. + +## ארכיטקטורה: מודולים, גבולות, חוזים + +לכל מערכת יש מבנה פנימי. הארכיטקטורה מכריחה אתכם להפוך את המבנה הזה למפורש. + +### מודולים + +מודול הוא יחידה עם אחריות בודדת. לא "מטפל בתשלומים"—זו קטגוריה. "מעבד אירועי Stripe webhook ומעדכן מצב תשלום"—זו אחריות. + +| מודול | אחריות | גבול | +|--------|---------------|----------| +| webhook-handler | עיבוד Stripe webhooks, עדכון מצב תשלום | `src/payment/webhooks/` | +| notification | שליחת מיילים על אירועי תשלום | `src/notification/` | + +כשאי אפשר לנסח מה מודול עושה במשפט אחד, הוא עושה יותר מדי. + +### גבולות + +גבולות מגדירים מה מודול *לא יכול* לייבא—אילוץ הצימוד (coupling). + +- **webhook-handler** — לעולם לא מייבא מ-notification או מ-order +- **webhook-handler** — מפרסם אירועים לתור, הצרכנים מחליטים על הפעולה + +גבולות מוֹנעים משינויים במודול אחד להתפשט במערכת. + +### חוזים + +חוזים מגדירים איך מודולים מתקשרים—מה הקורא מספק (preconditions) ומה הנקרא מבטיח (postconditions). + +| ספק | צרכן | חוזה | תאור | +|----------|----------|----------|----------| +| webhook-handler | payment | `processEvent(stripeEventId): PaymentIntent` | precondition: אירוע עדיין לא עובד | +| payment | notification | `PaymentEvent { type, paymentId, amount, timestamp }` |postcondition: לא בר-שינוי לאחר פרסום | +| payment | checkout | `createIntent(orderId, amount): PaymentIntent` | precondition: הזמנה קיימת ולא שולמה | + +### נקודות אינטגרציה + +נקודות אינטגרציה הן הדלתות בקיר הגבול—איפה תעבורה חוצה מחיצוני לפנימי או להפך. + +| נקודה | סוג | כיוון | בעלות | +|-------|------|-----------|-------| +| `/webhooks/stripe` | HTTP endpoint | inbound | webhook-handler | +| `/api/v1/payments` | REST API | inbound | payment | +| `payment-events` | Message queue | internal pub/sub | payment | + +כיוון חשוב: נקודות כניסה צריכות אימות והגנה על כמות קריאות; pub/sub פנימי צריך דרך לוודא שהודעות התקבלו. אבל כיוון לבדו לא מסביר *למה* אימות מסוים קיים—זה דורש לציין מה אתם מניחים לגבי השירות החיצוני. + +### הנחות צד שלישי + +נקודות אינטגרציה אומרות לכם *איפה* שירותים חיצוניים מתחברים. הנחות צד שלישי לוכדות *מה אתם מאמינים לגבי אותם שירותים*—ערבויות התנהגותיות שהדיזיין שלכם תלוי בהן בשקט. כשלא הופכים אותן למפורשות, החלטות דיזיין נראות שרירותיות: סוכן רואה דרישה ספציפית "C-001" עבור "idempotency" אבל לא את סמנטיקת המסירה שדורשת אותה. + +עבור מערכת ה-Stripe webhook, ההנחות שמניעות החלטות דיזיין מפתח הן: + +| הנחה | מקור | מניע | +|------------|--------|--------| +| Webhooks מועברים at-least-once, לא exactly-once | Stripe docs | C-001 (idempotency), Redis lock, מודל event-driven-state | +| Webhooks עשויים להגיע שלא בסדר | Stripe docs | מכונת מצבים עם מעברים מפורשים | +| Payloads חתומים ב-HMAC-SHA256 | Stripe docs | C-002 (אימות חתימה) | +| זמינות API ~99.99% | Stripe SLA | Circuit breaker, תור להרצה מחדש, פולבק ידני | + +עמודת ה**מניע** היא הנקודה. היא יוצרת יכולת מעקב מהנחה לאלמנט spec—כך שכשהנחה משתנה (מעבר מ-Stripe ל-Adyen, או ש-Stripe משנה סמנטיקת מסירה), תדעו בדיוק אילו אילוצים, מודלי state, והחלטות אבטחה לבחון מחדש. בלעדיה, מיגרציה של spec הופכת בעצם למעבר מחדש על כל ה-spec. באמצעות המניע, הביקורת מוגבלת אך ורק לשורות שההנחות שלהן כבר לא מתקיימות. + +### נקודות הרחבה + +לפעמים לא כל נקודות האינטגרציה ממומשות עדיין. כשוריאציה ספציפית *מחויבת*—ממומנת, מתוזמנת, נדרשת בדדליין ידוע—הצהירו על ממשק ברור שישאר יציב עכשיו כדי שהמימוש הנוכחי לא יתקבע. + +| וריאציה | ממשק יציב | נוכחי | מתוכנן עד | +|-----------|-----------------|---------|------------| +| PayPal checkout | ממשק `PaymentGateway` | מימוש Stripe בלבד | Q3 — מחויב | +| Multi-currency | `Amount { value, currency }` | USD hardcoded | לא נסגר עדיין — יש להשמיט | + +העיקרון הוא Protected Variation[^3] (Cockburn/Larman): זַהו נקודות של שינויים צפויים וצרו ממשק יציב סביבן. השורה השנייה נשארת בחוץ—YAGNI שומר אילו שינויים נכנסים ל-spec. רק צרכים עסקיים שהחליטו להכניס אותם מקבלים אבסטרקציה. + +בלי זה, סוכנים בונים את המימוש הנכון הפשוט ביותר—Stripe client קשיח. כש-PayPal מגיע ב-Q3, זה הופך לשכתוב מאפס, לא הרחבה. הצהרה על הממשק עכשיו עולה אבסטרקציה אחת; השמטתו עולה מיגרציה. + +## State: מה שנשמר, מה שמשתנה, מה שמתאושש + +State הוא המקום שבו באגים מסתתרים. חלק ה-state מכריח אתכם לתת דין וחשבון על מה שהמערכת זוכרת. + +### ישויות + +מה נשמר מעבר לבקשה בודדת? איפה זה חי? מי הבעלים? + +| ישות | שמירה | אחסון | בעלות | +|--------|-------------|---------|-------| +| PaymentIntent | persistent | טבלת payments | payment service | +| WebhookEvent | persistent | טבלת webhooks | payment service | +| ProcessingLock | ephemeral (ארעי) | Redis | payment service | + +ההבחנה חשובה להתאוששות מקריסה (Crash Recovery). אם התהליך מת באמצע פעולה, state ארעי נעלם. המערכת שלכם חייבת להתמודד עם זה. + +### מודלי State + +איך שאתם ממדלים state קובע איך אתם חושבים על מעברים (transitions). + +| מודל | מתי להשתמש | Trade-off | שאלת מפתח | +|-------|----------|----------|-------------| +| דקלרטיבי | רינדור UI, תשתיות, התכנסות schema | פשוט להבנה; צריך reconciler שיעשה diff ולהתכנס | "מה צריך להיות מצב הסיום?" | +| Event-Driven | Webhooks, messaging, event sourcing, CQRS | audit trail מלא והפעלה חוזרת (replay); eventual consistency, מורכבות סדר | "מה קרה, ובאיזה סדר?" | +| מכונת מצבים | מחזורי חיי תשלום, זרימות הזמנה, שרשראות אישור | מעברים לא חוקיים בלתי אפשריים; כל קו מחבר חייב להיות מוגדר מראש | "אילו מעברים חוקיים ממצב זה?" | + +המודל הדקלרטיבי הולך והופך לברירת מחדל בתחומים רבים — React מבצע reconcile לUI וTerraform מיישב תשתיות, SQL מצהיר תוצאות שאילתה, GitOps מיישב deployments. התבנית הבסיסית היא תמיד אותו דבר: `desired_state + reconciliation_loop`. אתם מצהירים מה, משהו אחר מבין איך. כשאין reconciler לתחום שלכם, אתם בונים אחד — זו העלות. + +בחרו מודל אחד לכל ישות. מחזור חיי תשלום = מכונת מצבים (pending → processing → succeeded/failed). קליטת webhook = event-driven (append-only log, at-least-once delivery). יתרת חשבון = declarative (`SUM(transactions)` חייב להתכנס ל-`account.balance`). המודל מעצב את הקוד שסוכנים מייצרים: מכונות מצבים מייצרות `switch/case` עם מעברים מפורשים, event-driven מייצר handlers ו-projections, מודל דקלרטיבי מייצר reconcilers של diff-and-patch. + +### מצבי שגיאה + +שגיאות אינן חריגות למודל הנתונים שלכם—הן חלק ממנו. + +| קוד | משמעות | התאוששות | +|------|---------|----------| +| PAYMENT_PENDING | ממתין לאישור Stripe | נסה שוב בדיקת webhook | +| PAYMENT_FAILED | Stripe דחה | הודע למשתמש, אפשר ניסיון חוזר | +| WEBHOOK_DUPLICATE | כבר עובד | החזר 200, דלג על עיבוד | + +כשממדלים מצבי שגיאה במפורש, נתיבי התאוששות (Recovery Paths) הופכים ברורים. + +### אתחול והתאוששות מקריסה + +מערכות לא מתחילות במצב יציב. סדר אתחול והתאוששות מקריסה קובעים האם restart משחית נתונים או ממשיך בצורה נקייה. + +| סדר | רכיב | תלוי ב | מוכן כש | בכישלון | +|-------|-----------|------------|------------|---------| +| 1 | Database | — | מקבל חיבורים | abort | +| 2 | Cache | Database | Ping מצליח | degrade | +| 3 | HTTP server | DB, Cache | Healthcheck 200 | retry 3×, abort | + +אם צעד אתחול כלשהו לא תומך בהתעלמות מהרצה כפולה ,crash-and-restart יכול להשחית state. ציינו מה "Ready" אומר לגבי כל רכיב, ומה קורה כשמוכנות נכשלת. + +--- + +ארכיטקטורה מגדירה את השלד הפנימי—מודולים, גבולות, חוזים. החלק הבא מחליף פרספקטיבה: איך המערכת נראית מ*בחוץ*? +
+ +
+ +הקו המקווקו הוא המפתח. כל מה שבתוכו הוא ארכיטקטורה: מודולים מחוברים בחוזים. כל מה שחוצה אותו הוא ממשק: נתונים שנכנסים (inputs) או יוצאים (outputs) מהמערכת. נקודות אינטגרציה הן הדלתות בקיר. + +## ממשקים: כניסות ויציאות + +לכל מערכת יש שטח פַּנים — המקום שדרכו נתונים נכנסים ויוצאים. בעוד ארכיטקטורה מתארת מבנה פנימי, ממשקים מתארים את המשטח החיצוני של המערכת: מה חוצה את הגבול, באיזה פורמט, ותחת אילו אילוצים. + +### כניסות + +| שם | מקור | פורמט | ולידציה | הגבלת כמות | +|------|--------|--------|------------|------------| +| Stripe webhook | Stripe (HTTPS POST) | `StripeEvent` JSON | חתימת HMAC-SHA256, timestamp < 5min | 10K/min | +| Payment request | Client app (REST API) | `{ orderId: UUID, amount: number }` | JWT auth, orderId קיים, amount > 0 | 100/min per client | + +כל כניסה חוצה את הגבול ממקור חיצוני. עמודת ה"פורמט" היא מה שמפרסרים; עמודת ה"ולידציה" היא מה שדוחים; עמודת "הגבלת הכמות" היא מה שמגבילים. כניסות ללא שלושתם הן באגים שמחכים לקרות. + +### יציאות + +| שם | יעד | פורמט | SLA | +|------|-------------|--------|-----| +| Webhook ack | Stripe (HTTP response) | `200` ריק / `400` קוד שגיאה | < 100ms p95 | +| Payment notification | RabbitMQ (AMQP) | `{ event_type, payment_id, amount, timestamp }` | at-least-once, < 500ms | +| Payment response | Client app (HTTP response) | `{ paymentId, status, created_at }` | < 200ms p95 | + +כל שורת יציאה היא הבטחה לצרכן חיצוני. עמודת ה"פורמט" היא החוזה שהם תלויים בו. עמודת ה"SLA" היא ההבטחה שיחייבו אתכם לעמוד בה. + +## אילוצים ו-Invariants: הגדרת נכונות + +אילוצים מגבילים *פעולות* (לעולם אל תעשה X). Invariants מתארים *state* קבוע (X תמיד נכון). יחד הם מגדירים מה "נכון" אומר למערכת שלכם. + +### אילוצים + +| ID | כלל | מאומת על ידי | נתונים | עומס | +|----|------|-------------|------|--------| +| C-001 | לעולם אל תעבד webhook כפול | Unique constraint על stripe_event_id | 10K אירועים סינתטיים, 5% כפולים | 100 מסירות מקבילות | +| C-002 | לעולם אל תסמוך על webhook לא חתום | אימות חתימה לפני עיבוד | payloads תקינים + מזויפים | — | +| C-003 | לעולם אל תרשום מספרי כרטיס | סורק PCI compliance ב-CI | payloads המכילים PAN data | — | + +עמודות **נתונים** ו**עומס** הופכות אילוץ ממשאלה לדרישה שניתן לבדוק. "לעולם אל תעבד כפולים" היא מדיניות. "לעולם אל תעבד כפולים, מאומת עם 10K אירועים ב-100 מסירות מקבילות" היא דרישה הנדסית עם תוכנית אימות. (שימו לב ש-C-001 ו-C-002 מתחקים חזרה ל[הנחות צד שלישי](#הנחות-צד-שלישי)—הם קיימים *בגלל* סמנטיקת המסירה והחתימה של Stripe, לא כבחירות אבטחה שרירותיות.) + +במהלך המימוש, IDs אלה מהגרים לקוד כהערות מובנות ([שיעור 11](/docs/practical-techniques/lesson-11-agent-friendly-code#comments-as-context-engineering-critical-sections-for-agents)): + +```typescript +// C-001: NEVER process duplicate webhook — idempotency via unique constraint on stripe_event_id +// C-002: NEVER trust unsigned webhook — HMAC-SHA256 validation before any processing +export async function handleWebhook(req: Request): Promise { + verifySignature(req) // C-002 + if (await isDuplicate(req.body.id)) return new Response(null, { status: 200 }) // C-001 + // ... +} +``` + +טבלת ה-spec היא מקור האמת היחיד בזמן הדיזיין. הערות הקוד הופכות למקור האמת היחיד אחרי המימוש. זה מה שהופך את [מחיקת ה-spec](/docs/practical-techniques/lesson-12-spec-driven-development) לבטוחה—האילוצים הִגרוּ אל הקוד. + +### Invariants + +| ID | תנאי | טווח | מתבטא על ידי | +|----|-----------|-------|---------------| +| I-001 | `payment.status IN (pending, processing, succeeded, failed)` | PaymentIntent | הכנס status לא תקין, ודא דחייה | +| I-002 | `webhook.processed_at IS NULL OR webhook.event_id IS UNIQUE` | WebhookEvent | עבד אותו אירוע פעמיים, ודא רשומה בודדת | +| I-003 | `SUM(transactions) = account.balance` | Account ledger | צור 1K טרנזקציות, ודא סכום אחרי כל batch | + +עמודת ה**מתבטא על ידי** עונה איך טסט מפעיל את ה-invariant. בלעדיו, invariants הם assertions שאף אחד לא בודק. הפרת invariant אומרת שמודל הנתונים שלכם פגום—ודאו שאתם יכולים לזהות את זה. + +## אימות התנהגות: תרחישים קונקרטיים בגבולות + +אילוצים אומרים לעולם לא. Invariants אומרים תמיד. אף אחד מהם לא עונה: מה *צריך* לקרות כש-`amount=0`? + +תרחישים התנהגותיים ממלאים את הפער הזה—דוגמאות Given-When-Then קונקרטיות בגבולות המערכת, ספציפיות מספיק להפוך לטסטים בלי להכתיב framework, mocks, או תחביר assertion. + +| ID | Given | When | Then | קטגוריית הגבול | +|----|-------|------|------|---------------| +| B-001 | PaymentIntent במצב `pending` | Webhook מעביר `succeeded` עם amount=0 | מעבר ל-`succeeded`, balance ללא שינוי | boundary value | +| B-002 | אין PaymentIntent תואם | Webhook מעביר אירוע תקין ל-intent לא ידוע | החזר 200, רשום warning, אין שינוי state | null / missing | +| B-003 | Stripe API מחזיר 503 | לקוח שולח בקשת תשלום | החזר 502, העמד בתור ל-retry, לא נוצר charge | error propagation | +| B-004 | שני webhooks זהים תוך 10ms | שניהם עוברים אימות חתימה | הראשון מעובד, השני מחזיר 200, אין שינוי state | concurrency | + +כל תרחיש מקושר חזרה לאילוץ או לinvariant. למשל B-001 מפעיל את I-003 (שלמות balance), B-004 מפעיל את C-001 (אין עיבוד כפול). עמודת **קטגוריית הגבול** היא צ'קליסט שיטתי: boundary values, null/empty, error propagation, concurrency, temporal. עברו על כל קטגוריה לכל ממשק; שגיאות מתרכזות בגבולות[^2] כי סוכנים לא מסיקים אותן באופן אמין. + +ה-spec מתאר *מה צריך לקרות*, לא *איך לבדוק את זה*. בחירת פריימוורק, קונפיגורציות mock, וסינטקס של assertion שייכים למימוש—הם משתנים עם בסיס הקוד. דוגמאות התנהגותיות שורדות ריפקטורינג. + +## תכונות איכות: כמה טוב זה מספיק טוב? + +תכונות איכות מגדירות ספי מדידה בשלוש רמות: יעד (פעולות רגילות), ירידה בביצועים (התראות), וכישלון (פתיחת קריאה לטיפול). + +| תכונה | יעד | ירידה בביצועים | כישלון | מדידה | +|-----------|--------|----------|---------|-------------| +| Latency p95 | 100ms | 200ms | 1s | APM traces | +| Availability | 99.9% | 99.5% | 99% | uptime/month | +| Recovery | 15min | 30min | 1h | incident drill | + + שלוש רמות נותנות לכם תקציב לתקלות לפני ה-outage הראשון והופכות "מספיק טוב" למשהו קונקרטי במקום שאיפה ערטילאית. + +## תקציב ביצועים: פירוק SLOs + +תכונות איכות אומרות "Latency p95: 100ms." אבל לתהליך ה-webhook יש חמישה צעדים. איזה צעד מקבל כמה מילישניות? + +| צעד זרימה | תקציב | Hot/Cold | +|-----------|--------|----------| +| אימות חתימה | 2ms | hot | +| בדיקת Idempotency - מניעת טיפול כפול (Redis) | 5ms | hot | +| Parse + validate payload | 3ms | hot | +| עדכון state תשלום (DB) | 15ms | hot | +| פרסום אירוע (queue) | 5ms | cold | +| **סה"כ** | **30ms** | | +| **מרווח** | **70ms** | | + +התקציב מכריח שתי החלטות שסוכנים לא יכולים לקבל לבד. ראשית, *hot vs. cold path*: אימות חתימה הוא סינכרוני וחוסם—הוא מקבל תקציב צמוד. פרסום אירועים הוא אסינכרוני — הוא סובל יותר. שנית, *מרווח (headroom)*: הסה"כ הוא 30ms מול SLO של 100ms, משאיר 70ms לפעולות עתידיות בנתיב הזה. ללא פירוק, סוכן עשוי לבזבז את כל התקציב על query לא אופטימלי בודד. + +תקציבים לכל פעולה גם מעלים אילוצים אלגוריתמיים. אם "בדיקת idempotency" חייבת להסתיים ב-5ms, זה שולל full-table scan—הסוכן יודע להשתמש ב-indexed lookup או bloom filter בלי שיגידו לו. + +## תרשימי זרימה: מעקב אחר ביצוע + +תרשימי זרימה עוקבים אחר ביצוע מהטריגר עד להשלמה, הם חושפים נקודות אינטגרציה ופערים בטיפול בשגיאות. + + + +לכל צעד יש שלושה חלקים: מה קורה, מה קורה בהצלחה, מה קורה בכישלון. תרשימי זרימה מכריחים אתכם לחשוב על נתיב הביצוע בפועל, לא אבסטרקציה אידיאלית של ה-happy path. + +## אבטחה ואובזרבביליות (Observability): תכונות מערכת + +אלה לא פיצ'רים שמוסיפים בדיעבד— אלה תכונות מערכת שנובעות מגבולות נכונים ומכשור (Instrumentation) נכון. + +### אבטחה + +איפה האמון נגמר? במה תוקף יכול לשלוט? + +| איום | מיטיגציה | +|--------|------------| +| Webhook מזויף | אימות חתימה עם STRIPE_WEBHOOK_SECRET | +| התקפת replay | בדיקת idempotency על event_id | +| חשיפת secrets | Secrets מ-env vars, לעולם לא נרשמים | + +:::tip צ'קליסט מעמיק לאבטחה +למערכות עם attack surface משמעותי, ציינו גם: **Authentication** (איך זהויות מאומתות?), **Authorization** (מי יכול לעשות מה? default deny), **הגנת נתונים** (מה PII? מוצפן at rest? מדיניות retention?). ראו את [התבנית המלאה](/prompts/specifications/spec-template) לפורמט המלא. +::: + +### אובזרבביליות - היכולת להבין את מצב המערכת + +איך יודעים שזה עובד? + +| מטריקה | סוג | סף התראה | +|--------|------|-----------------| +| webhook_processing_duration | histogram | p99 > 5s | +| payment_success_rate | gauge | < 95% over 5min | +| duplicate_webhook_rate | counter | > 10/min | + +:::tip צ'קליסט מעמיק לאובזרבביליות +למערכות קריטיות של פרודקשן, ציינו גם: **Logging** (פורמט מובנה, correlation IDs, redaction של PII), **SLOs** (יעדי availability/latency, התראות burn-rate), **Tracing** (תקן propagation, אסטרטגיית דגימות, ספאנים מרכזיים. ראו את [התבנית המלאה](/prompts/specifications/spec-template) לפורמט המלא. +::: + +## Deployment ואינטגרציה: הגבול התפעולי + +איך מערכת מגיעה לפרודקשן ואיך היא מתנהגת כשתלויות נכשלות—אלה חלק מה-spec בדיוק כמו הלוגיקה העסקית. + +### אסטרטגיית Deployment + +ציינו את שיטת הפריסה לפרודקשן (blue-green, canary, rolling), טריגרים ל-rollback (אילו מטריקות גורמות ל-auto-rollback?), וגישת מיגרציה (שינויי schema תואמים לאחור לכמה זמן?). החלטות אלו משפיעות על מבנה הקוד—canary deployments דורשים פיצ'ר-פלֶגס; rolling updates דורשים APIs תואמים לאחור. + +### תלויות אינטגרציה + +| שירות | חוזה | בכישלון | Timeout | +|---------|----------|------------|---------| +| Stripe API | REST, idempotency key | העמד בתור ל-retry, degrade לידני | 5s, circuit breaker ב-50% כישלון | + +Circuit breakers, timeouts, ומצבי fallback מגדירים איך המערכת שלכם מתדרדרת בחן (Graceful Degradation). בלעדיהם, תלות איטית אחת יכולה להוביל לנפילה מלאה. מצבי כישלון תפעוליים אלה מממשים את [ההנחות הארכיטקטוניות](#הנחות-צד-שלישי) שהוצהרו קודם—ה-circuit breaker קיים כי הנחתם ~99.99% זמינות, לא 100%. + +## המטרה היא להתכנס, אל תספרו מעברים + +ה-spec הוא היפותזה. הקוד הוא ניסוי. הולידציה היא תצפית או תובנה. זו השיטה המדעית מיושמת להנדסה—והיא מסתיימת בהתכנסות (Convergence), לא במספר מעברים קבוע מראש. + +תמיד התחילו עם שלושה חלקים: **ארכיטקטורה**, **ממשקים**, ו**סטייט**. חוללו מעבר ראשון. ואז שאלו שאלה אחת: **האם הארכיטקטורה תקינה?** + +- **כן** ← תקנו את הקוד. הסוכן עשה שגיאה מכנית - תקנו את המימוש. +- **לא** ← תקנו את ה-spec וייצרו מחדש. אל תעשו איזה האק בקוד בתוך גבולות פגומים. + +כל לולאה דרך המחזור הזה חושפת מה ה-spec החמיץ. המעבר הראשון עשוי לחשוף אילוצי מקביליוּת. המעבר השני עשוי להעלות צוואר בקבוק בביצועים—הוסיפו תקציב ביצועים. הקוד *מושך* עומק מכם; אתם לא דוחפים עומק עליו על ידי קטגוריזציה של מורכבות מראש. אי אפשר לדעת אילו חלקים חשובים לפני שהקוד מראה לכם איפה הפערים[^4]. + +**סיימתם כשהלולאה לא מייצרת פערים חדשים:** הקוד עובר את כל התרחישים ההתנהגותיים, ה-spec מכסה את כל האילוצים שהקוד חשף, והמעבר האחרון לא מעלה דבר חדש. זה תנאי סיום בר בדיקה. פיצ'ר פשוט מתכנס בלולאה אחת. שינוי ארכיטקטוני מורכב עשוי לקחת חמש. אבל מגלים עם איזה מהם מתמודדים *על ידי הרצת הלולאה*, לא על ידי חיזוי. + +**מהירות איטרציה היא המכפיל.** קידוד מתקרב לעידן של שפע, פוסט-מחסור (Post-Scarcity)[^1]—המשאב הנדיר הוא שיקול הדעת שלכם לגבי *מה* לבנות. המהנדס שמריץ עשר לולאות היפותזה←ניסוי←ולידציה ביום עולה על מי שמריץ שתיים עם spec יסודי יותר מראש[^4][^5]. זו אותה תובנה שגרמה ל-Agile להיות טוב יותר מ-Waterfall. השתמשו ב[תכנון בגישת החקירה](/docs/methodology/lesson-3-high-level-methodology#שלב-2-תכנון-החלטה-אסטרטגית) (שיעור 3) ו-[ArguSeek](/docs/methodology/lesson-5-grounding#arguseek-isolated-context--state) (שיעור 5) למחקר לפני כל לולאה. לעבודה ברמת מערכת, התחילו מ[התבנית המלאה](/prompts/specifications/spec-template). ולידציה דרך [תהליך SDD](/docs/practical-techniques/lesson-12-spec-driven-development)—נתחו פערים, ממשו, ואז מחקו את ה-spec. הדברים ששורדים הם מחיקה: IDs של אילוצים שמוטבעים אל הקוד ([שיעור 11](/docs/practical-techniques/lesson-11-agent-friendly-code#comments-as-context-engineering-critical-sections-for-agents)), והשאריות הקטנות של ה"למה" (אלטרנטיבות שנדחו, רציונל עסקי) שנשמרות כ-decision records. + +:::info חלקי תבנית שלא כוסו +[תבנית ה-spec המלאה](/prompts/specifications/spec-template) כוללת חלקים שלא נלמדו בשיעור זה: **רקע** (הצהרת בעיה + מטריקות baseline), **Caching** (אסטרטגיה/TTL/invalidation), **Endpoints** (פרטי חוזה REST), **Cleanup Flows** (רצפי teardown/rollback), **Code Traceability** (עמודות ראיה file:line). השתמשו בהם כשהקוד מושך אותם מכם—לא לפני. +::: + +## נקודות מפתח + +- **Specs הם עדשת זום, לא תוכניות מתאר** — דלגו בין ארכיטקטורה ממבט ציפור לבין מימוש ברמת הפרטים. + +- **Spec = היפותזה, קוד = ניסוי** — כל לולאה דרך המחזור בודקת האם ההנחות הארכיטקטוניות שלכם מחזיקות. עיצרו כשהלולאה לא מייצרת פערים חדשים. + +- **דיוק מתגלה עם הזמן, לא כתוב מראש** — כל מעבר spec←קוד חושף פערים שה-spec הקודם החמיץ. הקוד מושך עומק מכם. + +- **מהירות איטרציה היא המכפיל** — קוד הוא זול, שיקול דעת נדיר. שימו דגש על לולאות "היפותזה←ניסוי←ולידציה" לכל יום, ולא על יסודיות ה-spec בכל לולאה. + +- **ארכיטקטורה הופכת מבנה למפורש** — מודולים בעלי אחריות בודדת, גבולות מונעים תלות, חוזים מגדירים תקשורת. + +- **הנחות צד שלישי הן מניעים ארכיטקטוניים** — הפכו אותן למפורשות כדי שסוכנים ידעו אילו החלטות לבחון מחדש כשספקים משתנים. + +- **מידול state מעצב קוד מעברים** — בחרו מודל דקלרטיבי, event-driven, או מכונת מצבים לכל ישות. + +- **תקנו specs לארכיטקטורה, תקנו קוד לבאגים** — גבולות פגומי-> ג'נרטו מחדש מ-spec מעודכן; שגיאות מכניות -> תקנו את המימוש. + +- **מחקו את ה-spec כשסיימתם** — הקוד הוא מקור האמת. + +--- + +[^1]: Xu et al. (2025) - "When Code Becomes Abundant: Implications for Software Engineering in a Post-Scarcity AI Era" - טוען שהנדסת תוכנה עוברת מפרודקשן לאורקסטרציה + ולידציה כש-AI הופך פרודקשן קוד לזול. מקור: [arXiv:2602.04830](https://arxiv.org/html/2602.04830v1) +[^2]: מחקר Boundary Value Analysis מראה באופן עקבי ששגיאות מתרכזות בקצוות קלט (min, max, off-by-one). ראו Ranorex — ["What Is Boundary Value Analysis in Software Testing?"](https://www.ranorex.com/blog/boundary-value-analysis) ו-NVIDIA — ["Building AI Agents to Automate Software Test Case Creation"](https://developer.nvidia.com/blog/building-ai-agents-to-automate-software-test-case-creation) (HEPH framework ל-AI-driven positive/negative test specification). +[^3]: Cockburn, Alistair / Larman, Craig — "Protected Variation: The Importance of Being Closed" (IEEE Software). מנסח מחדש את Open-Closed Principle כ: "זהו נקודות של וריאציה צפויה וצרו ממשק יציב סביבן." ראו גם Fowler, Martin — [YAGNI](https://martinfowler.com/bliki/Yagni.html) להבחנה בין פיצ'רים presumptive ל-known. +[^4]: Eberhardt, Colin (2025) — ["Putting Spec Kit Through Its Paces: Radical Idea or Reinvented Waterfall?"](https://blog.scottlogic.com/2025/11/26/putting-spec-kit-through-its-paces-radical-idea-or-reinvented-waterfall.html) — מצא ש-iterative prompting ~10x יותר מהיר מ-specification-driven development. Li et al. (2025) — "Specine: An AI Agent That Writes Your Spec" ([arXiv:2509.01313](https://arxiv.org/abs/2509.01313)) — מאשר ש-LLMs טועים בתפיסת איכות specification, דורש iterative alignment. +[^5]: Lloyd, Zach (2025) — [ראיון First Round Capital](https://www.firstround.com/ai/warp) — משווה specs מבוססי outcome מראש ל"כתיבת design doc ענק למשהו מראש"; תומך בהנחיית agent איטרטיבית והדרגתית במקום. Beck, Kent (2025) — ["Augmented Coding: Beyond the Vibes"](https://tidyfirst.substack.com/p/augmented-coding-beyond-the-vibes) — מדגים תוכניות שנכשלות במגע עם מורכבות המימוש; תומך במחזורי TDD הדרגתיים על פני specification מראש. diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-6-project-onboarding.md b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-6-project-onboarding.md new file mode 100644 index 0000000..1cc7f0b --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-6-project-onboarding.md @@ -0,0 +1,237 @@ +--- +sidebar_position: 1 +sidebar_label: 'שיעור 6: אונבורדינג אל הפרויקט' +title: 'שיעור 6: אונבורדינג אל הפרויקט' +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import GenerateAgentsMD from '@site/shared-prompts/\_generate-agents-md.mdx'; + +כשמצטרפים לפרויקט חדש, השבוע הראשון הוא אכזרי. את|ה שוחה בארכיטקטורה לא מוכרת, החלטות טכנולוגיות, ידע שבטי (tribal knowledge) קבור בשרשורי Slack, ואותו סקריפט bash קריטי שכולם מריצים אבל אף אחד לא תיעד. + +סוכני AI מתמודדים עם אותה בעיה—רק שהם לא יכולים לשבת על קפה עם מהנדס בכיר כדי לסגור פערים. הם רואים בדיוק מה שנמצא בחלון הקונטקסט שלהם (~200K טוקנים) ותו לא. אין זיכרון משיחת אתמול. אין הבנה של "איך עושים דברים אצלנו". + +**הפתרון: לקודד את הקונטקסט של הפרויקט בקבצים היררכיים וקריאים למכונה.** + +שיעור זה עוסק בקבצי קונטקסט ובאיך לבנות אותם ברמות המשתמש, הפרויקט והמודול כדי להפוך את סוכן ה-AI שלך ממחולל קוד גנרי לאופרטור שמכיר את הפרויקט. + +## האקוסיסטם של קבצי הקונטקסט + + + +**השוואת AGENTS.md לעומת CLAUDE.md - שתי הגישות תקפות בהתאם לכלים ומורכבות הפרויקט של הצוות. להשתמש בעיצוב ניטרלי.** + + + +קבצי קונטקסט הם מסמכי Markdown שמזריקים ידע ספציפי לפרויקט בין פרומפט המערכת לבין הקלט שלך, נותנים לסוכני AI "זיכרון פרויקט" ללא צורך בהסברים חוזרים של הסטאק הטכנולוגי, הקונבנציות והארכיטקטורה שלך. התעשייה התכנסה על שתי גישות: `AGENTS.md` (תקן ניטרלי לספקים שעובד על פני רוב כלי ה-AI המרכזיים כמו Cursor, Windsurf, ו-GitHub Copilot) והרחבות ספציפיות לכלי כמו `CLAUDE.md` (לתכונות מתקדמות כמו קונטקסט היררכי ב-Claude Code). + + + + +`AGENTS.md` הוא התקן הניטרלי לספקים שאומץ על ידי 20,000+ פרויקטי קוד פתוח, עובד על GitHub Copilot, Cursor, Windsurf, ורוב כלי הקידוד AI אחרים (הערה: Claude Code לא תומך ב-AGENTS.md—יש להשתמש ב-CLAUDE.md במקום). יש לשמור אותו מינימלי—ה-README שלכם צריך להכיל 90% ממה ש-AI צריך; AGENTS.md מוסיף רק קונטקסט תפעולי ספציפי ל-AI כמו תצורות שרת MCP, משתני סביבה, פקודות בדיקה מותאמות להרצה לא-אינטראקטיבית, ואזהרות על תלויות לא ברורות. יש למקם אותו בשורש (תיקיית הroot של) הריפו שלכם לתאימות מקסימלית. + + + + +`CLAUDE.md` של Claude Code משתמש בקונטקסט היררכי שבו קבצים מרובים מתיקיות שונות (גלובלי `~/.claude/CLAUDE.md`, תיקיית שורש הפרויקט, תת-תיקיות) נטענים אוטומטית וממוזגים בהתבסס על תיקיית העבודה שלך, עם הוראות ספציפיות יותר שדורסות את הכלליות בעוד כללים לא מתנגשים מכל הרמות נשארים פעילים. מערכת שכבתית זו מאפשרת לך להגדיר העדפות אוניברסליות בצורה גלובלית, סטנדרטים של פרויקט בתיקיית השורש שלו, ודריסות ספציפיות למודול בתת-תיקיות—ללא שכפול כללים. + + + + +---- +**השוואה מהירה:** + +| תכונה | AGENTS.md | CLAUDE.md | +| --------------------- | -------------------------------------------------------- | ----------------------------- | +| **מיקום קובץ** | קובץ יחיד בשורש הריפוזיטורי | קבצים מרובים בכל רמה | +| **טעינת קונטקסט** | קובץ אחד בלבד | כל הקבצים הרלוונטיים ממוזגים | +| **היררכיה** | לא | כן (גלובלי ← שורש ← תת-תיקיות) | +| **התנהגות override** | לא רלוונטי (קובץ יחיד) | ספציפי עושה override לכללי | +| **התנהגות merge** | לא רלוונטי (קובץ יחיד) | כל הקבצים מוזרקים יחד | +| **תמיכת כלים** | GitHub Copilot, Cursor, Windsurf, וכו' (לא Claude Code) | Claude Code בלבד | + +**השורה התחתונה:** AGENTS.md הוא קובץ אוניברסלי אחד. CLAUDE.md היא מערכת היררכית שבה קבצים מרובים נטענים וממוזגים בהתאם לתיקיית העבודה שלך. + +:::tip אקוסיסטם מעורב: שימוש ב-Claude Code עם AGENTS.md +Claude Code הוא עוזר הקידוד AI המרכזי היחיד שלא תומך ב-AGENTS.md באופן מובנה. אם אתם עובדים בסביבה מעורבת כלים (למשל, חברי צוות משתמשים ב-Codex/Copilot בעוד אתם משתמשים ב-Claude Code), הימנעו משכפול תוכן על ידי שימוש ב-**@linking** ב-`CLAUDE.md` שלכם להפניה ל-`AGENTS.md` המשותף: + +```markdown +# CLAUDE.md - Claude-specific configurations + +@/AGENTS.md + +# Additional Claude Code-specific context below +``` + +זה מייבא את כל תוכן AGENTS.md לקונטקסט של Claude, ושומר על מקור אמת יחיד תוך תמיכה בשני פורמטי הקבצים. +::: + +:::warning שיקולי אבטחה (Security) +קבצי קונטקסט מוזרקים ישירות לפרומפטי המערכת. חוקרי אבטחה זיהו התקפות "Rules File Backdoor" שבהן הוראות זדוניות מוזרקות באמצעות תווי Unicode או טכניקות התחמקות. שמרו על קבצי קונטקסט מינימליים, מנוהלים בבקרת גרסאות, ועוברים קוד ריוויו כמו כל קוד אחר. +::: + +## קונטקסט היררכי: רמות המשתמש, הפרויקט והמודול + +קבצי קונטקסט פועלים ברמות שונות של ספציפיות. **קונטקסט גלובלי** מכיל העדפות אישיות שחלות על כל הפרויקטים שלך—סגנון קידוד, הלך רוח, כללים תפעוליים. **קונטקסט ברמת פרויקט** לוכד סטאק טכנולוגי, ארכיטקטורה, וקונבנציות ספציפיות לבסיס קוד אחד. שניהם ניתנים ליישום באמצעות `AGENTS.md` (תקן ניטרלי לספקים) או `CLAUDE.md` (מערכת היררכית של Claude Code שממזגת קבצים מרובים). + +### דוגמת קובץ לרמה הגלובלית + +קונטקסט גלובלי נמצא בתיקיית הבית שלכם וחל על כל הפרויקטים. הנה ה-`~/.claude/CLAUDE.md` האמיתי של מחבר הקורס—דוגמה מסביבת ייצור שאפשר להתאים לצרכיכם: + +```markdown +# Mindset + +You are a senior architect with 20 years of experience across all software domains. + +- Gather thorough information with tools before solving +- Work in explicit steps - ask clarifying questions when uncertain +- BE CRITICAL - validate assumptions, don't trust code blindly +- MINIMALISM ABOVE ALL - less code is better code + +# Search Protocol + +- Use ChunkHound's Code Research tool to learn the surrounding code style, architecture and module responsibilities +- PREFER THE CODE RESEARCH TOOL OVER ALL SUB AGENTS +- Use ArguSeek to read documentation and research relevant background for the task +- Search for best practices, prior art, and technical context with research_iteratively +- Use `search_semantic` and `search_regex` with small, focused queries +- Multiple targeted searches > one broad search + +# Architecture First + +LEARN THE SURROUNDING ARCHITECTURE BEFORE CODING. + +- Understand the big picture and how components fit +- Find and reuse existing code - never duplicate +- When finding duplicate responsibilities, refactor to shared core +- Match surrounding patterns and style + +# Coding Standards + +KISS - Keep It Simple: + +- Write minimal code that compiles and lints cleanly +- Fix bugs by deleting code when possible +- Optimize for readability and maintenance +- No over-engineering, no temporary compatibility layers +- No silent errors - failures must be explicit and visible +- Run tests after major changes +- Document inline when necessary + +# Operational Rules + +- Time-box operations that could hang +- Use `uuidgen` for unique strings +- Use `date +"%Y-%m-%dT%H:%M:%S%z" | sed -E 's/([+-][0-9]{2})([0-9]{2})$/\1:\2/'` for ISO-8601 +- Use flat directories with grep-friendly naming +- Point out unproductive paths directly + +# Critical Constraints + +- NEVER Commit without explicit request +- NEVER Leave temporary/backup files (we have version control) +- NEVER Hardcode keys or credentials +- NEVER Assume your code works - always verify +- ALWAYS Clean up after completing tasks +- ALWAYS Produce clean code first time - no temporary backwards compatibility +- ALWAYS Use sleep for waiting, not polling +``` + +### דוגמת קובץ לרמת הפרויקט + +קונטקסט ברמת פרויקט מכיל את מה שחבר צוות חדש צריך כדי להיות פרודוקטיבי בשעה הראשונה: פרטי הסטאק הטכנולוגי, פקודות נפוצות, ידע שבטי, וקונבנציות קידוד. הנה ה-`CLAUDE.md` האמיתי מהריפו של הקורס הזה: + +````markdown +# AI Coding Course - Project Context + +## Mindeset + +You are an expert technical writer specializing in explaining complex topics to experienced software engineers. + +## Project Overview + +This is an **AI Coding Course designed for Senior Software Engineers**. The course teaches experienced developers how to effectively leverage AI coding assistants in production environments. + +**Target Audience:** Senior engineers with 3+ years of professional experience +**Estimated Course Duration:** 24-33 hours of hands-on training + +## Technology Stack + +**Platform:** Docusaurus 3.9.2 (Static site generator) +**Languages:** TypeScript 5.6.2, React 19.0 +**Key Features:** + +- Live code blocks with `@docusaurus/theme-live-codeblock` +- MDX support for interactive components +- Full-text search with `@easyops-cn/docusaurus-search-local` +- Versioning system for content snapshots + +## Development Commands + +```bash +# Development +cd website && npm start # Start dev server (localhost:3000) +npm run build # Production build +npm run serve # Preview production build locally + +# Deployment +npm run deploy # Deploy to GitHub Pages +``` + +## Tone & Communication Style + +**Coworker-level communication** - Professional, direct, no hand-holding + +- Assume strong fundamentals (data structures, design patterns, system design) +- Skip basic explanations - link to external docs if needed +- Focus on practical application and production considerations +- Use industry-standard terminology without over-explaining + +## Content Philosophy + +**Production-Ready Architecture Focus** + +- Real-world examples over toy demos +- Scalability and maintainability considerations +- Security and performance implications +- Trade-offs and decision-making criteria + +**Minimalism & Clarity** + +- Concise explanations +- Code examples that compile and run +- Clear learning objectives per lesson +- Hands-on exercises with real scenarios + +## Key Configuration Files + +- `website/docusaurus.config.ts` - Site configuration +- `website/sidebars.ts` - Auto-generated from docs structure +- `website/package.json` - Dependencies and scripts +- `.github/workflows/deploy.yml` - GitHub Pages deployment + +## Deployment + +- **Platform:** GitHub Pages +- **URL:** https://agenticoding.ai +- **Trigger:** Automatic on push to main branch +- **Base URL:** `/` +```` + +## יצירה אוטומטית: Bootstrap עם AI + +**מהלך העל: יישום החומר משיעורים 3-5 כדי לייצר קבצי קונטקסט בצורה אוטומטית.** במקום לכתוב ידנית `AGENTS.md` או `CLAUDE.md`, השתמשו בתהליך העבודה בארבעה שלבים ([שיעור 3](/docs/methodology/lesson-3-high-level-methodology)) כדי לתת לסוכנים לעשות bootstrap לקונטקסט שלהם. **שלב המחקר:** השתמשו בכלי `code_research` של ChunkHound להבנת הארכיטקטורה, התבניות והקונבנציות של הפרויקט—שאלו על ארכיטקטורה, סגנונות קידוד, אחריות מודולים, וקונבנציות בדיקה, וכו' לבניית הבנה ארכיטקטונית מקיפה. השתמשו ב-`research_iteratively` ו-`fetch_url` של ArguSeek להבאת תיעוד הפריימוורק, שיטות עבודה מומלצות, והנחיות אבטחה רלוונטיות לסטאק הטכנולוגי שלכם. **שלב התכנון:** הסוכן מסנתז תובנות מבסיס הקוד (מ-ChunkHound) וידע תחומי (מ-ArguSeek) לתוכנית קובץ קונטקסט מובנית. **שלב הביצוע:** צרו את קובץ הקונטקסט באמצעות טכניקות אופטימיזציית פרומפט ספציפיות למודל שלכם. **שלב האימות:** בדקו את הקונטקסט שנוצר עם משימה טיפוסית, ועשו איטרציה על סמך פערים. +
+ +
+ +הפרומפט הזה מדגים עיגון ([שיעור 5](/docs/methodology/lesson-5-grounding)): ChunkHound מספק קונטקסט ספציפי לבסיס הקוד, ArguSeek מספק ידע אקוסיסטם עדכני, ושרשרת חשיבה מובנית מבטיחה שהסוכן עוקב אחר נתיב שיטתי. התוצאה: קבצי קונטקסט מוכנים לסביבת ייצור שנוצרו באיטרציה אחת, במקום לאסוף חוקים והוראות ידנית לאורך שבועות. הוסיפו ידע שבטי ידנית אחר כך—תקלות ייצור, קונבנציות צוות, מלכודות נסתרות שרק בני אדם מכירים. + +:::tip הפניה +ראו את תבנית הפרומפט המלאה עם הנחיות אימות והתאמות: [Generate AGENTS.md](/prompts/onboarding/generate-agents-md) +::: + +--- + +**הבא:** [שיעור 7: תכנון וביצוע](./lesson-7-planning-execution.md) diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-7-planning-execution.md b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-7-planning-execution.md new file mode 100644 index 0000000..480db03 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-7-planning-execution.md @@ -0,0 +1,251 @@ +--- +sidebar_position: 2 +sidebar_label: 'שיעור 7: תכנון וביצוע' +title: 'תכנון וביצוע' +--- + +[שיעור 5: עיגון](../methodology/lesson-5-grounding.md) כיסה איך RAG וחיפוש סמנטי מאפשרים לסוכנים לאחזר קונטקסט מקוד הבסיס שלכם ומהרשת. שיעור זה מתמקד במה שקורה במהלך תכנון וביצוע—איך לעגן באופן פעיל את הסוכן בזמן שאתם עובדים, איך לסקור את התכנון שלו לפני ביצוע אוטונומי, ואיך להגדיר workflows שתומכים בפיתוח מקבילי על פני מספר מופעים של סוכנים. + +המעבר מאיסוף קונטקסט לשימוש בקונטקסט הוא קריטי. עיגון אינו פעילות חד-פעמית מראש—הוא רציף. אתם טוענים קונטקסט, סוקרים את תוכנית הסוכן, נותנים לו לבצע, ואז מאמתים. כשמשהו לא מתאים למודל המנטלי שלכם, אתם עוצרים ומבהירים. כשהסוכן מציע שכפול, אתם אוכפים DRY. שיעור זה מכסה את הטכניקות הטקטיות שהופכות סוכנים ממחוללי קוד למכונות יצור קוד אמינות. + +## טיפים לעיגון: הנדסת קונטקסט פעילה + +ביצוע אפקטיבי דורש ניהול קונטקסט מכוון. טכניקות אלה שומרות את הסוכן מעוגן בקוד הבסיס האמיתי שלכם, לא בדפוסים סטטיסטיים מנתוני אימון. + +### תמיד לעגן בקוד + +הראו לסוכנים דפוסים אמיתיים מקוד הבסיס שלכם, לא תיעוד גנרי. תיאורים מופשטים מובילים לפתרונות גנריים שלא מתאימים לקוד הבסיס הספציפי שלכם. + +**דוגמה:** אתם צריכים להוסיף rate limiting ל-API שלכם. אל תכתבו פרומפט כמו "Add rate limiting middleware." במקום זאת השתמשו בפרומפט שמעגן את הסוכן לקוד שלכם: +
+"Search for existing middleware patterns, especially authentication. Check our Redis configuration. +Then propose rate limiting that follows the same error handling, export structure, and Redis client usage you found." +
+ +הסוכן יחפש קבצי middleware, יקרא את תצורת Redis שלכם, ינתח את הדפוסים שלכם, ויציע יישום שמתאים לקונבנציות המבוססות שלכם. הוראות קונקרטיות מנצחות פרומפט מופשט. + +### פרומפט להסבר: טעינת קונטקסט לחלון + +כשאתם שואלים "?How does X work", אתם לא בודקים את הידע של הסוכן—אתם מפעילים רצף שטוען קונטקסט לחלון לשלבים הבאים. + +**המנגנון:** "Explain how our authentication middleware works" גורם לסוכן: + +1. לחפש בקוד הבסיס קבצים הקשורים לאימות +2. לקרוא יישומי middleware +3. לנתח דפוסים ומבנה +4. לסנתז ממצאים + +הסינתזה הזו עכשיו נמצאת בחלון הקונטקסט. כשאתם ממשיכים עם "Add rate limiting following the same pattern," לסוכן כבר יש מבנה middleware, קונבנציות טיפול בשגיאות, דפוסי export, ושימוש בתלויות טעונים בקונטקסט. הוא לא צריך לחפש שוב—הידע הרלוונטי כבר נוכח. + +**שאלות הן כלי הנדסת קונטקסט.** אתם מכינים בכוונה את זיכרון העבודה של הסוכן לפני בקשת אימפלמנטציה. זה יעיל יותר מאריזת הכל לפרומפט ענקי אחד ואמין יותר מלקוות שהסוכן יחפש את הדברים הנכונים באופן אוטונומי. + +:::tip ביצוע אוטונומי בטוח +שאלות בטוחות לביצוע אוטונומי—הן פעולות קריאה בלבד עם סיכון מינימלי. הגדירו את הסוכן שלכם למצב "אישור נדרש" כדי לאכוף זאת (הוא ישאל לפני ביצוע שינויים). אם ההסבר של הסוכן שגוי או לא שלם, פשוט התעלמו ממנו, שפרו את הפרומפט שלכם, ונסו שוב. רצף מעוצב היטב של שאלות חקירה הופך את משימות הקידוד האוטונומיות הבאות לאמינות הרבה יותר כי חלון הקונטקסט כבר טעון במידע מעוגן לקוד הבסיס האמיתי שלכם. +::: + +### דרשו ראיות כדי לכפות עיגון + +דרישת ראיות באופן מפורש מאלצת סוכנים לקרוא את הקוד האמיתי שלכם במקום לייצר ניחושים שנשמעים סבירים על בסיס דפוסים מנתוני האימון. + +**המנגנון:** כשאתם דורשים "evidence (file paths, line numbers, actual values)" בפרומפט שלכם, הסוכן לא יכול לספק ראיות אלה מבלי ממש לאחזר אותן. זה הופך מה שעלול היה להיות הזיה לתגובה מעוגנת בקוד הבסיס שלכם. + +**ללא דרישת ראיות:** + +``` +Debug the login endpoint - it's returning 500 errors +``` + +הסוכן עשוי להגיב: "Probably a database timeout or null pointer exception in the authentication logic." + +זו השלמת דפוסים מנתוני אימון, לא ניתוח של הקוד האמיתי שלכם. + +**עם דרישת ראיות:** + +``` +Debug the login endpoint - it's returning 500 errors. +Explain the root cause with evidence: file paths, line numbers, actual error messages. +``` + +עכשיו הסוכן חייב לקרוא את הקוד של ה-endpoint, לעקוב אחר הביצוע, ולצטט פרטים: +
+"The error occurs in `src/api/auth.ts:67` where `user.profile.email` is accessed. The `profile` object is null for OAuth users (see `src/services/oauth.ts:134` - profile creation is skipped for federated auth). Stack trace shows: `TypeError: Cannot read property 'email' of null`." +
+ +**מה יכול להוות ראיות טובות:** + +- **נתיבי קבצים עם מספרי שורות** - `src/auth/jwt.ts:45-67` (לא "the auth file") +- **ערכים אמיתיים מקונפיג/לוגים** - `port: 8080` (לא "a port number") +- **מזהים ספציפיים** - פונקציית `()validateJWT` (לא "the validation function") +- **הודעות שגיאה מדויקות** - stack traces מלאים או רשומות לוג (לא "an error occurred") + +**שילוב עם שרשרת חשיבה (Chain-of-Thought):** + +דרישת ראיות עובדת באופן עצמאי או בשילוב עם הוראות שלב-אחר-שלב. לדיבאג מורכב, השתמשו בשתיהן—[שרשרת חשיבה](../methodology/lesson-4-prompting-101.md#chain-of-thought-paving-a-clear-path) שולטת בנתיב הביצוע בעוד דרישת ראיות מבטיחה שכל שלב מעוגן: + +``` +Debug the failing test in UserService.test.ts: + +1. Read the test file, identify which test is failing +2. Analyze test assertion: expected vs actual values +3. Trace code path through UserService to find the bug +4. Explain root cause with evidence (file paths, line numbers) +5. Propose a fix + +Provide evidence for each step. +``` + +זה נותן לכם שליטה בביצוע (CoT) תוך אילוץ עיגון (ראיות) בכל שלב. + +### שאלו שאלות הבהרה לאתגר את הלוגיקה + +LLMs גרועים בלוגיקה—הם משלימים דפוסים על בסיס סבירות סטטיסטית, לא על בסיס חשיבה לוגית. כישורי ההנדסה שלכם עדיין נדרשים כדי לתפוס אי-עקביויות. + +כשמשהו לא מתאים למודל המנטלי שלכם, הצביעו על זה: "If X is true, how can Y happen?" + +**דוגמה:** הסוכן אומר "The config uses port 3000" אבל הלוגים שלכם מראים חיבורים על 8080. אתגרו אותו: +
+"You said port 3000, but logs show 8080. Explain this discrepancy with evidence from the config files and environment setup" +
+ +זה מאלץ את הסוכן לבחון מחדש את ההנחות שלו, לחפש יותר בזהירות, ולעגן את התגובה שלו בנתונים אמיתיים במקום השלמת דפוסים. השתמשו במודל המנטלי שלכם לאמת את ההיגיון של הסוכן. כשהלוגיקה לא מחזיקה, גרמו לסוכן להצדיק עם ראיות. + +## תכנון מפורט: סקירה לפני ביצוע + +לפני שאתם נותנים לסוכן לבצע באופן אוטונומי, סקרו את התוכנית שלו. כאן אתם תופסים אי-התאמות ארכיטקטוניות, שיקולים חסרים, ושגיאות לוגיקה—לפני שהן הופכות לקוד. + +### שימו לב לאסטרטגיה והיגיון + +**שאלות מפתח:** + +- איך הסוכן הסיק את התוכנית הזו? +- האם העיגון היה יסודי? (האם הוא קרא קבצים רלוונטיים, בדק תיעוד, הבין אילוצים?) +- האם הוא פספס שיקולים חשובים? (אבטחה, ביצועים, תאימות לאחור, מקרי קצה?) + +סקרו את ה"למה" מאחורי התוכנית, לא רק את ה"מה". אם הסוכן אומר "Implement feature X using approach Y," שאלו את עצמכם: האם הוא עיגן החלטה זו בקוד הבסיס שלכם? האם הוא שקל חלופות? האם ההיגיון מחזיק? + +**דוגמה:** הסוכן מציע לשמור בקאש סשנים של המשתמששים ב-Redis עם TTL של 24 שעות. תוכנית טובה—אבל האם הוא בדק את יישום הסשנים הקיים שלכם? האם הוא שקל תאימות GDPR לנתוני סשן? האם הוא התחשב ב-cache invalidation כשמשתמשים משנים סיסמאות? + +אם העיגון היה רדוד, עצרו והוסיפו קונטקסט לפני ביצוע: + +```markdown +Before implementing, research our existing session management, +check for compliance requirements in COMPLIANCE.md, and propose cache +invalidation strategy for security-critical events. +Use ArguSeek, validate the approach against current security best practices. +``` + +### הציצו בשינויים המוצעים + +לפני ביצוע אוטונומי, סקרו את התוכנית לתפיסת אי-התאמות ארכיטקטוניות ובעיות היקף. זה מחיל את [עקרונות האילוצים של שיעור 4](../methodology/lesson-4-prompting-101.md#constraints-as-guardrails) במהלך סקירת התוכנית—אתם מאמתים שהגישה המוצעת של הסוכן מוגבלת ומעוגנת מספיק לפני שהוא מבצע. + +**מה אתם בודקים:** + +זו התאמה ארכיטקטונית ברמה גבוהה, לא סקירת קוד שורה-אחר-שורה (אימות מגיע מאוחר יותר). אתם מבטיחים שהסוכן מעוגן בארכיטקטורה האמיתית שלכם: + +- **היצמדות לדפוסים** - האם זה מתאים לדפוסים המבוססים שלנו? (אם לא, הסוכן לא היה מעוגן בקוד קיים) +- **גבולות מודולים** - האם השינויים במודולים הנכונים? (אם לא, הסוכן לא הבין ארכיטקטורה) +- **היקף מתאים** - האם הסוכן מנסה לבצע ריפקטור לחצי מקוד הבסיס כשביקשתם תיקון ממוקד? + +**דוגמה:** הסוכן מתכנן להוסיף אימות כתובת דוא"ל על ידי יצירת ספריית אימות חדשה ב-`src/lib/validators/`. אבל כבר יש לכם סכמות Zod ב-`src/validation/`. זה כשל עיגון—הסוכן ייצר פתרון סביר מדפוסי אימון במקום לגלות את גישת האימות הקיימת שלכם ולהוסיף לה. + +עצרו ותקנו: + +```markdown +We use Zod for validation—check `src/validation/userSchema.ts` and follow that +pattern instead of creating a new library. +``` + +**למה זה חשוב:** תפיסת כשלי עיגון בשלב התכנון מהירה יותר משכתוב קוד שנוצר. אם התוכנית חושפת עיגון רדוד, הוסיפו אילוצים ואלצו מחקר עמוק יותר לפני ביצוע. + +### שימו לב: סוכנים ממציאים במקום לעשות שימוש חוזר + +**הבעיה:** כשסוכנים מתכננים יישומים, הם נוטים כברירת מחדל לייצר קוד סביר מדפוסי אימון במקום לגלות מה כבר קיים בקוד הבסיס שלכם. זו השלמת דפוסים, לא גילוי קוד קיים—הסוכן מסנתז משהו ש"נראה נכון" על בסיס מיליוני דוגמאות אימון, במקום לחפש את ה-utilities, ה-helpers, וההפשטות (abstractions) שכבר יש לכם. + +מחקרים מאשרים את ההטיה הזו: קוד שנוצר על ידי AI מכיל **פי 8 יותר בלוקים משוכפלים** מקוד שנכתב על ידי בני אדם, עם ירידה במדדי קונסולידציית קוד בכל התעשייה[^1]. סוכנים ממציאים את הגלגל מחדש כי סטטיסטית קל יותר להמציא מאשר לגלות. + +**דגלים אדומים בתוכניות:** + +שימו לב לביטויים אלה במהלך סקירת תוכנית—הם מסמנים שהסוכן ממציא במקום מגלה: + +- "Create a new utility function for..." (האם הוא חיפש כלים קיימים?) +- "Implement a helper to handle..." (האם העוזר הזה כבר קיים?) +- "Build error handling logic..." (מה עם דפוסי שגיאות קיימים?) +- "Add validation for..." (בדקו תחילה סכמות אימות קיימות) + +## נקודות שחזור: רשת הביטחון שלכם + +סוכנים עושים טעויות לעתים קרובות—במיוחד בזמן שאתם לומדים דפוסי עיגון ו-prompting אפקטיביים. החדשות הטובות: ככל שהכישורים שלכם משתפרים, הצורך ב-rollbacks יורד באופן דרמטי. באופן טבעי תכתבו פרומפטים טובים יותר, תתפסו בעיות במהלך סקירת תוכנית, ותנחו סוכנים ביעילות רבה יותר. אבל גם מתרגלים מנוסים מעריכים נקודות שחזור כרשת ביטחון. ההבדל בין סשן מתסכל לפרודוקטיבי מסתכם במהירות שבה אתם יכולים לבצע רולבק כשדברים משתבשים. קידוד אייגנטי הוא הסתברותי — אתם צריכים את היכולת להחזיר לאחור גם את קונטקסט השיחה וגם שינויי קוד כשהביצוע סוטה מהכוונה שלכם. + +קבעו קצב נקודות שחזור (checkpoints): צרו נקודת שחזור לפני פעולות מסוכנות, תנו לסוכן לבצע, אמתו תוצאות, ואז שמרו או בטלו. כלי קידוד AI מודרניים (Claude Code, Cursor, VS Code Copilot, וכו') כוללים יכולות נקודות שחזור מובנות שהופכות רולבק לפשוט —זה מאפשר לכם להתנסות באגרסיביות מבלי להמר על שינויים בלתי הפיכים. אם הכלי שלכם לא תומך בנקודות שחזור ובקרה, בצעו קומיט לעתים הרבה יותר קרובות מאשר בפיתוח מסורתי: אחרי כל תוספת או שינוי מוצלח, לפני פעולות מסוכנות, לפני ששמשנים כיוון, אחרי תיקונים ידניים. זה יוצר רשת ביטחון של נקודות שחזור מאומתות שבהן כל קומיט מייצג מצב הידוע-כטוב שאתם יכולים לחזור אליו מיד. שלב האימות (מכוסה ב[שיעור 9](./lesson-9-reviewing-code.md)) קובע אם אתם שומרים או מבטלים שינויים—נקודות שחזור הופכות את ההחלטה להפיכה. + +:::tip נקודות שחזור ב-Claude Code +לחצו ESC פעמיים ליצירת checkpoint ב-Claude Code. זה שומר גם קונטקסט שיחה וגם מצב קוד, ומאפשר לכם להתנסות באגרסיביות ולהחזיר מיד אם צריך. +::: + +## ביצוע אוטונומי: תהליכי עבודה מקבילים והגדרת כלים + +ברגע שהתוכנית נסקרה והעיגון מוצק, אתם יכולים לתת לסוכן לבצע באופן אוטונומי. עבור פיצ'רים מורכבים, ביצוע מקבילי על פני מספר מופעים של סוכנים מאיץ באופן דרמטי את הפיתוח. + +### Git Worktrees: מאפשרים מקביליות אמיתית + +Git worktrees מאפשרים תיקיות עבודה מרובות מריפו יחיד, כשכל אחת מכילה branch שונה. זה מאפשר הרצת מספר מופעים של סוכנים על משימות שונות במקביל, ללא קונפליקטים. + +**הגדרה בסיסית:** + +```bash +# Main repo in ~/project (on main branch) +git worktree add ../project-feature-auth feature/auth +git worktree add ../project-feature-api feature/api +git worktree add ../project-bugfix bugfix/login-error + +# Now you have 4 separate directories: +# ~/project (main) +# ~/project-feature-auth (feature/auth branch) +# ~/project-feature-api (feature/api branch) +# ~/project-bugfix (bugfix/login-error branch) +``` + +**הגדרה בסיוע סוכן:** + +סוכנים יכולים לעזור לייצר פקודות worktree, במיוחד כשמגדירים סביבות מקבילות מרובות. עגנו קודם עם ArguSeek לשיטות עבודה מומלצות, ואז בקשו מהסוכן לייצר פקודות. + +``` +Use ArguSeek to research git worktree best practices for parallel development. + +Create 3 worktrees with the following specifications: +1. Authentication refactor (branch: feat/auth-refactor) +2. New analytics API (branch: feat/analytics-api) +3. Dashboard performance improvements (branch: perf/dashboard) + +Output: +- Exact `git worktree add` commands for each worktree +- Recommended directory structure following best practices +``` + +הסוכן יחקור תהליכי worktree, יציע מבנה תיקיות נקי, ויייצר את הפקודות המדויקות. זה מהיר יותר מקריאת תיעוד ידנית ומבטיח שהפקודות מתאימות לקונטקסט הספציפי שלכם. + +:::tip כלים לתהליכי עבודה מקביליים +ניהול worktrees מרובים ו-sessions של סוכנים דורש כלים יעילים. ראו **[Developer Tools](/developer-tools/terminals)** להמלצות טרמינל (Ghostty, Kitty, WezTerm) ו-**[CLI Tools](/developer-tools/cli-tools)** לכלי git וניווט קבצים מודרניים (lazygit, eza, fzf). שלבו כלי CLI ו-IDE בצורה פרגמטית—השתמשו במה שהכי יעיל לכל משימה. +::: + +## נקודות מפתח + +- **שאלות טוענות קונטקסט, הן לא מאמתות ידע** - "How does X work?" מפעיל רצפי חיפוש/קריאה שממלאים את חלון הקונטקסט במידע רלוונטי לשלבי ביצוע הבאים. שאלות הן כלי הנדסת קונטקסט. + +- **דרשו ראיות כדי לכפות עיגון** - דרישת ראיות באופן מפורש (נתיבי קבצים, מספרי שורות, ערכים אמיתיים) מאלצת סוכנים לאחזר מידע במקום לנחש. הסוכן לא יכול לספק ראיות מבלי לקרוא את הקוד האמיתי שלכם, זה מחליף הזיות בתגובות מעוגנות. זה עובד גם באופן עצמאי או בשילוב עם שרשרת חשיבה למשימות מורכבות. + +- **LLMs משלימים דפוסים, לא לוגיקה** - שיקול הדעת ההנדסי שלכם מאמת התאמה ארכיטקטונית ותופס שגיאות לוגיקה. סוכנים מטפלים בתחביר ו-boilerplate; אתם מטפלים בהיגיון ונכונות. + +- **סקרו את האסטרטגיה וההיגיון של התוכנית, לא רק את הפלט** - לפני ביצוע אוטונומי, בדקו: איך התוכנית הזו נגזרה? האם העיגון היה יסודי? האם הוא פספס שיקולי אבטחה, ביצועים, או ארכיטקטורה? + +- **שימו לב להמצאה על פני שימוש חוזר במהלך סקירת תוכנית** - סוכנים מעדיפים כברירת מחדל לייצר קוד סביר מדפוסי אימון במקום לגלות קוד קיים. דגלים אדומים: "create new utility," "implement helper." התערבות: אלצו גילוי קודם עם דרישת ראיות לפני מתן אפשרות ליישום. + +- **צרו נקודת שחזור לפני ביצוע, קומיט אחרי אימות** - השתמשו בתכונות checkpointing מובנות כשזמינות (Claude Code, Copilot, Cursor). בלעדיהן, בצעו קומיט לעתים הרבה יותר קרובות מפיתוח מסורתי—אחרי כל שינוי מוצלח, לפני פעולות מסוכנות. סוכנים עושים טעויות תכופות; נקודות שחזור הופכות איטרציה למהירה והפיכה. + +- **Git worktrees מאפשרים מקביליות אמיתית** - תיקיות עבודה מרובות מריפוזיטורי יחיד מאפשרות לכם להריץ מופעים מקבילים של סוכנים על branch-ים שונים ללא קונפליקטים. השתמשו בסוכנים לייצר פקודות הגדרת worktree מעוגנות בשיטות עבודה מומלצות. + +--- + +**הבא:** [שיעור 8: בדיקות כמעקות בטיחות](./lesson-8-tests-as-guardrails.md) + +[^1]: GitClear (2025) - ניתוח של 211 מיליון שורות קוד (2020-2024) המראה עלייה פי 8 בבלוקי קוד משוכפלים (5+ שורות משוכפלות) בקוד שנוצר על ידי AI. מקור: [LeadDev: How AI-generated code accelerates technical debt](https://leaddev.com/technical-direction/how-ai-generated-code-accelerates-technical-debt) diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-8-tests-as-guardrails.md b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-8-tests-as-guardrails.md new file mode 100644 index 0000000..36834ba --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-8-tests-as-guardrails.md @@ -0,0 +1,218 @@ +--- +sidebar_position: 3 +sidebar_label: 'שיעור 8: טסטים כמעקות בטיחות' +title: 'שיעור 8: טסטים כמעקות בטיחות' +--- + +import ThreeContextWorkflow from '@site/src/components/VisualElements/ThreeContextWorkflow'; +import EdgeCaseDiscovery from '@site/shared-prompts/\_edge-case-discovery.mdx'; +import TestFailureDiagnosis from '@site/shared-prompts/\_test-failure-diagnosis.mdx'; + +סוכני AI יכולים לבצע ריפקטור לחצי מקוד הבסיס שלכם בתוך דקות. הם ישנו שמות פונקציות, יארגנו מחדש מודולים, ויעדכנו עשרות קבצים—הכל בזמן שהלכתם להביא קפה. מהירות זו חזקה, אבל מסוכנת. שגיאות לוגיקה קטנות מצטברות מהר כששינויים קורים בקנה מידה גדול. + +הטסטים הם מערכת האילוצים שלכם. הטסטים, או **הבדיקות האוטומטיות** שלכם מגדירות גבולות תפעוליים שסוכנים לא יכולים לחצות. חשוב מכך, הן תיעוד חי שסוכנים קוראים כדי להבין כוונה, מקרי קצה, ומלכודות שידע שבטי (tribal knowledge) בדרך כלל מכסה. + +## בדיקות אוטומטיות כתיעוד: מה סוכנים באמת קוראים + +לפני שסוכנים כותבים קוד, הם חוקרים—מחפשים קבצים רלוונטיים וקוראים יישומים. גם קוד מקור וגם קוד בדיקות נטענים לחלון הקונטקסט במהלך שלב המחקר הזה. בדיקות אינן תיעוד שסוכנים "לומדים" ממנו; הן אילוצים קונקרטיים שמעגנים את שלבי היישום הבאים בקוד הבסיס האמיתי שלכם במקום בדפוסים סטטיסטיים מנתוני אימון. + +בדיקות טובות מספקות עיגון. הן מראות שמשתמשי OAuth מדלגים על אימות דוא"ל, שתאריכים מטופלים עבור בעיות אזורי זמן, שכמויות שליליות נדחות. כשבדיקות אלה קיימות בקונטקסט, החלטות יישום מוגבלות על ידי דוגמאות קונקרטיות מקוד הבסיס שלכם. בדיקות גרועות מזהמות קונטקסט. בדיקות בשם `test('works')` עם assertions לא ברורים, או בדיקות שעושות mock להתנהגות אמיתית, ממלאות את חלון הקונטקסט ברעש. כש-50 בדיקות נטענות לקונטקסט לפני ריפקטור של auth, האיכות שלהן קובעת אם היישום של הסוכן מעוגן באילוצים שלכם או משלים דפוסים מאימון. + +### מחקר קודם: גילוי מקרי קצה דרך שאלות + +לפני כתיבת בדיקות, יש להשתמש בטכניקות התכנון מ[שיעור 7](./lesson-7-planning-execution.md) כדי לגלות מה צריך לבדוק. שאלות טוענות פרטי יישום ומקרי קצה קיימים לקונטקסט. + +**דפוס פרומפט לגילוי מקרי קצה:** +
+ +
+ +הסוכן מחפש את הפונקציה, קורא את המימוש, מוצא קוד של בדיקות קיימות, ומסנתז ממצאים משלב 1. זה טוען אילוצים קונקרטיים לקונטקסט: משתמשי OAuth מדלגים על אימות דוא"ל, משתמשי admin עוקפים rate limits, משתמשים שנמחקו נדחים. שלב 2 מנתח את המימוש מול השאלות שלכם ומזהה נתיבים לא נבדקים. עכשיו יש לכם רשימה מעוגנת של מקרי קצה שנגזרו מקוד אמיתי, לא עצות בדיקה גנריות. + +:::tip הפניה +ראו את תבנית הפרומפט המלאה עם דוגמאות והתאמות נוספות: [Edge Case Discovery](/prompts/testing/edge-case-discovery) +::: + +### לולאה סגורה: לפתח קוד לצד בדיקות + +כשקוד ובדיקות נוצרים באותו קונטקסט—אותה שיחה, מצב היגיון משותף—הם יורשים את אותן הנחות ונקודות עיוורון, ויוצרים ["מחזור של הונאה עצמית"](https://arxiv.org/html/2506.18315v1). למשל, סוכן עשוי לממש API endpoint שמקבל מספרים שליליים או אפס ככמות מוצרים, ואז לייצר בדיקות באותו סשן שמאמתות שהוספת אפס פריטים מצליחה. שני ה-artifacts נובעים מאותו היגיון פגום: אף אחד לא שאל אם כמויות חייבות להיות חיוביות. הבדיקה עוברת, הבאג נשאר לא מזוהה. בקנה מידה גדול, זה מצטבר: סוכנים עוסקים ב"specification gaming," מחלישים assertions או מוצאים קיצורי דרך להשיג ✔️ ירוקים. מחקר מראה שזה [קורה בכ-1% ממחזורי יצירת בדיקה-קוד](https://arxiv.org/html/2510.23761v1), אבל מצטבר על פני בסיסי קוד גדולים. + +:::warning חוק Goodhart בפעולה + +כשבדיקות הופכות ליעד האופטימיזציה, סוכנים מאופטמים למעבר בדיקות במקום לנכונות. ללא אמצעי הגנה, מקבלים assertions חלשים יותר, קוד עם המון באגים, וצינורות CI ירוקים שמאמתים התנהגות שגויה. זה חוק Goodhart: "כשמדד הופך ליעד, הוא חדל להיות מדד טוב." הפתרון דורש circuit breaker שמונע התכנסות לתוצרים תואמים-הדדית-אך-שגויים. + +::: + +יש להחיל את אותה מתודולוגיית תכנון וביצוע מ[שיעור 7](./lesson-7-planning-execution.md) לכל שלב—כתיבת קוד, כתיבת בדיקות, וטריאז' לכשלים. כל אחד עוקב אחר אותו דפוס: לחקור דרישות, לתכנן גישה, לבצע, לאמת. ההבדל הקריטי: יש להשתמש ב**קונטקסטים טריים** לכל שלב. זה ממנף את הטבע הסטייטלסי מ +[שיעור 1](../fundamentals/lesson-1-how-llms-work.md) +על המודלים ו +[שיעור 2](../fundamentals/lesson-2-how-agents-work.md) +על הסוכנים +— הסוכן לא מביא עימו הנחות או מגן על החלטות קודמות בין קונטקסטים. + +## תהליך עבודה בשלושה קונטקסטים: +
+ +
+שלושה סוכנים: +1. **כתוב קוד** בקונטקסט A—חקור דפוסים קיימים באמצעות [עיגון משיעור 5](../methodology/lesson-5-grounding.md), תכנן מימוש, בצע, אמת נכונות +2. **כתוב בדיקות** בקונטקסט B טרי—חקור דרישות ומקרי קצה, תכנן כיסוי בדיקות, בצע (הסוכן לא זוכר שכתב את המימוש, אז בדיקות נגזרות באופן עצמאי מדרישות), אמת שבדיקות נכשלות בהתחלה +3. **טריאז' כשלים** בקונטקסט C טרי—חקור את פלט הכשל, נתח כוונת בדיקה מול התנהגות המימוש, קבע root cause עם ראיות (נתיבי קבצים, מספרי שורות, ניתוח סמנטי), הצע תיקונים (הסוכן לא יודע מי כתב קוד או בדיקות, מספק ניתוח אובייקטיבי) + +מערכות ארגוניות מאמתות גישה זו: Salesforce [הפחיתה זמן דיבוג ב-30%](https://engineering.salesforce.com/how-ai-test-automation-cut-developer-productivity-bottlenecks-by-30-at-scale) באמצעות root-cause-analysis אוטומטי למיליוני ריצות בדיקה יומיות. תהליך עבודת האבחון המפורטת מכוסה בסעיף [אבחון כשל בדיקה](#test-failure-diagnosis-agent-driven-debug-cycle) למטה. + +## בדיקות כמעקות בטיחות: מניעת רגרסיות בסקייל גדול + +### למה בדיקות חשובות בסקייל גדול + +סוכנים פועלים במהירות שבני אדם לא יכולים להדביק. לעתים רחוקות הם מצליחים בפעם הראשונה. + +כשסוכן עושה ריפקטור ל-30 קבצים בסשן אחד, שינויים לא מכוונים מסתתרים ב-diffs ענקיים ש"בעיקר נכונים." אתם עושים ריוויו ל diff של 2,000 שורות, מפתחים עיוורון לדפוסים חוזרים, וסורקים מעבר ל-28 קבצים נכונים תוך פספוס שני קבצים עם שגיאות לוגיקה עדינות. + +**בדיקות מקבעות אילו התנהגויות הן מכוונות ואסור שישתנו.** ללא בדיקות, באגים מצטברים בקנה מידה גדול. סקירה ידנית נכשלת כשסוכן עשוי "לפשט" לוגיקת עיגול (rounding) קריטית שקבורה בשינוי קובץ של 50 שורות. הבדיקה נכשלת מיד—הסוכן לא יכול להסיר בשקט לוגיקה ששוברת פרודקשן. + +### בדיקות חברתיות לעומת Mocking כבד + +בדיקות עם mocking כבד נותנות ביטחון שווא. הן מאמתות פרטי מימוש (קריאות פונקציה) במקום התנהגות (פונקציונליות אמיתית). + +**[בדיקות יחידה חברתיות](https://chroniclesofapragmaticprogrammer.substack.com/p/keeping-tests-valuable-social-testing) ו[בדיקות אינטגרציה צרות](https://emmanuelvalverderamos.substack.com/p/explaining-unit-tests-solitarysociable) משתמשות באימפלמנטציות אמיתיות לקוד פנימי.** יש לעשות mock רק למערכות חיצוניות (APIs, שירותי צד שלישי). + +**דוגמה: בדיקת אימות** + +- **בדיקה עם mocking כבד**: עושה stub ל-`findByEmail()`, `verify()`, ו-`create()`. עוברת גם כשסוכן שובר את שלושת האימפלמנטציות. +- **בדיקה חברתית**: משתמשת בשאילתות מסד נתונים אמיתיות, hashing סיסמאות אמיתי, וטוקני סשן אמיתיים. מפעילה code paths אמיתיים—אם הסוכן שובר חלק כלשהו מהריצה, הבדיקה נכשלת. + +**מתי לעשות mock:** + +- Mock Stripe ← עולה כסף ודורש מפתחות API +- להשתמש במסד נתונים בדיקה אמיתי ← מהיר ומאמת התנהגות אמיתית + +[Testing Without Mocks](https://www.jamesshore.com/v2/projects/nullables/testing-without-mocks) מציע +"Nullables" - +קוד פרודקשן עם מתג כיבוי—לבדיקת תשתית in-memory ללא mock setup מורכב. + +### משוב מהיר עם בדיקות עשן - Smoke tests + +יש לבנות **סט בדיקות עשן שרצות בפחות מ30 שניות** שמכסה צמתים קריטיים בלבד—מסע משתמש ליבתי (core user journey), גבולות אותנטיקציה, וקישוריות מסד נתונים—לא כיסוי ממצה. חבילת בדיקות מקיפה של 10 דקות חסרת תועלת לפיתוח איטרטיבי עם סוכנים; ידלגו על הרצתה עד הסוף כשדיבוג הופך יקר. יש להריץ בדיקות עשן אחרי כל משימה לתפיסת כשלים מיד כשהקונטקסט טרי, במקום לעשות 20 שינויים לפני גילוי איזה מהם שבר את המערכת. כפי ש[Jeremy Miller מציין](https://jeremydmiller.com/2024/09/29/my-recommendations-for-a-test-automation-strategy), יש להשתמש ב"מנגנון הכי עדין שאומר לכם משהו חשוב." יש לשמור מקרי קצה, ולידציה מפורטת, ופרטי רינדור לחבילת הבדיקות המלאה—בדיקות עשן קיימות אך ורק למניעת שגיאות מצטברות במהלך איטרציה מהירה. יש לקודד פרקטיקה זו בקובץ `AGENTS.md` או `CLAUDE.md` של הפרויקט שלכם ([שיעור 6](./lesson-6-project-onboarding.md)) כדי שסוכנים יריצו אוטומטית בדיקות עשן אחרי השלמת כל משימה ללא צורך בתזכורות מפורשות. + +--- + +## בדיקות סוכן אוטונומיות: מציאת מקרי קצה שפיספסת + +בדיקות דטרמיניסטיות מאמתות דרישות ידועות. סימולציית סוכן מגלה מקרי קצה לא ידועים. **שתיהן חיוניות—יש לשלב את שתיהן בצינור הבדיקות שלכם.** + +### סוכנים כסימולטורים של משתמשים + +סוכני AI יכולים לסמלץ התנהגות משתמש אמיתית על ידי מתן משימה והכלים הנדרשים לאינטראקציה עם המוצר שלכם—אוטומציית דפדפן (שרתי MCP), גישת CLI, קליינט API. כמו בודק אנושי שחוקר את האפליקציה שלכם, הסוכן מנווט, לוחץ, ממלא טפסים, וצופה בתוצאות. ההבדל המהותי: סוכנים חוקרים מרחבי מצבים באופן לא-דטרמיניסטי. + +**התנהגות לא-דטרמיניסטית:** בהרצת אותו סקריפט בדיקה פעמיים, הסוכן חוקר נתיבים שונים בכל פעם. זה לא באג—זה פיצ'ר. סוכנים מבוססי LLM מקבלים החלטות הסתברותיות, בוחרים רצפי ניווט שונים, וריאציות קלט, ודפוסי אינטראקציה בין ריצות. איטרציה אחת עשויה לבדוק את ה-happy path, אחרת עשויה במקרה לגלות race condition על ידי לחיצות מהירות, שלישית עשויה להיתקל במקרה קצה עם תווי unicode שלא שיערתם. + +**אקראיות זו לא אמינה לבדיקות רגרסיה.** לא ניתן להבטיח שהסוכן יפעיל את אותם code paths ב-CI/CD. אבל היא מצוינת לגילוי—מציאת מקרי קצה, באגים של מכונת מצבים, ופערי ולידציה של קלט שבדיקות דטרמיניסטיות מפספסות כי לא חשבו לכתוב אותן. + +### אסטרטגיות בדיקה משלימות + +**בדיקות דטרמיניסטיות (יחידה, אינטגרציה, E2E):** + +- מאמתות דרישות ולוגיקה עסקית ידועים +- רצות באופן אמין בצינורות CI/CD +- תופסות רגרסיות כשקוד משתנה +- מספקות לולאות פידבק מהירות +- מתעדות התנהגות צפויה + +**סימולציית סוכן (חקירה לא-דטרמיניסטית):** + +- מגלה מקרי קצה לא ידועים +- חוקרת user journeys לא צפויים +- מוצאת race conditions ובאגי תזמון +- חושפת פערי ולידציה של קלט +- מסמלצת משתמשים יצירתיים/עוינים + +**תהליך העבודה:** יש להשתמש בסוכנים לגילוי, ואז לגבש ממצאים לבדיקות דטרמיניסטיות. סוכנים חוקרים את הלא נודע; בדיקות דטרמיניסטיות מונעות רגרסיה על הידוע. + +כשכותבים פרומפטים לסוכנים לבדיקות סימולציה, יש להחיל את הטכניקות מ[שיעור 4](../methodology/lesson-4-prompting-101.md)—הוראות ברורות, אילוצים ספציפיים, פלטים צפויים—ליצירת פרומפטים אפקטיביים לחקירה שמנחים סוכנים לגילוי מקרי קצה בעלי ערך גבוה. + +:::tip חיבור סוכנים למוצר שלכם + +יש לאפשר לסוכנים אינטראקציה עם האפליקציה שלכם על פני דפדפנים, מובייל, ודסקטופ באמצעות שרתי Model Context Protocol (MCP): + +**אוטומציית דפדפן** + +**Chrome DevTools MCP** ([רשמי מ-Google](https://github.com/ChromeDevTools/chrome-devtools-mcp)) + +- גישה מלאה ל-Chrome DevTools Protocol (CDP) לאוטומציית דפדפן +- פרופיילינג ביצועים, בדיקת רשת, מניפולציית DOM, console logs בזמן אמת +- הגדרה: `npx chrome-devtools-mcp@latest` +- [תיעוד](https://developer.chrome.com/blog/chrome-devtools-mcp) + +**Playwright MCP** ([Microsoft](https://github.com/microsoft/playwright-mcp)) + +- בדיקות על דפדפנים שונים (Chromium, WebKit, Firefox) +- אינטראקציות מבוססות עץ-נגישות לבחירת אלמנטים אמינה +- הפניות אלמנטים בשפה טבעית ("click the submit button") +- הגדרה: `npx @playwright/mcp@latest` + +**אוטומציית מובייל** + +**mobile-mcp** ([Mobile Next](https://github.com/mobile-next/mobile-mcp)) + +- אוטומציית סימולטור/אמולטור iOS/Android ומכשירים אמיתיים +- אינטראקציות מונעות נגישות לבדיקת אפליקציות native +- צילומי UI מובנים לזיהוי אלמנטים אמין +- תומך ב-multi-step user journeys וחילוץ נתונים + +**אוטומציית דסקטופ (מתפתחת)** + +**שרתי MCP לשימוש במחשב** + +- שליטה באפליקציות דסקטופ דרך screen capture, קלט עכבר/מקלדת, וניהול חלונות +- משתמש ב-APIs של נגישות ואינטראקציות מבוססות קואורדינטות ל-UI automation +- טכנולוגיה בשלב מוקדם עם אימוץ ארגוני גדל (Microsoft, Cloudflare, IBM משלבים MCP על פני פלטפורמות) + +שרתי MCP אלה נותנים לסוכנים "עיניים וידיים" על פני פלטפורמות, מאפשרים בדיקות אוטונומיות, שחזור באגים, וחקירת מוצר. יש להגדיר בהגדרות MCP של עוזר ה-AI שלכם לחבר סוכנים ישירות לסביבת המוצר שלכם. + +::: + +## אבחון נפילות בטסטים: מחזור דיבאג מונחה סוכן + +כשבדיקות נכשלות, יש להחיל את אותו תהליך עבודה בארבעה שלבים מ[שיעור 3](../methodology/lesson-3-high-level-methodology.md): מחקר > תכנון > ביצוע > אימות. זו אותה גישה שיטתית שמשתמשים בה לכל אינטראקציות הסוכן, עכשיו מותאמת לדיבאג של נפילה של טסטים. + +### דפוס הפרומפט האבחוני + +פרומפט אבחוני זה מחיל טכניקות מ[שיעור 4](../methodology/lesson-4-prompting-101.md): צעדים רצופים [Chain-of-Thought](../methodology/lesson-4-prompting-101.md#chain-of-thought-paving-a-clear-path), [אילוצים](../methodology/lesson-4-prompting-101.md#constraints-as-guardrails) שדורשים ראיות, ו[פורמט מובנה](../methodology/lesson-4-prompting-101.md#applying-structure-to-prompts). הבנה למה כל אלמנט קיים מאפשרת להתאים דפוס זה למשימות אבחון אחרות. + +
+ +
+ +**למה זה עובד:** + +- **בלוק קוד מגודר** (``````) שומר על פורמט הודעות השגיאה ומונע מה-LLM לפרש אותן כהוראות ([פורמט מובנה](../methodology/lesson-4-prompting-101.md#applying-structure-to-prompts)) +- **"Use the code research"** היא הנחיית עיגון מפורשת—מאלצת חיפוש בבסיס הקוד במקום הזיה מדפוסי אימון ([אילוצים](../methodology/lesson-4-prompting-101.md#constraints-as-guardrails)) +- **צעדי אבחון ממוספרים תחת הכותרת "DIAGNOSE"** מיישמים [Chain-of-Thought](../methodology/lesson-4-prompting-101.md#chain-of-thought-paving-a-clear-path), מאלצים ניתוח רצוף (לא יכול לקפוץ ל"root cause" בלי לבחון קודם כוונת בדיקה) +- **"Understand the intention"** (צעד 2) מבטיח שהסוכן מנסח למה הבדיקה קיימת, לא רק מה היא עושה—קריטי ל[היגיון CoT](../methodology/lesson-4-prompting-101.md#chain-of-thought-paving-a-clear-path) +- **החלטה בינארית תחת הכותרת "DETERMINE"** [מגבילה פלט](../methodology/lesson-4-prompting-101.md#constraints-as-guardrails) ל"bug vs outdated test" במקום מסקנות פתוחות +- **"Provide evidence"** דורש נתיבי קבצים ומספרי שורות—הוכחה קונקרטית דרך [דרישת ראיות](./lesson-7-planning-execution.md#require-evidence-to-force-grounding), לא טענות מעורפלות + +ניתן להתאים זאת לבעיות ביצועים, פגיעויות אבטחה, או כשלי deployment על ידי שינוי צעדי האבחון תוך שימור המבנה: CoT רצוף ← החלטה מוגבלת ← דרישת ראיות. + +:::tip הפניה +ראו את תבנית הפרומפט המלאה עם דוגמאות שימוש מפורטות והתאמות: [Test Failure Diagnosis](/prompts/testing/test-failure-diagnosis) +::: + +## נקודות מפתח + +- **בדיקות הן תיעוד שסוכנים באמת קוראים** - הם לומדים כוונה, מקרי קצה, ואילוצים משמות בדיקות, assertions, והערות (comments). יש לכתוב בדיקות שמסבירות את ה"למה", לא רק מאמתות את ה"מה". + +- **יש להשתמש בקונטקסטים נפרדים לקוד, בדיקות, ודיבוג** - כשקוד ובדיקות נוצרים באותה שיחה, הם יורשים את אותן הנחות פגומות ("מחזור של הונאה עצמית"). יש לכתוב קוד בקונטקסט A, לכתוב בדיקות בקונטקסט B טרי, ולעשות טריאז' כשלים בקונטקסט C טרי. זה מונע specification gaming ומספק ניתוח אובייקטיבי. + +- **יש לכתוב בדיקות חברתיות, לא בדיקות עם mocking כבד** - יש לעשות mock רק למערכות חיצוניות (APIs, שירותי צד שלישי). יש להשתמש באימפלמנטציות אמיתיות לקוד פנימי לתפיסת שבירה אמיתית. יש לבנות סט בדיקות עשן של עד 30 שניות ללולאת פידבק מהירה. + +- **בדיקות ירוקות הן לא ערובה לתוכנה עובדת** - בדיקות מאמתות לוגיקה, לא UX או שימושיות בעולם האמיתי. יש להריץ את המוצר האמיתי בעצמכם—בדיקות תופסות 80%, אימות אנושי תופס את 20% הנותרים. + +- **בדיקות אוטונומיות מגלות מקרי קצה** - בדיקות אקראיות מוּנַעות-סוכן חוקרות מרחבי מצבים שבני אדם לא חושבים לבדוק. יש להפוך מקרי קצה שהתגלו לבדיקות רגרסיה קבועות. + +- **אבחון שיטתי פותר את רוב כשלי הבדיקות** - יש להשתמש בפרומפט האבחוני המובנה (בחון, הבן, השווה, זהה, קבע) לניתוח כשלים. סוכנים יכולים לתקן את רוב הבעיות באופן אוטונומי עם תהליך עבודה זו. + +--- + +**הבא:** [שיעור 9: סקירת הקוד](./lesson-9-reviewing-code.md) diff --git a/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-9-reviewing-code.md b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-9-reviewing-code.md new file mode 100644 index 0000000..652b194 --- /dev/null +++ b/website/i18n/he/docusaurus-plugin-content-docs/current/practical-techniques/lesson-9-reviewing-code.md @@ -0,0 +1,193 @@ +--- +sidebar_position: 4 +sidebar_label: 'שיעור 9: קוד ריוויוּ' +title: 'שיעור 9: קוד ריוויוּ' +--- + +import DualOptimizedPR from '@site/shared-prompts/\_dual-optimized-pr.mdx'; +import AIAssistedReview from '@site/shared-prompts/\_ai-assisted-review.mdx'; + +סיימת את המימוש. הבדיקות עוברות. הסוכן ביצע את התוכנית שלך בהצלחה. עכשיו מגיעה השאלה הקריטית: האם זה באמת נכון? + +זהו שלב ה**אימות** מ[תהליך העבודה בארבעה שלבים של שיעור 3](../methodology/lesson-3-high-level-methodology.md)—"שער האיכות" השיטתי לפני דילוור. סקירת קוד (בעברית, קוד ריוויוּ 😉) תופסת את השגיאות ההסתברותיות שסוכנים בהכרח מכניסים: באגי לוגיקה עדינים, אי-התאמות ארכיטקטוניות, מקרי קצה שטופלו בצורה שגויה, דפוסים שלא לגמרי מתאימים לבסיס הקוד שלך. + +תובנת המַפְתח: **לסקור בקונטקסט טרי, נפרד מקונטקסט כתיבת הקוד.** זה מונע הטיית אישור (confirmation bias) וממנף את האופי הסטייטלס של סוכנים מ[שיעור 1](../fundamentals/lesson-1-how-llms-work.md) ו[שיעור 2](../fundamentals/lesson-2-how-agents-work.md). סוכן שסוקר את העבודה שלו באותה שיחה יגן על ההחלטות שלו. סוכן בקונטקסט טרי ינתח באובייקטיביות, ללא היצמדות לבחירות קודמות. + +:::info בסיסי קוד המנוהלים אך ורק על ידי סוכנים לעומת בסיסי קוד מעורבים: הבחנה קריטית + +אותם תקני הנדסה—DRY, YAGNI, ארכיטקטורה, תחזוקתיות, קריאות—חלים על כל בסיסי הקוד. מה שמשתנה הוא אופטימיזציית סגנון הקוד ותהליך הסקירה: + +**בסיסי קוד המתוחזקים ע"י סוכן בלבד** מתוחזקים אך ורק על ידי AI עם התערבות אנושית מינימלית ברמת הקוד. העדיפו סגנון קוד מעט מוטה עבור בהירות לכלי AI: יותר type annotations מפורשים, תיעוד קצת יותר מפורט, קבצי קונטקסט ארכיטקטוניים מפורטים ([שיעור 6](./lesson-6-project-onboarding.md)). שאלת ריוויו: "האם סוכן יבין את זה בעוד 6 חודשים?" + +**בסיסי קוד מעורבים** מאזנים שיתוף פעולה אנושי ו-AI שבו שניהם עובדים ישירות עם קוד. העדיפו סגנון קוד שמתאים לתמציתיות אנושית תוך שמירה על ניווטיות והתמצאות קלה לAI. **רוב בסיסי הקוד בפרודקשן שייכים לקטגוריה זו.** + +**הבדל קריטי בבסיסי קוד מעורבים:** הוסיפו שלב סקירה ידני שבו אתם קוראים ובודקים במלואו קוד שנוצר על ידי AI לפני קומיט כדי להבטיח קריאוּת אנושית. זה לא נתון לוויכוח—ללא כללי פרויקט מפורשים שמנחים סגנון, סוכנים מייצרים קוד העוקב אחר דפוסים מנתוני האימון שלהם שעשויים לא להתאים לתקני הקריאוּת של הצוות שלכם. כוונו את כללי הפרויקט שלכם ([שיעור 6](./lesson-6-project-onboarding.md)) להנחות סוכנים לסגנון כתיבה שבני אדם מצפים לו, ואז לאמת שהפלט עומד בציפיות אלה. + +::: + +## תבנית הפרומפט לקוד ריוויו וסקירה כללית + +תבנית זו משלבת טכניקות מ[שיעור 4: Prompting 101](../methodology/lesson-4-prompting-101.md). הבנת **למה** כל אלמנט קיים מאפשרת לך להתאים דפוס זה למשימות סקירה אחרות (ביקורות אבטחה, ניתוח ביצועים, סקירה ארכיטקטונית). + +```markdown +You are an expert code reviewer. Analyze the current changeset and provide a critical review. + +The changes in the working tree were meant to: $DESCRIBE_CHANGES + +Think step-by-step through each aspect below, focusing solely on the changes in the working tree. + +1. **Architecture & Design** + - Verify conformance to project architecture + - Check module responsibilities are respected + - Ensure changes align with the original intent + +2. **Code Quality** + - Code must be self-explanatory and readable + - Style must match surrounding code patterns + - Changes must be minimal - nothing unneeded + - Follow KISS principle + +3. **Maintainability** + - Optimize for future LLM agents working on the codebase + - Ensure intent is clear and unambiguous + - Verify comments and docs remain in sync with code + +4. **User Experience** + - Identify areas where extra effort would significantly improve UX + - Balance simplicity with meaningful enhancements + +Review the changes critically. Focus on issues that matter. +Use ChunkHound's code research. +DO NOT EDIT ANYTHING - only review. +``` + +אחרי כתיבת קוד ([שיעור 7](./lesson-7-planning-execution.md)), כתיבת בדיקות ([שיעור 8](./lesson-8-tests-as-guardrails.md)), ולאחר שכל הבדיקות עוברות, שלב סקירה זה תופס מה שתהליך הפיתוח האיטרטיבי השאיר מאחור—שער האיכות האחרון לפני קומיט. + +:::tip הפניה +ראה את תבנית הפרומפט המלאה עם הנחיות סקירה איטרטיבית: [Comprehensive Code Review](/prompts/code-review/comprehensive-review) +::: + +### סקירה איטרטיבית: חזור עד ש"ירוק" או עד שהערך יורד + +סקירת קוד היא לעתים רחוקות מעבר אחד—סקירה ראשונה מוצאת בעיות, מתקנים אותן, מריצים בדיקות מחדש ([שיעור 8](./lesson-8-tests-as-guardrails.md)) לתפיסת רגרסיות, ואז סוקרים שוב בקונטקסט טרי (לא אותה שיחה שבה הסוכן יגן על החלטותיו הקודמות). המשיכו במחזור זה: סקירה בקונטקסט טרי, תיקון בעיות, אימות עם בדיקות, חזרה. + +**הסקירה עצמה היא הסתברותית**— גם היא מבוססת LLM שעושה תחזיות סטטיסטיות. הסוכן יכול לטעות. הוא עשוי להציע "תיקונים" ששוברים קוד עובד או מכניסים רגרסיות שסט הבדיקות שלך תופס. + +כאן שיקול הדעת שלך כמפעיל|ה הופך חיוני (ה"אמנות" של התהליך): + +- **בדיקות עוברות + סקירה ירוקה** = לדלוור +- **בדיקות עוברות + סקירה שמחזירה רק הערות קטנוניות (nitpicking)** = לדלוור +- **בדיקות נכשלות אחרי "תיקוני" סקירה** = הסקירה כנראה טעתה, יש לדחות את ההצעה + +הפסיקו את האיטרציות כשמגיעים ל**אור ירוק** (אין בעיות מהותיות, בדיקות עוברות) או *ירידה בערך הסקירה**. ירידת ערך מתבטאת כ: + +- **ניטפיקינג**: הערות קטנוניות, העדפות סגנון טריוויאליות כמו "שנה שם למשתנה הזה" +- **הזיות**: הסוכן ממציא בעיות לא קיימות או מציע דפוסים שלא מתאימים לארכיטקטורה שלך +- **נפילות טסטים שנגרמו מסקירה**: ה"תיקון" שבר קוד שעבד קודם +- **עלות מופרזת**: 4+ איטרציות לבעיות קטנות שנותרו + +בנקודה זו, סמכו על הטסטים שלכם כפוסק האובייקטיבי ודלוורו את הקוד—סקירת AI נוספת עולה יותר מהערך שהיא נותנת ועלולה להוביל להדרדרות באיכות. + +## Pull Requests לסוקרים אנושיים ו-AI + +Pull requests משרתים שני קהלים: מתחזקים אנושיים ועוזרי סקירת ה-AI שלהם. קהלים אלה מעבדים מידע באופן שונה מהותית: + +- **סוקרים אנושיים** סורקים מהר, מסיקים משמעות מקונטקסט, ומעדיפים סיכומים תמציתיים (1-3 פסקאות מקסימום). הם רוצים להבין את ה"למה" ואת הערך העסקי במבט חטוף. + +- **עוזרי סקירת AI** מעבדים תוכן חלק-אחר-חלק, מתקשים עם כינויים מעורפלים וסחף סמנטי (semantic drift), וצריכים מבנה מפורש ([שיעור 5](../methodology/lesson-5-grounding.md)). הם דורשים קונטקסט טכני מפורט: שינויי קבצים ספציפיים, דפוסים ארכיטקטוניים, שינויים-שוברים המפורטים בבירור. + +תיאורי PR מסורתיים מותאמים לקהל אחד או לאחר — הם עלולים להיות מילוליים מדי לבני אדם או מעורפלים מדי לסוכני AI. הפתרון: ליצור את שניהם בתהליך עבודה מתואם באמצעות תת-סוכנים (sub-agents). + +### דפוס הפרומפט המתקדם + +פרומפט זה מדגים טכניקות מרובות מ[שיעור 4 (Prompting 101)](../methodology/lesson-4-prompting-101.md), [שיעור 5 (עיגון)](../methodology/lesson-5-grounding.md), ו[שיעור 7 (תכנון וביצוע)](./lesson-7-planning-execution.md): + +
+ +
+ +### מנגנונים בפעולה + +**תת-סוכנים לשימור קונטקסט ([שיעור 5](../methodology/lesson-5-grounding.md#solution-2-sub-agents-for-context-isolation)):** + +ההוראה "Using the sub task tool to conserve context" מייצרת סוכן נפרד לחקירת היסטוריית git, ומונעת מהקונטקסט של המתזמר הראשי להתמלא ב-diff של קומיטים. תת-הסוכן מחזיר רק ממצאים מסונתזים. בלי זה, חקירת 20-30 קבצים שהשתנו צורכת 40K+ טוקנים, דוחפת אילוצים קריטיים לאמצע הנשכח של עקומת הקשב עם צורת הU. + +יכולת תת-סוכנים זו ייחודית ל-[Claude Code CLI](/developer-tools/cli-coding-agents#claude-code). כלים אחרים (Codex, GitHub Copilot) דורשים פיצול זה לפרומפטים רציפים מרובים: חקור קודם, ואז נסח על סמך ממצאים. + +**עיגון מרובה מקורות (multi-source grounding) ([שיעור 5](../methodology/lesson-5-grounding.md#production-pattern-multi-source-grounding)):** ArguSeek חוקר שיטות עבודה מומלצות ל-PR בעוד ChunkHound מעגן את תיאור הPR לארכיטקטורה ולסגנון הקידוד של בסיס הקוד שלך. + +**Prompting מובנה ([שיעור 4](../methodology/lesson-4-prompting-101.md)):** פרסונה, אילוצי תקשורת, גבולות פורמט, ודרישות מבניות מכוונים את הסוכן לייצר פלטים מותאמים כפולים (לבן אנוש וסוכן). + +**דרישת ראיות ([שיעור 7](./lesson-7-planning-execution.md#require-evidence-to-force-grounding)):** הפרומפט מאלץ עיגון דרך "explore the changes" ו-"learn the architecture"—הסוכן לא יכול לנסח תיאורים מדויקים מבלי לקרוא קומיטים וקוד אמיתיים. + +:::tip הפניה +ראו את תבנית הפרומפט המלאה עם טיפים לשילוב תהליך עבודה: [PR Description Generator](/prompts/pull-requests/dual-optimized-pr) +::: + +### סקירת PRs עם עוזרי AI + +כשנמצאים בצד המקבל של PR עם תיאורים מותאמים כפולים, יש לנו קונטקסט מובנה הן להבנה אנושית והן לסקירה בסיוע AI. סעיף זה מראה איך למנף את שני התיאורים ביעילות. + +#### צריכת התיאורים הכפולים + +**התיאור המותאם לאדם** (תיאור PR ב-GitHub): + +- לקרוא ראשית להבנת ה"למה" וערך עסקי +- לסרוק מהר למציאת שינויים-שוברים וקבצי-מפתח שהושפעו +- להשתמש בזה ליצירת המודל המנטלי הראשוני שלך של השינויים + +**התיאור המותאם ל-AI** (`PR_REVIEW_CONTEXT.md` או דומה): + +- להזין לעוזר סקירת ה-AI שלכם (GitHub Copilot, Codex, Claude Code, וכו') +- מספק קונטקסט טכני מקיף שה-AI צריך כדי לבצע ניתוח מדויק +- מכיל טרמינולוגיה מפורשת, נתיבי קבצים, ודפוסים ארכיטקטוניים + +#### דפוס הפרומפט לסקירה + +כשסוקרים PR עם תיאורים מותאמים כפולים, כדאי להשתמש בדפוס זה עם עוזר ה-AI שלכם: +
+ +
+ +:::tip הפניה +ראו את תבנית הפרומפט המלאה עם הסבר Chain of Draft: [AI-Assisted PR Review](/prompts/pull-requests/ai-assisted-review) +::: + +:::tip Chain of Draft (CoD): חלופה יעילה ל-Chain of Thought + +**שימו לב לטכניקה בצעד 2 של תהליך הסקירה למעלה:** + +>
"Think step by step, but only keep a minimum draft for each thinking step, with 5 words at most. Return the assessment at the end of the response after a separator ####."
+ +זה **שרשרת טיוטות (CoD)**—אופטימיזציה של פרומט מבוסס שרשרת חשיבה (CoT) שמקיימת היגיון מובנה תוך יעילות רבה יותר. + +**איך זה עובד:** במקום לייצר הסברים מפורטים שלב-אחר-שלב, CoD מורה ל-LLM לחשוב דרך כל שלב אבל לשמור את הטיוטה תמציתית (5 מילים מקסימום לשלב), ואז להחזיר את ההערכה הסופית אחרי מפריד (`####`). + +**למה להשתמש בזה לסקירות:** CoD מספק את אותם יתרונות שימוש-בהיגיון כמו CoT—פירוק ניתוח מורכב לשלבים לוגיים—אבל עם צריכת טוקנים מופחתת וזמני תגובה מהירים יותר. + +**ראו עוד:** + +- [מאמר המחקר המקורי](https://arxiv.org/abs/2502.18600) +- [תיעוד מתוך האתר Learn Prompting](https://learnprompting.org/docs/advanced/thought_generation/chain-of-draft) + +::: + +## נקודות מפתח + +- **סקירה בקונטקסט טרי למניעת הטיית אישור** - סוכן שסוקר את עבודתו באותה שיחה יגן על החלטותיו. קונטקסט טרי מספק ניתוח אובייקטיבי. + +- **החלת אותה מתודולוגית ארבעה שלבים לסקירה** - מחקר (הבן כוונה) ← תכנון (מבנה סקירה) ← ביצוע (בצע ניתוח) ← אימות (החלט לדלוור, לתקן, או לייצר מחדש). + +- **שימוש בפרומפטים סקירה מובנים עם Chain-of-Thought** - תבנית הסקירה משיעור זה מחילה עקרונות prompting של שיעור 4: פרסונה, CoT, מבנה, עיגון, אילוצים. התאימו דפוס זה לסקירות אבטחה, ניתוח ביצועים, או אימות ארכיטקטוני. + +- **איטרציה עד אור ירוק או ערך יורד** - תקנו בעיות, ואז בצעו סקירה מחדש בקונטקסט טרי. עיצרו כשהממצאים הופכים לניטפיקינג טריוויאלי או שהסוכן הוזה בעיות שלא קיימות. + +- **דרישת ראיות מאלצת עיגון** - "Provide file paths and line numbers" מ[שיעור 7](./lesson-7-planning-execution.md#require-evidence-to-force-grounding) מבטיח שממצאי הסקירה מבוססים על קוד אמיתי, לא ניחושים סטטיסטיים. + +- **כיתבו תיאורי PR כפולים מותאמים לסוקרים אנושיים ו-AI** - בני אדם צריכים סיכומים תמציתיים וניתנים לסריקה (1-3 פסקאות). עוזרי AI צריכים קונטקסט טכני מקיף וחד-משמעי. צרו את שניהם בתהליך עבודה מתואם על מנת לשרת את שני הקהלים ביעילות. + +- **מינוף קונטקסט מותאם ל-AI כשסוכן מבצע את הסקירה PRs** - כשסוכן סוקר PR עם תיאורים כפולים, הזן את התיאור המותאם ל-AI לעוזר הסקירה שלך. זה מספק את העיגון והקונטקסט הארכיטקטוני הנדרשים לניתוח מדויק, מפחית הזיות ומשפר את איכות סקירה. + +--- + +**הבא:** [שיעור 10: דיבאג עם AI](./lesson-10-debugging.md) diff --git a/website/i18n/he/docusaurus-theme-classic/footer.json b/website/i18n/he/docusaurus-theme-classic/footer.json new file mode 100644 index 0000000..31ae203 --- /dev/null +++ b/website/i18n/he/docusaurus-theme-classic/footer.json @@ -0,0 +1,39 @@ +{ + "link.title.Course": { + "message": "קורס", + "description": "The title of the footer links column with title=Course in the footer" + }, + "link.title.Community": { + "message": "קהילה", + "description": "The title of the footer links column with title=Community in the footer" + }, + "link.title.More": { + "message": "עוד", + "description": "The title of the footer links column with title=More in the footer" + }, + "link.item.label.FAQ": { + "message": "שאלות נפוצות", + "description": "The label of footer link with label=FAQ linking to /docs/faq" + }, + "link.item.label.Getting Started": { + "message": "התחלה מהירה", + "description": "The label of footer link with label=Getting Started linking to /docs" + }, + "link.item.label.Course Modules": { + "message": "מודולי הקורס", + "description": "The label of footer link with label=Course Modules linking to /docs/fundamentals/lesson-1-how-llms-work" + }, + "link.item.label.GitHub Discussions": { + "message": "דיונים ב-GitHub", + "description": "The label of footer link with label=GitHub Discussions linking to https://github.com/agenticoding/agenticoding.github.io/discussions" + }, + "link.item.label.Report Issues": { + "message": "דיווח על בעיות", + "description": "The label of footer link with label=Report Issues linking to https://github.com/agenticoding/agenticoding.github.io/issues" + }, + "link.item.label.GitHub": { + "message": "GitHub", + "description": "The label of footer link with label=GitHub linking to https://github.com/agenticoding/agenticoding.github.io" + } + +} diff --git a/website/i18n/he/docusaurus-theme-classic/navbar.json b/website/i18n/he/docusaurus-theme-classic/navbar.json new file mode 100644 index 0000000..6a1067e --- /dev/null +++ b/website/i18n/he/docusaurus-theme-classic/navbar.json @@ -0,0 +1,30 @@ +{ + "title": { + "message": "קידוד אג'נטי", + "description": "The title in the navbar" + }, + "logo.alt": { + "message": "לוגו קידוד אג'נטי", + "description": "The alt text of navbar logo" + }, + "item.label.Course": { + "message": "קורס", + "description": "Navbar item with label Course" + }, + "item.label.Prompt Library": { + "message": "ספריית פרומפטים", + "description": "Navbar item with label Prompt Library" + }, + "item.label.Toolbox": { + "message": "ארגז כלים", + "description": "Navbar item with label Toolbox" + }, + "item.label.FAQ": { + "message": "שאלות נפוצות", + "description": "Navbar item with label FAQ" + }, + "item.label.GitHub": { + "message": "GitHub", + "description": "Navbar item with label GitHub" + } +} diff --git a/website/package-lock.json b/website/package-lock.json index f22f5bf..694f059 100644 --- a/website/package-lock.json +++ b/website/package-lock.json @@ -247,7 +247,6 @@ "resolved": "https://registry.npmjs.org/@algolia/client-search/-/client-search-5.40.1.tgz", "integrity": "sha512-Mw6pAUF121MfngQtcUb5quZVqMC68pSYYjCRZkSITC085S3zdk+h/g7i6FxnVdbSU6OztxikSDMh1r7Z+4iPlA==", "license": "MIT", - "peer": true, "dependencies": { "@algolia/client-common": "5.40.1", "@algolia/requester-browser-xhr": "5.40.1", @@ -395,7 +394,6 @@ "resolved": "https://registry.npmjs.org/@babel/core/-/core-7.28.4.tgz", "integrity": "sha512-2BCOP7TN8M+gVDj7/ht3hsaO/B/n5oDbiAyyvnRlNOs+u1o+JWNYTQrmpuNp1/Wq2gcFrI01JAW+paEKDMx/CA==", "license": "MIT", - "peer": true, "dependencies": { "@babel/code-frame": "^7.27.1", "@babel/generator": "^7.28.3", @@ -2230,7 +2228,6 @@ } ], "license": "MIT", - "peer": true, "engines": { "node": ">=18" }, @@ -2253,7 +2250,6 @@ } ], "license": "MIT", - "peer": true, "engines": { "node": ">=18" } @@ -2363,7 +2359,6 @@ "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", "license": "MIT", - "peer": true, "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" @@ -2785,7 +2780,6 @@ "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", "license": "MIT", - "peer": true, "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" @@ -3673,7 +3667,6 @@ "resolved": "https://registry.npmjs.org/@docusaurus/plugin-content-docs/-/plugin-content-docs-3.9.2.tgz", "integrity": "sha512-C5wZsGuKTY8jEYsqdxhhFOe1ZDjH0uIYJ9T/jebHwkyxqnr4wW0jTkB72OMqNjsoQRcb0JN3PcSeTwFlVgzCZg==", "license": "MIT", - "peer": true, "dependencies": { "@docusaurus/core": "3.9.2", "@docusaurus/logger": "3.9.2", @@ -3942,7 +3935,6 @@ "resolved": "https://registry.npmjs.org/@docusaurus/theme-common/-/theme-common-3.9.2.tgz", "integrity": "sha512-6c4DAbR6n6nPbnZhY2V3tzpnKnGL+6aOsLvFL26VRqhlczli9eWG0VDUNoCQEPnGwDMhPS42UhSAnz5pThm5Ag==", "license": "MIT", - "peer": true, "dependencies": { "@docusaurus/mdx-loader": "3.9.2", "@docusaurus/module-type-aliases": "3.9.2", @@ -4786,7 +4778,6 @@ "resolved": "https://registry.npmjs.org/@mdx-js/react/-/react-3.1.1.tgz", "integrity": "sha512-f++rKLQgUVYDAtECQ6fn/is15GkEH9+nZPM3MS0RcxVqoTfawHvDlSCH7JbMhAM6uJ32v3eXLvLmLvjGu7PTQw==", "license": "MIT", - "peer": true, "dependencies": { "@types/mdx": "^2.0.0" }, @@ -5142,7 +5133,6 @@ "resolved": "https://registry.npmjs.org/acorn/-/acorn-6.4.2.tgz", "integrity": "sha512-XtGIhXwF8YM8bJhGxG5kXgjkEuNGLTkoYqVE+KMR+aspr4KGYmKYg7yUe3KghyQ9yheNwLnjmzh/7+gfDBmHCQ==", "license": "MIT", - "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -5570,7 +5560,6 @@ "resolved": "https://registry.npmjs.org/@svgr/core/-/core-8.1.0.tgz", "integrity": "sha512-8QqtOQT5ACVlmsvKOJNEaWmRPmcojMOzCz4Hs2BGG/toAp/K38LcsMRyLp349glq5AzJbCEeimEoxaX6v/fLrA==", "license": "MIT", - "peer": true, "dependencies": { "@babel/core": "^7.21.3", "@svgr/babel-preset": "8.1.0", @@ -6211,7 +6200,6 @@ "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.2.tgz", "integrity": "sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA==", "license": "MIT", - "peer": true, "dependencies": { "csstype": "^3.0.2" } @@ -6394,7 +6382,6 @@ "integrity": "sha512-BnOroVl1SgrPLywqxyqdJ4l3S2MsKVLDVxZvjI1Eoe8ev2r3kGDo+PcMihNmDE+6/KjkTubSJnmqGZZjQSBq/g==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@typescript-eslint/scope-manager": "8.46.2", "@typescript-eslint/types": "8.46.2", @@ -6841,7 +6828,6 @@ "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz", "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", "license": "MIT", - "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -6927,7 +6913,6 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.17.1.tgz", "integrity": "sha512-B/gBuNg5SiMTrPkC+A2+cW0RszwxYmn6VYxB/inlBStS5nx6xHIt/ehKRhIMhqusl7a8LjQoZnjCs5vhwxOQ1g==", "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", @@ -6973,7 +6958,6 @@ "resolved": "https://registry.npmjs.org/algoliasearch/-/algoliasearch-5.40.1.tgz", "integrity": "sha512-iUNxcXUNg9085TJx0HJLjqtDE0r1RZ0GOGrt8KNQqQT5ugu8lZsHuMUYW/e0lHhq6xBvmktU9Bw4CXP9VQeKrg==", "license": "MIT", - "peer": true, "dependencies": { "@algolia/abtesting": "1.6.1", "@algolia/client-abtesting": "5.40.1", @@ -7607,7 +7591,6 @@ } ], "license": "MIT", - "peer": true, "dependencies": { "baseline-browser-mapping": "^2.8.9", "caniuse-lite": "^1.0.30001746", @@ -7907,7 +7890,6 @@ "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-11.0.3.tgz", "integrity": "sha512-ci2iJH6LeIkvP9eJW6gpueU8cnZhv85ELY8w8WiFtNjMHA5ad6pQLaJo9mEly/9qUyCpvqX8/POVUTf18/HFdw==", "license": "Apache-2.0", - "peer": true, "dependencies": { "@chevrotain/cst-dts-gen": "11.0.3", "@chevrotain/gast": "11.0.3", @@ -8699,7 +8681,6 @@ "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", "license": "MIT", - "peer": true, "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" @@ -9019,7 +9000,6 @@ "resolved": "https://registry.npmjs.org/cytoscape/-/cytoscape-3.33.1.tgz", "integrity": "sha512-iJc4TwyANnOGR1OmWhsS9ayRS3s+XQ185FmuHObThD+5AeJCakAAbWv8KimMTt08xCCLNgneQwFp+JRJOr9qGQ==", "license": "MIT", - "peer": true, "engines": { "node": ">=0.10" } @@ -9441,7 +9421,6 @@ "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz", "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==", "license": "ISC", - "peer": true, "engines": { "node": ">=12" } @@ -10389,7 +10368,6 @@ "deprecated": "This version is no longer supported. Please see https://eslint.org/version-support for other options.", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "@eslint-community/eslint-utils": "^4.2.0", "@eslint-community/regexpp": "^4.6.1", @@ -11262,7 +11240,6 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz", "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==", "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -17181,7 +17158,6 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz", "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==", "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -17933,7 +17909,6 @@ } ], "license": "MIT", - "peer": true, "dependencies": { "nanoid": "^3.3.11", "picocolors": "^1.1.1", @@ -18837,7 +18812,6 @@ "resolved": "https://registry.npmjs.org/postcss-selector-parser/-/postcss-selector-parser-7.1.0.tgz", "integrity": "sha512-8sLjZwK0R+JlxlYcTuVnyT2v+htpdrjDOKuMcOVdYjt52Lh8hWRYpxBPoKx/Zg+bcjc3wx6fmQevMmUztS/ccA==", "license": "MIT", - "peer": true, "dependencies": { "cssesc": "^3.0.0", "util-deprecate": "^1.0.2" @@ -19674,7 +19648,6 @@ "resolved": "https://registry.npmjs.org/react/-/react-19.2.0.tgz", "integrity": "sha512-tmbWg6W31tQLeB5cdIBOicJDJRR2KzXsV7uSK9iNfLWQ5bIZfxuPEHp7M8wiHyHnn0DD1i7w3Zmin0FtkrwoCQ==", "license": "MIT", - "peer": true, "engines": { "node": ">=0.10.0" } @@ -19684,7 +19657,6 @@ "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.0.tgz", "integrity": "sha512-UlbRu4cAiGaIewkPyiRGJk0imDN2T3JjieT6spoL2UeSf5od4n5LB/mQ4ejmxhCFT1tYe8IvaFulzynWovsEFQ==", "license": "MIT", - "peer": true, "dependencies": { "scheduler": "^0.27.0" }, @@ -19759,7 +19731,6 @@ "resolved": "https://registry.npmjs.org/@docusaurus/react-loadable/-/react-loadable-6.0.0.tgz", "integrity": "sha512-YMMxTUQV/QFSnbgrP3tjDzLHRg7vsbMn8e9HAa8o/1iXoiomo48b7sk/kkmWEuWNDPJVlKSJRB6Y2fHqdJk+SQ==", "license": "MIT", - "peer": true, "dependencies": { "@types/react": "*" }, @@ -19788,7 +19759,6 @@ "resolved": "https://registry.npmjs.org/react-router/-/react-router-5.3.4.tgz", "integrity": "sha512-Ys9K+ppnJah3QuaRiLxk+jDWOR1MekYQrlytiXxC1RyfbdsZkS5pvKAzCCr031xHixZwpnsYNT5xysdFHQaYsA==", "license": "MIT", - "peer": true, "dependencies": { "@babel/runtime": "^7.12.13", "history": "^4.9.0", @@ -22135,8 +22105,7 @@ "version": "2.8.1", "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", - "license": "0BSD", - "peer": true + "license": "0BSD" }, "node_modules/type-check": { "version": "0.4.0", @@ -22290,7 +22259,6 @@ "integrity": "sha512-hjcS1mhfuyi4WW8IWtjP7brDrG2cuDZukyrYrSauoXGNgx0S7zceP07adYkJycEr56BOUTNPzbInooiN3fn1qw==", "devOptional": true, "license": "Apache-2.0", - "peer": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -22666,7 +22634,6 @@ "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz", "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==", "license": "MIT", - "peer": true, "dependencies": { "fast-deep-equal": "^3.1.1", "fast-json-stable-stringify": "^2.0.0", @@ -22932,7 +22899,6 @@ "resolved": "https://registry.npmjs.org/webpack/-/webpack-5.102.1.tgz", "integrity": "sha512-7h/weGm9d/ywQ6qzJ+Xy+r9n/3qgp/thalBbpOi5i223dPXKi04IBtqPN9nTd+jBc7QKfvDbaBnFipYp4sJAUQ==", "license": "MIT", - "peer": true, "dependencies": { "@types/eslint-scope": "^3.7.7", "@types/estree": "^1.0.8", @@ -23716,7 +23682,6 @@ "resolved": "https://registry.npmjs.org/zod/-/zod-4.1.12.tgz", "integrity": "sha512-JInaHOamG8pt5+Ey8kGmdcAcg3OL9reK8ltczgHTAwNhMys/6ThXHityHxVV2p3fkw/c+MAvBHFVYHFZDmjMCQ==", "license": "MIT", - "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } diff --git a/website/src/css/custom.css b/website/src/css/custom.css index db45273..6bfd961 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -354,3 +354,24 @@ div[class*='announcementBar'] { border-bottom: 2px solid rgba(255, 255, 255, 0.1); box-shadow: 0 2px 12px rgba(234, 88, 12, 0.3); } + +/* ======================================================================== + LOCALE DROPDOWN - Click-only behavior (disable hover) + ======================================================================== + Override Docusaurus default hover behavior for the language selector. + The dropdown now only opens on click, not on hover. + ======================================================================== */ + +/* Disable hover behavior for locale dropdown */ +.navbar__item.dropdown.dropdown--hoverable:has([class*='iconLanguage']) .dropdown__menu { + visibility: hidden; + opacity: 0; + transition: visibility 0.2s, opacity 0.2s; +} + +/* Show dropdown only when explicitly shown (via click/keyboard) */ +.navbar__item.dropdown.dropdown--hoverable.dropdown--show:has([class*='iconLanguage']) .dropdown__menu { + visibility: visible; + opacity: 1; +} + diff --git a/website/src/pages/index.module.css b/website/src/pages/index.module.css index 266b726..11f0dd3 100644 --- a/website/src/pages/index.module.css +++ b/website/src/pages/index.module.css @@ -163,7 +163,11 @@ border-radius: 8px; overflow: hidden; box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3); - text-align: left; + /* rtl:ignore */ + text-align: left; + /* rtl:ignore */ + direction: ltr; + } .terminalHeader { @@ -202,6 +206,7 @@ .terminalBody { padding: 1.25rem 1.5rem; background: #1e1e1e; + } .terminalCode { @@ -212,7 +217,8 @@ margin: 0; white-space: pre-wrap; background: transparent; - text-align: left; + /* rtl:ignore */ + text-align: left; } .terminalKeyword { @@ -632,6 +638,8 @@ align-items: center; justify-content: space-between; margin-bottom: 0.5rem; + /* rtl:ignore */ + direction: ltr; } .projectTitle { diff --git a/website/src/pages/index.tsx b/website/src/pages/index.tsx index 5aa168a..b964d0a 100644 --- a/website/src/pages/index.tsx +++ b/website/src/pages/index.tsx @@ -3,6 +3,7 @@ import clsx from 'clsx'; import Link from '@docusaurus/Link'; import Layout from '@theme/Layout'; import Heading from '@theme/Heading'; +import {translate} from '@docusaurus/Translate'; import sidebars from '../../sidebars'; import promptsSidebars from '../../sidebarsPrompts'; @@ -68,7 +69,7 @@ function TerminalWindow() { {': File paths, line numbers, root cause'} - From the Prompt Library → + {translate({id: 'homepage.terminal.link', message: 'From the Prompt Library →'})} @@ -90,7 +91,7 @@ function HomepageHeader() { className={styles.heroBadge} > - Open Source + {translate({id: 'homepage.hero.badge.openSource', message: 'Open Source'})} · MIT {stars !== null && ( @@ -102,21 +103,20 @@ function HomepageHeader() { )} - Master Agentic Coding + {translate({id: 'homepage.hero.title', message: 'Master Agentic Coding'})}

- Structured methodology proven on enterprise mono-repos with - millions of lines of code + {translate({id: 'homepage.hero.subtitle', message: 'Structured methodology proven on enterprise mono-repos with millions of lines of code'})}

- Start Learning + {translate({id: 'homepage.hero.cta.startLearning', message: 'Start Learning'})} - Browse Prompts + {translate({id: 'homepage.hero.cta.browsePrompts', message: 'Browse Prompts'})}
@@ -124,15 +124,15 @@ function HomepageHeader() { to="/docs/faq" className={styles.heroStatLink} > - FAQ + {translate({id: 'homepage.hero.stats.faq', message: 'FAQ'})} | - {LESSON_COUNT} Lessons + {translate({id: 'homepage.hero.stats.lessons', message: '{count} Lessons'}, {count: LESSON_COUNT})} | - {PROMPT_COUNT} Production Prompts + {translate({id: 'homepage.hero.stats.prompts', message: '{count} Production Prompts'}, {count: PROMPT_COUNT})}
@@ -492,10 +492,10 @@ function EcosystemTools() {
- Open Source Ecosystem + {translate({id: 'homepage.ecosystem.title', message: 'Open Source Ecosystem'})}

- Production-ready tools that apply course methodology + {translate({id: 'homepage.ecosystem.subtitle', message: 'Production-ready tools that apply course methodology'})}

- Don't search your code. Research it. + {translate({id: 'homepage.ecosystem.chunkhound.tagline', message: "Don't search your code. Research it."})}

10K–1M+ LOC @@ -525,7 +525,7 @@ function EcosystemTools() {

- Wide research, not deep reports + {translate({id: 'homepage.ecosystem.arguseek.tagline', message: 'Wide research, not deep reports'})}

12–100+ sources per query @@ -539,11 +539,11 @@ function EcosystemTools() {
- Curated Toolbox + {translate({id: 'homepage.ecosystem.toolbox.title', message: 'Curated Toolbox'})}

- Modern CLI tools for AI-first development + {translate({id: 'homepage.ecosystem.toolbox.tagline', message: 'Modern CLI tools for AI-first development'})}

ripgrep, fzf, lazygit... @@ -551,10 +551,10 @@ function EcosystemTools() {

- The research layer that anchors your agents in reality + {translate({id: 'homepage.ecosystem.integrationNote', message: 'The research layer that anchors your agents in reality'})}

- ChunkHound and ArguSeek are created by the course author. + {translate({id: 'homepage.ecosystem.disclosureNote', message: 'ChunkHound and ArguSeek are created by the course author.'})}

@@ -572,7 +572,7 @@ function ModuleCard({ number, title, topics, link }: ModuleCardProps) { return (
-
Module {number}
+
{translate({id: 'homepage.modules.moduleLabel', message: 'Module {number}'}, {number})}
@@ -598,31 +598,31 @@ function CourseModules() { const modules = [ { number: 1, - title: 'Fundamentals', + title: translate({id: 'homepage.modules.1.title', message: 'Fundamentals'}), topics: [ - 'LLM internals: context, attention, token limits', - 'What breaks: hallucinations, code drift, refactoring', - 'Context management and RAG integration', + translate({id: 'homepage.modules.1.topic1', message: 'LLM internals: context, attention, token limits'}), + translate({id: 'homepage.modules.1.topic2', message: 'What breaks: hallucinations, code drift, refactoring'}), + translate({id: 'homepage.modules.1.topic3', message: 'Context management and RAG integration'}), ], link: '/docs/fundamentals/lesson-1-how-llms-work', }, { number: 2, - title: 'Methodology', + title: translate({id: 'homepage.modules.2.title', message: 'Methodology'}), topics: [ - 'Prompt structure: constraints, examples, chain-of-thought', - 'Grounding: embedding context that persists', - 'Iteration patterns: plan, execute, verify', + translate({id: 'homepage.modules.2.topic1', message: 'Prompt structure: constraints, examples, chain-of-thought'}), + translate({id: 'homepage.modules.2.topic2', message: 'Grounding: embedding context that persists'}), + translate({id: 'homepage.modules.2.topic3', message: 'Iteration patterns: plan, execute, verify'}), ], link: '/docs/methodology/lesson-3-high-level-methodology', }, { number: 3, - title: 'Practical Techniques', + title: translate({id: 'homepage.modules.3.title', message: 'Practical Techniques'}), topics: [ - 'CI integration and automated review patterns', - 'Test generation and coverage strategies', - 'Debugging sessions: when AI makes it worse', + translate({id: 'homepage.modules.3.topic1', message: 'CI integration and automated review patterns'}), + translate({id: 'homepage.modules.3.topic2', message: 'Test generation and coverage strategies'}), + translate({id: 'homepage.modules.3.topic3', message: 'Debugging sessions: when AI makes it worse'}), ], link: '/docs/practical-techniques/lesson-6-project-onboarding', }, @@ -632,11 +632,10 @@ function CourseModules() {
- What You'll Learn + {translate({id: 'homepage.modules.title', message: "What You'll Learn"})}

- {LESSON_COUNT} lessons covering research, planning, execution, and - validation patterns + {translate({id: 'homepage.modules.subtitle', message: '{count} lessons covering research, planning, execution, and validation patterns'}, {count: LESSON_COUNT})}

{modules.map((module) => ( @@ -654,34 +653,34 @@ function LearningFormats() {
- Learn Your Way + {translate({id: 'homepage.formats.title', message: 'Learn Your Way'})} -

Every lesson, three formats

+

{translate({id: 'homepage.formats.subtitle', message: 'Every lesson, three formats'})}

- Reference Docs + {translate({id: 'homepage.formats.docs.title', message: 'Reference Docs'})}

- Bookmark it. Jump back in when you need it. + {translate({id: 'homepage.formats.docs.description', message: 'Bookmark it. Jump back in when you need it.'})}

- Podcasts + {translate({id: 'homepage.formats.podcasts.title', message: 'Podcasts'})}

- Commute, gym, walking the dog. + {translate({id: 'homepage.formats.podcasts.description', message: 'Commute, gym, walking the dog.'})}

- Presentations + {translate({id: 'homepage.formats.presentations.title', message: 'Presentations'})} -

Share with your team.

+

{translate({id: 'homepage.formats.presentations.description', message: 'Share with your team.'})}

@@ -692,8 +691,8 @@ function LearningFormats() { export default function Home(): ReactNode { return (
diff --git a/website/src/theme/NavbarItem/DropdownNavbarItem/Desktop/index.tsx b/website/src/theme/NavbarItem/DropdownNavbarItem/Desktop/index.tsx new file mode 100644 index 0000000..ce1e89e --- /dev/null +++ b/website/src/theme/NavbarItem/DropdownNavbarItem/Desktop/index.tsx @@ -0,0 +1,86 @@ +/** + * Swizzled from @docusaurus/theme-classic to change dropdown behavior + * from hover-to-open to click-to-open for the locale selector. + */ + +import React, {useState, useRef, useEffect, type ReactNode} from 'react'; +import clsx from 'clsx'; +import NavbarNavLink from '@theme/NavbarItem/NavbarNavLink'; +import NavbarItem from '@theme/NavbarItem'; +import type {Props} from '@theme/NavbarItem/DropdownNavbarItem/Desktop'; + +export default function DropdownNavbarItemDesktop({ + items, + position, + className, + onClick, + ...props +}: Props): ReactNode { + const dropdownRef = useRef(null); + const [showDropdown, setShowDropdown] = useState(false); + + useEffect(() => { + const handleClickOutside = ( + event: MouseEvent | TouchEvent | FocusEvent, + ) => { + if ( + !dropdownRef.current || + dropdownRef.current.contains(event.target as Node) + ) { + return; + } + setShowDropdown(false); + }; + + document.addEventListener('mousedown', handleClickOutside); + document.addEventListener('touchstart', handleClickOutside); + document.addEventListener('focusin', handleClickOutside); + + return () => { + document.removeEventListener('mousedown', handleClickOutside); + document.removeEventListener('touchstart', handleClickOutside); + document.removeEventListener('focusin', handleClickOutside); + }; + }, [dropdownRef]); + + return ( +
+ { + if (!props.to) { + e.preventDefault(); + } + setShowDropdown(!showDropdown); + }} + onKeyDown={(e) => { + if (e.key === 'Enter') { + e.preventDefault(); + setShowDropdown(!showDropdown); + } + }}> + {props.children ?? props.label} + +
    + {items.map((childItemProps, i) => ( + + ))} +
+
+ ); +} diff --git a/website/src/theme/NavbarItem/DropdownNavbarItem/Mobile/index.tsx b/website/src/theme/NavbarItem/DropdownNavbarItem/Mobile/index.tsx new file mode 100644 index 0000000..8ad3820 --- /dev/null +++ b/website/src/theme/NavbarItem/DropdownNavbarItem/Mobile/index.tsx @@ -0,0 +1,164 @@ +/** + * Swizzled from @docusaurus/theme-classic - Mobile dropdown unchanged. + * Only Desktop version modified for click-to-open behavior. + */ + +import React, {useEffect, type ReactNode, type ComponentProps} from 'react'; +import clsx from 'clsx'; +import { + isRegexpStringMatch, + useCollapsible, + Collapsible, +} from '@docusaurus/theme-common'; +import {isSamePath, useLocalPathname} from '@docusaurus/theme-common/internal'; +import {translate} from '@docusaurus/Translate'; +import NavbarNavLink from '@theme/NavbarItem/NavbarNavLink'; +import NavbarItem, {type LinkLikeNavbarItemProps} from '@theme/NavbarItem'; +import type {Props} from '@theme/NavbarItem/DropdownNavbarItem/Mobile'; +import styles from './styles.module.css'; + +function isItemActive( + item: LinkLikeNavbarItemProps, + localPathname: string, +): boolean { + if (isSamePath(item.to, localPathname)) { + return true; + } + if (isRegexpStringMatch(item.activeBaseRegex, localPathname)) { + return true; + } + if (item.activeBasePath && localPathname.startsWith(item.activeBasePath)) { + return true; + } + return false; +} + +function containsActiveItems( + items: readonly LinkLikeNavbarItemProps[], + localPathname: string, +): boolean { + return items.some((item) => isItemActive(item, localPathname)); +} + +function CollapseButton({ + collapsed, + onClick, +}: { + collapsed: boolean; + onClick: ComponentProps<'button'>['onClick']; +}) { + return ( +