자동으로 챙겨주는 안전망

이 페이지는 본인이 명령을 외우지 않아도 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 입니다.