Kiro Workflows 上手：把多步驟 coding agent 任務寫成可重跑的 recipe

瀏覽次數: 5

先更正一個標題上的版本號：Kiro 官方 changelog 寫的是 2026-09-30 同步推出，IDE 目前列在 1.2.x（最新看到 1.2.4），CLI 是 2.26.0，我沒有查到「IDE 1.4.2 / CLI 2.0」這組數字。CLI 2.0 是更早的另一次大改版（Windows 支援、headless 模式）。本文一律以官方 changelog 的版本為準。

本文大綱

為什麼值得花時間學

用 coding agent 做大一點的任務，最常見的痛點有三個：

一個對話塞太多事，context 越滾越髒，後半段開始忘前半段。
「寫完的人自己審自己」，審查形同虛設。
你得一直盯著，等 CI、等 review，agent 在中間空轉燒 token。

Kiro（AWS 做的 agentic IDE / CLI）在 2026-09-30 推出的 Workflows，就是針對這三件事：把多步驟計畫寫成可重跑的 recipe，每一步開獨立 agent session，主對話照常能用。 官方 blog 由 Romain Dura（Engineering）與 Doug Clauson（Product Lead）署名。

這篇不談趨勢，只談怎麼開、怎麼寫、怎麼避坑。

它到底是什麼

官方的說法是：Workflows 讓你「run a reusable, multi-step plan while you continue in the parent chat」，每個 step 在自己的 agent session 裡跑。文件列了五個基本概念：

Steps：一個 agent、一個聚焦的 context。
Handoffs：步驟之間只能靠明確的交接傳結果，後一步讀不到前一步的 session。
Branching：多個 agent 獨立評估同一份工作，再用規則合併結果。
Loops：重複執行直到條件成立，或碰到安全上限。
Waits：監看外部系統（例如 PR），等待期間不花模型 token。

三個平台（IDE、CLI、Web）共用同一套 runtime，但啟用方式不同。

第一步：三個平台怎麼開

Workflows 是 opt-in，預設關閉。

平台	啟用方式	備註
IDE	Workspace Configuration 裡 Agent Focus 打開，或在 Settings 設 `kiroAgent.workflows.enabled`	開完要新開一個 chat 才生效
CLI（2.26.0）	在 V3 session 開 `/settings` → Features → 勾 Workflows，然後重啟 CLI	用 `/workflow run` 啟動、`/workflow` 管理
Web（cloud session）	Settings > Workflows	可上傳 `.workflow.json/.yaml/.yml`，或用 Configuration Sync 同步 `.kiro/workflows/` 資料夾

兩個容易踩的點：

CLI 要在 V3 session 才有，Classic session 看不到。
開完沒生效，九成是忘了重啟 CLI 或沒開新 chat。

第二步：先用內建 recipe，不要急著自己寫

Web 版附三個內建 recipe：

investigate：唯讀調查，適合「先搞懂這個 repo 的部署架構」，把髒活丟背景，主對話 context 保持乾淨。
feature-pipeline：分階段交付功能，涵蓋需求、設計審查、實作規劃、平行 code review。官方 blog 提到每個 loop 最多嘗試三次就停。
publish-pr：開 PR、處理 CI 重試與 review 意見，一路到 merge。

建議的上手順序：先跑 investigate，因為它唯讀、零風險；再跑 feature-pipeline 在一個小功能上；最後才寫自己的。

可以直接下這類 prompt（CLI 可用 /workflow run，或用自然語言請 agent 幫你建）：

用 investigate workflow 調查這個 repo 的部署架構，
輸出要包含：進入點、相依服務、風險點、現有測試覆蓋，並附程式碼出處。

官方也說可以「描述你要的結果，讓 Kiro 提案一個結構化計畫」，再由你決定要不要跑。

第三步：看懂 recipe 的結構

recipe 是放在 .kiro/workflows/ 的 JSON 或 YAML，檔名後綴 *.workflow.json / *.workflow.yaml / *.workflow.yml。內容是「inputs + 一棵節點樹」。

官方文件列出的必填欄位：

節點	用途	必填欄位
step	單一 agent、獨立 session	`id`、`agent`、`prompt`
sequence	依序執行子節點	`id`、`steps`
repeat	迴圈到條件成立	`id`、`steps`、`maxIterations`、`onMaxIterations`
parallel	平行分支	`id`、`branches`、`joinPolicy`（`all` / `allSettled` / `any`）
watch	輪詢外部系統	`id`、`handler`、`config`

step 的選填欄位有 artifacts、captureOutput、completion、modelId、effortLevel。

資料怎麼傳： 用模板語法。{{input-name}} 取啟動輸入，{{step-id.output}} 取指定步驟輸出，{{previous.output}} 取前一個同層步驟輸出，{{artifacts.name}} 取登錄過的檔案路徑。引用必須指向「先完成」的 producer。

步驟怎麼回報： step agent 用 send_message 工具表態，severity 決定生命週期：success 完成該步、warning 暫停等你回覆、error 該步失敗。

硬限制： 單一 recipe 最多 50 個 step 節點、巢狀最深 8 層、節點 id 不可重複、宣告的 inputs 啟動時都要給。repeat 的迭代不佔用 50 個靜態 step 名額。

迴圈停止條件有三種：containsText（輸出含特定文字）、completionSignal（步驟結果）、fileCheck（檢查某路徑上 JSON 值）。

內建的 workflow 專用 agent 有 wf-planner、wf-coder、wf-design、wf-design-reviewer、wf-review-aggregator、wf-pr-submitter、wf-pr-responder、wf-auto-researcher、semantic_reviewer。

第四步：照文件欄位寫一個「修到測試過為止」的 recipe

官方範例「Troubleshoot Until Verified」的精神是：重現失敗、一次診斷一個原因、做最小修正、重跑同一個檢查，最多 10 輪就暫停。下面是我依文件列的欄位拼的示意骨架，不是官方原文，巢狀細節（例如 stopCondition 的精確形狀）我沒有查到完整範例，所以請務必先用 validate_workflow 檢查再跑。

# .kiro/workflows/fix-until-green.workflow.yaml（示意，未實測）
inputs:
  - test-command
root:
  id: main
  type: sequence
  steps:
    - id: reproduce
      type: step
      agent: wf-coder
      captureOutput: true
      prompt: |
        執行 {{test-command}}，只重現並記錄失敗，不要修改任何程式碼。
    - id: fix-loop
      type: repeat
      maxIterations: 10
      onMaxIterations: pause
      steps:
        - id: fix-one
          type: step
          agent: wf-coder
          prompt: |
            參考失敗紀錄 {{reproduce.output}}。
            一次只診斷一個原因，做最小修正，再重跑 {{test-command}}。
            全部通過才用 send_message 回報 success。

這個骨架想傳達的設計原則比語法重要：

重現與修復拆成兩個 step。 重現那步唯讀，輸出當證據交給後面。
停止條件要機器可判讀。 官方強調 loop 該用明確訊號（輸出文字、完成訊號、檔案檢查）結束，而不是靠 agent「覺得好了」。
iteration cap 是安全閥，不是成功指標。 碰到上限時 run 會進入 Paused (iteration cap)，由你決定繼續還是改方向。
每步 prompt 只講一件事。 因為步驟之間不共享 session，需要的資訊都得用 {{...}} 明確帶過去。

寫完後先請 agent 呼叫 validate_workflow，它會在啟動前抓 schema 錯誤、重複 id、模板問題。

第五步：跑起來之後怎麼控

run 有幾種狀態：Running、Paused（needs input：某步用 send_message 要你回覆）、Paused（at boundary：你要求的暫停安全生效）、Paused（iteration cap）、以及 Completed / Failed / Aborted。

操作上：

pause：停在下個安全邊界。
resume：從已存檔狀態繼續，已完成的工作不重做。
stop：立即中斷。
retry：重置失敗節點，同層已完成的保留。
步驟需要輸入時，可以直接在該步驟的介面回覆（Web 版有「Answer this step」「Steer the agent」「Message this step's agent」），你的回覆會進入該暫停步驟自己的 session。

中斷後不用慌：重開父 session，到 Workflows 區看狀態，再 resume 或 retry，Kiro 會從最後一個 durable checkpoint 還原。

數據與限制（誠實版）

官方這次沒有公布效能數字，沒有「省多少時間」或「成功率提升多少」的 benchmark，所以我也不會編。能確認的只有機制與限制：

成本會隨複雜度成長。 官方 blog 明說 credit 用量與 workflow 複雜度成正比。多步驟加平行 review 加迴圈，用量一定比單一對話高。
Kiro 在沒有指示時會自己做假設。 blog 的原話精神是：沒給具體指示，它會對任務結構做假設；遇到設計變更、範圍擴張、UX 改動才會停下來問你。所以 prompt 與 inputs 要寫清楚。
同時跑多個 run 要隔離。 需要不同的 run_dir 與 artifact 路徑；若多個 run 可能改同一批檔案，文件建議用獨立 worktree。
安全防護。 在 .kiro/workflows/ 改 recipe，agent 必須先經你同意，即使你給了更廣的檔案權限也一樣。在未信任的 workspace，recipe 不會載入，直到你信任該 workspace。
功能是否可用取決於帳號資格，這點官方有註明。

什麼時候該用、什麼時候別用

適合：

流程固定、你已經手動做過好幾次的事（調查、功能交付、修測試、發 PR）。
需要「獨立第二意見」的審查：官方範例讓平行 review 使用不同模型，這比同一個 agent 自審可靠。
要等外部事件的任務：watch 節點等待時不花模型 turn，只在有動靜時才耗 token。

不適合：

一次性的小修改，開 workflow 的設定成本大於收益。
需求還在變、你自己都沒想清楚的探索。步驟之間靠明確交接，探索型任務會一直被打斷。
預算敏感而且 loop 上限設得很大的情境。

對工程團隊的可操作建議

先在一個 repo 試點，只開 investigate。 零寫入風險，先建立對 step 與 handoff 的手感。
把 recipe 當程式碼管理。 放在 .kiro/workflows/、走 PR review。Web 版可用 Configuration Sync 把整個資料夾同步到雲端。
loop 一律設保守的 maxIterations。 官方範例是 10 或 3，先小後大。
每個 loop 都要有機器可判讀的停止條件。 優先用 fileCheck 或 completionSignal，少用 containsText 配模糊字串。
審查步驟換模型。 用 modelId 讓 reviewer 跟 coder 用不同模型，才有獨立性。
值得實測的點： 同一個任務，單一對話 vs workflow，比較 token 用量與審查抓到的問題數。官方沒給這個對照，建議自己量一次再決定要不要推廣。