클로드 코드 사용법: 왜 또 설명해야 할까? CLAUDE.md·스킬 설정

클로드 코드(Claude Code) 사용법의 핵심은 지침과 반복 작업을 분리하는 것이에요.
CLAUDE.md 작성법부터 스킬(Skills), 훅(Hooks), 서브에이전트 설정,
공통 설정과 자동 메모리 관리까지 예제와 함께 정리했어요.

 

클로드 코드에 분명히 설명했는데,
다음 작업에서는 다시 같은 이야기를 하고 계신가요?

기능을 추가해 달라고 했더니 관계없는 파일까지 바꾸거나,
설정 파일이 길어져서 어디부터 손봐야 할지 막막할 때도 있죠.

 

이럴 때는 프롬프트를 더 길게 쓰는 것보다
항상 알아야 하는 내용과, 필요할 때만 꺼내 볼 내용을 나누는 것부터 시작하면 좋아요.

이번에는 클로드 코드 공식 문서와 함께 기본 설정부터 작업 방법까지 정리해 봤어요.
(처음부터 모든 기능을 설정할 필요는 없어요.)

Claude Code 공식 소개 페이지의 데스크톱 앱 데모 화면
출처: Claude Code 공식 사이트

목차

1. 클로드 코드 사용법, 프롬프트보다 기본 설정부터
2. CLAUDE.md 작성법: 프로젝트 지침과 실행 명령 정리
3. Rules·Skills·Hooks·Agents 차이와 설정 예제
4. 클로드 코드 공통 설정과 자동 메모리 관리
5. 실전 프롬프트: 계획 → 코드 수정 → 테스트
6. 초보자를 위한 클로드 코드 설정 체크리스트
7. 자주 묻는 질문: 지침·스킬·훅 설정
8. 총평과 공식 자료

1. 클로드 코드 사용법, 프롬프트보다 기본 설정부터

클로드 코드는 코드에 관해 답변만 하는 도구가 아니에요.
프로젝트 파일을 읽고, 코드를 수정하고,
명령어를 실행해 테스트하는 작업까지 할 수 있어요.

그만큼 “알아서 잘 만들어줘”보다는
무엇을 바꾸고, 무엇은 건드리지 말고,
어떤 상태가 되면 완료인지를 알려주는 게 중요해요.

 

또 하나 알아둘 단어가 컨텍스트예요.
쉽게 말하면 클로드가 지금 펼쳐 놓고 참고하는 작업 책상이라고 보면 돼요.
여기에 불필요한 규칙과 긴 로그가 계속 쌓이면 정작 필요한 내용을 찾기 어려워지겠죠.

2. CLAUDE.md 작성법: 프로젝트 지침과 실행 명령 정리

CLAUDE.md는 프로젝트의 기본 안내문이라고 생각하면 돼요.
무슨 프로젝트인지, 어떤 명령으로 실행하는지,
매번 지켜야 할 중요한 약속을 적는 파일이에요.

공식 문서는 CLAUDE.md 파일당 200줄 미만을 목표로 권장해요.
200줄이 넘으면 실행이 안 된다는 뜻은 아니고,
불필요하게 길어지지 않도록 관리하라는 의미에 가까워요.

처음에는 프로젝트 폴더에서 /init으로 초안을 만들고,
실제 프로젝트와 맞지 않는 내용은 직접 정리하면 돼요.
아래는 구성을 보여주기 위한 예시예요.

# 프로젝트 개요
여행 일정을 정리하는 웹 서비스입니다.

# 기본 명령어
- 개발 실행: npm run dev
- 테스트: npm test
- 빌드: npm run build

# 작업 원칙
- 기존 화면 디자인과 공개 API를 유지합니다.
- 요청과 관계없는 파일은 수정하지 않습니다.
- 변경 후 실행한 테스트와 결과를 알려줍니다.
- 테스트하지 못했다면 이유를 명확히 적습니다.

(위 명령어는 예시예요.
실제 프로젝트의 package.json과 실행 환경에 맞춰 바꿔주세요.)

배포 절차 30단계나 특정 폴더에서만 필요한 규칙까지
모두 여기에 넣을 필요는 없어요.
매번 필요한 사실만 남기고, 나머지는 역할별로 나누는 게 핵심이에요.

3. Rules·Skills·Hooks·Agents 차이와 설정 예제

이름은 조금 복잡해 보이지만, 역할로 보면 생각보다 단순해요.

CLAUDE.md  → 늘 읽는 기본 안내문
rules      → 특정 작업에 적용할 규칙
skills     → 필요할 때 꺼내는 작업 설명서
hooks      → 특정 시점에 실행하는 검사·자동화
agents     → 별도 작업을 맡기는 담당자

① Rules: 해당 파일에 필요한 규칙만

API 규칙과 화면 디자인 규칙을 한곳에 섞지 말고,
.claude/rules/ 안에 주제별 파일로 나눠보세요.

예를 들어 .claude/rules/api.md는 이렇게 만들 수 있어요.

---
paths:
  - "src/api/**/*.ts"
---

# API 작성 규칙
- 입력값을 검증합니다.
- 기존 오류 응답 형식을 유지합니다.
- 변경한 동작을 확인하는 테스트를 추가합니다.

위의 paths는 규칙을 적용할 파일 범위를 뜻해요.
이렇게 지정하면 해당 패턴에 맞는 파일을 읽을 때 규칙이 로드돼요.
paths 없이 파일만 나누면 시작할 때 함께 읽힐 수 있어요.
단순히 파일 개수만 늘리는 것과는 달라요.

② Skills: 반복하는 절차를 설명서로

“변경 내용을 검토해줘”, “릴리스 노트를 정리해줘”처럼
자주 반복하는 절차는 스킬로 만들면 편해요.

스킬은 평소에는 이름과 설명 같은 정보로 발견하고,
사용할 때 상세한 SKILL.md 본문을 읽는 방식이에요.
긴 절차를 항상 CLAUDE.md에 올려둘 필요가 줄어들어요.

.claude/skills/review-change/SKILL.md 예시예요.

---
name: review-change
description: 변경한 코드를 검토하고 테스트 누락과 위험 요소를 정리합니다.
---

1. git diff로 변경 범위를 확인합니다.
2. 오류 가능성과 누락된 테스트를 찾습니다.
3. 파일 위치와 이유를 함께 설명합니다.
4. 코드를 수정하지 말고 검토 결과만 알려줍니다.

이렇게 만든 스킬은 /review-change로 불러 쓸 수 있어요.
처음에는 배포 자동화보다 이런 읽기 중심의 검토 스킬로 시작하는 걸 추천해요.

③ Hooks: 부탁이 아니라 실행 단계에서 검사

“중요한 파일은 수정하지 마”라고 적는 것과,
수정하려는 순간 검사해 막는 것은 다른 이야기예요.
Hooks는 정해진 이벤트가 발생할 때 실행되는 자동화 장치예요.

예를 들어 PreToolUse 훅은 도구 실행 전에 검사하고,
조건에 맞는 호출을 차단하도록 구성할 수 있어요.

다만 .claude/hooks/ 폴더를 만드는 것만으로 작동하지는 않아요.
이 폴더는 스크립트를 보관하는 위치로 사용할 수 있고,
settings.json의 hooks 설정에 이벤트와 실행 명령을 연결해야 해요.

또 Edit·Write만 검사하도록 만들었다면,
Bash 명령을 통한 파일 수정까지 자동으로 막아주는 것은 아니에요.
훅이 모든 위험을 막는 만능 보안 장치라고 생각하기보다는,
실제 사용하는 도구와 우회 경로까지 확인해 두는 게 좋아요.

④ Agents: 긴 조사는 별도 담당자에게

테스트 로그를 길게 읽거나 여러 파일을 조사하는 일은
서브에이전트에게 따로 맡길 수 있어요.
서브에이전트는 자기 컨텍스트에서 작업하고 결과를 메인 대화로 돌려줘요.

프로젝트용 정의는 .claude/agents/에서 관리할 수 있어요.
처음에는 여러 에이전트에게 동시에 코드를 바꾸게 하기보다,
한쪽은 조사, 한쪽은 검토처럼 역할을 분리하는 편이 덜 복잡해요.

테스트 실패 원인을 서브에이전트로 조사해줘.
코드는 수정하지 말고, 원인 후보와 관련 파일,
확인한 근거를 요약해서 알려줘.

4. 클로드 코드 공통 설정과 자동 메모리 관리

프로젝트를 새로 만들 때마다 똑같은 설정을 복사하고 있다면,
개인 공통 설정과 프로젝트 설정을 나눠보세요.

~/.claude/CLAUDE.md
  → 모든 프로젝트에서 사용할 개인 지침

~/.claude/settings.json
  → 개인 공통 권한·훅 등의 설정

~/.claude/skills/
  → 여러 프로젝트에서 재사용할 개인 스킬

프로젝트/CLAUDE.md
  → 이 프로젝트만의 안내문

프로젝트/.claude/
  → 프로젝트 전용 rules·skills·agents·settings

여기서 ~는 사용자 홈 폴더를 뜻해요.
“한국어로 답변”, “변경 이유를 짧게 설명” 같은 개인 취향은 공통 지침에,
실행 명령이나 폴더 구조는 프로젝트 지침에 두면 돼요.

주의할 점도 있어요.
전역과 프로젝트 CLAUDE.md는 함께 문맥에 들어가므로,
충돌하면 무조건 프로젝트 설정이 이긴다고 믿기보다는
애초에 서로 반대되는 지침을 없애는 편이 안전해요.

허용 목록은 넓게 풀지 않기

자주 쓰는 명령은 settings.json의 허용 목록으로 관리할 수 있어요.
다만 일반적인 읽기 전용 Git 명령은 기본적으로 승인이 필요하지 않을 수 있어요.
매번 허용 창이 나온다면 현재 권한 설정과 명령 옵션부터 확인해 보세요.

설정을 추가하더라도 필요한 명령만 좁게 허용하는 게 좋아요.
모든 Bash 명령이나 모든 Git 명령을 한꺼번에 허용하는 식은 피하고요.
파일 삭제, 외부 전송, 실제 배포는 편의성보다 확인 절차가 먼저예요.

Auto memory는 자동으로 적는 작업 메모

CLAUDE.md가 사람이 정한 안내문이라면,
Auto memory는 클로드가 작업 중 배운 내용을 적어두는 메모예요.

기본 저장 위치
~/.claude/projects/<project>/memory/

확인·수정할 때
/memory

이 경로는 소스 프로젝트 안의 memory 폴더와는 달라요.
기본적으로 사용자 홈 아래에 프로젝트별로 저장돼요.
틀린 명령어나 오래된 정보가 남아 있다면 /memory로 열어서 고치거나 지울 수 있어요.

자동으로 기억한다고 해서 항상 정확한 것은 아니에요.
프로젝트 구조나 실행 방법이 크게 바뀌었다면
지침과 메모도 같이 정리해 주세요.

5. 실전 프롬프트: 계획 → 코드 수정 → 테스트

설정을 잘 해두어도 요청 범위가 모호하면 결과를 확인하기 어려워요.
조금 큰 작업이라면 탐색 → 계획 → 작은 수정 → 검증 순서로 진행해 보세요.

1단계: 바로 수정하지 말고 구조부터 확인

로그인 오류를 수정하려고 해.
먼저 관련 파일과 현재 로그인 흐름을 확인해줘.
아직 코드는 수정하지 말고, 원인 후보와 수정 계획을 알려줘.

2단계: 이번에 바꿀 범위를 명확히

확인한 계획 중 로그인 오류 처리 부분만 수정해줘.
기존 화면 디자인과 공개 API 형식은 유지해줘.
관련 없는 리팩터링이나 의존성 추가는 하지 말아줘.

3단계: 완료 기준과 확인 방법까지

수정한 동작을 확인할 테스트를 실행해줘.
변경 파일, 실행한 명령, 성공·실패 결과를 요약해줘.
실행하지 못한 검증은 이유를 알려줘.
실제 배포나 원격 저장소 푸시는 하지 말아줘.

화면 작업이라면 정상 화면뿐 아니라
오류 메시지, 모바일 화면, 빈 데이터 상태도 확인하면 좋아요.
“수정했어요”라는 답변과 “실제로 정상 작동해요”는 다르니까요.

반대로 오타 한두 개를 고치는 일까지 긴 계획을 세울 필요는 없어요.
작업이 클수록 계획과 검증을 꼼꼼히 하는 정도로 생각하면 편해요.

6. 초보자를 위한 클로드 코드 설정 체크리스트

오늘 바로 해볼 최소 설정

1. 프로젝트에서 /init으로 CLAUDE.md 초안 만들기
2. 실행·테스트 명령이 실제로 맞는지 확인하기
3. 매번 필요한 핵심 지침만 짧게 남기기
4. 개인 취향은 ~/.claude/CLAUDE.md로 분리하기
5. 반복하는 검토 절차 하나를 스킬로 만들기
6. 작은 작업 하나를 맡기고 결과를 직접 검증하기

그다음 규칙이 많아지면 Rules,
반드시 검사해야 할 작업이 생기면 Hooks,
긴 조사나 검토가 많아지면 Agents를 추가하면 돼요.
폴더를 전부 채우는 것보다 지금 반복되는 불편 하나를 줄이는 게 먼저예요.

7. 자주 묻는 질문: 지침·스킬·훅 설정

CLAUDE.md는 200줄을 넘으면 안 되나요?

200줄 미만은 권장 분량이지, 그 이상이면 실행되지 않는다는 뜻은 아니에요.
늘 필요한 사실만 남기고, 긴 절차는 스킬로,
특정 파일에 적용할 규칙은 Rules로 나누는 편이 좋아요.

 

클로드 스킬과 훅은 어떻게 다른가요?

스킬은 반복하는 작업의 절차를 필요할 때 읽는 설명서예요.
훅은 도구 실행 전후 같은 이벤트에 연결하는 검사·자동화예요.
지침에 금지 문구를 적는 것과 실행 단계에서 검사하는 것은 달라요.

 

프로젝트마다 같은 설정을 복사해야 하나요?

개인 공통 지침은 ~/.claude/CLAUDE.md,
재사용할 개인 스킬은 ~/.claude/skills/에 둘 수 있어요.
프로젝트의 명령어·구조·팀 규칙은 프로젝트 설정에 남기고,
공통 지침과 충돌하는 내용이 없는지 확인해 주세요.

 

8. 총평과 공식 자료

클로드 코드를 잘 사용하는 방법은
결국 더 많은 일을 한꺼번에 시키는 것만은 아닌 것 같아요.

항상 필요한 정보는 짧게,
반복 절차는 꺼내 쓰기 쉽게,
위험한 작업은 확인 가능하게,
완료한 결과는 검증할 수 있게.

이렇게 나눠두면 같은 설명을 반복하는 수고를 줄일 수 있어요.
다만 규칙이나 메모가 오래되면 오히려 혼란을 줄 수 있고,
확장 도구를 많이 붙일수록 관리할 설정도 늘어나요.

처음에는 CLAUDE.md 한 장과 스킬 하나면 충분해요.
작게 시작해서 자주 쓰는 작업부터 정리해 보세요.

공식 참고 자료

공식 문서: CLAUDE.md·Rules·Auto memory
공식 문서: Skills · Hooks · Subagents
공식 문서: 설정 · 권한 · 권장 사용법

2026년 9월 30일 확인한 공식 자료 기준이에요.
기능과 설정 방식은 버전에 따라 바뀔 수 있어요.
예시 프롬프트와 설정은 이해를 돕기 위한 것이며, 성능·비용 절감 실측 후기는 아니에요.
본문 이미지는 각 공식 사이트의 소개 화면·이미지이며, 권리는 각 권리자에게 있어요.