Claude Config Patterns

.claude/ 디렉토리 내 파일 작성 시 따라야 할 패턴과 템플릿입니다.

---

식별 기준

대화에서 추출할 내용의 타입을 결정하는 기준입니다.

타입	식별 기준	예시
Agent	여러 단계로 구성된 자동화 작업, 특정 도구 조합이 필요한 워크플로우	"프로젝트 초기화", "배포 파이프라인"
Skill	필요시 참조하는 패턴, 템플릿, 도메인 지식	"API 에러 처리 패턴", "TechSpec 작성 템플릿"
Command	사용자가 자주 요청하는 작업, 인자를 받아 실행되는 반복 작업	"/deploy", "/test-coverage"
Rules	세션 시작 시 자동 로드되어야 하는 프로젝트 지침/정책	"보안 규칙", "코딩 스타일", "테스트 컨벤션"
CLAUDE.md	프로젝트 개요, 구조, 주요 명령어	"환경변수 추가", "디렉토리 구조"

타입 구분 플로우차트

Q: 도구(Read, Write, Bash 등)를 사용해야 하는가?
├─ Yes → Q: 사용자가 직접 호출하는가?
│         ├─ Yes → Command
│         └─ No → Agent
└─ No → Q: 세션 시작 시 자동 로드되어야 하는가?
          ├─ Yes → Rules (프로젝트 지침, 자동 로드)
          └─ No → Q: 명시적 호출 시에만 참조되는가?
                    ├─ Yes → Skill (재사용 패턴/컨벤션)
                    └─ No → CLAUDE.md (프로젝트 개요)

Rules vs Skills 선택 기준:

• Rules: 항상 적용되어야 하는 지침 (보안, 코딩 스타일, 테스트 규칙)
• Skills: 필요할 때만 참조하는 패턴 (템플릿, 워크플로우, 도메인 지식)

---

디렉토리 구조

.claude/
├── agents/           # 자동화 워크플로우 실행자
│   └── {name}.md
├── skills/           # 재사용 패턴 및 규칙 (명시적 참조)
│   └── {name}/
│       └── SKILL.md
├── commands/         # 사용자 명령어 (진입점)
│   └── {name}.md 또는 {category}/{name}.md
└── rules/            # 프로젝트 지침/정책 (자동 로드)
    ├── {name}.md
    └── {category}/   # 하위 디렉토리 지원
        └── {name}.md

---

Agent 템플릿

위치: .claude/agents/{name}.md

용도: 특정 도구를 사용해 자동화 작업을 수행하는 실행자

---
name: {agent-name}
description: {한 줄 역할 설명}
allowed-tools:        # 선택사항
  - Read
  - Write
  - Bash
---

# {Agent Name}

{상세 설명}

## Prerequisites
- 필요한 스킬: `{skill-name}`
- 필요한 환경: {환경 요구사항}

## Workflow

### Phase 1: {단계명}
{단계 설명}

### Phase 2: {단계명}
{단계 설명}

## Error Handling
- {에러 상황}: {대응 방법}

## Example
{사용 예시}

Agent Tools 가이드

도구	용도	예시
Read	파일 읽기	스크립트, 설정 파일 읽기
Write	파일 생성	JSON, 설정 파일 생성
Edit	파일 수정	기존 파일 일부 수정
Bash	명령 실행	npm, npx, 시스템 명령
Glob	파일 검색	패턴으로 파일 찾기
Task	서브에이전트 위임	다른 에이전트 호출
WebFetch	웹 요청	API 호출, 문서 조회
AskUserQuestion	사용자 입력	확인, 선택 요청

Agent 네이밍 규칙

• kebab-case 사용: script-writer, audio-generator
• 역할을 명확히 표현: {동작}-{대상} 패턴
• 짧고 명확하게: 2-3 단어

---

Skill 템플릿

위치: .claude/skills/{name}/SKILL.md

용도: 필요시 참조하는 문서 (규칙, 패턴, 예제, 템플릿)

---
name: {skill-name}
description: {한 줄 설명}
globs:                # 선택사항: 파일 패턴에 따라 자동 활성화
  - "{glob-pattern-1}"
  - "{glob-pattern-2}"
---

# {Skill Name}

{개요 설명}

## 핵심 규칙

### 규칙 1: {규칙명}
{규칙 설명}

```{lang}
// ✅ 올바른 예시
{good example}

// ❌ 잘못된 예시
{bad example}

템플릿/스키마

{재사용 가능한 코드/구조}

흔한 실수와 해결책

문제	원인	해결
{문제}	{원인}	{해결책}

### Globs 패턴 가이드

| 패턴 | 매칭 대상 |
|------|-----------|
| `**/*.ts` | 모든 TypeScript 파일 |
| `src/**` | src 디렉토리 내 모든 파일 |
| `.claude/agents/**` | 에이전트 파일들 |
| `**/test*/**` | test가 포함된 경로 |

### Skill 네이밍 규칙

- kebab-case 사용: `remotion-patterns`, `api-error-handling`
- `{도메인}-{타입}` 패턴 권장: `video-script-rules`
- 디렉토리명 = name 필드값

---

## Command 템플릿

**위치:** `.claude/commands/{name}.md` 또는 `.claude/commands/{category}/{name}.md`

**용도:** 사용자가 `/name` 또는 `/{category}/{name}`으로 호출하는 진입점

```yaml
---
name: {command-name 또는 category/command-name}
description: {사용자에게 보여지는 설명}
arguments:
  - name: {arg-name}
    description: {인자 설명}
    required: true|false
    default: {기본값 (optional)}
allowed-tools:
  - {사용할 도구 목록}
---

# {Command Name}

{명령어 개요}

## Input
- `$ARGUMENTS.{arg-name}`: {설명}

## Execution Flow

### 1. {단계명}
{단계 설명}

### 2. {단계명}
{단계 설명}

## Example

/command-name --arg1 "value1" --arg2 value2

Command 네이밍 규칙

• 단일 단어 또는 카테고리/이름: wrap, video/generate
• 동사로 시작: generate, render, validate
• 사용자 관점에서 직관적으로

---

Rules 템플릿

위치: .claude/rules/{name}.md (하위 디렉토리 지원)

용도: 세션 시작 시 자동 로드되는 프로젝트 지침, 코딩 컨벤션, 정책

로딩: 모든 .md 파일이 .claude/CLAUDE.md와 동일한 우선순위로 자동 로드됨

무조건 적용 규칙

Frontmatter 없이 작성하면 모든 파일 작업에 적용됩니다:

# Security Rules

## 시크릿 관리
- 환경변수 사용 필수
- .env 파일 gitignore 확인
- 하드코딩된 API 키 금지

## 인증/인가
- JWT 토큰 만료 시간 설정
- 민감한 엔드포인트에 인증 필수

조건부 적용 규칙

paths frontmatter로 특정 파일 패턴에만 적용할 수 있습니다:

참고: Skill의 globs와 동일한 glob 패턴 문법을 사용하지만, Rules에서는 paths라는 키를 사용합니다.

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

# API Development Rules

- 모든 API 엔드포인트에 입력 검증 필수
- 표준 에러 응답 형식 사용
- OpenAPI 문서 주석 포함

Paths 패턴 가이드

패턴	매칭 대상
**/*.ts	모든 디렉토리의 TypeScript 파일
src/**/*	src 디렉토리 하위 모든 파일
*.md	프로젝트 루트의 마크다운 파일
src/**/*.{ts,tsx}	src 하위 ts/tsx 파일 (brace expansion)
{src,lib}/**/*.ts	src 또는 lib 하위 ts 파일

Rules 네이밍 규칙

• 단일 단어 또는 kebab-case: security.md, code-style.md
• 도메인/주제 명확히: testing.md, api-design.md
• 하위 디렉토리 활용: frontend/react.md, backend/api.md

Rules 예시 구조

.claude/rules/
├── security.md           # 보안 정책
├── code-style.md         # 코딩 스타일
├── testing.md            # 테스트 컨벤션
├── git-workflow.md       # Git 워크플로우
├── frontend/
│   ├── react.md          # React 컨벤션
│   └── styles.md         # 스타일링 규칙
└── backend/
    ├── api.md            # API 설계
    └── database.md       # DB 규칙

---

CLAUDE.md 업데이트 가이드

위치: 프로젝트 루트 CLAUDE.md

용도: 프로젝트 컨텍스트, 제약사항, 규칙

추가할 내용 유형

1. 프로젝트 구조 - 새 디렉토리, 파일 구조
2. 환경 변수 - 새 API 키, 설정값
3. 핵심 패턴 - 반드시 따라야 할 규칙
4. 명령어 - 새 CLI 명령, 스크립트

추가 위치 가이드

내용 유형	추가 위치
디렉토리 구조	## 저장소 구조 섹션
CLI 명령어	## 주요 명령어 섹션
API 사용 규칙	## 핵심 패턴 섹션
환경 변수	## 환경 변수 섹션

작성 스타일

• 간결하게 (한 항목당 1-2줄)
• 코드 예시 포함
• ✅/❌ 로 올바른/잘못된 예시 구분

---

체크리스트

Agent 생성 시

• name이 kebab-case인가?
• allowed-tools에 필요한 도구만 포함했는가? (선택사항)
• Workflow가 단계별로 명확한가?
• Error Handling이 있는가?

Skill 생성 시

• globs가 정확한 패턴인가? (선택사항: 자동 활성화가 필요한 경우만)
• 규칙에 ✅/❌ 예시가 있는가?
• 흔한 실수 섹션이 있는가?

Command 생성 시

• arguments가 명확히 정의되었는가?
• allowed-tools가 최소한인가?
• Example이 있는가?

Rules 생성 시

• 파일명이 kebab-case인가?
• 한 파일에 하나의 주제만 다루는가?
• 조건부 규칙인 경우 paths 패턴이 정확한가?
• 명확한 섹션 구분이 있는가?
• Rules vs Skills 구분이 적절한가? (자동 로드 vs 명시적 참조)