Claude Code 구성과 활용 노하우 (settings.local.json 및 settings.json)

settings.json을 통한 환경 맞춤 설정

settings.json 파일을 이용하면 Claude Code의 동작 방식과 권한을 자세히 조절할 수 있습니다. 사용자별, 프로젝트별로 따로 관리할 수 있고, 각 옵션마다 다양한 상세 설정이 가능합니다. 예를 들면, 특정 명령어 허용/거부, 환경 변수 지정, 커스텀 훅 설정 등이 있어 작업 환경을 유연하게 만들고 팀 협업에도 적합합니다.

권한 관리로 데이터 보호하기

Claude Code는 세분화된 권한 관리 기능을 제공합니다.

allow, deny 등 규칙을 설정해 특정 명령어나 파일 접근을 제한할 수 있습니다.
민감한 파일(예: .env, secrets, API 키 등)은 permissions.deny 옵션으로 아예 접근을 차단할 수 있어, 정보 유출 걱정 없이 안전하게 사용할 수 있습니다.

env file 을 배제한 모습. curl 로 정보를 빼갈 수 있기 때문에 curl 도 제한.

{
  "permissions": {
    "allow": [],
    "deny": ["Bash(curl:*)", "Read(./.env)", "Read(./.env.*)"],
    "ask": []
  }
}

설정 우선순위와 계층 구조

설정은 여러 단계로 적용되며, 우선순위에 따라 높은 단계의 설정(기업 관리 정책)이 개인이나 프로젝트 설정을 덮어씁니다.

기업 정책 > CLI 일회성 설정 > 프로젝트별(local/global) > 사용자 전체 설정 이 구조 덕분에 조직 전체의 보안 정책을 철저하게 적용하면서도, 각 프로젝트와 사용자의 개별 맞춤도 가능합니다.
전체 설정은 ~/.claude/settings.json에 정의되며 모든 프로젝트에 적용됩니다.
프로젝트 설정은 프로젝트 디렉토리에 저장됩니다:
- .claude/settings.json은 소스 제어에 체크인되어 팀과 공유되는 설정용
- .claude/settings.local.json은 체크인되지 않는 설정으로, 개인 선호도와 실험에 유용합니다. Claude Code는 생성될 때 .claude/settings.local.json을 무시하도록 git을 구성합니다.

서브에이전트로 AI 보조자 만들기

원하는 용도에 맞는 AI 서브에이전트를 직접 정의할 수 있습니다.

YAML 프론트매터가 담긴 Markdown 파일 형태로 만들며, 사용자는 개인 또는 프로젝트 디렉터리 내에 파일을 저장합니다.
각 서브에이전트에는 독자적인 프롬프트와 툴 권한을 부여할 수 있습니다.
다양한 작업을 자동화하거나 전문화된 어시스턴트로 활용할 수 있어 개발 흐름을 한층 높여줍니다.

다양한 환경 변수 활용

Claude Code는 설정 파일이나 운영 환경에서 여러 환경 변수로 동작을 세밀하게 조정합니다. 예를 들어 API 키, 인증 토큰, 요청 헤더, 시간 제한, 모델 종류, 자동 업데이트 설정 등, 수십 가지 이상의 값으로 세션의 동작을 제어할 수 있습니다.

CLI 명령으로 설정 빠르게 관리하기

아래처럼 다양한 명령어로 설정 값을 쉽게 조회, 변경, 추가, 삭제할 수 있습니다. 프로젝트용과 전역용을 구분해 관리도 가능합니다.

# 설정 목록 확인
claude config list

# 특정 설정 값 확인
claude config get <key>

# 설정 변경
claude config set <key> <value>

# 리스트에 값 추가/제거
claude config add <key> <value>
claude config remove <key> <value>

# 전역 설정
claude config set -g <key> <value>

권한별 작업 가능 도구 안내

Claude Code는 파일 편집, 셸 명령 실행, 웹 검색, 패턴 검색 등 다양한 도구를 지원합니다. 일부 도구(파일 편집, 셸, 웹 연결 등)는 별도 권한 허용이 필요하며, 이를 미리 지정해두면 보안과 효율을 동시에 챙길 수 있습니다.

후크로 동작 자동화

도구 사용 전후로 원하는 커맨드를 실행하는 ‘후크’ 기능을 사용할 수 있습니다. 예를 들어, 파일 수정 후 자동 코드 포매팅이나 특정 경로의 작업 차단 등 다양한 방식으로 작업 프로세스를 자동화할 수 있습니다.

시스템 프롬프트 직접 커스텀하기

공식 시스템 프롬프트를 공개하지 않지만, 사용자는 CLAUDE.md 파일이나 커맨드 옵션으로 자체 시스템 프롬프트를 추가할 수 있습니다. 이 기능을 이용해 Claude Code의 행동을 맞춤화하거나 AI의 응답 스타일을 세밀하게 제어할 수 있습니다.

출처 및 참고 : Claude Code 설정 - Anthropic