swe-knowledge

# swe-knowledge — 軟體工程的 Definition of Done 這裡放的是**所有增量共用**的完成條件。跟每張單獨有的驗收條件（acceptance criteria）分得很 開：AC 寫在那張單凍結的斷言裡，DoD 寫在這裡。**一張單可以通過全部 AC 卻沒有 done**—— 斷言全綠但改動還躺在預設分支上、沒有任何人看得到它，就是那個情況。 所以這幾條不要抄進任何一張單的凍結區。抄進去等於每張單都重簽一次同樣幾行不承載新資訊的 東西，而漏抄的那一張就靜默地少了一條完成條件。 ## 五條 1. **改動住在一條 branch 上，不躺在預設分支。** 開的時機是「判定要立案之後、動手之前」—— 一個還沒開工的成功定義直接躺在預設分支上，等於它已經是既成事實。 2. **有一個 PR。** **PR 開出來就是實作完成**：它是那份改動變成可被別人看見、可被判定的 東西的那一刻。沒有 PR 的改動不管本機多綠都還沒 done。 3. **判定過才進預設分支。** 進去的路徑是那個 PR，不是直接推。 4. **push 之前，本機跑完跑得動的驗證。** type check、lint、單元測試、受影響路徑的冒煙。 把 CI 當第一道防線等於把 reviewer 當驗證工具。 5. **reviewer 提的每一條，處置回到那條意見上。** 不是「有沒有處理」——是**提出者拿不拿 得到那個處置**。他看的是他留言的地方，回在別處他收不到。 第 2 條有一個這個 repo 自己的教訓：2026-08-03，「開 PR」這個能力在腳本歸位時被刪掉，因為 它在三站裡沒有主人；43 分鐘後有人寫了一句跟腳本矛盾的散文把洞蓋住，於是「PR 算不算完成」 有兩個互相矛盾的答案在流通。現在它有主人了，就是這一條。 第 5 條是同一個形狀又發生了一次。2026-08-11：一個 PR 收到三位 reviewer 的意見，全部查證、 修掉、斷言重跑全綠，也回了另一個系統的訊息串——**但那個 PR 上一則回覆都沒有**，是人自己 發現的（「我好像沒有在 PR 上看到你怎麼處理的」）。偵測有主人（誰欠我回覆、誰欠我審查， 都有東西在算），**動作沒有主人**。而「還沒被 approve」這個狀態，跟「我還沒動手」長得 一模一樣。 ## 在程式碼裡，「你寫下的話」長成什麼樣子 `engineering` 那條「送審之前把自己寫下的話跟行為對一遍」在這一類工作裡有具體形狀。這幾樣 都是對行為的主張，都會跟實作分開演化，而編譯器與測試都不會抓： - **doc-comment 的第一句**——通常是最早寫下的，也最可能是舊設計的化石。 - **型別宣告**（參數型別、回傳型別、介面欄位）——宣告成數字就不能送出字串。它是契約， 不是提示；改了寫入路徑要回頭看宣告。 - **名字**——一個叫「處理中」的狀態要真的在事情處理中的時候是真的。 - **形狀**——把等待用的結構套在一個不會等待的呼叫上（例如包住一個同步呼叫），會讓一段 沒有等待的程式碼長得像在等待，而讀的人依樣相信它。 第 4 條那句「本機跑完跑得動的驗證」的另一半就是這個：**跑得動的用跑的，跑不動的用讀的。** 一句說謊的 doc-comment 跑不出紅燈，它只會在下一個人依它行事的時候生效。 所以寫的時候就要讓它值得被讀： - **新增或修改的 function 要有 doc-comment**（TSDoc / JSD...