Holarch

참조

레시피: GitHub

GitHub Actions에서 Holarch 모델 검사를 실행하고 발견 사항을 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의 제안에는 편집자 또는 소유자 역할이 필요합니다.
  • Actions 비밀과 변수를 추가할 수 있고 Actions가 이슈를 만들 수 있는 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를 만듭니다. 워크플로가 이를 사용해 자기 이슈를 찾습니다.

일정에 따라 모델 검사 실행

이 파일을 .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는 오류가 나면 단계를 실패시키고 {"error": "…", "code": "token-invalid"} 같은 Holarch의 메시지를 출력합니다.
  • gh와 jq는 GitHub의 Ubuntu 러너에 포함되어 있습니다.

변형:

  • 다른 규칙: 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 → 인증을 선택한 후, Holarch에 로그인하고 읽기 및 변경 제안으로 허용을 클릭합니다.

  1. 저장소의 브랜치에서 Claude Code에게 예를 들어 이렇게 묻습니다. “이 브랜치를 main과 비교해 줘. 변경이 구현하는 Holarch CubeSat 프로젝트의 요구사항을 찾고, 검증하는 테스트 케이스가 없는 각 요구사항에 테스트 케이스를 제안해 줘. 제안 요약에 브랜치 이름을 적어 줘.”
  2. Claude Code는 git으로 diff를 읽습니다. Holarch에서는 search_entities와 get_entity로 요구사항을 찾고, 규칙 Requirement.10으로 run_model_checks를 실행해 검증하는 테스트 케이스가 없는 요구사항을 확인합니다. create_entity와 그 verifies 관계로 각 테스트 케이스를 추가한 다음 propose_changes로 제안을 보냅니다.

    Claude Code가 제안의 제목과 검토 링크로 답합니다.

  3. Holarch에서 ✦ AI ▾ → “<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의 규칙 설정을 사용합니다. 모델 검사에서 규칙을 끄거나 수준을 바꾸면 다음 실행이 이를 따릅니다.
  • 토큰은 선택한 날짜에 만료됩니다. 워크플로에는 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"이 토큰으로 분당 요청 600건을 넘었습니다. 워크플로를 덜 자주 실행하거나 다른 스크립트에 자체 토큰을 줍니다.
gh issue create 실패: label not found저장소에 레이블 holarch를 만듭니다.
gh가 HTTP 403으로 응답워크플로에 permissions: issues: write가 필요하며, 저장소의 Actions 설정이 이를 허용해야 합니다.
Claude Code가 Holarch 쓰기 도구를 제공하지 않음연결이 읽기 전용입니다. /mcp를 실행하고 읽기 및 변경 제안으로 holarch를 다시 연결한 다음 새 대화를 시작합니다.