개인적으로 사용할 때는 최고였던 Claude Code를 5인 팀에 도입한 순간 분출된 문제──그 모든 것에 대해 현재까지 기능하고 있는 규칙을 공유합니다.

먼저 결론부터 말씀드립니다. Claude Code는 도구로서 우수하지만, 팀에서 사용하면 "누가 어디까지 사용해도 되는가", "비용이 무제한으로 늘어나지 않을까", "AI 생성 코드의 품질은 누가 담보하는가"라는 세 가지 문제가 즉시 발생합니다. 이 기사에서는 3개월간의 시행착오를 통해 정착된 11가지 규칙과, 반대로 실패하여 철폐한 3가지 규칙을 구체적으로 소개합니다.

먼저, 현재의 팀 개발 워크플로우 전체를 보여드립니다. 각 단계에 어떤 규칙이 관여하고 있는지를 주석으로 달아두었습니다.

Claude Code를 사용할 수 있는 리포지토리(Repository)를 명시적으로 허용 목록(allowlist)으로 관리하고 있습니다.

이유: 도입 첫 주에, 운영 DB의 마이그레이션 스크립트를 포함한 리포지토리에서 Claude Code가 의도하지 않은 스키마 변경을 제안하여, 하마터면 그대로 PR(Pull Request)이 올라올 뻔했습니다.

# 팀에서 관리하고 있는 allowlist (사내 Wiki 관리)
allowed_repos:
- org/web-frontend # 프론트엔드 → 전원 이용 가능
...

Claude Code가 실행할 수 있는 도구(셸 커맨드, 파일 편집 등)를 단계적으로 제한하고 있습니다.

// .claude/settings.json (리포지토리 루트에 배치)
{
"permissions": {
...

포인트: deny를 먼저 결정하는 것이 아니라, "무엇을 허용할 것인가"부터 설계했습니다. 파괴적인 조작에 대한 거부 목록(denylist)은 최소한의 안전망입니다.

새로 팀에 합류한 멤버는 처음 2주 동안 Claude Code를 Read와 WebSearch로만 이용합니다.

의도: Claude Code의 출력 경향을 이해한 뒤에 쓰기 권한을 부여함으로써, "AI가 작성한 코드의 의미를 모르는 채로 PR을 올리는" 사태를 방지하고 있습니다.

Max plan에서는 계정 단위의 이용 상황을 관리 화면에서 확인할 수 있습니다. 팀에서는 다음과 같은 기준을 설정하고 있습니다.

엄격한 "하드 리미트 (Hard Limit)"가 아니라, 주간 미팅에서 소비량을 공유하는 운용 방식입니다.

Claude Code의 이용 상황을 주간 단위로 가시화하고 있습니다.

현시점에서는 API 이용량 대시보드를 수동으로 집계하고 있지만, 향후에는 Claude Code CLI의 --output-format json 옵션을 활용한 자동 집계를 검토 중입니다.

다음 중 하나에 해당하는 태스크는 착수 전에 Slack의 #claude-code-ops 채널에서 사전 신고합니다.

대규모 리팩터링 (Refactoring) (10개 이상의 파일 변경이 예상되는 경우)
신규 모듈의 0→1 생성
테스트 코드 일괄 생성 (대상 파일 수가 많으면 토큰이 급증함)

사전 신고 템플릿은 다음과 같습니다.

📋 고비용 태스크 신고
- 태스크: [Jira 티켓 번호]
- 예상 변경 규모: [파일 수·행 수 개략]
...

PR에 ai-generated 라벨을 붙임으로써 리뷰어의 리뷰 관점을 전환합니다.

이는 GitHub Actions로 자동화하고 있습니다. PR 본문이나 커밋 메시지에 Claude나 ai-generated 키워드가 포함되어 있으면 자동으로 라벨을 부여합니다.

# .github/workflows/ai-label.yml
name: Auto AI Label
on:
...

통상적인 리뷰와 "AI 생성 코드 리뷰"는 중점을 두는 포인트가 다릅니다.

"AI 생성 코드니까 대충 봐도 된다"는 생각은 정반대입니다. AI는 도메인 지식 없이도 그럴듯한 코드를 작성하기 때문에, 도메인을 깊이 이해하고 있는 멤버가 리뷰하지 않으면 업무 로직의 미묘한 오류를 놓치게 됩니다.

구체적인 예: 어떤 API 엔드포인트에서 Claude Code가 '논리 삭제 (Logical Delete)'를 구현해야 할 곳을 '물리 삭제 (Physical Delete)'로 구현했던 사례가 있었습니다. 코드 자체는 완벽하게 동작했고 테스트도 통과했지만, 비즈니스 요구사항 관점에서는 오류였습니다.

CLAUDE.md는 Claude Code에 대한 프로젝트 고유의 지시 파일입니다. 개인마다 제각각이면 출력 품질이 흔들리기 때문에, 팀 공통 템플릿을 리포지토리 루트에 배치하고 있습니다.

<!-- CLAUDE.md (팀 공통 템플릿 · 발췌) -->
# 프로젝트 규약
## 코딩 규약
...

Claude Code의 hooks 기능을 사용하여, 코드 생성 전후로 자동 체크를 실행하고 있습니다.

// .claude/hooks.json
{
"PostEditHook": {
...

효과: hooks 도입 전에는 "Claude Code가 생성한 코드가 lint 에러투성이라 CI가 실패함 → 수동으로 수정"하는 재작업이 빈번하게 발생했습니다. hooks 도입 후에는 PR 단계에서의 lint 에러가 거의 제로에 가깝습니다.

성공한 규칙만 소개하는 것은 불공평하므로, 도입했지만 기능하지 않았던 규칙도 공유합니다.

의도: AI 생성 코드의 품질을 담보하기 위함.

철폐 이유: 리뷰 대기 병목 현상이 심각해졌습니다. 5인 팀에서 2인 승인을 필수화하면 팀의 40%가 리뷰에 구속됩니다. 규칙 8·9를 통해 "무엇을 볼 것인가"를 명확히 함으로써, 1인 리뷰만으로도 품질을 유지할 수 있다고 판단했습니다.

의도: 투명성 확보와 지식 공유.

철폐 이유: 노이즈가 너무 많아 아무도 읽지 않게 되었습니다. 한 번의 세션에서 수십 개의 메시지가 오가기 때문에 Slack 채널이 도배됩니다. 현재는 "PR 설명란에 요점을 3줄로 작성한다"는 운영 방식으로 안착했습니다.

의도: AI에 너무 의존하지 않는 개발 기술 유지.

철폐 이유: "시간"으로 구분하는 것은 의미가 없었습니다. 30분 만에 고품질 코드가 생성되는 경우도 있는 반면, 4시간을 들여도 만족스러운 결과를 얻지 못하는 경우도 있습니다. 비용 관리(규칙 4~6)를 통해 실질적인 이용량은 컨트롤되고 있으므로, 시간 제한은 불필요했습니다.

도입 전후 3개월간의 비교 데이터입니다.

주목해야 할 점은 리뷰 지적 수의 증가입니다. 이는 나쁜 수치가 아닙니다. AI 생성 코드에 대해 리뷰어가 더 주의 깊게 보게 된 결과, 기존에는 놓쳤던 경미한 문제(명명 규칙의 불일치, 불필요한 null 체크 등)도 잡아낼 수 있게 되었기 때문입니다. 중대한 문제의 지적 수는 감소하고 있으며, 이는 CLAUDE.md와 hooks를 통한 사전 품질 체크가 효과를 발휘하고 있다고 생각합니다.

• Claude Code의 팀 도입은 "도구의 설정"이 아니라 "운영 설계"가 핵심입니다. allowlist · 비용 관리 · 리뷰 기준이라는 세 가지 기둥을 먼저 결정한 후 도입해야 합니다.
• CLAUDE.md와 hooks를 "팀의 공통 인프라"로 정비함으로써, 개인차에 따른 품질 편차를 대폭 줄일 수 있습니다. 개인의 CLAUDE.md에 맡기면 멤버마다 출력 품질이 들쭉날쭉해집니다.
• 실패한 규칙에서 배운 가장 큰 교훈은 "과도한 통제는 팀의 속도를 죽인다"는 것입니다. AI 도구 도입으로 속도를 높이려는데, 거버넌스 때문에 속도가 떨어진다면 본말전도입니다.