claude.md 와 skills

개요

claude code 를 사용해서 많은 코딩을 진행하고 있지만 사람마다 claude를 사용하는 방식이 다르고 이에 따라 많은 차이가 나는 상황입니다. Claude Code 를 사용하기 위해서 중요한 개념인 claude.md 와 claude skills 를 정리하고, 실제 프로젝트에서 적용한 예시를 정리하기 위해서 이 글을 작성하게 되었습니다.

1. Claude.md 란?

claude.md 는 claude code 가 세션을 시작할 때 자동으로 읽는 안내 파일입니다. 매 세션이 시작될 때 이 파일을 읽고, 프로젝트의 규칙과 맥락을 이해한 상태에서 작업을 시작하게 됩니다.

claude.md 의 위치

claude.md 는 여러 위치에 놓을 수 있으면, 위치에 따라서 순서대로 로드됩니다.

1. - ./.claude/claude.md : 모든 프로젝트에서 공통으로 적용되는 설정입니다.
2. - ~root/claude.md : 해당 프로젝트 전체에 적용되는 설정입니다.
3. - /폴더/claude.md : 해당 폴더 작업 시 적용되는 설정입니다.

또한 claude.md 는 세션 시작 시 한 번만 읽힙니다. 따라서 세션 도중에 수정해도 현재 세션에는 적용되지 않습니다. 또한 읽힌 claude.md 내용은 대화가 끝날 때까지 컨텍스트 윈도우에 항상 존재하게 됩니다. 이 이유로 claude.md 를 간결하게 유지해야 효율적으로 사용 가능합니다.

claude.md 에 적어야 하는 것

claude.md 에는 claude 가 작업할 때 알아야 하는 모든 규칙, 구조, 정책 등을 적습니다. 저는 아래의 형태대로 작성하고 있습니다.

markdown
## 프로젝트 개요

- 프로젝트 내용, 장르 및 전체적인 개요를 작성합니다.

## 프로젝트 목표

- 이번 프로젝트에서 달성해야하는 목표와 요구사항을 작성합니다.

## 디렉토리 구조 및 아키텍쳐 환경

- 기본적인 폴더 구조, 상태관리 도구, 사용할 라이브러리 등을 작성합니다.

## 작업 규칙

- 작업을 진행할 때 필요한 규칙들을 작성합니다.
- 코딩 계획 규칙, 토큰 절약 규칙 등을 작성합니다.

## 코딩 표준

- 코딩 시 네이밍 규칙, 코드 스타일, 코드 패턴 등의 규칙을 작성합니다.

## 스킬 목록

- 하위 스킬들을 작성해 어떤 스킬들이 존재하는지 정리합니다.

claude.md 는 최대한 구체적으로 작성하고, 예시를 포함해서 작성하는게 효과적입니다. 또한 처음부터 100%로 작성하는게 아니라, 작업하면서 하나씩 추가/삭제하면서 완성하는게 중요합니다.

2. Claude Skills

claude.md 가 전체에 적용되는 규칙이라면, skills 는 상황별로 적용되는 규칙입니다. claude.md 와 다르게 항상 로드되는 것이 아니라 필요한 상황에 claude 가 작업 맥락을 보고 자동으로 로드하거나, 사용자가 직접 호출할 수 있습니다.

skills 동작 방법

세션이 시작되면 claude 는 ./.claude/skills/ 폴더 내부를 보고 어떤 스킬들이 있는지 이름과 description 만 파악합니다. 스킬 본문을 전부 읽지는 않습니다.

그러다가 작업 중 skills 가 필요한 순간이 오면, description 을 읽고 현재 작업에 필요한 skills 를 로드합니다. 또한 user-invocate: true 로 설정이 되어있는 스킬은 사용자가 직접 호출할 수 있습니다. claude 가 자동으로 인식하지 못하는 상황에 강제로 호출할 수 있습니다.

위와 같은 특성 덕분에 claude.md 에 모든 것을 기록하는 것이 아닌, skills 로 분리해서 정리한다면 토큰도 절약할 뿐만 아니라 작업을 상세하고 빠르게 처리할 수 있습니다.

skills 구조

skill.md 파일은 claude 가 읽는 메타데이터와 상세한 내용이 담긴 본문으로 구성됩니다.

markdown
---
name: 각 스킬의 이름을 작성합니다.
description: 이 스킬이 호출되어 작업할 때 따르는 규칙을 작성합니다.
user-invocable: 유저가 강제로 호출할 수 있는지를 true/false 로 작성합니다.
---

# 본문

- 작업 시 사용하는 규칙이나 워크플로우를 작성합니다.

위처럼 claude 는 skills 를 특정한 상황에만 호출해 사용하기 때문에 본문을 상세하게 작성하는 것이 중요할 뿐만 아니라, description 을 보고 자동으로 로드할 지 여부를 판단하기 때문에 description 작성이 상당히 중요합니다.