Claude Config Patterns

Claude Config Patterns

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

식별 기준

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

타입 구분 플로우차트

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 가이드

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 패턴 가이드

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 명령, 스크립트

추가 위치 가이드

작성 스타일

• 간결하게 (한 항목당 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 명시적 참조)