SOP：可觀測性回饋迴圈

當除錯速度太慢、代理在沒有證據時反覆宣稱成功，或執行期行為比程式碼本身更難觀察時，就使用這份 SOP。

目標

給代理一個涵蓋 logs、metrics、traces 與可重跑 workload 的本地回饋迴圈，讓它根據執行結果推理，而不是只靠閱讀程式碼。

最低配置

• 應用程式會輸出結構化 logs
• 可行時輸出 metrics 與 traces
• 本地 fan-out 或採集層
• 可查詢 logs、metrics 與 traces 的介面
• 每次變更後都能重跑的 workload 或使用者旅程

執行 SOP

1. 定義最重要的黃金執行期旅程。
2. 在啟動流程與關鍵路徑加入結構化 logs。
3. 在合適位置加入 latency、失敗次數或佇列深度等 metrics。
4. 為緩慢或多步驟流程加入 traces 或計時標記。
5. 讓這些訊號能從本地開發環境查詢。
6. 給代理一個可重複執行的 workload 或情境。
7. 要求採用這個迴圈，query -> correlate -> reason -> implement -> restart -> rerun -> verify。

除錯工作階段檢查清單

• 哪裡失敗了？
• 哪個訊號能證明失敗？
• 哪一層負責這個失敗？
• 修復後哪些訊號改變了？
• 應用程式是否已乾淨重啟？
• 同一個 workload 在重跑後是否通過？

完成定義

• 代理能根據執行期證據說明失敗模式。
• 每次變更後都能重跑同一個 workload。
• 重啟與重跑已成為正常工作流程的一部分。
• 可靠性訊號已記錄在 docs/RELIABILITY.md。