Holarch

참조

레시피: Jira

REST API로 Holarch 요구사항을 Jira 이슈에 연결하고, Claude를 통해 Jira 이슈를 검토된 Holarch 변경으로 바꿉니다. 설정, 동기화 스크립트, 실습 예제, 문제 해결을 다룹니다.

사용 방법 →

이 페이지의 내용
  1. 개요
  2. 사전 요구 사항
  3. 사용 방법
    1. 사용 시기와 이유
    2. 동기화 설정
    3. 승인된 요구사항에서 Jira 이슈 만들기
    4. Holarch에 Jira 키 보관(선택 사항)
    5. Claude로 Jira 이슈를 Holarch 제안으로 바꾸기
    6. 실습 예제: CubeSat EO-1 데모
    7. 팁
  4. 문제 해결
  5. 관련 페이지

개요

이 레시피는 Jira의 엔지니어링 작업을 Holarch의 요구사항에 연결된 상태로 유지합니다. 두 부분으로 이루어져 있습니다.

  • Holarch에서 Jira로(REST API): 스크립트가 승인된 요구사항마다 Jira 이슈를 하나씩 만듭니다. 각 이슈는 Holarch의 요구사항으로 다시 링크됩니다. 언제든지 다시 실행할 수 있으며, 이미 이슈가 있는 요구사항은 건너뜁니다.
  • Jira에서 Holarch로(MCP, Claude를 통해): Claude가 고객 변경 요청 같은 Jira 이슈를 읽고 해당하는 요구사항 변경을 Holarch에 제안합니다. Holarch에서 제안을 검토하고 적용하기 전에는 아무것도 바뀌지 않습니다.

Holarch에는 기본 제공 Jira 커넥터가 없습니다. 이 레시피는 REST API 및 MCP를 사용하므로 모든 단계를 조정할 수 있습니다.

사전 요구 사항

  • API와 MCP가 포함된 요금제: Individual 또는 Team, 또는 Individual 체험판입니다. Free 요금제에서도 확인된 학술 이메일 주소가 있거나 활성 수업 조직에 속한 계정은 이를 사용할 수 있습니다(요금제 및 한도).
  • 편집자나 소유자로 있는 Holarch 프로젝트. 제안에는 편집자 역할이 필요합니다.
  • 개인 액세스 토큰: 계정 설정 → API 토큰 → 새 토큰. Holarch에서 Jira로 가는 스크립트에는 읽기 전용을 사용하고 프로젝트로 제한합니다(토큰 만들기).
  • Jira Cloud: 이슈를 만들 수 있는 Jira 프로젝트와 Atlassian API 토큰(Atlassian 계정 설정 → Security → API tokens). Jira Data Center는 대신 /rest/api/2/ 경로와 개인 액세스 토큰을 사용하므로 해당 API 참조를 확인합니다.
  • 스크립트용으로 requests 패키지(python3 -m pip install requests)가 있는 Python 3.9 이상.
  • Claude 부분: Holarch에 연결된 Claude(Holarch를 Claude에 연결). Claude는 Jira 커넥터도 있을 때만 Jira 이슈를 직접 읽으며, 그렇지 않으면 이슈 텍스트를 대화에 붙여 넣습니다.

사용 방법

사용 시기와 이유

요구사항은 Holarch에 있고, 이를 구축하고 테스트하는 작업은 흔히 Jira에서 계획됩니다. 둘을 연결하면 두 가지 질문에 답할 수 있습니다. “이 요구사항을 구현하는 Jira 작업은 무엇인가?”와 “이 변경 요청이 어떤 요구사항에 영향을 주는가?”입니다. 요구사항 검토가 끝날 때마다, 새 요구사항이 Approved가 되면 동기화를 실행합니다.

동기화 설정

  1. Holarch에서 프로젝트로 제한한 읽기 전용 토큰을 만들고 복사합니다.
  2. 프로젝트 id를 찾습니다. GET /api/v1/projects가 프로젝트를 id와 함께 나열합니다.
curl -H "Authorization: Bearer hol_…" https://app.holarch.app/api/v1/projects
  1. 스크립트가 읽는 환경 변수를 설정합니다.
    • HOLARCH_TOKEN: Holarch 토큰.
    • HOLARCH_PROJECT: 프로젝트 id.
    • JIRA_URL: Jira 사이트(예: https://your-site.atlassian.net).
    • JIRA_EMAIL 및 JIRA_API_TOKEN: Atlassian 로그인 이메일과 API 토큰.
    • JIRA_PROJECT: Jira 프로젝트 키(예: EO).
  2. 아래 스크립트를 holarch_to_jira.py로 저장합니다.

승인된 요구사항에서 Jira 이슈 만들기

스크립트는 REST API로 모든 요구사항을 읽고, 이미 Jira 이슈가 있는 요구사항은 건너뛰며, 상태가 Approved인 나머지 요구사항마다 Task를 만듭니다.

# holarch_to_jira.py: one Jira issue per approved Holarch requirement. Safe to run again.
import os

import requests

HOLARCH = os.environ.get("HOLARCH_URL", "https://app.holarch.app") + "/api/v1"
PROJECT = os.environ["HOLARCH_PROJECT"]
HEADERS = {"Authorization": "Bearer " + os.environ["HOLARCH_TOKEN"]}
JIRA = os.environ["JIRA_URL"].rstrip("/")
JIRA_AUTH = (os.environ["JIRA_EMAIL"], os.environ["JIRA_API_TOKEN"])
JIRA_PROJECT = os.environ["JIRA_PROJECT"]


def holarch(method, path, **kw):
    r = requests.request(method, HOLARCH + path, headers=HEADERS, timeout=60, **kw)
    if r.status_code >= 400:
        d = r.json()
        raise SystemExit(f"Holarch answered {r.status_code} {d.get('code')}: {d.get('error')}")
    return r.json()


def requirements():
    offset = 0
    while True:
        page = holarch("GET", f"/projects/{PROJECT}/entities",
                       params={"class": "Requirement", "limit": 500, "offset": offset})
        yield from page["entities"]
        offset += page["limit"]
        if offset >= page["total"]:
            return


def linked_in_jira():
    """The Jira labels holarch-<requirement id> already on issues of the Jira project."""
    seen, token = set(), None
    while True:
        params = {"jql": f'project = "{JIRA_PROJECT}" AND labels = holarch', "fields": "labels", "maxResults": 100}
        if token:
            params["nextPageToken"] = token
        r = requests.get(JIRA + "/rest/api/3/search/jql", params=params, auth=JIRA_AUTH, timeout=60)
        r.raise_for_status()
        d = r.json()
        for issue in d.get("issues", []):
            seen.update(x for x in issue["fields"]["labels"] if x.startswith("holarch-"))
        token = d.get("nextPageToken")
        if not token:
            return seen


seen = linked_in_jira()
for req in requirements():
    if "holarch-" + req["id"] in seen:
        continue
    e = holarch("GET", f"/projects/{PROJECT}/entities/{req['id']}")["entity"]
    if e["attributes"].get("Status") != "Approved":
        continue
    text = (e["description"] + "\n\n" if e["description"] else "") + "Requirement in Holarch: " + e["url"]
    fields = {
        "project": {"key": JIRA_PROJECT},
        "issuetype": {"name": "Task"},
        "summary": f"{e['number']} {e['name']}".strip(),
        "labels": ["holarch", "holarch-" + e["id"]],
        "description": {"type": "doc", "version": 1, "content": [
            {"type": "paragraph", "content": [{"type": "text", "text": text}]}]},
    }
    issue = requests.post(JIRA + "/rest/api/3/issue", json={"fields": fields}, auth=JIRA_AUTH, timeout=60)
    issue.raise_for_status()
    key = issue.json()["key"]
    print(f"{e['number']} {e['name']} -> {key}")
  1. python3 holarch_to_jira.py를 실행합니다.

    새 이슈마다 2.1 Pointing Accuracy -> EO-12 같은 줄이 하나씩 표시됩니다.

작동 방식:

  • GET /api/v1/projects/<project>/entities?class=Requirement는 요구사항을 한 번에 500개씩 나열합니다.
  • GET /api/v1/projects/<project>/entities/<id>는 각 요구사항의 속성(여기서는 상태)과 Holarch에서 요구사항을 여는 링크인 url을 제공합니다.
  • 각 이슈는 Jira 레이블 holarch와 holarch-<id>를 받습니다. 다음 실행은 Jira 검색으로 이를 찾아 해당 요구사항을 건너뜁니다.
  • 요구사항은 읽기만 합니다. 스크립트는 Holarch에서 아무것도 변경하지 않습니다.

Holarch에 Jira 키 보관(선택 사항)

Holarch의 요구사항에서 Jira 키를 보려면 텍스트 속성을 추가하고 거기에 키를 씁니다.

  1. Holarch에서 설정 → 스키마를 열고 Requirement를 클릭한 다음, 유형이 짧은 텍스트인 Jira Key라는 속성을 추가합니다(클래스에 속성 추가하기).
  2. 스크립트에 읽기 전용 토큰 대신 읽기 및 쓰기 토큰을 만듭니다.
  3. 스크립트의 마지막 반복문 끝, print(…) 줄 뒤에 다음을 추가합니다.
    holarch("PATCH", f"/projects/{PROJECT}/entities/{e['id']}", json={"attributes": {"Jira Key": key}})

변경은 앱에서의 편집처럼 기록됩니다. 내 이름으로 기록되고 프로젝트를 열고 있는 모든 사람이 봅니다. 이 속성을 설정해도 승인된 요구사항이 검토로 돌아가지 않습니다. 프로젝트가 형상 통제를 사용하면 승인된 요구사항은 직접 변경을 거부합니다(409 change-control). 키를 Jira에만 보관하거나 변경 요청을 통해 변경합니다.

Claude로 Jira 이슈를 Holarch 제안으로 바꾸기

Jira 이슈가 요구사항 변경을 요청할 때, 예를 들어 고객이 값을 더 엄격하게 해 달라고 요청할 때 사용합니다.

  1. 읽기 및 변경 제안 접근 권한으로 Holarch에 연결된 Claude를 엽니다.
  2. 예를 들어 이렇게 묻습니다. “Jira 이슈 EO-31을 읽어 줘. 이 이슈가 영향을 주는 CubeSat 프로젝트의 Holarch 요구사항을 찾고, 요청한 변경을 제안해 줘. 제안 요약에 EO-31을 언급해 줘.”

    Jira 커넥터가 없으면 대신 이슈의 요약과 설명을 메시지에 붙여 넣습니다.

  3. Claude는 list_projects, search_entities, get_entity로 프로젝트를 읽습니다. update_entity(새 요구사항은 create_entity와 relate)로 각 변경을 제안에 추가한 다음 propose_changes로 보냅니다.

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

  4. Holarch에서 ✦ AI ▾ → “<title>” 검토… 또는 종 아래의 알림을 엽니다.
  5. 각 변경을 확인합니다. 원하지 않는 것은 체크 해제한 다음 선택 항목 적용을 클릭합니다.

    변경이 적용되며, 실행 취소 한 번으로 모두 되돌립니다. 요구사항 텍스트가 바뀌면 다른 편집과 마찬가지로 추적 연결이 검토 대상으로 표시되고, 승인된 요구사항은 In Review로 돌아갑니다.

스크립트는 Claude 없이도 같은 제안을 만들 수 있습니다. 변경마다 POST /api/v1/projects/<project>/proposal/changes를 한 번씩 호출한 다음 title과 summary로 POST /api/v1/projects/<project>/proposal을 호출합니다.

curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"op": "update", "entity": "<requirement id>", "description": "The ADCS shall point the payload boresight within 0.08 degrees of the commanded target."}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal/changes
curl -X POST -H "Authorization: Bearer hol_…" -H "Content-Type: application/json" \
  -d '{"title": "EO-31: tighter pointing", "summary": "Customer request EO-31 tightens pointing accuracy to 0.08 degrees."}' \
  https://app.holarch.app/api/v1/projects/<project>/proposal

실습 예제: CubeSat EO-1 데모

  1. 프로젝트 관리 → 프로젝트 파일 ▾ → 새 데모 프로젝트로 데모를 만듭니다.
  2. 데모 프로젝트로 제한한 읽기 전용 토큰을 만들고, 테스트용 Jira 프로젝트를 대상으로 holarch_to_jira.py를 실행합니다.

    승인된 각 요구사항이 이슈를 받습니다. 예를 들어 텍스트 “The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.”와 요구사항 링크가 있는 2.1 Pointing Accuracy입니다.

  3. 스크립트를 다시 실행합니다.

    아무것도 출력하지 않습니다. 승인된 모든 요구사항에 이미 이슈가 있습니다.

  4. Jira에서 0.1도 대신 0.08도를 요청하는 이슈 EO-31을 만듭니다. 위와 같이 Claude에게 변경을 제안하도록 요청합니다.
  5. Holarch에서 제안을 검토합니다. 제안은 2.1 Pointing Accuracy의 텍스트를 바꾸며, 영향 목록에 이를 검증하는 TC-04 Pointing Accuracy Test가 표시됩니다.

팁

  • 동기화 스크립트에는 프로젝트로 제한한 자체 읽기 전용 토큰을 주고, Claude에게는 별도의 연결을 줍니다.
  • 토큰은 스크립트가 아니라 비밀 저장소나 환경에 보관합니다.
  • 스프린트의 바탕이 된 요구사항은 Jira에서 레이블 holarch로 검색합니다.
  • 요구사항 번호는 바뀔 수 있지만 holarch-<id> 레이블은 바뀌지 않습니다. 요약의 번호가 아니라 레이블로 대조합니다.

문제 해결

메시지 또는 증상원인과 해결
Holarch answered 401 token-invalid토큰이 잘못되었거나, 취소되었거나, 만료되었습니다. 계정 설정 → API 토큰에서 새 토큰을 만듭니다.
Holarch answered 403 plan-api계정의 요금제에 API와 MCP가 포함되지 않습니다. Individual 체험판을 시작하거나 요금제를 선택하면 토큰이 다시 작동합니다.
Holarch answered 403 org-policy프로젝트의 조직이 API 접근을 껐습니다. 조직 관리자에게 문의합니다.
Holarch answered 403 read-only-tokenJira Key 쓰기에는 읽기 및 쓰기 토큰이 필요합니다.
Holarch answered 400 unknown-attribute프로젝트에 Requirement용 Jira Key 속성이 없습니다. 설정 → 스키마에서 추가하거나 선택 단계를 생략합니다.
Holarch answered 409 change-control요구사항이 형상 통제 대상입니다. 변경 요청을 통해 변경하거나 키를 Jira에만 보관합니다.
Holarch answered 429 rate-limited분당 요청 600건 또는 변경 120건을 넘었습니다. Retry-After의 초만큼 기다린 다음 다시 실행합니다. 완료된 이슈는 건너뜁니다.
Jira가 400으로 응답Jira가 이슈 필드를 거부했습니다. 예를 들어 프로젝트에 없는 이슈 유형입니다. Task 대신 프로젝트의 이슈 유형 중 하나를 사용합니다.
Jira가 401 또는 403으로 응답JIRA_EMAIL, JIRA_API_TOKEN, 그리고 Jira 프로젝트에서 이슈를 만들 권한을 확인합니다.
Claude에 Holarch 쓰기 도구가 표시되지 않음연결이 읽기 전용입니다. 읽기 및 변경 제안으로 다시 연결한 다음 새 대화를 시작합니다.