inbox 自動消化 workflow の運用手順 (ADR-0197)
tasks/prompts/handover_*.md に届いた依頼を、main への merge event を trigger に自動で消化する仕組みの運用手順。
決定: ADR-0197 (docs/adr/0197-auto-consume-inter-clone-inbox-on-merge.md)。起案規約 (frontmatter 必須 field / type 判定 / mechanical allow-list): .claude/rules/handover.md。
いま何がある (2026-07-03 時点 · Phase 2b shipping 済)
| 成果物 | ファイル | 状態 |
|---|---|---|
| lint script | scripts/handover-frontmatter-lint.mjs | 稼働中 (Phase 1 shipping · PR #4213) |
| lint workflow | .github/workflows/handover-lint.yml | 稼働中 |
| 消化 script | scripts/inbox_consume.sh | 稼働中 (Phase 2b shipping · guard 3 種 + Claude CLI 発火 · default dry-run) |
| reusable 消化 workflow | .github/workflows/reusable-inbox-consume.yml | 稼働中 (Phase 2b shipping) |
| 消化 workflow (5 clone) | .github/workflows/inbox-consume-{main,doc,drp,mas,ocr}.yml | 5 本稼働中 (Phase 2b shipping · reusable 呼び出し · feature flag off default) |
| 月次レポート dir | docs/_internal/06_ops/inbox_consume_report/ | 稼働中 (Phase 3 shipping) |
| cost 集計 script + workflow | scripts/inbox-consume-metrics.mjs + .github/workflows/inbox-cost-report.yml | 稼働中 (Phase 4 shipping) |
type 分類の概要
詳細は .claude/rules/handover.md。この節は運用者向けの要約。
type | 消化経路 | 例 |
|---|---|---|
handover (既存互換) | 受信クローンの人間が session で読む | 全ての session close handover · 通常の申し送り |
order-mechanical | workflow が Claude Code CLI headless で自動消化 | archive 退避 · workflow 1 step 追加 · lint 追加 · frontmatter fix |
order-needs-approval | workflow が Issue 起票のみ · 人間判断待ち | Pipeline 発火 · 撤退判断 · ADR flip · 新規 script 実装 |
type を書き忘れた handover は lint が PR で block する。lint が誤って通した場合でも消化 script 側で order-needs-approval 相当扱いにする二重防御。
発火経路
各クローン向け workflow (inbox-consume-<role>.yml) は次で発火する。
- trigger:
push: branches: [main]+paths: [tasks/prompts/handover_*_to_<role>.md] - concurrency:
group: inbox-consume-<role>·cancel-in-progress: false - permissions:
contents: read·pull-requests: read(Phase 2b で write 追加予定)
手順:
- 起票者が
handover_YYYY-MM-DD_topic_to_<role>.mdを書き、frontmatter に必須 6 field + 適切なtypeを記入 handover-lintが PR で緑になったら merge- main への merge で
inbox-consume-<role>workflow が起動 - 変更のあった handover を 1 本ずつ
scripts/inbox_consume.shに渡して消化 - 消化完了で
tasks/prompts/archive/へgit mv(ADR-0134)
feature flag / dry-run 切替
Phase 2b shipping 時点でも消化 workflow は完全 no-op default。有効化は明示的に repo variable + secret を set する。
| variable / secret | 意味 | default | 有効化 |
|---|---|---|---|
INBOX_CONSUME_ENABLED (variable) | workflow を実行するか | false (no-op) | gh variable set INBOX_CONSUME_ENABLED --body true |
INBOX_CONSUME_DRY_RUN (variable) | 実行するが Claude Code CLI を発火しない | true (dry-run) | gh variable set INBOX_CONSUME_DRY_RUN --body false |
CLAUDE_API_KEY (secret) | Claude Code CLI 用 API key (CLAUDE_CODE_ANTHROPIC_API_KEY として export) | 未設定 | gh secret set CLAUDE_API_KEY --body '<key>' (dry-run false 時のみ必須) |
撤退の 30 秒手順: INBOX_CONSUME_ENABLED を false に戻すだけで完全停止。secret 失効は Anthropic Console で。
guard 3 種 (§3.2 盲点 1/3/6 対応)
dry-run false = 本番実行時に発火する 3 つの guard。
| guard | 検出内容 | 動作 |
|---|---|---|
| allow-list guard | Claude Code CLI 生成 diff の変更 file path が allow-list 外 | PR を draft 化 · 人手 review 要 |
| secret scan (gitleaks) | 生成 diff に secret / API key / credential 検出 | PR を draft 化 · 人手 review 要 |
| revert commit guard | trigger commit が Revert ... message | workflow skip (再消化回避) |
allow-list (2026-07-03 時点)
以下の path pattern のみ mechanical で許可。他は draft PR で人手 review 要。
.github/workflows/*.yml·.yaml(workflow 追加 · 既存に 1 step 追加)scripts/*.{sh,mjs,js,py,ts}·scripts/lib/*.{sh,mjs,js,ts}(script 追加 · lib 修正)tasks/prompts/archive/handover_*.md(archive 退避)tasks/prompts/handover_*.md(通知 handover 起票).claude/rules/*.md(path-scoped rule 追加 · lint 追記)docs/_internal/**/*.md(docs 追記)docs/adr/adr-index.json·docs/adr/INDEX.md(adr-index 再生成)docs/_config.json(nav 登録)
allow-list の拡張: 新規 pattern の追加は ADR 改訂を必須とし、追加 PR は必ず order-needs-approval 扱い (盲点 7 対応)。allow-list 更新の PR 自身は自動消化不可 (self-approval 禁止)。
trouble-shooting
workflow が発火したのに handover が消化されない
- 確認 1:
INBOX_CONSUME_ENABLED == 'true'が set されているか (gh variable list) - 確認 2: handover の
typeがorder-mechanicalか (handover/order-needs-approvalは自動消化しない) - 確認 3: handover の
target_sessionが workflow の<role>と一致するか - 確認 4: revert commit / archive 退避後の delete で
pathsfilter に該当したケース (workflow log のSKIPログを見る)
Claude Code CLI 呼び出しで fail
Phase 2b で有効化。job の 10 分 timeout 超過 · Claude CLI 未 install · secret 未設定で fail する設計。
- timeout: workflow が自動で
inbox-consume-failurelabel 付きの Issue を起票 · 人間 fallback で消化 (.claude/rules/handover.md準拠で手動対応) - secret 未設定:
CLAUDE_API_KEYを追加するか、INBOX_CONSUME_DRY_RUN=trueに戻して dry-run 縮退 - cost 超過: allow-list を絞り込むか mechanical 分類を見直す (§8-2 撤退条件)
guard 逸脱で PR が draft 化された
- allow-list 逸脱:
scripts/inbox_consume.shのallow_list_regexと実際の変更 file を照合。allow-list 拡張が妥当なら ADR 改訂で追加 · 妥当でなければ手動 revert - secret 検出: gitleaks log (
/tmp/gitleaks.log) で detect した line を確認 · 誤検出なら.gitleaks.tomlで allowlist · 実 secret なら key rotation + 削除 commit
handover-lint が緑にならない
scripts/handover-frontmatter-lint.mjs の findings を見る。主要 rule:
no-frontmatter:---\n...\n---が無いmissing-<field>: 必須 6 field のいずれかが欠落empty-<field>: 値が空 or 空白のみinvalid-type:typeの値が allow-list 3 種 (handover/order-mechanical/order-needs-approval) の外
ローカル実行: node scripts/handover-frontmatter-lint.mjs tasks/prompts/handover_YYYY-MM-DD_...md
GitHub Actions 60 日 disable 挙動 (ADR-0197 §盲点 9)
GitHub は 60 日間 push が無い repo の schedule / push trigger の workflow を自動 disable する。本 workflow は次で対処する。
- push trigger: bizlp-gas-accounting は日次で複数 PR が merge されるため 60 日連続 push なしは想定外。cron 系より安全。
- stale 検知:
docs/_internal/06_ops/inbox_consume_report/YYYY-MM.mdの月次レポートでrun_count = 0が 3 ヶ月継続したら disable を疑う (ADR-0197 §8 撤退条件 4 の前段) - 再起動:
gh workflow enable inbox-consume-main.yml
関連
- ADR-0197 — 決定本体
- ADR-0159 — 5 クローン並行運用の役割境界
- ADR-0134 — 消費者退避 ·
tasks/prompts/archive/運用 - ADR-0141 — SoD 補償統制 (auto-merge の監査追跡性根拠)
.claude/rules/handover.md— 起案規約 SSoTdocs/_internal/06_ops/inbox_consume_report/README.md— 月次レポート SSoTscripts/hooks/session_start_prompts.sh— session 開始時の inbox 通知 hook (代替経路 · 既存)