先問「邊份先算數」，再諗放喺邊個資料夾

AI 編碼代理嘅項目文件愈堆愈多，最易出事嘅未必係目錄唔夠整齊，而係同一件事有幾份文件各自講法：規則互相矛盾、任務狀態重複更新，或者做完之後連點解當初咁做都搵唔返。

所以，治理嘅重點唔應該係強制所有項目用同一套目錄，而係講清楚四件事：文件負責乜、邊份係權威來源、幾時要更新或保留，以及代理喺乜情況下要讀佢。

BMAD 比較似一套交付工作流同文件管理協定；藍圖式方案就偏向整理項目知識。兩者處理嘅層面唔完全相同，可以借用彼此做法，唔使二揀一。

BMAD 值得借鏡嘅係治理方法

BMAD 嘅做法可以概括為幾個原則：

• 方法同定制分開。 將預設資產、團隊覆蓋設定同個人調整分層；有需要先加覆蓋，避免複製成套預設內容，日後更新時反而難跟。
• 文件跟住工作歸屬走。 initiative、epic 同較細嘅任務形成工作樹，需求、設計、實施計劃同回顧就連返所屬工作。
• 細節可以逐步補。 先記低待辦項目，去到需要細化或實施時先補齊詳細文件，減少過早寫好、之後又過時嘅內容。
• 完成嘅計劃仍然有歷史價值。 計劃可以記錄狀態、起始版本、實施證據同審查發現。若直接刪走，已完成嘅工作有機會再次睇落似未開始。

重點唔係照搬某個目錄名，而係令每份文件有明確歸屬、引用有穩定身份、狀態有權威來源，完成與否亦有證據支持。

藍圖式分類要小心五個「一刀切」

1. 做完就覆寫：改成保留紀錄、收起舊內容

活動視圖可以只展示而家要做嘅工作，但唔代表要覆寫唯一一份任務契約。舊計劃可以唔再預設載入，同時保留狀態同溯源資料。

2. 一份橋接文件通行所有工具：改為逐個宿主驗證

唔同 Agent 宿主對指引檔案嘅支援同載入方式可以唔同。OpenAI 嘅工作流示例就指出，Codex 會識別 AGENTS.md，但其他建議用嘅工作流檔案屬於可調整約定，唔係工具必須使用嘅檔案。6 所以，唔好單靠檔名或一行引導語，就當跨工具兼容已經搞掂。

3. 用固定行數防止幻覺：改成檢視實際負擔

某份文件幾多行，唔足以單獨判斷代理會唔會漏讀或誤解。更值得檢查嘅係：載入咗幾多重複內容、有冇重要依賴被拆散，以及讀者可唔可以根據清楚條件搵到必要規則。唔好為咗符合行數而將一個完整契約硬生生拆開。

4. 測試目錄唔准有 JSON：先分清測試夾具同運行輸出

固定、去敏感資料、可以重現嘅測試資料，同一次測試跑出嚟嘅日誌或暫存檔，唔係同一類資產。應該分開說明測試類型、執行環境、副作用同產物去向，而唔係見到 JSON 就一概當成垃圾。

5. 忽略資料夾兼做歷史庫：分開處理保存同檢索

「預設唔讀」、「Git 唔追蹤」同「禁止存取」係三種唔同安排。若一邊要求檔案忽略某啲資料，一邊又期望靠 Git 歷史跨機器追溯，做法本身就可能互相矛盾。敏感資料同一般舊紀錄亦應分開設計保存方法。

長期指引要精簡，長任務計劃可以詳細

Ralph 嘅資料強調每個循環集中處理一件事，而非一輪塞入多個目標。14 相關指南亦展示按關注範圍整理規格，並將建置、測試方面嘅操作經驗放喺項目指引內。11

呢啲例子支持嘅方向係：任務細分、規格清楚、上下文有限，而且有實際回饋；唔代表所有項目都必須用同一種目錄拓撲。另一方面，OpenAI 嘅複雜任務示例亦使用較詳細、可持續更新嘅計劃文件。5 即係話，平時常駐載入嘅入口可以短，遇到長任務時仍然可以另備足夠詳細嘅任務契約。

實際上可以咁安排：

• 常駐規則保持精簡，清楚講邊類任務要讀邊份資料。
• 閱讀路由盡量用可觀察條件，例如目標路徑、涉及介面或任務類型，而唔係只寫「複雜時再讀」。
• 詳細計劃按任務風險同持續時間提供，唔需要每件小事都寫成長篇文件。
• 新一輪工作要重建足夠嘅當前任務上下文，唔等於要載入全部聊天紀錄。

一套較易維護嘅文件分工

1. 規則文件：講清楚必須遵守嘅要求、權限邊界同禁區。
2. 事實與領域規格：記錄源碼未必交代到嘅背景、業務規則、跨組件責任同已核實限制。
3. 任務計劃與狀態：說明目標、進度、阻塞、依賴同未完成事項，並指定唯一權威狀態來源。
4. 驗證證據：記錄憑乜判斷工作完成，例如實際檢查結果；唔好將以前做成功一次，當成新一輪工作已驗證。
5. 歷史與索引：保留重要決定同被取代嘅關係，但令現行有效規則容易辨認。

摘要同索引可以重述資訊，但應標明來源、版本或失效條件，避免計劃、規格同狀態卡各自維護同一份進度。測試源文件亦應同運行產物分開管理；檔案放喺草稿目錄，唔會自動令相關操作變成安全或獲授權。

由職責開始，唔好一開始就搬晒目錄

較穩陣嘅演進次序係：先定義文件職責同權威關係，再逐個宿主確認載入方式；之後先整理精簡活動視圖，最後按實際任務檢討閱讀負擔同保存期限。格式檢查、保護路徑等可以由工具可靠執行嘅規則，就用真實檢查機制處理；未有機制覆蓋之前，唔好當文字規則已經可以刪走。

簡單講，目錄係收納方法，唔係治理本身。只要每類資訊有清楚嘅權威來源、生命周期同閱讀條件，唔同項目就可以按需要採用唔同結構，而唔使靠一套萬用模板硬套。

先問「邊份先算數」，再諗放喺邊個資料夾

AI 編碼代理嘅項目文件愈堆愈多，最易出事嘅未必係目錄唔夠整齊，而係同一件事有幾份文件各自講法：規則互相矛盾、任務狀態重複更新，或者做完之後連點解當初咁做都搵唔返。

所以，治理嘅重點唔應該係強制所有項目用同一套目錄，而係講清楚四件事：文件負責乜、邊份係權威來源、幾時要更新或保留，以及代理喺乜情況下要讀佢。

BMAD 比較似一套交付工作流同文件管理協定；藍圖式方案就偏向整理項目知識。兩者處理嘅層面唔完全相同，可以借用彼此做法，唔使二揀一。

BMAD 值得借鏡嘅係治理方法

BMAD 嘅做法可以概括為幾個原則：

• 方法同定制分開。 將預設資產、團隊覆蓋設定同個人調整分層；有需要先加覆蓋，避免複製成套預設內容，日後更新時反而難跟。
• 文件跟住工作歸屬走。 initiative、epic 同較細嘅任務形成工作樹，需求、設計、實施計劃同回顧就連返所屬工作。
• 細節可以逐步補。 先記低待辦項目，去到需要細化或實施時先補齊詳細文件，減少過早寫好、之後又過時嘅內容。
• 完成嘅計劃仍然有歷史價值。 計劃可以記錄狀態、起始版本、實施證據同審查發現。若直接刪走，已完成嘅工作有機會再次睇落似未開始。

重點唔係照搬某個目錄名，而係令每份文件有明確歸屬、引用有穩定身份、狀態有權威來源，完成與否亦有證據支持。

藍圖式分類要小心五個「一刀切」

1. 做完就覆寫：改成保留紀錄、收起舊內容

活動視圖可以只展示而家要做嘅工作，但唔代表要覆寫唯一一份任務契約。舊計劃可以唔再預設載入，同時保留狀態同溯源資料。

2. 一份橋接文件通行所有工具：改為逐個宿主驗證

唔同 Agent 宿主對指引檔案嘅支援同載入方式可以唔同。OpenAI 嘅工作流示例就指出，Codex 會識別 AGENTS.md，但其他建議用嘅工作流檔案屬於可調整約定，唔係工具必須使用嘅檔案。6 所以，唔好單靠檔名或一行引導語，就當跨工具兼容已經搞掂。

3. 用固定行數防止幻覺：改成檢視實際負擔

某份文件幾多行，唔足以單獨判斷代理會唔會漏讀或誤解。更值得檢查嘅係：載入咗幾多重複內容、有冇重要依賴被拆散，以及讀者可唔可以根據清楚條件搵到必要規則。唔好為咗符合行數而將一個完整契約硬生生拆開。

4. 測試目錄唔准有 JSON：先分清測試夾具同運行輸出

固定、去敏感資料、可以重現嘅測試資料，同一次測試跑出嚟嘅日誌或暫存檔，唔係同一類資產。應該分開說明測試類型、執行環境、副作用同產物去向，而唔係見到 JSON 就一概當成垃圾。

5. 忽略資料夾兼做歷史庫：分開處理保存同檢索

「預設唔讀」、「Git 唔追蹤」同「禁止存取」係三種唔同安排。若一邊要求檔案忽略某啲資料，一邊又期望靠 Git 歷史跨機器追溯，做法本身就可能互相矛盾。敏感資料同一般舊紀錄亦應分開設計保存方法。

長期指引要精簡，長任務計劃可以詳細

Ralph 嘅資料強調每個循環集中處理一件事，而非一輪塞入多個目標。14 相關指南亦展示按關注範圍整理規格，並將建置、測試方面嘅操作經驗放喺項目指引內。11

呢啲例子支持嘅方向係：任務細分、規格清楚、上下文有限，而且有實際回饋；唔代表所有項目都必須用同一種目錄拓撲。另一方面，OpenAI 嘅複雜任務示例亦使用較詳細、可持續更新嘅計劃文件。5 即係話，平時常駐載入嘅入口可以短，遇到長任務時仍然可以另備足夠詳細嘅任務契約。

實際上可以咁安排：

• 常駐規則保持精簡，清楚講邊類任務要讀邊份資料。
• 閱讀路由盡量用可觀察條件，例如目標路徑、涉及介面或任務類型，而唔係只寫「複雜時再讀」。
• 詳細計劃按任務風險同持續時間提供，唔需要每件小事都寫成長篇文件。
• 新一輪工作要重建足夠嘅當前任務上下文，唔等於要載入全部聊天紀錄。

一套較易維護嘅文件分工

1. 規則文件：講清楚必須遵守嘅要求、權限邊界同禁區。
2. 事實與領域規格：記錄源碼未必交代到嘅背景、業務規則、跨組件責任同已核實限制。
3. 任務計劃與狀態：說明目標、進度、阻塞、依賴同未完成事項，並指定唯一權威狀態來源。
4. 驗證證據：記錄憑乜判斷工作完成，例如實際檢查結果；唔好將以前做成功一次，當成新一輪工作已驗證。
5. 歷史與索引：保留重要決定同被取代嘅關係，但令現行有效規則容易辨認。

摘要同索引可以重述資訊，但應標明來源、版本或失效條件，避免計劃、規格同狀態卡各自維護同一份進度。測試源文件亦應同運行產物分開管理；檔案放喺草稿目錄，唔會自動令相關操作變成安全或獲授權。

由職責開始，唔好一開始就搬晒目錄

較穩陣嘅演進次序係：先定義文件職責同權威關係，再逐個宿主確認載入方式；之後先整理精簡活動視圖，最後按實際任務檢討閱讀負擔同保存期限。格式檢查、保護路徑等可以由工具可靠執行嘅規則，就用真實檢查機制處理；未有機制覆蓋之前，唔好當文字規則已經可以刪走。

簡單講，目錄係收納方法，唔係治理本身。只要每類資訊有清楚嘅權威來源、生命周期同閱讀條件，唔同項目就可以按需要採用唔同結構，而唔使靠一套萬用模板硬套。