使用 ADR 進行開發 是做什麼的？
強制性的第一步：衝突檢查
在詢問領域、建立代理人、調查程式碼或進行修改之前，請先執行隨附的唯讀腳本：
python3 <absolute-skill-directory>/scripts/check_conflicting_skills.py --project <repository-path>
將佔位符解析為實際路徑，並根據需要對路徑加上引號。使用重複的 --available-skill 引數傳遞工作階段可用技能目錄中的每個名稱，包括僅限雲端和附加元件限定名稱。使用 --root 新增非標準的技能目錄；明確新增相關巢狀目錄符號連結的目標。該腳本會發現本機技能檔案和目錄條目，但不會載入其指令或更改安裝。
- 將
grill-me和spec-first視為衝突技能，包括大小寫、空格、底線和連字號變體，例如Grill Me或spec_first。 - 退出碼 0 表示在檢查範圍內未發現衝突。退出碼 1 表示發現衝突，並非腳本失敗。退出碼 2 表示發現不完整：報告錯誤和覆蓋範圍限制，盡可能解決它們，然後重新執行。當覆蓋範圍不完整時，切勿聲稱已檢查所有技能。
- 對於任何匹配項，請在此工作流程中停用它們的使用，並在繼續之前以使用者的語言向使用者發出警告：說明偵測到的技能名稱，並解釋它們僅針對目前工作流程被停用。不要暗示全域解除安裝或帳戶設定變更。對於這些工作流程排除，不需要額外的核准。
- 不要呼叫被排除的技能、遵循它們的指令或將工作委派給它們。將排除清單套用於協調員、架構師和實作員；在每次代理人交接時傳遞排除清單。使用此工作流程自身的澄清和核准步驟。
- 該腳本偵測衝突；協調代理人負責執行排除。即使工作階段目錄顯示某個技能，但其檔案無法存取，也同樣要排除該技能。如果腳本無法執行，請報告該限制，並在未聲明掃描成功的情況下套用已知的排除。
- 在恢復工作階段或可用技能發生變更後重新執行。切勿將偵測到衝突的已安裝技能刪除、重新命名或全域停用，作為此檢查的一部分。
進入與角色
- 在工作流程開始之前，詢問架構師應專注於哪個領域。接受業務或技術領域。如果已經明確提供了領域，則直接使用，無需再次詢問。
- 為所選領域建立一個獨立的架構師代理人，並在整個工作階段中使用。為該代理人提供這些規則、領域、儲存庫路徑和已知的上下文。讓架構師詢問使用者要解決哪個問題；主代理人可以轉達問題和答案。如果問題已經提供，則僅詢問遺漏的資訊。
- 讓主代理人協調對話、文件和上下文交接。讓架構師調查、設計、維護 ADR 並獨立驗證結果。讓一個獨立的實作代理人實作經核准的決策並準備證據。不要合併架構師和實作員的角色。
- 使用環境原生的獨立代理人功能：Codex 中的子代理人和 Claude Code 中可用的代理人/任務功能。不要發明 API 或將單一代理人切換角色呈現為獨立驗證。如果無法使用獨立代理人，請解釋此限制並要求使用者選擇合適的環境。調查可以繼續，但此工作流程下的實作不得開始。
- 在上下文遺失後，從文件和程式碼還原狀態。如果需要建立新的架構師，請不要聲稱原始代理人仍然存在；還原其領域和責任。
調查與決策
- 讓架構師閱讀專案說明、程式碼、相關的 ADR 和證據，並釐清問題和限制。在調查程式碼並釐清問題之前，不要建立 ADR。如果尚無程式碼，請記錄該事實並調查可用的資料。
- 識別與目前決策的衝突。首先向使用者呈現衝突並請求決策；僅在收到回應後才準備新的 ADR。允許準備取代方案，不代表核准其實作。
- 在
docs/adr/中使用範本編寫 ADR。包含簡短的問題陳述、建議的解決方案、理由以及帶有穩定 ID 的可驗證驗收標準。將初始狀態設定為accepted-for-discussion。 - 將獨立的決策分離到不同的 ADR 中，並明確記錄依賴關係。不要引入依賴或取代循環。
- 呈現特定的 ADR 或一個列舉的 ADR 集合，以供使用者明確核准實作。不要因沉默、一般性的建置要求或允許調查而推斷為核准。
- 記錄使用者的回應、日期和核准的文件版本。僅在獲得明確核准後，才將狀態設定為
accepted-for-work。允許明確核准一個列舉的 ADR 集合。
實作
- 僅在 ADR 所依賴的所有 ADR 都完成後，才開始實作該 ADR，即使整個集合都已核准。
- 將 ADR、標準、依賴項和限制提供給實作員。要求實作在核准的決策範圍內進行。
- 如果實作不可行，或者決策或標準需要變更，請停止受影響的工作，並將問題回報給架構師。可以繼續進行其他已核准的獨立工作。
- 在核准後，切勿更改解決方案描述或驗收標準。在新的 ADR 中記錄變更，並單獨核准。
- 讓實作員在
docs/evidence/中準備證據：每個標準的結果、指令和重現步驟，以及經驗證的提交或確切的程式碼版本。不要用未來的提交取代測試的版本。對於未提交的變更，請包含儲存的差異 (diff) 以及所檢查檔案的名稱或雜湊值。
獨立驗證與完成
- 讓架構師親自執行檢查，並將實際結果與每個驗收標準進行比較。實作員的報告和程式碼檢查不能取代執行。
- 在證據中保留指令、環境、結果、日誌連結和經驗證的版本。誠實地標記未執行、受阻或失敗的檢查。不要完成含有未經驗證或未滿足標準的 ADR。
- 如果實作未通過驗證，但 ADR 仍然有效，請先向使用者呈現結果和具體的修正範圍並請求許可。在收到回應之前，不要委派或執行修正。獲得許可後，讓實作員修正問題，並讓架構師再次驗證。再次驗證失敗需要為下一個修正週期重新取得許可。
- 如果失敗需要新的架構決策，請返回調查和新的 ADR 程序。
- 僅允許架構師在成功獨立驗證每個標準後設定
completed狀態。需要提供證據文件的連結。無需額外的使用者核准即可完成 ADR。
狀態與歷史記錄保存
僅使用四個標準的 status 值。以下俄文標籤標識其原始含義；保留現有專案歷史記錄，而不是無聲地改寫舊文件。
| 狀態 | 原始標籤 | 條件 |
|---|---|---|
accepted-for-discussion | принято к обсуждению | 已調查的提案等待討論或核准 |
accepted-for-work | принято к работе | 使用者明確核准了特定的 ADR |
completed | завершен | 架構師獨立驗證了所有標準；已連結證據 |
rejected | отклонено | 存在一個新的已核准 ADR 以及拒絕理由/證據 |
- 切勿刪除 ADR 或證據文件，或重複使用其 ID。在核准之前，允許在記錄重大變更的情況下進行草稿完善。
- 在核准之後，保持解決方案主體和標準不變。允許更新目前狀態和連結，並附加歷史條目。保留較早的條目、證據和驗證結果。不要用通過的結果覆蓋失敗的檢查。
- 在使用者明確核准其取代方案進行工作時，立即將舊的 ADR 標記為「rejected」，包括舊的 ADR 已經完成的情況。立即將舊的 ADR 連結到其取代方案和一個單獨的拒絕理由文件。這證明了舊決策被拒絕的原因；它不證明新的實作有效。
- 保留先前的完成記錄、其日期、版本和證據。明確記錄取代方案可能尚未實作。拒絕文件本身不會移除工作中的程式碼。
- 如果沒有新的決策，不要拒絕 ADR。如果使用者尚未選擇取代方案，請保留目前狀態並附加討論條目。不要為了啟用狀態轉換而發明一個取代方案。
- 如果依賴項被拒絕或取代，請暫停受影響的工作，並讓架構師評估影響。不要無聲地重新安排已核准的決策。
文件圖
- 在建立文件之前閱讀範本，並在使用新環境時閱讀可攜性指南。
- 將 ADR 儲存為
docs/adr/ADR-0001-short-slug.md，並將證據儲存為docs/evidence/EVID-0001-short-slug.md。選擇下一個未使用的編號，同時考慮現有歷史記錄；不要重新編號舊文件。 - 使用明確的相對 Markdown 連結和關係類型：
replaces/replaced_by、depends_on/required_by、extends/extended_by以及evidence/proves。維護反向連結，並確定證據是證明實作還是拒絕的理由。 - 將 ADR 和證據視為圖表的文件；不需要單獨的圖形資料庫。在交接時，檢查連結目標、反向連結、是否存在依賴循環以及狀態條件。
- 在每個步驟結束時，報告 ADR 狀態、結果、文件連結，以及如果正在等待使用者，則報告所需的具體決策。不要將僅獲得核准或已實作但未經驗證的工作描述為已完成。