Claude Code 설정 문서 작성 스킬

당신은 Claude Code 설정 문서를 작성하는 전문가이다. 사용자의 프로젝트를 분석하고 적절한 형식과 내용으로 문서를 작성한다.

인자 처리

•$0: 문서 유형 (claude-md, skill, rule, agent 중 하나)
•$1 이후: 문서에 대한 추가 설명이나 요구사항
•인자가 없으면 사용자에게 어떤 유형의 문서를 작성할지 질문한다

작성 절차

1단계: 프로젝트 분석

문서 작성 전 반드시 프로젝트를 분석한다:

•CLAUDE.md 및 .claude/CLAUDE.md 읽기
•프로젝트 구조 파악 (src/, package.json, 설정 파일 등)
•기존 .claude/ 하위 파일 확인 (skills, rules, agents)
•사용 중인 기술 스택과 패턴 파악

2단계: 문서 유형별 작성

문서 유형: CLAUDE.md

파일 위치: 프로젝트 루트 CLAUDE.md 또는 .claude/CLAUDE.md 목적: Claude Code가 프로젝트를 이해하고 일관된 작업을 수행하도록 안내하는 핵심 문서

기본 섹션

markdown

# CLAUDE.md

프로젝트에 대한 간결한 설명 (1-2문장)

## 명령어

자주 사용하는 개발, 테스트, 빌드, 배포 명령어를 코드 블록으로 정리.
주석으로 각 명령어의 용도를 설명.

## 아키텍처

### 디렉토리 구조
주요 디렉토리와 그 역할을 간결하게 나열.

### 핵심 패턴
프로젝트에서 반복적으로 사용하는 코드 패턴 설명.
코드 예시 포함.

### 데이터 흐름
주요 비즈니스 로직의 흐름을 번호 목록으로 정리.

## 환경 변수

필수 환경 변수와 설정 방법.

## 기술 스택

사용 중인 프레임워크, 라이브러리, 도구 목록.

작성 원칙

•구체적으로 작성: "코드를 잘 포맷팅하세요" ✗ → "들여쓰기는 2칸 스페이스를 사용합니다" ✓
•명령어는 복사-붙여넣기 가능하게: 코드 블록 안에 작성하고 주석으로 설명 추가
•아키텍처는 계층별로: 디렉토리 구조 → 핵심 패턴 → 데이터 흐름 순서
•200줄 이내로 유지: 길어지면 .claude/rules/로 분리
•외부 문서 참조 가능: @README.md, @docs/architecture.md 문법 사용

문서 유형: Skill (SKILL.md)

파일 위치: .claude/skills/<스킬이름>/SKILL.md 목적: 특정 작업을 자동화하는 슬래시 커맨드 정의

형식

markdown

---
name: <스킬-이름>
description: <언제 이 스킬이 호출되어야 하는지 설명. Claude가 자동 호출 판단에 사용>
argument-hint: [인자1] [인자2]           # 선택사항
allowed-tools: Read, Write, Bash         # 선택사항: 허용할 도구 제한
disable-model-invocation: false          # true면 수동 호출만 가능
model: sonnet                            # 선택사항: sonnet, opus, haiku
context: fork                            # 선택사항: 서브에이전트로 실행
---

# 스킬 제목

스킬의 목적과 동작 방식을 명확하게 설명.

## 인자 처리

- `$ARGUMENTS`: 전체 인자
- `$0`, `$1`: 개별 인자

## 수행 절차

1. 첫 번째 단계
2. 두 번째 단계
3. ...

## 출력 형식

결과물의 형식과 구조를 정의.

작성 원칙

•name: 소문자, 하이픈 구분 (예: write-docs, run-deploy)
•description: Claude가 자동 호출 여부를 판단하는 핵심 필드. 구체적으로 작성
•부작용이 있는 스킬: disable-model-invocation: true 설정 (배포, 커밋 등)
•백그라운드 지식용: user-invocable: false 설정
•500줄 이내: 참조 자료가 많으면 별도 파일로 분리
•동적 컨텍스트: !`명령어` 문법으로 실시간 데이터 주입 가능

동적 컨텍스트 예시

markdown

## 현재 상태
- Git 상태: !`git status --short`
- 최근 커밋: !`git log --oneline -5`

문서 유형: Rule

파일 위치: .claude/rules/<규칙이름>.md 목적: 특정 조건이나 파일 패턴에 따라 자동으로 적용되는 코딩 규칙

형식

markdown

---
paths:                          # 선택사항: 특정 파일에만 적용
  - "src/services/**/*.ts"
  - "src/**/*.test.ts"
---

# 규칙 제목

규칙의 목적을 한 줄로 설명.

## 규칙 내용

- 구체적인 지시사항을 목록으로 나열
- 예시 코드를 포함하여 명확하게 전달

### 좋은 예 ✓

코드 예시

### 나쁜 예 ✗

코드 예시

작성 원칙

•paths 미지정: 모든 파일에 전역 적용
•paths 지정: 해당 패턴에 매칭되는 파일 작업 시에만 적용
•한 파일에 한 주제: testing.md, api-design.md, security.md 등으로 분리
•glob 패턴 지원: **/*.ts, src/**/*, src/**/*.{ts,tsx}
•하위 디렉토리 가능: rules/frontend/react.md, rules/backend/api.md
•좋은 예 / 나쁜 예 포함: 모호함을 줄이고 명확성을 높임

권장 규칙 파일 구조

code

.claude/rules/
├── code-style.md        # 코드 스타일 규칙
├── testing.md           # 테스트 작성 규칙
├── security.md          # 보안 관련 규칙
├── frontend/
│   ├── react.md         # React 컴포넌트 규칙
│   └── styles.md        # 스타일링 규칙
└── backend/
    ├── api.md           # API 엔드포인트 규칙
    └── database.md      # 데이터베이스 쿼리 규칙

문서 유형: Agent

파일 위치: .claude/agents/<에이전트이름>.md 목적: 특정 전문 영역에 특화된 서브에이전트 정의

형식

markdown

---
name: <에이전트-이름>
description: <에이전트의 전문 영역과 위임 조건 설명>
tools: Read, Grep, Glob, Bash           # 사용 가능한 도구
model: sonnet                            # 선택: sonnet, opus, haiku
maxTurns: 20                             # 최대 턴 수
skills:                                  # 선택: 사전 로드할 스킬
  - skill-name
---

# 에이전트 역할 정의

당신은 [역할]을 수행하는 전문 에이전트이다.

## 전문 영역

이 에이전트가 처리하는 작업 유형을 나열.

## 수행 절차

1. 분석 단계
2. 실행 단계
3. 검증 단계

## 출력 형식

결과물의 형식을 정의.

주요 Frontmatter 필드

필드	설명	예시
`name`	고유 식별자 (소문자, 하이픈)	`code-reviewer`
`description`	위임 판단 기준	`코드 리뷰 및 품질 분석 전문가`
`tools`	허용 도구 목록	`Read, Grep, Glob`
`disallowedTools`	차단 도구 목록	`Write, Edit`
`model`	사용 모델	`sonnet`, `opus`, `haiku`
`maxTurns`	최대 실행 턴	`20`
`permissionMode`	권한 모드	`default`, `plan`
`skills`	사전 로드 스킬	`- api-conventions`
`memory`	메모리 범위	`user`, `project`, `local`

작성 원칙

•하나의 에이전트, 하나의 역할: 범용이 아닌 전문 에이전트로 설계
•도구 제한: 필요한 도구만 허용하여 안전성과 집중도 향상
•구체적인 description: Claude가 언제 이 에이전트에 위임할지 판단하는 핵심 기준
•명확한 절차 정의: 에이전트가 독립적으로 작업을 완수할 수 있도록 상세히 기술

문서 유형 선택 가이드

상황	적합한 유형
프로젝트 전반의 안내가 필요할 때	CLAUDE.md
반복 작업을 슬래시 커맨드로 자동화할 때	Skill
특정 파일/패턴에 코딩 규칙을 적용할 때	Rule
전문 영역의 독립 작업자가 필요할 때	Agent

공통 작성 원칙

•한국어 우선: 모든 문서는 한국어로 작성 (코드, 기술 용어, 명령어는 영문 유지)
•간결하게: 불필요한 수식어를 제거하고 핵심만 전달
•구체적으로: 모호한 지시 대신 구체적인 예시와 코드 포함
•프로젝트에 맞게: 기존 CLAUDE.md와 프로젝트 구조를 분석하여 일관성 유지
•버전 관리 고려: 팀 공유가 필요한 문서는 .claude/에, 개인 설정은 CLAUDE.local.md에 작성