返回列表

部落格

從手機除錯正式環境問題

當正式環境在晚餐時間出問題，你的手機就成了除錯介面。以下是如何在不急著趕回筆電前診斷和修復問題的方法。

發布於 標籤: 入門教學 / debugging / production / incident-response
部落格

繼續查看該欄目下的產品與工程更新。

瀏覽此分類

星期五晚上七點。你正在和朋友吃晚餐，手機突然振動收到一則 PagerDuty 警報：你的支付服務錯誤率飆升到 15%。筆電在家裡。隊友們都離線了。這個事件由你來處理。

這就是 Tactic Remote 存在的意義。本教學將帶你走過一個真實的正式環境除錯工作流程，僅使用你的 iPhone，示範如何遠端調查、診斷和修復正式環境問題。

情境設定

本教學將處理一個真實的情境：

  • 服務： Node.js 支付處理 API
  • 症狀： /api/payments/process 端點出現 500 錯誤
  • 影響： 15% 的支付嘗試失敗
  • 環境： 正式環境日誌可透過 SSH 存取，程式碼庫在你的 Mac 上

你的 Mac 在家裡開著，運行著 Tactic Remote 配套應用程式。你從 iPhone 連線並開始調查。

第一階段：分類評估（5 分鐘）

第一個目標是了解範圍和緊急程度。啟動一個指向你專案目錄的 Claude Code 工作階段：

We have a production incident. The /api/payments/process endpoint
is returning 500 errors for ~15% of requests. This started approximately
30 minutes ago.

Help me investigate:
1. Check the git log for any recent deployments (last 24 hours)
2. Look at the payment processing code in src/api/payments/
3. Check if there were any dependency updates recently

Claude Code 會檢查程式碼和最近的變更。在它工作的同時，在手機瀏覽器中打開你的監控儀表板檢查：

  • 錯誤率是穩定的、上升的還是下降的？
  • 所有實例都受影響還是只有部分？
  • 失敗的請求是否有規律？

Claude Code 可能發現的問題： 3 小時前的一個提交將 Stripe SDK 依賴從 v12.1.0 更新到了 v13.0.0，其中包含了破壞性的 API 變更。

第二階段：診斷（10 分鐘）

有了假設（Stripe SDK 更新），進一步深入：

Compare the Stripe SDK v12 and v13 changelog.
Check our payment processing code for any API calls that changed
between versions. Focus on the payment intent creation and
confirmation flow in src/api/payments/processor.ts.

Claude Code 會分析程式碼並識別具體的不相容問題。典型的發現：

Found the issue. In Stripe SDK v13, the `payment_intents.create()` method
changed its error handling behavior:

- v12: Returns { error: { type, message } } for card declines
- v13: Throws StripeCardError exception for card declines

Our code in processor.ts:45-52 checks for `result.error` but doesn't
catch the new exception type. When a card is declined, the uncaught
exception propagates as a 500 error.

This explains the 15% error rate — approximately 15% of payment
attempts involve card declines (expired cards, insufficient funds, etc.)
that now throw uncaught exceptions.

這個診斷是具體的、可測試的，而且能解釋觀察到的行為。從你的手機上，你可以在繼續之前驗證它是否合理。

第三階段：修復（10 分鐘）

現在實作修復。你有兩個選項：

選項 A：快速回滾

如果情況緊急且之前的版本是穩定的：

Revert the Stripe SDK update. Change package.json to pin
stripe at v12.1.0. Create a commit with message:
"hotfix: revert Stripe SDK to v12 (fixes payment 500 errors)"

核准步驟： Claude Code 會請求核准修改 package.json 和執行 npm install。在核准卡片中查看變更並核准。

選項 B：前向修復

如果你想修復程式碼以相容 v13（避免回滾而失去其他改進）：

Fix the payment processing code to handle both the legacy error
response format and the new exception-based error handling in
Stripe SDK v13.

Specifically:
1. Wrap the payment_intents.create() call in a try/catch
2. Catch StripeCardError and convert it to our standard error format
3. Keep the existing result.error check as a fallback
4. Add a test case for the card decline scenario

Commit with: "hotfix: handle Stripe v13 exception-based card decline errors"

Claude Code 會進行變更並執行測試。在終端機檢視中觀看測試結果。

核准流程： 你可能會看到多個核准請求：

  1. 修改 src/api/payments/processor.ts — 核准（這是修復）
  2. 修改 src/api/payments/__tests__/processor.test.ts — 核准（新增測試）
  3. 執行 npm test — 核准（驗證修復）

第四階段：部署（5 分鐘）

修復已提交並測試通過：

Push this commit to the main branch.
Then trigger the deployment pipeline by running our deploy script:
./scripts/deploy.sh production

關鍵核准： Claude Code 會請求核准部署命令。這是工作流程中風險最高的操作。仔細審查：

  • 驗證提交訊息與你的修復相符
  • 確認部署目標正確（production）
  • 確保上一步的測試已通過

核准後，Claude Code 執行部署。在終端機輸出中監控部署進度。

第五階段：驗證（5 分鐘）

部署完成後：

Check the deployment status. Then help me verify:
1. Run a test request against the production payment endpoint
2. Check if the error rate has started decreasing
3. Look for any new error patterns in the last 5 minutes

同時，在手機上檢查你的監控儀表板。錯誤率應該在部署完成後幾分鐘內開始下降。

事後：撰寫報告

趁事件記憶猶新時（仍然在晚餐中，菜與菜之間）：

Write a post-incident report based on our investigation:

Include:
- Timeline of events
- Root cause (Stripe SDK v13 breaking change)
- Impact (15% payment failure rate for ~1 hour)
- Resolution (code fix to handle new exception type)
- Action items to prevent recurrence

Format as a markdown document in docs/incidents/

這讓你的團隊在週一早上之前就有了完整的事件報告。你的晚餐同伴幾乎沒有注意到這個插曲。

高效遠端除錯的技巧

先廣後窄。 不要立即跳到假設。讓 Claude Code 先巡查全局（最近的變更、錯誤模式、系統狀態），然後再聚焦到特定原因。

善用核准閘門作為檢查點。 每個核准請求都是一個自然的檢查點，讓你審查 Claude Code 正在做什麼。利用這些來驗證調查方向是否正確。

將診斷和修復分開。 先取得清晰的診斷並確認它合理，再實作任何變更。這可以防止在不了解根本原因的情況下進行「追逐式修復」。

在除錯時同步溝通。 如果你的團隊有事件頻道，從手機發佈更新：

  • 「正在調查支付 500 錯誤。懷疑是 Stripe SDK 更新。」
  • 「已確認：SDK v13 變更了信用卡拒絕的錯誤處理方式。正在部署修復。」
  • 「修復已部署。錯誤率正在恢復正常。」

這讓相關人員保持知情並防止重複調查。

了解你的限制。 有些正式環境問題需要基礎設施存取、資料庫查詢或系統層級的除錯，無法透過 Claude Code 完成。如果你碰壁了，就升級處理——不要花一個小時用手機處理在工作站前只需要 5 分鐘就能解決的問題。

建立你的事件工具包

在事件發生之前就做好準備：

  1. 預先建立一個正式環境除錯工作階段，可存取你的部署腳本和監控工具。
  2. 建立事件回應提示放在你的提示庫中，讓 Claude Code 可以遵循。
  3. 在非關鍵情境下測試工作流程，這樣在壓力真正來臨時你已經熟悉整個流程。
  4. 確保 Cloudflare Tunnel 存取，這樣你可以從任何地方除錯，不只限於家裡的網路。

正式環境事件不會等待方便的時間。Tactic Remote 確保無論你在哪裡，都有工具可以有效回應。

立即體驗 Tactic Remote

用手機遠端操作程式開發 Agent

連線到 Mac、Windows 或 Linux 電腦上的 Claude Code、Codex 等 Agent，在 iPhone 或 iPad 上查看進度並傳送下一個請求。

查看設定步驟查看所有下載