iT邦幫忙

2026 iThome 鐵人賽

DAY 6
0
Claude AI

用 AI Agent 撰寫長篇技術系列文章系列 第 6

Day 05:系列的單一事實來源,打造全域錨點檔案

  • 分享至 

  • xImage
  •  

Day 04:規劃代理人的產出介面,認識 Section Spec》結尾留下一個具體的問題。第 20 天的規劃代理人,要怎麼確保自己沒有遺忘或誤用第 8 天已經定案的用詞與決策。今天要正式回答這個問題。

一份被遺忘的定案,會發生什麼事

想像一個畫面。系列進行到第 8 天,規劃代理人替某個架構元件定下了一個名稱,也定義好它的職責範圍。這個定義寫進了當天的 Section Spec,文章也照著這個定義寫完發布。

時間來到第 20 天,另一次獨立展開的規劃工作裡,同一個架構元件又出現了,但這次規劃代理人手上只有第 20 天這一次任務的上下文,沒有人特別提醒它第 8 天已經定案過什麼。於是它憑著當下的理解,替這個元件重新選了一個相近但不完全相同的說法,或者悄悄調整了職責範圍的邊界。

兩篇文章各自讀起來都很通順,問題要等到讀者前後對照才會浮現,同一個名詞,怎麼在系列裡有兩種說法。

這正是 Day 04 結尾懸念指向的具體場景。今天的任務範圍要先畫清楚,只處理「已經定義過的名詞或已經定案的架構決策,要怎麼被跨天一致地記錄與沿用」,不涉及原始筆記或素材本身要如何被整理收集,那是明天才要處理的範疇。

這個共享記錄,今天要正式為它命名,叫做全域錨點檔案。它是一份記錄系列中所有已定義專有名詞與已定案架構決策的獨立檔案,作為所有 Agent 共享的單一事實來源。

為什麼不能只靠規劃代理人自己記得

讀完上面的畫面,一個直覺可能會冒出來,規劃代理人只要把每天的 Section Spec 都寫清楚,自己應該記得住之前定義過什麼吧。這個直覺值得認真回應,因為它建立在一個容易被忽略的錯誤類比之上。

人類作者長期投入一個系列的寫作,會在腦中自然累積起一套連貫的記憶,某個名詞是哪天定義的、某個架構決策當初為什麼這樣拍板,這些記憶會隨著寫作進度持續疊加。但規劃代理人在規劃每一天內容時,往往是相對獨立展開的一次工作,不必然帶著前面每一天的完整脈絡進場。把人類作者的長期記憶經驗,直接套用在規劃代理人身上,是一種站不住腳的類比。

如果跨天一致性只能仰賴翻閱前面每一天各自的 Section Spec 或成品全文去比對,隨著天數累積,需要回頭核對的文件數量只會線性增加。等到第 20 天要核對第 8 天的定案時,等於要求每一次規劃都重新搜尋並確認過去所有天數的內容,這件事在系列規模放大之後會迅速變得不可靠。這也違背了 Day 02:產出優先思維,先定義規格再動筆 定案的產出優先思維所追求的效率,先定義清楚要產出什麼,而不是每次都得先花大量力氣重新確認過去發生過什麼。

把這個問題扣回 Day 01:為什麼傳統的「一鍵生成」寫不出好的長篇技術文章? 定案的四大病灶會更清楚。如果沒有一份獨立於單篇文件之外的共享記錄,內容漂移這個病灶,會從單篇內部的規模,擴大成跨越整個系列的規模。某個名詞或架構決策在不同天數之間出現微妙的用詞或語意差異,讀者若前後對照閱讀就會察覺系列內部自相矛盾,這對長達 35 天的系列而言,是比單篇內容漂移更嚴重的傷害。

收束回來看,Day 04:規劃代理人的產出介面,認識 Section Spec 定案的 Section Spec,解決的是單篇文章內部規劃代理人與寫作代理人之間的交接問題,但它本質上是一次性、單篇範圍的文件,不負責記住其他天數定案過什麼。這正是為什麼需要一份獨立於所有單篇規格書之外,專門記錄跨天定案內容的共享檔案。

全域錨點檔案該記錄什麼

全域錨點檔案至少需要記錄兩類內容,已定義專有名詞,以及已定案架構決策。每一類內容存在都有明確的目的,也各自對應著缺少它時會冒出來的具體問題。

已定義專有名詞:記錄系列中每一個被正式定義過的專有名詞、它的完整定義內容,以及它第一次被定義是在哪一天。它存在的目的,是讓任何一天的規劃代理人在需要引用某個名詞時,能直接查到權威版本的定義與出處,不必自己重新措辭或憑印象轉述。缺少這類記錄時,同一個概念容易在不同天數被不同方式重新解釋,逐漸偏離原始定義,就像開場那個畫面裡發生的狀況。

已定案架構決策:記錄系列中對整體架構或系統設計拍板定案的重要決策,例如角色如何分工、階段如何劃分,以及這個決策當初拍板定案的理由摘要。它存在的目的,是避免後續某一天的規劃工作,在不知情的狀況下做出與早先決策相矛盾的安排。缺少這類記錄時,容易出現後面天數不小心推翻或悄悄修改了前面已經定案架構的狀況,讀者對照閱讀時會感受到系列內部邏輯不連貫。

除了這兩類內容本身,每一筆記錄還應該標註出處與狀態,首次定案於哪一天,以及目前是否仍為有效狀態或已被後續調整取代。這個欄位存在的目的,是讓查閱者能追溯決策脈絡並判斷資訊是否為最新版本。缺少它時,查閱者無法分辨手上看到的記錄是否仍然有效,容易誤用已經過時的舊定義。

這份檔案的性質,值得特別強調一次,它獨立於任何單篇文章之外。它不屬於某一天的 Section Spec,也不會隨著某一天的產出而結案,而是隨著系列進展持續累積、持續被查閱與回填的常駐檔案。這與 Section Spec 在生命週期上有本質差異,Section Spec 服務單篇交接,用完即完成階段性任務,全域錨點檔案服務整個系列,隨系列存續而持續累積。

誰在讀這份檔案,單一事實來源的意義

全域錨點檔案的讀者,不只是規劃代理人自己。依 Day 03:拆解寫作工作流,規劃、撰寫、視覺、審查的四種角色 定案的四類 Agent 分工架構,寫作代理人查證用詞時、視覺代理人繪製架構圖時、審查代理人核對前後文是否一致時,理論上都可能需要查閱同一份檔案,確保四類角色對同一個名詞或決策抱持相同理解。這正是「單一事實來源」這個說法的實際意義,所有角色查到的都是同一份權威版本,而不是各自持有一份可能已經不同步的理解。

這也是全域錨點檔案與 Section Spec 之間值得再次釐清的層級區分。Section Spec 是規劃代理人與寫作代理人之間一次性的單篇交接介面,全域錨點檔案是所有 Agent 共享的長期記憶。兩者服務的協作範圍與生命週期都不同,不是彼此的替代品,而是系統地基裡互補的兩塊拼圖。

地基的第二塊拼圖,原始素材還沒著落

今天正式定案了全域錨點檔案,這是記錄系列中所有已定義專有名詞、已定案架構決策的獨立檔案,作為所有 Agent 共享的單一事實來源。透過持續累積、持續查閱的方式,讓跨天協作不必仰賴任何單一角色的記憶,也不必每次都翻閱過去每一天的文件去比對。

但這只解決了「已經定案過的內容,如何被跨天一致地記錄與沿用」這個問題。規劃代理人與寫作代理人平時工作時,還需要查證大量還沒被定義過的原始內容,例如某個技術細節的具體行為、某段程式碼的正確用法。這些原始素材目前散落在各種零散的筆記裡,要如何被有效率地整理成可以查詢與引用的資料來源,這個問題今天還沒有答案,將在《Day 06:從筆記到知識庫,素材的收集與初步整理》正式揭曉。


上一篇
Day 04:規劃代理人的產出介面,認識 Section Spec
下一篇
Day 06:從筆記到知識庫,素材的收集與初步整理
系列文
用 AI Agent 撰寫長篇技術系列文章8
圖片
  熱門推薦
圖片
{{ item.channelVendor }} | {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言