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

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

추가할 내용 유형

프로젝트 구조 - 새 디렉토리, 파일 구조
환경 변수 - 새 API 키, 설정값
핵심 패턴 - 반드시 따라야 할 규칙
명령어 - 새 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 명시적 참조)