Holarch

Referencja

Przepis: GitHub

Uruchamiaj Kontrole modelu Holarch z GitHub Actions i śledź ustalenia jako zgłoszenie GitHub oraz pozwól Claude Code proponować przypadki testowe dla wymagań implementowanych przez gałąź; konfiguracja, plik przepływu pracy, przykład krok po kroku i rozwiązywanie problemów.

Jak z niego korzystać →

Na tej stronie
  1. Przegląd
  2. Wymagania wstępne
  3. Jak z niego korzystać
    1. Kiedy i dlaczego
    2. Konfiguracja repozytorium
    3. Uruchamianie kontroli modelu według harmonogramu
    4. Proponowanie przypadków testowych dla gałęzi za pomocą Claude Code
    5. Przykład: demo CubeSat EO-1
    6. Wskazówki
  4. Rozwiązywanie problemów
  5. Powiązane strony

Przegląd

Ten przepis łączy repozytorium GitHub z projektem Holarch. Ma dwie części:

  • Kontrole modelu w GitHub Actions (REST API): zaplanowany przepływ pracy uruchamia kontrole modelu Holarch na wymaganiach projektu. Zapisuje ustalenia w podsumowaniu przebiegu i utrzymuje z nimi aktualne jedno zgłoszenie GitHub.
  • Wymagania w przeglądzie kodu (MCP, przez Claude Code): Claude Code odczytuje gałąź, nad którą pracujesz, znajduje w Holarch realizowane przez nią wymagania i proponuje weryfikujące je przypadki testowe. Przeglądasz propozycję w Holarch, zanim cokolwiek się zmieni.

Holarch nie ma wbudowanej aplikacji GitHub. Przepis korzysta z REST API i MCP, więc każdy krok można dostosować.

Wymagania wstępne

  • Plan z API i MCP: Individual lub Team albo okres próbny Individual. W planie Free mają je też konta ze zweryfikowanym akademickim adresem e-mail lub w aktywnej organizacji zajęć (Plany i limity).
  • Projekt Holarch. Przepływ pracy tylko go odczytuje; propozycje z Claude Code wymagają roli edytora lub właściciela.
  • Repozytorium GitHub, w którym możesz dodawać sekrety i zmienne Actions i w którym Actions mogą tworzyć zgłoszenia.
  • Dla części z Claude: Claude Code połączony z Holarch z dostępem Odczyt i proponowanie zmian (Podłączanie Holarch do Claude).

Jak z niego korzystać

Kiedy i dlaczego

Kontrole modelu znajdują luki w modelu, np. wymagania bez weryfikującego przypadku testowego. Uruchamianie ich według harmonogramu i śledzenie ustaleń tam, gdzie zespół już pracuje, utrzymuje luki widoczne między przeglądami. Claude Code zamyka pętlę od drugiej strony: gdy kod realizuje wymaganie, przygotowuje projekt weryfikującego je przypadku testowego.

Konfiguracja repozytorium

  1. W Holarch utwórz token Tylko do odczytu ograniczony do projektu: Ustawienia konta → Tokeny API → Nowy token (Tworzenie tokenu).
  2. Znajdź id projektu: GET /api/v1/projects wymienia Twoje projekty z ich id.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. W GitHub otwórz Settings → Secrets and variables → Actions repozytorium:
    • W sekcji Secrets dodaj HOLARCH_TOKEN z tokenem.
    • W sekcji Variables dodaj HOLARCH_PROJECT z id projektu.
  2. W Issues → Labels utwórz etykietę holarch. Przepływ pracy używa jej do znalezienia swojego zgłoszenia.

Uruchamianie kontroli modelu według harmonogramu

Zapisz ten plik jako .github/workflows/holarch-checks.yml i zatwierdź go (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

Aby uruchomić go teraz, otwórz Actions → Holarch model checks → Run workflow.

Ustalenia widać w podsumowaniu przebiegu, jeden wiersz na ustalenie, np. Requirement.10 <number> <name>: Leaf requirements with no verifying test case. Zgłoszenie Holarch Model Checks findings zawiera tę samą listę. Gdy ustalenia zostaną naprawione, następny przebieg je zamyka.

Jak to działa:

  • GET /api/v1/projects/<project>/model-checks?class=Requirement wykonuje kontrole z własnymi ustawieniami reguł projektu i zwraca ustalenia: rule, heading, entity (id, number, name) i powiązane elementy. Wyniki są zwracane, a nie zapisywane.
  • curl --fail-with-body przerywa krok przy błędzie i wypisuje komunikat Holarch, np. {"error": "…", "code": "token-invalid"}.
  • gh i jq są dostępne w maszynach Ubuntu GitHub.

Warianty:

  • Inne reguły: zmień class=Requirement na inną klasę (Test Case, Asset, Custom dla własnych zestawów reguł) lub wskaż jedną regułę przez rule=Requirement.10.
  • Jakość wymagań: GET /api/v1/projects/<project>/quality ocenia każde wymaganie według dziewięciu atrybutów jakości. W ten sam sposób wyświetl wymagania, których score jest poniżej Twojego progu.
  • Przerywanie przebiegu przy ustaleniach: dodaj test "$total" -eq 0 jako ostatni wiersz, na przykład w kontrolach gałęzi wydania.

Proponowanie przypadków testowych dla gałęzi za pomocą Claude Code

Użyj tego przed otwarciem pull requesta, aby wymagania realizowane przez zmianę otrzymały weryfikujący przypadek testowy.

  1. Połącz Claude Code z Holarch jeden raz:
claude mcp add --transport http holarch https://app.holarch.app/mcp

Następnie wpisz /mcp, wybierz holarch → Authenticate, zaloguj się do Holarch i kliknij Zezwól z dostępem Odczyt i proponowanie zmian.

  1. W repozytorium, na swojej gałęzi, poproś Claude Code na przykład: “Porównaj tę gałąź z main. Znajdź w projekcie Holarch CubeSat wymagania realizowane przez tę zmianę i zaproponuj przypadek testowy dla każdego, które nie ma weryfikującego przypadku testowego. Podaj nazwę gałęzi w podsumowaniu propozycji.”
  2. Claude Code odczytuje różnice za pomocą git. W Holarch używa search_entities i get_entity, aby znaleźć wymagania, oraz run_model_checks z regułą Requirement.10, aby sprawdzić, które nie mają weryfikującego przypadku testowego. Dodaje każdy przypadek testowy za pomocą create_entity wraz z relacją verifies, a następnie wysyła propozycję za pomocą propose_changes.

    Claude Code odpowiada tytułem propozycji i łączem do jej przeglądu.

  3. W Holarch otwórz ✦ AI ▾ → Przejrzyj “<title>”… albo powiadomienie pod dzwonkiem.
  4. W razie potrzeby edytuj nazwy i opisy, a następnie kliknij Zastosuj zaznaczone.

    Przypadki testowe zostają utworzone z Twoim nazwiskiem w historii, a jedno polecenie Cofnij wycofuje całość. Następny zaplanowany przebieg przepływu pracy przestaje wymieniać te wymagania.

Wklej łącze do wymagania w opisie pull requesta: get_entity i REST API zwracają je jako url. Otwiera ono wymaganie dla każdego członka projektu.

Przykład: demo CubeSat EO-1

  1. Utwórz projekt demonstracyjny poleceniem Zarządzaj projektami → Pliki projektów ▾ → Nowy projekt demonstracyjny i użyj jego id jako HOLARCH_PROJECT.
  2. Uruchom przepływ pracy przyciskiem Run workflow.

    Podsumowanie wymienia wymagania oznaczone przez kontrole modelu, na przykład wymagania liście bez weryfikującego przypadku testowego. Zgłoszenie Holarch Model Checks findings wymienia to samo.

  3. Na gałęzi zmieniającej kod sterowania orientacją poproś Claude Code o zaproponowanie przypadków testowych dla wymagań realizowanych przez gałąź.

    Wymagania dla tego kodu to 2.1 Pointing Accuracy i 2.2 Pointing Stability. Oba są już weryfikowane przez TC-04 Pointing Accuracy Test, więc nie potrzebują nowego przypadku testowego.

  4. Poproś zamiast tego o zaproponowanie przypadku testowego dla wymagania z listy zgłoszenia, a następnie przejrzyj i zastosuj propozycję w Holarch.
  5. Uruchom przepływ pracy ponownie.

    To wymaganie nie jest już wymienione.

Wskazówki

  • Daj przepływowi pracy własny token tylko do odczytu, ograniczony do projektu. Unieważnij go w Ustawienia konta → Tokeny API po usunięciu przepływu pracy.
  • Zaplanowany przepływ pracy używa ustawień reguł Holarch: wyłącz regułę lub zmień jej poziom w Kontrolach modelu, a następny przebieg to uwzględni.
  • Token wygasa w wybranym dniu. Dla przepływu pracy wybierz rok lub nigdy i zanotuj datę.

Rozwiązywanie problemów

Komunikat lub objawPrzyczyna i rozwiązanie
"code": "token-required"Sekret HOLARCH_TOKEN jest pusty lub go brak. Dodaj go w Settings → Secrets and variables → Actions.
"code": "token-invalid"Token jest błędny, unieważniony lub wygasł. Utwórz nowy i zaktualizuj sekret.
"code": "plan-api"Plan konta nie obejmuje API i MCP. Rozpocznij okres próbny Individual lub wybierz plan; token znów zadziała.
"code": "org-policy"Organizacja projektu wyłączyła dostęp przez API. Zwróć się do administratora organizacji.
"code": "not-found"HOLARCH_PROJECT nie jest projektem, którego token może używać. Sprawdź id i ustawienie Projekty tokenu.
"code": "rate-limited"Ponad 600 żądań na minutę z tym tokenem. Uruchamiaj przepływ pracy rzadziej lub daj innym skryptom własne tokeny.
gh issue create kończy się błędem: nie znaleziono etykietyUtwórz w repozytorium etykietę holarch.
gh odpowiada HTTP 403Przepływ pracy wymaga permissions: issues: write, a ustawienia Actions repozytorium muszą na to pozwalać.
Claude Code nie oferuje narzędzi zapisu HolarchPołączenie jest tylko do odczytu. Uruchom /mcp, połącz ponownie holarch z dostępem Odczyt i proponowanie zmian, a następnie rozpocznij nową rozmowę.