스마트폰으로 프로덕션 이슈 디버깅하기

금요일 오후 7시. 친구들과 저녁 식사 중에 PagerDuty 알림으로 스마트폰이 진동합니다: 결제 서비스의 에러율이 15%로 급등했습니다. 노트북은 집에 있습니다. 팀원들은 오프라인입니다. 이 인시던트는 당신이 처리해야 합니다.

이것이 Tactic Remote가 존재하는 이유입니다. 이 튜토리얼에서는 iPhone만 사용한 현실적인 프로덕션 디버깅 워크플로를 실습하며, 원격으로 문제를 조사, 진단, 수정하는 방법을 시연합니다.

시나리오 설정

이 튜토리얼에서는 현실적인 시나리오를 다룹니다:

• 서비스: Node.js 결제 처리 API
• 증상: /api/payments/process 엔드포인트에서 500 에러
• 영향: 결제 시도의 15%가 실패
• 환경: SSH를 통해 프로덕션 로그 접근 가능, 코드베이스는 Mac에 있음

집에 있는 Mac이 켜져 있고 Tactic Remote 컴패니언 앱이 실행 중입니다. iPhone에서 연결하여 조사를 시작합니다.

페이즈 1: 분류 (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 변경이 포함되어 있었음.

페이즈 2: 진단 (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.

이 진단은 구체적이고, 테스트 가능하며, 관찰된 동작을 설명합니다. 스마트폰에서 진행하기 전에 내용이 타당한지 확인할 수 있습니다.

페이즈 3: 수정 (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 실행 — 승인 (수정 검증)

페이즈 4: 배포 (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: 검증 (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시간을 소비하지 마세요.

인시던트 도구 키트 구축

인시던트가 발생하기 전에 준비하세요:

1. 배포 스크립트와 모니터링 도구에 접근할 수 있는 프로덕션 디버깅 세션을 미리 준비하세요.
2. Claude Code가 따를 수 있는 인시던트 대응 프롬프트를 프롬프트 라이브러리에 만드세요.
3. 실제 압박이 있을 때 흐름에 익숙하도록 중요하지 않은 상황에서 워크플로를 테스트하세요.
4. 어디서든 디버깅할 수 있도록 Cloudflare Tunnel 접근을 확보하세요.

프로덕션 인시던트는 편한 타이밍을 기다려주지 않습니다. Tactic Remote는 어디에 있든 효과적으로 대응할 수 있는 도구를 보장합니다.