팀 공용 Claude Code 설정 배포와 업데이트

팀 공용 Claude Code 설정은 파일을 저장소에 커밋하는 것으로 끝나지 않습니다. 실제로 무너지는 곳은 그다음입니다. 한 사람의 로컬에만 들어가 있거나, 팀원마다 다르게 고쳐 서로 다른 설정이 되거나, 새 버전이 나왔는데 무엇을 받아들이고 무엇을 지킬지 아무도 판단하지 못합니다. 이 글은 공용 설정을 배포하고 업데이트를 따라가는 절차를 다룹니다. 파일을 어디에 두면 어떤 순서로 읽히는지는 CLAUDE.md 계층 구조에, 권한 규칙 문법은 퍼미션 설정 최적화에 있으므로 여기서는 반복하지 않습니다.

핵심 요약

• 커밋 기준은 하나입니다. 팀 전체가 같은 동작을 얻어야 하는가.
• 상시 읽히는 규칙 파일이 길어지면 사람도 모델도 읽지 않습니다. 검사로 옮길 수 있는 것은 옮깁니다.
• "확인이 필요한 경계"를 팀 문장으로 먼저 쓰고 나서 권한 규칙으로 옮깁니다. 순서를 바꾸면 설정이 근거 없이 늘어납니다.
• 기존 리포지터리에 얹을 때는 공용 묶음 원본만 담는 추적용 브랜치를 먼저 만듭니다.
• 새 버전은 도입 시점을 공통 조상으로 둔 3-way 머지로 받습니다. 그래야 우리가 고친 것이 남습니다.

무엇을 커밋하고 무엇을 개인 설정으로 두나

판단 기준은 "팀 전체가 같은 동작을 얻어야 하는가"입니다. 이 질문에 예라면 공용, 아니라면 개인입니다.

경계에서 자주 흔들리는 것이 허용 규칙입니다. 확인 창을 줄이려고 개인이 하나씩 추가하다 보면 팀원마다 자동 실행되는 명령이 달라집니다. 안전하고 자주 쓰는 명령(테스트·린트·타입 검사·읽기 전용 조회)은 공용으로 올려 전원이 같은 편의를 얻게 하고, 개인 로컬에는 정말 개인적인 것만 남기는 쪽이 낫습니다.

반대로 금지 규칙은 절대 개인 설정에 두지 않습니다. 개인 파일은 커밋되지 않으므로 새로 합류한 사람에게 적용되지 않고, 사고는 대개 그 사람에게서 납니다.

팀 규칙 파일은 왜 짧아야 지켜지나

상시 읽히는 규칙 파일은 세 가지 이유로 짧아야 합니다. 첫째, 길어지면 뒤쪽 문장이 덜 지켜집니다. 둘째, 사람이 더 이상 읽지 않으므로 낡은 문장이 남아도 아무도 모릅니다. 셋째, 매 세션 컨텍스트를 차지합니다.

줄이는 방법은 문장을 지우는 것이 아니라 옮기는 것입니다. 세 단계로 분류합니다.

조건부 규칙을 경로 조건으로 나눠 싣는 방법은 .claude/rules로 규칙 나누기에 있습니다. 상시 항목 중에서도 기계로 검사할 수 있는 것은 문장이 아니라 검사로 옮깁니다. "커밋 전에 테스트를 돌린다"는 문장보다 종료 전에 테스트 결과를 확인하는 검사가 확실합니다.

확인이 필요한 경계를 어떻게 팀 언어로 적나

"확인해도 될까요"가 너무 잦다는 불만과 "확인도 없이 저질렀다"는 불만은 같은 팀에서 동시에 나옵니다. 해결은 권한을 푸는 것이 아니라 멈춰야 할 곳을 먼저 문장으로 쓰고 나머지를 허용하는 것입니다.

설정 파일을 열기 전에 경계 문서를 씁니다. 여섯 종류로 나누면 대부분 덮입니다.

문장을 쓸 때 "조심한다" 같은 표현은 금지합니다. 명령·파일·행동 단위로 적어야 설정으로 옮길 수 있습니다. 이 문서가 있어야 나중에 규칙을 늘릴 때도 근거가 생기고, 업데이트에서 충돌이 났을 때 판단 기준이 됩니다. 팀 전체가 이 경계를 같은 기준으로 쓰게 만드는 과정은 에이전트 팀 운영 교육에서 다룹니다.

공용 설정이 정말 도는지 어떻게 확인하나

설정 묶음에서 가장 위험한 상태는 오류를 내는 것이 아니라 조용히 아무것도 하지 않는 것입니다. 실행 권한 누락, 줄바꿈 형식 차이, 필요한 명령어 미설치, 경로 오타로 검사가 통째로 건너뛰어지고, 아무도 모르는 채 몇 주가 지납니다.

그래서 검사 스크립트에는 자체 테스트를 붙입니다. 표준 입력으로 받는 정보 형식을 알고 있으니, 가짜 입력을 만들어 넣고 종료 코드가 기대와 같은지 비교하면 됩니다.

#!/usr/bin/env bash
# 공용 검사 스크립트의 자체 테스트 — 막아야 할 것과 통과시켜야 할 것을 각각 확인
run() { echo "$2" | "$1"; echo $?; }

block=$(run .claude/hooks/guard.sh '{"tool_input":{"command":"git push --force origin main"}}')
pass=$(run .claude/hooks/guard.sh '{"tool_input":{"command":"npm run test"}}')

[ "$block" -eq 2 ] || { echo "실패: 강제 푸시가 막히지 않습니다" >&2; exit 1; }
[ "$pass" -eq 0 ] || { echo "실패: 테스트 명령이 막힙니다" >&2; exit 1; }
echo "자체 테스트 통과"

테스트 사례는 경계 문서에서 그대로 뽑습니다. 여기서 흔히 발견되는 빈틈이 따옴표로 감싼 명령이 패턴 검사를 빠져나가는 경우입니다. Windows 사용자가 섞인 팀이라면 스크립트 줄바꿈을 저장소 설정으로 고정해 두는 것을 도입 목록에 넣습니다. 검사 종료 코드의 의미는 훅 exit code에 정리돼 있습니다.

얹기 전에 무엇을 정해 두어야 하나

공용 묶음을 받아 그대로 넣으면 대개 두 주 뒤에 흐지부지됩니다. 묶음이 해 주지 않는 일이 무엇인지 아무도 정하지 않았기 때문입니다. 넣기 전에 세 칸을 채워 둡니다.

## 도입 체크리스트

- 들어 있는 것: 공통 작업 규칙, 위험 명령 차단, 검증 단계, 커맨드·서브에이전트 정의
- 들어 있지 않은 것: 우리 서비스의 도메인 규칙, 배포 절차, 우리 팀의 검증 명령, 사내 보안 정책
- 우리가 정할 것: 확인이 필요한 경계, 교훈 파일 담당자, 버전 확인 주기, 개인 설정에 둘 것

"들어 있는 것" 칸을 채울 때는 설정 파일을 직접 열어 대조합니다. 묶음의 설명 문서와 실제 설정이 어긋나 있는 경우가 흔하고, 그 어긋남을 먼저 찾아 두면 나중에 "왜 안 막히지"를 몇 시간 뒤지지 않아도 됩니다. "우리가 정할 것" 칸에 담당자 이름이 없으면 그 항목은 도입 후에도 비어 있게 됩니다.

기존 리포지터리에 나중에 얹을 때의 순서

새 프로젝트라면 공용 묶음을 그대로 복사하면 됩니다. 문제는 이미 누군가 규칙 파일과 설정 파일을 써 둔 저장소입니다. 그냥 덮어쓰면 기존 내용이 사라지고, 손으로 합치면 다음 업데이트 때 무엇이 원본이었는지 알 수 없습니다.

순서를 지키면 둘 다 피할 수 있습니다.

# 1. 공용 묶음 원본만 담는 추적용 브랜치 (이 브랜치에는 우리 수정을 넣지 않는다)
git checkout --orphan base-track
git rm -rf . && cp -r /path/to/shared-bundle/. .
git add -A && git commit -m "chore: 공용 설정 묶음 v1.0 도입 시점"

# 2. 도입 전용 브랜치에서 추적용 브랜치를 머지 (기본 브랜치에서 바로 하지 않는다)
git checkout -b adopt-shared main
git merge base-track --allow-unrelated-histories

충돌은 반드시 납니다. 겹치는 파일을 셋으로 분류합니다. 공용 것을 그대로 쓸 파일, 우리 것을 지킬 파일, 합칠 파일. 합칠 때는 한 파일 안에서 공용 구역과 우리 구역을 나눠 표시해 둡니다. 예를 들어 규칙 파일에 "공용 규칙" 구역과 "이 프로젝트 전용" 구역을 두는 식입니다. 이 구분이 다음 업데이트의 충돌 범위를 결정합니다.

마지막으로 도입 시점의 커밋을 문서에 적어 둡니다. 이 값이 없으면 다음 절의 머지를 할 수 없습니다.

새 버전을 따라갈 때 우리가 고친 것을 잃지 않는 법

공용 묶음이 새 버전을 내면 변경 요약만 믿지 말고 실제 차이를 확인하는 것이 첫 단계입니다. 그다음은 추적용 브랜치에 새 버전을 커밋하고 그 브랜치를 우리 브랜치로 머지하는 것뿐입니다.

git checkout base-track
cp -r /path/to/shared-bundle/. . && git add -A
git commit -m "chore: 공용 설정 묶음 v1.1"

git checkout adopt-shared
git merge base-track

이 구조가 중요한 이유는 공통 조상이 생기기 때문입니다. 도입 시점 커밋을 기준으로 3-way 머지가 되므로, 우리가 손대지 않은 부분은 자동으로 새 버전이 되고 양쪽이 고친 곳만 충돌로 남습니다. 추적용 브랜치에 우리 수정을 한 줄이라도 섞으면 이 성질이 깨집니다. 파일 하나만 따로 다뤄야 할 때는 git merge-file로 같은 원리를 적용할 수 있습니다.

충돌을 판정하는 기준은 경계 문서입니다. 새 버전이 경계를 느슨하게 만드는 변경이면 우리 것을 지키고, 빈틈을 막는 변경이면 받아들입니다. 반영이 끝나면 자체 테스트를 다시 돌립니다. 통과하지 않으면 머지를 완료하지 않습니다.

겪은 문제는 "증상 → 원인 → 확인 위치" 표로 남깁니다. "검사가 안 막는다 → 실행 권한이나 줄바꿈 → 자체 테스트", "확인이 갑자기 늘었다 → 새 버전의 ask 추가 → 설정 파일 차이" 같은 식입니다. 이 표가 두 번째 업데이트를 훨씬 빠르게 만듭니다.

우리가 찾은 빈틈 수정처럼 다른 팀에도 쓸모 있는 개선은 공용 묶음으로 되돌려 보내고, 우리 서비스 전용인 것은 우리 구역에 둡니다. 이 구분 기준을 한 줄로 정해 두면 매번 고민하지 않아도 됩니다.

교훈 파일이 계속 자라는 문제

운영을 하면 교훈이 쌓입니다. 문제는 교훈 파일이 늘기만 한다는 점입니다. 중복이 생기고, 이미 검사로 옮겨진 항목이 문장으로 남아 있고, 낡아서 틀린 내용도 섞입니다.

규칙은 두 개면 충분합니다. 하나는 분류입니다. 매 세션 읽어야 하는 것은 규칙 파일에, 특정 작업 때만 필요한 것은 조건부 규칙이나 스킬에, 기록으로만 남길 것은 보관 문서에 둡니다. 다른 하나는 승격입니다.

승격은 삭제를 포함합니다. 교훈이 검사 스크립트나 린트 규칙으로 옮겨져 기계가 강제하게 되면 원래 문장을 지우고, 커밋 메시지에 승격 사실을 남깁니다. 같은 내용이 문장과 검사 두 곳에 있으면 한쪽만 고쳐져 서로 어긋나고, 그 뒤로는 어느 쪽이 맞는지 아무도 모릅니다.

정리 주기와 담당자를 정해 두는 것도 필요합니다. 주 단위로 "지난주에 사람이 개입한 지점"과 "새 교훈 후보"를 모으고, 규칙 파일에 반영하는 일은 사람이 검토해 반영합니다. 자동으로 규칙이 늘어나게 두면 첫 번째 문제로 되돌아갑니다.

정리

• 커밋 기준은 "팀 전체가 같은 동작을 얻어야 하는가"입니다. 금지 규칙은 반드시 공용에 둡니다.
• 상시 읽히는 규칙은 짧게 유지하고, 검사로 옮길 수 있는 항목은 옮깁니다.
• 경계 문서를 먼저 쓰고 나서 권한 규칙으로 옮깁니다. 이 문서가 업데이트의 판단 기준이 됩니다.
• 공용 묶음 원본만 담는 추적용 브랜치를 만들어 도입 시점을 기록합니다.
• 새 버전은 3-way 머지로 받고, 반영 뒤 자체 테스트를 다시 돌립니다.

이어서 볼 글은 settings.json 설정 가이드, 퍼미션 설정 최적화, CLAUDE.md 계층 구조입니다. 공용 설정을 실제 저장소에 얹고 업데이트까지 한 바퀴 돌려 보는 실습은 에이전트 팀 운영 교육을 참고하세요.