在上一篇貼文中，我說明了我們為何想衡量工程時間都花在哪裡，以及一個小型的 LLM 代理如何協助將這項衡量整合到團隊的 Sprint 回顧會議中。幾個月後，我們已在各團隊中推行這個代理，它也成功引發了以往不會出現的討論。

本文聚焦於這個代理的運作方式、它如何接收資料，以及提示詞是如何演進的。至於底層的資料平台，包含 DORA 指標是如何推導出來的，將在下一篇貼文中另行介紹。

總覽

這個代理會從我們的生產力指標資料平台擷取指標與活動資料，並產生一份會前閱讀用的回顧報告，總結本次衝刺並提出可能的討論要點。

與其把所有原始資料一股腦丟給模型，代理只會拿到橫跨三個衝刺的指標摘要，以及用來查詢特定票證、合併請求與失敗發布細節的工具。

代理設計

初始提示詞

初始提示詞會總結橫跨三個衝刺的指標，並分別標記為 [BASELINE] 或 [LATEST - FOCUS SPRINT]。這些指標涵蓋 Jira 交付指標與 DORA 指標：

所有指標都是在資料平台中以確定性程式碼計算完成，我們不會要求模型嘗試從原始資料自行計算。提示詞對此有明確指示：「指標摘要具有權威性，請勿嘗試重新計算或質疑其正確性」。

摘要中還包含離群的票證與合併請求清單（例如週期時間或前置時間超過第 75 百分位數者），以及聚焦衝刺中所有失敗發布的清單。代理被指示以這些清單作為分析的起點。票證會以 KEY (16.8d, 3.0SP) 的格式內嵌呈現，合併請求則為 project!iid (308.7h: coding 116.3h, review 170.0h, deploy 22.4h)。

查詢工具

這個 PydanticAI 代理上註冊了三個工具，讓代理能夠查詢細節：

@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 同時也是模型用來推理的結構描述，而回傳的資料則是代理開始建構敘事的基礎。一張票證回傳時會包含完整的 status_history，以易讀的狀態鏈呈現（例如「In Progress → Code Review → Awaiting Release → Done」），有助於辨識曾反覆進出「Blocked」狀態的票證。合併請求則會拆分程式撰寫／審查／部署各階段所花的時間，並標示其所屬的發布版本，有助於找出合併請求之間的共同模式及其對發布週期的影響。

系統提示詞鼓勵代理主動使用這些工具：「主動使用這些工具……在下結論前先查詢確認」。

輸出結構

代理的輸出型別是純文字字串——沒有結構化的輸出 schema，也沒有後處理。唯一形塑報告的是提示詞中的任務定義：一份最新衝刺的精簡總結、2 至 4 項相較於基準的顯著趨勢（「包含正向與負向」），以及 3 至 5 項具體的討論要點或討論題目，並必須包含三個標題：Sprint Summary、Notable Trends、Retrospective Talking Points。

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

典型的執行流程

以下是一個典型的代理執行範例。摘要中點名了 11 張票證與合併請求，代理為了取得所需細節，平行執行了 11 次查詢。報告是在單次 LLM 呼叫中產生，輸出為包含三個章節的 Markdown 報告。

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

報告指出瓶頸在於審查延遲（中位數 58 小時，約為前一個衝刺的三倍），而非部署，並能點出具體可供討論的票證／合併請求。報告也標示發布次數從 23 次降至 6 次，同時變更失敗率從 8.7% 降至零，並提問：流動速度變慢究竟是刻意的風險控管，還是只是變更卡在審查階段排隊等待。

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

實務上的提示詞工程

別點名工程師

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

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

結構描述本身就是提示詞的一部分

代理會針對你的欄位名稱進行推理，因此命名很重要。早期版本會根據 Jira 的 status_category 欄位，錯誤判斷票證的狀態以及是否已完成。透過在票證的結構描述中新增一個布林值 is_done 欄位，這個問題就解決了——做法是以確定性邏輯與資料結構來編碼語意，而非依賴模型去解讀模稜兩可的欄位名稱或數值。

結構勝過指令

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

最初的提示詞還要求產生一個一目瞭然的關鍵指標總表，但模型每次產生的表格格式都不一樣。透過在代理之外建立一個網頁介面，總表改由確定性元件產生，顯示在自動生成的敘述旁。若輸出的某個部分每次都應該長得一樣，就別要求 LLM 來產生它。

結論

回顧代理對我們的團隊來說是一個小而有用的工具，有助於在工程回顧會議中激發討論與反思。它展示了如何透過提示詞工程與查詢工具的搭配，打造出一個既尊重團隊動態、又聚焦於可執行洞察的實用 AI 助手。

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