Holarch

Referenz

Rezept: GitHub

Führen Sie Holarch-Modellprüfungen aus GitHub Actions aus und verfolgen Sie die Befunde als GitHub-Issue, und lassen Sie Claude Code Testfälle für die Anforderungen vorschlagen, die ein Branch umsetzt; Einrichtung, eine Workflow-Datei, ein durchgearbeitetes Beispiel und Fehlerbehebung.

So gehen Sie vor →

Auf dieser Seite
  1. Überblick
  2. Voraussetzungen
  3. So setzen Sie es ein
    1. Wann und warum
    2. Das Repository einrichten
    3. Modellprüfungen nach Zeitplan ausführen
    4. Mit Claude Code Testfälle für einen Branch vorschlagen
    5. Durchgehendes Beispiel: die CubeSat-EO-1-Demo
    6. Tipps
  4. Fehlerbehebung
  5. Verwandte Seiten

Überblick

Dieses Rezept verbindet ein GitHub-Repository mit einem Holarch-Projekt. Es hat zwei Teile:

  • Modellprüfungen in GitHub Actions (REST-API): Ein geplanter Workflow führt Holarchs Modellprüfungen für die Anforderungen des Projekts aus. Er schreibt die Befunde in die Zusammenfassung des Laufs und hält ein GitHub-Issue damit aktuell.
  • Anforderungen im Code-Review (MCP, über Claude Code): Claude Code liest den Branch, an dem Sie arbeiten, findet die Anforderungen in Holarch, die er umsetzt, und schlägt Testfälle vor, die sie verifizieren. Sie prüfen den Vorschlag in Holarch, bevor sich etwas ändert.

Holarch hat keine eingebaute GitHub-App. Das Rezept verwendet die REST-API und MCP, sodass Sie jeden Schritt anpassen können.

Voraussetzungen

  • Ein Tarif mit API und MCP: Individual oder Team oder die Testphase Individual. Im Tarif Free hat auch ein Konto mit einer bestätigten akademischen E-Mail-Adresse oder in einer aktiven Kursorganisation sie (Tarife und Grenzen).
  • Ein Holarch-Projekt. Der Workflow liest es nur; Vorschläge von Claude Code erfordern die Rolle Bearbeiter oder Eigentümer.
  • Ein GitHub-Repository, in dem Sie Actions-Secrets und -Variablen hinzufügen können und in dem Actions Issues erstellen kann.
  • Für den Teil mit Claude: Claude Code, mit Holarch verbunden mit dem Zugriff Lesen und Änderungen vorschlagen (Holarch mit Claude verbinden).

So setzen Sie es ein

Wann und warum

Modellprüfungen finden Lücken im Modell, etwa Anforderungen ohne verifizierenden Testfall. Sie nach Zeitplan auszuführen und die Befunde dort zu verfolgen, wo das Team ohnehin arbeitet, hält die Lücken zwischen Reviews sichtbar. Claude Code schließt den Kreis von der anderen Seite: Wenn Code eine Anforderung umsetzt, entwirft es den Testfall, der sie verifiziert.

Das Repository einrichten

  1. Erstellen Sie in Holarch ein Token mit Nur lesen, beschränkt auf das Projekt: Kontoeinstellungen → API-Token → Neues Token (Ein Token erstellen).
  2. Ermitteln Sie die Projekt-ID: GET /api/v1/projects listet Ihre Projekte mit ihrer id.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. Öffnen Sie in GitHub Settings → Secrets and variables → Actions des Repositorys:
    • Fügen Sie unter Secrets HOLARCH_TOKEN mit dem Token hinzu.
    • Fügen Sie unter Variables HOLARCH_PROJECT mit der Projekt-ID hinzu.
  2. Erstellen Sie unter Issues → Labels das Label holarch. Der Workflow findet sein Issue darüber.

Modellprüfungen nach Zeitplan ausführen

Speichern Sie diese Datei als .github/workflows/holarch-checks.yml und committen Sie sie.

# 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

Um ihn jetzt auszuführen, öffnen Sie Actions → Holarch model checks → Run workflow.

Sie sehen die Befunde in der Zusammenfassung des Laufs, eine Zeile pro Befund, etwa Requirement.10 <number> <name>: Leaf requirements with no verifying test case. Das Issue Holarch Model Checks findings enthält dieselbe Liste. Wenn die Befunde behoben sind, schließt der nächste Lauf es.

So funktioniert es:

  • GET /api/v1/projects/<project>/model-checks?class=Requirement führt die Prüfungen mit den eigenen Regeleinstellungen des Projekts aus und gibt die Befunde zurück: rule, heading, entity (id, number, name) und die zugehörigen Elemente. Ergebnisse werden zurückgegeben, nicht gespeichert.
  • curl --fail-with-body lässt den Schritt bei einem Fehler fehlschlagen und gibt die Meldung von Holarch aus, etwa {"error": "…", "code": "token-invalid"}.
  • gh und jq sind in den Ubuntu-Runnern von GitHub enthalten.

Varianten:

  • Andere Regeln: Ändern Sie class=Requirement in eine andere Klasse (Test Case, Asset, Custom für Ihre Regelsätze) oder nennen Sie eine Regel mit rule=Requirement.10.
  • Anforderungsqualität: GET /api/v1/projects/<project>/quality bewertet jede Anforderung nach den neun Qualitätsattributen. Listen Sie auf dieselbe Weise die Anforderungen auf, deren score unter Ihrem Schwellenwert liegt.
  • Den Lauf bei Befunden fehlschlagen lassen: Fügen Sie test "$total" -eq 0 als letzte Zeile hinzu, zum Beispiel in den Prüfungen eines Release-Branches.

Mit Claude Code Testfälle für einen Branch vorschlagen

Verwenden Sie dies, bevor Sie einen Pull Request öffnen, damit die Anforderungen, die eine Änderung umsetzt, einen verifizierenden Testfall erhalten.

  1. Verbinden Sie Claude Code einmalig mit Holarch:
claude mcp add --transport http holarch https://app.holarch.app/mcp

Geben Sie dann /mcp ein, wählen Sie holarch → Authentifizieren, melden Sie sich bei Holarch an und klicken Sie mit Lesen und Änderungen vorschlagen auf Zulassen.

  1. Fragen Sie im Repository auf Ihrem Branch Claude Code zum Beispiel: „Vergleiche diesen Branch mit main. Finde die Anforderungen im Holarch-CubeSat-Projekt, die die Änderung umsetzt, und schlage für jede, die keinen verifizierenden Testfall hat, einen Testfall vor. Nenne den Branch in der Zusammenfassung des Vorschlags.“
  2. Claude Code liest den Diff mit git. In Holarch verwendet es search_entities und get_entity, um die Anforderungen zu finden, und run_model_checks mit der Regel Requirement.10, um zu sehen, welche keinen verifizierenden Testfall haben. Es fügt jeden Testfall mit create_entity und seiner Beziehung verifies hinzu und sendet dann den Vorschlag mit propose_changes.

    Claude Code antwortet mit dem Titel des Vorschlags und einem Link, um ihn zu prüfen.

  3. Öffnen Sie in Holarch ✦ KI ▾ → „<title>“ prüfen… oder die Benachrichtigung unter der Glocke.
  4. Bearbeiten Sie bei Bedarf die Namen und Beschreibungen und klicken Sie dann auf Auswahl anwenden.

    Die Testfälle werden mit Ihrem Namen im Verlauf erstellt, und ein einziges Rückgängigmachen nimmt alles zurück. Der nächste geplante Workflow-Lauf listet diese Anforderungen nicht mehr.

Fügen Sie den Link der Anforderung in die Beschreibung des Pull Requests ein: get_entity und die REST-API geben ihn als url zurück. Er öffnet die Anforderung für jeden, der Mitglied des Projekts ist.

Durchgehendes Beispiel: die CubeSat-EO-1-Demo

  1. Erstellen Sie die Demo mit Projekte verwalten → Projektdateien ▾ → Neues Demoprojekt und verwenden Sie ihre ID als HOLARCH_PROJECT.
  2. Führen Sie den Workflow mit Run workflow aus.

    Die Zusammenfassung listet die Anforderungen, die die Modellprüfungen markieren, zum Beispiel Blattanforderungen ohne verifizierenden Testfall. Das Issue Holarch Model Checks findings listet dieselben.

  3. Bitten Sie Claude Code auf einem Branch, der den Code der Lageregelung ändert, Testfälle für die Anforderungen vorzuschlagen, die der Branch umsetzt.

    Die Anforderungen für diesen Code sind 2.1 Pointing Accuracy und 2.2 Pointing Stability. Beide werden bereits von TC-04 Pointing Accuracy Test verifiziert, sie brauchen also keinen neuen Testfall.

  4. Bitten Sie es stattdessen, einen Testfall für eine Anforderung aus der Liste des Issues vorzuschlagen, und prüfen und wenden Sie den Vorschlag dann in Holarch an.
  5. Führen Sie den Workflow erneut aus.

    Diese Anforderung wird nicht mehr aufgeführt.

Tipps

  • Geben Sie dem Workflow ein eigenes Token mit Nur-Lesen-Zugriff, beschränkt auf das Projekt. Widerrufen Sie es unter Kontoeinstellungen → API-Token, wenn Sie den Workflow entfernen.
  • Der geplante Workflow verwendet die Regeleinstellungen von Holarch: Schalten Sie in den Modellprüfungen eine Regel aus oder ändern Sie ihre Stufe, und der nächste Lauf folgt.
  • Ein Token läuft an dem von Ihnen gewählten Datum ab. Wählen Sie für einen Workflow ein Jahr oder nie und notieren Sie das Datum.

Fehlerbehebung

Meldung oder SymptomUrsache und Behebung
"code": "token-required"Das Secret HOLARCH_TOKEN ist leer oder fehlt. Fügen Sie es unter Settings → Secrets and variables → Actions hinzu.
"code": "token-invalid"Das Token ist falsch, widerrufen oder abgelaufen. Erstellen Sie ein neues und aktualisieren Sie das Secret.
"code": "plan-api"Der Tarif des Kontos enthält API und MCP nicht. Beginnen Sie die Testphase Individual oder wählen Sie einen Tarif; das Token funktioniert dann wieder.
"code": "org-policy"Die Organisation des Projekts hat den API-Zugriff ausgeschaltet. Fragen Sie einen Organisationsadmin.
"code": "not-found"HOLARCH_PROJECT ist kein Projekt, das das Token verwenden kann. Prüfen Sie die ID und die Einstellung Projekte des Tokens.
"code": "rate-limited"Mehr als 600 Anfragen pro Minute mit diesem Token. Führen Sie den Workflow seltener aus oder geben Sie anderen Skripten eigene Token.
gh issue create schlägt fehl: Label nicht gefundenErstellen Sie das Label holarch im Repository.
gh antwortet mit HTTP 403Der Workflow braucht permissions: issues: write, und die Actions-Einstellungen des Repositorys müssen es erlauben.
Claude Code bietet die Holarch-Schreibwerkzeuge nicht anDie Verbindung hat nur Lesezugriff. Führen Sie /mcp aus, verbinden Sie holarch erneut mit Lesen und Änderungen vorschlagen und beginnen Sie dann ein neues Gespräch.