Holarch

Справочник

Рецепт: GitHub

Запуск проверок модели Holarch из GitHub Actions с отслеживанием замечаний в виде задачи 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, прежде чем что-либо изменится.

Встроенного приложения GitHub в Holarch нет. Рецепт использует 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

Используйте это перед открытием запроса на слияние, чтобы требования, которые реализует изменение, получили верифицирующий тестовый случай.

  1. Подключите Claude Code к Holarch один раз:
claude mcp add --transport http holarch https://app.holarch.app/mcp

Затем введите /mcp, выберите holarch → Authenticate, войдите в Holarch и нажмите Разрешить с Чтение и предложение изменений.

  1. В репозитории, в своей ветке, попросите Claude Code, например: “Compare this branch with main. Find the requirements in the Holarch CubeSat project that the change implements, and propose a test case for each one that has no verifying test case. Name the branch in the proposal summary.”
  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. При необходимости отредактируйте имена и описания, затем нажмите Применить выбранные.

    Тестовые случаи создаются с вашим именем в истории, и одно нажатие “Отменить” возвращает всё назад. Следующий запуск рабочего процесса по расписанию больше не перечисляет эти требования.

Вставьте ссылку на требование в описание запроса на слияние: 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 с доступом Чтение и предложение изменений, затем начните новую беседу.