anthropics/oncall-kit 不是重新打造一套 Agent runtime，而是示範：如果底層已經有 Claude Code / Claude 的工具能力，要怎麼把 SOP、工具綁定、團隊規則、跨 Session 經驗與 Evaluation 組成一套可實際運作的 on-call Agent。

官方也明確標示這是 reference implementation，不維護、不收 PR；比較適合當設計樣板，而不是直接視為長期維護的 production framework。

1. 先看整體架構

oncall-kit 可以先簡化成：

                    Claude Code / Claude
                      Agent Runtime
                            │
          ┌─────────────────┼─────────────────┐
          │                 │                 │
       Hooks            CLAUDE.md           Skills
     何時觸發？          長期規則             SOP / HOW
          │                                   │
          └─────────────────┬─────────────────┘
                            │
                      On-call workflow
                            │
          ┌─────────────────┼──────────────────┐
          │                 │                  │
      STACK.md          ONCALL.md          lessons.md
      Tool binding      Team policy        Experience
                            │
                         eval/
                      Replay / Shadow

幾個核心檔案的分工：

其中一個很值得注意的設計是 Skill 與工具 vendor 分離。

Skill 可以只要求：

查 metrics
查 logs
查 code

真正的綁定則放在：

STACK.md

metrics → Grafana
logs    → Datadog
code    → GitHub
pager   → PagerDuty

所以換工具時，不一定需要重寫整套 SOP。

2. First Run：first-run.sh 其實只做一件小事

第一次看 repo 很容易從 first-run.sh 開始，但它其實只是整個架構中的一個入口。

hooks/hooks.json 只在 SessionStart 的 startup 時機執行：

hooks/first-run.sh

而 first-run.sh 的核心邏輯也很簡單：

新 Session
    ↓
檢查 STACK.md 是否存在
    ↓
不存在
    ↓
告訴 Claude：
這是尚未完成設定的 oncall-kit
請依 CLAUDE.md 介紹 setup
並詢問是否開始 Phase 0

它自己 不會執行 setup，也不會連接 Grafana、PagerDuty 或開始掃 Incident。原始 script 甚至直接寫著：

Read-only; never runs setup.

因此比較準確的角色分工是：

first-run.sh
→ WHEN：什麼時候提醒 Claude

CLAUDE.md
→ RULES：Claude 長期要遵守什麼

skills/oncall-setup/SKILL.md
→ HOW：真正的 setup 怎麼做

3. Setup 是五個有 Gate 的 Phase

oncall-setup Skill 把 setup 拆成五段：

Phase 0  Discover
   ↓
產生 STACK.md

Phase 1  Mine
   ↓
從歷史 Incident 草擬 Playbook / lessons

Phase 2  Interview
   ↓
補齊無法從歷史資料推得的 policy

Phase 3  Validate
   ↓
用 holdout Incident 做 Replay

Phase 4  Install
   ↓
安裝 Slack routines

每個 Phase 結束都要求 STOP 並等待 human sign-off，而且 Skill 明確要求「一個 turn 不得連跑兩個 Phase」。

這裡要注意一個技術差異：

oncall-kit 的 Phase Gate 主要是 Markdown instruction + Human approval，不是 repo 自己另外實作一個 workflow engine 或 runtime lock。

repo 內建的 hooks.json 目前只看到 SessionStart → first-run.sh；Phase Gate 則寫在 CLAUDE.md 與 SKILL.md 中。

所以這是一種很值得參考的 Human-in-the-loop 設計，但如果業務場景要求「模型絕對不能繞過」，仍應考慮把關鍵限制下沉到程式、權限層或 Tool Gateway。

4. Memory：不是只靠 Conversation History

oncall-kit 很有意思的一點，是它把重要資訊直接外化成 Repo 檔案。

STACK.md
→ 現在有哪些 capability / tool binding

ONCALL.md
→ 團隊確認過的 operational policy

lessons.md
→ 過去 Incident 累積的經驗

paging-log.md
→ paging 決策紀錄

eval/replay-results.md
eval/shadow-log.md
→ 評估紀錄

CLAUDE.md 甚至明確規定：

Files are truth; memory is cache.

也就是新的 Session 不需要完全依賴過去聊天紀錄，只要重新讀 Repo，就可以恢復必要狀態。

這種做法對企業 Agent 很實用，因為 可檢查、可版控、可審查，也比較不會把重要規則藏在不可見的模型 memory 裡。

5. lessons.md：先記經驗，不直接改 SOP

Incident 結束後，oncall-kit 不會因為一次經驗就直接修改正式 Playbook。

它先寫進：

lessons.md

每筆 lesson 會記錄：

What happened
Root cause
Fix
Gotcha / reusable rule
failure-class tag

如果同一類機制反覆出現，或某個經驗已經成熟到可以變成 checklist，才會：

lessons.md
    ↓
累積相同 pattern
    ↓
提出 Playbook amendment
    ↓
PR
    ↓
Human review

官方 template 甚至提供一個簡單的 graduation rule：同一 tag 累積約三筆、且機制一致時，可考慮升級到對應的 reference / playbook。

因此 lessons.md 比較像：

Agent 的可審查 learning buffer，而不是 Agent 可以自行修改正式 SOP 的權限。

這點很適合拿來思考企業 Agent 的 Auto Learn：可以讓 Agent 學，但不等於讓 Agent 自己改 policy。

6. Replay：改完 Playbook 後，要證明真的有變好

oncall-kit 不只保存 lesson，也提供 eval/replay.md。

核心方法很接近離線回放：

選擇未參與 Playbook 建立的歷史 Incident
        ↓
只給當時一開始可取得的資訊
        ↓
讓 Agent 重新做 diagnosis
        ↓
在 fresh context 中 grading
        ↓
和實際 Incident 結果比較

官方特別要求 grading 不能在產生答案的同一個 context 裡完成，因為原本的 Agent 已經相信自己的 diagnosis；因此 grading 要換新的 Session / context，再由 Human 確認。

Grade 分成：

而 Replay 最重要的不是「得到一個分數」，而是：

Replay 發現錯誤
      ↓
定位是哪個 Playbook / Rule 造成
      ↓
提出具體 diff
      ↓
Human review
      ↓
重新 Replay

也就是把 Evaluation 接回 SOP 改進流程。

7. 我認為最值得帶走的四個設計

oncall-kit 雖然只是 reference implementation，但有四個觀念很適合企業 Agent：

1. Skill 與 Tool binding 分離
   SOP 描述「需要什麼能力」，STACK.md 再決定實際工具。

2. 重要狀態外化成檔案
   Policy、Tool mapping、Lesson、Evaluation 都不是只存在 conversation memory。

3. Learning 與正式 SOP 分離
   Agent 可以累積 lesson，但正式規則仍經過 PR / Human review。

4. Evaluation 要回到 Playbook
   Agent 答錯不是只記一筆分數，而是追問「哪一條 SOP 應該改」。

這也是 oncall-kit 比單純 Prompt + Tool Calling 更值得研究的地方：它示範的不是「怎麼做一個很聰明的 Agent」，而是 怎麼把 Agent 放進一個可以被人控制、修正與驗證的工作系統裡。

References

以下以 Anthropic 官方 anthropics/oncall-kit repository 為主：

1. oncall-kit README — Repo 定位、整體架構、五階段 setup、Shadow / Replay
   https://github.com/anthropics/oncall-kit

2. CLAUDE.md — First Run、standing rules、files-as-truth、Human Gate、lesson / policy 規則
   https://github.com/anthropics/oncall-kit/blob/main/CLAUDE.md

3. hooks/hooks.json — SessionStart → first-run.sh
   https://github.com/anthropics/oncall-kit/blob/main/hooks/hooks.json

4. hooks/first-run.sh — Fresh install 判斷與 First Run context
   https://github.com/anthropics/oncall-kit/blob/main/hooks/first-run.sh

5. skills/oncall-setup/SKILL.md — Phase 0–4、Gate、Discover / Mine / Interview / Validate / Install
   https://github.com/anthropics/oncall-kit/blob/main/skills/oncall-setup/SKILL.md

6. templates/ONCALL.md — Paging、Severity、Routing 等 team policy template
   https://github.com/anthropics/oncall-kit/blob/main/templates/ONCALL.md

7. templates/lessons.md — Incident learning、Gotcha、Graduation rule
   https://github.com/anthropics/oncall-kit/blob/main/templates/lessons.md

8. eval/replay.md — Holdout、Blind input、Fresh-context grading、Replay / Shadow 評估方式
   https://github.com/anthropics/oncall-kit/blob/main/eval/replay.md

9. test-fixtures/RUNBOOK.md — 無真實 infrastructure 的 end-to-end dry run / regression test
   https://github.com/anthropics/oncall-kit/blob/main/test-fixtures/RUNBOOK.md