Claude Code, 공식 문서엔 없는 숨은 설정들 — 소스코드를 뜯어보니

문서에 다 안 나와 있더라고요

Claude Code 써보신 분 많죠? 터미널에서 돌아가는 AI 코딩 에이전트예요. 기본 사용법은 공식 문서에 잘 정리돼 있는데, 막상 동작을 깊이 파고들면 문서가 친절하게 짚어주지 않는 숨은 설정이 꽤 많아요. 이걸 알면 Claude Code를 내 작업 흐름에 훨씬 정교하게 맞출 수 있거든요. 어떤 것들이 있는지 하나씩 풀어볼게요.

모든 설정의 중심, settings.json

Claude Code 설정은 settings.json 파일로 관리되는데, 위치가 세 단계로 나뉘어요. 내 컴퓨터 전체에 적용되는 사용자 설정(~/.claude/settings.json), 프로젝트마다 팀이 공유하는 프로젝트 설정(.claude/settings.json), 그리고 나만 쓰고 깃에는 안 올리는 로컬 설정(.claude/settings.local.json)이에요. 아래로 갈수록 우선순위가 높아서, 팀 공통 규칙은 프로젝트 설정에, 내 개인 취향은 로컬 설정에 두는 식으로 깔끔하게 나눌 수 있어요.

여기서 가장 실용적인 게 permissions예요. 어떤 도구나 명령을 매번 물어보지 않고 자동 허용할지(allow), 아예 막을지(deny), 꼭 한 번 물어볼지(ask)를 규칙으로 정할 수 있거든요. 예를 들어 npm run test는 알아서 돌리게 허용하고, rm이나 외부로 푸시하는 위험한 명령은 deny로 막아두면, 자동화의 편리함과 안전을 동시에 챙길 수 있어요.

환경 변수로 미세 조정하기

문서 바깥의 진짜 보물은 환경 변수예요. 어떤 모델을 쓸지 직접 지정하거나(ANTHROPIC_MODEL), 사용 통계 전송을 끄거나(DISABLE_TELEMETRY), 셸 명령 실행 타임아웃처럼 세세한 동작까지 변수로 조정할 수 있어요. 회사 정책상 외부 전송을 막아야 하거나, 특정 모델로 고정해야 하는 상황에서 특히 요긴하죠. 이런 건 평소엔 몰라도 되지만, 막상 필요할 때 알면 시간을 확 아껴주는 종류의 지식이에요.

제일 강력한 기능, hooks

개인적으로 가장 강력하다고 보는 건 hooks예요. 이게 뭐냐면, Claude Code가 동작하는 특정 순간에 내가 정한 셸 명령을 자동으로 끼워 넣는 기능이에요. 예를 들어 도구를 실행하기 직전(PreToolUse), 파일을 수정한 직후(PostToolUse), 내가 프롬프트를 보낼 때(UserPromptSubmit), 작업이 끝났을 때(Stop) 같은 시점마다 훅을 걸 수 있어요.

활용 예를 들면, 파일이 수정될 때마다 자동으로 포매터(prettier 같은 코드 정리 도구)를 돌리거나, 위험한 명령이 실행되려 할 때 훅에서 중간에 가로채 막아버리거나, 작업이 끝나면 알림을 보내는 식이에요. AI의 행동에 내 규칙을 강제로 끼워 넣는 안전장치이자 자동화 장치인 셈이죠.

그 밖에 알아두면 좋은 것들

이 외에도 프로젝트 맥락을 기억시키는 CLAUDE.md 메모리 파일, 자주 쓰는 작업을 슬래시 명령으로 만드는 커스텀 커맨드(.claude/commands/ 폴더에 마크다운으로 정의), 특정 역할에 특화된 서브에이전트, 그리고 외부 도구를 연결하는 MCP 서버 설정까지 있어요. 하나하나가 Claude Code를 ‘범용 도구’에서 ‘내 프로젝트 전용 도구’로 바꿔주는 레버예요.

한국 개발자에게 주는 시사점

핵심 교훈은 ‘AI 도구도 이제 설정으로 길들이는 시대’라는 거예요. 그냥 기본값으로 쓰는 것과, permissions와 hooks로 우리 팀의 규칙과 안전망을 새겨 넣어 쓰는 것은 생산성과 안정성에서 차이가 꽤 커요. 특히 여러 명이 함께 쓰는 프로젝트라면, 공유 settings.json과 CLAUDE.md에 팀 컨벤션을 박아두는 것만으로도 결과물의 일관성이 올라가거든요. 한 번쯤 시간 내서 내 설정 파일을 제대로 손봐둘 가치가 충분해요.