Claude Code Project Structure
이 이미지는 Claude Code 프로젝트를 어떻게 폴더와 설정 파일 중심으로 구성하면 좋은지를 한눈에 보여주는 구조도입니다. 즉, “AI 코딩 에이전트가 프로젝트를 더 잘 이해하고, 더 안전하고, 더 일관되게 일하게 하려면 어떤 파일들을 어디에 두는가”를 설명하는 그림이라고 보시면 됩니다.
전체적으로 보면, 이 구조는 단순한 소스코드 폴더 구조라기보다 다음 6가지를 체계화하려는 설계입니다.
프로젝트의 기본 설명
개발 규칙과 팀 규약
반복 작업용 명령어
특정 업무용 스킬
역할 분리된 서브 에이전트
안전장치와 자동 검증 훅
아래에서 하나씩 자세히 풀어보겠습니다.
1. 최상단의 핵심 파일들
이미지 왼쪽 상단을 보면 루트 폴더 아래에 다음 파일들이 있습니다.
CLAUDE.md
Claude.local.md
.mcp.json
이 세 개는 사실상 프로젝트에 대한 AI의 기본 이해 레이어입니다.
CLAUDE.md
오른쪽 설명을 보면 다음과 같은 역할로 적혀 있습니다.
세션 시작 시 로드됨
프로젝트 개요, 기술 스택, 명령어 정의
코딩 규칙과 아키텍처 포함
CLAUSE.local.md 오버라이드 지원
즉, 이 파일은 프로젝트용 AI 운영 매뉴얼에 가깝습니다.
여기에는 보통 이런 내용이 들어갈 수 있습니다.
이 프로젝트가 무엇인지
어떤 언어와 프레임워크를 쓰는지
실행 방법
테스트 방법
절대 건드리면 안 되는 디렉토리
코딩 스타일
API 설계 원칙
아키텍처 개요
쉽게 말하면, 사람 개발자에게 README.md 가 기본 안내문이라면, CLAUDE.md 는
AI 코딩 도구를 위한 프로젝트 헌법 같은 것입니다.
Claude.local.md
이 파일은 로컬 오버라이드 성격으로 보입니다.
즉, 팀 공용 규칙은 CLAUDE.md 에 두고, 개인 개발자가 자기 환경이나 실험적 설정을 조금 다르게 둘 때 Claude.local.md 로 보완하는 방식입니다.
예를 들면:
내 로컬에서만 쓰는 테스트 서버 주소
내 작업 스타일에 맞춘 임시 규칙
아직 팀 공용으로 확정하지 않은 개인 설정
이렇게 두면 공용 정책과 개인 설정을 분리할 수 있습니다.
.mcp.json
오른쪽 설명에는 이렇게 적혀 있습니다.
MCP 통합 설정 저장
GitHub, JIRA, Slack, DB 연결
git을 통해 팀과 공유 가능
여기서 MCP는 보통 외부 도구나 시스템과 AI를 연결하는 인터페이스/프로토콜 설정으로 이해하시면 됩니다.
즉, 이 파일은 Claude Code가 단순히 코드만 보는 것이 아니라 다음 같은 외부 자원에도 접근하도록 해주는 연결 지점입니다.
GitHub 저장소
Jira 이슈
Slack 대화
데이터베이스
기타 내부 도구
결국 .mcp.json 은 AI의 외부 세계 연결 설정 파일입니다.
2. .claude/ 폴더: 실제 운영 설정의 중심
그 아래에 .claude/ 폴더가 보입니다. 이 폴더가 사실상 이 구조의 핵심입니다.
안에는 다음이 있습니다.
settings.json
settings.local.json
rules/
commands/
skills/
agents/
hooks/
즉, 루트에 있는 파일들이 “기본 프로젝트 안내”라면, .claude/ 아래는 실제 실행 규칙과 동작 방식의 운영 본부에 가깝습니다.
3. settings.json / settings.local.json
오른쪽 설명을 보면:
권한과 도구 접근 제어
모델 선택과 훅 정의
settings.local.json 오버라이드 지원
settings.json
이 파일은 AI 도구의 운영 정책 파일입니다.
예를 들어 이런 걸 설정할 수 있습니다.
어떤 도구 사용 허용
셸 명령 실행 허용 범위
특정 디렉토리 수정 가능 여부
기본 모델 설정
작업 전후 훅 실행 여부
즉, CLAUDE.md 가 “무엇을 알아야 하는가”라면, settings.json 은 “무엇을 할 수 있는가”를 정하는 파일입니다.
settings.local.json
이건 로컬 개인 설정용입니다.
예를 들면 팀 전체는 보수적으로 설정해두고, 개인 개발자는 자기 환경에서만 조금 다른 권한이나 도구를 테스트할 수 있습니다.
이 구조의 장점은 명확합니다.
팀 공용 설정과 개인 설정을 분리
실험적 변경이 공용 설정을 오염시키지 않음
충돌을 줄임
4. rules/ 폴더: AI가 따라야 할 규칙 모음
이미지에서는 이 폴더 아래에 예시 파일이 세 개 보입니다.
code-style.md
testing.md
api-conventions.md
오른쪽 설명은 다음과 같습니다.
주제별로 모듈화된 md 파일
스타일, 테스트, API 설계 포함
특정 파일/경로를 타겟팅할 수 있음
이 부분이 매우 중요합니다. 왜냐하면 AI 코딩 도구는 규칙이 없으면 그때그때 다른 스타일로 코드를 만들기 쉽기 때문입니다.
왜 rules/ 가 필요한가
예를 들어 팀마다 다 다릅니다.
변수명 규칙
폴더 분리 방식
테스트 작성 방식
API 응답 포맷
에러 처리 패턴
DTO/Schema 사용 방식
이걸 전부 CLAUDE.md 하나에 몰아넣으면 너무 길고 관리가 어렵습니다. 그래서 규칙을 주제별로 나누는 것
입니다.
예시 파일 의미
code-style.md
코드 스타일 규칙입니다.
예:
함수는 짧게 유지
타입 명시 필수
매직 넘버 금지
파일당 책임 최소화
React 컴포넌트 구조 규칙
testing.md
테스트 작성 원칙입니다.
예:
신규 기능엔 단위 테스트 필수
버그 수정 시 회귀 테스트 추가
외부 API는 mock 처리
테스트 네이밍 규칙 통일
api-conventions.md
API 설계 원칙입니다.
예:
REST 경로 명명 방식
에러 응답 JSON 형식
pagination 규약
인증 토큰 처리 방식
status code 기준
즉, rules/ 는 AI를 팀 표준에 맞게 길들이는 문서 폴더입니다.
5. commands/ 폴더: 반복 작업을 명령어로 묶는 구조
예시 파일:
review.md
fix-issue.md
오른쪽 설명:
커스텀 슬래시 명령어(/project:) 지원
반복 워크플로우에 사용
셸 실행 지원
이건 쉽게 말해 자주 하는 작업을 템플릿 명령으로 만들어두는 구조입니다.
예를 들면 개발팀에서 이런 요청이 자주 있습니다.
코드 리뷰해줘
이슈 수정해줘
PR 설명문 작성해줘
배포 전 체크해줘
테스트 돌리고 실패 원인 정리해줘
이걸 매번 길게 설명하지 않고, 명령어처럼 호출할 수 있게 만드는 개념입니다.
review.md
코드 리뷰 워크플로우용 명령일 가능성이 큽니다.
예:
변경 파일 확인
코드 스타일 위반 찾기
테스트 누락 점검
보안 리스크 점검
개선 제안 정리
fix-issue.md
이슈 해결용 흐름입니다.
예:
관련 코드 찾기
재현 방법 정리
수정안 작성
테스트 추가
변경 요약 생성
즉, commands/ 는 AI에게 작업 지시를 재사용 가능한 절차로 묶어놓은 것 입니다.
6. skills/ 폴더: 상황별 전문 능력 모듈
예시 구조를 보면:
deploy/
skill.md
deploy-config.md
오른쪽 설명:
작업 맥락에 따라 자동 트리거
필요할 때만 로드
컨텍스트를 가볍게 유지
이 부분은 rules/ 와 비슷해 보이지만 역할이 다릅니다.
rules/는 항상 지켜야 할 기준
skills/는 특정 업무를 할 때 불러오는 전문 지식
예를 들어 배포 작업을 한다면, AI가 배포 관련 내용을 불러오면 됩니다.
왜 스킬 분리가 중요한가
AI에게 모든 정보를 항상 다 넣어두면:
컨텍스트가 무거워지고
중요한 정보가 묻히고
작업 집중도가 떨어집니다
그래서 “지금 배포 작업이냐?”, “지금 DB 마이그레이션이냐?”에 따라 해당 지식만 꺼내 쓰는 구조가 더 효율적입니다.
deploy/skill.md
배포할 때 필요한 절차나 원칙
예:
배포 전 체크리스트
마이그레이션 순서
롤백 조건
환경변수 검증 방법
deploy-config.md
배포 설정의 세부 정보
예:
배포 대상 환경
브랜치 전략
CI/CD 파이프라인 규칙
staging → production 승격 기준
즉, skills/ 는 특정 업무를 잘하게 만드는 전문 플레이북입니다.
7. agents/ 폴더: 역할별 서브 에이전트
예시 파일:
codeReviewer.md
security-auditor.md
오른쪽 설명:
역할이 분리된 전문 서브 에이전트
격리된 컨텍스트 윈도우
사용자 정의 도구와 모델 선호 설정
이 구조는 매우 흥미롭습니다. 단일 AI에게 모든 역할을 맡기는 대신, 역할별 전문가를 따로 둔다는 개념입니다.
왜 필요한가
개발 업무는 사실 역할이 다릅니다.
구현 담당
코드 리뷰 담당
보안 점검 담당
성능 최적화 담당
테스트 설계 담당
한 AI가 다 할 수도 있지만, 역할이 섞이면 관점이 흐려질 수 있습니다. 그래서 서브 에이전트 개념을 두는 것입니다.
예시 의미
codeReviewer.md
이 에이전트는 “코드를 만드는 역할”이 아니라 “코드를 검토하는 역할”에 특화됩니다.
관심사 예:
가독성
유지보수성
중복
테스트 적절성
아키텍처 일관성
security-auditor.md
이 에이전트는 보안 관점에 집중합니다.
관심사 예:
민감정보 노출
권한 검증 누락
입력값 검증 부족
SQL injection / XSS 위험
의존성 취약성
즉, agents/ 는 역할 기반 AI 분업 체계입니다.
8. hooks/ 폴더: 자동 검증과 안전장치
예시 파일:
validate-bash.sh
오른쪽 설명:
이벤트 기반 스크립트(도구 사용 전/후)
검증, 린트, 포맷팅 자동화
위험한 작업 차단
이건 매우 실무적입니다. AI가 편리하긴 하지만, 잘못된 셸 명령을 실행하거나 위험한 변경을 할 수도 있습니다. 그래서 훅을 둬서 특정 행동 전후에 자동 검사를 거는 것입니다.
예를 들면
파일 삭제 명령 전에 확인
배포 전에 테스트 자동 실행
커밋 전에 린트 검사
위험 명령어 차단
운영 DB 접근 차단
포맷팅 강제 적용
validate-bash.sh
이 파일은 이름상 셸 명령의 안전성 검사를 담당하는 스크립트로 보입니다.
예:
rm -rf / 류의 위험 명령 차단
production 환경 명령 차단
허용된 경로 밖 수정 차단
특정 명령은 승인 필요 처리
즉, hooks/ 는 AI에게 브레이크를 다는 장치입니다.
9. 이 구조를 한 문장으로 요약하면
이 그림은 결국 이렇게 말하고 있습니다.
Claude Code를 단순한 코드 생성기로 쓰지 말고,
프로젝트 규칙, 팀 표준, 반복 명령, 전문 스킬, 역할 분리, 안전장치를 갖춘
운영 가능한 개발 에이전트 시스템으로 구성하자.
10. 각 요소의 관계를 쉽게 다시 정리하면
아주 쉽게 비유하면 이렇습니다.
CLAUDE.md → “이 프로젝트는 이런 곳이다”라는 기본 안내서
.mcp.json → “어떤 외부 도구들과 연결되는가”라는 연결 설정
settings.json → “무엇을 할 수 있고 무엇을 못 하는가”라는 권한 정책
rules/ → “어떻게 일해야 하는가”라는 팀 규칙집
commands/ → “자주 하는 작업을 어떻게 실행하는가”라는 작업 템플릿
skills/ → “특정 업무를 잘하기 위한 전문 플레이북”
agents/ → “역할별 전문가를 따로 둔 구조”
hooks/ → “실수와 사고를 막는 자동 안전장치”
11. 이 구조가 특히 유용한 팀
이런 구조는 특히 아래 같은 팀에서 유용합니다.
1) 여러 명이 함께 AI 코딩을 쓰는 팀
사람마다 AI에게 다르게 지시하면 코드 스타일이 흔들립니다. 이 구조는 공통 규칙을 강제하기 좋습니다.
2) 반복 작업이 많은 팀
리뷰, 수정, 테스트, 배포 점검 등을 명령화할 수 있습니다.
3) 보안/품질 리스크가 큰 팀
훅과 규칙으로 위험한 행동을 줄일 수 있습니다.
4) 프로젝트가 커서 맥락 분리가 필요한 팀
스킬과 에이전트 분리 구조가 큰 도움이 됩니다.
12. 이 그림의 핵심 철학
이 이미지의 핵심 철학은 사실 아주 명확합니다.
AI는 그냥 똑똑한 자동완성이 아니라, 프로젝트의 규칙과 맥락 안에서 움직이도록 설계되어야 한다는 것입니다.
즉,
문서화하고
규칙화하고
모듈화하고
역할 분리하고
안전장치를 두는 것
이것이 AI 코딩을 “장난감”이 아니라 “팀 생산성 시스템”으로 만드는 방식이라는 뜻입니다.
13. 실무적으로 볼 때 가장 중요한 포인트
제가 이 구조에서 특히 중요하다고 보는 부분은 다음입니다.
첫째, CLAUDE.md 와 rules/
많은 팀이 AI를 쓰다가 실패하는 이유는
AI가 프로젝트 문맥을 충분히 모르기 때문입니다.
이 두 영역이 그 문제를 가장 직접적으로 해결합니다.
둘째, commands/
AI 활용이 일회성 대화가 아니라 반복 가능한 워크플로우가 되게 만듭니다.
셋째, hooks/
실무에서는 “똑똑함”보다 “사고를 안 치는 것”이 더 중요할 때가 많습니다.
그래서 훅은 상당히 현실적인 장치입니다.
넷째, skills/와 agents/
프로젝트가 커질수록 모든 지식을 한 번에 다 들고 가는 방식은 비효율적입니다. 이 구조는 AI의 맥락을 가볍고 전문적으로 유지하는 데 유리합니다.
14. 더 실용적으로 해석하면
이 이미지는 결국 AI 개발 거버넌스 구조라고도 볼 수 있습니다.
즉, 단순히 “Claude Code를 어떻게 쓰느냐”가 아니라,
팀 표준을 어떻게 내재화할 것인가
AI가 어떤 권한 안에서 움직이게 할 것인가
개발 반복 작업을 얼마나 시스템화할 것인가
역할과 책임을 어떻게 분리할 것인가
품질과 보안을 어떻게 강제할 것인가
를 폴더 구조와 파일 구조로 표현한 것입니다.
이 점에서 이 그림은 단순한 디렉토리 예시가 아니라, AI-보조 개발 조직의 운영 모델을 압축해 보여주는 도식이라고 볼 수 있습니다.
출처 소개
출처는 Source Code.dev에서 공유된 게시물로, Claude Code를 단순한 코드 생성 도구가 아니라 팀 단위에서 안정적으로 운영하기 위한 구조와 원칙을 설명한 실무 중심의 가이드 콘텐츠입니다.
이 게시물은 CLAUDE.md, mcp.json, rules, commands, agents, hooks 등의 구성 요소를 통해 프로젝트 맥락을 명확히 정의하고, 반복 작업을 체계화하며, 보안과 품질을 자동으로 관리하는 방법을 제시합니다. 특히 개발자마다 결과 품질이 흔들리지 않도록 하고, 매 세션마다 동일한 컨텍스트를 유지하는 것이 중요하다는 점을 강조하고 있습니다.
전반적으로 AI 코딩 도구를 개인 생산성 수준이 아닌, 팀의 개발 프로세스와 결합된 운영 시스템으로 활용하기 위한 베스트 프랙티스를 요약한 콘텐츠라고 볼 수 있습니다.
--
Written by AI Alchemist & Maestro 두드림(Two Dreams)
- Orchestrating AI, systems, and human judgment
이 글은 Creative Commons BY-NC 라이선스에 따라 비영리적 용도로 자유롭게 복사·배포·활용할 수 있습니다. 출처(저자명·브런치 링크)만 표시해 주세요.