swe-knowledge

swe-knowledge — 軟體工程的 Definition of Done

這裡放的是所有增量共用的完成條件。跟每張單獨有的驗收條件（acceptance criteria）分得很 開：AC 寫在那張單凍結的 assertion 裡，DoD 寫在這裡。一張單可以通過全部 AC 卻沒有 done—— assertion 全綠但改動還躺在預設分支上、沒有任何人看得到它，就是那個情況。

所以這幾條不要抄進任何一張單的凍結區。抄進去等於每張單都重簽一次同樣幾行不承載新資訊的 東西，而漏抄的那一張就靜默地少了一條完成條件。

五條

1. 改動住在一條 branch 上，不躺在預設分支。 開的時機是「判定要立案之後、動手之前」—— 一個還沒開工的成功定義直接躺在預設分支上，等於它已經是既成事實。

   那條 branch 是自己建的。 改動只推到自己建的 branch。別人建的、或有別人的 PR 在用的 branch，任何情況都不推——推不推得動、用不用 force 都一樣。要在別人還沒併的 branch 之上 做事，從它切一條自己的，PR 的 base 指向它。

   所以別人的 branch 推不動的時候，那不是要解決的問題。 它從一開始就不是推的對象， 沒有「換個方法推上去」這一題。2026-09-10 的實例：一顆 PR 的 base 是同事還沒併的 branch，遠端規則讓兩條都推不動，討論裡出現了「那條也一樣推不動」——那條本來就不是我們 會去推的東西。

2. 有一個 PR。 PR 開出來就是實作完成：它是那份改動變成可被別人看見、可被判定的 東西的那一刻。沒有 PR 的改動不管本機多綠都還沒 done。

   開之前，在改動落下去的那棵樹上跑過 check-your-own-work，它列出的每一項都處置完。 這是這一條的一部分，不是開完之後的選配：review 抓到的問題，多半是作者自己對一次就看得到 的那幾類。2026-09-17～10-01 兩週裡，有人 review 的 PR 只有一半一次過，被抓到的五類問題 有四類那支 skill 本來就在問，而開 PR 的那些 session 幾乎沒有一個跑過它。怎麼跑、為什麼要 指名那棵樹，在〈開 PR〉。

   一個功能跨好幾個 repo 的時候，只做了一半的那顆 PR 開 draft，描述寫出它依賴哪一顆。 單獨看它是綠的，併進去卻不成立；全部做完、端到端在本機量過真值，才轉成可以 review。 2026-09-24 的標本：讀取那一端的 PR 回了一個新欄位，寫入那一端還沒把它寫進索引，前者單獨 上線之後那個欄位全部是 null。

3. 判定過才進預設分支。 進去的路徑是那個 PR，不是直接推。

   這一條有東西在守（DP-865）：scripts/check-ship-point.sh 在併 PR、建或推 release tag、送 部署請求之前，問那個動作對到的本地單判過了沒——站別要是 delivered，併的時候 head 還要是 交付紀錄記的那一個。對不到任何本地單的不擋：別人的 PR、別人的發佈不是這一條管的。開 PR 不擋，PR 開出來是實作完成，判定在它之後。任何 agent 都能從命令列叫它；Claude Code 的 .claude/hooks/gate-ship-point.sh 只是轉呼叫它。

4. push 之前，本機跑完跑得動的驗證。 type check、lint、單元測試、受影響路徑的冒煙。 把 CI 當第一道防線等於把 reviewer 當驗證工具。

5. reviewer 提的每一條，處置回到那條意見上。 不是「有沒有處理」——是提出者拿不拿 得到那個處置。他看的是他留言的地方，回在別處他收不到。

   處置有四種：照做、回覆說明為什麼不照做、拒絕、另外開單。照做不是預設。「處置」這個 字是中性的，而它常被讀成「照做」。一條意見可以是對的、而仍然不該在這一輪做；也可以是 這個 repo 根本不做那件事。讀成「照做」的話，這一條會把每一則意見都變成一次施工。

   每一串都算，nit 也算。 「妥善處理」的量法是：每一串的最後一則是作者，而且那一則說出了 四種處置裡的哪一種。標成 nit 的意見只是提出者在說「這條不擋你」，不是在說「這條不用回」。

   回覆承認對方說得對、卻沒有改，不算四種處置的任何一種。 那是第五種，而它讀起來像照做。 回覆與 merge 之間也要留給提出者重看的機會，不在同一分鐘內回完就合併。