클로드가 “작업을 끝냈습니다”라고 말했는데, 정작 테스트는 실행하지 않았다면 어디까지 믿어야 할까. 승인창을 계속 누르는 것도 답은 아니다. 자동화를 오래 돌릴수록 사람이 확인할 부분과 도구가 강제할 부분을 나눠야 한다.
MINDUNG이 정리한 리디아 할리의 Claude Code 강연은 이 구분을 다룬다. 안내파일은 짧게, 예외 없는 규칙은 권한과 훅으로, 완료 여부는 실행 결과로 확인한다. 원강연 자막과 공식 문서를 2026년 11월 19일 기준으로 대조해, 바로 적용할 순서와 주의점을 정리했다.
1. CLAUDE.md에는 코드로 알 수 없는 맥락을 남긴다
CLAUDE.md를 길게 쓰면 일을 더 잘할 것 같지만, 이미 코드에 드러난 설명과 낡은 지시가 쌓이면 정작 필요한 예외가 묻힌다. 공식 권장사항도 파일을 짧게 유지하라고 안내한다.
예를 들어 사용 중인 언어와 프레임워크는 저장소에서 찾을 수 있다. 반면 “이 함수는 내부 호출이 없어 보여도 구형 모바일 앱이 사용한다”는 맥락은 코드만 읽어서 알기 어렵다. 이런 정보가 안내파일에 남을 이유다.
남길 내용과 옮길 내용을 나눠 보자.
- 유지: 외부 의존 관계, 비표준 동작의 이유, 반드시 지켜야 하는 호환 조건
- 정리: 파일과 모순되는 오래된 경로, 모델이 코드에서 확인할 수 있는 설명
- 별도 관리: 특정 작업 절차는 스킬, 일부 경로에만 필요한 지시는 범위가 정해진 규칙
- 도구로 강제: 비밀파일 접근 금지나 완료 전 검사처럼 예외를 허용하면 안 되는 조건
현재 문서는 /doctor prompt-audit로 오래된 모델용 지시나 모순된 안내를 점검할 수 있다고 설명한다. 결과는 삭제 후보로 검토하자. 중요한 팀 규칙까지 확인 없이 없애는 명령으로 사용할 필요는 없다.

2. 자동 모드, 거부 규칙, 샌드박스는 서로 다른 장치다
자동 모드는 사람이 승인하던 행동을 분류기가 검토하는 방식이다. 아무 판단 없이 모든 권한을 허용하는 설정과는 다르다. 그렇다고 판단 실수가 없어지는 것도 아니다.
Anthropic의 공개 실험은 유료 전문 테스터 1,053명의 코딩 실험에서 승인 요청 하나를 위험한 명령 문구로 바꿨다. 그 조건에서 사람의 차단 비율은 13.6%, 자동 모드는 89%였다고 보고했다. 실제 위험 명령을 실행한 실험은 아니며, 모든 업무에서의 보편적인 차단율도 아니다.
안전 설정은 다음처럼 역할을 나누면 이해하기 쉽다.
- 권한 규칙: 어떤 도구·파일·도메인 접근을 허용하거나 거부할지 정한다.
- 자동 모드: 허용 여부를 사람이 매번 판단하던 일부 행동을 검토한다.
- 샌드박스: 실행된 명령과 그 하위 프로세스가 접근할 파일·네트워크 범위를 제한한다.
가령 npm test를 승인해도 그 안에서 실행되는 패키지 코드의 모든 행동을 사람이 읽은 것은 아니다. 샌드박스 문서는 파일·네트워크 경계를 운영체제 수준에서 적용하고, 관련 권한 규칙을 경계 설정에 병합한다고 설명한다.
다만 플랫폼 지원, 활성화 여부, 제외 명령과 샌드박스 밖 실행 경로를 확인해야 한다. .env 읽기 거부만 추가했다고 이미 프로세스 환경변수에 들어간 비밀값까지 사라지는 것도 아니다. 설정 이름보다 실제 실행 경로에 어떤 경계가 적용되는지를 확인하자.
3. 훅은 ‘검사해 줘’라는 부탁을 실행 절차로 바꾼다
프롬프트에 “끝나면 테스트해”라고 적는 것과, 종료 시점에 검사 명령을 실행하도록 설정하는 것은 다르다. 훅은 특정 이벤트에서 정해둔 명령을 실행한다.
여기서 영상의 exit 2를 모든 훅에 똑같이 적용하면 안 된다. 공식 훅 문서는 이벤트마다 동작을 나눈다.
- PreToolUse: 도구 실행 전에 종료 코드 2로 호출을 차단할 수 있다.
- Stop: 종료 코드 2로 작업 종료를 막고, 표준 오류의 피드백을 전달해 대화를 이어갈 수 있다.
- PostToolUse: 이미 도구가 실행된 뒤다. 실패를 알릴 수는 있어도 완료된 변경을 취소하지는 못한다.
일반적인 테스트 명령이 실패하며 반환하는 코드 1이 자동으로 차단 신호가 되는 것도 아니다. 검사 결과를 해당 이벤트가 이해하는 실패 방식으로 전달해야 한다.

로컬 npm 프로젝트의 Stop 훅 예시
다음은 npm run lint와 npm test가 정의된 로컬 프로젝트를 가정한 예시다. 기존 .claude/settings.json을 통째로 덮어쓰지 말고 필요한 항목만 병합해야 한다. 클라우드 프로젝트 스레드에 그대로 적용되는 설정도 아니다.
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "sh \"$CLAUDE_PROJECT_DIR/.claude/hooks/verify-completion.sh\"",
"timeout": 120
}
]
}
]
}
}
해당 경로에 둘 셸 스크립트는 아래와 같다. 검사 명령은 자신의 프로젝트에 맞게 바꾸자. 실행 명령과 시간 제한도 실제 검사 소요시간에 맞춰야 한다.
#!/bin/sh
set -u
cd "${CLAUDE_PROJECT_DIR:?CLAUDE_PROJECT_DIR is required}" || exit 2
if npm run lint && npm test; then
exit 0
else
printf '%s\n' 'Completion checks failed. Read the failures, fix the code, and rerun checks.' >&2
exit 2
fi
이 예시는 lint가 실패하면 테스트까지 진행하지 않고 피드백을 반환한다. npm을 명시적인 대역 프로그램으로 바꾼 셸 검사에서 성공, lint 실패, 테스트 실패, 테스트 명령 오류의 네 분기와 종료 코드 변환을 확인했다. 실제 앱 검사나 Claude Code 통합 실행을 검증한 것은 아니다.
설정 적용 여부는 별도로 시험해야 한다. 실패하는 검사를 넣었을 때 실제로 종료가 막히는지, 스크립트 경로가 틀리거나 시간이 초과돼도 기대대로 처리되는지 확인하자. 단순 오류가 비차단 오류로 끝나는 경로가 있기 때문이다.
또한 검사 실패가 계속되면 수정과 재검사가 반복될 수 있다. 공식 문서는 stop_hook_active와 연속 종료 차단 제한을 설명한다. 이런 보호 장치가 있다고 전체 수정이 정해진 횟수 안에 성공한다는 뜻은 아니다. 비용 한도와 중단 기준을 두고, 최종 병합은 CI 검사로 별도 차단하는 편이 안전하다.
4. 클라우드 세션에서는 설정의 상속 범위부터 확인한다
노트북을 덮어도 작업이 이어지는 클라우드 세션은 긴 작업에 유용하다. 하지만 “내 컴퓨터가 아니니 비밀값 문제도 없다”는 결론은 성급하다.
Anthropic 호스팅 환경은 새 복제본과 격리된 실행 환경을 사용한다. 공식 클라우드 문서는 GitHub 자격증명과 네트워크 시크릿을 프록시 측에서 요청에 붙이는 경로를 설명한다. 일반 환경변수와는 다른 방식이다. 모든 키가 어떤 설정에서도 모델에 보이지 않는다는 보장은 아니다.
저장소에 비밀파일을 커밋했다면 복제본에도 들어갈 수 있다. 네트워크 허용 범위, 환경변수 주입, 로그와 외부 전송도 따로 살펴야 한다.
특히 설정 문서의 구분을 놓치기 쉽다.
- 프로젝트의 클라우드 스레드: 저장소
.claude/settings.json의 권한 규칙·훅·환경변수가 적용되지 않는다고 명시되어 있다. - 프로젝트 스레드가 아닌 단일 저장소 클라우드 세션: 공유 설정을 읽는 경로가 있다.
따라서 로컬에서 검증한 거부 규칙과 Stop 훅이 클라우드에서도 그대로 동작한다고 가정하면 안 된다. 실행 환경에 맞는 제어 경로를 구성하고, 실제 적용 여부를 확인해야 한다. 로컬·일반 클라우드 세션·프로젝트 스레드를 같은 환경으로 취급하지 말자.
5. 병렬 세션은 역할 분담과 합치는 기준이 있어야 한다
새 프로젝트 경험은 조정 역할의 세션과 실제 작업을 하는 스레드를 나눈다. 각 스레드는 자신의 브랜치와 저장소 복제본에서 작업하고, 조정 세션은 일을 나누고 결과를 검토한다. 단계적으로 제공되는 베타이므로 자신의 계정에서 제공되는 범위도 확인해야 한다.
영상의 특정 모델 조합을 고정된 정답으로 외우기보다 역할을 먼저 설계하는 편이 낫다. 작업을 분해하고 누락을 찾는 역할과, 코드를 수정하는 역할은 요구하는 능력이 다르다.
- 조정 세션: 완료 기준, 작업 경계, 의존 관계, 실패 보고를 관리한다.
- 작업 스레드: 정해진 범위의 수정과 해당 검증을 수행한다.
- 독립 리뷰: 작성 과정의 설명을 그대로 믿지 않고 변경과 요구사항을 새로 대조한다.
- CI와 사람: 합친 결과를 검사하고, 인증·권한·배포처럼 위험한 변경의 최종 승인을 맡는다.
브랜치를 나눈다고 충돌이 없어지는 것은 아니다. 여러 스레드가 같은 파일이나 의존성을 바꾸면 통합 시 문제가 생길 수 있다. 각 작업의 통과 보고와 통합된 결과의 통과 여부를 분리해서 확인하자.

큰 작업을 맡기기 전의 완료 기준
“로그인을 새 API로 바꿔 줘”보다 “기존 세션 유지, 실패 시 복구, 구형 호출 제거 여부까지 검증해 줘”가 결과를 판단하기 쉽다. 지시를 길게 늘리는 대신 검사할 수 있는 조건을 명확히 하자.
작업을 요청할 때는 다음 다섯 항목을 정해두면 된다.
- 변경 범위: 수정할 기능과 건드리지 않을 경계
- 성공 조건: 사용자가 확인할 동작과 유지할 호환성
- 검증 방법: 실행할 명령, 테스트와 통합 검사
- 운영 경계: 접근 가능한 자료·도메인·자격증명과 비용 한도
- 보고 형식: 변경 내용, 실제 실행 결과, 미검증 항목과 남은 문제
검사가 없는 큰 작업을 먼저 맡기기보다는, 작은 작업에서 일부러 실패를 만들어 제어가 작동하는지 확인해 보자. 그 뒤 작업을 넓히면 자동화를 믿을 수 있는 범위도 함께 넓힐 수 있다.
함께 읽을 글
참고자료
- MINDUNG, 리디아 할리의 Claude Code 사용법 해설
- Lydia Hallie, Rethinking Claude Code Best Practices 원강연
- Claude Code 권장 사용법
- 자동 모드와 승인 실험
- 권한 규칙
- 샌드박스
- 훅과 이벤트별 종료 코드
- 클라우드 세션
- 로컬·클라우드 설정 적용 범위
- 프로젝트와 병렬 스레드
캡처는 원영상의 해설·비평을 위한 장면 인용이다. 강연자의 운영 경험, 회사의 실험 결과, 현재 공식 문서와 이 글의 적용 예시를 구분했다. 실제 Claude Code 설정 변경, 자동 모드 실행, 클라우드 세션 생성이나 안전성 공격 실험은 수행하지 않았다.
FAQ
CLAUDE.md는 짧을수록 무조건 좋은가요?
불필요한 지시를 줄이자는 뜻이다. 코드로 알 수 없는 외부 의존과 중요한 예외까지 지우면 안 된다. 감사 명령의 제안도 팀의 실제 조건과 대조해야 한다.
자동 모드만 켜면 비밀파일과 위험 명령을 막을 수 있나요?
그렇게 보장할 수 없다. 권한 규칙, 샌드박스의 적용 여부, 네트워크와 환경변수 노출을 함께 확인해야 한다. 공개 실험의 비율도 모든 업무에 적용되는 보장값이 아니다.
모든 훅에서 exit2가 같은 효과를 내나요?
아니다. Stop은 종료를 막고 피드백을 전달하며, PreToolUse는 실행 전 호출을 막는다. PostToolUse는 이미 실행된 동작을 취소하지 못한다. 이벤트별 공식 규칙을 확인해야 한다.
로컬 훅을 저장소에 올리면 프로젝트 스레드에도 적용되나요?
현재 설정 문서는 프로젝트의 클라우드 스레드에 저장소 설정 파일의 권한 규칙·훅·환경변수가 적용되지 않는다고 설명한다. 일반 단일 저장소 클라우드 세션과 구분하고 실제 제어 경로를 확인해야 한다.