자동으로 챙겨주는 안전망

이 페이지는 본인이 명령을 외우지 않아도 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/state/progress.md 의 마지막 30 줄은 최근 진행 이력을 담고 있습니다.
.claude/state/feature_list.json 은 본인 SaaS 가 약속한 기능 목록과 통과 여부를 담고 있습니다.
docs/design/saas-spec.md 의 첫 50 줄은 컨셉과 시나리오, 데이터 모델을 담고 있습니다.
.claude/agent-memory/MEMORY.md 는 프로젝트 결정 캐시의 인덱스입니다.

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

처음 한 번은 아무 출력이 없습니다: base 를 막 클론한 직후 첫 세션에는 위 파일들이 아직 없습니다. 그래서 스크립트가 아무것도 출력하지 않고 조용히 끝납니다. 이때는 /start 라우터가 빈 템플릿 (active.md, progress.md, MEMORY.md) 을 자동으로 만들어 줍니다.

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

두 번째 안전망: 한 줄 적어 두라고 알려 줍니다

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

💡 다음 세션을 위해 한 줄 적어두면 이어서 시작하기 편해요:
   파일: .claude/session-state/archive/active.md
   예시: "checkout 흐름 e2e 시나리오 한 줄 짜고 /test-saas 돌리기"

이 파일은 비개발자가 가장 자주 비워 둡니다. “다음에 무엇을 할지 적어 두기” 가 습관으로 잡혀 있지 않아서, 한 세션이 끝날 때 그냥 창을 닫게 됩니다. 그러면 다음 세션의 자동 복원 메시지가 빈 채로 시작되고, 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 이력에 남습니다. 이 훅이 그 상황을 막아 줍니다.

특히 saas-base 에서는 lint 가 FSD boundaries 와 jsx-a11y 두 가지를 같이 봅니다. AI 가 features/ 안에서 다른 features/ 슬라이스를 직접 import 하거나, <img> 에 alt 를 빼먹으면 이 훅에 걸립니다.

정상 모습 (통과):

🔍 commit 전 자동 검사 (typecheck + lint)…
✓ typecheck 와 lint 를 통과했어요. commit 을 진행합니다.

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

비정상 모습 (차단):

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

src/features/checkout/ui/CheckoutButton.tsx
  14:7  error  Cross-feature import not allowed: features/checkout cannot import features/sign-in
  22:3  error  img elements must have an alt prop  jsx-a11y/alt-text

이때 그 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 페이지 에 같은 훅 시스템을 다른 방식으로 정리해 두었으니 거기서 시작하시면 됩니다.

다음 단계

자동 안전망이 알아서 처리하는 것을 알았다면, 다음 장은 본인 SaaS 를 호스팅에 올려 사용자 브라우저에 닿게 하는 단계입니다. Vercel, Netlify, Cloudflare Pages, self-host 네 갈래는 08-distribution.md 에서 다룹니다. 그 사이에 무언가 동작하지 않으면 09-troubleshooting.md 의 증상별 항목을 먼저 봅니다.