Company Bites — AI 테크 & 논문 리뷰
🧵 Threads

Claude Code .claude 폴더 구조 완전 정리: 팀이 AI와 제대로 협업하는 법

Claude Code를 제대로 쓰는 팀은 프롬프트를 잘 쓰는 팀이 아니다. 프로젝트 안에서 AI가 참고할 규칙과 설정을 구조화해둔 팀이다. 그 출발점이 바로 .claude 폴더다.

Claude Code .claude 폴더 구조 완전 정리: 팀 협업 가이드 - Company Bites 심층분석

왜 .claude 폴더가 중요한가
전체 구조 한눈에 보기
1. CLAUDE.md — 팀 전체가 공유하는 기본 지침
2. CLAUDE.local.md — 개인 오버라이드
3. .claude/settings.json — 권한과 실행 동작 제어
4. .claude/settings.local.json — 개인 권한 / 로컬 환경
5. .claude/commands/ — 반복 작업을 슬래시 커맨드로
6. .claude/rules/ — 규칙을 파일별로 모듈화
7. .claude/skills/ — 자동 호출 가능한 워크플로우 단위
8. .claude/agents/ — 역할별 서브에이전트 페르소나
skills/ vs agents/ — 헷갈리지 않게 정리
커밋할 파일 vs 개인용 파일
추천 운영 방식: 4단계로 시작하기
이런 팀에 특히 잘 맞는다
결론: Claude를 잘 쓰는 팀의 진짜 비결
자주 묻는 질문 (FAQ)
참고 자료

Claude Code의 .claude 폴더를 파일별로 완전 해부. CLAUDE.md vs .local 분리, commands·rules·skills·agents 역할 차이, 커밋/gitignore 원칙, 4단계 도입 가이드까지 정리.

핵심 요약

.claude 폴더는 단순한 설정 모음이 아니라 AI 협업을 위한 프로젝트 운영 체계다.
CLAUDE.md는 팀이 공유하는 공통 지침, CLAUDE.local.md는 개인 오버라이드.
settings.json으로 Claude의 권한과 실행 범위를 통제한다.
commands/로 반복 작업을 슬래시 커맨드로 표준화, rules/로 규칙을 모듈화한다.
skills/는 작업 흐름 묶음, agents/는 역할 페르소나. 흐름이냐 관점이냐가 다르다.
팀 공용 파일은 커밋하고, .local이 붙은 파일은 .gitignore로 로컬에만 둔다.

왜 .claude 폴더가 중요한가

프로젝트에서 AI를 쓰다 보면 이런 문제가 반드시 생긴다.

팀원마다 Claude에게 지시하는 방식이 다르다
코드 스타일, 테스트 방식, API 규칙이 일관되지 않다
반복 작업을 매번 새로 설명해야 한다
개인 설정과 팀 설정이 섞여 충돌한다

.claude 폴더를 잘 구성해두면 Claude가 프로젝트의 규칙과 작업 흐름을 더 정확하게 이해하고 일관되게 따라간다. "AI를 써보는 단계"에서 "AI를 팀 프로세스 안에 정착시키는 단계"로 넘어갈 때 꼭 필요한 구조다.

전체 구조 한눈에 보기

Claude Code .claude 폴더 구조 완전 정리: 팀 협업 가이드 - claude folder anatomy

1. CLAUDE.md — 팀 전체가 공유하는 기본 지침

프로젝트 루트에 위치하며 Claude가 이 프로젝트에서 기본적으로 따라야 할 공용 지침을 담는다. 프로젝트 목적, 기술 스택, 코드 작성 원칙, 응답 스타일, 문서화 규칙, 테스트 우선 원칙 등을 넣는다.

이 파일은 Git에 커밋해서 팀 전체가 공유한다.

# Project Instructions

- 모든 코드는 TypeScript로 작성한다.
- 함수형 스타일을 우선한다.
- API 변경 시 Swagger 문서도 함께 업데이트한다.
- 테스트가 없는 기능 추가는 허용하지 않는다.

이 파일이 잘 정리돼 있으면 팀원마다 프롬프트를 길게 설명하지 않아도 된다.

2. CLAUDE.local.md — 개인 오버라이드

이름 그대로 개인 전용 설정이다. 팀 공용 규칙은 유지하면서 본인 작업 스타일을 추가한다.

답변은 한국어로 받기
코드 제안 시 예외 처리까지 포함
변경 이유를 함께 설명해달라

이 파일은 보통 .gitignore에 넣어 Git에 올리지 않는다. CLAUDE.md가 팀 규칙이라면 CLAUDE.local.md는 내 작업 습관을 반영하는 개인 설정이다.

3. .claude/settings.json — 권한과 실행 동작 제어

Claude의 동작 방식과 권한 범위를 제어한다. 어떤 명령을 허용할지, 어떤 디렉터리 접근을 허용할지, 실행 정책과 환경 설정이 여기에 들어간다.

실무에서 꽤 중요한 파일이다. AI가 할 수 있는 행동 범위를 통제하기 때문이다.

특정 폴더만 수정 가능하도록 제한
위험한 명령 실행 차단
승인 필요한 작업 지정

즉, settings.json은 Claude를 프로젝트 안에서 안전하고 예측 가능하게 움직이게 만드는 장치다.

4. .claude/settings.local.json — 개인 권한 / 로컬 환경

settings.json의 개인 버전이다. 내 로컬 머신 기준 경로, 개인적으로 허용할 명령, 로컬 테스트 환경 설정 등을 담는다. Git에 올리지 않는다.

팀 공용 설정과 개인 환경을 분리하면 충돌이 줄고 유지보수가 쉬워진다.

5. .claude/commands/ — 반복 작업을 슬래시 커맨드로

자주 쓰는 작업을 커스텀 슬래시 명령어로 만드는 폴더다. review.md, fix-issue.md, deploy.md를 두면 다음처럼 쓸 수 있다.

/project:review
/project:fix-issue
/project:deploy

장점

반복 작업을 빠르게 실행 가능
팀원마다 같은 방식으로 요청 가능
리뷰·배포·이슈 수정 등 워크플로우 표준화
프롬프트 품질 편차 감소

예를 들어 review.md에는 이렇게 넣을 수 있다.

현재 변경된 파일을 기준으로 코드 리뷰를 수행해줘.
다음 항목을 중점적으로 확인해:
- 버그 가능성
- 성능 이슈
- 보안 취약점
- 테스트 누락

팀원 누구나 같은 품질의 리뷰 요청을 쉽게 재사용할 수 있다.

6. .claude/rules/ — 규칙을 파일별로 모듈화

프로젝트가 커지면 CLAUDE.md 하나에 규칙을 다 넣는 게 비효율적이다. rules/ 폴더로 분리한다.

파일	담는 내용
`code-style.md`	네이밍 규칙, 함수 길이 제한, 주석 정책, 린트 기준
`testing.md`	테스트 프레임워크, 단위 테스트 작성 기준, 커버리지, 목(mock) 원칙
`api-conventions.md`	REST 네이밍, 상태 코드 기준, 에러 응답 포맷, 버전 관리

규칙이 카테고리별로 정리되고, 필요한 항목만 쉽게 수정할 수 있다. 프로젝트가 커져도 관리가 편하다.

7. .claude/skills/ — 자동 호출 가능한 워크플로우 단위

보다 고도화된 작업 흐름을 구성할 때 쓴다. 이미지에서도 security-review/, deploy/, SKILL.md 같은 구조가 보인다.

이 영역은 단순 지침 파일을 넘어서 특정 목적의 작업 능력 묶음처럼 쓴다.

보안 점검 자동화
배포 체크리스트 실행
성능 분석 흐름 구성
문서 생성 루틴 정의

Claude에게 "무엇을 해야 하는지"만 알려주는 것이 아니라 어떤 순서와 기준으로 작업할지까지 구조화하는 개념이다. 반복되는 복합 작업일수록 skills/ 구성이 강력하다.

8. .claude/agents/ — 역할별 서브에이전트 페르소나

Claude에게 특정 역할을 부여한다. 하나의 AI를 만능으로 쓰기보다 역할별 전문가처럼 분리해서 활용하는 전략이다.

에이전트	중점 영역
`code-reviewer.md`	코드 품질, 가독성, 리팩토링 포인트, 테스트 누락
`security-auditor.md`	인증/인가 취약점, 입력값 검증, 비밀정보 노출, 의존성 보안

역할을 분리하면 같은 코드라도 관점이 달라지고 결과 품질도 더 좋아진다.

skills/ vs agents/ — 헷갈리지 않게 정리

둘 다 .claude/ 하위에 있지만 역할이 다르다.

구분	skills/	agents/
정의하는 것	작업 흐름 (어떤 순서로 처리할지)	관점 (어떤 시각으로 볼지)
예시	배포 체크리스트, 보안 점검 루틴	코드 리뷰어, 보안 감사자
호출 방식	자동/조건부 호출	격리된 서브에이전트로 실행

커밋할 파일 vs 개인용 파일

이미지에서 특히 중요한 포인트는 무엇을 Git에 커밋하고 무엇을 로컬에만 둘지가 분리되어 있다는 점이다.

커밋 권장 (팀 공유)

CLAUDE.md
.claude/settings.json
.claude/commands/
.claude/rules/
.claude/skills/
.claude/agents/

gitignore 처리 (개인 로컬)

CLAUDE.local.md
.claude/settings.local.json

이 원칙을 지키면 팀 공용 정책은 유지하면서 개인 생산성 설정은 자유롭게 가져갈 수 있다.

이런 팀에 특히 잘 맞는다

AI를 개발 워크플로우에 적극 도입한 팀
리뷰 기준이 자주 흔들리는 팀
온보딩 문서가 부족한 팀
코드 스타일 합의는 있는데 실제 반영이 안 되는 팀
반복 작업을 자동화하고 싶은 팀

"AI를 그냥 써보는 단계"에서 "AI를 팀 프로세스 안에 정착시키는 단계"로 넘어갈 때 꼭 필요한 구조다.

결론: Claude를 잘 쓰는 팀의 진짜 비결

Claude를 잘 쓰는 팀은 단순히 질문을 잘 던지는 팀이 아니다. Claude가 참고할 프로젝트 구조와 규칙을 잘 설계하는 팀이다.

.claude 폴더는 그 출발점이다.

CLAUDE.md로 공통 원칙을 정하고
rules/로 세부 규칙을 나누고
commands/로 반복 작업을 표준화하고
skills/와 agents/로 고급 워크플로우를 확장하면

Claude는 훨씬 더 일관되고 실무적인 협업 도구가 된다.

AI를 잘 쓰는 방법은 더 많이 요청하는 것이 아니라, 더 잘 구조화된 환경을 만들어주는 것이다.

자주 묻는 질문 (FAQ)

Q. .claude 폴더는 Git에 커밋해야 하나요?

팀이 공유할 CLAUDE.md, .claude/settings.json, commands/, rules/, skills/, agents/는 커밋합니다. 반면 CLAUDE.local.md와 .claude/settings.local.json은 개인 환경 설정이므로 .gitignore에 넣어 로컬에만 두는 것이 권장됩니다.

Q. CLAUDE.md와 rules/ 폴더는 어떻게 다르게 써야 하나요?

CLAUDE.md는 프로젝트 전체에 공통으로 적용되는 상위 원칙을 담습니다. rules/는 코드 스타일, 테스트 규칙, API 컨벤션처럼 카테고리별 세부 규칙을 나눠 관리할 때 유용합니다. 규칙이 길어지면 분리하세요.

Q. 커스텀 슬래시 명령어는 어떻게 호출하나요?

.claude/commands/review.md 같은 파일을 만들면 Claude Code에서 /project:review 형태로 실행할 수 있습니다. 파일 이름이 곧 명령어 이름이 되며, 반복 작업일수록 효과가 큽니다.

Q. skills/와 agents/는 어떻게 다른가요?

skills/는 "어떤 순서로 일을 처리할지" 정의하는 작업 흐름 묶음입니다(예: 보안 점검 자동화, 배포 체크리스트). agents/는 "어떤 관점으로 볼지" 정의하는 역할 페르소나입니다(예: 코드 리뷰어, 보안 감사자). 흐름이냐 관점이냐의 차이로 구분하면 쉽습니다.

Q. 팀원마다 Claude 응답 스타일이 달라서 혼란스러워요. 어떻게 맞추나요?

CLAUDE.md에 응답 톤, 주석 정책, 커밋 메시지 형식 등을 명시하고 커밋하면 팀 전체가 같은 기준으로 Claude와 협업하게 됩니다. 그래도 개인이 원하는 스타일은 CLAUDE.local.md에서 따로 오버라이드할 수 있습니다.

참고 자료

Anthropic Docs, "Claude Code — Configuration"
Anthropic Docs, "Slash Commands and Custom Workflows"
Anthropic Docs, "Agent Skills"
Anthropic Engineering Blog, "Working with Claude Code in Teams"

이 글이 도움이 됐다면 북마크 해두세요. Claude Code 업데이트마다 .claude 폴더 운영 노하우를 계속 정리합니다.

Company.bites

Claude Code .claude 폴더 구조 완전 정리: 팀 협업 가이드