Insight To Quality

insight-to-quality

`insight-to-quality` 是一套給人類與 AI agent 協作開發時使用的 workflow skill。

它存在的原因很簡單：

當專案開始變複雜，或討論橫跨多個 session、多個 agent、多次 plan mode / implementation mode 切換時，最常見的問題不是「想不到點子」，而是：

• 每次都重新討論一輪，沒有穩定累積
• 不同輪對話使用不同抽象層，需求、設計、結構、實作混在一起
• LLM context window 與快取有效時間有限，導致之前的重要判斷慢慢漂掉
• 到真正開始寫 code 時，已經沒有一份穩定的 shared document 能讓後續 agent 直接接手

這套 skill 的核心目的，就是把這些容易漂移的討論，收斂成少數幾份**能夠跨回合累積、跨 agent 接手、而且能一路往下推進實作**的核心文檔。

它不是要把所有事情文件化，也不是要把所有需求一次問完。 它要做的是：

• 先把系統輪廓講清楚
• 再把關鍵設計決策與 trade-off 講清楚
• 再把軟體結構、ownership、seams 講清楚
• 再規劃實作階段與當前工作，往 TDD、review 推進

換句話說，這套 skill 比較像是在建立一條**穩定可累積的開發討論骨架**，而不是幫你一次攤平所有細節。

它也想解決我自己遇到的其他問題：

• 這些測試到底有沒有保護到最重要的風險
• 測的是使用者真正會在意的結果，還是只是測了一堆 implementation detail
• 寫了很多 edge cases、很多 unit tests 之後，真正該保護的 seam、資料狀態、流程結果是不是還是漏掉了

這套 skill 想做的不是「逼 agent 多寫測試」，而是讓：

• feature-brief 先說清楚 main risk to protect
• scenario bullets 先對齊實際情境
• tdd-workflow 再根據風險決定從哪個測試層開始

這樣測試和實際情況才比較容易對齊，而不是最後只剩下一堆看起來很多、但不知道在保護什麼的測試。

當然，這不代表 agent 會自動把所有實作細節測好。 像這些東西：

• helper function 的細部測試
• 很局部的 implementation-detail test
• 某些純技術性的 defensive test

仍然可能需要使用者自己補判斷，或直接下更明確的指令。

但至少在這套 flow 裡，文檔先把：

• 這一刀在保護什麼
• 哪些 scenario 重要
• 建議先在哪一層測

整理出來後，如果 agent 少寫了重要測試，會更容易被看出來，而不需要人自己在腦中重新手動比對整個需求與實作。

---

這套 skill 適合誰

它特別適合這些情境：

• 你要和 AI agent 長時間協作開發，不希望每次都從頭重新對齊
• 你希望 plan mode 產出的內容能沉澱成穩定文檔，而不是只留在聊天紀錄裡
• 你的專案有明確的系統行為、設計取捨、結構切分、實作順序，這些東西值得被逐層釐清
• 你希望後續不同 agent 或未來的自己，可以根據既有文檔直接往下推，而不是再重開一輪 discovery
• 你在意「現在這段 code 為什麼這樣切、這個測試在保護什麼、這個 stage 為什麼先做」

比較典型的例子是：

• 有明確 domain / workflow 的後端或全端專案
• 需要逐步落地的 AI agent / AI workflow 專案
• 會跨多次討論與多輪實作的中小型產品開發

---

這套 skill 不適合什麼

它不太適合這些情境：

• 你只是要快速試一個非常短的小 prototype，幾十分鐘內就能直接寫完

• 你主要在做純視覺探索型的前端設計，重點在畫面風格、動效、版面迭代，而不是穩定的 system shape

• 你的專案本質上不是單一系統或單一產品，而是高度分散的多團隊微服務治理問題，這時候這套 flow 只能覆蓋其中某個服務或某個 bounded context，不適合直接拿來當整個組織層的架構方法

• **純前端設計**：通常不太適合完整套用這條流程，除非那個前端本身有很強的互動狀態、資料流、或 domain workflow。

• **微服務架構專案**：不是完全不適合，而是不要把它拿來一次描述整個服務群；比較適合把它用在其中一個具體服務、某條跨服務流程、或某個明確 bounded context。

---

這套 skill 做不到什麼

它不會幫你