AIエージェントに作業を任せると、ログには「何を実行したか」が残ります。けれど、運用で本当に詰まるのはそこだけではありません。なぜその tool を選んだのか、なぜ承認を求めたのか、なぜ retry せず rollback に寄せたのか、なぜ subagent に渡したのかが残っていないと、レビュー担当は会話履歴を掘り返すしかなくなります。
この記事では、AIエージェント運用における decision log を扱います。実行証跡として何を残すかは AIエージェント監査ログ設計ガイド、依頼を入口で分類する話は AIエージェント依頼受付設計ガイド、完了報告と実状態を突合する話は AIエージェント state reconciliation 設計ガイド、成果物の返却形式は AIエージェント出力契約設計ガイド に分けています。
今回の論点は、AIエージェントが分岐点で何を根拠に判断したかを、後から人間が読める粒度で残すことです。
先に結論: decision log は監査ログの理由欄ではない
decision log を監査ログの reason 欄で済ませると、すぐに使いにくくなります。
監査ログは「何が起きたか」を追うための証跡です。tool 名、引数の要約、実行時刻、承認者、結果、成果物、レビュー結果が中心になります。一方で decision log は「なぜその分岐を選んだか」を追うための記録です。
私なら、次のように分けます。
| 種類 | 主語 | 残すもの | 使う場面 |
|---|---|---|---|
| audit log | 実行 | tool call、承認、成果物、検証結果 | 事故調査、監査、証跡 |
| decision log | 判断 | 選択肢、採用理由、却下理由、根拠、責任者 | レビュー、再実行、引き継ぎ |
| output contract | 返却 | 成果物、検証、リスク、next action | 人間の次の判断 |
| state reconciliation | 突合 | planned / observed / persisted / reported / audit state | 完了前の状態確認 |
たとえば、監査ログには GitHub PR create succeeded が残ります。decision log には「なぜ issue comment ではなく PR を作ったのか」「なぜ draft PR にしたのか」「なぜこの branch 名にしたのか」を残します。
これは細かすぎるように見えます。ただ、AIエージェント運用では判断が高速に積み重なります。人間が後から1つずつ追うなら、実行ログだけでは足りません。
decision log が必要になる分岐点
すべての行動に理由を書く必要はありません。むしろ全部を残すと読めないログになります。
decision log が必要なのは、後から「別の選択肢もあり得た」とレビューされる分岐点です。
| 分岐点 | 例 | 理由を残さないと起きること |
|---|---|---|
| task routing | main agent、subagent、automation、人間へ戻す | 不向きな lane に載せた理由が分からない |
| tool selection | shell、MCP、GitHub API、browser のどれを使うか | 最小権限で済んだか判断できない |
| approval request | 自動実行、承認待ち、却下、代替案 | 承認疲れと過剰自動化の境界が消える |
| evidence selection | どの docs、ログ、既存コードを根拠にしたか | 古い情報や弱い根拠で進んだことに気づけない |
| retry / rollback | 再実行、手動確認、rollback、停止 | 外部副作用を二重実行する |
| scope change | 依頼範囲を狭める、広げる、保留する | 依頼外変更が正当化される |
| final next action | merge、review、re-run、block、ask user | 人間が誤った次アクションを取る |
OpenAI Agents SDK の docs では、agent は tools、handoffs、guardrails、sessions、structured outputs を組み合わせて動く前提になっています。つまり、実務上の agent run は単一の回答生成ではなく、複数の分岐を含むワークフローです。さらに MCP の Tools 仕様 では、tool はモデルが文脈に応じて呼び出せる外部システムへの操作口であり、信頼と安全のために人間が deny できる設計が推奨されています。
この前提では、「実行したかどうか」だけでなく「なぜ呼んでよいと判断したか」を残す価値があります。
最小の decision record
最初から大きなデータモデルを作る必要はありません。私なら、1つの重要判断につき次の9項目だけにします。
decision:
id: dec_20260705_001
run_id: agent_run_20260705_0900
point: tool_selection
question: "GSC data を取得するために外部 fetch を実行してよいか"
options:
- use_existing_snapshot
- run_fetch
- ask_user
selected: use_existing_snapshot
reason: "root worktree が dirty で、今回の目的は新規記事作成。最新GSC取得は必須ではなく、既存SEO planとorigin/mainの重複確認で判断可能"
evidence:
- "data/seo/keyword-plan.md"
- "docs/plans/2026-03-30-blog-seo-overhaul-plan.md"
- "open PR list"
rejected:
run_fetch: "network/API failure 時の調査が本筋から外れる"
ask_user: "blocking decision ではない"
next_action: continue_with_existing_plan重要なのは、selected だけでなく rejected を残すことです。採用理由だけでは、後から「なぜ別案を選ばなかったのか」が分かりません。
また、reason は長文の思考過程ではなく、レビュー可能な理由に絞ります。AIエージェントの chain-of-thought を保存する話ではありません。人間が業務判断として検証できる、短い rationale を残します。
decision log と chain-of-thought を混ぜない
ここは重要です。
decision log は、モデルの内部思考を丸ごと保存するものではありません。保存するのは、外部から検証できる判断理由です。
悪い例:
いろいろ考えた結果、Aの方がよさそうなのでAにした。これではレビューできません。
良い例:
selected: draft_pr
reason: "build は通ったが、MCP server catalog の owner 確認が未完了。直接 merge ではなく draft PR として review queue に戻す"
evidence:
- "pnpm run build: passed"
- "mcp-catalog.yml: owner missing for billing server"
next_action: owner_review_requiredこの形なら、判断の正しさを後から確認できます。根拠が弱ければ差し戻せますし、同じ条件の run で再利用できます。
NIST AI RMF は、AIリスク管理を設計、開発、利用、評価へ組み込むための枠組みとして位置づけられています。生成AI向け profile でも、組織の目標、リスク許容度、法規制、ベストプラクティスに合わせて管理する考え方が示されています。decision log は、その大きな governance を日々の agent run に落とすための小さな実装です。
どこに保存するか
保存先は、組織の成熟度で変わります。
最初は、次の順で十分です。
| 保存先 | 向いている用途 | 注意点 |
|---|---|---|
| PR body | code / docs 変更の判断 | 長くしすぎない |
| run artifact | automation、CI、batch run | 検索できる形式にする |
| audit log table | 承認、外部操作、MCP write | 実行ログと混ぜすぎない |
| issue comment | 人間判断が必要な保留 | 最終状態へリンクする |
| internal knowledge base | 後から設計判断として再利用 | 一次ログへの参照を残す |
小さいチームなら、PR body の Decision log セクションから始めるのが実用的です。
## Decision log
- `dec_001`: Used existing GSC snapshots instead of fetching fresh data.
- Reason: latest fetch is not required for duplicate check; root is dirty.
- Evidence: keyword-plan, SEO overhaul plan, origin/main article list.
- `dec_002`: Opened a PR instead of committing to main.
- Reason: root main is dirty and automation rule forbids direct main commit.ただし、外部操作や高リスク操作が増えるなら、PR body だけでは足りません。agent_run_id と decision_id を audit log、approval log、PR、MCP server log に渡せるようにします。
tool 選択の decision log
AIエージェント運用では、tool 選択が事故の入口になりやすいです。
同じ目的でも、選べる手段は複数あります。
| 目的 | 低リスク案 | 高リスク案 |
|---|---|---|
| GitHub PR 状態確認 | gh pr view / read API | review comment 投稿 |
| 設定確認 | ファイル read | 設定変更 |
| 外部仕様確認 | 公式 docs fetch | 古い blog 引用 |
| build 確認 | local build | deploy preview 更新 |
| データ確認 | read-only query | production write |
decision log では、tool 名だけでなく、なぜその risk tier を選んだかを残します。
decision:
point: tool_selection
question: "PR review 状態を確認する方法"
selected: gh_pr_view_readonly
reason: "必要なのは review state と thread の確認だけ。comment 投稿や dismiss は不要"
rejected:
post_comment: "現時点では人間向けの返信内容が確定していない"
browser_ui: "read API で十分"これは AIエージェント tool risk tier 設計ガイド と相性がよいです。risk tier が分類表なら、decision log はその分類を実際の run でどう使ったかを残します。
handoff の decision log
handoff は便利ですが、理由が残っていないと責任がぼけます。
Claude Code の subagents は、独立した context window、専用 system prompt、tool access、permission を持つ専門 agent として動きます。OpenAI Agents SDK でも、handoff と manager-style orchestration は設計上の選択肢として分けられています。
つまり handoff は、「手が空いている agent に投げる」機能ではありません。判断の責任をどこに置くかの設計です。
decision log では、次を残します。
decision:
point: handoff
question: "MCP authorization docs の確認を subagent に渡すか"
selected: research_subagent
reason: "本文執筆 context を汚さず、一次情報の URL と要点だけを戻せば十分"
constraints:
- read_only
- official_docs_only
- return_links_and_relevant_sections
rejected:
main_agent_reads_all: "記事本文の構成 context が膨らみすぎる"
implementation_agent: "編集権限は不要"handoff の判断理由を残すと、後から「なぜその agent がその情報を見たのか」「なぜ権限を絞ったのか」を説明できます。
approval の decision log
承認フローでは、承認者名だけを残しても不十分です。
たとえば、MCP tool が production ticket を更新する場合、監査ログには approved_by と tool call が残るかもしれません。しかし decision log には、少なくとも次を残すべきです。
decision:
point: approval
question: "production ticket に status update を投稿してよいか"
selected: ask_human
reason: "external action であり、投稿内容が顧客可視になる可能性がある"
approval_prompt:
action: "Post status update to incident ticket"
visible_to: "customer_success"
rollback: "delete_comment_possible_but_audit_trail_remains"
rejected:
auto_approve: "external visibility がある"
block: "投稿自体は incident runbook 上必要"MCP の Tools 仕様は、tool invocation に対して人間が deny できる UI や確認プロンプトを推奨しています。ここで decision log を足すと、承認プロンプトが単なる yes/no ではなく、後から説明できる判断になります。
retry と rollback の decision log
retry と rollback は、判断理由を残さないと危険です。
失敗したから retry する、危ないから rollback する、という単純な分岐では足りません。外部副作用がある作業では、retry が二重実行になり、rollback が追加事故になることがあります。
decision:
point: retry_or_rollback
question: "PR comment 投稿が timeout した後に再実行するか"
selected: reconcile_before_retry
reason: "HTTP timeout だが、GitHub 側で comment が作成済みの可能性がある"
evidence_needed:
- issue comments list
- client request id
next_action: state_reconciliation
rejected:
immediate_retry: "同一コメントの二重投稿リスク"
rollback: "投稿済みか未確認"これは retry 設計や state reconciliation と重なりそうに見えますが、責務は違います。retry 設計は再実行可能性を作る。state reconciliation は状態を突合する。decision log は、なぜその分岐に進んだかを残します。
実務で使う decision policy
毎回自由に理由を書くと、ログがばらつきます。最低限、decision policy を置きます。
decision_policy:
version: agent-decision-policy-2026-07-05
require_decision_log_when:
- risk_tier in ["write", "external_action", "forbidden_candidate"]
- handoff_to_agent is not null
- approval_required is true
- retry_after_partial_failure is true
- rollback_or_compensation is considered
- source_of_truth_changes
decision_fields:
- question
- options
- selected
- reason
- evidence
- rejected
- next_action
max_reason_length: 400policy as code を使っているなら、decision log に policy_version と rule_id を入れます。
decision:
id: dec_20260705_004
policy_version: agent-policy-2026-06-25
rule_id: external-action-needs-approval
selected: ask_humanこれで、承認フロー、監査ログ、eval、runtime monitoring と同じ基準で見られます。
よくある失敗
1. すべてを decision log にする
全部の tool call に理由を書くと、誰も読みません。
decision log は分岐点だけにします。read-only のファイル確認、明らかな build 実行、記事生成後の pnpm run build のような定型操作は、audit log や verification に残せば十分です。
2. 根拠ではなく感想を書く
安全そうだから、一般的だから、たぶん大丈夫 は根拠ではありません。
根拠は、公式 docs、設定ファイル、既存コード、ログ、PR diff、監査ログ、policy rule のように、後から確認できるものへ寄せます。
3. 却下理由を残さない
採用案だけ残すと、再レビューで同じ議論が戻ってきます。
特に auto_approve を選ばなかった理由、retry を選ばなかった理由、main agent で処理しなかった理由は、次回の自動化改善に効きます。
4. decision log を成果物に埋め込みすぎる
PR body に長い decision log を貼りすぎると、レビューしにくくなります。
PR body には重要判断だけを要約し、詳細は run artifact や内部ログへリンクします。出力契約の evidence と risks に、decision log の要約だけを返す方が読みやすいです。
5. 人間の責任を消す
decision log は、AIエージェントに責任を押しつけるためのものではありません。
むしろ逆です。どの判断を agent に任せ、どの判断を人間に戻し、どの policy に従ったかを明確にするために置きます。
導入順序
最初から全システムに入れる必要はありません。
私なら、次の順で入れます。
- PR body に
Decision logを3行だけ入れる writeとexternal actionのときだけ必須にするdecision_idを audit log と approval log に入れる- retry / rollback / handoff へ対象を広げる
- policy version と rule id を入れる
- eval で「理由が弱い decision」を落とす
この順番なら、運用負荷を上げすぎずに始められます。
まとめ
AIエージェント運用では、ログを残すだけでは足りません。実行ログは「何が起きたか」を教えてくれますが、「なぜその判断をしたか」は別に設計しないと残りません。
decision log は、監査ログ、出力契約、state reconciliation、policy as code の間に置く薄い台帳です。tool、handoff、承認、retry、rollback、scope change のような分岐点だけに絞り、選択肢、採用理由、却下理由、根拠、next action を残します。
AIエージェントの判断をブラックボックスにしないために、まずは PR body の小さな Decision log から始めるのが現実的です。そこから audit log と approval log に decision_id を渡せるようにすると、後から説明できる運用に近づきます。