Claude Code를 혼자 쓸 때는 설정 파일 위치가 크게 중요하지 않습니다. 내가 쓰는 단축키, 허용 도구, 로컬 hook만 맞으면 됩니다. 하지만 팀에서 Claude Code를 도입하는 순간 설정 scope가 운영 이슈가 됩니다. 어떤 설정은 팀 전체에 강제해야 하고, 어떤 설정은 개인 환경에만 있어야 합니다. 이 경계를 잘못 잡으면 보안 사고나 “내 환경에서는 되는데” 문제가 생깁니다.
Claude Code 문서는 설정 scope를 Managed, User, Project, Local로 나눕니다. 우선순위도 다릅니다. Managed가 가장 강하고, 그다음 command line, Local, Project, User 순서로 적용됩니다. 이 구조를 이해하면 팀 정책과 개인 자동화를 서로 방해하지 않게 설계할 수 있습니다.
설정 scope를 고를 때 “어디에 넣으면 편한가”가 아니라 “누가 책임지는가”로 판단해야 합니다. 회사 보안팀이 책임지는 정책은 Managed scope가 맞습니다. 프로젝트 팀이 함께 유지해야 하는 규칙은 Project scope가 맞습니다. 개인 생산성 설정은 User나 Local이 맞습니다. 책임자가 다르면 설정 위치도 달라져야 합니다.
예를 들어 production 배포 명령 차단, 특정 외부 도구 금지, 민감 파일 접근 제한은 개인이 끄면 안 되는 정책입니다. 이런 항목은 Managed로 강제하는 것이 안전합니다. 반대로 에디터 테마, 개인 알림, 로컬 경로, 실험용 MCP 서버는 팀원에게 공유하면 오히려 문제를 만듭니다. User 또는 Local에 둬야 합니다.
Project scope는 팀 협업의 중심입니다. 저장소별 테스트 명령, 코드 스타일 hook, PR 요약 규칙, 프로젝트 문서 위치, 허용된 내부 도구 같은 설정은 repository에 같이 두는 편이 좋습니다. 신규 팀원이 들어와도 같은 규칙으로 Claude Code를 사용할 수 있어야 하기 때문입니다.
프로젝트 설정에는 재현 가능해야 하는 규칙을 넣습니다. 예를 들어 프론트엔드 저장소라면 npm test, npm run lint, npm run typecheck 같은 검증 명령 매핑이 들어갈 수 있습니다. 백엔드 저장소라면 migration 검증, API contract test, 보안 스캔 명령이 들어갈 수 있습니다. 에이전트가 코드를 바꾼 뒤 어떤 검증을 해야 하는지 팀 기준으로 알려주는 역할입니다.
또한 프로젝트 문서 위치를 명확히 해야 합니다. README, architecture 문서, API spec, design system 문서, 릴리스 절차가 어디 있는지 Claude Code가 알 수 있어야 합니다. 매번 프롬프트에 “이 파일도 읽어”라고 쓰는 것은 운영이 아닙니다. 프로젝트 설정과 문서 구조로 기본 컨텍스트를 제공해야 합니다.
허용 도구 정책도 Project에 둘 수 있습니다. 예를 들어 이 저장소에서는 package manager로 pnpm만 쓰고, npm install은 금지한다는 규칙이 있다면 에이전트가 실수로 lockfile을 바꾸지 않게 해야 합니다. 이런 규칙은 개인 취향이 아니라 프로젝트 일관성 문제입니다.
Local 설정은 특정 프로젝트에서 나만 쓰는 설정입니다. 로컬 DB 포트, 개인 테스트 데이터 경로, 임시 hook, 실험용 MCP 서버처럼 repository에 커밋되면 안 되는 항목이 여기에 해당합니다. 팀 공유가 필요 없는 설정을 Project에 넣으면 다른 사람 환경에서 깨지거나 민감 정보가 노출될 수 있습니다.
User 설정은 여러 프로젝트에서 개인에게 공통으로 적용되는 설정입니다. 예를 들어 개인 알림 방식, 선호하는 출력 스타일, 자주 쓰는 로컬 도구 연결이 해당됩니다. 다만 User 설정에 강한 허용 규칙을 넣는 것은 조심해야 합니다. 프로젝트에서 막아야 하는 작업을 개인 설정이 우회하게 되면 팀 정책이 무력화될 수 있습니다.
좋은 기준은 “이 설정이 다른 팀원 컴퓨터에서도 그대로 동작해야 하는가”입니다. 그렇다면 Project입니다. “나에게만 의미 있는가”라면 Local 또는 User입니다. “누구도 마음대로 바꾸면 안 되는가”라면 Managed입니다.
작은 팀에서는 Managed scope 없이도 시작할 수 있습니다. 하지만 고객 데이터, 금융, 의료, 엔터프라이즈 환경에서는 강제 정책이 필요합니다. Claude Code 문서는 macOS, Windows, Linux 환경에서 managed settings를 배포하는 방식을 설명합니다. 이는 IT나 DevOps가 조직 전체 정책을 관리하기 위한 구조입니다.
Managed에 넣을 후보는 명확합니다. secret 출력 금지, production credential 접근 금지, 승인 없는 배포 명령 차단, 외부 네트워크 호출 제한, 로그 보존 규칙, 특정 MCP 서버 allowlist가 있습니다. 이런 정책은 개발자의 선의에 맡기면 안 됩니다. AI 에이전트는 실수로도 위험한 작업을 시도할 수 있으므로 실행 전 경계가 필요합니다.
단, Managed를 너무 많이 쓰면 개발 생산성이 떨어집니다. 모든 것을 중앙에서 막으면 팀별 특수성을 반영하기 어렵습니다. 조직 공통 보안 경계만 Managed로 두고, 프로젝트별 작업 방식은 Project에 위임하는 구조가 현실적입니다.
설정 충돌을 줄이려면 문서화가 필요합니다. 저장소에 “Claude Code 사용 규칙” 문서를 두고 어떤 설정이 어디에 있는지 설명하세요. 특히 Project 설정을 바꿀 때는 PR 리뷰를 거치게 해야 합니다. 에이전트 권한과 hook은 코드만큼 중요합니다. 작은 설정 변경이 전체 팀의 AI 작업 방식을 바꿀 수 있습니다.
두 번째는 기본값을 보수적으로 두는 것입니다. 처음부터 많은 도구를 허용하지 말고, 실제로 필요한 도구를 allowlist에 추가하세요. 에이전트가 실패하면 그때 이유를 보고 허용 범위를 넓히는 편이 안전합니다. 반대로 모든 것을 열어두고 사고가 난 뒤 막는 방식은 AI 자동화에서는 위험합니다.
세 번째는 설정 변경 로그를 남기는 것입니다. 언제 누가 어떤 hook이나 권한을 바꿨는지 확인할 수 있어야 합니다. 팀에서 Claude Code가 중요한 개발 도구가 될수록 설정 파일은 운영 자산입니다. 단순 개인 도구 설정처럼 다루면 안 됩니다.
Claude Code settings 설계는 사소한 환경 설정이 아닙니다. AI 에이전트가 팀 코드베이스에서 어디까지 움직일 수 있는지 정하는 권한 모델입니다. 개인 자동화의 속도와 팀 정책의 안전성을 함께 가져가려면 scope를 처음부터 분리해서 설계해야 합니다.
