iT邦幫忙

2026 iThome 鐵人賽

DAY 5
0
Claude AI

把 Claude 練成專家:30 天打造可驗證的 Agent Skills系列 第 5

Day 05|案例實戰:把 ticket-guard 寫成可驗收的需求

  • 分享至 

  • xImage
  •  

昨日回顧

Day 4 建立了規格卡:一句話任務、輸入輸出、範圍、護欄與成功標準。今天不再談抽象原則,直接把演唱會購票安全檢查 skill 的需求寫完整。目標是讓明天開始實作時,每一個檔案都有理由,每一個結果都能驗收。

先定義成功,不先列功能

這支 skill 的價值不是「看起來懂售票」,而是穩定回答一個窄問題:使用者提供的網址,是否屬於我們有證據確認的官方售票管道?

成功標準有四條:

  1. 相同的網址,不管使用者怎麼問,都得到一致分類。
  2. 每個分類都有可追溯的證據,不靠模型印象。
  3. 資訊不足或證據衝突時,明確回報不知道。
  4. 不跨進登入、付款、代購或非官方轉售推薦。

需求卡 v1

名稱

ticket-guard

一句話任務

檢查使用者提供的演唱會售票網址,判斷其域名是否命中已驗證的官方來源,並用固定格式回報結果與證據。

觸發時機

當使用者:

  • 貼出售票或購票網址
  • 問「這個連結是真的嗎/官方嗎」
  • 提到票務網站、假連結或售票詐騙
  • 要求確認某個售票入口

不因為只出現「演唱會」或「門票」就觸發。使用者若只是問活動日期、座位或票價,這不是本 skill 的工作。

必要輸入

至少一個可解析的完整網址,例如:

https://tickets.example.com/event/123

可以同時接受使用者的補充文字,例如「這是朋友傳給我的」。補充文字能提供背景,但不能取代網址證據。

輸入正規化

在比對前必須:

  1. 解析 URL,不用字串包含判斷。
  2. 將域名轉成小寫。
  3. 移除結尾的點。
  4. 分開記錄完整 host 與可註冊根域名。
  5. 保留子網域,因為 tickets.example.comexample.com 的授權範圍可能不同。
  6. 拒絕無法解析、缺少 host 或使用非 HTTP(S) scheme 的輸入。

資料來源

第一版只使用版本庫裡的 references/sources.md。每筆官方來源至少包含:

  • domain
  • 主辦方或售票服務名稱
  • 官方證據 URL
  • 驗證日期
  • 適用範圍或備註

模型記憶、搜尋摘要、頁面長得像官方網站,都不能直接升級成官方來源。新增清單項目必須有可追溯的官方證據。

分類結果

結果只能是三種:

  1. OFFICIAL:host 或規格允許的子網域規則命中已驗證清單。
  2. UNCONFIRMED:未命中清單,或出現仿冒風險訊號,但證據不足以斷言詐騙。
  3. INSUFFICIENT_INPUT:缺少完整網址,或網址無法解析。

第一版不提供 SCAM 類別。沒有調查與法律層級的證據,skill 不應直接指控。

判斷順序

流程順序固定,避免不同執行產生不同答案:

  1. 驗證並解析輸入。
  2. 正規化 host。
  3. 對官方來源清單做精確比對。
  4. 未命中時,檢查仿冒風險訊號。
  5. 依固定 schema 產生結果。

官方清單比對必須由確定性腳本完成,不交給語言模型自由判斷。模型負責解釋結果,不負責改寫分類。

風險訊號

未命中官方清單時,可以檢查:

  • 與官方域名只差一個字元
  • 使用容易混淆的 Unicode 字元
  • 把官方名稱塞在不相關的根域名之前
  • 使用異常長的子網域誘導閱讀
  • 網址中含有要求立即付款或索取憑證的可疑路徑字詞

命中風險訊號仍然只回報 UNCONFIRMED,並列出觀察到的訊號。訊號是提醒,不是定罪。

固定輸出 schema

status: OFFICIAL | UNCONFIRMED | INSUFFICIENT_INPUT
checked_url: 使用者提供的完整網址
normalized_host: 正規化後的 host,無法解析時為 null
evidence:
  - 命中的來源紀錄或風險訊號
next_step: 建議的下一個安全步驟

給人的回答可以是自然語言,但必須忠實映射這五個欄位。不能把 UNCONFIRMED 改寫成「看起來沒問題」。

護欄

  1. 不把 HTTPS 鎖頭當成官方證據。
  2. 不因搜尋排名、廣告或頁面設計而判定官方。
  3. 不輸入帳號、密碼、驗證碼或付款資料。
  4. 不替使用者完成購票。
  5. 不推薦清單外的轉售平台。
  6. 證據衝突或清單過期時,回報無法確認並指向官方入口。
  7. 不揭露使用者提供的私人背景;判斷只需要網址。

驗收案例

案例 A:精確命中

輸入:清單裡的官方 host。
預期:OFFICIAL,回傳對應紀錄與驗證日期。

案例 B:大小寫與尾點

輸入:同一 host,但混用大寫或帶結尾點。
預期:正規化後仍穩定命中。

案例 C:相似字元仿冒

輸入:與官方域名只差一個字元。
預期:UNCONFIRMED,列出相似域名訊號,不使用「確定詐騙」。

案例 D:官方名稱放在錯誤根域名

輸入:official-name.example.net,但真正官方根域名不是 example.net
預期:UNCONFIRMED,不能因子網域含官方名稱而放行。

案例 E:只有截圖

輸入:沒有完整網址。
預期:INSUFFICIENT_INPUT,只要求補完整連結。

案例 F:要求直接購買

輸入:官方網址加上「幫我買兩張」。
預期:只完成來源分類,清楚說購買不在此 skill 範圍。

完成定義

第一版需求完成的條件不是「寫出一份 SKILL.md」,而是:

  • 上述六個案例都有唯一預期結果
  • 官方清單有欄位規格與證據要求
  • 分類由腳本決定,回答不改寫分類
  • 不知道與不執行的邊界寫清楚
  • 後續可以把案例直接轉成 eval fixtures

這份需求已經替實作做了幾個決定:需要一份 SKILL.md、一份 references/sources.md、一支域名檢查腳本,以及之後可重用的測試案例。沒有任何檔案是因為「skill 通常長這樣」才出現,而是由需求推導出來。

明天預告

Day 6 開始動手:建立目錄骨架與第一版 SKILL.md,讓今天的需求第一次變成可執行流程。


上一篇
Day 04|設計一支 skill 的規格:範圍與護欄
下一篇
Day 06|動手建立 skill:目錄骨架與第一版 SKILL.md
系列文
把 Claude 練成專家:30 天打造可驗證的 Agent Skills10
圖片
  熱門推薦
圖片
{{ item.channelVendor }} | {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言