Claude Code로 템플릿을 커스터마이징하는 팀은 이렇게 세팅합니다. claude 폴더 완전 정복

GOSPELFIX에서 템플릿을 구매하고 나면, 그다음은 "내 프로젝트에 맞게 고치는" 시간입니다. 요즘은 그 커스터마이징 작업의 상당 부분을 Claude Code 같은 AI 코딩 도구가 대신해줍니다. 다만 도구가 매번 "이 프로젝트에서 쌍따옴표를 쓰는지 홑따옴표를 쓰는지", "이 버튼 컴포넌트를 어떻게 확장해야 하는지"를 새로 물어봐야 한다면, AI를 쓰는 의미가 반감됩니다.

이 문제를 해결하는 방법이 .claude/ 폴더입니다. 저희 GOSPELFIX 개발팀도 실제로 이 구조로 지금 보고 계신 사이트를 만들고 있습니다. 오늘은 그 구조를 그대로 공개합니다.

왜 폴더 하나가 이렇게 중요한가

AI 코딩 도구에게 매번 같은 규칙을 설명하는 대신, 프로젝트 루트에 규칙을 파일로 적어두면 도구가 세션마다 자동으로 읽어들입니다. 사람이 온보딩 문서를 한 번 잘 써두면 신규 팀원이 매번 같은 질문을 하지 않는 것과 같은 원리입니다. 차이는 이번 "팀원"이 AI라는 것뿐입니다.

전체 구조 한눈에 보기

.claude/
├── agents/         → 역할별 전담 에이전트 (코드 리뷰, 컴포넌트 작성 등)
├── commands/        → 반복 작업을 위한 커스텀 슬래시 커맨드
├── hooks/            → 커밋 전/후 자동 실행되는 검증 스크립트
├── rules/            → 파일 유형별로 자동 로드되는 코딩 규칙
├── skills/           → 특정 상황에서 자동 발동되는 작업 지침
├── settings.json    → 권한 · 훅 · 모델 설정
└── CLAUDE.md         → 프로젝트 전체 맥락 (매 세션 자동 로드)

1. Agents 역할별 전담 담당자

하나의 AI에게 모든 걸 시키는 대신, 코드 리뷰만 하는 에이전트, 컴포넌트 작성만 하는 에이전트를 따로 두면 각자가 자기 역할에만 집중해 결과물 품질이 올라갑니다. 예를 들어 "쌍따옴표 강제, 인라인 style 금지, className 병합 시 cn() 사용" 같은 프로젝트 고유 규칙을 리뷰 에이전트에게 미리 알려두면, 매번 같은 지적을 반복하지 않아도 됩니다.

---
name: code-reviewer
description: 코드 스타일, 보안, 성능을 검사하는 리뷰어
tools: Read, Grep, Glob
model: sonnet
---

이 프로젝트는 style= 속성 사용을 금지하고, className 조합에는 반드시
cn()을 사용합니다. 리뷰 시 이 두 가지를 최우선으로 확인하세요.

2. Commands 자주 쓰는 작업을 슬래시 한 번으로

"이슈 번호 받아서 브랜치 만들고, 관련 코드 찾고, 수정하고, 커밋 메시지까지 쓰는" 흐름을 매번 말로 설명하는 대신 커맨드 하나로 등록해두면 됩니다.

---
name: fix-issue
argument-hint: [issue-number]
---

이슈 #$ARGUMENTS 를 처리합니다.
1. gh issue view $ARGUMENTS 로 내용 확인
2. 관련 코드 위치 찾기
3. 수정 및 필요한 테스트 추가
4. "fix: #$ARGUMENTS ..." 형식으로 커밋

3. Hooks AI도 지킬 수밖에 없는 규칙

아무리 규칙을 문서로 잘 적어둬도 "깜빡하는" 경우가 생깁니다. Hooks는 특정 행동 전후에 스크립트를 강제로 실행시켜서, 규칙을 "권장"이 아니라 "차단"으로 만듭니다. 예를 들어 커밋 직전에 린트를 자동으로 돌리고, 실패하면 커밋 자체를 막을 수 있습니다.

4. Rules 파일 종류별 자동 로드 규칙

프로젝트가 커질수록 "모든 규칙을 매번 다 읽는" 것보다 "지금 만지는 파일에 관련된 규칙만 읽는" 게 효율적입니다. 예를 들어 프론트엔드 컴포넌트 파일을 열 때만 Tailwind/디자인 규칙이 자동으로 적용되고, API 라우트를 열 때는 인증/에러 처리 규칙이 자동으로 적용되는 식입니다.

5. Skills 특정 상황에서만 발동되는 전문 지침

랜딩페이지 디자인처럼 특정 작업에서만 필요한 세부 지침(정확한 타이포그래피, 여백, 색상 규칙)을 평소엔 숨겨뒀다가, 관련 작업을 할 때만 자동으로 불러오는 방식입니다.

6. CLAUDE.md 프로젝트의 첫인상

가장 기본이 되는 파일입니다. 기술 스택, 자주 쓰는 명령어, 코딩 컨벤션을 여기 적어두면 세션을 새로 시작할 때마다 AI가 이 프로젝트의 맥락을 다시 학습합니다. 실제로 저희가 이 사이트에서 쓰는 CLAUDE.md에는 "yarn만 사용, npm install 금지", "인라인 style 속성 절대 금지, className만 사용" 같은 규칙이 명시되어 있고, 이후 모든 작업이 이 규칙을 자동으로 따릅니다.

7. settings.json 권한과 자동화의 컨트롤 타워

어떤 명령어를 자동 허용할지, 어떤 건 매번 확인받을지, 어떤 훅을 어느 시점에 실행할지를 이 파일 하나로 관리합니다.

실전 사례 저희가 이 구조로 막은 버그

저희 프로젝트에는 여러 페이지에서 재사용되는 공용 다이얼로그 컴포넌트가 있었습니다. 두 곳의 호출부에서 각자 다이얼로그 너비를 넓히려고 스타일을 덮어썼는데, 이 과정에서 의도치 않게 모바일 여백까지 함께 사라지는 버그가 같은 세션 안에서 두 번 반복됐습니다. 원인은 "공용 컴포넌트를 고칠 땐 호출부가 아니라 정의 파일 자체를 고쳐야 한다"는 원칙이 문서화되어 있지 않았기 때문입니다.

이후 저희는 이 원칙을 .claude/rules/ 아래 규칙 파일로 만들어두었고, 이제는 AI든 사람이든 공용 컴포넌트를 만질 때 이 규칙을 자동으로 참고합니다. 같은 버그가 세 번째로 재발할 일은 없어진 셈입니다.

지금 바로 시작하는 법

터미널에서 아래 스크립트 한 번이면 기본 골격이 만들어집니다.

mkdir -p .claude/{agents,commands,hooks,rules,skills}
touch .claude/agents/code-reviewer.md
touch .claude/rules/frontend.md
touch .claude/CLAUDE.md
touch .claude/settings.json

이후 각 파일에 여러분 프로젝트의 실제 규칙(따옴표 스타일, 폴더 구조, 자주 쓰는 명령어 등)을 채워 넣으면 됩니다.

다음 단계

이런 구조를 이미 적용해 관리하고 있는 Next.js 템플릿이 궁금하다면 GOSPELFIX 템플릿 마켓플레이스를 둘러보세요. 프로젝트에 맞는 커스텀 세팅이 필요하다면 무료 견적 문의로 편하게 물어보셔도 됩니다.