클로드 코드 90%가 모르는 폴더 설정

3줄 요약

• CLAUDE.md는 Claude에게 주는 프로젝트 업무 지시서입니다.
• .claude 폴더는 Claude가 실제로 일하는 방식, 버튼, 팀원, 안전장치를 넣는 작업실입니다.
• Agents, Skills, Hooks 3가지만 잡아도 Claude Code 활용도가 확 달라집니다.

전체 폴더 구조 한눈에 보기

your-project/
├── CLAUDE.md
├── CLAUDE.local.md
├── .gitignore
├── .mcp.json
├── .claude/
│   ├── agents/
│   │   ├── code-reviewer.md
│   │   └── researcher.md
│   ├── skills/
│   │   └── carousel/
│   │       ├── SKILL.md
│   │       └── scripts/
│   │           └── export.ts
│   ├── commands/
│   │   └── commit.md
│   ├── hooks/
│   │   ├── PostToolUse.sh
│   │   └── SessionStart.sh
│   ├── output-styles/
│   │   └── terse.md
│   ├── plugins/
│   │   └── vercel/
│   └── rules/
│       └── api.md
├── settings.json
├── settings.local.json
└── statusline.sh

이 구조를 다 만들어야 한다는 뜻은 아닙니다.

처음에는 CLAUDE.md, .claude/agents, .claude/skills, .claude/hooks 정도만 잡아도 충분합니다.

1. CLAUDE.md — 프로젝트의 두뇌

CLAUDE.md는 Claude에게 주는 프로젝트 매뉴얼입니다.

사람으로 치면 첫 출근한 직원에게 주는 온보딩 문서입니다. 이 파일이 없으면 Claude는 매번 프로젝트 상황을 새로 물어봐야 하고, 같은 설명을 반복해야 합니다.

여기에 적어둘 내용은 아래 정도면 됩니다.

• 이 프로젝트의 목적
• 기술 스택
• 폴더 구조 설명
• 코드 작성 규칙
• 절대 하면 안 되는 행동
• 배포 전 체크리스트
• 자주 쓰는 명령어

예시

# Project Guide

## 프로젝트 목적
이 프로젝트는 AI 무료자료 랜딩페이지를 관리하는 웹사이트입니다.
사용자가 인스타그램 댓글을 통해 들어왔을 때, 자료를 빠르게 확인하고 신청하도록 돕는 것이 목적입니다.

## 기술 스택
- Frontend: Next.js
- Styling: Tailwind CSS
- Deploy: Vercel
- Database: Supabase

## 작업 규칙
- 기존 UI 톤을 유지한다.
- 불필요한 라이브러리를 추가하지 않는다.
- 수정 전 관련 파일을 먼저 확인한다.
- 배포 전 `npm run build`를 실행한다.

## 금지 사항
- `.env` 파일을 수정하지 않는다.
- 사용자 데이터 구조를 임의로 바꾸지 않는다.
- 확인 없이 대규모 리팩토링하지 않는다.

작성 팁

CLAUDE.md는 길다고 좋은 게 아닙니다. Claude가 빠르게 읽고 판단할 수 있게 핵심만 200줄 이하로 정리하는 게 좋습니다.

2. CLAUDE.local.md — 내 컴퓨터 전용 메모

CLAUDE.local.md는 개인 환경 전용 설정입니다.

팀원과 공유하면 안 되는 로컬 포트, 개인 테스트 계정, 내 컴퓨터에서만 쓰는 실행 방식 등을 적어둡니다.

예시는 아래와 같습니다.

# Local Notes

## 내 로컬 환경
- 개발 서버: http://localhost:3000
- 테스트 계정: test@example.com
- 로컬 DB 포트: 54321

## 개인 작업 방식
- 디자인 수정 전 `/components` 폴더부터 확인한다.
- 배포는 내가 직접 확인한 뒤 진행한다.

주의할 점은 이 파일을 GitHub에 올리지 않는 것입니다. 그래서 .gitignore에 반드시 추가해야 합니다.

3. .gitignore — 위험한 파일을 GitHub에서 제외

.gitignore는 올리면 안 되는 파일을 막아주는 안전장치입니다.

특히 아래 파일은 보통 GitHub에 올리지 않는 게 좋습니다.

.env
.env.local
CLAUDE.local.md
settings.local.json
node_modules/
.DS_Store

간단히 말하면, 비밀번호, 토큰, 개인 설정, 로컬 전용 파일은 GitHub에 올리면 안 됩니다.

4. .mcp.json — Claude와 외부 도구 연결

.mcp.json은 Claude Code가 외부 도구와 직접 연결될 수 있게 해주는 설정 파일입니다.

예를 들면 이런 도구들을 연결할 수 있습니다.

• Supabase
• Playwright
• Stripe
• GitHub
• Notion
• Vercel

쉽게 말하면, Claude가 단순히 코드를 읽는 게 아니라 데이터베이스, 브라우저 테스트, 결제 API, 배포 시스템까지 같이 다룰 수 있게 해주는 연결 설정입니다.

다만 MCP 설정에는 민감한 토큰이 들어갈 수 있으니 팀 프로젝트에서는 공개 범위를 조심해야 합니다.

5. .claude 폴더 — 진짜 핵심 작업실

많은 사람이 CLAUDE.md까지만 만들고 끝냅니다.

그런데 Claude Code를 제대로 쓰려면 진짜 핵심은 .claude 폴더 안에 있습니다.

.claude 폴더에는 Claude가 프로젝트에서 어떻게 일할지 정하는 하위 시스템이 들어갑니다.

6. agents — 일 나눠줄 AI 팀원

agents는 특정 역할을 맡은 하위 에이전트입니다.

메인 Claude에게 모든 일을 한 번에 시키면 컨텍스트가 지저분해지고 판단이 흐려질 수 있습니다. 이때 역할별 에이전트를 만들어두면 좋습니다.

예시 역할은 아래와 같습니다.

• code-reviewer.md: 코드 리뷰 전담
• researcher.md: 자료 조사 전담
• bug-hunter.md: 버그 원인 분석 전담
• copywriter.md: 랜딩페이지 카피 전담
• seo-checker.md: SEO 점검 전담

예시: .claude/agents/code-reviewer.md

# Code Reviewer Agent

당신은 10년 차 시니어 프론트엔드 개발자입니다.
코드를 검토할 때 아래 기준으로 판단합니다.

## 검토 기준
- 기능이 요구사항과 맞는가
- 불필요한 복잡성이 없는가
- 보안상 위험한 코드가 없는가
- 기존 코드 스타일과 맞는가
- 빌드 실패 가능성이 없는가

## 출력 방식
1. 핵심 문제
2. 수정 제안
3. 배포 전 체크리스트

이렇게 만들어두면 Claude에게 “코드 리뷰어로 확인해줘”라고 시킬 때 훨씬 일관된 결과가 나옵니다.

7. skills — 자주 하는 일을 버튼처럼 실행

skills는 반복 업무를 묶어둔 워크플로우입니다.

매번 긴 프롬프트를 입력하지 않고, 자주 하는 일을 정해진 방식으로 실행하게 만들 수 있습니다. 잘 활용하면 결과물 퀄리티도 동일한 수준으로 높게 끌어올릴 수 있어요.

예를 들면 이런 식입니다.

• 릴스 대본 생성
• 카드뉴스 구성
• 랜딩페이지 카피 점검
• 코드 배포 전 검수
• 블로그 글 SEO 점검
• 상세페이지 섹션 구성

예시 구조

.claude/
└── skills/
    └── carousel/
        ├── SKILL.md
        └── scripts/
            └── export.ts

예시: .claude/skills/carousel/SKILL.md

# Carousel Skill

인스타그램 카드뉴스를 기획하고 제작하기 위한 스킬입니다.

## 사용 목적
하나의 주제를 5~7장짜리 카드뉴스 구조로 정리합니다.

## 입력값
- 주제
- 타깃
- 원하는 톤
- CTA

## 출력 형식
1. 표지 문구
2. 문제 제기
3. 핵심 설명
4. 예시
5. 정리
6. CTA

## 규칙
- 한 장에는 한 메시지만 담는다.
- 문장은 짧게 쓴다.
- 표지는 1초 안에 이해되게 쓴다.

이런 식으로 만들어두면 “이 주제로 캐러셀 스킬 써줘”처럼 반복 업무를 훨씬 빠르게 처리할 수 있습니다.

8. hooks — 실수를 막는 자동 안전장치

hooks는 특정 순간에 자동 실행되는 쉘 스크립트입니다.

CLAUDE.md가 “이렇게 해줘”라고 적어둔 문서라면, hooks는 실제로 행동을 강제하는 장치입니다.

예를 들면 아래 같은 상황에 쓸 수 있습니다.

• 세션 시작 시 프로젝트 상태 자동 점검
• 파일 수정 후 자동 포맷팅
• 커밋 전 테스트 실행
• 배포 전 빌드 체크
• 위험한 명령어 실행 차단

예시: .claude/hooks/SessionStart.sh

#!/bin/bash

echo "프로젝트 상태를 확인합니다."
git status

예시: .claude/hooks/PostToolUse.sh

#!/bin/bash

echo "파일 수정 후 포맷팅을 실행합니다."
npm run lint

초보자는 처음부터 복잡하게 만들 필요 없습니다. 우선 git status, npm run lint, npm run build 정도만 연결해도 충분합니다.

9. commands — 자주 쓰는 명령어를 문서화

commands는 자주 반복하는 작업 명령을 정리해두는 곳입니다.

예를 들어 커밋 메시지를 자동으로 정리하거나, 배포 전 체크리스트를 실행하는 식으로 쓸 수 있습니다.

예시: .claude/commands/commit.md

# Commit Command

변경된 파일을 확인하고, 의미 단위로 커밋 메시지를 제안합니다.

## 해야 할 일
1. `git diff`로 변경사항을 확인한다.
2. 기능 추가, 버그 수정, 문서 수정 중 하나로 분류한다.
3. 커밋 메시지를 3개 제안한다.
4. 사용자가 승인하기 전에는 커밋하지 않는다.

10. rules — 특정 파일을 다룰 때의 세부 규칙

rules는 특정 영역을 다룰 때 지켜야 하는 규칙입니다.

예를 들어 API 파일을 수정할 때는 보안 검사를 더 엄격하게 하고, DB 파일을 수정할 때는 마이그레이션을 확인하게 만들 수 있습니다.

예시: .claude/rules/api.md

# API Rules

API 관련 파일을 수정할 때는 아래 규칙을 따른다.

## 규칙
- 인증 로직을 임의로 제거하지 않는다.
- 사용자 입력값은 반드시 검증한다.
- 에러 메시지에 민감한 정보를 노출하지 않는다.
- DB 구조 변경이 필요하면 먼저 사용자에게 확인한다.

11. output-styles — 답변 스타일 고정

output-styles는 Claude의 출력 방식을 정하는 곳입니다.

예를 들어 너무 장황하게 설명하지 않고, 바로 액션 아이템만 말하게 만들 수 있습니다.

예시: .claude/output-styles/terse.md

# Terse Output Style

## 답변 원칙
- 불필요한 배경 설명은 줄인다.
- 먼저 결론을 말한다.
- 실행 가능한 체크리스트로 정리한다.
- 코드 변경 시 변경 파일과 이유를 함께 설명한다.

12. plugins — 스킬, 에이전트, 명령어 묶음

plugins는 여러 설정을 하나의 패키지처럼 묶어두는 공간입니다.

예를 들어 Vercel 배포용 플러그인을 만들어두면, 배포 전 체크, 빌드 확인, 환경변수 점검, 배포 명령까지 한 흐름으로 묶을 수 있습니다.

예시 구조

.claude/
└── plugins/
    └── vercel/
        ├── deploy.md
        ├── checklist.md
        └── rules.md

13. settings.json — 전체 제어 패널

settings.json은 Claude Code의 전체 동작 설정을 관리하는 파일입니다.

여기에는 모델 설정, 권한, 실행 가능한 명령, 차단할 명령, 훅 사용 여부 등이 들어갈 수 있습니다.

초보자는 처음부터 복잡하게 만질 필요 없습니다. 다만 중요한 점은 하나입니다.

Claude가 할 수 있는 일과 하면 안 되는 일을 분리해야 합니다.

예를 들어 아래처럼 생각하면 됩니다.

• 허용: 파일 읽기, 코드 수정, 테스트 실행
• 주의: 패키지 설치, DB 변경, 배포
• 금지: 비밀키 출력, 환경변수 삭제, 승인 없는 배포

초보자용 최소 세팅

처음부터 모든 폴더를 만들 필요는 없습니다.

일단 아래 4개만 만들어도 체감이 큽니다.

your-project/
├── CLAUDE.md
├── .gitignore
└── .claude/
    ├── agents/
    │   └── code-reviewer.md
    ├── skills/
    │   └── content-checker/
    │       └── SKILL.md
    └── hooks/
        └── SessionStart.sh

이 정도만 있어도 Claude가 프로젝트를 훨씬 안정적으로 이해합니다.

바로 복붙해서 쓰는 CLAUDE.md 템플릿

# CLAUDE.md

## 프로젝트 개요
이 프로젝트는 [프로젝트 목적]을 위한 프로젝트입니다.
주요 사용자는 [사용자 유형]이며, 핵심 목표는 [핵심 목표]입니다.

## 기술 스택
- Frontend: [예: Next.js]
- Styling: [예: Tailwind CSS]
- Backend: [예: Supabase]
- Deploy: [예: Vercel]

## 폴더 구조
- `/app`: 페이지와 라우팅
- `/components`: 재사용 컴포넌트
- `/lib`: 유틸 함수와 API 연결
- `/public`: 이미지와 정적 파일

## 작업 원칙
- 기존 구조를 먼저 확인한 뒤 수정한다.
- 불필요한 리팩토링은 하지 않는다.
- 큰 변경 전에는 사용자에게 먼저 확인한다.
- 수정 후 빌드 가능성을 확인한다.

## 금지 사항
- `.env` 파일을 노출하지 않는다.
- 승인 없이 배포하지 않는다.
- DB 스키마를 임의로 변경하지 않는다.
- 보안 관련 코드를 임의로 삭제하지 않는다.

## 자주 쓰는 명령어
- 개발 서버 실행: `npm run dev`
- 린트 확인: `npm run lint`
- 빌드 확인: `npm run build`

## 응답 방식
- 먼저 결론을 말한다.
- 수정한 파일과 이유를 함께 설명한다.
- 위험한 변경은 진행 전에 확인한다.

세팅 순서

1. 프로젝트 루트에 CLAUDE.md를 만든다.
2. 프로젝트 목적, 기술 스택, 금지사항을 적는다.
3. CLAUDE.local.md를 만들고 개인 설정을 적는다.
4. .gitignore에 로컬 전용 파일을 추가한다.
5. .claude 폴더를 만든다.
6. agents, skills, hooks 중 필요한 것부터 추가한다.
7. Claude Code를 열고 “이 프로젝트 구조를 읽고 개선점 알려줘”라고 요청한다.

Claude에게 처음 시킬 말

아래 문장을 그대로 복사해서 Claude Code에 넣어보세요.

이 프로젝트를 위해 CLAUDE.md와 .claude 폴더 구조를 토큰 최적화 및 context를 잘 파악할 수 있게 세팅하려는데 내 의도에 맞게 세팅해줘.
특히 agents, skills, hooks를 어떻게 나누면 좋을지 초보자도 이해할 수 있게 제안해줘.
그리고 바로 만들 수 있는 최소 폴더 구조와 파일 내용을 예시로 작성해줘.

보너스! 진단용 프롬프트예요. 역시 복붙해서 써보세요.

이 프로젝트의 CLAUDE.md와 .claude 폴더 구조를 읽고, 현재 설정에서 부족한 점을 진단해줘.
특히 agents, skills, hooks를 어떻게 나누면 좋을지 초보자도 이해할 수 있게 제안해줘.
그리고 바로 만들 수 있는 최소 폴더 구조와 파일 내용을 예시로 작성해줘.

실전 예시: 마케팅 랜딩페이지 프로젝트라면

마케팅 랜딩페이지 프로젝트에서는 이런 식으로 나눌 수 있습니다.

.claude/
├── agents/
│   ├── copywriter.md
│   ├── conversion-reviewer.md
│   └── seo-checker.md
├── skills/
│   ├── landing-copy/
│   │   └── SKILL.md
│   └── blog-seo/
│       └── SKILL.md
└── hooks/
    └── pre-deploy-check.sh

역할은 이렇게 잡으면 됩니다.

• copywriter: 헤드라인, CTA, 상세페이지 문구 점검
• conversion-reviewer: 전환율 관점에서 섹션 흐름 점검
• seo-checker: 검색 노출 관점에서 제목, H태그, 키워드 점검
• pre-deploy-check: 배포 전 빌드와 링크 오류 확인

마지막 체크리스트

• ☐ CLAUDE.md에 프로젝트 목적이 적혀 있는가?
• ☐ 금지사항이 명확한가?
• ☐ 로컬 전용 파일이 .gitignore에 들어가 있는가?
• ☐ 반복 업무를 skills로 분리했는가?
• ☐ 코드 리뷰나 조사 업무를 agents로 분리했는가?
• ☐ 배포 전 실수 방지용 hooks가 있는가?
• ☐ Claude에게 승인 없이 하면 안 되는 일을 명확히 알려줬는가?

핵심 정리

클로드 코드는 그냥 채팅창이 아닙니다.

CLAUDE.md는 업무 매뉴얼이고, .claude 폴더는 Claude의 작업 시스템입니다.

이 구조를 잡아두면 Claude는 매번 새로 설명해야 하는 도구가 아니라, 프로젝트 맥락을 알고 움직이는 전담 개발자처럼 일할 수 있습니다.