Claude Code의 숨겨진 설정: 공식 문서가 알려주지 않는 것(그리고 무시해야 할 것)

최근 한 개발자가 Claude Code의 소스 코드를 직접 읽고, 공식 문서에서 대충 넘어가는 모든 내용을 정리하여 글을 올렸습니다. 이 글은 수백 개의 추천을 받으며 Hacker News 메인 페이지에 올라갔고, 댓글창은 소위 "소스 코드를 읽었다"는 게시물에서 흔히 볼 수 있는 반응을 보였습니다. 절반은 즐거워했고, 나머지 절반은 "문서화되지 않은 것"과 "이것에 의존해야 한다"는 말은 같은 의미가 아니라고 지적했습니다.

두 반응 모두 옳습니다. 대부분의 사람들이 전혀 건드리지 않는 Claude Code 설정 계층이 실제로 존재하며, 그중 대부분은 문서화되어 있습니다. 다만 설정이 묻혀 있거나, 설정 페이지와 훅 (hooks) 참조 문서에 나뉘어 있어 두 가지를 연결 짓기 어려울 뿐입니다. 소스 코드에서 역공학 (reverse-engineered)된 아주 작은 부분도 있는데, 이는 말 그대로 흥미로운 정보일 뿐 핵심적인 기능(load-bearing)으로 취급해서는 안 됩니다. 여기서는 정말 알 가치가 있는 내용과 그 경계가 어디인지에 대한 솔직한 버전을 소개합니다.

아무도 읽지 않는 설정 계층

Claude Code를 설정하는 거의 모든 사람은 세 가지 단계에서 멈춥니다. 프로젝트 지침이 담긴 CLAUDE.md 파일, 매번 npm 명령어를 실행할 때마다 묻지 않도록 하는 권한 허용 목록 (permission allowlist), 그리고 모델 선택기 (model picker)입니다. 이것이 90%의 사례이며, 이 정도로도 충분합니다.

공식 설정 문서는 그보다 훨씬 더 깊은 내용을 다루고 있는데, 사람들이 놓치는 부분이 바로 여기입니다. 명령줄 (command line)에서 설정할 수 있는 모든 환경 변수 (environment variable)는 settings.json의 env 키 아래에 저장될 수 있습니다. 즉, 모든 팀원에게 셸 (shell)에서 변수를 내보내라고(export) 요청하는 대신, 프로젝트의 .claude/settings.json에 커밋함으로써 팀 전체에 설정을 배포할 수 있다는 뜻입니다. 권한 (Permissions) 또한 잘 활용되지 않는 또 다른 요소입니다. 권한은 대부분의 설정이 작동하는 방식처럼 범위 (scope)에 따라 덮어쓰는 것이 아니라, 병합 (merge)됩니다. 사용자 수준의 규칙, 프로젝트 규칙, 그리고 모든 관리된 설정이 모두 쌓이게 (stack) 됩니다. 이것이 당신이 "제거한" 권한이 때때로 여전히 적용되는 이유입니다. 스택의 다른 어딘가에 설정되어 있기 때문입니다.

만약 당신의 팀원이 동일한 리포지토리(repo)에서 사용하는 Claude Code가 왜 당신의 것과 다르게 동작하는지 궁금했던 적이 있다면, 대개 이것이 그 답입니다. 모델의 문제가 아닙니다. 아무도 그 순서를 정의하지 않은 세 개의 설정 파일이 병합되고 있기 때문입니다.

Hook(훅)은 진정한 강력함이 있는 곳이자, 진정한 실수(footguns)가 발생하는 곳입니다

Hook(훅)은 Claude Code를 단순한 채팅창으로 생각하는 사람과 이를 빌드 시스템(build system)으로 변모시킨 사람을 구분 짓는 기능입니다. Hook(훅)은 특정 라이프사이클(lifecycle) 시점에 코드를 실행합니다: 도구(tool)가 실행되기 전, 편집(edit) 후, 세션이 시작될 때, 또는 Claude가 당신의 입력을 기다리고 있을 때 말입니다.

공식 Hook(훅) 레퍼런스(reference)는 이제 여러 가지 Hook(훅) 유형을 문서화하고 있으며, 이는 진정으로 숙지할 가치가 있습니다. **Command hook(커맨드 훅)**은 셸 명령(shell command)을 실행합니다. **Prompt hook(프롬프트 훅)**은 모델에 단발성 질문을 보내고 yes/no 형태의 JSON 결정을 받아오는데, 이는 "이것을 허용해야 하는가"가 정규 표현식(regex)이 아닌 판단의 영역일 때 유용합니다. **Agent hook(에이전트 훅)**은 결정을 내리기 전에 Grep 및 Glob을 사용하여 파일을 읽을 수 있는 서브 에이전트(subagent)를 생성합니다. 정규 표현식에서 빠른 모델 호출로, 그리고 완전한 에이전트로 이어지는 이 단계적 발전은 문서에서도 설명하는 부분이며, 대부분의 사람들이 존재조차 모르는 부분입니다.

역공학(reverse-engineering) 분석 글은 한 걸음 더 나아가, Hook(훅)이 실행 도중 동작을 제어하기 위해 더 풍부한 JSON을 반환할 수 있다고 주장합니다: 강제 허용 또는 거부를 위해 permissionDecision을 전달하는 PreToolUse Hook(훅), 텍스트를 주입하기 위한 additionalContext 필드, 또는 명령이 실행되기 전에 재작성하기 위한 updatedInput 등이 그것입니다. 이 중 일부는 문서화된 동작과 깔끔하게 일치합니다. 하지만 백그라운드 async(비동기) Hook(훅)이나, Hook(훅)을 단 한 번만 실행하고 스스로를 제거하는 once 플래그와 같은 일부 내용은 저자가 내부 필드(internal fields)를 해석한 결과입니다. 이러한 단계의 정보는 운영 환경(production)에 배포할 설정이 아니라, 확인을 위한 단서로 취급하십시오. 문서가 선을 긋는 이유는 내부 필드 이름이 예고 없이 릴리스(release) 사이에 변경되기 때문이며, 조용히 실행을 멈춰버리는 Hook(훅)은 아예 없는 것보다 더 나쁘기 때문입니다.

여기에는 쉽게 간과하기 쉬운 보안 측면도 존재합니다. HTTP 훅(hooks)은 요청 헤더(request headers)에 환경 변수(environment variables)를 보간(interpolate)할 수 있으며, 이제 설정(settings)을 통해 훅이 읽을 수 있는 변수 이름의 범위를 제한할 수 있습니다. 만약 Claude Code를 실제 비밀 정보(secret)를 다루는 무언가와 연결하고 있다면, 이 허용 목록(allowlist)은 선택 사항이 아닙니다. 이는 하나의 엔드포인트로 인증 토큰(auth token)을 보내는 훅과, 사용자의 환경 변수 전체를 읽을 수 있는 훅 사이의 차이를 만듭니다.

이것이 보기보다 중요한 이유

저는 이러한 도구들의 세부 사항을 파고들며, 제품이 주장하는 기능과 실제로 실행했을 때의 기능이 어떻게 다른지 비교하는 데 많은 시간을 보냅니다. Claude Code는 제가 끊임없이 목격하는 패턴, 즉 '발표 자료(deck)와 실제 배포(deployment) 사이의 간극'을 보여주는 거의 완벽한 사례 연구입니다. 마케팅 측면의 표면적인 기능은 "코드를 작성한다"입니다. 하지만 실제 제품은 권한 모델(permissions model), 라이프사이클 훅(lifecycle hook) 시스템, 그리고 세 가지 범위(scopes)에 걸쳐 병합되는 설정 계층 구조(settings hierarchy)를 갖춘 구성 가능한 런타임(runtime)입니다. 가치의 대부분은 두 번째 설명에 들어 있으며, 온보딩(onboarding) 과정에는 거의 들어 있지 않습니다.

"소스 코드를 읽어보았다"라는 장르가 존재하는 이유가 바로 이 간극 때문입니다. 문서화된 표면이 실제 기능보다 작을 때, 누군가는 결국 탐험을 떠나 발견한 내용을 정리하여 작성하게 됩니다. 그것은 건강한 현상입니다. 하지만 여기서 얻어야 할 교훈은 "문서화되지 않은 플래그(flags)를 설정하라"가 아닙니다. "문서화되어 있지만 묻혀 있는 80%의 기능이 이미 당신이 사용 중인 것보다 훨씬 많다"는 것입니다. 권한 규칙(permission rules)이 의도한 대로 병합되도록 하세요. 팀의 환경 설정(env config)을 커밋된 설정 파일(committed settings file)로 옮기세요. 취약한 정규 표현식(regex) 훅 하나를 프롬프트 훅(prompt hook)으로 교체하세요. 역공학(reverse-engineered)을 시도할 필요도 없이, 그것만으로도 일주일간의 실질적인 워크플로 개선을 이룰 수 있습니다.

소스 코드나 3,000단어 분량의 분석 글을 읽을 필요가 없는 버전을 원하신다면, 그것이 바로 제가 계속해서 수집하고 있는 바로 그 내용입니다. 즉, 실제로 실질적인 변화를 만들어내는 설정(configs), 훅 패턴(hook patterns), 그리고 CLAUDE.md 설정법들을 바로 복사해서 붙여넣고 다음 단계로 넘어갈 수 있도록 정리해 두는 것입니다. 도움이 될 수 있도록 tools.thesoundmethod.me에 Claude Code 레시피 세트와 도구 디렉토리가 계속 업데이트되고 있습니다.

요약하자면 다음과 같습니다: Claude Code는 공식 문서가 보여주는 것보다 더 많은 설정이 가능하며, 가장 큰 승부처는 문서화되어 있지만 간과되는 계층에 있습니다. 또한 "문서화되지 않았다"는 것은 검증해야 할 이유이지, 신뢰해야 할 이유가 아닙니다. 먼저 공식 레퍼런스(official references)를 읽으십시오. 소스 코드 탐색(source-diving)은 공식 문서의 수준을 이미 넘어섰을 때를 위해 아껴두십시오.

출처 (Sources)

• "I read the Claude Code source code" (buildingbetter.tech): https://buildingbetter.tech/p/i-read-the-claude-code-source-code
• Claude Code 설정 레퍼런스 (공식): https://docs.claude.com/en/docs/claude-code/settings
• Claude Code 훅(hooks) 레퍼런스 (공식): https://docs.claude.com/en/docs/claude-code/hooks