출력 스타일 설정

읽는 시간: 8분 | 난이도: 중급자

출력 스타일(Output Styles)은 Claude Code의 핵심 기능—로컬 스크립트 실행, 파일 읽기/쓰기, TODO 추적 등—을 유지하면서 소프트웨어 엔지니어링 이외의 다양한 에이전트로 활용할 수 있게 해주는 기능입니다. 이 가이드에서는 기본 제공 출력 스타일부터 나만의 커스텀 스타일을 만드는 방법까지 상세히 설명합니다.

출력 스타일이란?

출력 스타일은 Claude Code의 시스템 프롬프트를 직접 수정하는 방식으로 동작합니다. 기본 스타일은 소프트웨어 엔지니어링 작업에 최적화되어 있지만, 출력 스타일을 변경하면 Claude Code가 완전히 다른 역할을 수행할 수 있습니다.

예를 들어 코드 튜터, 기술 문서 작성자, 또는 팀 내 도메인 전문가로서 동작하도록 설정할 수 있습니다.

기본 제공 출력 스타일

Claude Code는 세 가지 기본 출력 스타일을 제공합니다.

Default (기본)

소프트웨어 엔지니어링 작업을 효율적으로 완료하도록 설계된 기본 시스템 프롬프트입니다. 대부분의 개발 작업에는 이 스타일을 사용하는 것이 적합합니다.

Explanatory (설명형)

소프트웨어 엔지니어링 작업을 도우면서 중간중간 교육적인 "인사이트(Insights)"를 제공합니다. 이 스타일은 다음과 같은 상황에 유용합니다.

새로운 코드베이스를 처음 파악할 때
특정 구현 선택의 이유를 이해하고 싶을 때
코드베이스의 패턴과 규칙을 배우고 싶을 때

Claude Code는 작업을 진행하면서 "왜 이런 방식을 선택했는지", "이 패턴이 어떤 의미를 갖는지" 등을 자동으로 설명해 줍니다.

Learning (학습형)

협력적인 학습-실습 모드로, 단순히 인사이트를 제공하는 것을 넘어 직접 코드를 작성해 볼 기회를 줍니다.

Claude Code가 구현 중 전략적으로 중요한 코드 조각을 직접 작성하도록 요청합니다.
코드에 TODO(human) 마커를 추가하여 여러분이 구현해야 할 부분을 표시합니다.
단순한 코드 생성이 아닌, 이해와 실력 향상을 목표로 합니다.

def calculate_fibonacci(n: int) -> int:
    # TODO(human): 피보나치 수열을 재귀적으로 구현하세요
    # 힌트: fib(0) = 0, fib(1) = 1, fib(n) = fib(n-1) + fib(n-2)
    pass

출력 스타일 작동 방식

출력 스타일이 시스템 프롬프트에 미치는 영향을 이해하면 더 효과적으로 활용할 수 있습니다.

모든 출력 스타일: 간결한 응답 등 효율적 출력을 위한 기본 지시사항을 제외합니다.
커스텀 출력 스타일: keep-coding-instructions가 true가 아니면 코딩 관련 지시사항(테스트로 코드 검증 등)을 제외합니다.
각 스타일은 시스템 프롬프트 끝에 고유한 커스텀 지시사항을 추가합니다.
대화 중에 Claude가 출력 스타일 지시사항을 지속적으로 따르도록 상기시켜 줍니다.

출력 스타일 변경 방법

출력 스타일을 변경하는 방법은 두 가지입니다.

메뉴에서 선택

/output-style

또는 /config 메뉴에서도 접근할 수 있습니다. 사용 가능한 스타일 목록이 표시되며 선택할 수 있습니다.

직접 지정

/output-style explanatory
/output-style learning
/output-style default

스타일 이름을 인수로 직접 전달하면 즉시 해당 스타일로 전환됩니다.

설정 파일에서 변경

변경 사항은 로컬 프로젝트 수준에 적용되며 .claude/settings.local.json에 저장됩니다. 설정 파일에서 직접 outputStyle 필드를 편집할 수도 있습니다.

{
  "outputStyle": "explanatory"
}

커스텀 출력 스타일 만들기

기본 제공 스타일 외에 나만의 출력 스타일을 만들 수 있습니다. 커스텀 출력 스타일은 frontmatter와 시스템 프롬프트에 추가될 텍스트가 포함된 마크다운 파일입니다.

파일 형식

---
name: My Custom Style
description:
  이 스타일이 하는 일에 대한 간단한 설명 (사용자에게 표시됨)
---

# Custom Style Instructions

You are an interactive CLI tool that helps users with software engineering
tasks. [여기에 커스텀 지시사항을 작성하세요...]

## Specific Behaviors

[이 스타일에서 어시스턴트가 어떻게 동작해야 하는지 정의...]

저장 위치

커스텀 출력 스타일 파일을 저장할 수 있는 위치:

위치	경로	적용 범위
사용자 수준	`~/.claude/output-styles/`	모든 프로젝트
프로젝트 수준	`.claude/output-styles/`	해당 프로젝트만

Frontmatter 옵션

필드	목적	기본값
`name`	파일 이름 대신 사용할 스타일 이름	파일 이름에서 상속
`description`	`/output-style` UI에 표시되는 설명	없음
`keep-coding-instructions`	코딩 관련 시스템 프롬프트 유지 여부	false

커스텀 스타일 예시: 기술 문서 작성자

---
name: Technical Writer
description:
  명확하고 구조화된 기술 문서를 작성하는 데 특화된 스타일
keep-coding-instructions: false
---

# Technical Documentation Style

You are a professional technical writer specialized in developer documentation.
Your primary goal is to produce clear, accurate, and well-structured documentation.

## Writing Principles

- Use precise, unambiguous language
- Structure content with clear headings and subheadings
- Provide concrete examples for all concepts
- Assume technical competence but explain domain-specific concepts
- Use active voice and present tense

## Output Format

- Start with a brief summary paragraph
- Use bullet points for lists of 3+ items
- Include code examples in appropriate language blocks
- End with a "See Also" section linking to related documentation

기능	시스템 프롬프트 영향	적용 범위
출력 스타일	소프트웨어 엔지니어링 관련 부분을 완전히 "끄고" 대체	선택한 스타일로 완전 전환
CLAUDE.md	기본 시스템 프롬프트 이후에 사용자 메시지로 추가	추가적인 컨텍스트 제공
--append-system-prompt	시스템 프롬프트 끝에 내용 추가	기존 프롬프트 유지하며 확장

기능	동작 방식	사용 시점
출력 스타일	선택 후 항상 활성화, 응답 방식(형식, 톤, 구조) 변경	일관된 형식 선호도가 필요할 때
스킬	`/skill-name`으로 호출하거나 관련 시 자동 로드	재사용 가능한 워크플로우와 작업에

실용적인 활용 사례

코드 리뷰 스타일

---
name: Code Reviewer
description: 체계적인 코드 리뷰를 수행하는 스타일
keep-coding-instructions: true
---

코드를 검토할 때는 항상 다음 순서로 분석하세요:
1. 기능적 정확성
2. 성능 고려사항
3. 보안 취약점
4. 코드 가독성 및 유지보수성
5. 테스트 커버리지

각 항목에 대해 구체적인 피드백과 개선 제안을 제공하세요.

데이터 분석 스타일

---
name: Data Analyst
description: 데이터 분석 및 시각화 작업에 특화된 스타일
keep-coding-instructions: false
---

데이터 분석 작업을 수행할 때:
- 먼저 데이터의 구조와 품질을 파악하세요
- 통계적 요약을 제공하세요
- 시각화 코드를 작성할 때 matplotlib 또는 seaborn을 선호하세요
- 발견한 패턴과 이상값을 명확히 설명하세요
- 분석 결과를 비기술적 청중도 이해할 수 있게 요약하세요

다음 단계

출력 스타일을 효과적으로 활용하기 위해 다음 주제도 참고해 보세요.

CLAUDE.md 가이드 - 프로젝트별 컨텍스트 및 지시사항 설정
스킬(Skills) 가이드 - 재사용 가능한 워크플로우 자동화
설정(Settings) 가이드 - Claude Code 전반적인 설정 관리
서브에이전트 가이드 - 특수 목적 에이전트 활용