AX LABS
← 블로그 에이전트 제품 설계

팀 설정이 에이전트를 지킨다

settings.json은 개인 취향 파일이 아니라 운영 규약이다

AX LABS 6분 읽기

개발자 한 명이 Claude Code를 잘 쓰는 것과 팀이 안정적으로 쓰는 것은 다른 문제다. 한 사람은 ~/.claude/settings.json에 편한 권한을 열어 둔다. 다른 사람은 프로젝트 루트의 .claude/settings.json을 수정한다. 또 다른 사람은 local 설정에서 실험한 hook을 그대로 남긴다. 며칠 뒤 같은 프롬프트가 다른 결과와 다른 권한 요청을 만든다. 이때 문제는 모델이 아니다. 설정 운영이 없는 것이다.

settings.json은 실행 환경의 계약이다

Claude Code의 설정은 계층으로 동작한다. 공식 문서 기준으로 Managed, command line, Local, Project, User 순서의 우선순위가 적용된다. Project 설정인 .claude/settings.json은 저장소에 커밋되어 팀 전체에 공유되고, .claude/settings.local.json은 개인 실험과 장비별 설정에 둔다. Managed 설정은 조직 정책으로 배포되며 다른 계층이 덮어쓸 수 없다.

팀 단위 관리의 핵심은 단순하다. 개인 취향과 팀 규약을 섞지 않는 것이다.

범위 둘 내용 두면 안 되는 것
Managed 보안상 절대 규칙, bypass 차단, 승인된 marketplace 프로젝트별 편의 설정
Project 팀 공통 permissions, hooks, plugins, repo 규칙 개인 토큰, 개인 경로
Local 실험 hook, 개인 editor, 장비별 override 팀 표준으로 착각될 설정
User 개인 전역 선호, 개인 도구 특정 repo의 운영 규칙

팀 설정은 “Claude를 더 똑똑하게 만드는 파일”이 아니다. 같은 코드베이스에서 같은 위험 경계가 작동하게 만드는 운영 장치다.

권한은 allow보다 deny와 ask가 먼저다

Claude Code permissions는 allow, ask, deny로 구성된다. 팀 설정에서는 “무엇을 허용할까”보다 “무엇은 절대 읽거나 실행하지 못하게 할까”를 먼저 정한다. .env, secret 디렉터리, credential 파일, build 산출물은 Project 설정의 permissions.deny에 넣어야 한다. 공식 문서도 민감 파일 차단을 permissions.deny로 처리하라고 명시한다.

Bash 권한은 특히 넓게 열면 안 된다. Bash(npm run *)처럼 반복 업무는 허용하되, 배포·삭제·외부 전송 계열은 ask 또는 deny로 둔다. 조직 차원에서는 disableBypassPermissionsMode를 Managed 설정에 두는 편이 맞다. 팀이 아무리 좋은 Project 설정을 만들어도 누군가 bypass 모드로 들어가면 운영 경계가 무너진다.

sandbox도 같은 원리다. 파일 도구 권한만으로는 subprocess의 파일·네트워크 접근을 충분히 설명하지 못한다. sandbox filesystem과 network 제한은 CLI 안에서 실행되는 kubectl, terraform, npm 같은 명령까지 운영 경계 안에 넣는 장치다.

hook은 권고가 아니라 검문소다

CLAUDE.md는 지시다. hook은 실행이다. 팀 단위 Claude Code 운영에서 이 차이를 놓치면 “규칙을 써 두었는데 왜 안 지켰나”라는 회의가 반복된다.

PreToolUse hook은 Bash, Read, Edit, Write, WebFetch, MCP tool 호출 전에 실행된다. PostToolUse는 실행 뒤 검증에 맞다. SessionStart는 세션 시작 시 repo 상태, 이슈 컨텍스트, 팀 규약을 주입하는 데 쓴다. Stop 또는 SubagentStop은 최종 응답이 팀의 완료 조건을 만족하는지 확인하는 검문소가 된다.

고급 패턴은 세 가지다.

  1. hook 스크립트는 $CLAUDE_PROJECT_DIR 기준으로 참조한다. 작업 디렉터리 차이로 hook이 깨지면 팀 설정이 아니다.
  2. formatting, lint, secret scan처럼 결정 가능한 검사는 hook으로 보낸다. 모델에게 “반드시 확인”하라고 쓰지 않는다.
  3. HTTP hook은 allowedHttpHookUrls와 httpHookAllowedEnvVars로 목적지와 환경변수 노출을 제한한다.

Anthropic은 2026년 Claude Code advanced patterns 세션에서 subagents, hooks, MCP, 대규모 코드베이스 context 전략을 함께 다룬다. 이것은 방향을 잘 보여준다. 에이전트 설계의 중심은 prompt가 아니라 harness다.

팀 배포는 plugin과 MCP까지 묶어야 한다

2025년 10월 Anthropic은 Claude Code plugin을 public beta로 공개했다. plugin은 slash commands, subagents, MCP servers, hooks를 한 번에 배포하는 단위다. 팀이 같은 hook과 subagent를 써야 한다면 복사한 설정 조각보다 plugin이 낫다.

단, MCP는 별도 경계로 본다. Project-scoped MCP 서버는 .mcp.json에 둔다. settings.json에는 MCP 자체를 억지로 밀어 넣기보다 plugin 활성화, marketplace 제한, hook allowlist, permissions를 둔다. 이 분리가 중요하다. 연결 도구의 구성과 실행 정책의 구성이 뒤섞이면 감사와 변경 관리가 어려워진다.

운영 절차는 가볍게 시작한다.

  • .claude/settings.json을 코드 리뷰 대상으로 둔다.
  • .claude/settings.local.json은 커밋 금지 원칙을 확인한다.
  • /status로 실제 적용 계층을 점검한다.
  • Managed 설정 후보와 Project 설정 후보를 분리한다.

설정 관리는 AX Ops의 일부다

Claude Code settings.json 고급 패턴의 결론은 기술 팁이 아니다. 팀이 AI agent를 운영 시스템 안에 넣는 방식이다. 권한, hook, plugin, MCP, sandbox가 각자 흩어지면 현장은 다시 개인 숙련도에 의존한다. 설정이 계층화되면 팀은 같은 위험 경계 안에서 더 빠르게 실험한다.

AX LABS는 이런 설정 파일을 “개발자 편의”가 아니라 AgentOps 통제면으로 본다. PoC에서 끝난 팀은 프롬프트를 공유한다. 운영으로 간 팀은 설정과 검문소를 공유한다.

참고

팀 단위 에이전트 운영 설계는 설정 표준에서 시작한다. AX Ops 방법론 →