先講結論：要管好產物去向，唔係一味刪減

測試同文件愈積愈多，的確會令維護同閱讀變得吃力。不過，解法唔應該係「測試全部唔提交」或者「文件全部合併」。比較穩妥嘅做法，係保留長期有用嘅質量資產，將一次性驗證材料隔離，再分開管理三件事：有冇放入原始碼庫、會唔會跟安裝內容一齊分發、模型會唔會讀到。

今次查核屬階段性調研：已取得部分 V4 倉庫靜態資料、Geoffrey Huntley 嘅文章，以及部分學術資料；Python 官方文件布局同 X、Reddit、Hacker News、Lobsters 嘅交叉調研仍未完成。因此以下係根據目前證據提出嘅建議，唔代表已完成全面盡調或已經落實整改。

測試：隔離臨時驗證，唔好隔離質量保障

V4 現況有咩線索？

• CI 設定明確使用集中嘅 tests/ 目錄，涵蓋設定契約、安裝分發同資產保護。單憑測試檔睇落零散，唔足以判斷佢哋係一次性垃圾；今次亦無重跑測試，或者逐項評估其長期維護價值。
• .gitignore 有排除部分沙箱、快取同臨時檔，但未明確列出實際存在嘅草稿區 _bmad-output/scratch/ 同驗證輸出區 _bmad-output/verification/。不過，目錄存在唔等於入面嘅檔案已經畀 Git 跟蹤；今次未有核實索引狀態。
• 更新入口 bs.sh 更新嘅係倉庫；部署來源收集程式讀取嘅就係指定套件。兩者係唔同界線，所以「更新倉庫時見到測試」唔等於「測試會裝入業務運行目錄」。
• 部署來源收集邏輯會遞迴收集套件內嘅一般檔案，再作為插件部署輸入。據此推斷，如果將臨時材料誤放入套件，就有機會一併分發；但目前冇證據顯示呢種情況已經發生。

按用途分，而唔係一刀切

資產類型	版本控制建議	布局與分發建議
長期回歸測試、契約測試、必要整合測試	隨實作提交並持續維護	跟返語言同項目慣例；預設唔放入運行時安裝包
一次性診斷、驗證腳本、實驗輸入	預設留喺本地，唔自動提交	放入獲准嘅任務隔離區；唔好放入套件資產目錄
日誌、覆蓋率資料、運行回執	預設唔放入源碼提交；有需要先按用途保留	同測試源碼分開，亦唔放入安裝包

以上係建議，唔係現行規則已經改好。

Go 官方教學示範喺被測套件同一個目錄加入測試檔；所以，唔應該將「所有 Go 單元測試搬去統一外置目錄」當成硬性方法論。15 Python 呢個倉庫本身已採用集中測試布局，可以先沿用；至於 Python 普遍應該點擺測試，今次未有足夠官方資料支持定論。

如果你想令「一般使用者收到嘅內容乾淨」，應優先檢視發行包或安裝清單；如果你想令「開發用源碼樹整齊啲」，就按語言慣例整理測試布局。搬檔案唔會自動同時解決兩個問題。

文件：收斂職責，唔係追求最少檔案

V4 目前嘅產物路由已區分分析、ADR（架構決策紀錄）、計劃同契約，亦要求歸屬唔清楚時先詢問；但草稿規則仍然提供另一套路徑約定。現有靜態資料支持「產物生命周期規則未完全接通」呢個判斷，但不足以證明每次出現新目錄嘅具體原因。

建議先喺既有結構上講清楚各類文件負責乜，而唔係新增一大批目錄：

• 正式分析：保存證據、比較、反證同未知事項。一般諮詢可以只喺對話交付；無持久化需要，就唔使特登開報告。
• ADR：記錄重要決策、理由同限制；唔好複製整份分析，亦唔好變成執行流水帳。
• 實施計劃：寫清楚授權、範圍、依賴同驗收方式；引用相關決策即可，唔使重複研究正文。
• 臨時材料：草稿、診斷輸入同原始輸出集中放入獲准嘅臨時區；檔名有「草稿」兩個字，唔代表就應該放入正式分析區。
• 長期操作文件：只有真係要做可重用操作手冊先保存；一次部署過程唔應自動變成一個新部署目錄。

文件有幾多份、會唔會提交、會唔會安裝、會唔會畀模型讀取，應該分開決定。全部塞入同一目錄，唔等於完成治理。

Geoffrey Huntley 嘅文章可以帶嚟咩啟示？

Geoffrey Huntley 談到 Agent 背壓時，重點係圍繞 Agent 建立自動化質量同正確性回饋，而唔係將測試檔當成應該刪走嘅噪音。12

佢亦曾喺程式移植情境提出，先將測試行為整理成規格，再用規格指引移植工作。14 呢個係特定移植流程，唔足以證明「所有項目都應該用文件取代測試」。對 V4 較合理嘅啟示係：保留可執行嘅正確性回饋，同時減少重複或一次性驗證材料。規格負責講清楚預期行為；測試就提供可執行嘅反證，兩者唔應未經評估就互相取代。

至於 Geoffrey 有冇一套統一嘅測試提交、草稿目錄同發行排除標準：證據不足。至於相關論壇有冇一致共識：證據不足。今次唔會將未讀過嘅帖子，或者未取得嘅作者倉庫，當成證據。

文件愈長就愈容易令模型幻覺？證據未去到咁遠

長上下文研究討論過，模型未必能有效利用輸入中段嘅資訊；HELMET 研究亦指出，評估長上下文能力需要涵蓋多種任務，唔應只靠簡單檢索測試。34 但呢啲研究唔足以證明「檔案超過某個固定行數就會引發幻覺」，亦未能直接量化 V4 目前嘅風險。

比起盲目減少文件數目，更實際嘅做法係控制模型讀乜：

• 按主題同決策邊界拆分內容，避免一份總文件無止境咁增長。
• 預設只讀同當前任務相關嘅章節；歷史材料需要時再查。
• 摘要保留證據位置、未知事項同未完成責任，原始資料就留作追溯。
• 索引用嚟導航就好，唔好複製正文，整多一份互相打架嘅事實版本。
• 日誌同舊報告唔好預設全文重新餵畀模型。

V4 可以先做嘅最小改進

與其加一套繁複流程，不如補齊一條由建立到交付都適用嘅產物規則：

1. 建立前：講清楚資產用途；優先擴充既有測試或文件，唔好每次改動都機械式新開一份。
2. 保存前：先決定獲准路徑、屬於長期定臨時、會唔會納入版本控制，以及會唔會隨套件發行；未清楚就唔好自行另開目錄。
3. 提交前：檢查臨時輸出、敏感內容、重複測試同重複文件；唔好靠忽略全部測試嚟換取整潔。
4. 分發前：講明安裝資產邊界，避免臨時材料混入套件；亦唔好因為簡化而取消現有摘要、身份同資產保護。
5. 清理前：保護失敗證據、進行中任務同歷史引用；任務完成或者材料過期，唔等於自動獲准刪除。

反向檢視之後，較優先嘅工作係補清臨時材料同發行邊界，其次先統一文件職責同按需讀取。現有證據唔支持全面搬走 Go 單元測試、停止提交長期測試，或者將全部文件合併成一份。

今次只交付調研內容：冇寫入檔案、冇運行終端或測試、冇實施清理，亦冇恢復或推進既有工程計劃。

先講結論：要管好產物去向，唔係一味刪減

測試同文件愈積愈多，的確會令維護同閱讀變得吃力。不過，解法唔應該係「測試全部唔提交」或者「文件全部合併」。比較穩妥嘅做法，係保留長期有用嘅質量資產，將一次性驗證材料隔離，再分開管理三件事：有冇放入原始碼庫、會唔會跟安裝內容一齊分發、模型會唔會讀到。

今次查核屬階段性調研：已取得部分 V4 倉庫靜態資料、Geoffrey Huntley 嘅文章，以及部分學術資料；Python 官方文件布局同 X、Reddit、Hacker News、Lobsters 嘅交叉調研仍未完成。因此以下係根據目前證據提出嘅建議，唔代表已完成全面盡調或已經落實整改。

測試：隔離臨時驗證，唔好隔離質量保障

V4 現況有咩線索？

• CI 設定明確使用集中嘅 tests/ 目錄，涵蓋設定契約、安裝分發同資產保護。單憑測試檔睇落零散，唔足以判斷佢哋係一次性垃圾；今次亦無重跑測試，或者逐項評估其長期維護價值。
• .gitignore 有排除部分沙箱、快取同臨時檔，但未明確列出實際存在嘅草稿區 _bmad-output/scratch/ 同驗證輸出區 _bmad-output/verification/。不過，目錄存在唔等於入面嘅檔案已經畀 Git 跟蹤；今次未有核實索引狀態。
• 更新入口 bs.sh 更新嘅係倉庫；部署來源收集程式讀取嘅就係指定套件。兩者係唔同界線，所以「更新倉庫時見到測試」唔等於「測試會裝入業務運行目錄」。
• 部署來源收集邏輯會遞迴收集套件內嘅一般檔案，再作為插件部署輸入。據此推斷，如果將臨時材料誤放入套件，就有機會一併分發；但目前冇證據顯示呢種情況已經發生。

按用途分，而唔係一刀切

資產類型	版本控制建議	布局與分發建議
長期回歸測試、契約測試、必要整合測試	隨實作提交並持續維護	跟返語言同項目慣例；預設唔放入運行時安裝包
一次性診斷、驗證腳本、實驗輸入	預設留喺本地，唔自動提交	放入獲准嘅任務隔離區；唔好放入套件資產目錄
日誌、覆蓋率資料、運行回執	預設唔放入源碼提交；有需要先按用途保留	同測試源碼分開，亦唔放入安裝包

以上係建議，唔係現行規則已經改好。

Go 官方教學示範喺被測套件同一個目錄加入測試檔；所以，唔應該將「所有 Go 單元測試搬去統一外置目錄」當成硬性方法論。15 Python 呢個倉庫本身已採用集中測試布局，可以先沿用；至於 Python 普遍應該點擺測試，今次未有足夠官方資料支持定論。

如果你想令「一般使用者收到嘅內容乾淨」，應優先檢視發行包或安裝清單；如果你想令「開發用源碼樹整齊啲」，就按語言慣例整理測試布局。搬檔案唔會自動同時解決兩個問題。

文件：收斂職責，唔係追求最少檔案

V4 目前嘅產物路由已區分分析、ADR（架構決策紀錄）、計劃同契約，亦要求歸屬唔清楚時先詢問；但草稿規則仍然提供另一套路徑約定。現有靜態資料支持「產物生命周期規則未完全接通」呢個判斷，但不足以證明每次出現新目錄嘅具體原因。

建議先喺既有結構上講清楚各類文件負責乜，而唔係新增一大批目錄：

• 正式分析：保存證據、比較、反證同未知事項。一般諮詢可以只喺對話交付；無持久化需要，就唔使特登開報告。
• ADR：記錄重要決策、理由同限制；唔好複製整份分析，亦唔好變成執行流水帳。
• 實施計劃：寫清楚授權、範圍、依賴同驗收方式；引用相關決策即可，唔使重複研究正文。
• 臨時材料：草稿、診斷輸入同原始輸出集中放入獲准嘅臨時區；檔名有「草稿」兩個字，唔代表就應該放入正式分析區。
• 長期操作文件：只有真係要做可重用操作手冊先保存；一次部署過程唔應自動變成一個新部署目錄。

文件有幾多份、會唔會提交、會唔會安裝、會唔會畀模型讀取，應該分開決定。全部塞入同一目錄，唔等於完成治理。

Geoffrey Huntley 嘅文章可以帶嚟咩啟示？

Geoffrey Huntley 談到 Agent 背壓時，重點係圍繞 Agent 建立自動化質量同正確性回饋，而唔係將測試檔當成應該刪走嘅噪音。12

佢亦曾喺程式移植情境提出，先將測試行為整理成規格，再用規格指引移植工作。14 呢個係特定移植流程，唔足以證明「所有項目都應該用文件取代測試」。對 V4 較合理嘅啟示係：保留可執行嘅正確性回饋，同時減少重複或一次性驗證材料。規格負責講清楚預期行為；測試就提供可執行嘅反證，兩者唔應未經評估就互相取代。

至於 Geoffrey 有冇一套統一嘅測試提交、草稿目錄同發行排除標準：證據不足。至於相關論壇有冇一致共識：證據不足。今次唔會將未讀過嘅帖子，或者未取得嘅作者倉庫，當成證據。

文件愈長就愈容易令模型幻覺？證據未去到咁遠

長上下文研究討論過，模型未必能有效利用輸入中段嘅資訊；HELMET 研究亦指出，評估長上下文能力需要涵蓋多種任務，唔應只靠簡單檢索測試。34 但呢啲研究唔足以證明「檔案超過某個固定行數就會引發幻覺」，亦未能直接量化 V4 目前嘅風險。

比起盲目減少文件數目，更實際嘅做法係控制模型讀乜：

• 按主題同決策邊界拆分內容，避免一份總文件無止境咁增長。
• 預設只讀同當前任務相關嘅章節；歷史材料需要時再查。
• 摘要保留證據位置、未知事項同未完成責任，原始資料就留作追溯。
• 索引用嚟導航就好，唔好複製正文，整多一份互相打架嘅事實版本。
• 日誌同舊報告唔好預設全文重新餵畀模型。

V4 可以先做嘅最小改進

與其加一套繁複流程，不如補齊一條由建立到交付都適用嘅產物規則：

1. 建立前：講清楚資產用途；優先擴充既有測試或文件，唔好每次改動都機械式新開一份。
2. 保存前：先決定獲准路徑、屬於長期定臨時、會唔會納入版本控制，以及會唔會隨套件發行；未清楚就唔好自行另開目錄。
3. 提交前：檢查臨時輸出、敏感內容、重複測試同重複文件；唔好靠忽略全部測試嚟換取整潔。
4. 分發前：講明安裝資產邊界，避免臨時材料混入套件；亦唔好因為簡化而取消現有摘要、身份同資產保護。
5. 清理前：保護失敗證據、進行中任務同歷史引用；任務完成或者材料過期，唔等於自動獲准刪除。

反向檢視之後，較優先嘅工作係補清臨時材料同發行邊界，其次先統一文件職責同按需讀取。現有證據唔支持全面搬走 Go 單元測試、停止提交長期測試，或者將全部文件合併成一份。

今次只交付調研內容：冇寫入檔案、冇運行終端或測試、冇實施清理，亦冇恢復或推進既有工程計劃。