Claude Code의 확장 기능은 모두 같은 종류의 프롬프트가 아니다. Rules는 지속적으로 적용할 지침, Skills는 반복해서 재사용할 작업 절차, Agents는 별도 컨텍스트에서 일하는 역할별 실행자다. 세 기능을 정확히 구분하면 프롬프트 반복을 줄이면서도 메인 대화의 컨텍스트를 효율적으로 관리할 수 있다.
이 문서는 프로젝트 단위 설정을 기준으로 설명한다. Claude Code 버전에 따라 지원되는 메타데이터나 화면이 달라질 수 있으므로, 동작하지 않는 필드는 설치된 버전의 공식 문서에서 다시 확인해야 한다.
1단계: .claude 디렉터리와 설정 범위 정하기
프로젝트에서 공유할 Rules, Skills, Agents는 일반적으로 저장소 루트의 .claude 아래에 둔다.
my-project/
├── .claude/
│ ├── rules/
│ │ ├── code-style.md
│ │ └── api.md
│ ├── skills/
│ │ └── fix-issue/
│ │ └── SKILL.md
│ └── agents/
│ ├── code-reviewer.md
│ └── test-runner.md
├── src/
└── package.json
디렉터리는 다음과 같이 만들 수 있다.
mkdir -p .claude/rules
mkdir -p .claude/skills/fix-issue
mkdir -p .claude/agents
.claude에 관한 두 가지 오해
-
.claude가 Claude Code의 모든 지침에 반드시 필요한 것은 아니다. 프로젝트 지침은 루트의CLAUDE.md또는.claude/CLAUDE.md로도 관리할 수 있고, 사용자 개인 설정은 홈 디렉터리의~/.claude아래에 둘 수 있다. - 파일명은 운영체제에 따라 대소문자가 구분된다. Skill 진입 파일은 공식 형식에 맞춰 대문자
SKILL.md로 작성하는 것이 안전하다.skill.md로 저장하면 인식되지 않을 수 있다.
프로젝트 설정과 개인 설정의 선택 기준
| 범위 | 적합한 내용 | 예시 |
|---|---|---|
| 프로젝트 공유 | 모든 기여자가 동일하게 따라야 하는 규칙과 자동화 | 테스트 명령, 디렉터리 구조, API 규약 |
| 사용자 개인 | 개인 취향이나 저장소에 공개하면 안 되는 설정 | 개인 작업 방식, 로컬 도구 선택 |
| 로컬 전용 | 특정 컴퓨터에서만 유효한 경로나 실험 설정 | 로컬 데이터 경로, 임시 디버깅 절차 |
팀에서 함께 사용할 파일만 Git에 커밋한다. 비밀 키, 토큰, 내부 서버 비밀번호는 Rules나 Skills에 기록하지 않는다.
2단계: Rules로 지속 지침 만들기
Rules는 Claude가 작업할 때 참고해야 하는 프로젝트 지침을 여러 Markdown 파일로 나누어 관리하는 기능이다. .claude/rules 아래에 있는 규칙 가운데 paths 조건이 없는 파일은 프로젝트 지침으로 로드되며, 경로 조건을 지정한 파일은 관련 파일을 다룰 때 적용된다.
기본 Rule 예제
.claude/rules/code-style.md를 다음처럼 작성할 수 있다.
# 코드 작성 원칙
- 새 애플리케이션 코드는 TypeScript로 작성한다.
- 공개 함수에는 입력값, 반환값, 실패 조건을 설명한다.
- 기존 테스트를 삭제해서 실패를 숨기지 않는다.
- 변경 후 관련 테스트와 타입 검사를 실행한다.
- 설명은 한국어로 작성하되 코드 식별자는 기존 명명 규칙을 따른다.
좋은 Rule은 검증할 수 있다. “코드를 멋지게 작성한다”보다 “변경 후 npm test와 npm run typecheck를 실행한다”가 명확하다.
특정 경로에만 적용하는 Rule
프런트엔드와 백엔드의 규칙이 다르면 YAML front matter의 paths로 범위를 좁힐 수 있다.
---
paths:
- "src/api/**/*.ts"
- "tests/api/**/*.ts"
---
# API 규칙
- 모든 API 입력은 스키마로 검증한다.
- 인증 실패와 권한 부족을 서로 다른 오류로 처리한다.
- 엔드포인트를 변경하면 대응하는 API 테스트도 갱신한다.
경로별 규칙은 불필요한 지침이 모든 작업의 컨텍스트를 차지하는 문제를 줄여준다.
Rules에 넣지 말아야 할 내용
- 한 번만 수행할 마이그레이션 절차
- 특정 이슈에만 필요한 상세 요구사항
- 서로 충돌하는 절대 지시
- 이미 코드나 린터 설정으로 강제되는 내용을 길게 반복한 문장
- 비밀번호, API 키, 고객 정보 등 민감한 데이터
Rules는 “무조건 따르는 마법의 보장 장치”가 아니다. 모호하거나 상충하는 지침이 있으면 결과가 달라질 수 있으므로 테스트, 린터, 권한 통제 같은 결정적 검증 수단을 함께 사용해야 한다.
3단계: Skills로 반복 절차 자동화하기
Skill은 설명, 작업 절차, 필요 도구, 보조 자료를 하나의 재사용 가능한 단위로 묶는다. 프로젝트 Skill의 기본 구조는 .claude/skills/<skill-name>/SKILL.md이며, 필요하면 같은 디렉터리에 템플릿이나 스크립트를 추가할 수 있다.
Rules와 달리 Skill은 특정 작업에 필요할 때 사용된다. Claude가 Skill의 설명을 보고 자동으로 선택할 수도 있고, 사용자가 /<skill-name> 형식으로 명시적으로 호출할 수도 있다. 반드시 수동으로만 작동하는 것은 아니다.
이슈 수정 Skill 예제
.claude/skills/fix-issue/SKILL.md 예시는 다음과 같다.
---
name: fix-issue
description: 버그를 재현하고 원인을 좁힌 뒤 최소 수정과 회귀 테스트를 수행한다.
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Edit, Bash(npm test:*)
---
# 이슈 수정 절차
대상 이슈: $ARGUMENTS
1. 관련 코드와 기존 테스트를 조사한다.
2. 수정 전에 재현 방법과 예상 동작을 정리한다.
3. 근본 원인을 한 문단으로 설명한다.
4. 영향 범위가 가장 작은 수정을 적용한다.
5. 회귀 테스트를 추가하거나 기존 테스트가 문제를 검증하는지 확인한다.
6. 허용된 테스트를 실행하고 결과를 요약한다.
7. 변경 파일, 남은 위험, 수동 확인 항목을 보고한다.
이 Skill은 다음처럼 호출할 수 있다.
/fix-issue 로그인 후 프로필 사진이 갱신되지 않는 문제
disable-model-invocation: true는 Claude가 임의로 이 Skill을 실행하지 않고 사용자가 직접 호출하도록 제한할 때 유용하다. 지원되는 front matter 필드는 Claude Code 버전에 따라 달라질 수 있다.
설계 우선 Skill 예제
바로 코딩하는 대신 설계 문서를 먼저 만들게 하려면 다음 흐름을 Skill에 넣을 수 있다.
- 요구사항과 모호한 부분을 분리한다.
- 기존 구조와 재사용 가능한 모듈을 조사한다.
- 데이터 흐름, 인터페이스, 실패 조건을 설계한다.
-
docs/design/아래에 설계 문서를 작성한다. - 사용자의 승인 또는 명시된 승인 조건을 확인한 후 구현한다.
- 테스트와 롤백 방법을 제시한다.
좋은 Skill의 조건
- 입력과 최종 산출물이 분명하다.
- 절차의 순서와 중단 조건이 명시돼 있다.
- 필요한 도구만 허용한다.
- 긴 참고 자료는 별도 파일로 분리한다.
- 실패했을 때 임의로 계속 진행하지 않고 보고하도록 한다.
- 한 Skill이 지나치게 많은 목적을 갖지 않는다.
커밋 작성, 코드 리뷰, 릴리스 점검, API 설계처럼 반복되면서 시작과 끝이 분명한 작업이 Skill에 적합하다.
