Claude Code로 Vercel 환경 변수 사고를 방지하는 검증 스크립트 활용법

AI가 환경 변수를 망치기 전에 차단하는 법

AI 에이전트에게 코드를 맡길 때 가장 불안한 지점은 런타임 설정입니다. Claude Code가 편리하긴 하지만, Next.js 프로젝트에서 NEXT_PUBLIC_ 접두사를 빼먹거나 필수 API 키를 누락하는 실수는 충분히 일어날 수 있습니다. 이런 확률론적인 실수를 사람의 눈으로 매번 확인하는 건 피곤한 일입니다.

프로젝트 루트에 .claude-check 스크립트를 작성하고 Claude Code의 post-tool-use 훅에 연결하십시오. 스크립트가 .env 파일의 변경 사항을 감지해 접두사 누락이나 빈 값을 체크하게 만들면 됩니다. 검증에 실패했을 때 에러 내용을 JSON 형태로 출력하도록 설정하면, Claude는 그 메시지를 보고 스스로 수정을 시도합니다. 기계적인 검증 루프를 하나 추가하는 것만으로도 배포 후 환경 변수 오류로 삽질하는 시간을 주당 2시간은 줄일 수 있습니다.

Vercel Preview URL을 Claude 세션에 동기화하기

로컬 환경과 실제 배포 환경의 괴리는 AI가 엉뚱한 답을 내놓게 만듭니다. Vercel은 브랜치마다 고유한 프리뷰 URL을 생성하는데, 이를 Claude 세션에 주입하면 AI가 실제 런타임 상황을 인지하기 시작합니다.

먼저 터미널에서 vercel ls --format json 명령어로 현재 브랜치의 배포 URL을 뽑아내는 쉘 스크립트를 만드십시오. 그 다음 Claude Code를 실행할 때 --append-system-prompt 플래그로 해당 URL을 전달하면 됩니다. 이제 Claude에게 "프리뷰 URL 로그를 보고 에러를 찾아줘"라고 시킬 수 있습니다. 로컬에서는 멀쩡한데 배포 서버에서만 터지는 하이드레이션 오류를 잡을 때 특히 유용합니다. 실제 개발 현장에서는 이런 실시간 데이터 주입만으로도 디버깅 속도가 30% 이상 빨라집니다.

토큰 낭비를 막는 효율적인 파일 감시 설정

무턱대고 프로젝트의 모든 파일을 AI에게 넘기는 건 돈 낭비입니다. 컨텍스트가 복잡해질수록 AI의 추론 성능은 떨어지고 비용은 올라갑니다. .claudignore 파일을 제대로 쓰는 게 실력입니다.

**/.next/**, **/node_modules/**, **/dist/** 같은 빌드 결과물은 반드시 제외하십시오. 보안이 중요한 .env.local도 목록에 넣어야 합니다. 프로젝트 규모가 크다면 하위 디렉토리마다 CLAUDE.md를 두는 계층적 구조를 추천합니다. 해당 폴더 내 작업에 필요한 최소한의 정보만 제공하는 방식입니다. 최적화된 무시 패턴 설정만으로 세션당 토큰 소모량을 40%까지 아낄 수 있다는 데이터도 있습니다.

팀 협업을 위한 권한 제한과 표준 가드레일

팀 단위로 Claude Code를 도입한다면 각자 제멋대로 쓰게 둬선 안 됩니다. 사고는 한순간입니다. 공통의 가드레일을 정의한 .claude/settings.json을 Git 저장소에 포함해 팀원 모두가 동일한 규칙을 따르게 만드십시오.

보안이 걱정된다면 권한을 쪼개야 합니다. 특히 GitHub Actions 같은 CI 환경에서 돌릴 때는 contents: read와 pull-requests: write 권한만 주는 것이 안전합니다. AI가 코드를 직접 커밋해버리는 게 아니라 리뷰 댓글로 제안만 하게 만드는 겁니다. 관리자 설정인 Managed Settings를 활용해 개별 개발자가 보안 검증 훅을 마음대로 끄지 못하게 강제하는 장치도 필요합니다. 프롬프트 주입 공격으로 인한 악성 코드 주입 리스크는 이런 다중 방어 체계로 막아야 합니다.

AI가 수정한 내용을 Git 커밋 메시지로 자동 변환하기

AI가 수정한 코드를 리뷰할 때 가장 짜증 나는 건 "왜 이렇게 고쳤는지" 모를 때입니다. Claude Code는 자기가 한 일을 제일 잘 압니다. 작업 맥락을 활용해 Conventional Commits 규격에 맞는 메시지를 뽑아내게 시키십시오.

git diff --cached 결과를 Claude에게 넘겨 변경 사항을 분석하게 하는 쉘 함수를 하나 만드십시오. CLAUDE.md에 팀의 커밋 컨벤션을 명시해두면 AI가 feat(env): add NEXT_PUBLIC_API_URL 같은 구체적인 메시지를 만들어냅니다. 사람이 대충 "fix"라고 적는 것보다 훨씬 정보량이 많습니다. 이렇게 자동화된 커밋 기록은 동료들이 코드를 이해하고 승인하는 시간을 획기적으로 줄여줍니다. 단순한 요약을 넘어 Vercel 인프라 변경점까지 정확히 기록하는 게 핵심입니다.