현장에서 Claude Code를 도입한 팀을 보면 첫 실패는 모델 성능에서 오지 않는다. 누군가는 ~/.claude/settings.json에 모든 권한을 열어두고, 누군가는 프로젝트마다 허용을 다시 누른다. 보안팀은 MCP 서버가 어디서 붙었는지 모르고, 리더는 “왜 팀마다 결과가 다르냐”고 묻는다. 이 문제는 프롬프트 문제가 아니다. 설정 관리 문제다.
Claude Code 공식 문서는 settings.json을 계층형 설정 메커니즘으로 설명한다. User, Project, Local, Managed scope가 있고, 우선순위도 정해져 있다. 팀 단위 운영은 이 구조를 그대로 받아들이는 데서 시작한다. https://code.claude.com/docs/en/configuration
팀 설정은 프로젝트에, 통제는 Managed에 둔다
팀이 공유해야 할 설정은 .claude/settings.json에 둔다. 이 파일은 소스 컨트롤에 들어가야 한다. 권한, hooks, 팀 공통 MCP 정책, 파일 접근 제한처럼 협업 결과에 영향을 주는 항목은 개인 홈 디렉터리에 있으면 안 된다.
반대로 반드시 강제해야 하는 보안 정책은 Managed settings로 올린다. 공식 문서 기준으로 Managed settings는 다른 scope에서 override할 수 없다. 서버 관리 설정, MDM, OS-level policy, file-based managed-settings.json이 여기에 속한다. https://code.claude.com/docs/en/server-managed-settings
| 설정 위치 | 소유자 | 넣어야 할 것 | 넣으면 안 되는 것 |
|---|---|---|---|
~/.claude/settings.json |
개인 | 에디터 취향, 개인 도구 | 팀 권한 정책 |
.claude/settings.json |
팀 | 공통 allow/deny, hooks, repo 규칙 | 개인 토큰 |
.claude/settings.local.json |
개인 | 실험, 장비별 예외 | 공유되어야 할 규칙 |
| Managed settings | IT/보안/플랫폼 | 금지 명령, MCP 통제, 우회 차단 | 팀별 편의 설정 |
settings.json을 “개인 생산성 파일”로 보면 팀이 흔들린다. “실행 정책 파일”로 보면 운영이 잡힌다.
allow보다 deny를 먼저 설계한다
Claude Code 권한은 allow, ask, deny로 나뉜다. 공식 권한 문서는 deny가 우선한다고 설명한다. 그래서 팀 설정의 첫 작업은 “무엇을 허용할지”가 아니라 “무엇을 절대 읽거나 실행하지 못하게 할지”다. https://code.claude.com/docs/en/permissions
기본 패턴은 단순하다.
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"permissions": {
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)",
"Bash(curl *)"
],
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)",
"Bash(git diff *)"
],
"ask": [
"Bash(git push *)"
]
}
}
핵심은 allow list를 넓히는 속도를 늦추는 것이다. 팀은 반복적으로 등장하는 안전한 명령만 allow로 승격한다. 애매한 명령은 ask에 둔다. 금지 대상은 project scope가 아니라 Managed scope로 올려야 한다. 그래야 개인이나 프로젝트 예외로 빠져나가지 못한다.
hooks는 자동화가 아니라 검문소다
Claude Code hooks는 명령 실행 전후, 세션 시작, 권한 요청 시점에 개입한다. 최근 공식 hooks 문서는 HTTP hook, prompt hook, agent hook, async hook까지 다룬다. 그러나 팀 운영에서 중요한 것은 기능의 폭이 아니다. 어디에 검문소를 세울지다. https://code.claude.com/docs/en/hooks
우리가 보는 좋은 패턴은 세 가지다.
PreToolUse: 위험한 Bash, 파일 삭제, 외부 전송을 사전 차단한다.PostToolUse: 파일 수정 뒤 lint, test, secret scan을 붙인다.SessionStart: repo 규칙, 배포 금지 구간, 브랜치 정책을 컨텍스트로 주입한다.
hooks를 남발하면 개발자는 우회한다. 그래서 sync hook은 차단이 필요한 곳에만 둔다. 긴 테스트와 감사 로그는 async hook으로 돌린다. 공식 문서도 async hook은 Claude 실행을 막지 않고 백그라운드에서 돌릴 수 있다고 설명한다. 운영의 목적은 모든 행동을 느리게 만드는 것이 아니라 위험한 행동만 멈추는 것이다.
MCP는 팀별 편의가 아니라 접속면이다
MCP 서버는 Claude Code의 손을 늘린다. GitHub, 사내 문서, 티켓, DB 주변 도구가 붙으면 생산성은 오른다. 동시에 접속면도 넓어진다. 공식 MCP 문서는 조직이 managed-mcp.json으로 고정 서버를 배포하거나 allowlist/denylist로 사용자 추가를 제한할 수 있다고 설명한다. https://code.claude.com/docs/en/mcp
팀 단위 패턴은 분명하다. 읽기 전용 문서 MCP는 project scope에서 시작해도 된다. 인증과 외부 시스템 접근이 있는 MCP는 Managed 정책으로 올린다. 사용자가 임의 MCP를 추가해야 하는 조직이라면 allowedMcpServers, deniedMcpServers, allowManagedMcpServersOnly 같은 관리형 키를 검토한다.
여기서 AX Ops 관점의 운영 원칙은 하나다. 설정 파일은 배포로 끝나지 않는다. /status로 활성 source를 확인하고, PR에서 .claude/settings.json 변경을 리뷰하고, 보안 정책은 managed layer에서 따로 배포한다. Claude Code는 에이전트다. 에이전트에는 프롬프트보다 하네스가 먼저다.
참고
- Anthropic Claude Code configuration docs, 2026 접근: https://code.claude.com/docs/en/configuration
- Anthropic Claude Code permissions docs, 2026 접근: https://code.claude.com/docs/en/permissions
- Anthropic Claude Code server-managed settings docs, 2026 접근: https://code.claude.com/docs/en/server-managed-settings
- Anthropic Claude Code hooks docs, 2026 접근: https://code.claude.com/docs/en/hooks
- Anthropic Claude Code MCP docs, 2026 접근: https://code.claude.com/docs/en/mcp
- Measuring the Permission Gate: A Stress-Test Evaluation of Claude Code's Auto Mode, arXiv 2026: https://arxiv.org/abs/2604.04978
팀의 Claude Code 설정은 한 번 정리하는 문서가 아니다. 권한, hooks, MCP, 예외를 계속 조정하는 운영 체계다. AX LABS는 이 체계를 AX Ops의 일부로 설계한다. AX Ops 방법론 →