막혔거나 길을 잃었을 때

이 페이지는 워크플로 자체가 막히는 두 가지 상황을 다룹니다.

하나는 AI 가 같은 실수를 두 번 연속 반복해서 검증이 통과하지 않는 경우입니다. 다른 하나는 며칠 만에 돌아왔거나 /clear 로 대화창을 비운 직후라 어디까지 했는지 기억나지 않는 경우입니다. 둘 다 코드 문제가 아니라 워크플로 문제이고, base 에 들어 있는 슬래시 명령어 두 개가 이 상황을 풀어 줍니다.

슬래시 명령어	언제 부르나
/recover-from-blocked	/review-saas 가 두 번 연속 통과하지 못해 blocked 라고 적은 직후에 부릅니다
/resume	”어디까지 했더라” 하는 생각이 들 때 부릅니다. /clear 직후나 며칠 쉬다가 다시 들어왔을 때에 해당합니다

09-troubleshooting.md 이 환경과 코드 자체의 막힘을 다룬다면, 이 페이지는 그보다 한 단계 위의 막힘을 다룹니다.

/recover-from-blocked, AI 가 같은 실수를 두 번 했을 때

/review-saas 는 AI 가 짠 코드를 여섯 관점에서 채점합니다 (보안, 시크릿, 접근성, 검색 대응, 타입, 빌드). 통과하면 approved, 고칠 것이 있으면 changes_requested, 두 번 연속 같은 문제를 잡지 못하면 blocked 으로 적습니다. blocked 가 보이면 “AI 에게 같은 방식으로 다시 시켜 봐야 또 같은 결과가 나온다” 는 신호입니다.

흔한 경우를 하나 들면, Stripe webhook 의 서명 검증을 빼먹고 두 번 review 에 막히는 상황입니다. 첫 시도는 webhook handler 안에서 stripe.webhooks.constructEvent 호출이 빠진 상태이고, 두 번째 시도는 같은 함수의 다른 줄에서 비슷한 모양으로 다시 빠진 상태입니다. 보안 관점 점수가 두 번 모두 낮게 나옵니다. 이때 부를 명령이 /recover-from-blocked 입니다.

/recover-from-blocked

정상 동작 모습: 어디서 막혔는지 알려 주는 보고

명령을 입력하면 AI 가 다음을 자동으로 합니다.

1. 가장 최근 검증 보고서를 찾아 읽습니다 (.claude/state/review-*.md 중 시각이 가장 늦은 파일입니다).
2. 어느 관점에서 점수가 낮았는지 추출합니다.
3. AI 가 이전 두 번의 시도에서 무엇을 고쳤는지 비교합니다 (.claude/state/builder-*.md 를 읽습니다).
4. 같은 파일을 같은 방향으로 두 번 고쳤다면 그 사실을 본인에게 알립니다.

화면에는 다음 형식의 보고가 뜹니다.

어디서 막혔는지 정리

AI 가 Stripe webhook 영역을 만들고 있었는데, 검증에서 2 번 막혔어요.

무엇이 통과하지 못했나
- 보안 (2점): webhook 함수가 서명 검증 없이 본문을 그대로 DB 에 저장하고 있어요.
  위조된 webhook 이 임의 구독을 활성화시킬 수 있어요.
- 시크릿 (3점): STRIPE_WEBHOOK_SECRET 이 .env.local 에 들어 있어요.
  Edge Function 은 거기서 읽지 못해요. supabase secrets set 으로 옮겨야 해요.

AI 가 시도한 것
- 1차: stripe.webhooks.constructEvent 호출이 빠진 채로 handler 를 작성했어요
- 2차: 같은 함수에서 검증하는 곳만 try/catch 로 감쌌으나 검증 자체는 여전히 없어요

⚠️ AI 가 두 번 모두 같은 줄을 비슷하게 고치려다 실패했어요. 추가 정보 없이 한 번 더 시도해도 같은 결과가 날 가능성이 큽니다.

현재 코드 상태
- 마지막 commit: a3f8c12 stripe webhook 초기 골격 (3 시간 전)
- 아직 커밋하지 않은 변경: 변경된 파일 2 개 (working tree dirty)

기술 용어를 일부러 풀어 적어 줍니다. constructEvent 같은 표현이 그대로 나와도 옆에 쉬운 한국어가 같이 붙어 있어 무엇을 손봐야 하는지 보입니다.

세 가지 옵션 중 하나를 고릅니다

보고 다음에는 질문이 하나 나옵니다.

어떻게 복구할까요?

A. 마지막으로 잘 동작했던 시점으로 되돌리기
B. 더 자세한 정보를 알려주고 다시 시도하기
C. 직접 손보기

각 옵션이 하는 일은 다음과 같습니다.

A. 마지막으로 잘 동작했던 시점으로 되돌리기: 권장 옵션입니다. AI 가 마지막으로 검증을 통과했던 시점의 commit 으로 코드를 되돌립니다. 그 사이 AI 가 시도한 모든 변경이 사라집니다. 깨끗한 출발점으로 돌아간 다음, 본인이 추가 정보를 더 적어 주고 같은 영역을 다시 작성하게 시키는 흐름이 보통 가장 잘 풀립니다.

B. 더 자세한 정보를 알려주고 다시 시도하기: AI 가 막혀 있는 관점에 본인이 추가 설명을 해 줍니다. 예를 들어 webhook 보안에서 막혔다면 “이 webhook 은 어떤 비밀로 서명을 검증해야 하나요? 그 비밀은 지금 어디에 있나요?” 라는 질문이 따라옵니다. 본인이 답을 적으면 그 답이 AI 에게 새 정보로 들어가고, 같은 영역을 한 번 더 시도합니다. 이 옵션은 막힌 관점이 본인이 답할 수 있는 영역(가격 모델, 라우팅 모드 같은 비즈니스 결정)일 때 효과가 좋습니다. 타입이나 FSD 같은 코드 문제는 A 가 보통 더 빠릅니다.

C. 직접 손보기: 어느 파일을 보면 되는지만 알려 주고 명령이 종료됩니다. 본인이 직접 코드를 고친 다음 /review-saas 를 다시 실행하면 됩니다.

A 옵션의 안전장치

A 를 고르면 한 번 더 확인 질문이 따라옵니다.

다음 commit 으로 되돌립니다:
a3f8c12 stripe webhook 초기 골격 (3 시간 전)

되돌리면 그 이후 AI 가 만든 파일은 전부 사라져요. 진행할까요? (yes / no)

yes 라고 적어야만 git reset --hard 가 실행됩니다. 다른 답을 적거나 이 화면을 닫으면 아무 일도 일어나지 않습니다. 한 번 더 막아 두는 장치입니다.

저장하지 않은 변경(working tree 에 남아 있는 수정)이 있다면 그것도 같이 사라진다는 안내가 한 줄 더 따라옵니다. 본인이 따로 보관해 둘 파일이 있다면 그 단계에서 멈추고 그 파일을 다른 곳에 복사해 두면 됩니다.

/resume, 어디까지 했는지 기억이 안 날 때

/clear 로 대화창을 비웠거나, 며칠 쉬었다가 돌아왔거나, “어디까지 했지?” 하는 생각이 들 때 부르는 명령입니다.

/resume

session-start 훅과는 어떻게 다른가

07-automated-safety-net.md 에서 session-start.sh 훅이 새 세션마다 자동으로 active.md, progress.md, saas-spec.md 같은 파일을 AI 컨텍스트에 넣어 준다고 설명했습니다. 그 훅은 원본 내용을 그대로 넣기만 합니다.

/resume 은 그 원본을 한 화면 요약으로 정리합니다.

동작 방식	시점	사용자에게 보이는 것
session-start.sh 훅	새 세션 시작 시 자동으로 동작합니다	state 파일의 내용이 그대로 들어갑니다. AI 는 알지만 본인은 보지 못합니다
/resume 명령	본인이 직접 호출합니다	”현재 단계, 마지막 작업, 다음 추천 명령어” 를 한 화면으로 요약해 줍니다

훅은 AI 가 보는 것이고, /resume 은 본인이 보는 것입니다. 두 방식이 짝을 이뤄 동작합니다.

정상 동작 모습: 한 화면 요약

명령을 입력하면 다음 형식의 출력이 나옵니다.

현재 상태 요약

진행 단계: customized (브랜딩과 라우트 트리가 정해진 상태예요)
마지막 작업 (2 일 전): Pro 플랜 카드에 Stripe Price ID 넣기
기능 진척: 4 / 7 통과
페이스: novice
라우팅 모드: marketing-app
API 어댑터: edge-functions
MCP: figma, supabase

사용자가 적어둔 다음 작업 (active.md)
"checkout 흐름 e2e 시나리오 한 줄 짜고 /test-saas 돌리기"

다음 자연스러운 단계
implement-billing 영역을 이어가시려면 그 슬래시 명령 안내를 따라가실까요?

요약 출력은 20 줄 이내로 나오도록 짜여 있습니다. 한 화면에 전체가 들어와 다음 한 걸음이 바로 보이게 하는 것이 목표입니다. progress.md 가 길어도 마지막 한두 줄만 요약해 줍니다.

active.md 와 진행 단계가 어긋날 때

가끔 본인이 active.md 에 적어 둔 작업과 실제 진행 단계가 맞지 않는 경우가 있습니다. 예를 들어 active.md 에는 “Pro 플랜 카드에 Stripe Price ID 넣기” 라고 적혀 있는데 실제 폴더에는 가격 페이지 골격이 아직 만들어지지 않은 상태입니다.

이럴 때 /resume 은 둘이 맞지 않는다는 것을 본인에게 보여 주고 어느 쪽이 맞는지 묻습니다. active.md 는 본인이 직접 적은 기록이라 보통 그쪽이 우선이지만, 그 사이에 다른 PC 에서 작업했거나 끝낸 뒤 기록을 잊은 경우가 섞여 있어 한 번 더 확인을 받는 것입니다.

둘이 함께 도는 한 사이클

두 명령어가 같이 도는 흐름은 보통 이렇습니다.

1. 작업하다가 검증이 두 번 막힙니다 (예: webhook 서명 검증)
   → /recover-from-blocked 를 부르고 A 옵션으로 되돌립니다
   → 본인이 active.md 에 "어디서 막혔고 어떻게 다시 시도할지" 를 한 줄 적습니다

2. 그날은 닫고 다음 날 다시 들어옵니다
   → /resume 을 부르면 "어제 어디서 막혔고 다음에 무엇을 할지" 가 한 화면으로 보입니다

3. 추천된 슬래시 명령어로 같은 영역을 다시 작성합니다
   → 이번에는 본인이 추가 설명을 미리 적어 둔 상태라 통과합니다

두 명령어를 따로 외우지 않아도 됩니다. 막혀 있으면 첫 번째를 쓰고, 어디까지 했는지 모르겠으면 두 번째를 씁니다. 두 가지만 기억하면 됩니다.

명령어가 동작하지 않을 때

두 명령어 모두 base 의 .claude/skills/ 폴더에 들어 있는 스킬을 실행합니다. Claude Code 가 명령을 알아보지 못한다면 거의 항상 다음 둘 중 하나입니다.

• 본인이 base 를 fork 했을 때 .claude/ 폴더가 같이 받아지지 않은 경우입니다. git clone 이 정상이라면 거의 일어나지 않지만, 누군가 .gitignore 에 .claude/ 를 넣은 fork 를 받았다면 가능합니다. 본인 폴더에서 ls .claude/skills/ 를 실행해 recover-from-blocked 와 resume 디렉터리가 보이는지 확인하세요.
• 슬래시 명령어 자체를 다르게 적은 경우입니다. 정확히 /recover-from-blocked 와 /resume 입니다. 띄어쓰기나 대문자가 들어가면 인식되지 않습니다.

다음 단계

워크플로 안전망까지 알아 두면 본격적인 배포 단계로 넘어갈 준비가 된 것입니다. 본인 SaaS 를 호스팅에 올려 다른 사람의 브라우저에서 동작시키는 네 가지 방법은 08-distribution.md 에 정리돼 있습니다. 그 전에 자동 안전망 세 개가 무엇을 알아서 처리하는지 07-automated-safety-net.md 에서 한 번 보고 가셔도 됩니다.