Claude Code 실험이 재현 안 될 때 무엇부터 고정해야 하나 2026 — prompt보다 환경 스냅샷

Posted on by

같은 프롬프트를 넣었는데 어제랑 오늘 결과가 다르면 사람은 본능적으로 프롬프트부터 욕한다.

문장을 좀 더 다듬어볼까

지시를 세게 써볼까

한 줄 더 넣을까

근데 운영 쪽에서 보면 진짜 범인은 프롬프트가 아닌 경우가 꽤 많다.

작업 디렉터리, 파일 상태, 훅 설정, 권한, 불러온 문서, worktree 상태가 이미 달라져 있으면 프롬프트를 똑같이 넣어도 같은 실험이 아니다.

그래서 이 글은 2026년 4월 7일 기준으로 Claude Code 실험이 재현 안 될 때 프롬프트보다 먼저 무엇을 고정해야 하는지, 환경 스냅샷 순서대로 정리한 글이다.

Quick Answer
재현성 이슈가 생기면 프롬프트보다 먼저 환경을 고정하는 게 맞다.
Claude Code 공식 문서도 hooks, cwd 변경, file change, memory loading처럼 세션 중 반응하는 환경 요인을 분명히 갖고 있다.
그래서 최소한 cwd, git/worktree 상태, 변경 파일, settings/hooks, 불러온 지시문을 먼저 고정해야 한다.
한 줄로 줄이면
같은 prompt보다 같은 environment가 재현성에 더 중요할 때가 많다.

이 글이 필요한 사람

  • 같은 실험을 다시 돌렸는데 결과가 자꾸 바뀌는 사람
  • 프롬프트를 계속 만지는데도 원인을 못 잡는 사람
  • Claude Code hooks나 settings를 여러 군데서 쓰는 사람
  • worktree, subagent, 파일 변경이 섞인 운영을 하는 사람
  • 실험 노트를 팀 플레이북으로 바꾸고 싶은 사람

지금 결론

  1. 재현성 이슈의 첫 체크포인트는 프롬프트가 아니라 환경이다.
  2. 공식 docs 기준으로 hooks는 lifecycle과 file change, cwd change에 반응한다.
  3. memory 또한 전역, 프로젝트, 로컬 맥락을 다르게 불러온다.
  4. 즉 프롬프트만 저장해두면 반쪽 기록이다.
  5. 최소 환경 스냅샷을 남겨야 다음 실험도 같은 실험이 된다.

왜 프롬프트보다 환경을 먼저 보나

실험이 재현 안 되는 이유를 세 가지로 나누면 이렇다.

  • 입력이 바뀌었다
  • 환경이 바뀌었다
  • 기대 결과가 모호했다

프롬프트는 입력의 일부다.

그런데 Claude Code 운영에서는 입력 바깥의 환경도 꽤 크다.

예를 들면

  • 다른 파일이 열려 있고
  • 다른 CLAUDE.md가 로드됐고
  • 다른 hooks가 걸려 있고
  • 다른 worktree에서 실행했고
  • 이전 세션의 변경 파일이 남아 있고

이런 상태면 프롬프트가 똑같아도 실험은 이미 달라진다.

공식 문서가 말하는 환경 변수들

Hooks reference를 보면 Claude Code는

  • CwdChanged
  • FileChanged
  • InstructionsLoaded
  • ConfigChange
  • WorktreeCreate

같은 이벤트를 따로 가진다.

이건 꽤 노골적인 힌트다.

도구 설계 자체가 환경이 바뀌면 결과도 달라질 수 있다 를 전제로 하고 있다는 뜻이기 때문이다.

또 Memory 문서는

  • 사용자 메모리
  • 프로젝트 메모리
  • 로컬 메모리

같은 층을 설명한다.

즉 같은 프롬프트라도 어떤 메모리가 불려왔는지에 따라 행동이 달라질 수 있다.

이걸 안 남기고 프롬프트만 저장하면 실험 기록이 자꾸 허술해진다.

재현성 체크 순서

순서 먼저 고정할 것 왜 중요한가
1 작업 디렉터리(cwd) 다른 프로젝트면 다른 실험
2 git SHA / worktree 파일 상태가 달라질 수 있음
3 변경 파일 목록 Claude가 읽는 문맥이 달라짐
4 settings / hooks 자동 반응이 결과를 바꿈
5 로드된 지시문 CLAUDE.md와 rules가 달라질 수 있음
6 프롬프트 본문 그다음 비교 대상

이 표에서 핵심은 프롬프트가 중요하지 않다는 게 아니다.

프롬프트는 중요하다.

근데 6번이다.

사람이 너무 빨리 6번부터 본다는 게 문제다.

1단계: cwd부터 고정

공식 hooks 문서엔 CwdChanged 이벤트가 따로 있다.

이건 그냥 편의 기능이 아니라 작업 디렉터리가 바뀌는 순간 실험 맥락이 달라질 수 있다는 뜻이다.

예를 들어

  • 같은 레포가 아닌데 이름만 비슷한 폴더
  • worktree가 다른 브랜치
  • sample project와 production project 혼동

이런 것만으로도 결과는 쉽게 달라진다.

그래서 실험 기록엔 최소한 cwd 를 남겨야 한다.

2단계: git 상태와 worktree 고정

실험은 코드 위에서 돈다.

코드가 달라졌는데 프롬프트만 같다고 같은 실험일 리가 없다.

그래서 최소한

  • 현재 브랜치
  • git SHA
  • worktree 여부

는 같이 남기는 게 좋다.

이건 귀찮아 보여도 나중에 가장 빨리 사람을 살리는 정보다.

3단계: 변경 파일 스냅샷

Claude Code는 파일을 읽고, 파일을 바꾸고, 파일 변화에 반응한다.

공식 docs에 FileChanged 이벤트가 따로 있는 것도 이 때문이라고 보면 된다.

실험 전후로 어떤 파일이 달라졌는지 안 남기면 재현성은 금방 흐린다.

최소 스냅샷은 이 정도면 된다.

  • 변경된 파일 목록
  • 핵심 설정 파일 해시 또는 최종 수정시각
  • generated 파일 포함 여부

4단계: settings와 hooks 고정

이게 은근히 제일 많이 빠진다.

사람은 프롬프트는 저장한다.

근데 .claude/settings.json, .claude/settings.local.json, skill/agent frontmatter hook, plugin hook 차이는 자주 안 남긴다.

그런데 공식 hooks 문서를 보면 정의 위치에 따라 scope가 달라진다고 분명히 적혀 있다.

이건 곧 설정 위치가 다르면 같은 훅 이름이어도 실행 환경이 다를 수 있다는 뜻이다.

그래서 환경 스냅샷엔 최소한

  • 어떤 settings 파일이 활성인지
  • 어떤 hook이 켜져 있는지
  • 로컬 설정이 있는지

를 적어두는 게 좋다.

5단계: 로드된 지시문 고정

InstructionsLoaded 이벤트가 따로 있는 것도 같은 맥락이다.

실험 시점에

  • 어떤 CLAUDE.md
  • 어떤 .claude/rules/*.md
  • 어떤 skill 문서

가 실제로 로드됐는지에 따라 Claude 행동이 달라질 수 있다.

이건 거의 숨은 프롬프트다.

프롬프트 본문만 저장하고 지시문 로드 상태를 안 남기면 나중에 같은 입력을 넣어도 왜 다르게 나오는지 설명이 안 된다.

최소 환경 스냅샷 템플릿

아래 정도만 남겨도 재현성 품질이 꽤 올라간다.

date:
cwd:
branch:
git_sha:
worktree:
changed_files:
settings_scope:
active_hooks:
loaded_instructions:
prompt_id_or_title:
expected_output:
actual_output_summary:

이건 무슨 논문 프로토콜까진 아니고, 운영팀이 다시 같은 실험을 해볼 수 있게 만드는 최소셋이다.

숫자 예시처럼 보면

예시 1. 프롬프트 동일, 브랜치 다름

항목 어제 오늘
프롬프트 동일 동일
브랜치 main codex/test
결과 A B

이건 프롬프트 이슈보다 브랜치 이슈일 가능성이 더 크다.

예시 2. 프롬프트 동일, hooks 다름

항목 어제 오늘
프롬프트 동일 동일
hooks 없음 출력 길이 제한 hook 있음
결과 장문 압축된 답

이건 재현 실패가 아니라 환경이 달라진 거다.

예시 3. 프롬프트 동일, 로드된 rules 다름

항목 어제 오늘
프롬프트 동일 동일
로드 규칙 기본 blog-writing 포함
결과 자유 서술 템플릿화

이것도 같은 이유다.

제일 흔한 실수

1. prompt만 저장하고 cwd를 안 남기는 것

이러면 실험 기록이 반쪽이다.

2. settings.local 존재를 무시하는 것

로컬 설정은 생각보다 결과에 큰 차이를 만든다.

3. hooks가 켜져 있는지 안 적는 것

자동화는 흔적을 남기지 않으면 나중에 유령처럼 느껴진다.

4. worktree를 그냥 “레포 하나”로 보는 것

같은 레포여도 다른 worktree면 맥락이 다르다.

5. 기대 결과를 안 적는 것

이건 재현성보다 평가 문제인데, 같이 안 남기면 결국 뭐가 다른지 판단이 흐려진다.

5분 셀프 체크

아래 항목 중 셋 이상 비어 있으면 프롬프트를 다시 깎기 전에 환경 스냅샷부터 채우는 게 맞다.

  • cwd
  • 브랜치 / SHA
  • changed files
  • active hooks
  • loaded instructions
  • expected output

셋 이상 비어 있으면 지금은 prompt tuning보다 logging이 먼저다.

언제는 프롬프트를 먼저 봐야 하나

물론 항상 환경만 보는 건 아니다.

아래처럼 환경이 이미 완전히 고정된 상태면 그다음은 프롬프트를 보면 된다.

  • 같은 worktree
  • 같은 settings
  • 같은 hooks
  • 같은 지시문
  • 같은 파일 상태

그런데 현실에선 이 조건이 자주 안 맞는다.

그래서 운영팀은 프롬프트를 마지막에 보는 습관이 오히려 유리하다.

FAQ

Q1. 프롬프트가 제일 중요하지 않나?

중요하다.

하지만 재현성 문제에선 환경을 먼저 고정해야 프롬프트 비교가 의미가 생긴다.

Q2. hooks가 결과를 그렇게 많이 바꾸나?

그럴 수 있다.

공식 docs 기준으로 hooks는 lifecycle 여러 지점에서 자동 반응하므로, 출력 길이 제한, 검사, 차단, 후처리 같은 것이 결과 체감에 영향을 준다.

Q3. memory도 환경인가?

운영 관점에선 그렇다.

어떤 메모리 층이 로드됐는지가 행동에 영향을 주기 때문이다.

Q4. 최소한 뭘 남겨야 하나?

cwd, SHA, changed files, settings/hooks, loaded instructions, prompt 정도는 남기는 게 좋다.

Q5. 실험 노트를 플레이북으로 승격하려면 무엇이 필요하나?

같은 재현 체크 항목이 반복해서 등장할 때, 그걸 템플릿이나 script로 승격하면 된다.

다음에 읽을 글

Sources