Holarch

Довідник

Рецепт: GitHub

Запускайте перевірки моделі Holarch з GitHub Actions, відстежуйте зауваження як issue на GitHub і дозвольте Claude Code пропонувати тестові випадки для вимог, які реалізує гілка; налаштування, файл робочого процесу, розібраний приклад і усунення несправностей.

Як цим користуватися →

На цій сторінці
  1. Огляд
  2. Передумови
  3. Як користуватися
    1. Коли й навіщо
    2. Налаштування репозиторію
    3. Запуск перевірок моделі за розкладом
    4. Пропонування тестових випадків для гілки за допомогою Claude Code
    5. Робочий приклад: демопроєкт CubeSat EO-1
    6. Поради
  4. Усунення несправностей
  5. Пов’язані сторінки

Огляд

Цей рецепт з’єднує репозиторій GitHub із проєктом Holarch. Він має дві частини:

  • Перевірки моделі в GitHub Actions (REST API): запланований робочий процес запускає перевірки моделі Holarch для вимог проєкту. Він записує зауваження в підсумок запуску й підтримує актуальною одну задачу 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 можуть створювати задачі.
  • Для частини з Claude: Claude Code, під’єднаний до Holarch з доступом Читати й пропонувати зміни (Під’єднати Holarch до Claude).

Як користуватися

Коли й навіщо

Перевірки моделі знаходять прогалини в моделі, як-от вимоги без тестового випадку, що їх верифікує. Запуск за розкладом і відстеження зауважень там, де команда вже працює, тримає прогалини на виду між рецензуваннями. Claude Code замикає цикл з іншого боку: коли код реалізує вимогу, він готує чернетку тестового випадку, що її верифікує.

Налаштування репозиторію

  1. У Holarch створіть токен Лише читання, обмежений проєктом: Налаштування облікового запису → Токени API → Новий токен (Створення токена).
  2. Знайдіть id проєкту: 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 з id проєкту.
  2. У розділі Issues → Labels створіть мітку holarch. Робочий процес використовує її, щоб знайти свою задачу.

Запуск перевірок моделі за розкладом

Збережіть цей файл як .github/workflows/holarch-checks.yml і закомітьте його.

# 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. Задача 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 входять до раннерів 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 → Authenticate, увійдіть у Holarch і натисніть Дозволити з Читати й пропонувати зміни.

  1. У репозиторії, у своїй гілці, попросіть Claude Code, наприклад: "Порівняй цю гілку з main. Знайди вимоги в проєкті Holarch CubeSat, які реалізує зміна, і запропонуй тестовий випадок для кожної, що не має тестового випадку, який її верифікує. Назви гілку в підсумку пропозиції."
  2. Claude Code читає diff за допомогою git. У Holarch він використовує search_entities і get_entity, щоб знайти вимоги, і run_model_checks із правилом Requirement.10, щоб побачити, які не мають тестового випадку, що їх верифікує. Він додає кожен тестовий випадок через create_entity з його зв’язком verifies, потім надсилає пропозицію через propose_changes.

    Claude Code відповідає назвою пропозиції й посиланням для її перегляду.

  3. У Holarch відкрийте ✦ ШІ ▾ → Переглянути “<title>”… або сповіщення під дзвіночком.
  4. За потреби відредагуйте назви й описи, потім натисніть Застосувати вибране.

    Тестові випадки створюються з вашим іменем в історії, і одне натискання “Відмінити” повертає все назад. Наступний запланований запуск робочого процесу більше не наводить ці вимоги.

Вставте посилання на вимогу в опис pull request: get_entity і REST API повертають його як url. Воно відкриває вимогу для будь-кого, хто є учасником проєкту.

Робочий приклад: демопроєкт CubeSat EO-1

  1. Створіть демо через Керування проєктами → Файли проєктів ▾ → Новий демопроєкт і використайте його id як HOLARCH_PROJECT.
  2. Запустіть робочий процес через Run workflow.

    Підсумок перелічує вимоги, які позначають перевірки моделі, наприклад листкові вимоги без тестового випадку, що їх верифікує. Задача Holarch Model Checks findings перелічує те саме.

  3. У гілці, що змінює код керування орієнтацією, попросіть Claude Code запропонувати тестові випадки для вимог, які реалізує гілка.

    Вимоги до цього коду — 2.1 Pointing Accuracy і 2.2 Pointing Stability. Обидві вже верифікує TC-04 Pointing Accuracy Test, тож нові тестові випадки їм не потрібні.

  4. Натомість попросіть його запропонувати тестовий випадок для вимоги зі списку задачі, потім перегляньте й застосуйте пропозицію в 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 не є проєктом, який може використовувати токен. Перевірте id і налаштування Проєкти токена.
"code": "rate-limited"Понад 600 запитів на хвилину з цим токеном. Запускайте робочий процес рідше або дайте іншим скриптам власні токени.
gh issue create завершується помилкою: мітку не знайденоСтворіть мітку holarch у репозиторії.
gh відповідає HTTP 403Робочому процесу потрібно permissions: issues: write, і налаштування Actions репозиторію мають це дозволяти.
Claude Code не пропонує інструментів запису HolarchЗ’єднання лише для читання. Виконайте /mcp, перепід’єднайте holarch з Читати й пропонувати зміни, потім почніть нову розмову.