Day 19：事實查證與撰寫的分工邊界 結尾留下一句明確的期待。架構、查證、程式碼正確性、跨篇狀態記憶、長篇論證的緊密度、與查核工作的邊界，這幾件事到今天都已經各自有了具體的答案。
是時候把這些機制放在一起，完整跑一次寫作代理人依規格產出完整初稿的流程了。
今天要做的事很單純，親自跑一次完整的實戰流程，把 Day 14：寫作代理人的架構設計，從規格到草稿 到 Day 19：事實查證與撰寫的分工邊界 這六天建立的機制放在同一次產出裡，看它們如何協同運作。這是階段四寫作代理人開發七天的收尾驗收，任務性質與 Day 19 之前每一天單獨定案一個機制不同，今天不再新增任何一項機制，而是驗證這六項機制合起來，是不是真的能跑出一篇通順、可信、有跨篇一致性的初稿。
呈現方式延續 Day 13：實戰，讓規劃代理人產出一套完整的系列大綱 已經使用過的示意主題，Git 版本控制入門系列，挑選其中一則段落規格，具體走一遍寫作代理人的產出過程。
這裡要先講清楚一件容易被誤解的事，今天六個機制不是全部依固定順序線性發生。
逐段展開架構是骨架，是其餘機制運作的共同容器，全域錨點檔案延伸使用是貼著撰寫節奏走的常態動作，剩下三個，ReAct 模式、程式碼正確性兩道防線、論證步驟拆解，都是視這一段內容性質而定的條件觸發，不是逢段必發。這個差異，正是今天與 Day 13 七個環節單純線性依序執行最大的不同之處。
先簡短回顧一次。Day 13 選定的示意主題是 Git 版本控制入門系列，給完全沒有寫過程式、沒用過版本控制的讀者看的實用系列，預計五天。今天延續同一個示意脈絡，不重新虛構一個與 Day 13 無關的新主題。這裡要再次明確標註，今天走的這則段落規格是示意用途，用來展示寫作代理人的產出流程長什麼樣子，不是系列作者真正拿去用的產出結果。
這次挑選的段落規格，主題是 commit 粒度如何影響回溯與除錯效率。
> [!NOTE] 這份文件是什麼
> 這是 [[Day 13：實戰，讓規劃代理人產出一套完整的系列大綱]] 裡規劃代理人實際交出的成品，Git 版本控制入門示意系列第三天的 Section Spec。這是五天裡技術參數最重的一篇，銜接第二天已經示範過的完整存檔手續，這一天要回答存檔這件事做得好或不好，差別到底在哪裡。
# 一次存檔該記多少事，commit 粒度如何影響回溯效率
**系列**：Git 版本控制入門系列文章，共五天，給完全沒有寫過程式、沒用過版本控制的讀者看的實用系列
**本篇順序**：第 3 天
## 核心目標
讓讀者理解 commit 粒度這個概念，一次 commit 涵蓋的改動範圍大小，會直接決定未來回溯或除錯時的效率，粒度太粗會讓回溯變得又慢又痛苦，粒度太細又會讓歷史記錄變得瑣碎難讀。
讀完這篇，讀者應該能判斷自己手上正在做的這次改動，該切成一次 commit 還是該拆成幾次，並且知道一句好的 commit 訊息標題該長什麼樣子。
## 前置概念
本篇可以直接假設讀者已經懂 commit、repository 這兩個名詞，也已經走過工作區、暫存區、commit 三者的完整操作手續，這是第二天已經定案的內容，不需要重新示範指令，也不需要重新解釋暫存區的作用，直接沿用。
本篇會新增兩個量化的經驗法則，這是本篇第一次出現，需要完整定義並在段落規格裡示範因果推導過程。
## 段落規格
**第一段，昨天存了一次檔，但如果那次改動牽涉十個檔案呢**
承接第二天結尾伏筆，昨天示範的是單純情境，只改了一兩個檔案。這一段要拋出一個假設情境，如果同一次改動牽涉的檔案數量變多、變雜，例如同時調整了排版、修正了錯字、又順手改了一段完全不相關的內容，全部塞進同一次 commit，未來回頭找問題的時候會發生什麼事。這一段先讓讀者感受到問題，還不給答案。
**第二段，正式定義 commit 粒度**
把第一段的情境抽象成一個正式概念，commit 粒度指的是一次 commit 涵蓋的改動範圍大小，範圍太大稱為粒度太粗，範圍太小、太瑣碎則稱為粒度太細。這一段要說明粒度太粗的具體代價，如果未來發現某個功能出了問題，想回頭找出是哪一次修改造成的，一次 commit 裡混了十個不相關的檔案，等於要把這十個檔案的改動全部當作嫌疑對象，逐一排查，回溯效率因此大幅下降。
**第三段，一個具體的經驗法則，數字與因果推導**
這一段是本篇的核心，要提出一個可量化的經驗法則，並示範完整的因果推導。經驗法則本身，單次 commit 涵蓋的檔案數，建議不超過五個，commit 訊息標題建議不超過五十個字元。因果推導要這樣鋪陳，如果單次改動涵蓋的檔案數愈多，代表這次改動同時處理了愈多不相關的目的，回頭排查時需要逐一檢視的範圍就愈大，回溯效率隨檔案數增加而下降；反過來，如果一句 commit 訊息標題必須壓在五十字元以內還能講清楚這次改了什麼，這件事本身會反過來逼著你在動手改之前，先想清楚這次改動的目的到底是不是單一的，講不清楚往往就是粒度太粗的徵兆。這段推導要讓讀者看到，數字不是憑空訂出來的門檻，而是從「回溯效率」這個目標倒推出來的合理限制。
**第四段，粒度太細也不是好事**
補上另一個極端，避免讀者誤以為愈細愈好。如果每改一個字就存一次檔，歷史記錄會變得極度瑣碎，未來想理解某個功能是怎麼一步步完成的，反而要翻閱大量瑣碎的記錄才能拼出全貌，這是另一種形式的回溯效率下降。這一段要讓讀者理解，粒度的目標不是愈細愈好或愈粗愈好，而是每一次 commit 都對應到一個「單一、講得清楚的目的」。
**第五段，收尾，把粒度原則落成一句可操作的判斷方式**
收尾，給讀者一個簡單可操作的自問方式，動手改之前先問自己，這次改動能不能用一句五十字元以內的話講清楚在做什麼，如果講不清楚，代表這次改動裡藏著不只一個目的，該考慮拆成幾次 commit。埋下伏筆，粒度掌握好了，接下來如果同時有多條工作要並行進行，例如一邊修一個小問題、一邊開發新功能，要怎麼讓這些工作互不干擾，這件事留給明天處理。
## 結尾伏筆
今天讀者學會了 commit 粒度這個判斷標準，單次改動涵蓋的檔案數不超過五個、commit 訊息標題不超過五十字元，這兩個數字背後的因果邏輯是，範圍愈大愈難回溯，講不清楚就是粒度太粗的徵兆。但今天談的都是一個人單獨工作時怎麼存檔存得好。如果同時有多條工作要並行進行，會不會彼此打架，這件事還沒碰過，明天要正式進入分支的世界。
---
> [!TIP] 給寫作代理人的補充
> - 本篇是系列裡技術參數最重的一天，兩個數字，單次改動檔案數不超過五個、commit 訊息標題不超過五十字元，務必完整寫出因果推導的鋪陳過程，不要只丟出數字本身，讀者需要看到「為什麼是這個數字」的邏輯，不是背下一條規則。
> - 這兩個數字是經驗法則，不是 Git 本身的技術限制，撰寫時要避免讓讀者誤以為 Git 有強制要求，措辭上宜用「建議」「經驗上」這類字眼。
> - commit 的存檔點比喻與 repository 的定義都不需要重新鋪陳，直接沿用第一天的版本。
---
> [!NOTE] 本篇新增定案內容
> 本篇第一次定義了兩個量化經驗法則，單次 commit 涵蓋的檔案數建議不超過五個，commit 訊息標題建議不超過五十字元，這兩項需回寫進全域錨點檔案，供後續天數沿用查閱。
規格要求這一段同時交代一個可量化的參數，也就是單次 commit 建議涵蓋的檔案數量或改動範圍，以及一段從參數觀察推導到 commit 建議的簡短因果論證，commit 太大會發生什麼、commit 太細碎又會發生什麼、讀者該怎麼依專案情境調整。
挑這則規格不是隨意決定，它同時涉及技術性參數、可能需要查證的量化依據、以及一段邏輯層次不算淺的因果推導，剛好能讓後續 ReAct 查詢、執行驗證、論證步驟拆解三個條件觸發機制，都有機會在同一次示範裡被具體點名判斷是否觸發。
寫作代理人拿到這則段落規格時，並非從零開始。它延續 Day 14 定案的架構，只針對這一段要求的重點與前提展開內容，不需要重新理解整份規格書、也不需要預先設想後面幾段要寫什麼。
寫作代理人讀取這則段落規格，確認這一段要求的重點是 commit 粒度與回溯效率、除錯效率之間的關係，前提是讀者完全沒有寫過程式、沒用過版本控制，語氣不能預設任何背景知識。
> [!NOTE] 這份文件是什麼
> 這是 [[Day 13：實戰，讓規劃代理人產出一套完整的系列大綱]] 環節三提到的既有依據，規劃代理人在規劃每一天內容之前，會拿出這份風格指南與受眾畫像來套用，判斷語氣基調、句式偏好、用詞習慣該怎麼設定。格式比照 [[Day 10：定義文章的風格指南與目標受眾畫像]] 定義的兩份文件應包含的要素，內容是 Git 版本控制入門示意系列專屬的版本，不是抽象通用模板。這份文件在系列規劃初期一次性確立，供五天共用查閱。
# 目標受眾畫像
## 讀者的背景知識水位
完全沒有寫過程式、完全沒有用過任何版本控制工具。讀者可能是文字工作者、行政人員，或者剛開始想自學程式、卻卡在跟別人合作時的檔案管理問題上，才第一次聽到 Git 這個名字。
讀者不具備任何指令列操作經驗，這件事必須被完整考慮進去，系列裡第一次出現任何指令，都要附上可以直接照打的範例，不能假設讀者知道怎麼開啟終端機或知道指令列是什麼。
## 讀者的痛點與動機
讀者的痛點通常很具體，多人或多版本同時修改同一份檔案時，曾經遇過覆蓋、遺失、對不出誰改了什麼的經驗，或者聽同事、朋友提過 Git，但每次想學都被一大堆陌生指令與術語擋在門外，學到一半就放棄。
讀者的動機不是想成為工程師，而是想解決眼前這個具體的合作與版本管理問題。這決定了系列不該往「程式開發最佳實務」這個方向延伸，該緊扣在「檔案版本管理」這個最貼近讀者需求的範圍裡。
## 讀者的閱讀情境
讀者比較可能是坐下來願意跟著操作，而不是通勤時快速瀏覽。這決定了系列可以保留完整的指令範例與操作步驟，不需要為了適應碎片閱讀而過度精簡步驟，但每篇仍要維持在讀者一次坐下來就能讀完並跟著操作一遍的長度。
# 風格指南
## 語氣基調
採用直接了當的口語對話口吻，像是一個有經驗的朋友坐在旁邊，一步一步帶你操作，不是正式的技術文件口吻。避免任何生硬的制式套話，例如「總而言之」「值得注意的是」這類詞，改用直白的陳述銜接。
## 句式偏好
偏好短句，直接下結論，再用具體情境補上理由。避免用長句鋪陳複雜的因果關係，如果一句話裡塞了太多轉折，要拆成兩句分開講。
## 用詞習慣
專有名詞第一次出現時，要用讀者已知的生活情境類比帶出，例如用遊戲存檔點類比 commit，再補上正式定義，不能只丟出英文術語就直接開始使用。
`Git`、`commit`、`repository`、`GitHub`、`branch`、`merge` 這類專有名詞保留英文原文，不翻譯成中文，這是系列從第一天開始就要遵守的用詞習慣，讀者未來查詢資料或閱讀 Git 官方介面時，才能對照得上英文原文。
不使用第一人稱敘事，全篇用直接對讀者說話的方式進行，例如「你現在看到的這個畫面」，而不是「我建議你」。稱呼讀者一律用「你」，不使用「使用者」或「開發者」這類疏離的稱呼。
比喻的使用原則，一個核心比喻只建立一次，後續天數直接沿用，不重新鋪陳，也不換一種新的比喻去解釋同一個名詞，避免讀者因為比喻不斷變換而困惑。
## 哪些句式或修辭要避免
避免「不是……而是……」這種句型。
避免用括號在句中補充說明，該用逗號、冒號或直白陳述取代。
避免堆疊超過一個專有名詞在同一句話裡第一次出現，專有名詞的登場要有節奏，一次只介紹一個。
避免任何暗示讀者「這很簡單」「這很容易」的說法，讀者是完全零基礎，這類說法容易讓卡關的讀者感到被否定。
---
> [!TIP] 給規劃代理人的補充
> 這份文件在規劃每一天內容之前都要完整讀取一次，判斷這一天該用什麼語氣、深度、用詞習慣，套用方式依 [[Day 11：避免內容漂移，跨篇一致性的機制設計]] 定案的機制，讀取後視為不可違背的既定前提，產出後主動比對是否與這裡的設定一致。
確認完畢，寫作代理人開始針對這個範圍展開內容，不越界處理系列其他段落規格才該回答的問題。
這一步的角色需要特別點出來。逐段展開架構不只是「一段一段寫」這麼簡單的節奏安排，它是接下來要示範的每一個機制運作的共同容器。查詢動作發生在這段展開的過程裡、執行驗證發生在這段程式碼或量化片段成形之後、全域錨點檔案的查閱發生在這段動筆之前、論證步驟拆解發生在這段需要因果推導的地方，全部都鑲嵌在這一段展開的節奏裡被觸發，沒有一個機制是獨立於這個節奏之外另起一套流程。這裡不重新展開 Day 14 已經定案的完整論證，只呈現這一步在實戰流程中作為骨架被呼叫的樣貌。
展開到「單次 commit 建議只涵蓋一個邏輯功能，commit 訊息標題建議控制在五十字元以內」這句時，寫作代理人依 Day 15 定案的觸發判準判斷，這段內容的正確性是否可能隨時間或版本而改變。commit 粒度的經驗法則屬於有客觀依據、且坊間資料版本不一的技術性參數，判準成立，這裡需要查證。
推理先判斷需要查證的具體對象是什麼，是這個經驗法則本身有沒有站得住腳的實務依據，接著執行一次外部查詢動作，確認這個建議是否符合普遍認可的版本控制慣例，再把查詢結果帶回原本的推理脈絡繼續往下走，完成一次交錯循環。
但這則段落規格裡並非每一句都需要觸發查詢。緊接在 commit 粒度建議之後的一句「commit 拆得越細，回溯定位問題越快，拆得越粗，回溯越慢」，這是版本控制原理裡通用而穩定的邏輯概念，不隨時間或版本變動，寫作代理人判斷這裡不需要查證，直接依推理結果撰寫。查詢不是逢字必查，觸發與否取決於這句話本身是否具備隨時間或版本漂移的風險。
Git 版本控制入門本身不是需要即時運算的主題，但這則段落規格裡有一段量化計算類比，值得依 Day 16 定案的兩道防線走一遍。段落規格要求提供一個簡單的拆分數量換算，例如「如果一個功能預期拆成三次 commit，每次改動涵蓋的檔案數上限抓在五個以內，一個涵蓋十五個檔案改動的大改動應該拆成幾次 commit」。查詢動作先確認每次改動五個檔案以內這個上限本身是否符合普遍採用的版本控制慣例，確認之後，寫作代理人不是直接把查詢結果寫進正文，還要通過執行驗證這道關卡，實際把十五除以五算一次，確認換算出來的拆分次數與文中要寫的數字一致，確認這段內容套用起來真的站得住腳，而不是只停留在查詢結果聽起來合理。
這裡要具體示範驗證未通過時會發生什麼。假設換算過程中版本不一致，例如查詢到的資料是以檔案數為基準、但正文原本的措辭卻寫成以程式碼行數為基準，執行驗證這一步會直接抓出這個落差，寫作代理人回頭調整措辭，直到換算邏輯與文字敘述完全一致為止，通過才繼續往下走進入下一句。這道關卡鑲嵌在逐段展開架構與 ReAct 模式之上運作，緊跟在查詢動作之後、正文成形之前完成，不是等這一整段寫完後才另外跑一輪獨立的檢查流程。
在正式寫下這段量化換算之前，寫作代理人先查閱全域錨點檔案，確認系列前面天數是否已經定義過類似的檔案數上限或計量習慣。如果前一天已經用過「每次改動五個檔案以內」這個上限作為系列預設值，這一段就沿用同一個數字，不能因為這段單獨查證後又得出另一個聽起來也合理但不同的上限，導致同一個系列裡前後出現兩套不一致的換算基準。
完稿之後，寫作代理人把這一段新引入的具體案例回填進全域錨點檔案，把「commit 訊息標題建議控制在五十字元以內」與「每次改動檔案數上限抓在五個以內」這兩項新定案的具體數值記錄下來，供系列後續天數查閱。這個查閱與回填動作鑲嵌在逐段展開的節奏裡，屬於既有節奏內部的常態動作，每一段涉及具體案例或量化情境時都會觸發，不是額外獨立於外的另一套流程。
這則段落規格裡真正需要因果推導的部分，是從 commit 粒度觀察推導到具體 commit 建議這一段。寫作代理人不是一次通順寫完，而是依 Day 18 定案的論證步驟拆解，把這段收斂到論證步驟層級。第一步先立足在剛才已經查證通過的結論，commit 太大。第二步在第一步的基礎上往下推，commit 太大代表改動內容混雜難以定位。第三步再立足在第二步的結論繼續往下推，如果讀者所在的專案處於快速迭代階段，就該把 commit 拆得更細以換取更快的回溯速度，反之如果專案階段偏向穩定維護，則可以酌情放寬 commit 涵蓋的範圍。每一步都顯式交代這一步是根據前一步的哪個結論展開的，不是跳過中間推理直接丟出結論。
但同一則段落規格裡，並非所有句子都需要收斂到步驟層級。段落開頭「以下說明 commit 粒度如何影響回溯與除錯效率」這類單純的敘述性交代，邏輯密度不高，直接依一般段落展開的節奏寫完即可，不需要拆解成步驟。這正是視內容而定的顆粒度收斂，不是所有段落都要拆到步驟。這個機制本質上是逐段展開架構在顆粒度上的收斂，服務的仍是同一個原則，只針對眼前這個最小單位要求的重點與前提展開內容。
完稿產出如下
# 一次存檔該記多少事，commit 粒度如何影響回溯效率
## 昨天存了一次檔，但如果那次改動牽涉十個檔案呢
昨天你走完了一次完整的存檔手續。修改先出現在工作區，用 `git add` 挑進暫存區，再用 `git commit` 變成一次 commit。
那次示範的情境很單純，只改了一兩個檔案。真實的工作很少這麼乾淨。
換一個情境。你的企劃書拆成十個檔案：封面、目錄，加上第一章到第八章。週三晚上，你同時做了三件事。
第一件，把十個檔案的標題字級和行距調成同一種樣式。第二件，發現第三章的數據表有個錯字，順手改掉。第三件，覺得第五章的預算段落寫得不夠清楚，整段重寫，連數字也跟著動了。
三件事做完，時間已經很晚。你把十個檔案全部挑進暫存區，commit 訊息只寫了「週三修改」。
兩週後，主管指著第五章問你：「這個預算數字，什麼時候改成這樣的？」
你翻開 repository 的記錄，找到「週三修改」那一次。裡面有十個檔案的變動。排版的改動散在十個檔案裡，錯字的改動在第三章，預算的改動在第五章。三件事混在同一個存檔點。
你想弄清楚預算數字是怎麼變的，只能把十個檔案的改動全部攤開，一個一個確認哪些和預算有關。
這個麻煩在存檔當下完全看不出來，要等到兩週後才出現。
為什麼同樣是一次 commit，有的好找、有的難找？下一段先給這個差別一個名字。
## commit 粒度，一次 commit 涵蓋多大的範圍
這個差別叫 commit 粒度。
commit 粒度指的是一次 commit 涵蓋的改動範圍大小。範圍太大，稱為粒度太粗。範圍太小、太瑣碎，稱為粒度太細。
「週三修改」就是粒度太粗的例子。一次 commit 塞進三個不相關的目的，涵蓋十個檔案。
粒度太粗的代價，要等你回頭找問題時才會付。
出問題時，你會往回翻歷史，找出是哪一次修改造成的。這個動作叫回溯。回溯花的時間愈短，回溯效率就愈高。
一次 commit 裡混了十個不相關的檔案，這十個檔案的改動就全部變成嫌疑對象。你得逐一排查，每個檔案都要問一次：問題出在這裡嗎？
多數改動和你要找的問題毫無關係，卻還是得一個一個看過。
粒度太粗的代價，就是每次回溯都得把無關的改動一起排查一遍，回溯效率因此大幅下降。
## 五個檔案與五十個字元，從回溯效率倒推出來的兩個數字
那粒度要多細才夠？沒有哪個數字能套在每個專案上，不過經驗上有兩條好用的參考線。
建議單次 commit 涵蓋的檔案數，不超過五個。建議 commit 訊息標題，不超過五十個字元。
commit 訊息標題，指的是你寫的那句說明。字元的算法很直接：中文字、英文字母、數字、空格與標點，每一個都算一個字元。
這兩個數字是經驗法則。Git 本身不會因為你超過就擋下 commit，要不要遵守由你決定。重點在這兩個數字怎麼來的，下面從回溯效率往回推，一步一步走。
先從目標出發。你要的是回溯效率，也就是出問題時，排查花的時間愈短愈好。
接著找出決定排查時間的因素。回溯時，一次 commit 涵蓋的所有檔案都是嫌疑對象，所以排查範圍就等於這次 commit 的檔案數。檔案數愈多，要逐一檢視的東西愈多，回溯效率隨檔案數增加而下降。
再看檔案數背後藏著什麼。一次改動涵蓋的檔案愈多，通常代表這次同時處理了愈多不相關的目的。「週三修改」有十個檔案、三個目的。單一目的的改動，經驗上多半只會碰到少數幾個檔案。
有了這層關係，警戒線就能定下來。檔案數超過五個，經驗上往往已經混進第二個目的，排查範圍也大到很難一眼掃完。所以建議停在五個以內。
超過五個時，先停下來檢查目的是否真的單一。舉例來說，把全文的公司名稱統一換成新名稱，動了十個檔案，目的仍然只有一個，這時超過五個也合理。五個檔案是一條提醒線，提醒你停下來檢查目的。
檔案數講完了，換個方向看標題。
標題要回答一個問題：這次改了什麼。回溯時，你會先掃過一排標題，挑出可疑的幾次再打開。標題講得清楚，你不用打開就能排除大半。
標題為什麼要壓在五十個字元以內？如果一句話壓在這個長度內，還能講清楚這次改了什麼，代表這次改動的目的多半是單一的。要塞進兩三個目的，標題一定會變長，得靠「並且」「還有」「順便」把它們串起來。標題超過五十個字元，往往就是粒度太粗的徵兆。
這條線還有一個用處：它在你動手之前就能發揮作用。為了壓在五十個字元內，你得先想清楚這次改動的目的。講不清楚的時候，癥結在改動本身，換再多措辭也沒用。
來看幾個標題。下面三句都在十五個字元以內，各自只講一件事：
- 「修正第三章數據表的錯字」，11 個字元
- 「重寫第五章的預算說明段落」，12 個字元
- 「統一十個檔案的標題字級與行距」，14 個字元
下面兩句則有問題：
- 「週三修改」，4 個字元。字數很短，卻什麼都沒講，兩週後的你看不出裡面有什麼。
- 「修正第三章的錯字並調整全文標題排版同時刪除第五章已過期的預算段落以及更新封面日期還有把頁尾的公司名稱改成新的名稱」，56 個字元。超過五十個字元，裡面塞了好幾個目的。
可以看出，這兩個數字從同一個目標倒推而來，也會互相印證。檔案數超過五個、標題壓不進五十個字元，兩種警訊常常同時出現。
兩個數字加起來，是同一個判斷：這次改動的目的是否單一。
## 每改一個字就存一次，是另一種麻煩
講到這裡，你可能會想：那就每個改動都單獨存，愈細愈保險。
這會走到另一個極端。
假設你要把全文十二處的「企畫」改成「企劃」，每改一處就 commit 一次。做完之後，你有十二筆 commit，訊息全是「修正企劃的寫法」。
幾週後，你想弄清楚第三章是怎麼一步步寫完的。你得翻過一大串瑣碎的記錄，才拼得出全貌。真正有意義的幾次大改動，被十二筆小記錄淹沒。
這同樣是回溯效率下降，只是原因換成記錄太碎。
粒度的目標，是讓每一次 commit 都對應到一個單一、講得清楚的目的。
照這個標準，十二處「企畫」改「企劃」只有一個目的，存成一次 commit 剛剛好。第三章的錯字和第五章的預算是兩個目的，存成兩次。
粒度太粗，是一次裝了太多目的。粒度太細，是一個目的被切成太多筆。兩種情況都讓你在回頭查找時多花力氣。
## 動手改之前，先問自己一句話
動手改之前，先問自己一句：這次改動，能不能用五十個字元以內的一句話，講清楚在做什麼？
講得清楚，一次 commit 就夠。講不清楚，或者得用「還有」「順便」串起來，代表這次改動藏著不只一個目的，該考慮拆成幾次 commit。
回到週三晚上。拆開之後，三件事各存一次。
同一個檔案裡的兩種改動，昨天學的 `git add 檔名` 沒辦法拆開。所以最省事的做法，是一件事做完就存一次，再動手做下一件事。
以第三章的錯字為例，改完之後這樣存：
```bash
git add chapter3.txt
git commit -m "修正第三章數據表的錯字"
標題 11 個字元，只講一件事。第五章的預算段落、全文的排版，照同樣的方式各存一次。
今天帶走的有兩件事。第一，兩個經驗上的參考線：單次 commit 涵蓋的檔案數建議不超過五個，commit 訊息標題建議不超過五十個字元。第二，這兩條線背後的因果：範圍愈大愈難回溯，標題講不清楚就是粒度太粗的徵兆。
不過，今天談的都是你一個人單獨工作時，怎麼把檔案存得好。
如果同時有兩條工作要並行進行，例如一邊修一個小問題，一邊開發新功能，它們會不會彼此打架？這件事你還沒碰過。明天要進入分支的世界。
## 這一段寫完了，接下來不是寫作代理人的事
這一段完稿，查詢與驗證都已通過之後，依 Day 19 定案的邊界，寫作代理人的職責範圍到此為止。它已經確認過這段內容此刻是否可信，commit 粒度建議查證屬實、檔案數換算驗算無誤、因果推導每一步都立足在前一步已成立的結論之上，這是撰寫當下的單點查證。
但這一段寫完之後，能不能與系列後面某一段產生矛盾，例如後面某天是否會出現與這裡不一致的 commit 粒度建議或檔案數上限，這件事寫作代理人不處理。全文尺度是否存在矛盾或衝突，留給審查代理人在成品完成後複核，寫作代理人不越界處理。這裡不展開審查代理人具體如何評判、依據什麼標準查核，只點出這個交接動作本身，呼應 Day 19 定案的分工邊界。
## 六個機制串起來，看見一條真正協同運作的工作流
把剛才走過的流程重新用一段簡短的話覆述一次。逐段展開架構是骨架容器，寫作代理人只針對這一段要求的重點與前提展開內容。全域錨點檔案延伸使用是常態動作，動筆前查閱、完稿後回填，貼著撰寫節奏進行。ReAct 模式、程式碼正確性兩道防線、論證步驟拆解，是視內容性質而定的條件觸發，commit 粒度建議觸發了查詢、檔案數換算觸發了查詢加執行驗證、因果推導觸發了步驟拆解，通用穩定的邏輯句與單純敘述句則沒有觸發任何一項。寫完的這一段，最終交給審查代理人做成文之後的複核。
過去六天分別學到的每一個機制，今天在這個實戰示範裡不是被單獨展示，而是被證明彼此之間確實存在明確的鑲嵌關係與觸發條件，這正是與 Day 13 七個環節線性依序執行最大的不同之處。走完這趟流程，正好可以回頭檢視，剛才這六個機制，各自具體解決了哪些從 Day 01 就開始追問的病灶，這一次的驗收會比 Day 13 更細緻。
## 病灶回顧，階段四七天累積的成果被回應到什麼程度
今天是階段四的收尾篇章，值得回頭檢視 Day 14 到 Day 20 這七天累積的成果，究竟如何回應 [Day 01：為什麼傳統的「一鍵生成」寫不出好的長篇技術文章？](https://ithelp.ithome.com.tw/articles/10410607) 定案的四大病灶，注意力稀釋、內容漂移、事實幻覺、零容錯結構。
**注意力稀釋**，可論證為完整解決。緊扣剛才骨架先行那一節與論證步驟拆解那一節，逐段展開架構讓寫作代理人一次只需要處理眼前這一段的重點與前提，宏觀推理與微觀查證不再被迫塞進同一次生成。論證步驟拆解進一步把宏觀推理側的顆粒度收斂到步驟層級，剛才示範的三步因果推導，每一步都只立足在前一步已成立的結論之上。注意力稀釋這個病灶原本定義涵蓋的兩側，宏觀邏輯推理與微觀細節查證，到今天都各自在受控的顆粒度上運作，不再彼此爭奪同一次推理的注意力。
**事實幻覺**，可論證為完整解決。緊扣剛才 ReAct 模式與執行驗證那兩節，寫作代理人在撰寫當下主動查證 commit 粒度建議這類可能隨資料來源而變動的技術性參數，而不是憑訓練記憶直接寫下一個聽起來合理的數字。查詢與執行驗證兩道防線進一步確保檔案數換算這類量化片段不只查詢正確，還真正通過驗算，站得住腳。寫作代理人不再延續一鍵生成依賴訓練記憶賭一把的邏輯，這正是事實幻覺這個病灶被完整解決的具體展現。
**內容漂移**，須誠實論證為實質進展但不算完整解決。緊扣剛才全域錨點檔案延伸使用那一節，查閱與回填處理的是跨篇概念定義與量化基準一致性這一層，確保「commit 訊息標題五十字元以內」與「每次改動檔案數上限五個以內」這類數值不會在系列不同天數之間各說各話。但 Day 01 定義的內容漂移還包含另一層，單篇內部語氣與深度隨長度稀釋。這一層的機制主要建立在規劃代理人 [Day 10：定義文章的風格指南與目標受眾畫像](https://ithelp.ithome.com.tw/articles/10416311) 與 [Day 11：避免內容漂移，跨篇一致性的機制設計](https://ithelp.ithome.com.tw/articles/10416828) 已經建立的風格指南與跨篇一致性機制之上，寫作代理人在這一層扮演的角色是延續與查閱既有定案，而非獨立新增一套攔截機制。這兩層必須清楚區分，不可籠統宣稱內容漂移已被寫作代理人完整解決。
**零容錯結構**，同樣須誠實論證為實質進展但不算完整解決。緊扣剛才骨架先行與執行驗證那兩節，逐段展開架構與查詢執行驗證兩道防線，讓局部錯誤能被精準定位到對應段落或對應片段，剛才示範的換算落差就是在執行驗證這一關被具體抓出、具體修正，不必牽動整段重寫。這比一鍵生成緊密纏繞上下文的產出方式已經是明確進展。但錯誤發現之後能否真正做到只抽換局部不牽動整體，以及如何在多篇之間傳遞這類局部修正的影響範圍，這些問題的最終解答落在後續審查代理人與工作流編排階段，寫作代理人本身提供的是定位精度的提升，不是零容錯結構這個病灶的最終解方。
收束來看，語氣誠實但不過度謙虛，寫作代理人這個角色在自己職責範圍內確實完整解決了兩個病灶，注意力稀釋與事實幻覺，另外兩個病灶，內容漂移與零容錯結構，它做出了具體且可驗證的實質進展，把最終的完整解決交接給後續角色。這正是單一職責 Agent 原則該有的樣貌，累積式的進展本身，就是這套系統相對一鍵生成最直接的證明。
## 文字都到位了，但還缺一塊
今天完整跑過一次實戰流程，證明寫作代理人紙面上具備的六個機制，確實能在實際運作中協同運作。骨架容器裝著條件觸發，常態動作貼著撰寫節奏進行，六個機制不是六個各自獨立的知識點，而是一條真正會依序或視情況被呼叫的工作流程。
回顧今天的病灶對照，注意力稀釋與事實幻覺在寫作代理人身上被完整解決，內容漂移與零容錯結構有實質進展但尚未完整解決，最終解答留給後續角色。寫作代理人這個角色到此已經完整驗收，它能穩定產出經過查證、程式碼可執行、跨篇狀態一致、論證緊密的初稿，階段四正式結束。
文字內容到今天已經全數到位，但技術文章顯然不只有文字。
還缺一塊，這個缺口今天還沒有答案，將在下一篇正式揭曉。
iThome鐵人賽
看影片追技術