Claude Code는 터미널에서 실행되지만 올바른 런타임, 디렉터리 권한, 자격 증명 저장 방식, 기업 프록시 설정이 필요합니다. 이 글은 로컬에서 무엇을 준비해야 하는지와 팀이 설정을 안전하게 공유하는 방법을 순서대로 설명합니다.
Claude Code는 터미널에서 사용하는 도구이며, 설치 후 명령 한 줄이면 바로 사용할 수 있습니다. 그래서 많은 사람이 네트워크에만 관심을 집중합니다. 하지만 실제로 막히는 지점은 다른 곳인 경우가 많습니다. 런타임 버전이 맞는지, 프로젝트 디렉터리에 쓰기 권한이 있는지, 키를 어디에 보관하는지, 회사 프록시를 어떻게 통과하는지, 동료끼리 하나의 설정을 어떻게 공유하는지가 핵심입니다.
먼저 런타임 환경과 의존성을 맞추기
먼저 공식 문서에서 현재 요구하는 런타임 버전을 확인하고 그 버전대로 설치합니다. 출시된 지 며칠밖에 되지 않은 버전을 시험 삼아 쓰는 것은 피하세요. 패키지 관리자는 팀 기준을 따르는 것이 좋습니다. npm, pnpm, yarn을 섞어 쓰면 lock 파일이 충돌할 수 있습니다. git과 기본 명령줄 도구도 필수입니다. 이런 도구는 저장소를 읽고, 명령을 실행하고, 테스트를 돌려야 하므로 하나라도 빠지면 즉시 오류가 납니다.
설치가 끝나면 빈 디렉터리에서 세 가지를 먼저 확인합니다. 파일을 읽을 수 있는지, 파일을 수정할 수 있는지, 테스트를 실행할 수 있는지입니다. 작은 디렉터리에서는 환경 문제가 빠르게 드러나지만, 업무 코드 안에서 찾기 시작하면 비용이 훨씬 커집니다.
프로젝트 디렉터리, 권한, 경계
사용자의 홈 디렉터리나 전체 디스크의 루트에서 실행하지 마세요. 명확한 저장소 루트를 지정하고 읽기와 쓰기 범위를 프로젝트 안에 제한합니다. 정말 더 넓은 범위가 필요할 때는 장기간 열어 두지 말고 일회성 권한을 부여합니다.
커밋하기 전에 .gitignore를 확인하세요. 로컬에서 생성된 캐시, 로그, 임시 스크립트는 버전 관리에서 제외해야 합니다. 팀에서 가장 쉽게 큰 문제가 되는 것은 코드 자체의 실수보다 로컬 디버깅 중 생성된 민감한 파일을 실수로 커밋하는 일입니다.
키와 자격 증명 보관 방법
API 키, 액세스 토큰 같은 비밀 정보는 환경 변수나 운영체제의 자격 증명 관리 기능을 사용하세요. 소스 코드, 설정 파일, 스크립트 주석에 직접 넣지 마세요. .env 자체도 .gitignore에 포함하고, 저장소에는 각 필드의 의미를 설명하는 예제 파일만 남겨 둡니다.
개인 자격 증명과 팀 자격 증명을 분리하세요. 여러 사람이 하나의 key를 함께 쓰면 문제가 생겼을 때 누가 사용했는지 확인하기 어렵습니다. 교체 주기도 미리 정합니다. 정기적으로 교체하고, 구성원이 떠나는 당일 교체하며, 유출이 의심되면 즉시 교체합니다. 노출을 발견하면 먼저 폐기한 뒤 조사하고, 로그부터 삭제하지 마세요.
기업 프록시 및 네트워크 환경과 맞추기
회사 네트워크에서 이런 도구를 사용할 때 문제는 연결 자체보다 프록시와 인증서인 경우가 많습니다. 기업 게이트웨이가 TLS 가로채기를 수행하면 인증서 체인을 신뢰하지 못해 도구가 바로 오류를 낼 수 있습니다. 이 경우 IT에 내부 루트 인증서를 요청해 올바른 신뢰 저장소에 설치하고, 검증을 임시로 끄는 방식은 피하세요.
로그인 과정에서 브라우저가 열리므로 명령줄과 브라우저는 가능하면 같은 egress 경로를 사용하는 것이 좋습니다. 이 경로는 고정되어 있고, 안정적이며, 제어 가능해야 합니다. 세 조건 중 하나라도 빠지면 반복 로그인이나 CAPTCHA 검증이 나타나기 쉽습니다. 노드를 자주 바꾸는 것은 하나를 고정해서 쓰는 것보다 검증을 더 쉽게 유발할 수 있습니다. 고정된 노드는 장기간 사용하는 사용자처럼 보이기 때문입니다.
실제로 egress가 적용되는지는 간단히 확인할 수 있습니다. 명령줄에 프록시 옵션을 붙여 IP 조회 서비스에 한 번 요청합니다.
curl -x http://127.0.0.1:7897 https://ipinfo.io
표시되는 주소가 예상한 주소와 같아야 합니다. 브라우저의 시간대와 언어도 egress 지역에 맞추는 것이 좋습니다. 한쪽은 북미를 가리키는데 다른 쪽은 UTC+8로 설정된 상태는 피하세요.
팀에서 설정을 공유하는 방법
공유해야 하는 것은 구조이지 비밀 정보가 아닙니다. 작업 디렉터리 규칙, 프록시 라우팅 규칙, 실행을 허용할 명령 범위, 코드 스타일 제약을 저장소의 버전 관리 가능한 설정 파일에 넣습니다. 키는 각자의 머신에서 환경 변수로 주입합니다.
새 구성원은 문서를 따라가며 동료에게 일일이 물어보지 않고도 바로 시작할 수 있습니다. 팀에서 여러 identity나 여러 환경을 동시에 사용한다면 PurpleMark로 각 환경의 브라우저 상태를 고정할 수도 있습니다. 나중에 특정 로그인이 어떤 환경에서 발생했는지 추적할 수 있습니다.
마무리
이런 도구에 문제가 생길 때 원인은 도구 자체의 bug가 아니라 사전 조건이 맞지 않은 경우가 많습니다. 런타임과 의존성, 디렉터리 권한, 키 보관 위치, 프록시 egress, 설정 공유라는 다섯 가지를 작은 프로젝트에서 먼저 정리해 두면 이후 반복적인 문제 해결 시간을 크게 줄일 수 있습니다.
