在先前的文章中，我說明了我們為何要衡量工程時間的投入分布，以及小型的 LLM agent 如何協助將這項衡量整合到團隊的 Sprint 回顧會議中。幾個月後，我們已在各團隊中推行這個 agent，它也成功引發了以往未曾出現的討論。

本文將聚焦於該 agent 的運作方式、資料接收方式，以及提示的演進過程。底層的數據平台，包含 DORA metrics(DORA 指標)的推導方式，將另闢專文說明。

概覽

該 agent 會從我們的生產力指標數據平台擷取指標與活動資料，並產生一份會前閱讀用的回顧報告，以總結本次 Sprint 並提出可能的討論要點。

與其用所有原始資料塞滿模型，不如讓 agent 僅取得橫跨三個 Sprint 的指標摘要，並搭配可用於查詢特定 ticket、merge request 與失敗發布詳細資訊的工具。

代理設計

初始提示

初始提示彙整了橫跨三個 Sprint 的指標，並將每個 Sprint 標記為 [BASELINE] 或 [LATEST - FOCUS SPRINT]。這些指標涵蓋 Jira 交付指標與 DORA metrics：

所有指標皆由數據平台以確定性程式碼計算產生，我們不會要求模型嘗試從原始資料自行計算。提示中對此有明確說明："the metrics summary is authoritative, do not attempt to recalculate or second-guess it"。

摘要中還包含離群的 ticket 與 merge request 清單（例如週期時間或前置時間高於第 75 百分位數者），以及焦點 Sprint 中所有失敗發布的清單。Agent 被指示以這些清單作為分析的起點。Ticket 以 KEY (16.8d, 3.0SP) 的形式內嵌呈現，MR 則為 project!iid (308.7h: coding 116.3h, review 170.0h, deploy 22.4h)。

查詢工具

在 PydanticAI agent 上註冊了三個工具，讓 agent 能查詢詳細資訊：

@agent.tool
def lookup_jira_ticket(ctx: RunContext[AgentDeps], ticket_key: str) -> str:
    """Look up a Jira ticket by its key (e.g. PROJ-1363).

    Returns summary, status, assignee, story points, sprint, dates, cycle time,
    and full status transition history.
    """

@agent.tool
def lookup_merge_request(ctx: RunContext[AgentDeps], query: str) -> str:
    """Search merge requests by title substring, Jira key, or MR reference (e.g. !1049).

    Returns up to 10 matching MRs with title, author, dates, lead time, and release info.
    """

@agent.tool
def lookup_failure(ctx: RunContext[AgentDeps], query: str) -> str:
    """Search detected failed releases by tag, project name, evidence, or alert tiny id.

    Returns up to 10 matching failures with signal (alert/revert), evidence,
    resolution time, and correlated alert detail where available.
    """

這些 docstring 同時作為模型據以推理的 schema，而回傳的 payload 則是 agent 開始建構敘事的依據。Ticket 回傳時會包含完整的 status_history，以易讀的鏈狀呈現（例如「In Progress → Code Review → Awaiting Release → Done」），有助於識別曾反覆進出「Blocked」狀態的 ticket。MR 則會提供撰寫程式碼／審查／部署各階段的時間切分，以及發布它的 release，有助於識別 MR 之間的共通模式及其對發布週期的影響。

系統提示鼓勵 agent 主動使用這些工具："use these tools proactively ... look it up before drawing conclusions"。

輸出結構

Agent 的輸出型別為純字串——沒有結構化輸出 schema，也沒有後處理。形塑報告的唯一依據是提示中的任務定義：對最新 Sprint 的精簡摘要、相較於基準的 2 至 4 項顯著趨勢（"both positive and negative"），以及 3 至 5 項具體的討論要點或討論問題，並置於三個必要標題之下：Sprint Summary、Notable Trends、Retrospective Talking Points。

指定 2 至 4 項趨勢與 3 至 5 項討論要點，迫使內容必須有所取捨；而將第三部分設定為問題而非結論，則有助於讓報告維持會前閱讀資料的定位，而非定論，相信團隊擁有完整脈絡來解讀趨勢並決定後續行動。

典型的執行流程

以下為典型 agent 執行流程的示意。摘要中點名了 11 個 ticket 與 MR，agent 則平行執行了 11 次查詢以取得所需細節。報告在單次 LLM 呼叫中產生，輸出為包含三個章節的 Markdown 報告。

這些查詢讓報告的細節更為豐富。週期時間最嚴重的離群值（16.8 天）橫跨了兩個 Sprint，其 merge request 從首次提交到發布共耗時 308.7 小時（細分為撰寫程式碼 116.3 小時、審查 170.0 小時、部署 22.4 小時）。另一個 MR 在 99.7 小時中有 99.5 小時都花在審查上。

報告指出瓶頸在於審查延遲（中位數 58 小時，約為前一個 Sprint 的三倍），而非部署，並能點出可供討論的具體 ticket／MR。報告也標示發布次數已從 23 次降至 6 次，同時變更失敗率從 8.7% 改善至零，並提問：流量趨緩究竟是刻意的風險控管，還是僅僅是變更在審查階段排隊等候所致。

整個執行過程共進行了兩次 LLM 呼叫：約 11,400 個輸入 token（其中三分之一為第二次呼叫時的快取讀取）與 2,200 個輸出 token。以撰寫當時的 GPT-5.4 API 定價計算，費用約為 $0.05，其中大部分來自輸出 token。

實務上的提示工程

別點名工程師

在最初的原型中，agent 在討論進度較慢的 ticket 時經常會直接點名工程師。為了維持無責備的回顧氛圍，我在提示中加入了一道防護機制來避免這種情況。Agent 被指示聚焦於團隊整體的趨勢與工作本身，而非個人表現。

這一點也能透過確定性的 eval 來把關。該 eval 會從輸入中擷取所有經手人與 MR 作者，若其中任何一者出現在輸出中即判定為失敗。提示與 eval 共同落實了這項規則。

Schema 也是提示的一部分

Agent 會針對你的欄位名稱進行推理，因此命名十分重要。早期版本會依據 Jira 的 status_category 欄位誤判 ticket 的狀態以及是否已完成。在 ticket schema 中新增一個 is_done 布林欄位後便修正了此問題，透過確定性邏輯與資料結構來編碼語意，而非依賴模型去解讀含糊的欄位名稱或值。

結構勝過指令

提示從未使用「hypothesis」一詞，儘管假設正是其產出。第三部分的內容是討論要點與討論問題，而非結論。回顧會議應由人主導，而報告格式本身就體現了這一點，而非要求模型自行記住。

最初的提示還要求提供一份一目了然的關鍵指標摘要表，但模型每次產生的摘要格式都不一致。透過在 agent 之外建構 Web UI，摘要表成為產生敘事旁的確定性元件。若輸出的某部分每次都應保持一致，就別要求 LLM 來產生它。

結論

回顧代理對我們的團隊而言是一個小而實用的工具，有助於在工程回顧會議中激發討論與反思。它展現了如何透過提示工程與查詢工具的運用，打造出尊重團隊動態並聚焦於可執行洞見的有價值 AI 助理。

其實用性很大一部分來自底層的指標數據平台，該平台提供了 agent 據以推理的權威資料。這需要在追蹤哪些指標以及如何從開發工作流程中計算這些指標上做出審慎的選擇。在下一篇文章中，我將深入探討該平台的運作方式、我們如何推導 DORA metrics，以及這一切如何整合以支援我們的工程團隊。