在 AI 時代來臨之前，我曾為重大的程式碼變更撰寫相當長的提交描述（或稱提交內文）。草擬並重新閱讀這些描述，確保沒有遺漏任何重要資訊，大約需要五到十分鐘。我這麼做有幾個原因。
我希望包含所有有用的資訊，這樣讀者就不必在多個地方尋找。我希望解釋「是什麼」，更重要的是，「為什麼」。
「是什麼」總結了變更，通常不言自明，但它為解釋「為什麼」提供了起點。
有時，我會以第一人稱撰寫，就像在草擬給某人的訊息：「我這樣做是因為……」、「我暫時這樣做，直到我們……」等等。然後我會進一步解釋原因，這樣其他人，尤其是未來的我，就能更容易理解我們為何做出這個變更。
這是一個很好的練習。它不僅僅是撰寫提交訊息和描述。寫作過程本身幫助我反思我寫的程式碼。我會重讀程式碼並總結變更。在這個過程中，我傾向於重新評估決策，有時這會導致不同的或更好的變更。
現在我們進入了代理編碼（agentic coding）的時代，從程式碼到提交描述的一切都由 AI 編寫。關於我們是否應該閱讀 AI 編寫的程式碼，以及在可讀性方面有多困難，存在著巨大的爭論。我發現困難的部分是閱讀和理解 AI 編寫的提交描述。
代理可以為它們所做的變更編寫提交訊息。但它們可能沒有散佈在不同通訊和專案管理工具中的完整脈絡。其中一些可能還是離線的。當 AI 不知道「為什麼」時，它會提出自己的理由。我認為這很危險。當我們以後閱讀時，可能無法理解，因為真正的原因完全不同。
一個顯而易見的解決方案是透過聊天或工具，為代理提供它所需的所有脈絡。這有助於解決捏造理由的問題。代理現在可以清楚地解釋「為什麼」。
但這並沒有解決另一個問題。擁有正確脈絡的代理會寫出令人信服的提交訊息。但只有我能驗證程式碼是否如描述所示。所以，這是我做的一件事：
自己撰寫提交訊息和描述。
自己撰寫提交描述有助於我反思 AI 所做的變更。這也是一種檢查一切是否如預期的方式。如果我無法解釋「為什麼」，那麼我就是在發佈我不理解的東西，如果將來出現問題，將很難解釋或修復。這又回到了那句老話：如果你無法解釋它，你就沒有理解它。提交描述在這裡再次作為一個思考工具。
有些部分，例如「我暫時這樣做，直到我們……」，是帶有退出標準的臨時決策。我們有時會設定退出條件，而 AI 無法從程式碼或其他工具中推斷出來，因為它們通常沒有被寫下來，因為它們似乎太明顯而無需提及。但撰寫提交訊息迫使我完成這個句子，並幫助未來的讀者決定是否保留這個變更。
代理可以編寫程式碼和描述。但撰寫「為什麼」的地方，你才能發現你是否理解你正在發佈的內容。