[ Claude ] 클로드 코드 상세 세팅 알아보기

AI Prompt Repo

---

https://github.com/HSRyuuu/AI-Practice-Archive

GitHub - HSRyuuu/AI-Practice-Archive: AI 활용방안, 사례를 모아둔 repository 입니다.

 

.claude

---

Claude Code를 사용하다 보면 프로젝트 루트에 .claude 디렉터리가 생성되는 것을 볼 수있다.

단순 설정파일이나 작업 공간으로 생각할 수 있지만, claude code를 단순 챗봇이 아니라 한명의 개발자로 사용할 수 있도록 도와주는 핵심 공간이다.

디렉터리 구조

.claude/
├── skills/           # 재사용 가능한 전문 지식 모듈 (자동 활성화)
├── agents/          # 특정 작업에 특화된 AI 서브에이전트
├── hooks/           # 생명주기 이벤트 기반 자동화 스크립트
├── commands/        # 사용자가 직접 호출하는 슬래시 커맨드
├── settings.json    # 프로젝트 레벨 설정
└── CLAUDE.md        # 프로젝트 컨벤션 및 가이드

 

.claude 디렉터리는 전역 설정 ( ~/.claude)을 할 수도 있고, 프로젝트 별로 따로 설정할 수도 있다. 

• ~/.claude/CLAUDE.md : 전역 설정, 모든 프로젝트에 적용
• {projectDir}/CLAUDE.md: 해당 프로젝트에만 적용 -> 전역보다 우선시 됨 

---

CLAUDE.md

이 파일은 Claude Code가 세션 시작 시 자동으로 컨텍스트에 로드하는 특별한 파일이다.

세션에서 사용할 기억, 규칙 역할을 한다.

모든 세션에서 항상 참조하는 규칙 프롬프트라고 생각하면 좋다.

example

# 프로젝트 명: XXX

## 기술스택
- Frontend: React19.x.x, Next.js 15.x.x, TypeScript
- Backend: Java21, SpringBoot3.x.x
- Database: PostgreSQL 15.x
...

## 주요 명령어
- `npm run build`: 프로젝트 빌드
- `npm run test`: 테스트 실행
- `./gradlew bootRun`: 백엔드 실행
- `./gradlew test`: 백엔드 테스트
...

## 개발 규칙
- **타입 안정성**: TypeScript 규칙을 엄격하게 준수
- **테스트 우선**: TDD 방법론으로 API 개발, 테스트 커버리지 90% 이상 유지
- **네이밍 규칙**: camelCase, 기능을 명확히 나타내는 이름 사용
...

## 제한사항
- main 브랜치에 직접 커밋 금지
- 코드 변경 후 타입 체크 실행
...

 

---

settings.json: 정적 설정 파일

settings.json은 Claude Code 동작을 커스터마이징 하는 정적 설정 파일이다.

권한 설정, hook 등록, 환경변수 설정, 모델 설정 등을 지정할 수 있다.

example

{
  "model": "claude-sonnet-4-20250514",
  "maxTokens": 4096,
  "permissions": {
    "allowedTools": ["Read", "Write", "Bash(git *)"],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Write(./production.config.*)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write(*.py)",
        "hooks": [
          {
            "type": "command",
            "command": "python -m black $file"
          }
        ]
      }
    ]
  }
}

 

---

Skills: 재사용 가능한 전문 지식 모듈 (자동 활성화)

Skills는 Claude에게 특정 도메인의 전문 지식을 주입하는 모듈이다. 

가장 큰 특징은 사용자가 명시적으로 호출하지 않아도 Claude가 상황을 판단해서 자동으로 활용한다는 점이다.

 

사용자 명령 프롬프트의 맥락을 파악하고, .claude/skills 디렉터리를 뒤져서 쓸만한 참고문서를 찾는것이다.

 

예를들면 미리 spring-testing 스킬을 등록해 둔 상태에서,

"Spring Boot 프로젝트에서 UserService 단위테스트 작성해줘" 라는 명령을 하면 아래와 같이 동작한다.

사용자 프롬프트: "Spring Boot 프로젝트에서 UserService 단위테스트 작성해줘"
                    ↓
미리 등록한 스킬들의 name, description 확인
                    ↓
spring-testing/SKILL.md의 description: "Spring Boot 단위테스트, JUnit5, Mockito, @WebMvcTest..."
                    ↓
매칭! 이 스킬을 사용해서 UserService 단위테스트 작성에 활용해야겠다.
                    ↓
AI는 spring-testing/SKILL.md의 전체 내용을 읽고, 작업에 규칙으로 활용한다.

 

호출 방법

자동 호출된다. 사용자 입력 프롬프트의 내용에 따라 적절한 Skill을 자동으로 찾는 방법으로 호출된다.

 

[ AI ] 클로드 스킬(Claude Skills, Agent Skill) 사용 방법, 커스텀해서 에이전트 만들기

[ AI ] 클로드 스킬(Claude Skills, Agent Skill) 사용 방법, 커스텀해서 에이전트 만들기

---

Commands: 사용자가 직접 실행하는 slash command

Commands는 Claude Code 세션에서 사용자가 직접 /명령어 형식으로 호출할 수 있는 재사용 가능한 프롬프트이다.

아래와 같이 등록 하여, 사용자가 명시적으로 호출하여 사용한다.

example

# 코드 리뷰

커밋되지 않은 변경 사항에 대한 포괄적인 보안 및 품질 검토

1. 변경된 파일 가져오기: `git diff --name-only HEAD`

2. 변경된 각 파일에 대해 다음 사항을 확인합니다.

**보안 문제(심각):**
- 하드코딩된 credential, API key, token
- SQL injection 취약점
- XSS 취약점
- 입력 유효성 검사 누락

**코드 품질(높음):**
- 함수 50줄 초과
- 파일 800줄 초과
- 중첩 깊이 4단계 초과
- 오류 처리 누락

**모범 사례(중간):**
- 변경 패턴(유의미한 이름의 정적 팩토리 메서드 사용)
- 코드/주석에서의 이모지 사용
- 새 코드에 대한 테스트 누락

3. 다음 명령으로 보고서 생성:
- 심각도: 심각, 높음, 중간, 낮음
- 파일 위치 및 줄 번호
- 문제 설명
- 권장 해결 방법

...

---

Agents: 특정 작업에 특화된 AI 서브 에이전트

Agents는 특정 작업에 특화된 독립적인 AI 어시스턴트이다. 

자체 Context Window를 가지고, 특정 도구와 권한으로 구성된다.

아래와 같이 역할을 부여하고, 특정 작업을 수행하도록 할 수 있다.

---
name: planner
description: 인터뷰 워크플로우(Opus)를 활용한 전략 기획 컨설턴트
model: opus
tools: Read, Glob, Grep, Edit, Write, Bash, WebSearch
---

# 전략 기획 컨설턴트

## 핵심 정체성 (먼저 읽어주세요)
당신은 기획자입니다. 실행자가 아닙니다. 코드를 작성하지 않습니다. 작업을 실행하지 않습니다.
이것은 제안이 아닙니다. 당신의 근본적인 정체성 제약 조건입니다.

### 요청 해석 (핵심)
사용자가 "X를 해 주세요", "X를 구현해 주세요", "X를 만들어 주세요", "X를 수정해 주세요", "X를 만들어 주세요"라고 말할 때:
- **절대** 작업을 수행하라는 요청으로 해석하지 마세요.

- **항상** "X에 대한 작업 계획을 세워 주세요"로 해석하세요.

| 사용자 말 | 당신의 해석 |

|-----------|------------------|

| "로그인 버그를 수정해 주세요" | "로그인 버그 수정을 위한 작업 계획을 세워 주세요" |

| "다크 모드를 추가해 주세요" | "다크 모드 추가를 위한 작업 계획 수립" |

"인증 모듈 리팩토링" | "인증 모듈 리팩토링을 위한 작업 계획 수립" |

**절대 예외 없음. 어떠한 상황에서도.**

...

---

Hooks: 생명 주기 이벤트 기반  자동화 스크립트

Hooks는 Claude Code 에이전트의 라이프사이클의 특정 시점에서 자동 실행되는 쉘 스크립트이다.

CLAUDE.md 규칙에서 AI 특유의 비결정적인(non-deterministic) 것을 보완해서, 결정론적인 규칙을 지정할 수 있다.

Hook Event 종류

Hook	실행 시점	용도
PreToolUse	도구 실행 전	작업 차단/허용
PostToolUse	도구 실행 후	포맷팅, 린팅
PermissionRequest	권한 요청 시	자동 승인/거부
UserPromptSubmit	사용자 입력 제출 시	컨텍스트 추가
SessionStart	세션 시작 시	환경 설정
SessionEnd	세션 종료 시	정리 작업
Notification	알림 발생 시	커스텀 알림
Stop	Claude 작업 완료 시	검증
PreCompact	컨텍스트 압축 전	상태 저장

 

Hook script 파일 예시 (.claude/hooks/learning_logger.py)

#!/usr/bin/env python3
"""
Stop hook 진입점 - 백그라운드로 분석 프로세스 실행 후 즉시 종료
"""
import json
import sys
import subprocess
from pathlib import Path

def main():
    try:
        # Stop hook에서 전달받은 데이터
        input_data = json.load(sys.stdin)
        session_id = input_data.get('session_id', '')
        cwd = input_data.get('cwd', '')

        if not session_id or not cwd:
            sys.exit(0)

        # 백그라운드로 analyze_session.py 실행
        analyze_script = Path.home() / '.claude' / 'hooks' / 'analyze_session.py'

        if analyze_script.exists():
            subprocess.Popen(
                ['python3', str(analyze_script), session_id, cwd],
                stdout=subprocess.DEVNULL,
                stderr=subprocess.DEVNULL,
                start_new_session=True  # 부모 프로세스와 완전 분리
            )

    except Exception:
        pass  # 에러가 나도 조용히 종료

    sys.exit(0)

if __name__ == '__main__':
    main()

 

Hook 등록 예시 (Settings.json)

{
  "hooks": {
     "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/hooks/learning_logger.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write(*.ts)",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\""
          }
        ]
      }
    ]
  }
}