AI 說完成了，然後呢？

「Issue #4407 已修復，參考 ADR-264，資料庫身分權限……」

「……功能已完成，測試結果全數通過，PR #4087 已提交並合併到 main……」

看起來交代了問題編號、技術依據和修改範圍。但對於平行開著 20+ Claude Session 工作的我來說，經常是滿頭問號。工程開發最大的瓶頸，竟是人類自己。

每個 Session 都很認真，也都有自己的上下文。但我切過去的時候，得先想一下：你是哪位？我們剛剛做到哪？這個東西當初是為了什麼要做？

大家好，我是 June，目前在 AI 軟體新創擔任研發與工程主管，近期帶著小夥伴們，每天兢兢業業地開發產品。
第一篇，我想聊聊：當工程開發跑得太快，我們怎麼回到產品本質的需求釐清與理解？

好，那請 AI 說清楚一點？

難點是如何讓 AI 好好地說清楚，但什麼才叫說清楚？

白話一點嗎？ELI5（Explain Like I’m 5）確實能做得很好，但它有搔到癢處嗎？這個開發項目裡，最需要釐清的是什麼？

各位可以嘗試看看下面這個 Prompt：

/eli5 這個交付項目與 PRD（Product Requirements Document）的達成關係

然後你可能會拿到一個煞有其事，但看不出意義的精美 HTML。而且還很燒 Token。

有圖、有表格、有比喻，還會告訴你資料庫像倉庫，權限像鑰匙。好，我知道了，所以呢？這次到底是誰拿不到鑰匙？他為什麼需要進倉庫？現在給了他鑰匙，會不會連隔壁倉庫也打得開？

重點在於故事

問題就在前面粗體標註的「看不出意義」。每句話都懂，但接不起來，也不知道這跟當初要解決的問題有什麼關係。

直接判斷價值是非常困難的，請看下面的例子：

桌上有一個玻璃杯。

各位有感受到什麼資訊嗎？應該滿摸不著頭腦的吧。知道有個杯子，所以呢？但如果換成下面這個：

桌上有一個玻璃杯，和一個空的馬克杯。

突然就有比較的對象了。為什麼特別說馬克杯是空的？玻璃杯裡有東西嗎？兩個杯子是誰的？

我們開始找關係了，但還是很難判斷，這件事到底有什麼重要。再加一點：

小林緩緩伸出手，桌上的玻璃杯裝著水，他的手卻朝著一個空的馬克杯。

突然就有故事了。小林想做什麼？那杯水是誰的？他為什麼「緩緩」伸出手？
有趣的是，我們還不知道答案，但已經開始試著理解他的處境，甚至腦補接下來會發生的事情。這也是故事有用、卻要小心的地方。故事讓我們產生理解，也可能讓我們以為自己理解了。

回到開發情境，AI 說「權限已修復」，就像告訴我桌上有一個玻璃杯。我需要知道小林想做什麼、遇到什麼限制，才有辦法判斷這次修改有沒有幫上忙。

但小林真的想喝水嗎？還是他只是要把杯子收走？這就要回到需求釐清了。讓 AI 把故事說出來，我們才有機會指出：「等等，你是不是從這邊就理解錯了？」

舉個權限功能的例子，假設 AI 這樣說：

小林是客服，需要查詢自己負責的客戶資料。原本他登入後，查詢會被拒絕，只能請管理員代查。
這次修改後，小林可以自己查，但只能看到負責範圍內的資料。其他客戶的資料，仍然不能看。

這時候我就有問題可以問了：小林負責哪些客戶，是誰設定的？轉交給另一個客服之後呢？原本的小林還看得到嗎？

你看，需求開始有東西可以討論了。也可能講到這邊才發現，喔，原來我們對「負責範圍」的理解根本不一樣。

這就是故事的力量。讓大家能把自己放進情境裡，想一下：「如果是我操作，接下來會發生什麼？」

所以我整理了一個 Story Skill

這個 Skill 裡面，主要要求 AI 做幾件事：

• **先找人：**誰要用這個功能？他想完成什麼？
• **把事情走一遍：**做了什麼操作、收到什麼回應，成功和失敗都要講。
• **把畫面帶進來：**設定面板、使用者畫面或 API 回應，讓大家有東西可以對照。
• **說清楚做到哪：**已實作、只有設計、還在等待，要分開標示，並附上可查核的依據。

拿來看交付項目時，我會再請 AI 把故事接回原本的需求：原本卡在哪？這次改變了什麼？還有哪些沒有解決？

我希望透過這個方式，讓小夥伴們跟我都能早一點發現：「等等，這不是我們當初要的吧？」

AI琳娜，回來吧，說好故事，我們才有機會說 蛤?

以下是 Flow Story Skill 的單檔簡化版，可以直接複製給 AI 使用；也可以存成 SKILL.md，加入自己的開發工具。重點是讓 AI 說清楚：誰遇到什麼問題、功能如何運作，以及哪些已完成、哪些仍待確認。

---
name: flow-story
description: 先建立三個 Persona，再將需求、功能或開發回報轉成使用者流程故事，協助團隊釐清需求、理解差異與確認完成狀態。
---

# Flow Story：讓 AI 把功能說清楚

## 目的

讓團隊理解：誰遇到什麼問題、功能如何幫上忙，
以及這次交付是否符合原本的需求。

適用於需求討論、功能介紹，以及 Issue、PR 或任務完成回報。
單檔即可使用，不依賴其他 Skill 或外部樣式。

## 1. 先建立 3 個 Persona

閱讀提供的需求與開發資料，先提出 3 個與功能相關、
目標或使用情境不同的人物角色，再開始寫故事。

每個 Persona 包含：
- 名字與身分。
- 使用情境：什麼時候會接觸這個功能？
- 目標：他想完成什麼？
- 困難：目前卡在哪裡？
- 期待結果：怎樣才算解決問題？

不要只換名字，卻描述相同的需求。
角色與情境若為推演，標示「假設，待確認」。
資料只支持部分角色時，其餘作為候選，不當成既定需求。

## 2. 從角色展開故事

分別從 3 個 Persona 的角度說明：

1. 發生什麼事，讓他需要使用這個功能？
2. 他做了什麼操作？
3. 系統如何回應？他看見什麼畫面或訊息？
4. 遇到失敗、限制或權限不足時，會發生什麼？
5. 最後是否達成目標？還需要誰協助？

角色若參與同一條流程，就串成完整故事；
若屬於不同情境，則分開呈現，不要硬湊。

技術名詞跟著情境解釋，保留影響需求判斷的細節。
必要時用簡單文字畫面或回應範例輔助，標明是否為示意。

## 3. 對照需求與修改差異

若有提供 PRD、Issue、PR 或實作資料，說明：
- 原本的需求是什麼？
- 修改前，角色遇到什麼問題？
- 修改後，他可以完成什麼？
- 哪些需求已涵蓋？哪些仍有缺口？

需求討論階段尚未實作時，使用「預期行為」描述。
無法存取引用資料時，明確說明，不猜測文件內容。

## 4. 誠實標明完成狀態

依據資料區分：
- 僅有設計：描述了預期行為，尚未實作。
- 已實作：程式已修改，但不代表已部署。
- 已部署：註明環境與版本，若資料有提供。
- 已驗證：註明驗證情境、結果與依據。
- 待確認或受阻：說明缺少什麼、正在等待什麼。

已合併到 main 不代表客戶已能使用。
測試通過只代表已測情境的結果，不代表所有需求都達成。
畫面示意不能作為功能完成的證據。

## 輸出格式

### 三個 Persona
簡列各角色的情境、目標、困難與期待結果。
標明假設。

### 使用者流程故事
從角色角度呈現操作、系統回應與重要分支。

### 與需求的關係
說明前後差異、對應需求及尚未解決的部分。

### 現在做到哪裡
簡列完成狀態、可查核依據與待確認事項。

### 還需要釐清什麼
提出最多 3 個會影響需求或驗收判斷的問題。
沒有實質疑問時，不必硬湊。

## 寫作原則

- 使用繁體中文，技術識別字保留原文。
- 先交代人的處境，再解釋技術。
- 依據資料說故事，不為了流暢而補造事實。
- 已知事實、假設與預期行為要分清楚。
- 保持精簡，不必製作 HTML。
- 目標是讓團隊能指出理解落差，並確認需求。

## 使用範例

請用 Flow Story 整理這個交付項目。
先提出 3 個 Persona，再說明各自的使用情境、
修改前後差異，以及與 PRD 的達成關係。
請標明假設、驗證依據與待確認事項。

參考資料：
〔貼上需求、Issue、PR 或任務回報〕