Holarch

הפניה

מתכון: GitHub

הרצת בדיקות המודל של Holarch מ-GitHub Actions ומעקב אחר הממצאים כ-issue ב-GitHub, ומתן אפשרות ל-Claude Code להציע מקרי בדיקה לדרישות שענף מממש; הגדרה, קובץ workflow, דוגמה מעובדת ופתרון בעיות.

אופן השימוש ←

בדף זה
  1. סקירה כללית
  2. דרישות מקדימות
  3. איך להשתמש בה
    1. מתי ולמה
    2. הגדרת המאגר
    3. הרצת בדיקות המודל לפי לוח זמנים
    4. הצעת מקרי בדיקה לענף עם Claude Code
    5. דוגמה מעשית: הדגמת CubeSat EO-1
    6. טיפים
  4. פתרון בעיות
  5. דפים קשורים

סקירה כללית

המתכון הזה מחבר מאגר GitHub לפרויקט Holarch. יש לו שני חלקים:

  • בדיקות המודל ב-GitHub Actions (REST API): תהליך עבודה מתוזמן מריץ את בדיקות המודל של Holarch על הדרישות של הפרויקט. הוא כותב את הממצאים לסיכום של ההרצה ושומר issue אחד ב-GitHub מעודכן בהם.
  • דרישות בסקירת קוד (MCP, דרך Claude Code): Claude Code קורא את הענף שעובדים עליו, מוצא ב-Holarch את הדרישות שהוא מממש, ומציע מקרי בדיקה שמאמתים אותן. סוקרים את ההצעה ב-Holarch לפני ששום דבר משתנה.

ל-Holarch אין אפליקציית GitHub מובנית. המתכון משתמש בREST API וב-MCP, כך שאפשר להתאים כל שלב.

דרישות מקדימות

  • תוכנית עם ה-API ו-MCP: Individual או Team, או תקופת הניסיון של Individual. בתוכנית Free, גם לחשבון עם כתובת דוא״ל אקדמית מאומתת או בארגון כיתה פעיל יש אותם (תוכניות ומגבלות).
  • פרויקט Holarch. תהליך העבודה רק קורא אותו; הצעות מ-Claude Code דורשות את תפקיד העורך או הבעלים.
  • מאגר GitHub שבו אפשר להוסיף סודות ומשתנים של Actions, ושבו Actions יכולים ליצור issues.
  • לחלק של Claude: Claude Code, מחובר ל-Holarch עם גישת קריאה והצעת שינויים (חיבור Holarch ל-Claude).

איך להשתמש בה

מתי ולמה

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

הגדרת המאגר

  1. ב-Holarch, יש ליצור אסימון קריאה בלבד שמוגבל לפרויקט: הגדרות החשבון ← אסימוני API ← אסימון חדש (יצירת אסימון).
  2. יש למצוא את מזהה הפרויקט: GET /api/v1/projects מפרט את הפרויקטים שלך עם ה-id שלהם.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. ב-GitHub, יש לפתוח את Settings → Secrets and variables → Actions של המאגר:
    • תחת Secrets, מוסיפים HOLARCH_TOKEN עם האסימון.
    • תחת Variables, מוסיפים HOLARCH_PROJECT עם מזהה הפרויקט.
  2. תחת Issues → Labels, יוצרים את התווית holarch. תהליך העבודה משתמש בה כדי למצוא את ה-issue שלו.

הרצת בדיקות המודל לפי לוח זמנים

יש לשמור את הקובץ הזה כ-.github/workflows/holarch-checks.yml ולבצע לו commit.

# Holarch Model Checks: requirement findings in the run summary and in one GitHub issue.
name: Holarch model checks
on:
  schedule:
    - cron: "0 6 * * 1-5"   # weekdays at 06:00 UTC
  workflow_dispatch:
permissions:
  issues: write
jobs:
  checks:
    runs-on: ubuntu-latest
    env:
      HOLARCH_TOKEN: ${{ secrets.HOLARCH_TOKEN }}
      HOLARCH_PROJECT: ${{ vars.HOLARCH_PROJECT }}
      GH_TOKEN: ${{ github.token }}
      GH_REPO: ${{ github.repository }}
    steps:
      - name: Run Model Checks
        run: |
          curl -sS --fail-with-body -H "Authorization: Bearer $HOLARCH_TOKEN" \
            "https://app.holarch.app/api/v1/projects/$HOLARCH_PROJECT/model-checks?class=Requirement" > checks.json
          jq -r '"Holarch Model Checks: \(.total) requirement findings\n",
                 (.issues[] | "- [ ] \(.rule) \(.entity.number) \(.entity.name): \(.heading)")' checks.json > findings.md
          cat findings.md >> "$GITHUB_STEP_SUMMARY"
      - name: Update the tracking issue
        run: |
          total=$(jq .total checks.json)
          issue=$(gh issue list --label holarch --state open --json number --jq '.[0].number')
          if [ "$total" -gt 0 ] && [ -z "$issue" ]; then
            gh issue create --title "Holarch Model Checks findings" --label holarch --body-file findings.md
          elif [ "$total" -gt 0 ]; then
            gh issue edit "$issue" --body-file findings.md
          elif [ -n "$issue" ]; then
            gh issue close "$issue" --comment "Holarch Model Checks find no requirement issues."
          fi

כדי להריץ אותו עכשיו, פותחים את Actions → Holarch model checks → Run workflow.

הממצאים מוצגים בסיכום של ההרצה, שורה אחת לכל ממצא, כגון Requirement.10 <number> <name>: Leaf requirements with no verifying test case. ה-issue Holarch Model Checks findings מכיל את אותה רשימה. כשהממצאים מתוקנים, ההרצה הבאה סוגרת אותו.

איך זה עובד:

  • GET /api/v1/projects/<project>/model-checks?class=Requirement מריץ את הבדיקות עם הגדרות הכללים של הפרויקט עצמו ומחזיר את הממצאים: rule, heading, entity (id, number, name) והפריטים הקשורים. התוצאות מוחזרות, לא נשמרות.
  • curl --fail-with-body מכשיל את השלב בשגיאה ומדפיס את ההודעה של Holarch, כגון {"error": "…", "code": "token-invalid"}.
  • gh ו-jq מגיעים עם ה-runners של Ubuntu ב-GitHub.

וריאציות:

  • כללים אחרים: משנים את class=Requirement למחלקה אחרת (Test Case, Asset, Custom לערכות הכללים שלך), או מציינים כלל אחד עם rule=Requirement.10.
  • איכות הדרישות: GET /api/v1/projects/<project>/quality נותן ציון לכל דרישה בתשעת מאפייני האיכות. באותה דרך מפרטים את הדרישות שה-score שלהן מתחת לסף שלך.
  • הכשלת ההרצה כשיש ממצאים: מוסיפים test "$total" -eq 0 כשורה האחרונה, למשל בבדיקות של ענף שחרור.

הצעת מקרי בדיקה לענף עם Claude Code

משתמשים בזה לפני שפותחים pull request, כדי שהדרישות ששינוי מממש יקבלו מקרה בדיקה מאמת.

  1. מחברים את Claude Code ל-Holarch פעם אחת:
claude mcp add --transport http holarch https://app.holarch.app/mcp

אחר כך מקלידים /mcp, בוחרים holarch ← אימות, נכנסים ל-Holarch ולוחצים על אישור עם קריאה והצעת שינויים.

  1. במאגר, בענף שלך, אפשר לשאול את Claude Code, למשל: "השווה את הענף הזה ל-main. מצא את הדרישות בפרויקט CubeSat ב-Holarch שהשינוי מממש, והצע מקרה בדיקה לכל אחת שאין לה מקרה בדיקה מאמת. ציין את הענף בסיכום ההצעה."
  2. Claude Code קורא את ה-diff עם git. ב-Holarch הוא משתמש ב-search_entities וב-get_entity כדי למצוא את הדרישות, וב-run_model_checks עם הכלל Requirement.10 כדי לראות לאילו אין מקרה בדיקה מאמת. הוא מוסיף כל מקרה בדיקה עם create_entity ועם הקשר verifies שלו, ואז שולח את ההצעה עם propose_changes.

    Claude Code עונה עם הכותרת של ההצעה וקישור לסקירה שלה.

  3. ב-Holarch, יש לפתוח את ✦ AI ▾ ← סקירת “<title>”…, או את ההתראה מתחת לפעמון.
  4. אם צריך, עורכים את השמות והתיאורים, ואז לוחצים על החלת הנבחרים.

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

כדאי להדביק את הקישור של הדרישה בתיאור ה-pull request: get_entity וה-REST API מחזירים אותו כ-url. הוא פותח את הדרישה לכל מי שחבר בפרויקט.

דוגמה מעשית: הדגמת CubeSat EO-1

  1. יוצרים את ההדגמה עם ניהול פרויקטים ← קובצי פרויקט ▾ ← פרויקט הדגמה חדש, ומשתמשים במזהה שלה כ-HOLARCH_PROJECT.
  2. מריצים את תהליך העבודה עם Run workflow.

    הסיכום מפרט את הדרישות שבדיקות המודל מסמנות, למשל דרישות עלה בלי מקרה בדיקה מאמת. ה-issue Holarch Model Checks findings מפרט את אותן.

  3. בענף שמשנה את קוד בקרת הגישה (attitude control), מבקשים מ-Claude Code להציע מקרי בדיקה לדרישות שהענף מממש.

    הדרישות של הקוד הזה הן 2.1 Pointing Accuracy ו-2.2 Pointing Stability. שתיהן כבר מאומתות על ידי TC-04 Pointing Accuracy Test, כך שאינן צריכות מקרה בדיקה חדש.

  4. במקום זאת מבקשים ממנו להציע מקרה בדיקה לדרישה מהרשימה של ה-issue, ואז סוקרים ומחילים את ההצעה ב-Holarch.
  5. מריצים שוב את תהליך העבודה.

    הדרישה הזו כבר אינה מופיעה ברשימה.

טיפים

  • כדאי לתת לתהליך העבודה אסימון קריאה בלבד משלו, מוגבל לפרויקט. כשמסירים את תהליך העבודה, מבטלים את האסימון תחת הגדרות החשבון ← אסימוני API.
  • תהליך העבודה המתוזמן משתמש בהגדרות הכללים של Holarch: מכבים כלל או משנים את הרמה שלו בבדיקות המודל, וההרצה הבאה פועלת בהתאם.
  • תוקפו של אסימון פג בתאריך שבחרת. לתהליך עבודה כדאי לבחור שנה אחת או אף פעם, ולרשום את התאריך.

פתרון בעיות

הודעה או תסמיןסיבה ותיקון
"code": "token-required"הסוד HOLARCH_TOKEN ריק או חסר. יש להוסיף אותו תחת Settings → Secrets and variables → Actions.
"code": "token-invalid"האסימון שגוי, בוטל או שתוקפו פג. יש ליצור אסימון חדש ולעדכן את הסוד.
"code": "plan-api"התוכנית של החשבון אינה כוללת את ה-API ו-MCP. יש להתחיל את תקופת הניסיון של Individual או לבחור תוכנית; האסימון יפעל אז שוב.
"code": "org-policy"הארגון של הפרויקט כיבה את גישת ה-API. יש לפנות למנהל ארגון.
"code": "not-found"HOLARCH_PROJECT אינו פרויקט שהאסימון יכול להשתמש בו. יש לבדוק את המזהה ואת ההגדרה פרויקטים של האסימון.
"code": "rate-limited"יותר מ-600 בקשות בדקה עם האסימון הזה. יש להריץ את תהליך העבודה בתדירות נמוכה יותר, או לתת לסקריפטים אחרים אסימונים משלהם.
gh issue create נכשל: התווית לא נמצאהיש ליצור את התווית holarch במאגר.
gh עונה HTTP 403תהליך העבודה צריך permissions: issues: write, והגדרות ה-Actions של המאגר חייבות להתיר זאת.
Claude Code אינו מציע את כלי הכתיבה של Holarchהחיבור הוא לקריאה בלבד. יש להריץ /mcp, לחבר מחדש את holarch עם קריאה והצעת שינויים, ואז להתחיל שיחה חדשה.