Day 12：規格書的自我檢查，規劃代理人如何驗證自己的產出 結尾留下一個具體的問題。規劃代理人在紙面上該具備的所有能力都齊全了，但這一切究竟能不能在實際運作中兌現，還有一段需要親自驗證的距離。今天要正式回答這個問題。
今天的任務，是完整跑一次規劃代理人從拿到主題到交出 Section Spec 的實際產出流程，這是階段三規劃代理人開發六天的收尾驗收。
呈現方式會用敘事性的方式走一遍流程，示範每個環節做了什麼、為什麼這樣做，不會逐字展示一份完整規格書的內容，那樣會讓文章淪為規格書全文的堆疊，失去該有的節奏感。
今天不會挑一個與系列本身完全無關的隨機主題，也不會直接示範系列自身正在進行的規劃內容，那樣容易產生奇怪的自我指涉。
這裡選定一個中性、與系列本身「用 AI Agent 協同寫長篇技術系列文章」這個主題完全無關的示意題材：Git 版本控制入門系列文章。這是示意用途，不是系列作者真正拿去用的規劃結果，只是用來走一遍流程，讓讀者看清楚每個環節實際發生了什麼。
基本輸入很簡單，主題是 Git 版本控制入門，系列定位是給完全沒有寫過程式、沒用過版本控制的讀者看的實用系列，預計五天。有了這三項輸入，規劃代理人就可以開始動工。
依 Day 11：避免內容漂移，跨篇一致性的機制設計 建立的機制，規劃代理人在動筆之前，先完整讀取目前已經定案的名詞與架構決策、風格指南、受眾畫像，把這些內容當作規劃這一篇時不可違背的既定前提。
以下是全域定位的範例
---
type: global-anchor
series: Git 版本控制入門系列文章
status: 已累積至第 5 天
---
> [!NOTE] 這份文件是什麼
> 這是 [[Day 13：實戰，讓規劃代理人產出一套完整的系列大綱]] 環節一提到的既定前提來源，也是環節六回寫的目標，Git 版本控制入門示意系列專屬的全域錨點檔案。格式比照 [[Day 05：系列的單一事實來源，打造全域錨點檔案]] 定案的慣例，記錄已定義專有名詞與已定案架構決策兩類內容，每一筆都標註首次定案於哪一天。這份檔案呈現的是五天規劃全部跑完之後的完整累積狀態，實務上它會隨著規劃逐天推進而逐筆增補，不是一次寫成。
## 已定義專有名詞
| 名詞 | 定義 | 首次定案 | 狀態 |
| :--- | :--- | :--- | :--- |
| commit | 一次有意義的存檔動作，記錄下這個時間點檔案變成了什麼樣子，並附上一句說明這次改了什麼。比喻為遊戲存檔點，但這個存檔點還附一句自己寫的說明 | 第 1 天 | 有效 |
| repository（repo） | 存放一個專案所有版本記錄的地方。類比成存放所有存檔點的合集 | 第 1 天 | 有效 |
| 工作區 | 你現在看到、正在編輯的檔案所在的地方，修改先出現在這裡 | 第 2 天 | 有效 |
| 暫存區 | 工作區與 repository 之間的中間地帶，用來主動挑選這次要記錄哪些修改，對應 `git add` 這個動作 | 第 2 天 | 有效 |
| commit 粒度 | 一次 commit 涵蓋的改動範圍大小，範圍太大稱為粒度太粗，範圍太小、太瑣碎稱為粒度太細 | 第 3 天 | 有效 |
| 分支 | 在不影響原本時間線的前提下，另外開一條獨立的時間線去嘗試新的東西。比喻為從某個存檔點岔出去的一條平行時間線 | 第 4 天 | 有效 |
| 合併 | 把分支上累積的一連串 commit，依序接回主線，決定這條分支上的成果是否正式併入正史 | 第 4 天 | 有效 |
| 合併衝突 | 兩條分支改到同一個地方，Git 無法自動判斷該留哪一邊，需要由人決定的狀態 | 第 5 天 | 有效 |
## 已定案架構決策與量化經驗法則
| 項目 | 內容 | 首次定案 | 狀態 |
| :--- | :--- | :--- | :--- |
| 核心論點方向 | 掌握 commit 習慣與分支節奏，比選用高級工具更能決定版本控制的效果 | 第 1 天 | 有效，第 4 天、第 5 天皆回扣此論點 |
| 系列定位 | 給完全沒有寫過程式、沒用過版本控制的讀者看的實用系列，共五天 | 第 1 天 | 有效 |
| Git 與 GitHub 的區分 | Git 是記錄機制本身，GitHub 是讓這些記錄能放上網路、多人共用的平台 | 第 1 天 | 有效 |
| commit 訊息標題字數上限 | 建議不超過五十個字元，講不清楚往往是粒度太粗的徵兆 | 第 3 天 | 有效 |
| 單次改動檔案數上限 | 建議單次 commit 涵蓋的檔案數不超過五個，超過會使回溯時需要排查的範圍過大 | 第 3 天 | 有效 |
| 分支合併時機判斷 | 合適的合併時機是新想法已確定可行、且與主線差異範圍還沒堆得太大的時候，太早合併會讓不穩定的嘗試污染主線，太晚合併會讓差異愈堆愈多、愈容易衝突 | 第 4 天 | 有效 |
| 誤刪分支的排查依據 | 只要分支上的 commit 曾經存在過，可透過 `git reflog` 找到最後一次的 commit 位置重新建分支接回去 | 第 5 天 | 有效 |
| 收尾語氣原則 | 系列最後一天不留系列外的懸念鉤子，改用「五天所學如何在真實專案裡持續使用」的收束語氣 | 第 5 天 | 有效，僅適用於本示意系列最後一天 |
---
> [!TIP] 給規劃代理人的補充
> 每次規劃新的一天之前，先完整讀取這份檔案裡目前已定案的所有名詞與決策，視為不可違背的既定前提，不可憑印象重新推斷或另創相近但不同的說法。若規劃過程中確實產生新的定案內容，例如本例中第 3 天新增的兩個量化經驗法則，須即時回寫進這份檔案，並標註首次定案於哪一天，供後續天數查閱沿用。
以下是所有材料的範例
---
type: support-material
series: Git 版本控制入門系列文章
status: 已定案
---
> [!NOTE] 這份文件是什麼
> 這是 [[Day 13：實戰，讓規劃代理人產出一套完整的系列大綱]] 環節三提到的既有依據，規劃代理人在規劃每一天內容之前，會拿出這份風格指南與受眾畫像來套用，判斷語氣基調、句式偏好、用詞習慣該怎麼設定。格式比照 [[Day 10：定義文章的風格指南與目標受眾畫像]] 定義的兩份文件應包含的要素，內容是 Git 版本控制入門示意系列專屬的版本，不是抽象通用模板。這份文件在系列規劃初期一次性確立，供五天共用查閱。
# 目標受眾畫像
## 讀者的背景知識水位
完全沒有寫過程式、完全沒有用過任何版本控制工具。讀者可能是文字工作者、行政人員，或者剛開始想自學程式、卻卡在跟別人合作時的檔案管理問題上，才第一次聽到 Git 這個名字。
讀者不具備任何指令列操作經驗，這件事必須被完整考慮進去，系列裡第一次出現任何指令，都要附上可以直接照打的範例，不能假設讀者知道怎麼開啟終端機或知道指令列是什麼。
## 讀者的痛點與動機
讀者的痛點通常很具體，多人或多版本同時修改同一份檔案時，曾經遇過覆蓋、遺失、對不出誰改了什麼的經驗，或者聽同事、朋友提過 Git，但每次想學都被一大堆陌生指令與術語擋在門外，學到一半就放棄。
讀者的動機不是想成為工程師，而是想解決眼前這個具體的合作與版本管理問題。這決定了系列不該往「程式開發最佳實務」這個方向延伸，該緊扣在「檔案版本管理」這個最貼近讀者需求的範圍裡。
## 讀者的閱讀情境
讀者比較可能是坐下來願意跟著操作，而不是通勤時快速瀏覽。這決定了系列可以保留完整的指令範例與操作步驟，不需要為了適應碎片閱讀而過度精簡步驟，但每篇仍要維持在讀者一次坐下來就能讀完並跟著操作一遍的長度。
# 風格指南
## 語氣基調
採用直接了當的口語對話口吻，像是一個有經驗的朋友坐在旁邊，一步一步帶你操作，不是正式的技術文件口吻。避免任何生硬的制式套話，例如「總而言之」「值得注意的是」這類詞，改用直白的陳述銜接。
## 句式偏好
偏好短句，直接下結論，再用具體情境補上理由。避免用長句鋪陳複雜的因果關係，如果一句話裡塞了太多轉折，要拆成兩句分開講。
## 用詞習慣
專有名詞第一次出現時，要用讀者已知的生活情境類比帶出，例如用遊戲存檔點類比 commit，再補上正式定義，不能只丟出英文術語就直接開始使用。
`Git`、`commit`、`repository`、`GitHub`、`branch`、`merge` 這類專有名詞保留英文原文，不翻譯成中文，這是系列從第一天開始就要遵守的用詞習慣，讀者未來查詢資料或閱讀 Git 官方介面時，才能對照得上英文原文。
不使用第一人稱敘事，全篇用直接對讀者說話的方式進行，例如「你現在看到的這個畫面」，而不是「我建議你」。稱呼讀者一律用「你」，不使用「使用者」或「開發者」這類疏離的稱呼。
比喻的使用原則，一個核心比喻只建立一次，後續天數直接沿用，不重新鋪陳，也不換一種新的比喻去解釋同一個名詞，避免讀者因為比喻不斷變換而困惑。
## 哪些句式或修辭要避免
避免「不是……而是……」這種句型。
避免用括號在句中補充說明，該用逗號、冒號或直白陳述取代。
避免堆疊超過一個專有名詞在同一句話裡第一次出現，專有名詞的登場要有節奏，一次只介紹一個。
避免任何暗示讀者「這很簡單」「這很容易」的說法，讀者是完全零基礎，這類說法容易讓卡關的讀者感到被否定。
---
> [!TIP] 給規劃代理人的補充
> 這份文件在規劃每一天內容之前都要完整讀取一次，判斷這一天該用什麼語氣、深度、用詞習慣，套用方式依 [[Day 11：避免內容漂移，跨篇一致性的機制設計]] 定案的機制，讀取後視為不可違背的既定前提，產出後主動比對是否與這裡的設定一致。
這一步不能跳過。如果跳過這一步，規劃代理人很可能單純根據當下主題直覺推斷出一個聽起來也合理、卻與過去定案存在細微出入的版本，例如某個 Git 指令或概念的稱呼方式，前面幾天已經定案過一種稱呼方式，這一步沒讀取到，很可能又重新想出一個相近但不完全一致的說法。
依 Day 09：運用結構化推理模式產出大綱骨架 建立的結構化推理，規劃代理人針對這次示意主題，先梳理出一句可被檢驗的核心論點，例如「掌握 commit 習慣與分支節奏，比選用高級工具更能決定版本控制的效果」，再梳理支撐這個論點需要哪些子論證，以及子論證之間該有的排列順序。
規劃代理人接著用互換測試自問，確認這份骨架不是關鍵字的隨意排列，而是真正具備先後依賴關係的邏輯結構。如果把「commit 粒度的影響」與「分支合併節奏的影響」兩個段落順序對調，後面段落是否還能順暢銜接，如果對調後論證出現跳躍，代表這兩段確實存在先後依賴，骨架站得住腳。
這段推理脈絡完全發生在規劃代理人內部，不會出現在成品裡，也不會寫進 Section Spec 的正式欄位。
這正是 Day 09 已經定案的職責邊界。
依 Day 10：定義文章的風格指南與目標受眾畫像 建立的風格指南與受眾畫像，規劃代理人依據既定的受眾畫像，判斷這次示意主題的讀者背景知識水位、痛點與動機、閱讀情境，並據此決定語氣基調、句式偏好、用詞習慣。
如果受眾畫像跟這一次設定的一樣，是完全沒有寫過程式、沒用過版本控制的讀者，語氣就該貼近口語、句式該更短更直接，避免堆疊過多專有名詞。
這一步確保這篇規格書讀起來與系列其他篇章像是同一個人寫的，而不是各自漂移的語氣。
依 Day 04：規劃代理人的產出介面，認識 Section Spec 建立的格式，規劃代理人把前面梳理好的論點、順序、語氣、深度假設，轉譯成正式的四個必要欄位，核心目標、前置概念、段落規格、結尾伏筆。
這裡只呈現示範性質的簡短描述，不逐字展示完整規格書內容。這一步是前面三個環節的匯流點，前面梳理的邏輯、語氣、深度假設，都要在這一步被正式落地成寫作代理人看得懂的交接介面。
以下是根據上面的規劃，寫出的 Day 1 規格書
# 為什麼你需要 Git，從一場檔案覆蓋的意外說起
**系列**：Git 版本控制入門系列文章，共五天，給完全沒有寫過程式、沒用過版本控制的讀者看的實用系列
**本篇順序**：第 1 天
## 核心目標
讓讀者理解版本控制存在的理由，不是多一個要學的工具，而是解決一個他們大概都遇過的具體痛點：多人或多版本同時修改同一份檔案時，覆蓋、遺失、對不出誰改了什麼。
讀完這篇，讀者應該能一句話說出版本控制在解決什麼問題，而不是背出 Git 的功能清單。
## 前置概念
本篇是系列第一天，沒有任何前置概念，所有名詞第一次出現都要完整定義。
本篇會定義兩個後續天數都要沿用的名詞：
- **commit**：一次有意義的存檔動作，記錄下這個時間點檔案變成了什麼樣子，並附上一句說明這次改了什麼
- **repository**（簡稱 repo）：存放一個專案所有版本記錄的地方
這兩個定義之後每一天都要照抄，不能重新換一種說法。
## 段落規格
**第一段，一次檔案覆蓋的意外**
用一個讀者會覺得「這不就是我」的具體情境開場，例如兩人各自修改同一份文件後互傳，其中一份修改整個消失，查不出是誰、什麼時候改的。這一段不提 Git，不提任何工具名稱，先讓讀者純粹感受到問題本身。
**第二段，問題不是誰粗心，是缺少一個記錄機制**
把第一段的意外抽象成一句話：問題不是使用者不小心，是整個流程裡沒有東西記錄下「這個時間點檔案是什麼樣子、是誰改的、改了什麼」。順勢帶出版本控制最口語的定義，讓每一次有意義的修改都留下可回溯的記錄。這一段要讓讀者自己推導出「如果當時有記錄，就不會發生覆蓋」，不要替讀者講完，留一點空間讓他自己接上。
**第三段，認識 commit 與 repository**
正式定義這兩個名詞。commit 用遊戲存檔點來類比，但這個存檔點還附一句自己寫的說明；repository 類比成存放所有存檔點的合集。順手澄清一件事，Git 跟 GitHub 不是同一個東西，Git 是記錄機制本身，GitHub 是讓這些記錄能放上網路、多人共用的平台。這一段不示範任何指令，只建立概念。
**第四段，這五天要帶你走到哪裡**
收尾，重申今天的兩個收穫：版本控制解決的是什麼問題，commit 與 repository 是什麼。埋下伏筆，今天只建立了心理模型，還沒真正動手做過一次存檔，這件事明天處理。不要提前透露工作區、暫存區的細節。
## 結尾伏筆
今天只解決了一件事，讀者現在該理解版本控制在解決什麼問題，也認識了 commit 與 repository 這兩個接下來會反覆用到的名詞。但認識名詞不等於會操作，今天從頭到尾都還沒有實際做過一次存檔動作。工作區與暫存區之間，一份修改要經過幾道手續才會真正變成一次 commit，這件事留給明天。
---
> [!TIP] 給寫作代理人的補充
> - 全篇語氣要口語、短句，避免一開場就堆專有名詞。`commit`、`repository`、`GitHub` 這幾個詞照上面段落規格指定的順序帶出即可，不要提前用。
> - commit 的存檔點比喻要在第三段完整鋪陳一次，後面幾天可以直接沿用，不用每次重新解釋。
> - 這一篇完全不示範指令列語法，操作留給第二天。
依 Day 12：規格書的自我檢查，規劃代理人如何驗證自己的產出 建立的四項自我檢查，規劃代理人在交出規格書之前，逐一跑過四項檢查，確認四個必要欄位是否齊全、重新對段落規格跑一次互換測試、比對規格書內部名詞用法是否前後矛盾、檢視每個段落規格是否真的服務於核心目標。
假設這次的段落規格裡，某一段在轉譯過程中不小心遺漏了「commit 粒度會影響回溯效率」這個邏輯依賴，導致這段讀起來又變回了與前段無關的並列說明，自我檢查機制在這裡就能把這個瑕疵抓出來並要求補上。
依 Day 11 建立的機制，如果這次規劃過程中確實產生了新的定案內容，例如某個 Git 指令的標準稱呼是第一次被正式定義，規劃代理人要把這個新增內容即時回寫進全域錨點檔案。
這一步很重要。如果回寫被拖延或省略，後續天數查到的會是一份過時的地基，反而會製造出新一輪的漂移。整條流程走到這裡完整閉環，從讀取既有定案開始，到回寫新定案結束，下一次規劃啟動時，這次的新增內容也會成為既定前提的一部分。
把七個環節依序串起來覆述一次，拿到輸入、強制讀取既定前提、結構化推理、套用風格與受眾、產出四個必要欄位、自我檢查、回寫全域錨點檔案。
過去五天分別學到的每一個機制，今天在這個實戰示範裡不是被單獨展示，而是被證明彼此之間確實存在明確的呼叫順序與交接關係。走完這趟流程，正好可以回頭檢視，剛才這七個環節，各自具體解決了哪些從 Day 01 就開始追問的病灶。
今天是階段三的收尾篇章，值得回頭檢視 Day 08 到 Day 13 這六天累積的成果，究竟如何回應 Day 01：為什麼傳統的「一鍵生成」寫不出好的長篇技術文章？ 定案的四大病灶，注意力稀釋、內容漂移、事實幻覺、零容錯結構。
注意力稀釋，緊扣剛才的實戰流程，規劃代理人自始至終沒有查證任何一個技術細節的正確性，它只負責宏觀推理，這個角色邊界從 Day 03 定案以來，在今天的七個環節裡沒有任何一步要求它兼顧微觀查證，這正是注意力稀釋這個病灶在規劃代理人身上被完整解決的具體展現。
內容漂移，緊扣剛才的環節一與環節三，強制讀取既定前提確保這次產出忠於過去的定案，套用風格指南與受眾畫像確保語氣與深度不隨天數推移而走鐘，兩者合起來讓內容漂移在規劃階段就被主動攔截，這正是內容漂移這個病灶被完整解決的具體展現。
事實幻覺，這裡要誠實說明，規劃代理人只能提供間接貢獻，因為規劃代理人本身不查證任何技術細節，它產出的 Section Spec 只是要求寫作代理人在對應段落查證，但查證這個動作本身要留給寫作代理人執行，這項病灶真正的解決要等到寫作代理人開發階段才有答案。
零容錯結構，同樣誠實說明，規劃代理人只能提供間接貢獻，因為它把整篇文章拆分成具備獨立邊界的段落規格，讓後續若發現局部錯誤時能精準定位到對應段落，但規劃代理人本身不撰寫正文，真正決定局部錯誤能否只抽換不牽動整體的關鍵，落在寫作代理人與後續工作流編排階段。
語氣誠實但不過度謙虛地收束，規劃代理人這個角色在自己職責範圍內確實完整解決了兩個病灶，另外兩個病灶它盡了能盡的本分，把攔截責任正確地交接給下一個角色。這正是單一職責 Agent 原則該有的樣貌，每個角色只需要把自己負責的部分做到底，不必也不該去解決所有病灶。
今天完整跑過一次實戰流程，證明規劃代理人紙面上具備的能力確實能在實際運作中兌現，七個環節依序被呼叫，構成一條真正在運作的工作流程。注意力稀釋與內容漂移在規劃代理人身上被完整解決，事實幻覺與零容錯結構規劃代理人只能提供間接貢獻，真正的解決要留給後續角色。
規劃代理人這個角色到此已經完整驗收，它能穩定產出邏輯清楚、風格一致、通過自我檢查的 Section Spec，階段三正式結束。
但規劃代理人自己明確不做的事，查證技術細節、撰寫正文，這些工作交給誰、如何從一份規格書出發真正展開成一篇文章，這個問題今天還沒有答案。呼應 Day 03：拆解寫作工作流，規劃、撰寫、視覺、審查的四種角色 定案的角色交接精神，這正是規劃代理人準備把成果正式交棒給寫作代理人的時刻，將在 《Day 14：寫作代理人的架構設計，從規格到草稿》 正式揭曉。
iThome鐵人賽
看影片追技術