자동으로 챙겨주는 안전망

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

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

어디에 들어 있나

.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에게 보여 줍니다.

• .claude/session-state/archive/active.md: 직전 세션이 남긴 “다음 작업”
• .claude/session-state/progress/progress.md 의 마지막 30줄: 최근 진행 이력
• .claude/state/feature_list.json: 본인 확장이 약속한 기능 목록
• docs/design/extension-spec.md 첫 50줄: 확장 사양
• .claude/agent-memory/MEMORY.md: 프로젝트 결정 캐시 인덱스

정상 모습: 새 세션을 열면 첫 번째 메시지에 “세션 컨텍스트 자동 복원” 이라는 제목과 그 아래 위 파일들의 내용이 한 번에 떠 있습니다. 본인은 그냥 “이어서” 라고만 말해도 AI가 그 자리에서 다음 단계를 시작합니다.

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

비정상 모습: 분명 어제 작업했는데 새 세션을 열어도 “세션 컨텍스트 자동 복원” 자리가 안 보입니다. 거의 항상 .claude/settings.json 의 SessionStart 항목을 누가(본인이든 AI든) 지운 경우입니다. base의 원본을 다시 받아 그 한 항목만 복사해 넣으면 다시 돕니다.

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

stop-reminder.sh 가 하는 일입니다. AI 응답이 끝날 때마다 active.md 의 길이를 살핍니다. 공백 빼고 20글자가 안 되면 본인에게 짧은 안내를 띄웁니다.

💡 다음 세션을 위해 한 줄 적어두면 이어서 시작하기 편해요:
   파일: .claude/session-state/archive/active.md
   예시: "popup UI 색상 결정 중. 다음엔 옵션 페이지 폼 만들기"

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

정상 모습: 위 안내가 떴을 때 본인이 한 줄짜리 메모를 .claude/session-state/archive/active.md 에 적어 둡니다. 다음 세션의 첫 번째 자동 복원 메시지에 그 한 줄이 그대로 들어가 있습니다.

무시해도 되는 자리: 이미 active.md 에 충분히 적혀 있다면 안내는 안 뜹니다. 그리고 안내가 떴어도 본인이 그 세션에서 진짜로 한 일이 없다면 그냥 닫아도 됩니다. 자동 안전망이지 강제는 아닙니다.

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

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

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

정상 모습 (통과):

🔍 commit 전 자동 검사 (typecheck + lint)…
✓ typecheck + lint 통과 — commit 진행

이 두 줄이 보이면 commit이 그대로 진행됐다는 뜻입니다.

비정상 모습 (차단):

🔍 commit 전 자동 검사 (typecheck + lint)…
❌ typecheck 실패. commit이 차단됐어요. 아래 메시지를 AI에게 보여주고 고쳐달라고 하세요:

src/popup/index.tsx:14:7 - error TS2322: Type 'string' is not assignable to type 'number'.
...

이때 그 30줄을 그대로 복사해서 Claude Code 창에 붙여 넣고 “이거 고쳐 줘” 라고 말하면 AI가 그 자리를 잡아 다시 짭니다. 고친 다음에 commit 명령을 다시 내리면 두 번째에는 통과합니다.

pnpm 외 패키지 매니저: 이 훅은 pnpm-lock.yaml, yarn.lock, package-lock.json 셋 중 어느 게 있는지 보고 자동으로 적절한 매니저를 씁니다. base 기본은 pnpm이라 대부분의 경우 pnpm이 돌아갑니다.

끄고 싶을 때

특정 안전망이 본인 워크플로에 거슬리면 .claude/settings.json 에서 해당 항목만 빼면 됩니다. 모두 독립이라 한 개를 빼도 다른 두 개에 영향 없습니다.

{
  "hooks": {
    "SessionStart": [...],
    "Stop": [...],
    "PreToolUse": [...]
  }
}

예를 들어 commit 전 자동 검사가 거슬리면 "PreToolUse": [...] 한 항목만 통째로 지우면 됩니다. 다시 켜고 싶으면 base의 원본 settings.json 에서 그 항목을 복사해 넣으면 됩니다.

권하는 건 그대로 두는 쪽입니다. 셋 다 비개발자가 가장 자주 떨어지는 자리를 막아 주는 것이라, 끄면 그 자리가 다시 본인 책임으로 돌아옵니다.

새 훅을 본인이 추가해야 하나

거의 그럴 일 없습니다. base가 박은 세 개가 비개발자 워크플로에서 컨텍스트가 무너지는 가장 큰 자리들을 이미 막고 있습니다. 본인이 따로 추가하지 않아도 충분합니다.

만약 추가하고 싶은 자리가 정말 생긴다면 셸 스크립트를 짜야 합니다. 그 자리는 이 가이드의 범위를 벗어납니다. 전문가용 매뉴얼의 architecture 페이지에 동일한 훅 시스템을 다른 호흡으로 정리해 두었으니 거기서 시작하시면 됩니다.

다음 단계

자동 안전망이 알아서 도는 자리를 알았다면, 다음 장은 워크플로 자체가 멈춰 버리는 자리입니다. AI가 같은 실수를 두 번 반복하거나, 새 세션에서 어디까지 했는지 기억이 안 날 때 부르는 두 슬래시 명령어를 08-when-ai-gets-stuck.md 에서 다룹니다. 본격적인 배포는 그 다음 09-distribution.md 입니다.