最終更新: 2026/07/11 23:55

pipeline-adr-autofix runbook — Anthropic API 障害 / レート制限時のオンコール手順 (ADR-0232 §11.3)

対象: scripts/pipeline-adr-autofix.mjs の Phase 4 (§10.1 日本語ラベル bullet の Haiku 分類 post-process) が Anthropic API 障害・レート制限で失敗した際の対処手順。 前提: ADR-0232 shipping 後 (2026-07-11) の Pipeline 生成 ADR PR (head = adr/*) が対象。手動起票 ADR PR (drp / main clone 起票) は対象外 (§10.1 を英語 prefix で書けば Phase 4 起動しない)。

1. 症状と exit code

.github/workflows/pipeline-pr-autofix.yml の autofix step が非ゼロ exit で fail する。log と PR コメントの内容で症状を切り分ける:

exit code症状log 特徴対処
6ANTHROPIC_API_KEY secret 未設定 (日本語ラベル bullet 検出時のみ発火)❌ ADR-NNNN: §10.1 に日本語ラベル bullet N 件検出 … ANTHROPIC_API_KEY が未設定§2 secret 復元
7Haiku 呼び出しが fail (API 障害 / レート制限 / タイムアウト / domain 外分類)❌ ADR-NNNN: ... の Haiku 分類 fail: <詳細>§3 分類 fail
8LLM 分類反映後の --check-edges --enforce が fail (LLM 誤分類の疑い)❌ Phase 4 (LLM 分類反映) 後の --check-edges --enforce が fail§4 誤分類 detect

2. exit code 6 (ANTHROPIC_API_KEY 未設定)

Secret が repo settings から欠落した / 権限が変わったケース。

  1. gh secret list --repo BizLinkPartners/bizlp-gas-accounting | grep ANTHROPIC_API_KEY で存在確認
  2. なければ代表取締役 ([email protected]) から key を取得し gh secret set ANTHROPIC_API_KEY --repo BizLinkPartners/bizlp-gas-accounting --body '<key>' で復元
  3. PR で workflow を再走 (Actions タブから re-run · 空 push は不要 · autofix step のみ再実行される)

回避策: 期限が迫っていれば - **<English Prefix>: ADR-NNNN** (Amends / Refines / Depends On / Relates To / Supersedes / Conflicts With / Follows Up On の 7 種) 形式で §10.1 を手動 backfill してから push。Phase 4 は日本語ラベル未検出で skip する。

3. exit code 7 (Haiku 呼び出し fail)

log の ❌ ADR-NNNN: ... 行を確認して原因を分岐:

  • Anthropic API 429 rate limit: 15-30 分待って再走 (Actions タブから re-run)
  • Anthropic API 500 / 503: Anthropic status を確認 · 復旧待ち後に再走
  • AbortError (タイムアウト 15 秒超過): 単発なら再走 · 継続的なら network 経路 / rate limit を疑う
  • domain 外分類: <invalid_type>: Haiku 出力揺らぎ · 再走で解消しない場合は §5 手動 backfill

回避策: §2 と同様。急ぎなら手動 backfill で PR merge を優先し、次 PR で secret / API 状態を復旧。

4. exit code 8 (LLM 分類反映後の enforce fail)

Haiku 分類が反映されたが typed-edges-consistency 側で不整合が残っている。実際に起きる pattern:

  • 相手側 ADR が実在しない (edge-dangling): LLM が誤って ADR-NNNN の桁を間違えた・存在しない未来 ADR を分類対象と誤認
  • 逆辺追記漏れ (edge-inverse-missing): 相手側 ADR file の書き換えが git conflict / permission で失敗
  • status mismatch (edge-status-mismatch): supersedes 分類が SKIP される §3.2 経路にも関わらず status 側が既に superseded に書き換わっていた

対処:

  1. PR の diff を確認 (gh pr diff <PR#> or GitHub UI) して LLM 分類結果 (log の 🤖 <file>: <keyword>:<target> → <edge_type> 行) を検証
  2. 誤分類なら PR branch に手動で英語 prefix bullet + frontmatter + 相手側逆辺を修正 push
  3. node scripts/adr-lint.mjs --check-edges --enforce を local で pass することを確認して push

5. 手動 backfill 手順 (§2/§3/§4 の共通回避策)

Phase 4 を skip する形で PR を merge するには、§10.1 の日本語ラベル bullet を手動で英語 prefix 化する:

  1. §10.1 の bullet を - **<English Prefix>: ADR-NNNN** (説明) 形式へ書き換え (7 種の英語 prefix は adr-draft.template.md §10.1 参照)
  2. frontmatter typed_edges (amends / refines / depends_on / relates_to / supersedes / conflicts_with / follows_up_on) に対応 ADR-NNNN を追記
  3. 相手側 ADR の逆辺 (superseded_by / amended_by / refined_by / relates_to / conflicts_with / followed_up_by · relates_to と conflicts_with は symmetric) を同 PR で追記
  4. node scripts/adr-lint.mjs --check-edges --enforce を local で pass 確認
  5. push → Phase 4 は日本語ラベル未検出で自動 skip → autofix step は成功

6. Confirmation KPI との関係 (ADR-0232 §9)

本 runbook で対処した事象は KPI 実測へ反映される:

  • KPI-1 (人手 backfill 発生数 = 0 件): §5 手動 backfill を実施した PR は gh pr list --search "typed edges backfill" で count される想定
  • KPI-2 (LLM 誤分類率 < 5%): exit 8 の発生件数は typed-edges-consistency CI FAILURE として集計される
  • KPI-3 (月次 LLM コスト < $1): exit 7 の 429 頻発は quota 超過を示す · LiteLLM ダッシュボードで実測

KPI 違反時の対応は ADR-0232 §8 撤退条件と §11.2 KPI 計測 scheduled workflow (Phase B PR で新設予定) を参照。

7. 関連 SSoT

  • ADR-0232 (docs/adr/0232-auto-translate-japanese-labels-in-pipeline-adr-autofix-llm.md): 決定本体
  • scripts/pipeline-adr-autofix.mjs: Phase 4 実装
  • scripts/lib/adr_ja_label_autofix.mjs: 語彙 SSoT + 分類 prompt + rewrite ロジック
  • .github/workflows/pipeline-pr-autofix.yml: workflow 定義 (ANTHROPIC_API_KEY env 参照)
  • .claude/rules/adr-draft.md §10.1 表記規則: 英語 prefix 推奨と日本語ラベル自動英語化の宣言
  • memory [[pipeline-generated-adr-pr-postprocess-checklist]]: 受理前後の checklist (本 amend shipping で「日本語ラベル手動 backfill 不要」に更新済)