isdnetworks
Go back

Claude Code 프로젝트 설정 구조 — 실전 사례

Claude Code는 .claude/ 폴더를 통해 프로젝트별 동작을 제어할 수 있다. 단순한 프롬프트 파일 하나가 아니라, 규칙·훅·컨텍스트·스킬·에이전트까지 체계적으로 구성하면 일관성 있는 AI 협업 환경을 만들 수 있다.

이 글에서는 실제 프로젝트에서 사용한 .claude/ 구성을 소개한다.

Table of contents

Open Table of contents

전체 디렉토리 구조

.claude/
├── CLAUDE.md                    # 프로젝트 메모리 (진입점)
├── settings.json                # 설정 + 훅 등록
├── settings.local.json          # 로컬 환경 오버라이드 (gitignore)
├── rules/                       # 도메인별 규칙
│   ├── database.md
│   ├── file.md
│   ├── naming.md
│   ├── mcp.md
│   └── documents-guidelines.md
├── hooks/                       # 자동화 스크립트
│   ├── guard-bash.ps1/.sh       # 위험 명령 차단
│   ├── guard-edit.ps1/.sh       # 민감 파일 수정 차단
│   ├── memory-*.ps1/.sh         # 외부 메모리 연동
│   ├── change-tracker.ps1/.sh   # 변경 추적
│   └── ...
├── context/                     # 환경별 컨텍스트
│   ├── servers/*.md             # 서버별 접속/스펙 정보
│   ├── containers/*.md          # 컨테이너별 설정 정보
│   ├── project/*.md             # 프로젝트별 기술 스택/빌드 정보
│   └── python.md, nodejs.md ... # 언어/도구별 설정
├── skills/                      # 커스텀 스킬 (슬래시 명령)
│   ├── deep-think/SKILL.md
│   ├── review/SKILL.md
│   └── ...
├── agents/                      # 커스텀 에이전트
│   ├── db-reader.md
│   └── security-reviewer.md
└── shared/                      # 공유 참조 문서
    └── project-references.md

CLAUDE.md — 프로젝트 진입점

CLAUDE.md는 Claude Code가 세션 시작 시 가장 먼저 읽는 파일이다. 여기에 모든 규칙을 나열하는 것이 아니라, 조건부 로딩 지시를 작성한다.

**최우선 지시: Hooks, Rules, CLAUDE.md 및 context의 모든 지시를 반드시 따를 것.**

### [db-context.md](context/db-context.md)
- 데이터베이스 관련 작업 시
- MariaDB 인스턴스 정보, 활성 작업 반드시 확인할 것

### [python.md](context/python.md)
- Python 관련 작업 시
- 준수 사항, PATH 설정, pyenv-win 환경 변수 반드시 확인할 것

이 방식의 장점:

rules/ — 도메인별 규칙

rules/ 폴더의 .md 파일은 Claude Code가 항상 로딩한다. 따라서 프로젝트 전반에 적용되는 핵심 규칙만 넣는다.

database.md — 데이터베이스 규칙 예시

## 금지 사항
- WHERE 없는 UPDATE/DELETE
- 프로덕션 DROP TABLE
- 인덱스 없는 UPDATE/DELETE
- SELECT * 프로덕션 사용
- 영향 row 수 미확인 대량 작업

## 작업 규칙
- 모든 작업 파일은 `database/YYYYMMDD_작업명/` 폴더에 보관
- 쿼리 실행 전 반드시 EXPLAIN으로 실행 계획 확인

file.md — 파일 작업 규칙 예시

## MUST NOT (절대 금지)
- 백업 확인 없이 삭제
- 시스템 디렉토리 수동 정리
- root 권한 무분별 사용

## MUST (필수)
- 경로 두 번 확인
- 백업 존재 확인
- 영향 범위 계산

규칙은 MUST NOT > MUST > SHOULD 순으로 우선순위를 명확히 한다.

hooks/ — 자동화의 핵심

hooks는 Claude Code의 특정 이벤트에 셸 스크립트를 연결하는 기능이다. settings.json에서 이벤트별로 등록한다.

주요 이벤트와 활용

이벤트용도실제 훅
PreToolUse도구 실행 전 검증/차단guard-bash.ps1 — 위험 명령 차단
PostToolUse도구 실행 후 처리change-tracker.ps1 — 변경 추적
SessionStart세션 시작 시 초기화memory-session-start.ps1 — 메모리 로드
UserPromptSubmit사용자 입력 시memory-user-prompt-submit.ps1 — 컨텍스트 주입
PostToolUseFailure도구 실패 시memory-post-tool-use-failure.ps1 — 해결책 검색
Notification알림 발생 시notify-windows.ps1 — Windows 토스트 알림
Stop작업 중단 시session-summary.ps1 — 세션 요약

guard-bash.ps1 — 위험 명령 차단

가장 중요한 훅이다. PreToolUse 이벤트에서 Bash 도구의 명령어를 검사하고, 위험한 패턴을 차단한다.

# mysql CLI 차단 → mariadb CLI 사용 강제
if ($Cmd -match '(^|[|;&])\s*(sudo\s+)?(\S*/)?mysql\b') {
    Block-Command "mysql CLI 사용 금지. mariadb CLI를 사용하세요."
}

# 재귀 삭제 차단
if ($Cmd -match 'rm\s+(-[a-zA-Z]*[rR]|--recursive)') {
    Block-Command "rm -r 사용 금지. 개별 파일 삭제를 사용하세요."
}

차단 대상:

guard-edit.ps1 — 민감 파일 수정 차단

Edit/Write 도구 사용 시 대상 파일을 검사한다.

# .env 파일 보호
if ($FilePath -match '\.env($|\.)') {
    Block-Edit ".env 파일 직접 수정 금지."
}

# lock 파일 보호
if ($FilePath -match '(package-lock|pnpm-lock|yarn\.lock)') {
    Block-Edit "lock 파일 직접 수정 금지."
}

외부 메모리 연동 훅

세션의 각 단계에서 외부 지식 그래프 기반 메모리 서비스를 자동으로 활용한다.

크로스 플랫폼 지원

모든 훅은 .ps1(Windows)과 .sh(macOS/Linux) 쌍으로 존재한다. settings.json은 OS별로 분리한다.

settings.json          # 공통 (git tracked)
settings.windows.json  # Windows 전용 훅 경로
settings.macos.json    # macOS 전용 훅 경로
settings.local.json    # 로컬 환경 오버라이드 (gitignored)

context/ — 조건부 로딩 컨텍스트

context/는 rules와 달리 항상 로딩되지 않는다. CLAUDE.md의 조건부 지시에 의해 필요할 때만 참조된다.

구성 카테고리

context/
├── servers/           # 서버별: SSH 정보, Docker 경로, 하드웨어 스펙
│   ├── server-a.md
│   ├── server-b.md
│   └── ...
├── containers/        # 컨테이너별: 이미지, 포트, 볼륨, 설정
│   ├── infra.md       # nginx, mariadb, redis 등
│   └── ai.md          # AI/ML 관련 서비스
├── project/           # 프로젝트별: 기술 스택, 빌드 명령, 주요 설정
│   ├── project-alpha.md
│   ├── project-beta.md
│   └── archive/       # 아카이브된 프로젝트
└── python.md          # 언어별: PATH, 버전, 컨벤션

서버 컨텍스트 예시

# server-a

## 접속 정보
- SSH: `ssh server-a`
- Docker 소스: `/data/docker/`

## 하드웨어
- CPU: ARM 8코어
- RAM: 16GB
- Storage: NVMe 1TB

## 실행 중인 서비스
- nginx (리버스 프록시)
- mariadb (메인 DB)

skills/ — 커스텀 슬래시 명령

/review, /deep-think 같은 커스텀 명령을 만들 수 있다. 각 스킬은 SKILL.md 파일에 프롬프트를 정의한다.

skills/
├── deep-think/SKILL.md    # 다차원 심층 분석
├── review/SKILL.md        # 체계적 코드 리뷰
├── file-context/SKILL.md  # 바이너리 파일 읽기 가이드
└── sync-docs/SKILL.md     # 문서 동기화

agents/ — 커스텀 서브에이전트

특정 역할에 특화된 에이전트를 정의한다.

# db-reader.md
MariaDB 데이터 분석 및 조회 전문.
데이터베이스 쿼리, 테이블 구조 파악, 데이터 분석 시 사용.

에이전트는 사용 가능한 도구를 제한할 수 있어서, DB 조회 에이전트에는 Write/Edit 도구를 제외하여 실수로 파일을 수정하는 것을 방지한다.

설계 원칙

1. 계층적 분리

항상 로딩: CLAUDE.md + rules/*.md + settings.json
조건부 로딩: context/*.md (CLAUDE.md 지시에 의해)
사용자 호출: skills/ (슬래시 명령)
자동 실행: hooks/ (이벤트 기반)

2. 방어적 자동화

Claude Code에게 bypassPermissions 권한을 주되, hooks로 위험한 작업을 차단한다. “신뢰하되 검증한다(Trust but verify)” 원칙이다.

3. 크로스 플랫폼

Windows와 macOS에서 동일한 프로젝트를 사용하므로, 모든 훅을 .ps1/.sh 쌍으로 관리한다.

4. 외부 메모리 연동

외부 지식 그래프를 hooks로 연동하여, 세션 간 맥락을 유지한다. 이전 세션에서의 결정 사항, 제약 조건, 해결책이 자동으로 다음 세션에 전달된다.

마무리

.claude/ 폴더 구성은 단순히 “프롬프트를 잘 쓰는 것”을 넘어, AI 협업 환경을 체계적으로 설계하는 작업이다. 규칙으로 경계를 설정하고, 훅으로 안전장치를 만들고, 컨텍스트로 지식을 제공하면, Claude Code는 훨씬 일관성 있고 안전하게 동작한다.

참고 자료

Share this post on:
Share this post via WhatsApp Share this post on Facebook Share this post on X Share this post via Telegram Share this post on Pinterest Share this post via email
Previous Post
RK3588 NPU로 로컬 LLM 서버를 포기한 이유
Next Post
Go + Python 혼합 마이크로서비스에서 장애 격리 패턴 적용기