diff --git a/CLAUDE.md b/CLAUDE.md
index 2135e78..918b019 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1931,6 +1931,48 @@ else
 
 ---
 
+### CI Deploy 트러블슈팅 하네스 (2026-06-28)
+
+커밋 후 배포가 동작하지 않는다고 판단하기 전에 아래 순서로 확인한다. 추측으로 runner, secret, 커밋 제목을 원인으로 단정하지 않는다.
+
+1. **푸시 결과 확인**
+   ```powershell
+   git push origin master 2>&1 | Select-String "master|To|Processed|remote"
+   ```
+   `master -> master`가 보이면 Git push는 성공이다. 이 단계는 CI 실행 성공을 의미하지 않는다.
+
+2. **Actions run 생성 확인**
+   ```powershell
+   $headers = @{ Authorization = "token $env:GITEA_TOKEN_TAXBAIK" }
+   $runs = Invoke-RestMethod -Headers $headers -Uri "http://178.104.200.7/api/v1/repos/kjh2064/taxbaik/actions/runs?limit=10"
+   $runs.workflow_runs | Select-Object id,path,event,head_sha,display_title,status,conclusion
+   ```
+   `deploy.yml@refs/heads/master`, `event=push`, 최신 `head_sha`가 있어야 배포가 실제로 시작된 것이다.
+
+3. **workflow 파싱 검증**
+   ```powershell
+   curl.exe -sS -w "`nHTTP_STATUS:%{http_code}`n" `
+     -H "Authorization: token $env:GITEA_TOKEN_TAXBAIK" `
+     -H "Content-Type: application/json" `
+     -X POST "http://178.104.200.7/api/v1/repos/kjh2064/taxbaik/actions/workflows/deploy.yml/dispatches?return_run_details=true" `
+     --data '{"ref":"refs/heads/master","inputs":{}}'
+   ```
+   `failed to unmarshal workflow content`가 나오면 `.gitea/workflows/deploy.yml` YAML 문법 문제다. 여러 줄 문자열은 반드시 `run: |` 블록 들여쓰기 안에 둔다.
+
+4. **job 실패 로그 확인**
+   ```powershell
+   curl.exe -sS -H "Authorization: token $env:GITEA_TOKEN_TAXBAIK" `
+     "http://178.104.200.7/api/v1/repos/kjh2064/taxbaik/actions/jobs/{job_id}/logs"
+   ```
+   빌드/테스트/배포/헬스체크 중 어느 단계인지 먼저 분리한다.
+
+**이번 장애 원인 기록**:
+- `deploy.yml`의 Telegram 여러 줄 메시지 일부가 YAML 블록 들여쓰기 밖에 있어 Gitea workflow 파서가 실패했다.
+- 이후 배포 실행은 되었지만, 운영 `Authentication:*:ClientId`가 빈 값인데 OAuth provider를 무조건 등록해 `ClientId` 예외로 500이 발생했다.
+- 외부 OAuth provider는 ClientId/ClientSecret이 모두 있을 때만 등록한다.
+
+---
+
 ## 12. 문제 해결
 
 | 문제 | 해결 |