Holarch

リファレンス

レシピ:GitHub

GitHub Actions から Holarch のモデルチェックを実行して指摘事項を GitHub の issue として追跡し、ブランチが実装する要求に対するテストケースを Claude Code に提案させます。設定、ワークフローファイル、具体例、トラブルシューティングを説明します。

使い方 →

このページの内容
  1. 概要
  2. 前提条件
  3. 使い方
    1. 使う場面と理由
    2. リポジトリを設定する
    3. スケジュールに従ってモデルチェックを実行する
    4. Claude Code でブランチのテストケースを提案する
    5. 実例:CubeSat EO-1 のデモ
    6. ヒント
  4. トラブルシューティング
  5. 関連ページ

概要

このレシピは、GitHub リポジトリを Holarch プロジェクトに接続します。2 つの部分があります:

  • GitHub Actions でのモデルチェック(REST API):スケジュールされたワークフローが、プロジェクトの要求に対して Holarch のモデルチェックを実行します。指摘事項を実行の概要に書き込み、1 つの GitHub の issue をそれで最新の状態に保ちます。
  • コードレビューでの要求(MCP、Claude Code を通じて):Claude Code が作業中のブランチを読み、それが実装している要求を Holarch で見つけ、それを検証するテストケースを提案します。何かが変わる前に、Holarch で提案をレビューします。

Holarch には組み込みの GitHub アプリはありません。このレシピは REST API と MCP を使うので、どの手順も調整できます。

前提条件

  • API と MCP を含むプラン:Individual または Team、または Individual トライアル。Free プランでも、確認済みのアカデミックメールアドレスがあるアカウント、または有効なクラス組織内のアカウントは利用できます(プランと上限)。
  • Holarch プロジェクト。ワークフローはそれを読み取るだけです。Claude Code からの提案には編集者またはオーナーのロールが必要です。
  • Actions のシークレットと変数を追加でき、Actions が issue を作成できる GitHub リポジトリ。
  • Claude の部分には:読み取りと変更の提案のアクセスで Holarch に接続した Claude Code(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 で、プロジェクト ID を値とする HOLARCH_PROJECT を追加します。
  2. Issues → Labels で、ラベル holarch を作成します。ワークフローはこれを使って自分の issue を見つけます。

スケジュールに従ってモデルチェックを実行する

このファイルを .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 を開きます。

実行の概要に、指摘事項が 1 件につき 1 行で表示されます。たとえば Requirement.10 <number> <name>: Leaf requirements with no verifying test case です。issue Holarch Model Checks findings にも同じ一覧が入ります。指摘事項が修正されると、次の実行でその issue がクローズされます。

仕組み:

  • GET /api/v1/projects/<project>/model-checks?class=Requirement は、プロジェクト独自のルール設定でチェックを実行し、指摘事項を返します:rule、heading、entity(id、number、name)、および関連する項目です。結果は返されるだけで、保存されません。
  • curl --fail-with-body は、エラー時にステップを失敗させ、{"error": "…", "code": "token-invalid"} のような Holarch のメッセージを出力します。
  • gh と jq は GitHub の Ubuntu ランナーに含まれています。

バリエーション:

  • その他のルール:class=Requirement を別のクラス(Test Case、Asset、独自のルールセットには Custom)に変えるか、rule=Requirement.10 で 1 つのルールを指定します。
  • 要求の品質:GET /api/v1/projects/<project>/quality は、すべての要求を 9 つの品質属性で採点します。score がしきい値を下回る要求も、同じ方法で一覧表示します。
  • 指摘事項があれば実行を失敗させる:最後の行として test "$total" -eq 0 を追加します。たとえばリリースブランチのチェックで使います。

Claude Code でブランチのテストケースを提案する

プルリクエストを開く前にこれを使うと、変更が実装する要求に検証するテストケースが付きます。

  1. Claude Code を Holarch に一度だけ接続します:
claude mcp add --transport http holarch https://app.holarch.app/mcp

次に /mcp と入力し、holarch → 認証を選んで Holarch にサインインし、読み取りと変更の提案で許可をクリックします。

  1. リポジトリの自分のブランチで、たとえば次のように Claude Code に依頼します:「このブランチを main と比較してください。変更が実装している Holarch の CubeSat プロジェクトの要求を見つけ、検証するテストケースのないものそれぞれにテストケースを提案してください。提案の要約にブランチ名を記載してください。」
  2. Claude Code は git で差分を読みます。Holarch では、search_entities と get_entity を使って要求を見つけ、ルール Requirement.10 を指定した run_model_checks で、どれに検証するテストケースがないかを確認します。create_entity とその verifies 関係で各テストケースを追加し、propose_changes で提案を送信します。

    Claude Code は、提案のタイトルとレビュー用のリンクで答えます。

  3. Holarch で ✦ AI ▾ → Review “<title>”…、またはベルの下の通知を開きます。
  4. 必要に応じて名前と説明を編集してから、選択した項目を適用をクリックします。

    テストケースは、履歴にあなたの名前を付けて作成されます。1 回の元に戻すですべて取り消せます。次にスケジュールされたワークフローの実行では、それらの要求は表示されなくなります。

要求のリンクをプルリクエストの説明に貼り付けます:get_entity と REST API はそれを url として返します。プロジェクトのメンバーであれば誰でも、そのリンクで要求を開けます。

実例:CubeSat EO-1 のデモ

  1. プロジェクトを管理 → プロジェクトファイル ▾ → 新しいデモプロジェクトでデモを作成し、その ID を HOLARCH_PROJECT として使います。
  2. Run workflow でワークフローを実行します。

    概要には、モデルチェックが指摘した要求が一覧表示されます。たとえば、検証するテストケースのない末端の要求です。issue Holarch Model Checks findings にも同じものが一覧表示されます。

  3. 姿勢制御のコードを変更するブランチで、そのブランチが実装する要求のテストケースを提案するよう Claude Code に依頼します。

    そのコードの要求は 2.1 Pointing Accuracy と 2.2 Pointing Stability です。どちらもすでに TC-04 Pointing Accuracy Test で検証されているので、新しいテストケースは必要ありません。

  4. 代わりに issue の一覧にある要求のテストケースを提案するよう依頼し、Holarch で提案をレビューして適用します。
  5. ワークフローをもう一度実行します。

    その要求は表示されなくなります。

ヒント

  • ワークフローには、プロジェクトに限定した専用の読み取り専用トークンを与えます。ワークフローを除去するときは、アカウント設定 → API トークンでそのトークンを失効させます。
  • スケジュールされたワークフローは Holarch のルール設定を使います:モデルチェックでルールをオフにするかレベルを変更すると、次の実行はそれに従います。
  • トークンは選択した日に期限切れになります。ワークフローには 1 年または無期限を選び、日付を控えておきます。

トラブルシューティング

メッセージまたは症状原因と対処
"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"このトークンで 1 分間に 600 リクエストを超えています。ワークフローの実行頻度を下げるか、他のスクリプトに専用のトークンを与えます。
gh issue create が失敗する:label not foundリポジトリにラベル holarch を作成します。
gh が HTTP 403 を返すワークフローには permissions: issues: write が必要で、リポジトリの Actions の設定でそれが許可されている必要があります。
Claude Code が Holarch の書き込みツールを提示しない接続が読み取り専用です。/mcp を実行し、読み取りと変更の提案で holarch を再接続してから、新しい会話を始めます。