Claude Code 내용 정리

요즘 팀 내에서도 Claude Code를 본격적으로 쓰기 시작했는데요. 처음에는 그냥 "터미널에서 쓰는 Claude" 정도로 가볍게 접근했다가, 쓰면 쓸수록 "어떻게 셋팅해두느냐에 따라 결과물이 완전히 달라진다"는 걸 체감하게 되었습니다.

이번 글에서는 Claude Code의 기본 구조와 설정 계층부터 한 번 정리해보려고 합니다. CLAUDE.md가 어떤 역할을 하는지, User 설정과 Project 설정이 어떻게 다른지, 그 외에 알아두면 좋은 기본기들을 모아봤습니다.

Claude Code란?

Claude Code는 Anthropic에서 제공하는 터미널 기반 AI 코딩 에이전트입니다. 단순히 채팅 인터페이스가 아니라, 실제 파일을 읽고 쓰고, 명령어를 실행하고, git을 다루고, 외부 도구까지 호출할 수 있는 실행형 에이전트입니다.

기본 사용 흐름은 다음과 같습니다.

1. 사용자가 자연어로 작업을 요청
2. Claude가 필요한 도구(Read/Edit/Bash/WebFetch 등)를 호출하며 실제 작업 수행
3. 결과를 보고하고 다음 지시를 받음

여기까지만 보면 다른 AI 코딩 도구와 큰 차이가 없어 보일 수 있는데요. Claude Code의 진짜 강점은 사용자가 셋팅해둔 컨텍스트와 설정을 기반으로 일관되게 동작한다는 점입니다. 그 셋팅의 출발점이 바로 CLAUDE.md 와 설정 계층입니다.

설정 계층 — User vs Project

Claude Code의 설정은 크게 두 계층으로 나뉩니다.

User 레벨 — 모든 프로젝트에 공통 적용

• 위치: ~/.claude/
• 주요 파일:
  • ~/.claude/CLAUDE.md — 모든 프로젝트에 공통으로 적용되는 지시사항
  • ~/.claude/settings.json — 권한, 훅, 환경변수 등 전역 설정

언제 쓰는가: 어떤 프로젝트에서든 일관되게 적용하고 싶은 작업 방식을 정의할 때. 예를 들어 "커밋 메시지는 한국어로 써줘", "테스트 작성 시에는 Given-When-Then 구조를 따라줘" 같은 개인 작업 스타일이 여기 들어갑니다.

Project 레벨 — 해당 프로젝트에만 적용

• 위치: <repo-root>/
• 주요 파일:
  • <repo-root>/CLAUDE.md — 해당 프로젝트의 컨벤션·아키텍처·도메인 지식
  • <repo-root>/.claude/settings.json — 프로젝트별 권한·훅 설정

언제 쓰는가: 그 프로젝트에서만 의미 있는 정보를 담을 때. "이 레포는 헥사고날 아키텍처를 따른다", "도메인 객체는 domain/ 하위에 둔다", "테스트는 JUnit5 + AssertJ 조합을 쓴다" 같은 컨벤션이 여기 들어갑니다.

두 계층의 합쳐짐

Claude Code가 실행되면 User CLAUDE.md → Project CLAUDE.md 순서로 컨텍스트에 주입됩니다. 즉 두 파일 다 읽히되, 프로젝트별 정보가 개인 설정 위에 얹히는 형태입니다.

설정 파일(settings.json)은 좀 더 단순한데, Project 설정이 User 설정을 덮어쓰는 머지 룰을 따릅니다. 권한이나 훅을 프로젝트별로 다르게 두고 싶을 때 이 우선순위를 활용할 수 있습니다.

CLAUDE.md의 역할

CLAUDE.md는 Claude Code 셋팅에서 가장 중요한 파일입니다. 이 파일의 내용은 Claude의 시스템 프롬프트에 주입되어, 매 대화의 가장 윗 컨텍스트로 들어갑니다. 즉 Claude가 작업을 시작하기 전에 가장 먼저 읽는 글이 됩니다.

무엇을 적는가

크게 세 가지 부류로 정리할 수 있습니다.

• 컨벤션·규칙: 코드 스타일, 네이밍, 디렉토리 구조, 테스트 방식 등 "이 환경에서 일할 때 지켜야 할 것"
• 자주 쓰는 작업 흐름: "Jira 티켓을 받으면 어떤 순서로 처리한다", "PR을 만들기 전에 어떤 검증을 거친다" 같은 워크플로우
• 금지 사항·주의 사항: "절대 main 브랜치에 직접 푸시하지 말 것", "특정 디렉토리는 건드리지 말 것" 등

작성할 때 신경 써야 할 점

처음 CLAUDE.md를 쓸 때 흔히 하는 실수가 "문서처럼 길게 쓰는 것" 입니다. 매 대화마다 시스템 프롬프트로 들어간다는 사실을 잊으면, 어느새 토큰을 잡아먹는 거대한 파일이 되어버립니다. 다음 원칙들을 지키면 좋습니다.

• 명령형 어투: 설명조보다 "~한다", "~하지 않는다" 같은 짧은 명령형
• 불릿 위주: 긴 문단보다 글머리 기호로 끊어서 가독성 확보
• 상황별 매핑: "X 요청이 들어오면 → Y 작업을 한다" 형태로 구조화
• 너무 길지 않게: 정말 자주 쓰이는 규칙만 남기고, 상세 가이드는 별도 문서로 빼서 링크

제 User CLAUDE.md 예시

참고용으로 제가 쓰던 초창기 User CLAUDE.md 구조를 일부 공유합니다 (Skill·Subagent를 도입하기 전 시점입니다).

# Claude Code 글로벌 설정

## 작업별 자동 매핑

사용자가 작업을 요청하면 아래 규칙에 따라 자동으로 적절한 흐름을 따릅니다.

- 코드 리뷰 요청 → 변경 diff를 받아 심각도별 리포트 생성
- 커밋 & 푸시 → 컨벤션에 맞춘 메시지 작성 후 푸시
- 빌드 에러(ClassNotFoundException) → 캐시 초기화 후 재빌드

## 커뮤니케이션 규칙
- 응답은 한국어로
- 코드 변경 전 변경 계획을 요약하여 사용자 승인 받기
- 작업 완료 후 수정한 파일 목록과 변경 의도를 정리해 보고

이런 식으로 "무슨 요청이 들어오면 → 무슨 흐름을 따른다" 를 명시해두면, 매번 같은 프롬프트를 입력하지 않아도 일관된 동작을 기대할 수 있습니다. 나중에 이 매핑들이 점점 늘어나고 패턴화되면서 자연스럽게 Skill로 분리하는 단계로 넘어가게 됩니다.

그 외 기본 구조

CLAUDE.md 외에도 알아두면 좋은 디렉토리·파일들이 있습니다. 처음에는 다 쓸 필요는 없지만, "이런 게 있다"는 위치 정도만 알아두면 나중에 셋팅 영역을 넓힐 때 도움이 됩니다.

~/.claude/ 디렉토리 구조

~/.claude/
├── CLAUDE.md          # 전역 지시사항
├── settings.json      # 권한·훅·환경변수
├── skills/            # 재사용 가능한 워크플로우 단위
├── agents/            # 독립 컨텍스트로 동작하는 Subagent
├── commands/          # 사용자 정의 슬래시 커맨드
└── plugins/           # 외부 플러그인 (MCP 서버 등 포함)

각각의 역할을 짧게 정리하면 다음과 같습니다.

• skills/: 자주 쓰는 작업 흐름을 /<skill-name> 으로 호출 가능한 단위로 정의
• agents/: 독립된 컨텍스트와 도구 권한을 가진 별도 Claude 인스턴스 정의
• commands/: 슬래시 커맨드 형태의 단축 명령
• plugins/: 외부에서 가져온 도구 묶음

settings.json — 권한·훅·환경변수

settings.json은 Claude Code의 동작 자체를 제어합니다. 주로 다루는 항목은 세 가지입니다.

• permissions: 어떤 도구를 자동 허용할지 / 매번 확인할지 / 차단할지
• hooks: 특정 이벤트(도구 호출 전·후, 응답 종료 후 등) 시점에 실행할 셸 스크립트
• env: 세션 동안 적용할 환경변수

처음에는 굳이 건드리지 않아도 동작에는 문제가 없지만, 자주 쓰는 명령(예: git status, ls)을 매번 확인받는 게 번거로워질 때 권한 설정부터 손대게 됩니다.

MCP — 외부 도구 연동 표준

MCP(Model Context Protocol)는 Claude Code가 외부 시스템의 도구를 호출할 수 있게 해주는 표준입니다. Jira, Confluence, GitHub, Datadog, Slack, 사내 DB 등을 MCP 서버로 붙이면, Claude가 이 시스템들의 데이터를 직접 읽고 쓸 수 있게 됩니다.

처음 셋팅할 때 모두 붙일 필요는 없고, 자주 쓰는 외부 도구가 있을 때 하나씩 추가하는 식으로 늘려가면 됩니다. 예를 들어 Jira 티켓을 자주 다룬다면 Atlassian MCP 서버를 가장 먼저 붙이게 됩니다.

Memory — 대화 간 컨텍스트 유지

Claude Code에는 자동 메모리 기능이 있어, 대화에서 학습한 사용자 선호·작업 방식·프로젝트 정보를 디스크에 파일 형태로 저장해두고 다음 대화에서도 이어 쓸 수 있습니다. 위치는 ~/.claude/projects/<프로젝트별-경로>/memory/ 입니다.

CLAUDE.md가 "사용자가 명시적으로 지시한 규칙"이라면, Memory는 "Claude가 대화에서 자연스럽게 학습한 정보"에 가깝습니다. 둘 다 컨텍스트 주입의 통로이지만, 편집 주체와 갱신 빈도가 다릅니다.

후기

이번 글에서는 Claude Code의 기본 구조와 설정 계층만 정리했습니다. 정리해보고 나니, 결국 Claude Code 셋팅의 핵심은 "Claude가 매번 어떤 컨텍스트를 가지고 시작하느냐" 를 설계하는 일이라는 생각이 듭니다. 그 출발점이 CLAUDE.md 이고, 그 위에 Skill, Subagent, MCP 같은 기능들이 얹히는 구조입니다.

긴 글 읽어주셔서 감사합니다.