AI가 막혔을 때

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

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

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

트러블슈팅이 환경과 테스트 자체의 막힘을 다룬다면, 이 페이지는 그 위층의 막힘을 다룹니다.

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

자동으로 챙겨주는 안전망에서 봤듯이 /review-e2e는 테스트를 여섯 차원으로 채점합니다(커버리지, flakiness, 셀렉터 품질, 테스트 격리, 실행 성능, 유지보수성). 통과하면 approved, 고칠 게 있으면 changes_requested, 두 번 연속 같은 자리를 잡지 못하면 blocked로 적습니다. blocked가 보이면 그 자리는 “AI에게 다시 같은 식으로 시켜 봐야 또 같은 결과”라는 신호입니다.

흔한 자리 하나를 짚어 두면, 테스트가 화면이 다 뜨기 전에 다음 동작을 해 버려서 flakiness 점수가 두 번 모두 낮게 떨어지는 경우입니다. 첫 시도는 임의 대기(하드 sleep)를 넣어 가렸다가, 두 번째 시도도 비슷한 자리에 또 sleep을 넣는 식입니다. 이때 부를 명령이 /recover-from-blocked입니다.

/recover-from-blocked

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

명령을 입력하면 AI가 가장 최근 검증 보고서를 찾아 읽고, 어느 차원에서 점수가 낮았는지, AI가 이전 두 번에 무엇을 시도했는지를 비교해 다음 형식으로 보고합니다.

어디서 막혔는지 정리

AI가 결제 흐름 테스트를 만들고 있었는데, 검증에서 2번 막혔어요.

무엇이 통과 못했나
- flakiness (1점): 결제 버튼을 누른 뒤 화면이 다 뜨기 전에 다음 단계로
  넘어가서, 돌릴 때마다 결과가 흔들려요.
- 셀렉터 품질 (3점): 버튼을 화면 구조(CSS) 위치로 찾고 있어서,
  화면이 조금만 바뀌어도 못 찾게 돼요.

AI가 시도한 것
- 1차: 버튼 클릭 뒤에 임의 대기(sleep)를 넣어 가림
- 2차: 같은 자리에 sleep 시간만 늘림. 흔들림은 그대로

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

현재 코드 상태
- 마지막 commit: a3f8c12 결제 흐름 테스트 초기 골격 (3시간 전)
- 변경 안 된 곳: 변경된 파일 2개 (working tree dirty)

기술 용어를 일부러 풀어 적어 줍니다. flakiness나 셀렉터 같은 표현이 떠도 옆에 평이한 한국어가 붙어 있어 무엇이 문제인지 보입니다.

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

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

어떻게 복구할까요?

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

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

B. 더 자세한 정보를 알려주고 다시 시도: AI가 막혀 있는 부분에 본인이 추가 설명을 해 줍니다. 예를 들어 화면 요소를 못 찾아 막혔다면 “그 결제 버튼에 보이는 글자가 뭐예요?” 같은 질문이 따라옵니다. 본인이 답하면 그 답이 새 정보로 들어가고, 같은 영역을 한 번 더 시도합니다. 이때 시도 횟수는 0으로 리셋됩니다. 새 정보가 들어왔으니 새 시도로 칩니다.

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

A 옵션의 안전장치

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

다음 commit으로 되돌립니다:
a3f8c12 결제 흐름 테스트 초기 골격 (3시간 전)

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

yes라고 적어야만 되돌리기가 실행됩니다. 아무 답이나 적거나 이 자리에서 닫으면 아무 일도 일어나지 않습니다. 저장 안 된 변경이 있으면 그것도 같이 사라진다는 안내가 한 줄 더 붙습니다. 따로 확인해 둘 자리가 있다면 그 단계에서 멈추고 그 파일을 어디 다른 곳에 복사해 두면 됩니다.

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

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

/resume

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

자동으로 챙겨주는 안전망에서 session-start.sh 훅이 새 세션마다 state 파일들을 AI 컨텍스트에 깔아 준다고 했습니다. 그 훅은 raw 내용 그대로를 깔기만 합니다. AI는 알지만 본인은 그걸 보지 못합니다.

/resume은 그 raw를 한 화면 요약으로 합성해 본인에게 보여 줍니다.

현재 상태 요약

진행 단계: implemented (테스트가 짜인 자리)
마지막 작업 (2일 전): 결제 흐름 테스트 첫 버전 작성
기능 진척: 2 / 4 통과
페이스: novice
타겟·도구: web (Playwright)

사용자가 적어둔 다음 작업 (active.md)
"결제 흐름 flaky 잡고 /run-suite 다시 돌리기"

다음 자연스러운 단계
/run-suite로 다시 돌려볼까요?

요약은 20줄 이내로 떨어지게 짜여 있습니다. 한 화면에 전체가 들어와 다음 한 걸음이 바로 보이게 하는 게 목표입니다.

적어 둔 작업과 진행 단계가 어긋날 때

가끔 본인이 active.md에 적어 둔 작업과 실제 진행 단계가 안 맞는 경우가 있습니다. 예를 들어 active.md에는 “결제 흐름 테스트 마저 작성”이라 적혀 있는데 실제로는 아직 테스트 골격도 안 깔린 상태입니다. 이럴 때 /resume은 둘이 안 맞는 걸 본인에게 보여 주고 어느 쪽이 맞는지 묻습니다. active.md는 본인이 적은 자리라 보통 그게 우선이지만, 그 사이에 다른 PC에서 작업했거나 한 게 섞여 있을 수 있어 한 번 더 확인을 받는 것입니다.

review가 blocked 상태라면 /resume이 그걸 알아채고 /recover-from-blocked를 권합니다. 두 명령어가 이렇게 맞물려 돕니다.

부분만 다시 돌리기

전체를 다시 짜지 않아도 됩니다. 막힌 게 결제 흐름 하나라면 그 트랙의 implement-* 스킬만 다시 부르면 됩니다. 보고서의 “다음” 줄에 보통 어느 스킬을 부르라는 안내가 적혀 있으니 그걸 따라가면 막힌 한 자리만 다시 손봅니다.

명령어가 안 도는 자리

두 명령어 모두 base의 .claude/skills/ 폴더에 들어 있는 스킬을 트리거합니다. Claude Code가 명령을 못 알아본다면 거의 둘 중 하나입니다. fork할 때 .claude/ 폴더가 같이 안 받아진 경우(ls .claude/skills/로 확인), 또는 슬래시 명령어를 다르게 적은 경우입니다. 정확히 /recover-from-blocked와 /resume입니다.

다음

워크플로 안전망까지 알았다면, 환경이나 테스트 자체가 깨졌을 때 보는 트러블슈팅으로 갑니다.