Claude Code 폴더 설정 가이드: CLAUDE.md·Skills·Agents·Hooks 실전 예시

your-project/
├── CLAUDE.md
├── CLAUDE.local.md
├── .gitignore
└── .claude/
    ├── settings.json
    ├── settings.local.json
    ├── agents/
    │   └── code-reviewer.md
    └── skills/
        └── project-check/
            └── SKILL.md

# Project Guide

## 프로젝트 개요

이 프로젝트는 [프로젝트 목적]을 위한 프로젝트입니다.
주요 사용자는 [사용자 유형]이며,
핵심 목표는 [사용자가 얻어야 할 결과]입니다.

## 기술 스택

- Frontend: [예: Next.js]
- Styling: [예: Tailwind CSS]
- Database: [예: Supabase]
- Deploy: [예: Vercel]

## 주요 폴더

- `/app`: 페이지와 라우팅
- `/components`: 재사용 컴포넌트
- `/lib`: 유틸리티와 외부 서비스 연결
- `/public`: 이미지와 정적 파일

## 작업 원칙

- 작업 전 관련 파일과 기존 구조를 먼저 확인한다.
- 현재 디자인과 코드 스타일을 유지한다.
- 불필요한 라이브러리를 추가하지 않는다.
- 요청과 관계없는 리팩터링은 하지 않는다.

## 금지사항

- 환경변수와 비밀키를 출력하지 않는다.
- 승인 없이 배포하지 않는다.
- 데이터베이스 구조를 임의로 변경하지 않는다.
- 기존 사용자 작업을 임의로 삭제하지 않는다.

## 작업 후 확인

- 관련 테스트를 실행한다.
- 린트와 빌드 오류를 확인한다.
- 수정한 파일과 이유를 요약한다.
- 확인하지 못한 항목은 명확하게 밝힌다.

## 응답 방식

- 결론을 먼저 말한다.
- 변경한 파일과 변경 이유를 설명한다.
- 위험하거나 되돌리기 어려운 작업은 먼저 확인한다.

cd my-project
claude
/init

/init으로 만든 CLAUDE.md를 확인하고 아래 내용을 보완해줘.

1. 이 프로젝트의 목적
2. 주요 폴더의 역할
3. 작업할 때 지켜야 할 규칙
4. 절대 수정하면 안 되는 파일
5. 작업 후 실행할 테스트와 빌드 명령

.claude/skills/project-check/SKILL.md

---
name: project-check
description: 변경 작업을 완료하기 전에 프로젝트 규칙, 오류, 테스트 여부를 점검합니다.
---

# Project Check

변경사항을 완료하기 전에 다음 순서로 확인합니다.

1. 요청한 기능이 실제로 반영되었는지 확인합니다.
2. 관련 테스트를 실행합니다.
3. 린트와 빌드 오류를 확인합니다.
4. 보안 또는 개인정보 노출 위험을 확인합니다.
5. 확인한 내용과 남은 위험을 요약합니다.

검증하지 않은 항목을 완료했다고 말하지 않습니다.

# 이 프로젝트에서만 사용
my-project/
└── .claude/
    └── skills/
        └── landing-copy/
            └── SKILL.md

# 모든 프로젝트에서 사용
~/.claude/
└── skills/
    └── writing-check/
        └── SKILL.md

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: 코드 변경사항을 기능, 보안, 복잡성, 테스트 관점에서 검토합니다.
tools: Read, Grep, Glob, Bash
model: inherit
---

# Code Reviewer

직접 코드를 수정하지 않고 변경사항을 검토합니다.

## 검토 기준

1. 요청한 기능과 구현이 일치하는가
2. 기존 구조와 스타일을 따르는가
3. 불필요한 복잡성이나 중복이 있는가
4. 비밀키, 개인정보, 권한 관련 위험이 있는가
5. 테스트가 핵심 동작을 검증하는가

## 출력 형식

- 먼저 배포를 막아야 할 문제를 제시합니다.
- 각 문제에 파일 위치, 영향, 수정 방향을 적습니다.
- 문제가 없다면 확인한 범위와 남은 위험을 적습니다.

.claude/agents/seo-checker.md

---
name: seo-checker
description: 블로그 글을 검색 의도, 제목, 구조, 내부 링크 관점에서 검토합니다.
tools: Read, Grep, Glob
model: inherit
---

# SEO Checker

글을 직접 수정하지 않고 아래 항목을 검토합니다.

## 검토 기준

1. 제목에 핵심 검색어가 자연스럽게 포함되어 있는가
2. 첫 문단에서 검색 질문에 바로 답하는가
3. H2 제목만 읽어도 글의 흐름이 이해되는가
4. 예시와 근거가 충분한가
5. 관련 글로 연결할 내부 링크가 있는가

## 출력 형식

- 가장 먼저 고쳐야 할 문제 3개
- 각 문제의 영향
- 수정 문장 예시
- 발행 전 체크리스트

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run format"
          }
        ]
      }
    ]
  }
}

.env
.env.local
.env.production

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

node_modules/
.next/
.DS_Store

# Local Notes

## 내 로컬 환경

- 개발 서버: http://localhost:3000
- 로컬 DB 포트: 54321
- 테스트 브라우저: Chrome

## 개인 작업 방식

- 디자인 수정 전 `/components` 폴더부터 확인한다.
- 실제 배포는 내가 직접 진행한다.
- 데이터베이스 변경이 필요하면 먼저 나에게 확인한다.

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

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

landing-page/
├── CLAUDE.md
├── CLAUDE.local.md
└── .claude/
    ├── settings.json
    ├── agents/
    │   ├── copy-reviewer.md
    │   └── seo-checker.md
    └── skills/
        ├── landing-copy/
        │   └── SKILL.md
        └── publish-check/
            └── SKILL.md

CLAUDE.md
→ 브랜드, 상품, 고객, 금지 표현

landing-copy Skill
→ 헤드라인과 CTA 작성 절차

copy-reviewer Agent
→ 작성된 카피를 독립적으로 검토

seo-checker Agent
→ 제목, H태그, 검색 의도 점검

publish-check Skill
→ 링크, 오탈자, 모바일 화면 확인

PostToolUse Hook
→ 파일 수정 후 포맷터 자동 실행

# Claude Code 최소 세팅 체크리스트

## CLAUDE.md
- [ ] 프로젝트 목적과 주요 사용자가 적혀 있다.
- [ ] 작업 원칙과 금지사항이 구체적이다.
- [ ] 테스트·린트·빌드처럼 확인할 명령이 적혀 있다.

## Skill
- [ ] 자주 반복하는 업무 하나를 Skill로 분리했다.
- [ ] 언제 사용하는 Skill인지 description에 적었다.
- [ ] 실행 순서와 완료 기준이 명확하다.

## Agent
- [ ] Agent가 맡을 역할이 한 가지로 명확하다.
- [ ] 검토 기준과 출력 형식이 적혀 있다.
- [ ] 필요한 도구만 사용할 수 있게 설정했다.

## Hook
- [ ] Hook이 .claude/settings.json에 등록되어 있다.
- [ ] 실행할 명령이 프로젝트에 실제로 존재한다.
- [ ] 위험한 명령이나 과도한 반복 실행이 없는지 확인했다.

## 보안과 최종 확인
- [ ] CLAUDE.local.md와 settings.local.json을 Git에서 제외했다.
- [ ] .env와 비밀키 파일의 읽기 권한을 제한했다.
- [ ] Claude Code를 다시 열어 설정이 동작하는지 확인했다.