자동으로 챙겨주는 안전망

이 페이지는 본인이 명령을 외우지 않아도 base가 알아서 돌려 주는 자동 안전장치를 다룹니다. 워크플로 어딘가에서 “내가 시킨 적 없는데 무언가 화면에 떴다”거나 “AI가 갑자기 commit을 멈췄다”는 모습을 보게 되면 거의 여기 적힌 것 중 하나입니다.

어떤 일이 자동으로 일어나는지 한 번만 알아 두면 다음에 같은 모습을 봤을 때 당황하지 않고 다음 한 걸음으로 넘어갑니다.

훅 세 개 — .claude/hooks/에 들어 있는 것

.claude/hooks/ 폴더에 셸 스크립트 세 개가 들어 있습니다. 활성화 여부는 .claude/settings.json에서 결정됩니다. 모두 base가 박아 둔 상태이고 본인이 손대지 않아도 처음부터 동작합니다.

파일	언제 도나	한마디로
session-start.sh	Claude Code 새 세션을 열 때	”어디서 멈췄나” 정보를 AI에게 자동으로 넘김
stop-reminder.sh	AI 응답이 끝날 때	”다음 세션을 위해 한 줄 적어 두라”라고 본인에게 안내
pre-commit-check.sh	AI가 git commit 명령을 내리기 직전	typecheck와 lint를 먼저 돌려 깨진 코드를 막음

첫 번째 — AI가 어제 어디서 멈췄는지 묻지 않습니다

session-start.sh가 하는 일입니다. 새로 Claude Code 창을 열면 이 스크립트가 먼저 돌아 다음 파일들을 자동으로 AI에게 보여 줍니다.

• active.md: 직전 세션이 남긴 “다음 작업”
• progress.md: 최근 진행 이력
• feature_list.json: 테스트 케이스 목록과 통과 여부
• docs/design/e2e-spec.md: 앱 개요와 크리티컬 흐름
• MEMORY.md: 프로젝트 결정 캐시 인덱스

정상 모습: 새 세션을 열면 첫 메시지에 위 파일들의 내용이 한 번에 떠 있습니다. 본인은 “이어서”라고만 말해도 AI가 그 자리에서 다음 단계를 시작합니다.

처음 한 번은 침묵: base를 막 받은 직후 첫 세션은 위 파일들이 아직 없습니다. 그래서 스크립트는 아무것도 출력하지 않고 조용히 빠집니다. 이때는 /start 라우터가 빈 템플릿을 자동으로 만들어 줍니다.

두 번째 — 한 줄 적어 두라고 알려 줍니다

stop-reminder.sh가 하는 일입니다. AI 응답이 끝날 때 active.md가 비어 있으면 본인에게 짧은 안내를 띄웁니다. “다음 세션을 위해 한 줄 적어 두면 이어서 시작하기 편해요” 같은 메시지입니다.

이 자리는 비개발자가 가장 자주 비웁니다. 다음에 뭘 할지 적어 두는 습관이 안 잡혀 있어서 그냥 창을 닫게 됩니다. 그러면 다음 세션 자동 복원 자리가 빈 채로 시작되고, AI가 어디서 멈췄는지 다시 물어보는 흐름으로 떨어집니다. 안내가 떴을 때 한 줄만 적어 두면 다음 세션의 첫 복원 메시지에 그 줄이 그대로 들어가 있습니다.

이미 active.md에 충분히 적혀 있으면 안내는 안 뜹니다. 강제는 아닙니다.

세 번째 — 깨진 코드를 commit 못 하게 막습니다

pre-commit-check.sh가 하는 일입니다. AI가 git commit 명령을 내리려고 할 때 그 앞에서 typecheck와 lint를 먼저 돌립니다. 둘 다 통과해야 commit이 진행되고, 하나라도 실패하면 commit이 차단됩니다.

비개발자에게 가장 도움이 되는 자리입니다. AI가 테스트 코드를 짜다가 타입을 어긋나게 짚어 두고 그 위에서 commit 명령까지 내리는 경우가 있습니다. 본인이 그냥 그 명령을 실행하면 깨진 상태가 git 히스토리에 박혀 버립니다. 이 훅이 그 자리를 막아 줍니다.

차단이 떴을 때는 출력된 에러를 그대로 복사해 Claude Code에 붙여 넣고 “이거 고쳐 줘”라고 말하면 됩니다. 고친 다음 commit을 다시 내리면 두 번째에는 통과합니다.

6차원 자동 검증 — /review-e2e가 멈추는 이유

테스트를 짠 다음 base는 그게 잘 짜였는지 여섯 가지 기준으로 스스로 채점합니다. 이게 /review-e2e입니다. 사람이 손으로 점검하지 않아도 테스트의 품질이 일정 수준 아래로 떨어지면 게이트가 막습니다.

여섯 가지 기준은 이렇습니다.

• 커버리지: 약속한 크리티컬 흐름이 다 테스트로 만들어졌는가
• flakiness: 돌릴 때마다 결과가 흔들리지 않는가. 임의 대기(하드 sleep)를 안 썼는가
• 셀렉터 품질: 화면 요소를 안정적인 방법으로 찾는가
• 테스트 격리: 테스트들이 서로의 상태에 의존하지 않는가
• 실행 성능: 과하게 느리지 않은가
• 유지보수성: 나중에 읽고 고치기 쉬운가

각 기준이 5점, 3점, 1점으로 채점되고, 여섯 개가 모두 3점 이상이어야 통과합니다. 하나라도 미달이면 AI가 그 부분을 고치고 다시 채점합니다. 다만 이 고치고 다시 채점하는 루프는 최대 2번까지입니다. 두 번 고쳐도 통과 못하면 blocked로 멈춥니다. 왜 2번에서 멈추는지, 그리고 그때 어떻게 빠져나오는지는 AI가 막혔을 때에서 다룹니다.

이 게이트가 본인에게 주는 가치는 단순합니다. AI가 “테스트 다 짰어요”라고 해도, 그게 돌릴 때마다 흔들리거나 화면 하나 바뀌면 깨지는 약한 테스트라면 통과시키지 않습니다.

가장 강한 안전선 — 프로덕션 차단

여러 자리에서 반복해 짚은 자리를 여기서 한 번 더 못 박습니다. 이 base는 운영 중인 실제 서비스(프로덕션)와 실제 데이터베이스에 절대 붙지 않습니다.

이건 권고가 아니라 강제입니다. 본인이 실수로 프로덕션 URL을 넣으려 하면 /3-analyze-target이 경고하고 스테이징이나 전용 환경으로 유도합니다. 그래도 프로덕션 주소가 박힌 채 테스트를 돌리려 하면 /run-suite가 실행 자체를 거부합니다.

테스트는 회원가입을 하고, 결제를 누르고, 데이터를 만들고 지웁니다. 그 대상이 운영 서버라면 진짜 데이터가 오염되고 진짜 결제가 일어납니다. 이 차단이 그 사고를 막아 줍니다. 테스트는 항상 로컬, 스테이징, 또는 전용 테스트 환경에만 붙입니다.

끄고 싶을 때

특정 훅이 본인 워크플로에 거슬리면 .claude/settings.json에서 그 항목만 빼면 됩니다. 모두 독립이라 한 개를 빼도 다른 두 개에 영향 없습니다. 다시 켜고 싶으면 base의 원본 settings.json에서 그 항목을 복사해 넣으면 됩니다.

권하는 건 그대로 두는 쪽입니다. 셋 다 비개발자가 가장 자주 떨어지는 자리를 막아 주는 것이라, 끄면 그 자리가 다시 본인 책임으로 돌아옵니다. 프로덕션 차단만큼은 끄지 마세요.

다음

자동 안전망을 알았다면, AI 워크플로가 같은 자리에서 맴돌 때 빠져나오는 법을 AI가 막혔을 때에서 봅니다.