Holarch

リファレンス

レシピ:Jira

REST API で Holarch の要求を Jira の課題に接続し、Claude を通じて Jira の課題をレビュー済みの Holarch の変更に変換します。設定、同期スクリプト、具体例、トラブルシューティングを説明します。

使い方 →

このページの内容
  1. 概要
  2. 前提条件
  3. 使い方
    1. 使う場面と理由
    2. 同期を設定する
    3. 承認済みの要求から Jira の課題を作成する
    4. Jira のキーを Holarch に保持する(任意)
    5. Claude で Jira の課題を Holarch の提案にする
    6. 実例:CubeSat EO-1 のデモ
    7. ヒント
  4. トラブルシューティング
  5. 関連ページ

概要

このレシピは、Jira でのエンジニアリング作業を Holarch の要求に結び付けておきます。2 つの部分があります:

  • Holarch から Jira へ(REST API):スクリプトが、承認済みの要求ごとに 1 つの 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 で計画されることがよくあります。両者をリンクすると、2 つの質問に答えられます:「この要求を実装する 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 の課題があるものをスキップし、残りの要求のうちStatusが 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 を実行します。

    新しい課題ごとに 1 行が表示されます。たとえば 2.1 Pointing Accuracy -> EO-12 です。

仕組み:

  • GET /api/v1/projects/<project>/entities?class=Requirement が、要求を 500 件ずつ一覧表示します。
  • GET /api/v1/projects/<project>/entities/<id> が、各要求の属性(ここではStatus)と、Holarch でそれを開くリンクである url を返します。
  • 各課題には Jira のラベル holarch と holarch-<id> が付きます。次の実行では Jira の検索でそれらを見つけ、その要求をスキップします。
  • 要求は読み取られるだけです。スクリプトは Holarch で何も変更しません。

Jira のキーを Holarch に保持する(任意)

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 ▾ → Review “<title>”…、またはベルの下の通知を開きます。
  5. 各変更を確認します。不要なもののチェックを外してから、選択した項目を適用をクリックします。

    変更が適用されます。1 回の元に戻すですべて取り消せます。通常の編集と同様に、要求のテキストが変更されるとそのトレースリンクにレビューの印が付き、承認済みの要求は In Review に戻ります。

スクリプトは Claude なしで同じ提案を作成できます:変更ごとに 1 回 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 を実行します。

    承認済みの各要求に課題が作成されます。たとえば 2.1 Pointing Accuracy で、テキストは「The ADCS shall point the payload boresight within 0.1 degrees of the commanded target.」、要求へのリンク付きです。

  3. スクリプトをもう一度実行します。

    何も出力されません:承認済みのすべての要求にすでに課題があります。

  4. Jira で、0.1 度ではなく 0.08 度を求める課題 EO-31 を作成します。上記のとおり、Claude に変更を提案するよう依頼します。
  5. Holarch で提案をレビューします。提案は 2.1 Pointing Accuracy のテキストを変更し、その影響の一覧には、それを検証する TC-04 Pointing Accuracy Test が表示されます。

ヒント

  • 同期スクリプトには、プロジェクトに限定した専用の読み取り専用トークンを与えます。Claude には別の接続を与えます。
  • トークンはシークレットストアまたは環境に保持し、スクリプトには決して入れません。
  • ラベル holarch で、スプリントの背後にある要求を Jira で検索します。
  • 要求の番号は変わることがありますが、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-limited1 分間に 600 リクエストまたは 120 変更を超えています。Retry-After の秒数だけ待ってから、もう一度実行します。完了した課題はスキップされます。
Jira が 400 を返すJira が課題のフィールドを拒否しました。たとえば、プロジェクトにない課題タイプです。Task の代わりに、プロジェクトの課題タイプのいずれかを使います。
Jira が 401 または 403 を返すJIRA_EMAIL、JIRA_API_TOKEN、および Jira プロジェクトで課題を作成する権限を確認します。
Claude に Holarch の書き込みツールが表示されない接続が読み取り専用です。読み取りと変更の提案でもう一度接続してから、新しい会話を始めます。