指令用途

在專案演進中，最難保留的是設計脈絡 (Design Context)。新加入的工程師常常會發出疑惑：「為什麼這個資料庫要設計成非同步連線池？」、「為什麼 PLC 通訊不用 TCP 而是要用語意 Modbus？」如果沒有記錄，這些歷史決策很快就會隨著人員離職而遺失，導致後續重構無意間破壞了當初的底層設計。

manage_adr 是 Codebase Memory 用於架構決策維護的工具。它允許開發者與 AI 助手，在專案中以標準的 ADR 格式（如 Markdown 規範）在 .adr/ 目錄下自動建立、列出並關聯架構決策，使整個專案的「設計意圖」也成為知識圖譜可檢索的一部分。

運作流程

1. 指令接收：接收 action (如 create, list, show) 與對應參數。
2. 範本套用：若是 create，工具會自動套用 MADR 格式，引進 Context (背景)、Decision (決策)、Consequences (後果) 等結構。
3. 圖譜關聯：將新建立的 ADR 檔案作為一個圖節點併入知識圖譜，並與受影響的類別程式碼節點建立 AFFECTS 關係邊。
4. 回傳與展示：回傳已建立的 ADR 詳情。

實戰對話範例

範例：建立 PLC 逾時設定的 ADR

• You:

  /opsx:explore "今天我們決定將 PLC 連線的超時時間從 30 秒改為 60 秒以防超載。請幫我記錄一筆 ADR。"

• AI:

  好的，為了記錄這個重要的架構參數變更，我將呼叫 codebase-memory 的 manage_adr 工具建立一筆 ADR。

  CM 呼叫:

  manage_adr(
    action: "create",
    title: "將 PLC 連線超時延長至 60 秒",
    context: "現場高負載尖峰網路延遲常超過 30 秒，原有的 30 秒逾時導致 PLC 連線頻繁隨機斷開。",
    decision: "將 PlcConnection 中的 CommandTimeout 參數全域調整為 60 秒。",
    consequences: "降低了離線報警的假報警率，但會導致異常斷線的故障排除回報稍微延遲。"
  )

  CM 回傳:

  {
    "status": "created",
    "adrFile": "/docs/adr/0004-extend-plc-timeout.md",
    "id": 4,
    "affectedSymbols": [
      "ControlSystem.Core.Communication.PlcConnection"
    ]
  }

  分析：
  架構決策已成功建立為 0004-extend-plc-timeout.md 檔案，且在圖譜中與 PlcConnection 類別關聯。

  未來的 AI 助手在修改該類別時，會自動讀取此項決策限制，防止被再次改回 30 秒。