Anthropic의 Lydia Hallie는 Claude Code 훅 스크립트가 종료 코드 2로 끝나야 실패한 작업이 다시 수정으로 돌아간다고 설명했습니다 | DAKER 커뮤니티

개발자 책상 장면에서 검증 신호등 장면으로 이어지는 10초 모션 미리보기
설명용 생성 이미지로 만든 10초 모션 미리보기입니다.
고화질 일러스트풍으로 그린 개발자 책상 위 모니터와 체크 표시가 있는 작업 카드, 가운데에 한글 문구가 있는 설명용 생성 이미지
설명용 생성 이미지입니다.

Claude Code 훅 스크립트가 실패했을 때 종료 코드를 1로 돌려주면 그 작업이 완료로 표시되고, 2로 돌려줘야 Claude가 다시 고치러 갑니다. Anthropic의 Claude Code 팀에서 일하는 Lydia Hallie는 AI Engineer 채널 발표 「Rethinking Claude Code Best Practices」(2026년 11월 12일 게시, 약 17분)에서 이렇게 설명했습니다. 모델이 좋아지면서 사람이 하던 조종과 승인이 모델, 하네스, 실행 환경으로 옮겨 갔고, 그 자리를 비운 만큼 검증 지점을 직접 만들어 두라는 것이 발표의 요지입니다. 오늘 해볼 일은 하나입니다. 지금 쓰는 검증 스크립트가 실패할 때 어떤 종료 코드를 돌려주는지 확인하고, 필요하면 2로 바꿔 보는 것입니다.

이 글은 영상의 영어 자막(자동 생성)을 읽고 정리한 것이며, 수치와 표현은 모두 발표자가 말한 내용입니다. 이 글에서 Claude Code를 직접 실행해 확인한 것은 없습니다. 자막이 자동 생성이라 제품명은 발표 맥락과 함께 확인했고, 발표자는 모델을 Opus 5.5와 Fable 5.2라고 불렀습니다.

발표는 승인하던 사람의 자리를 모델·하네스·환경이 나눠 맡는다고 설명합니다

발표자는 올해 초의 세션과 지금의 세션을 비교했습니다. 올해 초에는 Opus 4.5 같은 모델을 쓰면서 작업이 일찍 멈추었고, 사람이 계속 바로잡았으며, CLAUDE.md에 「중요」 같은 강조 표현을 덧붙였습니다. 자동 모드도 없어서 모든 명령을 직접 승인하거나 위험한 권한 생략 옵션을 썼다고 했습니다. 지금 Anthropic 안의 세션은 수십 개를 동시에 몇 시간씩 돌리고, 세션이 스스로 결과를 검증하며, 어떤 세션이 다른 세션을 지휘하기도 한다고 했습니다.

발표자는 Anthropic이 10월에 올린 블로그 글을 언급하며, 하루 변경 건수가 5월 약 2,500건에서 9월 3만 건 이상으로 늘었다고 말했습니다. 그래서 개발자는 한 번에 한 세션을 보는 사람이 아니라 수십 개 세션의 관리자에 가까워졌고, 예전의 모범 사례였던 조종, 명령 승인, 금지, 결과 확인, 세션 시작은 이제 모델, 하네스, 환경 중 하나가 맡는다고 정리했습니다. 발표 마지막에 같은 내용이 다시 나옵니다. 조종은 모델이, 승인은 자동 모드가, 제한은 거부 규칙과 환경이, 확인은 테스트·훅·CI가 하고, 사람은 첫 세션을 시작하고 나온 결과를 검토하는 일만 남는다는 것입니다.

CLAUDE.md에는 코드에서 읽을 수 없는 사실만 남기라고 합니다

발표자는 예전 모범 사례를 따랐다면 CLAUDE.md에 「중요」나 「절대 하지 마」 같은 강조가 남아 있을 수 있다고 했습니다. 지금 모델에서는 그런 문구가 필요 없을 뿐 아니라 모델을 엉뚱한 방향으로 보내서 도구 호출은 늘고 결과는 나빠질 수 있다고 말했습니다. 발표자가 제시한 기준은 이렇습니다. CLAUDE.md에는 Claude가 코드만 봐서는 알 수 없는 것만 적습니다. 예를 들어 코드에 직접 드러나지 않지만 어떤 서비스가 아직 옛 소스를 쓰고 있다는 사실은 남길 만합니다. 반대로 어떤 스택을 쓰는지, 어디를 봐야 하는지는 이미 코드에서 보이므로 적을 필요가 없다고 했습니다.

발표자는 모델에 맞게 환경을 점검해 주는 명령으로 「doctor prompt audit」을 소개했습니다. 예를 들어 Opus 5.5를 쓰는 상태에서 이 명령을 실행하면 CLAUDE.md와 스킬을 살펴 새 모델에게 더 이상 필요 없는 내용을 알려 준다고 했습니다. 명령의 정확한 입력 형식은 영상에서 화면으로 보여 주었고, 이 글에서는 자막에 나온 이름만 옮깁니다.

자동 모드는 사람보다 위험한 명령을 더 잘 막았지만 약 10건 중 1건은 통과했습니다

자동 모드는 프로젝트 안의 파일을 읽고 고치는 일 외의 거의 모든 동작에 별도의 분류기를 돌리는 권한 모드입니다. 테스트 실행이나 의존성 설치처럼 안전하다고 아는 명령은 허용하고, 안전한지 불확실한 명령은 막습니다. 발표자는 자동 모드가 8월부터 기본 권한 모드가 되었다고 했습니다. 기본값은 이 폴더와 이 저장소만 신뢰하므로, 예를 들어 배포용 저장소로 푸시하는 명령은 막혀서 사람이 다시 개입하게 됩니다.

승인 요청이 너무 자주 뜬다면 설정에서 자동 모드를 일반 영어 문장으로 조정할 수 있다고 했습니다. 어떤 저장소, 버킷, 도메인을 신뢰하고 무엇을 항상 허용하거나 절대 하지 않을지 적으면 그 문장이 분류기에 전달되어 허용과 거부를 결정한다는 설명입니다.

발표자는 8월에 공개한 연구 결과를 인용했습니다. 자동 모드와 실제 사람이 승인하는 경우를 비교했더니, 분명히 위험한 명령을 잡아낸 사람은 약 14%였고 자동 모드는 89%를 막았습니다. 사람보다 훨씬 낫지만 약 10건 중 1건은 그대로 통과했다고 말했습니다. 그래서 보장이 필요한 규칙은 하네스에서 강제해야 한다는 결론으로 이어집니다.

거부 규칙은 도구 호출 전에 걸리고, 샌드박스는 실행된 뒤의 접근까지 막습니다

발표자가 말한 순서는 이렇습니다. 프로젝트에 특정 도구 호출을 막는 거부 규칙이 있으면 Claude Code가 그 규칙을 자동 모드 분류기보다 먼저 확인하고, 규칙에 걸린 호출은 분류기가 보지도 못합니다. 그래서 Claude가 절대 하지 않아야 하는 일에는 거부 규칙이 여전히 가장 확실하다고 했습니다. 무엇을 규칙으로 만들지는 Claude가 한 번 틀렸을 때 되돌릴 수 있는지로 가르라고 했습니다. 잘못 쓴 코드는 되돌리면 되지만, 커밋하지 않은 변경을 버리거나 이미 대화 기록에 들어간 키를 읽는 일은 규칙으로 막아야 한다는 뜻입니다.

그런데 거부 규칙에는 한계가 있습니다. 발표자의 예는 환경 변수 파일입니다. 거부 규칙을 걸면 cat 명령으로도 그 파일을 열 수 없습니다. 하지만 npm test처럼 평범한 명령은 자동 모드가 허용하고, 그 안에서 실행되는 의존성이나 Claude가 방금 쓴 스크립트가 오염되어 있으면 같은 파일이나 SSH 키를 읽어 낯선 서버로 보낼 수 있습니다. 권한은 도구 호출을 실행할지만 정하고, 실행이 시작된 뒤 무엇에 닿는지는 제한하지 못한다는 설명입니다. 사람이 일일이 승인하던 시절에도 npm test에 거부할 이유가 없으므로 그대로 허용했을 것이라고 했습니다.

해결 방법은 실행 환경을 좁히는 것입니다. 로컬에서는 샌드박스를 켜면 명령이 읽을 수 있는 파일, 쓸 수 있는 폴더, 닿을 수 있는 호스트를 운영체제가 강제하고, 그 명령이 띄운 자식 프로세스에도 같이 적용됩니다. 같은 거부 규칙이 운영체제까지 전달되어, 의존성이 환경 변수 파일을 열려고 하면 운영체제가 거절합니다. 다만 기본값으로는 컴퓨터의 대부분을 읽을 수 있으므로 SSH 키가 걱정이면 규칙을 더 추가해야 합니다. 또 샌드박스는 Claude가 실행하는 셸 명령과 그 하위 프로세스만 덮으며, Claude 자신의 파일, MCP 서버, 훅은 샌드박스 밖에서 돌아갑니다.

그래서 발표자는 클라우드 세션을 권했습니다. 저장소의 새 복사본이 있는 독립된 머신에서 돌아가므로 git에 없는 환경 변수 파일이나 SSH 키, GitHub 토큰이 처음부터 없고, 노트북을 닫아도 계속 실행됩니다. API 키가 필요하면 네트워크 시크릿으로 넣을 수 있어, 모델에게 보내지 않고 쓸 수 있다고 했습니다. 클라우드 세션의 네트워크는 기본적으로 패키지 저장소와 GitHub 같은 곳으로 제한되며, 다른 호스트는 환경에 도메인을 추가해야 합니다. 다만 머신은 버릴 수 있어도 그곳에서 나가는 것, 즉 푸시한 커밋이나 커넥터로 보낸 메시지는 되돌릴 수 없으므로, 거부 규칙을 저장소에 커밋해 두어 강제 푸시나 커밋에 섞인 비밀을 잡게 하라고 했습니다.

검증 지점은 통과·실패로 돌아오는 것이어야 하고, 훅은 종료 코드 2로 끝나야 합니다

사람이 모든 변경을 보던 때는 결과가 좋은지 알고 있었지만, 몇 시간 돌아간 세션의 결과를 마지막에 전부 읽을 수는 없습니다. 발표자의 예는 인증 방식을 새 API로 옮기라는 같은 지시입니다. 한 번은 옛 API를 남겨 둔 채 옮길 수 있고, 한 번은 신규 로그인에만 적용할 수 있고, 한 번은 모든 사용자를 로그아웃시킬 수 있습니다. 모두 그럴듯해 보이므로, 중간중간 통과 또는 실패로 돌아오는 확인 지점을 두라고 했습니다. 테스트, 빌드, 스크린샷 무엇이든 괜찮고, 사람은 전체 변경이 아니라 그 지점들만 검토하면 됩니다. 모든 사용자를 로그아웃시키는 실행은 첫 번째 확인에서 걸려 다른 방법을 찾게 됩니다.

설정 방법은 세 단계로 설명했습니다.

발표자가 따로 강조한 부분이 종료 코드입니다. 테스트가 실패하면 대부분의 도구는 종료 코드 1을 돌려주는데, 이 경우 Claude Code에서는 작업이 그냥 완료로 표시됩니다. Claude를 고치러 돌려보내는 것은 종료 코드 2이므로, 스크립트가 2로 끝나도록 만들라고 했습니다. 이렇게 하면 실패한 검사가 Claude에게 보이고, 통과할 때까지 되돌아가 고칩니다. PR 단계에서는 CI 검사 결과도 Claude가 볼 수 있으며, 위험이 낮은 변경은 모든 검사가 통과하면 GitHub가 자동으로 머지하는 기능을 켤 수도 있다고 했습니다. 다만 이것은 기본값이 아니고 변경의 위험도에 달렸다고 했습니다.

Anthropic 팀의 사례도 있었습니다. 모든 PR을 먼저 Claude가 리뷰하는데, 코드를 쓴 세션이 아니라 새로운 맥락에서 따로 구성한 에이전트 그룹이 찾아낸 버그를 한 번 더 확인합니다. 사람이 얼마나 볼지는 위험도에 따라 달라서, 문서 문구 같은 작은 변경은 자동 검사가 모두 통과하면 사람이 보지 않고, 보통의 제품 변경은 리뷰어 한 명, 위험한 변경은 두 명이라고 했습니다.

다음 단계는 세션 하나가 나머지 세션을 시작하고 검증하는 구조입니다

발표자는 자신이 여러 세션을 오가는 데 서툴다고 말하며, 앞으로는 세션을 직접 시작하지 않고 하나의 메인 세션이 오케스트레이터 역할을 하는 구조로 가고 있다고 했습니다. 베타 상태인 Claude Code 프로젝트가 그 예로, 할 일을 말하면 오케스트레이터가 작업을 나누어 세션을 시작하고 돌아온 결과를 추적합니다. 메인 세션은 코드를 직접 쓰지 않으므로 무엇을 할지 정하고 돌아온 것을 판단하는 데 강한 모델이 맞고, 발표자는 Fable을 예로 들었습니다. 끝나지 않은 결과가 돌아오면 다시 돌려보내고, 실제 작업을 하는 스레드에는 Opus 5.5 같은 모델을 쓴다고 했습니다. 메인 세션과 스레드의 모델은 따로 설정할 수 있고, 이 방식에서는 컨텍스트 압축이나 초기화 시점을 사람이 신경 쓰지 않아도 된다고 했습니다.

오늘 해볼 일 다섯 가지

발표자는 마지막에 직접 시도해 볼 순서를 제안했습니다. 해커톤이나 개인 프로젝트에서 Claude Code를 쓴다면 아래 순서로 하나씩 확인해 볼 수 있습니다.

  1. 평소 Claude에게 주던 것보다 훨씬 큰 일 하나를 골라 맡겨 봅니다. 발표자가 가장 먼저 제안한 것이 바로 이것입니다.
  2. CI가 정말 걱정하는 문제를 잡는지 확인합니다. 테스트가 통과해도 인증이 깨지는 구조라면 검증 지점이 아닙니다.
  3. 실행 환경의 네트워크 접근, 시크릿, 설정 스크립트를 정리합니다.
  4. CLAUDE.md에서 코드를 보면 알 수 있는 설명과 강조 표현을 덜어 내고, 코드에 드러나지 않는 사실만 남깁니다.
  5. 검증 훅이 실패했을 때 종료 코드를 2로 돌려주는지 확인합니다.

그리고 클라우드에서 시작해 세션이 어디서 막히는지, 아직 사람이 개입하는 곳이 어디인지를 보라고 했습니다. 그 지점이 다음에 Claude에게 넘길 일이라는 것이 발표자의 설명입니다. 발표자는 자세한 내용을 문서의 모범 사례 페이지에서 확인하라고도 했습니다.

이 글에서 확인한 것과 확인하지 못한 것

자주 묻는 질문

훅이 실패해도 작업이 완료로 표시된 적이 있다면 무엇을 확인해야 하나요? 발표 설명으로는 스크립트가 종료 코드 1로 끝났는지가 첫 확인 대상입니다. 이 경우 Claude Code는 실패를 알고도 작업을 완료로 표시하므로, 스크립트가 종료 코드 2로 끝나게 바꾸면 Claude가 실패를 보고 고치러 돌아갑니다.

자동 모드를 쓰면 거부 규칙은 필요 없나요? 발표자는 반대로 설명했습니다. 자동 모드는 사람보다 많이 막았지만 약 10건 중 1건은 통과했으므로, 절대 일어나면 안 되는 일은 거부 규칙으로 막고, 규칙이 닿지 못하는 스크립트 안의 접근은 샌드박스나 클라우드 세션으로 막으라는 것입니다.

CLAUDE.md는 비워 두라는 뜻인가요? 그렇지 않습니다. 코드에서 읽을 수 없는 사실, 예를 들어 코드에 직접 드러나지 않지만 아직 쓰이는 옛 소스 같은 정보는 남기라고 했고, 스택과 탐색 위치처럼 코드에서 보이는 내용을 덜어 내라는 설명입니다.

출처