文件同步
程式碼與其文件應在同一提交中一起變更。錯誤的文件比沒有文件更糟。
文件出錯的三種方式
- 過時。 文件仍描述舊的行為、名稱或指令。
- 遺漏。 新的行為、指令或設定沒有對應文件。
- 重複。 同一件事出現在兩處，後來其中一處修改而另一處沒有。
步驟
- 查看改動內容。
git diff --cached --stat git diff --stat - 找出專案自有規則。 閱讀
CLAUDE.md、CONTRIBUTING.md和docs/README.md。如果它們說明了哪份文件負責哪個主題，就遵循這些規則。這些規則優先於步驟 3。 - 將每個改動歸檔到對應的文件。 使用
resources/doc-routing.md。一件事只屬於一個文件，其他文件則連結到它。 - 尋找過時的參考。 針對每個重新命名或移除的名稱（函式、旗標、端點、設定、檔案路徑、指令）：
git grep -n '<舊名稱>' - 編輯。 僅改動程式碼變更所導致的不正確或不完整之處。不要改寫無關的段落。如需清晰的措辭，若已安裝
simple-english技能則可使用它。 - 一起提交。 將文件變更與程式碼一同放入暫存區。不要將它們放在後續的 PR 中。
- 報告。 列出你修改過的文件。如果無需改動，用一行說明原因。例如：「無需文件：內部重構，行為、指令或設定均無變更。」
當歸屬不明確時
請詢問使用者。不要為了迴避問題而建立新文件。
一個有用的判斷：它是關於當前狀態的事實（設定、版本、狀態）嗎？如果是，放入參考文件或狀態文件。它是程序（步驟）嗎？如果是，放入擁有該程序的操作指南、操作手冊或技能中。
規格優先
如果倉庫中有 SPEC.md（參見 engineering:spec-writing）或 .gener8v/specifications/ 下的 gener8v 規格檔，它們定義了預期的行為。
- 若你的變更符合規格所述，則規格無需編輯。
- 若你的變更與規格矛盾，請停止。告知使用者。先透過該規格的負責人修改規格：
engineering:spec-writing負責SPEC.md，gener8v:specification負責管線規格。不要為了符合程式碼而默默地修改規格。
管線文件
請勿手動編輯 .gener8v/ 下的檔案。gener8v 管線技能會撰寫並更新它們。
相關技能
engineering:documentation-bootstrap：當整份文件缺失，而不僅僅是一個段落時使用。engineering:github-pr-merge：在 PR 合併前執行此檢查。engineering:github-release：讀取此技能持續維護的 CHANGELOGUnreleased區段。