Claude Code 공식문서 리뷰-Build with Claude Code[5] : Output styles

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> Build with Claude Code 섹션의 내용 중 [Output styles]를 살펴 보려고 합니다.

https://code.claude.com/docs/en/output-styles

Output styles - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다. 

 

30초 요약

1. 시스템 프롬프트

Claude의 응답 방식을
근본적으로 변경

2. 3가지 내장

Default, Explanatory,
Learning 제공

3. 커스텀 가능

STYLE.md 파일로
나만의 스타일 생성

Quick Start: /output-style explanatory

출력 스타일 (Output Styles)

• 정의: Claude Code의 시스템 프롬프트를 수정하여 응답 방식을 변경하는 기능
• 목적: 소프트웨어 엔지니어링 외의 용도로 Claude Code를 적응
• 핵심 특징: 핵심 기능(파일 읽기/쓰기, 스크립트 실행)은 유지하면서 행동만 변경
• 원본: code.claude.com/docs/en/output-styles

 

개요 (Overview)

출력 스타일을 사용하면 Claude Code를 어떤 유형의 에이전트로든 사용할 수 있다. 핵심 기능(로컬 스크립트 실행, 파일 읽기/쓰기, TODO 추적)을 유지하면서 시스템 프롬프트를 수정한다.

핵심 개념
스킬(Skill)은 "이런 상황에서 이렇게 행동해"라고 가르치는 것이고, 출력 스타일(Output Style)은 Claude의 기본 성격 자체를 바꾸는 것이다. 시스템 프롬프트를 직접 수정한다.

출력 스타일이 하는 일

유지하는 것

• 파일 읽기/쓰기
• 스크립트 실행
• TODO 추적
• 도구 사용 능력

변경하는 것

• 응답 스타일
• 설명 상세도
• 코딩 지침 적용 여부
• 커스텀 행동 규칙

 

내장 출력 스타일 (Built-in Styles)

Claude Code는 세 가지 출력 스타일을 제공한다:

Default

효율적인 소프트웨어 엔지니어링 작업을 위해 설계된 기본 시스템 프롬프트

간결한 응답

Explanatory

코딩 작업 사이에 교육적인 "인사이트"를 제공하여 구현 선택과 코드베이스 패턴 이해를 돕는다

초보자 추천

Learning

협업적이고 실습 중심의 모드. 사용자가 직접 코드를 작성하도록 TODO(human) 마커 추가

실습 학습

 

Learning 스타일 특징

• 코딩하면서 "인사이트" 공유
• 작고 전략적인 코드 조각을 사용자가 기여하도록 요청
• 사용자가 구현할 부분에 TODO(human) 마커 추가

초보자 팁
처음 시작할 때는 Explanatory 스타일을 사용하면 Claude가 왜 특정 구현을 선택했는지 설명해주어 학습에 도움이 된다.

 

작동 방식 (How It Works)

출력 스타일은 Claude Code의 시스템 프롬프트를 직접 수정한다:

동작	설명
효율성 지침 제외	모든 출력 스타일은 "간결하게 응답하라"는 효율성 지침을 제외
코딩 지침 제외	keep-coding-instructions가 true가 아니면 테스트 검증 등 코딩 지침 제외
커스텀 지침 추가	스타일 파일의 본문이 시스템 프롬프트에 추가됨
대화 중 리마인더	Claude가 출력 스타일 지침을 준수하도록 자동 리마인더 트리거

 

스타일 변경하기 (Changing Styles)

방법 1: 대화형 메뉴

/output-style

메뉴에서 원하는 스타일을 선택한다. /config에서도 접근 가능하다.

 

방법 2: 직접 전환

/output-style explanatory
/output-style learning
/output-style [custom-style-name]

 

방법 3: 설정 파일 편집

설정 파일에서 outputStyle 필드를 직접 편집할 수 있다:

범위	설정 파일 경로
로컬 프로젝트	.claude/settings.local.json
글로벌	~/.claude/settings.json

{
  "outputStyle": "learning"
}

ex) learning 모드 설정시 생성되는 소스 style

 

 

커스텀 스타일 만들기 (Creating Custom Styles)

디렉토리 구조

스타일 저장 위치

# 개인 스타일 (모든 프로젝트에서 사용)
~/.claude/output-styles/
   └── my-style.md

# 프로젝트 스타일 (git 커밋, 팀 공유)
.claude/output-styles/
   └── team-style.md

 

스타일 파일 형식

---
name: My Custom Style
description: 이 스타일이 무엇을 하는지에 대한 간단한 설명
keep-coding-instructions: false
---

# Custom Style Instructions

소프트웨어 엔지니어링 작업을 도와주는 인터랙티브 CLI 도구입니다.
[여기에 커스텀 지침...]

## Specific Behaviors

[이 스타일에서 Claude가 어떻게 행동해야 하는지 정의...]

 

프론트매터 필드

필드	설명	기본값
name	출력 스타일 이름 (UI에서 표시)	파일 이름
description	/output-style 메뉴에 표시되는 설명	없음
keep-coding-instructions	코딩 관련 시스템 프롬프트 섹션 유지 여부	false

keep-coding-instructions 언제 true로?

코드 리뷰, 테스트 작성, 리팩토링 같은 소프트웨어 엔지니어링 작업에 커스텀 스타일을 사용한다면 keep-coding-instructions: true로 설정하는 것이 좋다. 그래야 테스트 검증, 코드 품질 체크 등의 지침이 유지된다.

 

관련 기능 비교 (Comparisons)

출력 스타일 vs CLAUDE.md vs --append-system-prompt

기능	동작 방식	영향 레벨
출력 스타일	시스템 프롬프트의 코딩 지침을 완전히 대체	시스템 프롬프트 수정
CLAUDE.md	기본 프롬프트 다음에 사용자 메시지로 추가	사용자 메시지
--append-system-prompt	시스템 프롬프트에 추가 (기존 유지)	시스템 프롬프트 추가

언제 무엇을 사용할까?

출력 스타일

Claude의 근본적인 행동을 바꾸고 싶을 때

CLAUDE.md

프로젝트별 컨텍스트와 규칙을 추가할 때

--append-system-prompt

CLI에서 일회성 지침을 추가할 때

 

출력 스타일 vs 에이전트 vs 슬래시 명령

기능	비유	설명
출력 스타일	"저장된 시스템 프롬프트"	Claude의 작동 모드를 근본적으로 변경
에이전트	"특화된 전문가"	특정 작업에 호출됨, 모델/도구 설정 포함
슬래시 명령	"저장된 프롬프트"	특정 상호작용을 트리거

 

모범 사례 (Best Practices)

O 좋은 사례

• 명확한 목적: 하나의 스타일은 하나의 목적
• 행동 지침 명시: Claude가 어떻게 행동해야 하는지 구체적으로
• 테스트 후 배포: 테스트 프로젝트에서 먼저 시험
• 설명적인 이름: 스타일이 무엇을 하는지 명확하게

X 나쁜 사례

• 모호한 지침: "친절하게 응답해줘"
• 너무 긴 지침: 읽기 어려운 긴 문서
• 상충되는 규칙: 모순된 행동 요구
• 테스트 없이 배포: 바로 팀에 공유

 

예제 (Examples)

1. Teacher Mode (교육 스타일)

~/.claude/output-styles/teacher.md:

---
name: Teacher Mode
description: 모든 코드 변경에 대해 자세한 설명과 함께 가르치는 스타일
keep-coding-instructions: true
---

# Teacher Mode

You are a patient programming teacher using Claude Code.

## Core Behaviors

1. **Always explain before coding**: Before making any code changes,
   explain what you're about to do and why.

2. **Break down complex concepts**: Use analogies and simple examples.

3. **Ask comprehension questions**: After major changes, ask if the
   user understood.

4. **Provide context**: Explain how each change fits into the bigger picture.

## After Each Code Change

Include a brief "Learning Note" section explaining:
- What the code does
- Why this approach was chosen
- What alternatives exist

 

2. Concise Mode (간결 스타일)

~/.claude/output-styles/concise.md:

---
name: Concise
description: 최소한의 설명으로 빠르게 작업하는 스타일
keep-coding-instructions: true
---

# Concise Mode

You respond with minimal text. Get straight to the point.

## Rules

1. No pleasantries or filler phrases
2. Code comments only when complex logic requires explanation
3. Use bullet points, not paragraphs
4. One-line answers when possible

 

3. Technical Writer (기술 문서 스타일)

~/.claude/output-styles/technical-writer.md:

---
name: Technical Writer
description: 문서화와 기술 가이드 작성에 특화된 스타일
keep-coding-instructions: false
---

# Technical Writing Style

You are a technical writer specializing in clear, comprehensive documentation.

## Key Behaviors

- Write for a developer audience with varying technical backgrounds
- Include code examples where relevant
- Structure documentation with clear headings and sections
- Explain the "why" behind technical decisions
- Provide troubleshooting sections for common issues

## Output Format

- Use markdown formatting
- Include table of contents for longer documents
- Add code blocks with language syntax highlighting
- Include examples and use cases

 

상기 예시처럼 output-style을 추가 하여 선택할 수 있다.

 

문제 해결 (Troubleshooting)

스타일 변경이 적용되지 않음

확인 사항:

• 스타일 파일이 올바른 위치에 있는지 확인
  • 개인: ~/.claude/output-styles/
  • 프로젝트: .claude/output-styles/
• 설정 레벨(user vs project)이 파일 위치와 일치하는지
• YAML 프론트매터 문법이 올바른지

커스텀 스타일이 메뉴에 나타나지 않음

해결 방법:

• 파일이 정확한 디렉토리에 있는지 확인
• 파일 확장자가 .md인지 확인
• 프론트매터에서 name이 지정되지 않았다면 파일명이 스타일 이름이 됨
• Claude Code 재시작 시도

코딩 지침이 사라졌음

원인: 커스텀 출력 스타일은 기본적으로 코딩 지침을 제외한다.

해결: 프론트매터에 다음을 추가:

keep-coding-instructions: true

YAML 문법 오류

체크리스트:

• 프론트매터가 ---로 시작하고 끝나는지
• 들여쓰기가 일관적인지 (스페이스 vs 탭 혼용 금지)
• 콜론(:) 뒤에 공백이 있는지
• 특수문자는 따옴표로 감싸기

흔한 실수 TOP 3

1	파일 위치 오류 - ~/.claude/output-styles/가 아닌 다른 곳에 저장
2	keep-coding-instructions 누락 - 코딩 작업인데 false로 설정
3	너무 모호한 지침 - Claude가 해석하기 어려운 추상적인 요청

 

다음 단계 (Next Steps)

문서	설명
Headless	비대화형 자동화 모드
Settings	전체 설정 옵션
Slash Commands	커스텀 슬래시 명령 만들기
Skills	Claude에게 새로운 능력 가르치기

참고 자료

• 공식 문서: Output Styles
• 공식 문서: CLAUDE.md
• 공식 문서: Skills