如何使用 dox 自動更新 AGENTS.md 檔案

為何您的 AGENTS.md 在三週後就會過期

AGENTS.md 檔案會過期，是因為它與程式碼之間缺乏連結。您在儲存庫呈現特定狀態的那一天手動撰寫了它。隨後測試執行器變更、套件重新命名或服務被刪除，但該檔案仍描述著六月的狀態。由於沒有任何建置步驟會讀取它，因此不會觸發任何失敗。

代理程式會讀取並採信該檔案。這正是導致成本產生的原因。若儲存庫沒有 AGENTS.md，程式設計代理程式在執行動作前會先進行觀察。若儲存庫擁有錯誤的 AGENTS.md，代理程式會停止觀察，因為它認為已經有了答案。它會執行您檔案中指定的指令，而 shell 回傳 Missing script: "test"，接著代理程式便開始進行猜測。它通常會編輯 package.json 以加入您文件中承諾的指令碼。過期的檔案並非無聲無息地失效，而是導致了您不希望發生的編輯。

dox 是解決此問題的一種方案。它是一套為代理程式編寫的規則，將更新文件納入完成工作的一部分，確保檔案與導致其過期的程式碼在同一次 commit 中變更。

什麼是 dox，以及它不是什麼

dox 是一個單一的 Markdown 檔案。該儲存庫位於 agent0ai/dox，採用 MIT 授權。截至 2026 年 8 月 11 日，整個專案僅包含一個 3906 位元組的 AGENTS.md、一份 README、一份 LICENSE 以及兩張圖片。此專案無需安裝任何套件，也沒有執行階段（runtime）。

這一點很重要，因為「產生器」這個詞容易讓人誤以為它是解析程式碼的工具。事實上，沒有任何東西會解析你的程式碼。dox 是你與 AI 程式設計代理（coding agent）之間的合約：代理程式本身就是產生器，而 dox 是一組指令集，用來告知代理何時該讀取文件、何時該重寫文件，以及每份文件的格式規範。

該檔案包含十個章節，其中兩個章節負責核心運作。「編輯前閱讀」（Read Before Editing）指令要求代理從儲存庫根目錄開始，遍歷所有預計修改的路徑，並在當前工作階段中讀取沿途的每一份 AGENTS.md，不得依賴記憶。「編輯後更新」（Update After Editing）則要求代理在進行任何重大變更時，必須執行 DOX 流程，意即在任務完成前必須包含文件更新步驟。當目的、結構、工作流程、權限或使用者偏好發生變更時，此流程會更新最相關的所屬文件。

其餘部分則定義了結構規範。子目錄的 AGENTS.md 預設包含以下章節順序：目的（Purpose）、所有權（Ownership）、本地合約（Local Contracts）、工作指引（Work Guidance）、驗證（Verification）以及子 DOX 索引（Child DOX Index）。根目錄檔案則包含全專案規則以及頂層的子 DOX 索引，這是代理發現子文件的途徑。「結案」（Closeout）是代理在任務結束時執行的檢查清單：對照鏈結重新檢查已變更的路徑、更新最近的所屬文件、重新整理所有受影響的索引、刪除矛盾內容、執行現有的驗證程序，並回報它刻意未更動的文件。

將文件鎖定在特定 commit，而非 main 分支

該儲存庫目前沒有標籤（tags）或發布版本（releases），因此沒有版本號可供鎖定。請改為鎖定 commit。目前的 AGENTS.md 對應的 commit 為 f34ec7ad1055d3393887e5a2670e8cb7320c9165，日期為 2026 年 8 月 1 日。

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

wc -c 應輸出 3906。若顯示其他數字，代表您未取得本指南所述的檔案，請在信任該檔案前先閱讀內容。若 commit hash 輸入錯誤，-f 會導致 curl 停止並顯示 curl: (22) The requested URL returned error: 404，且不會寫入任何內容，隨後 wc -c 會輸出 0。截斷的檔案比沒有檔案更糟，因為代理程式會在不知情的情況下執行一半的合約。

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

該 cp 指令適用於尚未包含 AGENTS.md 的儲存庫。若您已有該檔案，請勿覆蓋。請將文件區段置於現有內容上方，保留您原有的規則在下方，並從頭到尾閱讀一次結果。若兩份文件內容衝突，代理程式會遵循最後讀取到的那一行。

接著，在儲存庫內要求您的代理程式進行第一次處理。README 提供了確切的指令：

Initialize DOX tree for this project now.

此指令會建立子 AGENTS.md 檔案以及指向這些檔案的索引。在信任結果前，請先檢查其執行動作：

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

find 輸出中的每個檔案，都應在上方某處的「子文件索引」（Child DOX Index）中出現。若某個子文件未被任何索引提及，代理程式可能會忽略它，因為索引是代理程式用來尋找不在當前路徑上的文件之依據。

dox 能看見什麼，以及它無法得知什麼

負責建立目錄樹的代理程式會讀取儲存庫，因此儲存庫中的任何內容都可能進入清單：目錄結構、套件清單與鎖定檔、package.json、Makefile 或 pyproject.toml 中的指令碼、CI 工作流程檔案、Dockerfile、進入點，以及若有的話的 CODEOWNERS。由這些內容建立的清單能真正實現自動維護。當套件移動時，下一次執行就會自動更新描述該套件的行。

以下內容必須由您自行說明，因為它們不在儲存庫中，無法被讀取：

• 規則存在的原因，這能防止代理程式因認為其屬於不必要的複雜度而將其移除。
• 在兩條運作路徑中，哪一條是受支援的，哪一條是準備刪除的。
• 儲存庫之外的任何事物，例如預備環境（staging environment），或是為何將相依套件鎖定在兩個版本之前的理由。
• 您下週的計畫，這區分了「當前檔案」與「實用檔案」的差異。

dox 對此有自我認知。其規則規定「工作指引」（Work Guidance）必須反映專案的當前標準或使用者的指示；若尚未有相關規範，則該章節應保持空白。「驗證」（Verification）必須反映現有的檢查機制，因此若儲存庫中沒有測試框架，該章節將保持空白，直到有測試框架為止。由程式產生並憑空捏造標準的檔案，比空白章節更糟糕，因為代理程式會進而強制執行這些虛構的標準。

將手寫意圖排除在自動產生的清單之外

這是導致使用者放棄自動化文件的常見失敗原因。您撰寫了一段說明，強調工作佇列必須維持單一消費者（single consumer）。三週後，自動化流程重寫了該檔案，您的說明段落隨之消失，淹沒在四十行的差異比較（diff）中，且內容多半只是檔案名稱的更動，無人察覺。

您需要同時採用以下兩種機制。

首先，將持久性的意圖移至不同的檔案。設計決策及其背後的邏輯應歸類於 專為代理程式編寫的 DESIGN.md，而給人類閱讀的註記則應歸類於 從 AGENTS.md 分離出的 HUMAN.md。如此一來，AGENTS.md 僅保留清單與本地合約，這正是程式碼變更時理應隨之更新的部分。

其次，將必須保留在 AGENTS.md 內的意圖進行隔離。使用標記將該區塊包覆起來，並將其視為人類所有：

## User Preferences

<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->

Markdown 註解不會在頁面上渲染，但代理程式仍可讀取。現在，請確保該區塊的存續性可被檢查，讓誤刪該區塊的自動化流程發出明顯錯誤。請在每次 pull request 的 CI（持續整合）中執行此檢查：

git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.head

diff 在區塊未被更動時不會輸出任何內容並回傳 0。若有任何輸出，即代表自動化流程重寫了人類所有的文字，此時需由人工審核或還原。此檢查機制無需人工記憶即可自動執行。

在 Pull Request 階段重新產生，而非依賴定時任務

更新文件的最佳時機，是在導致文件過時的提交發生時。將 DOX 處理程序放入與結構變更相同的 Pull Request 中，差異（diff）會小到足以進行實際審閱。

以下是一個強制執行的阻斷式檢查：

#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
  echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
  exit 1
fi

請根據您的儲存庫調整路徑。此機制的價值在於它會在分支上失敗，此時修復成本低廉，且失敗原因明確，審閱者可據此採取行動。

排程任務應作為備援，而非主要機制。每週執行的工作可捕捉到分支上未被察覺的問題：例如經由 rebase 移動的檔案、合併時刪除的套件，或是文件中參照了已不存在的目錄。請在小型伺服器上執行此任務，例如您用來 在 VPS 上執行程式碼代理 的那台，並讓它自動開啟 Pull Request，而非直接推送到 main 分支。

#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fill

該註解刻意留作預留位置。每個代理程式都有各自的 CLI（命令列介面）與非互動式旗標，若直接複製網頁上的指令而未對應您的版本，該指令在 cron 中執行時會失敗，且無人會察覺錯誤。請務必填入正確參數，並在排程前手動執行一次指令。|| exit 0 也至關重要：當目錄樹已是最新狀態時，git commit 會以 nothing to commit, working tree clean 退出，若在 set -e 下，這會導致正常的執行被回報為失敗。

每次執行都會消耗 Token，因為「編輯前先讀取」（Read Before Editing）機制會要求代理程式在每個任務中讀取整個鏈結。這是必要的權衡，如果您已經在 計算代理程式的執行成本，則值得密切關注。

Monorepos：多個合約，單一索引

在包含 40 個套件的儲存庫中，若僅使用一個根目錄的 AGENTS.md，會產生沒人會去閱讀的重新生成差異（diff），且該文件對於代理程式當前執行的任務大多無關。dox 的解決方案是「子 DOX 索引」（Child DOX Index）：根目錄存放全儲存庫通用的規則並指向各子項目，而每個持久性邊界（durable boundary）則擁有自己的檔案。關於如何規劃此樹狀結構，以及哪些工具支援讀取巢狀檔案，請參閱 monorepo 的巢狀 AGENTS.md 檔案。

dox 改變的是審查範圍。一個更動 packages/api 的提取請求（pull request），其文件差異應僅限於 packages/api 內部，而不應出現在其他地方：

git diff --stat -- '*AGENTS.md'

如果該指令針對單一套件的變更列出了 6 個檔案，則代表樹狀結構有誤。這可能是因為邊界劃分過於粗糙，或是本應屬於根目錄的規則被複製到了每個子項目中。dox 直接指出了修正方式：廣泛的規則應放在父層文件，具體的細節則放在子層文件。重複的規則正是導致例行性更新會重寫所有內容的原因。如果相同的規則確實適用於不同的儲存庫，那是另一個問題，此時 跨儲存庫共享代理程式技能 是更合適的工具。

審閱程式碼差異

生成的說明文件差異很容易在未經閱讀的情況下被核准，這正是錯誤檔案發佈的原因。請以審閱生成程式碼的懷疑態度閱讀差異，並檢查以下四點：

• 檔案中提及的指令，在合併前請務必自行執行。虛構的建置說明是最常見的錯誤來源。
• 被刪除的行是否包含重要意圖。新增內容成本低廉，刪除內容才是損失發生之處。
• 絕對路徑、主機名稱、內部 URL，或任何格式類似憑證的內容。
• 針對已不存在項目的清單條目，這類問題可透過 ls 迅速解決。

接著使用 wc -l AGENTS.md 檢查檔案大小。若 root 檔案超過 200 行，即為拆分檔案的訊號，因為此鏈結的核心價值在於讓代理程式僅讀取相關的小部分，而非全部內容。

當系統發生故障時

Pass 刪除了您的 intent 區塊。 上方的 diff 檢查會列印出被移除的行。請使用 git restore --source=origin/main AGENTS.md 從分支點還原檔案，接著以更精確的指令重新執行 pass，並指定其可更動的區段。

兩個分支同時進行了重新生成。 您會在檔案內看到 CONFLICT (content): Merge conflict in AGENTS.md 以及衝突標記 <<<<<<< HEAD。請勿手動編輯這些標記。由於該檔案是由程式生成的，正確的解決方式是對合併後的樹狀結構重新執行一次 pass。

Agent 完全忽略了該檔案。 請檢查您的工具實際讀取的檔案名稱為何。若讀取的是另一個檔案，請使用 ln -s AGENTS.md CLAUDE.md 將其指向相同的內容並提交該符號連結（symlink），這樣您就能維持單一來源，避免兩份文件內容產生差異。

樹狀結構產生了未被索引的子節點。 請比較 find . -name AGENTS.md 的輸出與父文件中索引項目的差異。若某個子節點未被任何索引提及，Agent 在遍歷時將會直接略過它。

何時不需使用產生器

若專案僅包含一個套件、一個測試指令，且兩位維護者皆熟悉儲存庫內容，請直接手寫這 20 行程式碼。一份 20 行的 AGENTS.md 檔案更新頻率極低，不值得為此建置樹狀結構、索引、CI 檢查與每週排程任務。只需在變更建置流程時重新閱讀即可。這是全部的維護成本，且遠低於建置周邊自動化工具的代價。

當儲存庫的邊界已超出單人所能掌握的範圍時，使用 dox 才有價值：例如包含多個規則各異的套件，或是成員加入時缺乏背景知識。其價值不在於產生的文字本身，而在於讓文件成為 Pull Request 的驗收標準之一；這也是儲存庫中任何檔案能保持更新的唯一原因。

FAQ

我需要安裝任何東西才能使用 dox 嗎？

不需要。dox 是一個 Markdown 檔案，採用 MIT 授權。截至 2026 年 8 月 11 日，該儲存庫並未發布任何套件或版本。您只需將其內容複製到專案的 AGENTS.md，您的程式設計代理程式就會遵循其中的規則。請鎖定您複製的 commit（撰寫本文時為 f34ec7ad1055d3393887e5a2670e8cb7320c9165），並在 commit 訊息中註明，以便日後辨識您的程式碼樹是基於哪個版本的規則所建構。

如何防止重新產生（regeneration）刪除我手寫的規則？

請將「意圖」與「清單」分開。持久性的推論應放在獨立的文件中，而任何必須保留在 AGENTS.md 內的內容，應放置於標記區塊內。接著在 CI 中檢查該區塊：從分支與 origin/main 中使用 sed 提取該區塊，再以 diff 比較兩者，若有差異則讓建置失敗。由人工進行審核或還原變更，而非讓變更隱沒在大型 diff 中而不被察覺。

多久應該重新產生一次 AGENTS.md？

在導致規則失效的 pull request 中進行。結構性的變更及其說明文件應屬於同一個 diff，因為只有在該時刻，審核者才具備檢視兩者的背景資訊。每週排程執行的檢查是針對漏網之魚的備援機制，且應開啟 pull request 而非直接 commit 到 main 分支。

建置指令應該放在根目錄的 AGENTS.md 還是子目錄中？

放在擁有該指令的最近文件內。全儲存庫通用的規則與子目錄索引應位於根目錄。適用於單一套件的指令則應放在該套件的 AGENTS.md 中。dox 透過距離來解決衝突：較近的文件控制局部細節，且任何子文件不得削弱父規則。將相同的指令複製到每個子目錄中，正是導致例行性檢查需要重寫整個程式碼樹的原因。

對於小型儲存庫，使用 dox 值得嗎？

通常不值得。若只有一個套件、一個測試指令以及二十行的 AGENTS.md，其規則衰退速度緩慢，您可以在發現問題後的一分鐘內修復。當儲存庫包含多個邊界且規則各異，或是貢獻者缺乏背景知識時，dox 才能發揮其價值，因為此時文件鏈所執行的工作，是單一開發者無法獨力完成的。