文件治理，重點不在目錄長什麼樣

設計 AI Agent 專案文件時，容易把討論收斂成「該不該有某個目錄」或「入口文件應該限制幾行」。但比起統一目錄，更值得先釐清的是：每份文件負責什麼、哪裡才是權威來源、何時應保留或淘汰，以及 Agent 要如何找到它。

BMAD 的任務治理與藍圖的知識分類可以互補；然而，計畫保留、跨宿主載入、測試隔離和文件預算都必須分開定義，不能期待目錄名稱自動解決問題。

BMAD 帶來的四項治理思路

本次分析依據讀取到的本地快照。該快照的 README.md 將目前分支描述為 V7 預覽、v6.12 為穩定路線；這只反映該快照的說法，不代表目前最新的發布狀態。

從 BMAD 的文件與工作流程，可以歸納出四項值得借鏡的做法：

• 方法與定制分開： 將預設資產、團隊覆寫與個人覆寫分層，盡量只保存必要的差異，避免整份複製預設內容，日後更新時反而難以追上。
• 文件歸屬對應工作： 以 initiative、epic 和較小的任務形成工作樹，讓需求、設計、實施計畫與回顧能對應到所屬工作；跨倉庫規劃則可獨立保存。
• 細節逐步展開： 先保留故事或任務條目，在細化、發布或建置時再補上必要文件與驗收內容，減少太早產生、很快就過時的細節。
• 完成計畫仍有價值： 已完成的計畫可以記錄狀態、起始版本、實施證據與審查發現。若直接刪除，完成過的工作可能又像是尚未處理，也會失去追溯線索。

因此，BMAD 值得參考的不是某一套固定目錄，而是讓工作有歸屬、引用有穩定身分、狀態有明確依據，完成也留下證據。

藍圖與 BMAD，處理的不是同一層問題

藍圖較像是專案知識如何分類的方案；BMAD 則更接近交付流程及其文件存放方式。兩者並非只能擇一，適用情境也不同：

• 單人、小型、順序進行的專案： 一個目前工作焦點，加上依領域讀取文件，通常足以維持簡潔。不過，活動中的摘要或視圖應指向任務記錄，不應覆寫唯一的歷史契約。
• 團隊協作、平行任務或跨倉庫工作： 穩定的任務身分與獨立計畫較有用。「唯一活動計畫」適合描述某個工作階段的焦點，不宜解讀成整個團隊只能共用一份會被改寫的文件。
• 原生 Agent： 通常需要少量常駐規則，以及清楚的文件讀取路徑；不必因此導入完整的方法框架。
• 擴充治理機制的專案： 可以加入控制器、狀態視圖或證據檢查，但前提是這些機制確實存在並且會執行。提示文字和靜態目錄本身並不能取代它們。

五項容易過度簡化的規則

1. 完成後覆寫，不如保留契約、精簡視圖

若完成一項工作就把計畫覆寫掉，固然能讓預設檢視保持簡短，卻可能失去工作狀態和來源脈絡。比較穩妥的做法，是讓舊內容退出日常閱讀範圍，但保留可追溯的記錄。

2. 跨 Agent 載入，要逐一驗證

不同宿主對指引檔案的名稱、搜尋位置與載入方式不盡相同。BMAD 也要求確認載入機制，尤其是巢狀規則是否生效。OpenAI 的工作流程範例則區分 Codex 可識別的 AGENTS.md，與可依專案調整的其他工作流程檔案約定。6 因此，不宜宣稱只要放一份通用引導文件，就能保證所有 Agent 正確載入。

3. 文件長度應是編輯預算，不是幻覺門檻

固定行數不能當作跨模型的失效界線。更實際的檢視項目包括：實際載入多少內容、是否重複，以及分拆文件後會不會讓必要的語意關係變得難以理解。不要為了達到行數門檻，把完整契約切得七零八落。

4. 測試夾具不等於執行產物

固定、脫敏且可重現的測試資料，和單次執行產生的日誌或輸出，並不是同一類資產。應分別說明單元、整合、端對端和真實環境驗證的環境條件與副作用，而不是一概禁止某種檔案格式。

5. 忽略規則不等於歷史保存政策

若文件一方面規定歸檔資料不得提交，另一方面又期待透過 Git 歷史在不同機器上查閱，兩者便互相牴觸。忽略配置、預設不檢索，以及禁止存取，也應視為不同政策，分別設計。

業界案例支持的是原則，不是單一拓樸

Geoffrey Huntley 的 Ralph 原文描述以單一程序循環處理工作、每輪聚焦一項任務，也展示了針對特定規格範圍執行工作的提示方式。14 他名下的指南則示範按關注點整理領域規格，並把建置與測試的操作經驗放進專案入口文件。11

這些案例支持的是「任務要小、規格要清楚、上下文要有限，並以實際回饋檢驗結果」，而不是「所有專案都該使用同一種目錄」。OpenAI 的複雜任務範例也採用較詳盡、可持續更新的執行計畫，顯示精簡的常駐入口文件可以和完整的任務契約並存。5

實務上可採取幾個原則：常駐規則保持精簡，任務計畫則依風險與持續時間展開；領域文件依關注點整理，同時確保跨領域的不變條件容易找到；若工作流程會重新啟動，應重建完成目前任務所需的上下文，而不是試圖重載所有聊天歷史；建置與測試入口則應明確記錄命令及其環境前提。

關於 overalls.dev 的具體測試隔離主張，現有證據不足以在此作出判斷。其他 Ralph 實作或社群整理也不能直接當成 Huntley 本人的原始規範。相鄰的 Ralph 專案自述採用其方法，但那屬於衍生實作，而非作者原始指引。

可落地的文件治理原則

1. 依資訊權威分類，而非依撰寫者分類。 人工撰寫不等於正確，機器生成也不必然短命。應區分政策、已核驗事實、目標提案、任務狀態、驗證證據與探索草稿。
2. 每項關鍵事實只保留一個可編輯的權威來源。 索引與摘要可以重述資訊，但應標明來源、版本和失效條件；避免計畫、規格、ADR 與狀態卡各自維護同一份進度。
3. 優先記錄原始碼無法回答的知識。 例如設計意圖、被否決的理由、外部限制與跨元件責任歸屬。靜態掃描可以協助理解程式結構，卻不能單獨證明業務規則或歷史決策動機。
4. 入口文件負責約束與導覽，不必成為百科全書。 讀取路由應使用可觀察的條件，例如目標路徑、介面或任務類型；只寫「複雜時再讀」，會把必要的文件讀取交給模糊判斷。
5. 規格、狀態與證據各司其職。 規格說明必須符合什麼，狀態說明進度到哪裡，證據說明憑什麼認定已符合。三者可以放在一起，但權威關係要清楚。
6. 壓縮內容時，不要丟掉恢復工作所需資訊。 未完成事項、阻塞、依賴、授權界線和證據位置都應保留；過去曾成功，也不代表新的執行實例自動通過驗證。
7. 讓歷史可追溯，也讓現行規則易辨識。 決策可以被新決策取代，但應保留原始依據及取代關係；領域規格應連結目前有效的決定，不必反覆累積整段歷史。
8. 把測試原始資料與執行輸出分開管理。 尊重各語言生態既有的測試位置，並依敏感程度、檔案體積與保留期限治理執行輸出，不要一概當成垃圾。
9. 能由工具檢查的規則，就交給實際檢查機制。 格式、受保護路徑和確定性契約，優先用工具驗證。把規則移到一份沒人讀的文件不算減負；在檢查機制覆蓋前，也不能視為文字約束已被取代。
10. 目錄約定不能擴大權限。 文件生成、執行命令、對外連線、部署與封存應分別授權；草稿資料夾不是執行環境的安全邊界。

較穩健的演進順序，是先定義文件用途與權威關係，再建立各宿主的載入適配，接著提供精簡的活動視圖，最後根據真實任務調整文件預算與保留策略。與其先全面搬動目錄，不如先把責任與規則說清楚。

證據與交付範圍

本次交付僅整理分析，沒有寫入檔案、執行終端命令、跑測試、安裝套件或啟用宿主。文中的建議屬於治理方向，不構成實施授權。

此外，先前答覆中關於 Claude Code 特定版本行為及「Found in the Middle」的說法，缺乏本次可定位的證據，因此不再作為已核實依據。具體行數門檻、跨宿主載入保證及普遍收益比例，也沒有足夠證據支持。

文件治理，重點不在目錄長什麼樣

設計 AI Agent 專案文件時，容易把討論收斂成「該不該有某個目錄」或「入口文件應該限制幾行」。但比起統一目錄，更值得先釐清的是：每份文件負責什麼、哪裡才是權威來源、何時應保留或淘汰，以及 Agent 要如何找到它。

BMAD 的任務治理與藍圖的知識分類可以互補；然而，計畫保留、跨宿主載入、測試隔離和文件預算都必須分開定義，不能期待目錄名稱自動解決問題。

BMAD 帶來的四項治理思路

本次分析依據讀取到的本地快照。該快照的 README.md 將目前分支描述為 V7 預覽、v6.12 為穩定路線；這只反映該快照的說法，不代表目前最新的發布狀態。

從 BMAD 的文件與工作流程，可以歸納出四項值得借鏡的做法：

• 方法與定制分開： 將預設資產、團隊覆寫與個人覆寫分層，盡量只保存必要的差異，避免整份複製預設內容，日後更新時反而難以追上。
• 文件歸屬對應工作： 以 initiative、epic 和較小的任務形成工作樹，讓需求、設計、實施計畫與回顧能對應到所屬工作；跨倉庫規劃則可獨立保存。
• 細節逐步展開： 先保留故事或任務條目，在細化、發布或建置時再補上必要文件與驗收內容，減少太早產生、很快就過時的細節。
• 完成計畫仍有價值： 已完成的計畫可以記錄狀態、起始版本、實施證據與審查發現。若直接刪除，完成過的工作可能又像是尚未處理，也會失去追溯線索。

因此，BMAD 值得參考的不是某一套固定目錄，而是讓工作有歸屬、引用有穩定身分、狀態有明確依據，完成也留下證據。

藍圖與 BMAD，處理的不是同一層問題

藍圖較像是專案知識如何分類的方案；BMAD 則更接近交付流程及其文件存放方式。兩者並非只能擇一，適用情境也不同：

• 單人、小型、順序進行的專案： 一個目前工作焦點，加上依領域讀取文件，通常足以維持簡潔。不過，活動中的摘要或視圖應指向任務記錄，不應覆寫唯一的歷史契約。
• 團隊協作、平行任務或跨倉庫工作： 穩定的任務身分與獨立計畫較有用。「唯一活動計畫」適合描述某個工作階段的焦點，不宜解讀成整個團隊只能共用一份會被改寫的文件。
• 原生 Agent： 通常需要少量常駐規則，以及清楚的文件讀取路徑；不必因此導入完整的方法框架。
• 擴充治理機制的專案： 可以加入控制器、狀態視圖或證據檢查，但前提是這些機制確實存在並且會執行。提示文字和靜態目錄本身並不能取代它們。

五項容易過度簡化的規則

1. 完成後覆寫，不如保留契約、精簡視圖

若完成一項工作就把計畫覆寫掉，固然能讓預設檢視保持簡短，卻可能失去工作狀態和來源脈絡。比較穩妥的做法，是讓舊內容退出日常閱讀範圍，但保留可追溯的記錄。

2. 跨 Agent 載入，要逐一驗證

不同宿主對指引檔案的名稱、搜尋位置與載入方式不盡相同。BMAD 也要求確認載入機制，尤其是巢狀規則是否生效。OpenAI 的工作流程範例則區分 Codex 可識別的 AGENTS.md，與可依專案調整的其他工作流程檔案約定。6 因此，不宜宣稱只要放一份通用引導文件，就能保證所有 Agent 正確載入。

3. 文件長度應是編輯預算，不是幻覺門檻

固定行數不能當作跨模型的失效界線。更實際的檢視項目包括：實際載入多少內容、是否重複，以及分拆文件後會不會讓必要的語意關係變得難以理解。不要為了達到行數門檻，把完整契約切得七零八落。

4. 測試夾具不等於執行產物

固定、脫敏且可重現的測試資料，和單次執行產生的日誌或輸出，並不是同一類資產。應分別說明單元、整合、端對端和真實環境驗證的環境條件與副作用，而不是一概禁止某種檔案格式。

5. 忽略規則不等於歷史保存政策

若文件一方面規定歸檔資料不得提交，另一方面又期待透過 Git 歷史在不同機器上查閱，兩者便互相牴觸。忽略配置、預設不檢索，以及禁止存取，也應視為不同政策，分別設計。

業界案例支持的是原則，不是單一拓樸

Geoffrey Huntley 的 Ralph 原文描述以單一程序循環處理工作、每輪聚焦一項任務，也展示了針對特定規格範圍執行工作的提示方式。14 他名下的指南則示範按關注點整理領域規格，並把建置與測試的操作經驗放進專案入口文件。11

這些案例支持的是「任務要小、規格要清楚、上下文要有限，並以實際回饋檢驗結果」，而不是「所有專案都該使用同一種目錄」。OpenAI 的複雜任務範例也採用較詳盡、可持續更新的執行計畫，顯示精簡的常駐入口文件可以和完整的任務契約並存。5

實務上可採取幾個原則：常駐規則保持精簡，任務計畫則依風險與持續時間展開；領域文件依關注點整理，同時確保跨領域的不變條件容易找到；若工作流程會重新啟動，應重建完成目前任務所需的上下文，而不是試圖重載所有聊天歷史；建置與測試入口則應明確記錄命令及其環境前提。

關於 overalls.dev 的具體測試隔離主張，現有證據不足以在此作出判斷。其他 Ralph 實作或社群整理也不能直接當成 Huntley 本人的原始規範。相鄰的 Ralph 專案自述採用其方法，但那屬於衍生實作，而非作者原始指引。

可落地的文件治理原則

1. 依資訊權威分類，而非依撰寫者分類。 人工撰寫不等於正確，機器生成也不必然短命。應區分政策、已核驗事實、目標提案、任務狀態、驗證證據與探索草稿。
2. 每項關鍵事實只保留一個可編輯的權威來源。 索引與摘要可以重述資訊，但應標明來源、版本和失效條件；避免計畫、規格、ADR 與狀態卡各自維護同一份進度。
3. 優先記錄原始碼無法回答的知識。 例如設計意圖、被否決的理由、外部限制與跨元件責任歸屬。靜態掃描可以協助理解程式結構，卻不能單獨證明業務規則或歷史決策動機。
4. 入口文件負責約束與導覽，不必成為百科全書。 讀取路由應使用可觀察的條件，例如目標路徑、介面或任務類型；只寫「複雜時再讀」，會把必要的文件讀取交給模糊判斷。
5. 規格、狀態與證據各司其職。 規格說明必須符合什麼，狀態說明進度到哪裡，證據說明憑什麼認定已符合。三者可以放在一起，但權威關係要清楚。
6. 壓縮內容時，不要丟掉恢復工作所需資訊。 未完成事項、阻塞、依賴、授權界線和證據位置都應保留；過去曾成功，也不代表新的執行實例自動通過驗證。
7. 讓歷史可追溯，也讓現行規則易辨識。 決策可以被新決策取代，但應保留原始依據及取代關係；領域規格應連結目前有效的決定，不必反覆累積整段歷史。
8. 把測試原始資料與執行輸出分開管理。 尊重各語言生態既有的測試位置，並依敏感程度、檔案體積與保留期限治理執行輸出，不要一概當成垃圾。
9. 能由工具檢查的規則，就交給實際檢查機制。 格式、受保護路徑和確定性契約，優先用工具驗證。把規則移到一份沒人讀的文件不算減負；在檢查機制覆蓋前，也不能視為文字約束已被取代。
10. 目錄約定不能擴大權限。 文件生成、執行命令、對外連線、部署與封存應分別授權；草稿資料夾不是執行環境的安全邊界。

較穩健的演進順序，是先定義文件用途與權威關係，再建立各宿主的載入適配，接著提供精簡的活動視圖，最後根據真實任務調整文件預算與保留策略。與其先全面搬動目錄，不如先把責任與規則說清楚。

證據與交付範圍

本次交付僅整理分析，沒有寫入檔案、執行終端命令、跑測試、安裝套件或啟用宿主。文中的建議屬於治理方向，不構成實施授權。

此外，先前答覆中關於 Claude Code 特定版本行為及「Found in the Middle」的說法，缺乏本次可定位的證據，因此不再作為已核實依據。具體行數門檻、跨宿主載入保證及普遍收益比例，也沒有足夠證據支持。