막혔거나 길을 잃었을 때

이 페이지는 워크플로 자체가 막힌 두 가지 자리를 다룹니다.

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

슬래시 명령어	언제 부르나
/recover-from-blocked	/review-extension 이 두 번 연속 통과 못해 blocked 라고 적은 직후
/resume	”어디까지 했더라” 가 머릿속에 떠오르는 자리. /clear 직후나 며칠 쉬다가 다시 들어왔을 때

06-troubleshooting.md이 환경과 코드 자체의 막힘을 다룬다면, 이 페이지는 그 위층의 막힘을 다룹니다.

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

/review-extension 은 AI가 짠 코드를 6개 차원에서 채점합니다 (권한, 시크릿, MV3, FSD, 타입, 빌드). 통과하면 approved, 고칠 게 있으면 changes_requested, 두 번 연속 같은 자리를 잡지 못하면 blocked 으로 적습니다. blocked 가 보이면 그 자리는 “AI에게 다시 같은 식으로 시켜 봐야 또 같은 결과” 라는 신호입니다.

이때 부를 명령은 /recover-from-blocked 입니다. 명령 한 줄로 끝납니다.

/recover-from-blocked

정상 모습 — 어디서 막혔는지 평이한 보고

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

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

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

어디서 막혔는지 정리

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

무엇이 통과 못했나
- 권한 (2점): 익스텐션이 모든 사이트에 접근할 수 있게 되어 있어요. 실제 필요한 사이트만 적도록 줄여야 해요.
- 타입 (1점): 코드의 타입(데이터 모양)이 어긋난 곳이 있어요.

AI가 시도한 것
- 1차: manifest.json의 host_permissions를 <all_urls>로 잡음
- 2차: 1차와 거의 같은 변경을 다른 자리에서 반복

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

현재 코드 상태
- 마지막 commit: a3f8c12 popup 베이스 진입점 추가 (3시간 전)
- 변경 안 된 곳: 변경된 파일 4개 (working tree dirty)

기술 용어를 일부러 풀어 적어 줍니다. <all_urls> 같은 표현이 그대로 떠도 옆에 평이한 한국어가 같이 붙어 있어 무엇을 줄여야 하는지가 보입니다.

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

보고 다음에는 본인에게 단일 질문이 떠 있습니다.

어떻게 복구할까요?

A. 마지막으로 잘 돌아갔던 곳으로 되돌리기
B. 더 자세한 정보를 알려주고 다시 시도
C. 직접 손봐보고 싶음

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

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

B. 더 자세한 정보를 알려주고 다시 시도: AI가 막혀 있는 차원에 본인이 추가 설명을 해 줍니다. 예를 들어 권한 문제로 막혔다면 “이 익스텐션은 실제로 어떤 사이트에서 동작해야 하나요?” 라는 질문이 따라옵니다. 본인이 답을 적으면 그 답이 AI에게 새 정보로 들어가고, 같은 영역을 한 번 더 시도합니다. 이 옵션은 막힌 차원이 본인이 답을 풀 수 있는 영역(권한, 빌드 크기 같은 비즈니스 결정)일 때 효과가 좋습니다. 타입이나 FSD 같은 코드 문제는 A가 보통 더 빠릅니다.

C. 직접 손봐보고 싶음: 어느 파일을 보면 되는지만 알려 주고 명령은 종료됩니다. 본인이 직접 코드를 고친 다음 /review-extension 을 다시 돌리면 됩니다.

A 옵션의 안전장치

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

다음 commit으로 되돌립니다:
a3f8c12 popup 베이스 진입점 추가 (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 같은 파일들을 AI 컨텍스트에 깔아 준다고 했습니다. 그 훅은 raw 내용 그대로를 깔기만 합니다.

/resume 은 그 raw를 한 화면 요약으로 합성합니다.

메커니즘	시점	사용자에게 보이는 것
session-start.sh 훅	새 세션 시작 자동	state 파일들의 내용이 그대로 깔림. AI는 알지만 본인은 안 봄
/resume 명령	본인이 명시 호출	”현재 단계, 마지막 작업, 다음 추천 명령어” 한 화면 요약

훅은 AI가 보는 것이고, /resume 은 본인이 보는 것입니다. 두 메커니즘이 짝으로 돕니다.

정상 모습 — 한 화면 요약

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

현재 상태 요약

진행 단계: customized (popup, options 같은 진입 화면을 만드는 중)
마지막 작업 (2일 전): popup UI에 백엔드 모드 토글 추가
기능 진척: 3 / 7 통과
페이스: novice
UI 모드: sidepanel
MCP: figma, supabase

사용자가 적어둔 다음 작업 (active.md)
"sidepanel 색상 결정 중. 다음엔 옵션 페이지 폼"

다음 자연스러운 단계
sidepanel UI 작업을 이어가시려면 /implement-sidepanel-ui 로 진입할까요?

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

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

가끔 본인이 active.md 에 적어 둔 작업과 실제 진행 단계가 안 맞는 경우가 있습니다. 예를 들어 active.md 에는 “popup 색상 결정 중” 이라고 적혀 있는데 실제 폴더에는 popup이 아직 없는 상태입니다.

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

둘이 함께 도는 한 사이클

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

1. 작업하다가 검증이 두 번 막힘
   → /recover-from-blocked → A 옵션으로 rollback
   → 본인이 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 입니다. 띄어쓰기나 대문자가 들어가면 인식 안 됩니다.

다음 단계

워크플로 안전망까지 알아 두면 본격적인 배포 단계로 넘어갈 준비가 됐습니다. 본인 확장을 다른 사람의 컴퓨터에서 동작시키는 세 가지 길은 09-distribution.md 에 정리돼 있습니다.