Claude Code 팀 프로젝트 설정 가이드: CLAUDE.md 컨벤션, Git Hook, 권한 모드 완벽 정리
Claude Code 팀 프로젝트 설정 가이드
Claude Code는 터미널 기반 AI 코딩 어시스턴트로, 팀 단위 프로젝트에서 일관된 개발 워크플로우를 구축할 수 있습니다. 이 가이드에서는 공유 CLAUDE.md 컨벤션, Git Hook 통합, 권한 모드 설정, 커스텀 슬래시 명령어 구성까지 실무 중심으로 안내합니다.
1단계: Claude Code 설치 및 초기 설정
먼저 Claude Code를 설치하고 인증을 완료합니다.
# npm을 통한 전역 설치
npm install -g @anthropic-ai/claude-code
프로젝트 디렉토리에서 Claude Code 실행
cd your-project
claude
첫 실행 시 브라우저 인증 진행
Anthropic 계정으로 로그인 후 자동 연결
API 키를 직접 설정하려면 환경 변수를 사용합니다.
# .bashrc 또는 .zshrc에 추가
export ANTHROPIC_API_KEY=YOUR_API_KEY
또는 프로젝트별 .env 파일
echo “ANTHROPIC_API_KEY=YOUR_API_KEY” > .env
2단계: 팀 공유 CLAUDE.md 컨벤션 구성
CLAUDE.md는 Claude Code가 프로젝트 컨텍스트를 이해하는 핵심 설정 파일입니다. 팀 전체가 공유하는 규칙을 정의합니다.
프로젝트 루트 CLAUDE.md (Git에 커밋)
# 프로젝트 루트에 CLAUDE.md 생성
cat > CLAUDE.md << ‘EOF’
프로젝트 컨벤션
코드 스타일
- TypeScript strict 모드 사용
- 함수명은 camelCase, 컴포넌트명은 PascalCase
- 테스트 파일은 *.test.ts 형식
아키텍처 규칙
- src/components: React 컴포넌트
- src/hooks: 커스텀 훅
- src/utils: 유틸리티 함수
- API 호출은 반드시 src/api 디렉토리에서만 수행
금지 사항
- any 타입 사용 금지
- console.log를 프로덕션 코드에 남기지 않을 것
- 직접 DOM 조작 금지 (ref 사용)
테스트
- 모든 유틸리티 함수에 단위 테스트 필수
- 테스트 실행: npm test
린트 검사: npm run lint EOF
개인 설정 파일 (~/.claude/CLAUDE.md)
# 개인 전용 설정 (Git에 커밋하지 않음)
mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md << 'EOF'
# 개인 설정
- 응답은 한국어로 작성
- 코드 설명 시 주석 포함
- 커밋 메시지는 Conventional Commits 형식
EOFCLAUDE.md는 계층 구조로 동작합니다. 프로젝트 루트, 하위 디렉토리, 사용자 홈 디렉토리 순으로 병합되며, 하위 설정이 상위를 오버라이드합니다.
3단계: Git Hook 통합 설정
Claude Code의 Hook 시스템을 활용해 도구 실행 전후에 자동 검증을 수행할 수 있습니다. 프로젝트 루트에 .claude/settings.json을 생성합니다.
mkdir -p .claude
cat > .claude/settings.json << ‘SETTINGS’
{
“hooks”: {
“PreToolUse”: [
{
“matcher”: “Bash”,
“hooks”: [
{
“type”: “command”,
“command”: “echo “$CLAUDE_TOOL_INPUT” | grep -q ‘rm -rf’ && echo ‘BLOCK: rm -rf 명령은 금지됩니다’ || true”
}
]
}
],
“PostToolUse”: [
{
“matcher”: “Write”,
“hooks”: [
{
“type”: “command”,
“command”: “npx eslint —no-error-on-unmatched-pattern “$CLAUDE_FILE_PATH” 2>/dev/null || echo ‘경고: 린트 오류가 발견되었습니다’”
}
]
}
]
}
}
SETTINGS
또한 Git의 pre-commit 훅과 연동하여 커밋 품질을 보장할 수 있습니다.
# .git/hooks/pre-commit 또는 husky 설정
npx husky add .husky/pre-commit “npm run lint && npm test”
4단계: 권한 모드 구성
Claude Code는 세 가지 권한 모드를 제공하여 팀 보안 정책에 맞게 운영할 수 있습니다.
| 모드 | 설명 | 적합한 상황 |
|---|---|---|
| **Ask Mode** | 모든 도구 실행 전 사용자 승인 필요 | 신규 팀원, 프로덕션 환경 |
| **Auto-edit Mode** | 파일 읽기/수정은 자동, 셸 명령은 승인 | 일반 개발 작업 |
| **Full Auto Mode** | 모든 작업 자동 실행 | CI/CD 파이프라인, 신뢰 환경 |
# 권한 모드별 실행
claude --allowedTools "Edit,Read,Glob,Grep" # 제한적 자동 허용
claude --allowedTools "Edit,Read,Bash(npm test)" # 특정 명령만 허용
설정 파일로 팀 공통 권한 정의
cat > .claude/settings.json << ‘EOF’
{
“permissions”: {
“allow”: [
“Edit”,
“Read”,
“Glob”,
“Grep”,
“Bash(npm test)”,
“Bash(npm run lint)”,
“Bash(npx tsc —noEmit)”
],
“deny”: [
“Bash(rm -rf *)”,
“Bash(git push —force)”
]
}
}
EOF
5단계: 커스텀 슬래시 명령어 만들기
반복적인 팀 워크플로우를 슬래시 명령어로 등록하면 생산성이 크게 향상됩니다.
# 프로젝트 전용 명령어 디렉토리
mkdir -p .claude/commands
코드 리뷰 명령어
cat > .claude/commands/review.md << ‘EOF’
현재 Git diff를 분석하여 코드 리뷰를 수행하세요:
- 변경된 파일 목록 확인
- 각 파일의 변경사항 분석
- 버그 가능성, 성능 이슈, 보안 취약점 체크
- 개선 제안사항 목록 작성
EOF
컴포넌트 생성 명령어
cat > .claude/commands/component.md << ‘EOF’
$ARGUMENTS 이름으로 React 컴포넌트를 생성하세요:
- src/components/$ARGUMENTS/$ARGUMENTS.tsx (컴포넌트)
- src/components/$ARGUMENTS/$ARGUMENTS.test.tsx (테스트)
- src/components/$ARGUMENTS/index.ts (배럴 export)
- 프로젝트의 기존 컴포넌트 패턴을 따를 것
EOF
PR 요약 명령어
cat > .claude/commands/pr-summary.md << ‘EOF’
main 브랜치 대비 현재 브랜치의 변경사항을 분석하고
PR 설명을 작성하세요. 포함할 내용:
- 변경 요약 (한국어)
- 주요 변경 파일 목록
테스트 체크리스트 EOF사용 시 Claude Code 세션에서 다음과 같이 실행합니다.
# 세션 내에서 슬래시 명령어 실행 /review /component UserProfile /pr-summary
Pro Tips: 파워 유저를 위한 고급 팁
- 멀티 세션 활용:
claude —resume으로 이전 세션을 이어가거나claude —continue로 마지막 대화를 계속할 수 있습니다.- 파이프 연동:git diff | claude -p “이 변경사항을 리뷰해줘”처럼 파이프를 통해 컨텍스트를 전달하면 효율적입니다.- CI 통합:claude -p —output-format json “테스트 실패 원인 분석”으로 CI 파이프라인에서 자동 분석을 수행할 수 있습니다.- CLAUDE.md 분리 전략: 모노레포에서는 각 패키지 디렉토리에 별도 CLAUDE.md를 두어 패키지별 컨텍스트를 관리하세요.- 메모리 시스템: Claude Code는 대화 간 지속되는 메모리를 지원합니다./memory명령으로 프로젝트 컨텍스트를 저장하면 다음 세션에서도 유지됩니다.
Troubleshooting: 자주 발생하는 오류
| 증상 | 원인 | 해결 방법 |
|---|---|---|
| CLAUDE.md가 인식되지 않음 | 파일 인코딩 또는 위치 오류 | UTF-8 인코딩 확인, 프로젝트 루트에 위치시킬 것 |
| Hook이 실행되지 않음 | settings.json 문법 오류 | cat .claude/settings.json | python -m json.tool로 JSON 검증 |
| 권한 거부 반복 발생 | deny 규칙이 너무 광범위 | deny 패턴을 더 구체적으로 수정 (예: Bash(rm*) → Bash(rm -rf /)) |
| 슬래시 명령어 미표시 | .claude/commands 경로 오류 | 디렉토리 경로와 .md 확장자를 정확히 확인 |
| API 인증 실패 | 키 만료 또는 환경 변수 미설정 | echo $ANTHROPIC_API_KEY로 확인 후 재설정 |
Q1: CLAUDE.md를 Git에 커밋해야 하나요?
프로젝트 루트의 CLAUDE.md는 팀 컨벤션을 공유하기 위해 반드시 Git에 커밋해야 합니다. 반면 개인 설정(~/.claude/CLAUDE.md)은 커밋하지 않으며, 개인별 환경 변수나 선호도를 담습니다. .claude/settings.json도 팀 공통 권한 정책이라면 커밋을 권장합니다.
Q2: 팀원마다 다른 권한 모드를 사용할 수 있나요?
네, 가능합니다. 프로젝트 설정(.claude/settings.json)에서 기본 허용/차단 규칙을 정의하고, 각 팀원은 개인 설정(~/.claude/settings.json)에서 추가 제한을 걸 수 있습니다. 단, 개인 설정으로 프로젝트의 deny 규칙을 무시할 수는 없으므로 보안 정책이 유지됩니다.
Q3: 커스텀 슬래시 명령어에서 외부 인자를 전달할 수 있나요?
네, $ARGUMENTS 변수를 사용하면 됩니다. 예를 들어 /component UserProfile을 실행하면 명령어 템플릿 내의 $ARGUMENTS가 “UserProfile”로 치환됩니다. 복수의 인자를 전달하면 공백으로 구분된 하나의 문자열로 들어오므로, 명령어 템플릿 내에서 적절히 파싱하도록 프롬프트를 작성하세요.