前言
我們在公司內部的 SaaS 加上了「應用程式內問卷功能」。分工方式是：題目由商務端負責人來設計，框架則由開發端來建立。
從開始對齊需求，到實作完成（合併了 3 個 PR），只花了 2 天。
速度快的原因，不是 AI 的實作能力，而是改變了需求定義的順序。不是先把需求用文字定死再做 mock，而是先做 mock，並在畫面上決定需求。
這篇文章會介紹實際做的 5 個步驟，以及在過程中「有 3 次認知落差在實作前被找出來」的故事。
預想讀者是以下這些人：
- 在少人團隊中，一邊和商務端（PdM、事業負責人）對齊規格，一邊開發的工程師
- 有在使用 Claude Code 之類的 AI 寫程式工具，但需求定義方式還沒改變的人
前提
- 團隊：開發團隊人數少。需求決策者是非工程師的商務端負責人
- 做的東西：在 App 內針對符合條件的使用者顯示問卷，收集回答並可用 CSV 查看
- 使用工具：Claude Code（需求定義很容易看出模型能力差異，因此建議使用當時能用的最高階模型）
傳統做法的問題是什麼
過去的流程是這樣：
用文字定義需求 → 審查 → 實作 → 「跟我想的不一樣」問題在於，文字上的共識會把誤解藏起來。即使讀的是同一段文字，每個人腦中浮現的畫面也不同，但還是可以說「OK」。等到真的做出可運作的東西之後，落差才會被發現。
那為什麼以前不先做 mock？答案很簡單，因為做 mock 的成本太高。如果要先出設計、再把畫面組起來，可能要花好幾天，那麼先用文字縮小範圍就比較合理。
但 AI 讓這個前提被打破了。接近正式設計的 mock 幾十分鐘就能做出來。先做便宜的東西，再把昂貴的東西（決策）放上去。順序就反過來了。
整體架構：5 個步驟
依序說明。
Step 1：先決定「之後一改就會需要重做」的部分
一開始我也猶豫：「要不要在 mock 之前先把需求完整定好？」結論是 No。
先決定的，只限於會影響資料結構的分歧。這次只有 2 個：
- 回答格式需要幾種？（只有單選，還是也要自由輸入、量表）
- 要不要做一個讓非工程師也能編輯題目的後台畫面？
這兩個如果之後才改，就得從資料表設計重來。相反地，文案、配色、版面、顯示位置這些之後都能改。邊看 mock 邊決定會更快，所以不用先定。
提問方式也有訣竅。用編號，並且讓對方可以用 yes / no 回答，一次只問 1～2 個問題。像「你想要什麼樣的問卷？」這種開放式問題，回覆通常比較慢，而且答案也容易模糊。
Step 2：先做 mock，而且要「像真的一樣」
等到 2 個答案都回來後，不先寫成文章，而是直接做 mock。
理由很簡單，人類理解視覺比理解文字快。把文字規格轉成腦中的畫面，對寫的人和讀的人都是負擔。直接把畫面拿出來，就不需要這個轉換。所以下一次對齊時，不是看文件，而是一起看 mock 畫面。「這個畫面會這樣顯示」「按這裡會變成這樣」這種方式，比起講文字更容易形成具體想像。
製作時有 3 個重點。
1. 用真實產品的設計 token 做
讓 AI 讀取產品的 CSS 變數（設計 token）和既有畫面的程式碼，做出和正式產品相同顏色與元件的 mock。越接近真實產品，指出問題的精度就越高。如果只是像紙板模型那樣的 wireframe，對方很容易覺得「反正只是概念」，就不會注意細節上的違和感。
2. 把所有畫面縱向排在同一頁
把使用者會看到的畫面與管理畫面放在同一個 HTML 裡，縱向排列，讓人從上往下看就能理解完整規格。最後再放上「已決定事項」與「待決事項」區塊，待決事項要加上「誰來決定」。
3. 更新時沿用同一個 URL
每次反映指摘都不要建立新檔案，而是直接覆寫同一個 URL。目的是維持「最新共識只要看這裡就知道」的狀態。
實際發生的事：畫面會揭穿誤解
把 mock 拿出來的瞬間，就有人指出：
「咦，這裡的選擇 UI 是拿來做什麼的？我覺得這個可以不要。」
原本在對話中被略過的設定 UI，一旦變成畫面，就被發現其實不需要。接著又出現：
「這裡的概念是，同一個問題會在使用的不同節點出現 4 次。」
我們原本誤以為是「要做 4 種不同的問題」，但其實是「同一組問題在使用的節點重複出現 4 次，以觀察變化」。這件事也是透過 mock 才發現。文字上的共識會把誤解藏起來，畫面會把誤解揭穿。
Step 3：需求文件要把「確認事項」分開寫
在 mock 決定大方向之後，才開始寫成文字。順序很重要。文字不是拿來「決定」的，而是拿來「固定已決定事項」的。
有效的寫法有 3 個。
1. 功能用「可以做到～」的條列式寫法，並且一定要列出「這次不做的東西」
如果不明確寫出範圍外的內容，讀的人（實作人員與 AI）就會自行腦補。
2. 尚未決定的事項不要混在本文裡，另外整理到最後的「確認事項」區塊
排序要按照「不決定就無法開始」的順序。每個項目附上 1～2 行選項與取捨，決策者就能直接回答。等到答案齊了之後，把它們融進正文，然後整個把確認事項區塊刪掉。如果留著，就會看起來像「還有沒決定的功能」。
3. 寫出可以實作的線索時，要用程式碼反查確認
像是「案件數的計算，接到既有的點數消耗觸發點上」這樣，明確寫出要使用現有哪一套機制，甚至寫到欄位名稱。無論是交給 AI 實作，或是之後由人接手，都可以直接開始。
閱讀順序：文字要放在最後最後
這是這篇文章最想傳達的重點。即使需求文件做好了，也不要一開始就讓對方只看文字。順序應該是這樣：
- 確認事項不要先給文字，而是用口頭或聊天，一題一題問。 如果直接丟給對方一篇漏洞百出的文件，認知負擔會很高，而且要指出的問題太多，讀的人會很累。疲勞的讀者會讓審查品質下降。
- 把答案融進正文，完成文件。
- 完成後的文件，作為最終檢查再讓對方花時間仔細看。 這個步驟不能省。因為「花時間讀」這件事本身就會讓人動腦，這時就能發現剛剛口頭溝通時漏掉的錯誤或落差。
也就是說，口頭是用來「決定」，文字是用來「最終檢查」。
還有一個注意事項。需求文件最好控制在 10 分鐘左右可以讀完。 如果要讀 20～30 分鐘以上，讀者的專注力會撐不住，無法當作最終檢查。反過來說，如果文件長到那種程度，本身就是應該拆分任務的訊號。
實際發生的事：文字化是第二道濾網
把完成的需求文件當作最終檢查交給商務端看時，對方回了這樣一句：
「顯示時機不是固定的，我希望可以自由設定。」
原本在 mock 階段已經取得共識的「顯示時機是固定值」，在重新讀過文字後又產生了不同理解。經過「對話 → 畫面 → 文字」這 3 種形式，每一層都濾掉了不同類型的誤解。由於是在實作前發現，所以完全沒有返工。
Step 4：資料庫設計要用「動作流程」來審查
這裡開始就是開發團隊內部的事了。商務端的對齊在 Step 3 就已經完成，schema 不會拿給商務端看。
當我們把 AI 產生的 schema 做成 ER 圖，想在團隊內審查時，老實說情況是這樣的：
「只看資料庫的視覺化，沒辦法判斷這樣設計合不合理。」
我們團隊以經驗較淺的成員為主，就算給 ER 圖，也很難判斷是否合理。仔細想其實很正常，ER 圖只顯示結構，不顯示動作。 真正能判斷合理性的，是動作流程。所以我們請 AI 做出一份用「3 種看法」來說明的資料。
看法內容能看出什麼何時會增加資料列模擬使用者操作的時間序列，並用 diff 風格顯示新增資料列資料表的角色資料從哪個畫面欄位來欄位對應表設計缺漏、不必要欄位改掉之後會壞什麼刪除、修改、重複送出等情境下追蹤歷史資料限制與快照的合理性
重點是要加入「不會發生任何事情的步驟」。例如放上一張「隔天再次打開同一個畫面 → 沒有任何新增」的畫面，就能在那裡確認防重複的規格。
透過這份資料，就算是不熟悉資料庫的人也能審查 schema。最後放上的「5 個問題」（例如：這張資料表是在誰做了什麼時，資料列會增加？）即使不做這份資料，也可以直接拿來用。
Step 5：實作，若有偏差就修正需求文件
到這一步，實作就會很快。Issue 依相依關係拆成 3 個（資料模型與後台畫面 → 使用者端顯示 → 回答列表與 CSV），並採用 1 個 Issue 對應 1 個 PR 的方式推進。
在實作過程中，規格一定會有些微偏移。這次也是在實作中加入了「CSV 的欄位標題採用目前的題目文字（回答內容則保留回答當下的快照）」這類判斷。只要有偏差，就把需求文件更新成與實作一致。
如果把需求文件不只是當成「用來製作的文書」，而是持續當成「功能說明書」來維護，之後每次有人問規格，就不用再回頭讀程式碼。只要在更新紀錄加上註解，文件歷史本身就會變成決策紀錄。
考察：為什麼 AI 時代會變成「先有畫面」
整理起來，我認為結構是這樣：
BeforeAftermock 的製作成本數天數十分鐘瓶頸做出來決定內容決定用的工具文字畫面（＋用文字固定）當 mock 成本很高的時代，先用文字篩選再製作是合理的。現在 mock 幾乎免費，先做出來再透過畫面決定反而更合理。人可以略過文字的字裡行間，但看到畫面不對勁時，會一眼就指出來。
也補充一下注意事項：
- 容易被 mock 的外觀牽著走，導致資料設計討論被跳過。 所以 Step 1 才會先決定「一改就得重做」的分歧，Step 4 再另外做資料庫設計審查
- 如果 mock 做得太漂亮，有時會讓人誤以為「已經做好了」。加一句「這只是外觀，裡面還沒完成」會比較安全
附帶一提：這個做法也整理成給 AI 的指示書
最後，我把這一整套流程存成 Claude Code 的 skills（給 AI 讀的作業手冊）了。裡面包含需求文件格式、確認事項的運作方式、DB 說明資料的架構與範例圖片，所以下一個功能只要說「我想做 XXX 功能」，就能用同樣的模式推進。
在 AI 時代，不只程式碼，成功的流程也可以資產化。我覺得，把一次有效的方法整理成任何團隊成員都能重現的形式，這是很小但很有價值的改變。
總結
- 先決定的只有「之後一改就會需要重做」的部分。用 yes / no 問 1～2 個就好
- 先做 mock。人類看畫面比看文字快，所以對齊時要邊看畫面邊談
- 確認事項用口頭問，等答案融進去完成後，再讓對方花時間仔細讀成品文字做最終檢查
- 需求文件控制在 10 分鐘內可讀完。超過就代表任務該拆分了
- 資料庫設計不要只看結構，而要看「動作流程」來審查（開發團隊內部）
- 實作時如果規格偏了，就把需求文件更新成與實作一致
如果要先從第一步開始嘗試，下次新增功能時，先在寫需求文件前做一張 mock 就好。你應該會感受到指出來的問題數量與品質都不一樣。
參考
- First Round Review: How Superhuman Built an Engine to Find Product Market Fit — 問卷功能的原始靈感，PMF survey 的做法
- 伊藤淳一《寫技術文章的技術》 — 本文寫作方式的參考
株式会社シンシア
在 xincere 株式會社，我們聘用沒有實務經驗的工程師與學生工程實習生，一起工作。
※ 關於在辛西亞的工作方式，請參考這裡
在辛西亞，每年大約有 100 位沒有實務經驗的人來應徵並參加技術面試。
有興趣的人，歡迎從上方連結看看。
原文出處：https://qiita.com/kazuki_ogawa/items/f1a15a199d9f91fe6080
1) --- 會變成分隔線（上一行必須是空白）
2) # 會變成一級標題
3) ## 會變成二級標題
4) ### 會變成三級標題
5) **粗體文字**會顯示粗體文字
6) ```當第一行與最後一行會顯示程式碼
7) 請搜尋 Markdown 語法，了解各種格式
