重構需要記錄哪些文件？

重構過程已經產生功能範圍、分析結果、架構決策、遷移規則、測試結果、版本、部署與監控資料。最後的文件工作不需要把這些內容重新抄成一份總報告，而要建立可以找到正確來源、判斷適用版本並隨變更更新的文件集合。

文件要協助讀者完成工作。只有名稱齊全但無法照著建立環境、判斷設計、執行切換或處理故障的內容，仍不足以支援後續維護。

先從讀者要完成的工作開始

每份文件都要先確認讀者與使用情境。同一項內容可以服務多個角色，不需要因此複製成多份彼此容易失去同步的文件。

文件詳細程度要由錯誤理解的影響決定。常用且容易透過指令驗證的內容可以保持簡短，高風險且跨多項責任的切換與復原程序則需要完整前提、步驟、判斷與結果。

建立文件索引與責任資料

文件數量增加後，需要一個索引說明每項內容的權威來源與維護方式。索引不必複製正文，至少要記錄下列欄位：

「內容負責人」表示誰能確認與維護文件，不代表由一個人撰寫所有內容。責任轉移時要更新索引與存取方式，避免文件仍指向已無法處理問題的人員。

讓專案說明文件成為入口

專案說明文件（README）適合提供第一次接觸專案時需要的最短路徑。GitHub 的 README 說明列出的常見內容包含專案用途、開始方式、求助位置與維護者資訊。

本系列的 README 可以包含：

• 說明目標系統用途、替換範圍與目前狀態。
• 列出目錄結構、主要組成項目與文件索引入口。
• 記錄必要工具、支援版本與從乾淨狀態建立環境的步驟。
• 提供建置、測試、啟動及最小驗證的共同指令。
• 說明設定欄位的準備方式，但不放入實際敏感內容。
• 指向功能規格、架構、遷移、發布與維運等詳細文件。
• 記錄問題回報、文件修正與責任確認方式。

README 應該保持可快速閱讀。需要多種情境、完整參數或故障處理的內容應該放在專用文件，再由 README 提供明確連結。

保存需求、範圍與驗收條件

需求文件要說明目標系統準備完成甚麼結果，並保留遺留系統與目標系統之間的核准差異。至少包含：

• 記錄重構目標、納入範圍、範圍外項目與完成條件。
• 區分保留、調整、捨棄與新增功能，並連回決定與驗收方式。
• 保存功能規格中的輸入、前置狀態、規則、輸出、狀態變化與例外情境。
• 記錄非功能需求的限制值、量測條件與通過門檻。
• 保存尚未確認事項、負責人、確認方式與影響範圍。
• 讓需求或風險識別碼連回實作、測試與結果紀錄。

需求改變時，要先更新差異與驗收條件，再調整程式與測試。只修改目前預期結果，卻刪除原本決定與原因，會讓後續人員無法判斷變更是否經過確認。

用架構文件描述邊界與責任

架構文件要回答系統包含哪些重要組成項目、各自負責甚麼、如何互動，以及哪些項目位於系統範圍外。圖表與文字應該互相補充，不需要用多張圖重複相同關係。

可以按照需要保存：

• 系統環境圖記錄觸發來源、資料來源、輸出對象與外部相依。
• 架構圖記錄主要組成項目、責任、相依方向與共用狀態。
• 功能流程或循序圖記錄關鍵操作的處理順序、條件與失敗路徑。
• 資料流向圖記錄資料進入、轉換、保存、傳出與刪除位置。
• 部署圖記錄成品如何放入已確認的執行環境，以及必要相依關係。

C4 模型（C4 Model）提供由系統環境、容器、元件到程式碼的分層視角，但不要求所有層級都必須繪製。C4 模型中的容器（Container）表示應用程式或資料儲存區，與部署技術中的容器具有不同語意。選擇任何表示方式時，圖表都要標示範圍、元素責任、關係方向、交換內容與圖例，並保存可以修改的來源檔案。

圖表不應該固定到每個類別與函式。這類細節容易隨實作變動，也通常能由程式與工具即時取得。長期文件應該保留會影響理解與變更判斷的穩定邊界。

用架構決策紀錄保存選擇脈絡

架構決策紀錄（Architecture Decision Record, ADR）要保存一項重要設計決定在當時限制下如何形成。內容至少包含問題、適用範圍、候選方案、判斷資料、最終選擇、影響與重新評估條件。

新決定取代既有決定時，應該新增一筆 ADR，標示被取代與取代關係。直接改寫原紀錄會失去當時脈絡，也無法解釋舊版本為甚麼採用不同設計。文字錯誤可以修正，但決策內容的改變要保留歷程。

ADR 只保存需要長期理解的決定。一般程式修改、容易復原的局部選擇或已由明確規範決定的內容，可以留在提交、審查或規範紀錄中，避免決策集合充滿無法使用的細節。

管理資料與互動契約

資料文件要保存名稱、格式、語意、來源、限制與生命週期，不能只列出型別。如果系統使用資料庫，可以建立資料字典（Data Dictionary）記錄資料表、欄位、關係、限制與敏感程度。如果使用檔案、訊息或其他保存方式，也要提供對應的結構描述與欄位意義。

至少要涵蓋：

• 記錄每個欄位的名稱、型別、單位、允許值、空值語意與範例。
• 說明識別內容、關聯、唯一性、順序與版本規則。
• 標示敏感程度、保存期限、可查閱範圍與刪除方式。
• 記錄來源與目標的對應、轉換、例外與驗證條件。
• 說明相容變更、淘汰程序與同時支援的版本。
• 連結產生或驗證結構的 Schema、程式與測試。

如果系統確實提供 HTTP 應用程式介面（Application Programming Interface, API），可以使用 OpenAPI Specification描述路徑、輸入、輸出與錯誤契約。其他互動方式則選擇符合檔案、命令、訊息或函式介面的格式。規格檔案可以產生說明頁面，但產生成功不能取代契約測試與語意審查。

保存測試與驗收的重現條件

只保留一份「全部通過」報告，無法重現當時的判斷。測試文件要連結需求、案例、版本、環境與實際結果：

• 保存測試策略、測試層級、責任範圍與阻擋條件。
• 保存重要案例的初始狀態、輸入、預期結果與清除方式。
• 記錄測試程式、資料、工具、目標成品與執行環境版本。
• 保存遺留系統與目標系統的比較結果及核准差異。
• 保存資料遷移、安全、效能、復原與部署後檢查等專項結果。
• 記錄失敗分類、處理決定與使用相同條件重新驗證的結果。

大量自動化輸出可以由流程保存，不需要逐筆貼入人工文件。長期文件應該記錄取得方式、保存期限、摘要結果與對應版本，並確保重要失敗不會因執行紀錄到期而失去必要資訊。

連結版本、發布、部署與切換紀錄

發布與部署文件要讓維護人員找到「部署了甚麼、如何部署、如何確認，以及失敗時如何處理」。至少要保存：

• 版本規則、發布標籤、變更紀錄與已知限制。
• 原始碼提交、建置流程、成品摘要、測試結果與部署紀錄的追溯關係。
• 部署環境限制、設定版本、部署順序、核准與存取範圍。
• 健康檢查、冒煙測試、觀察門檻、停止條件與復原方式。
• 遷移批次、來源與目標範圍、錯誤紀錄、驗證結果及重跑條件。
• 正式切換的停止寫入、最後同步、驗收、切換與既有系統保留期間。
• 既有系統退場前的備份、查詢需求、停止條件與完成確認。

程序中的每一步都要說明前置條件、操作、預期結果與失敗處理。只有指令而沒有判斷條件，操作人員仍無法知道何時可以繼續或必須停止。

建立可以執行的維運手冊

維運手冊（Runbook）用來處理可辨識且可能再次發生的事件。每個項目應該從告警或現象開始，提供受控且可以驗證的處理流程。

一份維運手冊可以包含：

• 記錄適用服務、環境、版本與觸發告警。
• 說明影響判斷、必要儀表板、記錄查詢與關聯識別方式。
• 提供可以立即執行的隔離、降級、停止或復原步驟。
• 為每一步記錄成功結果、失敗分支與停止條件。
• 指定通知、核准、問題升級與其他責任交接方式。
• 說明恢復後的功能、資料與告警結束確認。
• 記錄需要建立後續問題、補充分析或更新監控的條件。

維運手冊要透過演練與實際事件持續修正。只在事故期間臨時輸入的命令容易遺漏前提，也可能無法在下一個版本使用。確認有效後，應該將必要步驟轉成共同指令或受控自動化，再保留操作入口與判斷方式。

分開程式註解與系統文件

程式註解適合說明程式附近無法直接表達的原因、限制、相容處理與公開契約。跨組成項目、跨環境或需要多個角色共同理解的內容，則應該放在可搜尋的系統文件。

兩者之間應該使用穩定識別與連結建立關係。例如，相容程式旁的註解可以引用 ADR、需求或風險識別碼，系統文件則連回負責實作與測試。不要把完整設計複製進註解，也不要只在外部文件記錄會直接影響函式正確使用的輸入與錯誤契約。

區分人工維護與自動產生內容

同一項資訊只應該有一個權威來源。可以從程式或 Schema 可靠取得的內容，優先由工具產生，再由人工文件補充目的、語意與限制。

產生流程也要保存工具與規格版本，並在來源變更時重新產生。人工直接修改產生結果會在下次執行時消失，應該修改權威來源或把補充內容放在明確的擴充位置。

使用文件即程式碼維護內容

文件即程式碼（Docs as Code）將可文字化的文件、圖表來源與設定放入版本控制，並沿用變更審查與自動檢查流程。這可以讓文件與相關程式在同一項修改中更新，也能保留歷程與版本差異。

文件變更流程可以包含：

1. 依照更新條件找出受影響文件與圖表來源。
2. 在同一項變更中修改程式、測試、Schema 與必要說明。
3. 執行格式、連結、結構描述、範例與產生結果檢查。
4. 由能確認技術內容與使用方式的人員審查。
5. 發布或部署後，按照實際結果更新版本、限制與維運資訊。
6. 將被取代內容標示狀態、替代位置與適用的最後版本。

不適合文字版本控制的檔案仍要保存可修改來源、輸出格式與產生方式。圖表只保存圖片而沒有來源時，後續修改只能重畫，也無法可靠比較差異。

驗證文件能否真的使用

文件檢查不能只確認文字存在。應該按照使用情境驗證：

• 從乾淨狀態按照 README 建立環境、建置、測試及啟動。
• 由未參與原修改的人員按照部署或遷移程序完成一次演練。
• 從目前部署版本追溯到成品、來源提交、測試與變更紀錄。
• 從告警進入維運手冊，完成查詢、處置、恢復與結果確認。
• 對照圖表、契約與實際程式，確認名稱、方向與欄位一致。
• 執行文件中的指令與小型範例，確認輸出符合敘述。
• 檢查連結、錨點、產生檔案、敏感內容與已失效標記。

文件可以設定重新確認條件，例如介面版本變更、部署方式改變、維運手冊長期未演練或實際事件顯示步驟失效。固定日期審查可以補充保護，不能取代由內容變更觸發的更新。

封存被取代的文件並保留歷程

過期文件如果仍會被搜尋到，就要清楚標示狀態、最後適用版本與替代位置。被取代的 ADR、發布紀錄、遷移結果與事件處理紀錄通常需要保留，因為它們能解釋過去版本。單純重複、錯誤或已無參考價值的操作說明，則可以在確認沒有必要連結後移除。

封存時要同步更新文件索引與入口，避免 README 或維運手冊繼續連到過期內容。正式切換完成後，也要區分目標系統現行文件、遺留系統唯讀參考與依法或依需求保存的歷史紀錄。

防止敏感內容進入文件

文件可以說明設定與秘密管理流程，但不得保存密碼、權杖、私鑰、實際憑證、連線內容或其他可直接取得敏感資料的值。

• 只記錄設定名稱、用途、格式、取得責任與更新方式。
• 範例使用明確的假值，且不能與正式格式混淆。
• 自動化輸出、畫面擷取與故障記錄在保存前要遮蔽敏感內容。
• 文件存取範圍要按照內容敏感程度設定，不能假設版本庫一定適合所有資料。
• 發現敏感內容進入歷史紀錄時，要按照事件處理程序撤銷、替換並清理可移除副本。

安全風險、已知限制與處理方式可以被記錄，實際可用的秘密內容則要留在專用管理機制。

完成文件治理的檢查

• 每份文件是否具有讀者、用途、適用版本、負責人與更新條件？
• README 是否提供建立環境、執行共同指令與找到詳細文件的最短路徑？
• 需求、範圍、核准差異與驗收條件是否能連回實作及測試？
• 架構圖是否說明範圍、責任、相依方向與交換內容，並保存可修改來源？
• ADR 是否保留候選方案、判斷資料、影響與取代關係？
• 資料與互動契約是否記錄語意、限制、版本與相容方式？
• 測試、遷移、效能與驗收結果是否具有可重現的版本及環境資訊？
• 發布、成品、部署、設定、切換與復原紀錄是否可以互相追溯？
• 維運手冊是否能從告警開始，完成確認、處置、恢復與結果驗證？
• 自動產生內容是否具有明確權威來源與重新產生方式？
• 文件是否納入變更審查與適合的自動檢查？
• 被取代內容是否標示狀態、最後適用版本與替代位置？
• 文件、範例與執行輸出是否未包含實際敏感內容？
• 重要文件是否已由實際讀者按照使用情境完成驗證？

重點整理

• 重構文件要形成可搜尋、可追溯且能持續驗證的集合。
• 需求、架構、契約、測試、版本、部署、維運與退場紀錄各自保留權威來源，再由 README 與文件索引提供入口。
• 文件應該跟隨相關變更更新，保留決策與歷史版本，並透過共同流程、實際演練與敏感內容檢查維持可用性。