一開始，那份自動化流程很簡單。

文件上只有三步：

1. 建立工作項目
2. 驗證結果
3. 回報使用者

後來需求慢慢增加。

有人需要補一個欄位。

有人遇到 API Timeout。

另一個流程要多帶一組 Mapping。

為了方便維護，團隊直接把細節補進原本的 Workflow：

endpoint
payload
field mapping
retry condition
response parsing

當時每一次修改都很合理。

因為真正執行的人打開同一份流程，就能看到全部東西。

直到某次底層 API 改了一個欄位。

四條不同 Workflow 同時開始失敗。

真正修 Code 只花十幾分鐘。

後面卻花了大半天，逐份找哪一條流程還藏著舊的欄位名稱。

接手的人最後問了一句：

「這份 Workflow 到底是在描述工作，還是在描述 API？」

沒有人能很快回答。

細節放在一起，最開始確實比較省事

把所有資訊都寫在 Workflow 裡，有一個很直接的好處：

不需要跳檔案。

不需要先理解哪一層負責什麼。

看到 Step 1，就能直接知道 API 怎麼叫。

例如：

Create item
→ POST /xxx
→ field A = ...
→ field B = ...
→ if timeout retry ...

對第一個作者來說，這通常很好用。

因為他同時知道兩件事：

這份工作要完成什麼。

以及：

目前這個 API 要怎麼呼叫。

問題會在第二、第三條 Workflow 出現。

大家開始複製相同的 API Detail。

同一個底層 Contract，就被散落到不同的工作流程裡。

Workflow 和 Library 保存的是不同種類的穩定性

Package 裡對這個邊界寫得很直接：

Workflow task-oriented；Library API-oriented。

這不是為了把架構拆漂亮。

而是兩層真正需要穩定的東西不同。

Workflow 應該保存：

這份工作要做哪些步驟？
順序是什麼？
什麼條件下往下一步？
最後怎麼確認工作完成？

Library 則保存：

現在 API endpoint 是什麼？
payload 怎麼組？
field / ID 怎麼 resolve？
response 怎麼解讀？

如果底層 API 改版，真正應該被迫修改的，最好只有負責 API Contract 的那一層。

上面的工作意圖如果沒有變，就不該跟著一起重寫。

問題不只是 Maintenance Cost

那次事故裡更麻煩的，其實不是四份文件都要修。

而是 Workflow 已經很難讀。

一位新接手的人打開流程，看到的是：

POST
mapping
retry
response code
field conversion

但他很難快速回答：

這份工作為什麼要先做這一步？

或者：

哪個結果才代表這個 Task 真正完成？

當 implementation detail 太多，工作本身反而被埋在下面。

這也是 Layer Boundary 真正影響交接的地方。

一份 Workflow 如果只能由熟悉底層 API 的人理解，那它就不再只是工作流程。

他們沒有把 API 細節藏到看不見

後來團隊沒有刪掉那些精確規則。

只是把它們收回 Library。

Workflow 重新變成：

Create item
→ Verify created state
→ Report result

而 Create item 的 Library Contract 裡才保存：

current endpoint
current metadata
payload mapping
error behavior
verification fields

需要 Debug 時，維護者仍然可以往下看。

只是一般接手 Workflow 的人，不必先穿過一堆 API Detail 才知道工作在做什麼。

下一次改版，只壞在一個地方

幾週後，同一個 API 又改了一個欄位。

這次四條 Workflow 都沒有被打開。

團隊只修改 Library 裡的 Field Resolution。

重新跑幾個 Case。

上層流程照常：

建立
驗證
回報

接手的人看著 Commit 說：

「這次怎麼只有一個檔案？」

因為這一次，底層 API 改的只是底層。

工作的意思沒有跟著一起被改寫。