출력 스타일(Output styles)

소프트웨어 엔지니어링 너머의 용도로 Claude Code를 맞춰 쓰고 싶을 때가 있어요. 그럴 때 유용한 기능이 출력 스타일입니다. 출력 스타일은 Claude가 아는 것을 바꾸지 않고, 어떻게 응답하는지 바꿔요. 즉 매 응답에 적용되는 Claude의 역할·톤·출력 형식을 정해 줍니다. 매 턴마다 같은 목소리나 형식을 다시 요청해야 하는 상황, 또는 Claude가 소프트웨어 엔지니어가 아닌 다른 역할을 하길 원할 때 쓰면 됩니다.

커스텀 출력 스타일은 직접 만든 지시를 Claude에게 주면서, Claude Code 내장 소프트웨어 엔지니어링 지시를 유지할지도 고를 수 있어요. 항상 다이어그램으로 답하게 만들 것처럼 '소통 방식만 바꾸되 코딩은 그대로'일 땐 유지하고, 글쓰기 어시스턴트나 데이터 분석가처럼 소프트웨어 엔지니어링을 전혀 안 할 때는 빼면 됩니다.

프로젝트·관례·코드베이스에 대한 지시는 CLAUDE.md를 쓰는 게 더 맞아요.

출처: 공식문서

본문

내장 출력 스타일

Claude Code의 Default 출력 스타일은 소프트웨어 엔지니어링 작업을 효율적으로 완료하도록 설계된 표준 지시 집합입니다.

추가 내장 출력 스타일은 네 가지가 있어요.

Proactive: Claude가 즉시 실행하고, 일상적인 결정에 멈추지 않고 합리적인 가정을 하며, 계획보다 행동을 선호합니다. 이는 자동 모드가 적용하는 것보다 더 강한 자율 실행 지시인데, 권한 모드를 바꾸지 않아도 되어서 무엇을 묻지 않고 실행할지는 여전히 권한 모드가 정합니다.
Concise: 결과를 먼저 내놓고 전제·설명을 건너뛰며 기본적으로 응답을 짧게 유지하되, 엔지니어링 작업 자체는 Default 스타일만큼 철저히 합니다. 설명이나 더 많은 세부 사항을 요청하면 Claude는 충분히 답합니다. 오류 보고, 보안 경고, 파괴적 작업의 확인 내용은 항상 전체를 유지해요. Claude Code v2.1.237 이상 필요.
Explanatory: 소프트웨어 엔지니어링 작업을 돕는 사이에 교육적인 "Insights"를 제공합니다. 구현 선택과 코드베이스 패턴을 이해하는 데 도움을 줘요.
Learning: 협력적·배우면서 하는 모드로, Claude가 코딩 중 "Insights"를 공유할 뿐 아니라 스스로 작고 전략적인 코드 조각을 기여하도록 요청합니다. 직접 구현할 위치에 TODO(human) 마커를 코드에 추가해요.

출력 스타일 바꾸기

다음 중 한 가지 방법으로 스타일을 고르세요.

터미널: /config를 실행하고 Output style을 골라 메뉴에서 선택. Claude Code는 선택을 로컬 프로젝트 수준의 .claude/settings.local.json에 저장합니다.
VS Code 확장: /로 명령 메뉴를 열고 Output styles를 선택해 커스텀 스타일을 포함해 고르기. Claude Code는 터미널 메뉴가 쓰는 것과 같은 .claude/settings.local.json에 저장합니다. Claude Code v2.1.257 이상 필요.
데스크톱 앱: 설정 파일(예: 터미널 메뉴가 쓰는 .claude/settings.local.json)의 outputStyle 필드를 직접 설정. 거기서 /config를 실행하면 메뉴 대신 Claude Code가 Settings > Claude Code를 엽니다.

Note: 단독 /output-style 명령은 v2.1.73에서 deprecated, v2.1.91에서 제거됐습니다. /config를 쓰거나 outputStyle 설정을 직접 편집하세요.

메뉴 없이 설정하려면 설정 파일의 outputStyle 필드를 직접 편집하세요.

{
  "outputStyle": "Explanatory"
}

세션 중간에 스타일을 바꾸면 다음 메시지부터 새 스타일을 써요. 그 첫 메시지가 프롬프트 캐싱에 드는 비용은 Changing output style을 보세요. v2.1.251 이전에는 새 스타일이 /clear를 실행하거나 새 세션을 시작한 뒤에만 적용됐어요.

커스텀 출력 스타일 만들기

커스텀 출력 스타일은 Markdown 파일입니다. 메타데이터용 frontmatter와 Claude를 위한 지시로 이뤄져요.

VS Code 확장에서는 손으로 쓰는 대신 Output styles 메뉴에서 파일을 만들 수도 있어요. Claude Code v2.1.261 이상이 필요합니다.

Markdown 파일 만들기 — 다음 세 수준 중 하나에 저장하세요. frontmatter에서 name을 설정하지 않으면 파일 이름이 스타일 이름이 됩니다.
- User: ~/.claude/output-styles
- Project: .claude/output-styles
- Managed policy: managed settings 디렉토리 안의 .claude/output-styles
프로젝트 출력 스타일은 작업 디렉토리와 저장소 루트 사이의 모든 .claude/output-styles/에서 로드됩니다. 중첩된 디렉토리가 같은 이름의 스타일을 여럿 정의하면, Claude Code는 작업 디렉토리에 가장 가까운 것을 사용해요.
frontmatter와 지시 추가 — Claude Code의 소프트웨어 엔지니어링 지시를 유지할지 정하세요. 소통 방식만 바꾸되 여전히 같은 방식으로 코딩하길 원하면 keep-coding-instructions: true로 설정하고, 소프트웨어 엔지니어링을 안 할 거면 빼세요.

이 예시는 Claude의 코딩 동작을 유지하면서 모든 설명을 다이어그램으로 시작하게 합니다.
```
---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---

When explaining code, architecture, or data flow, start with a Mermaid diagram showing the structure, then explain in prose.

## Diagram conventions

Use `flowchart TD` for control flow and `sequenceDiagram` for request paths. Keep diagrams under 15 nodes.
```
자신의 스타일로 전환 — 터미널에서 /config를 실행하고 Output style 아래에서 자신의 스타일을 고르세요. Claude는 다음 메시지부터 새 스타일을 씁니다. 터미널에서 Claude Code는 시작할 때 스타일 파일을 읽으므로, 실행 중 세션에서 파일을 만들거나 편집하면 변경점을 반영하려면 Claude Code를 재시작하세요.

플러그인도 output-styles/ 디렉토리에 출력 스타일을 담아 배포할 수 있어요.

Frontmatter

출력 스타일 파일이 지원하는 frontmatter 필드는 다음과 같습니다.

Frontmatter	용도	기본값
`name`	파일 이름이 아닌 출력 스타일의 이름	파일 이름에서 상속
`description`	`/config` 선택기에 표시되는 출력 스타일 설명	없음
`keep-coding-instructions`	Claude Code 내장 소프트웨어 엔지니어링 지시 유지 여부	`false`
`force-for-plugin`	플러그인 출력 스타일 전용: 사용자가 선택하지 않아도 플러그인이 활성화될 때마다 이 스타일을 자동 적용. 사용자의 `outputStyle` 설정을 덮어씀. 활성 플러그인이 여럿 설정하면 로드된 첫 번째 것을 사용	`false`

출력 스타일이 동작하는 방식

출력 스타일은 Claude Code가 Claude에게 주는 지시를 바꿉니다.

Claude Code는 활성 스타일의 지시를 매 요청과 함께 보냅니다.
Default가 아닌 스타일을 선택하면, Claude Code는 대화 중에도 Claude에게 스타일을 상기시킵니다.
커스텀 출력 스타일은 keep-coding-instructions가 true로 설정되어 있지 않으면, 변경 범위·주석 작성·작업 검증 방법 같은 Claude Code 내장 소프트웨어 엔지니어링 지시를 뺍니다.

출력 스타일은 주 대화와 fork(부모의 전체 대화와 시스템 프롬프트를 상속)에 적용됩니다. 다른 서브에이전트는 자신의 시스템 프롬프트를 실행하므로, 스타일이 그들의 응답을 바꾸지는 않아요.

토큰 사용량은 스타일에 따라 달라져요. 스타일의 지시는 입력 토큰을 추가하지만, 프롬프트 캐싱이 세션 내 첫 요청 이후 비용을 줄여 줍니다.

내장 Explanatory·Learning 스타일은 설계상 Default보다 긴 응답을 만들어 출력 토큰이 늘어납니다. Concise 스타일은 기본적으로 응답을 짧게 유지하라고 지시하므로 반대예요. 커스텀 스타일의 출력 토큰 사용량은 지시가 Claude에게 무엇을 만들라고 하는지에 따라 달라집니다.

기능	동작 방식	언제 쓰나
출력 스타일	Claude Code의 기본 지시를 변경	매 턴 다른 역할·톤·기본 응답 형식을 원할 때
CLAUDE.md	시스템 프롬프트 뒤에 사용자 메시지를 추가	Claude가 항상 프로젝트 관례와 코드베이스 맥락을 알길 원할 때
`--append-system-prompt`	아무것도 지우지 않고 시스템 프롬프트에 추가	시작 시 CLI 플래그로 전달하는 일회성 추가를 원할 때
Agents	자신만의 시스템 프롬프트·모델·도구를 가진 서브에이전트 실행	초점을 맞춘 작업을 위한 별도 범위의 헬퍼를 원할 때
Skills	호출되거나 관련될 때 작업별 지시를 로드	재사용 가능한 워크플로가 있을 때

더 알아보기

Settings: outputStyle 필드가 어디에 있고 설정 우선순위가 어떻게 동작하는지
Permission modes: Proactive 스타일이 자동 모드와 어떻게 다른지
Plugins: skills·hooks·agents와 함께 출력 스타일을 패키징·배포
Debug your configuration: 출력 스타일이 적용되지 않는 원인 진단

출력 스타일(Output styles)