一個人做前端，也要寫給下一個人看的文件
九月我把做了大半年的 EMS 前端交接給新同事。交接能順利，靠的不是最後一週惡補，而是從一個人做 Starter Kit 的時候就持續留下的東西：README、資料夾結構說明、架構圖、決策紀錄、Commit 規範、任務紀錄。這篇整理一個專案該留下哪些文件、各自是寫給誰看的，還有實際交接時怎麼用它們。
目錄
九月，我把做了大半年的 EMS 前端交接給新同事，自己轉去做其他專案。交接的過程比想像中順，回頭看，原因不是最後一週惡補了什麼，而是這個專案從一開始就有在留文件，而一開始的時候，前端其實只有我一個人。
一個人的時候為什麼要寫
2024 年底我在收尾前一個專案，順便把架構整理成 Starter Kit 給後續專案用。那時候沒有其他前端同事，但我還是持續更新專案 Wiki 上的資料夾結構文件。
理由很簡單，文件的讀者不是現在的我，是下一個人，可能是幾個月後加入的同事、接手專案的人，也可能是半年後已經忘記細節的自己。
而且一個人的時候寫文件最便宜。所有決定都在腦袋裡還熱著，寫下來只要幾分鐘。等到要交接才回想「當初為什麼這樣做」，就得翻 Git 歷史慢慢拼。
一個專案該留下哪些文件
以我們的專案為例，這些東西都放在 Repo 裡，跟程式碼一起版本控制，不另外放在別的地方。
1. README：怎麼把它跑起來
第一份文件永遠是「怎麼跑起來」，需要哪些工具、安裝步驟、環境變數的範例檔、常用指令。新同事第一天只要照著做就能看到畫面，不用先找人問。環境變數一律給範例檔（env-example），真正的值不進 Repo。
2. 資料夾結構說明：東西放在哪裡、為什麼
我們用的是 Feature-based 的結構，每個功能的 API、型別、元件、狀態都集中在 features/ 底下自己的資料夾，共用的放 components/ 跟 lib/。
這份說明我在 2024 年底就寫過一篇，Wiki 上的版本會隨著專案調整持續更新，例如後來為什麼沒有 API Routes、後來又為什麼加回來了哪幾條。
3. 架構圖：系統的邊界跟服務之間的關係
前端不是孤島。它呼叫哪個服務、登入怎麼走、即時資料從哪裡來，這些畫成圖比寫成字清楚。
專案的架構文件是同事整理的，用 C4 model 的前兩層（系統脈絡、容器）跟 arc42 的章節骨架。我自己沒有畫過這些圖，但交接時第一個翻的就是它，前端在整個系統裡的位置一眼就看得出來。
4. 決策紀錄：為什麼是這樣而不是那樣
這是最常被省略、交接時卻最常被問到的東西。「為什麼用這套元件庫」「為什麼 Mock 資料放在 API 函式裡」「為什麼那層 API Routes 被拿掉了」，每一個都是當時花了時間討論出來的結論。
用一小段文字記下背景、選項、決定、後果就夠了，形式上可以參考 ADR。沒有這份文件，下一個人很容易把當初刻意不做的事又做回來。
5. Commit 規範跟 CHANGELOG：讓歷史讀得懂
專案用 commitlint 強制 Conventional Commits 的格式，type 固定一份清單（Feat、Fix、Refactor、Docs、Test…），scope 寫模組名稱。
好處在交接時特別明顯，新同事翻歷史就能看出某個功能是哪幾次提交組成的，出問題時也能快速縮小範圍。Release 的時候再從這些提交產生 CHANGELOG，不用另外手寫。
6. 任務紀錄：每件事做了什麼、怎麼驗證
每個任務一份 Markdown，檔名帶時間戳跟主題，內容記需求、做法、改了哪些檔案、怎麼驗證。它比 Commit 訊息長、比設計文件短，剛好是交接時最好用的顆粒度。新同事要接手某個模組，先讀那個模組的任務紀錄，就知道它經歷過什麼。
7. 交接清單：現在進行中的事
最後是交接當下才寫的一份，寫進行中的任務、已知但還沒修的問題、各個外部系統的聯絡窗口（寫角色不寫名字），還有「這些地方我本來打算改但沒改」。這份清單的壽命很短，但它是把前面六份文件串起來的入口。
實際交接時怎麼用
有了這些東西，交接就不是把腦袋倒給對方，而是帶著對方走一遍。先看架構圖跟資料夾結構，建立整體的地圖。接著挑兩三個典型的 feature 一起讀，從 API 函式、型別、元件到頁面，看一條完整的路徑。
然後一起做一兩個小任務，把 Commit、PR、測試這些規範實際跑一遍。最後留一份 Q&A 文件，交接期間問到的問題都記進去，之後再補回對應的文件。
我在交接之後就轉去做新的專案了，EMS 後續的更新跟維護都由接手的同事負責，中間沒有因為「只有原作者知道」而卡住過。
回顧
寫文件這件事，我覺得重點只有兩個。一個是時機，一個人做的時候就開始寫，因為那是成本最低的時候，而且要放在 Repo 裡跟程式碼一起版本控制、一起 Review，才不會過期。README、結構說明、決策紀錄都是幾段文字而已，隨著變更一起改，不要等「有空」。
另一個是內容，程式碼已經說明了「是什麼」，文件要補的是當時的「為什麼」。
至於交接，就是帶著對方走一遍，而不是把腦袋倒出來。地圖、路徑、一起做、留 Q&A，大概就這樣。