한 줄 요약: Claude Code 공식 문서 "Output styles". 출력 스타일을 "세션의 모든 응답에 Claude의 역할·톤·응답 형식을 정하는 지시 묶음"으로 정의하고, 내장 스타일 다섯 가지(Default와 Proactive·Concise·Explanatory·Learning), 바꾸는 방법(/output-style, /config, VS Code 메뉴, outputStyle 설정), 커스텀 스타일 파일 만들기와 frontmatter 필드, 다른 기능(CLAUDE.md·스킬·훅·서브에이전트·--append-system-prompt)과 고르는 기준, 작동 방식(매 요청 전송, keep-coding-instructions, 서브에이전트·포크 적용 범위, 토큰)을 다룬다.
원본 정보#
- 제목: Output styles
- 발행: Anthropic, Claude Code 공식 문서 (원본 날짜 미상)
- URL: https://code.claude.com/docs/en/output-styles (새 창)
- 수집(fetch)일: 2026-10-18. 본문의 버전 조건(v2.1.237, v2.1.251, v2.1.257, v2.1.261, v2.1.269), 설정 키, 경로, 명령은 이 날짜 기준이다.
핵심 주장#
- 출력 스타일은 지시이지 보장이 아니다. 원본 첫머리 Note: 출력 스타일은 Claude가 따를 지시를 줄 뿐 "어떤 일이 항상 일어나거나 절대 일어나지 않음을 보장하지 않는다". 프로젝트에 대해 알아야 할 것은 CLAUDE.md, 매번 일어나야 하는 일(편집마다 포맷, 명령 차단)은 훅을 쓰라고 한다. → 출력 스타일, 훅
- 내장 스타일은 기본 코딩 지시를 유지하고, 커스텀 스타일은 기본적으로 뺀다. Default는 스타일 지시가 없는 상태다. 나머지 내장 네 가지는 Default의 소프트웨어 엔지니어링 지시를 유지하고 자기 지시를 더한다. 커스텀 스타일은 전체 시스템 프롬프트에서 변경 범위·주석·검증 같은 내장 엔지니어링 지시 절을 빼고,
keep-coding-instructions: true일 때만 남긴다. 이 필드는 짧은 시스템 프롬프트에서는 효과가 없다. → 출력 스타일 - 세션 중 바꾸면 다음 메시지부터 적용된다.
/output-style,/config메뉴, VS Code 메뉴는 선택을.claude/settings.local.json에 저장한다. 설정 파일의outputStyle값은 대소문자를 구분해, 정확히 맞지 않으면 Default가 된다. v2.1.251 이전에는/clear나 새 세션 뒤에야 적용됐다. → Claude Code 출력 스타일 설정·만들기 - 커스텀 스타일은 마크다운 파일 하나다. 사용자(
~/.claude/output-styles), 프로젝트(.claude/output-styles), managed policy 세 레벨에 두고, 플러그인은output-styles/디렉터리로 배포한다. frontmatter 필드는name,description,keep-coding-instructions,force-for-plugin넷이고 모두 선택이다. 터미널에서는 시작할 때 스타일 파일을 읽으므로 실행 중에 만들거나 고치면 재시작해야 한다. → Claude Code 출력 스타일 설정·만들기, 플러그인 - 메인 대화와 포크에만 적용된다. 포크는 부모의 대화와 시스템 프롬프트를 물려받으므로 스타일이 적용되고, 다른 서브에이전트는 자기 시스템 프롬프트로 돌아 스타일이 응답을 바꾸지 않는다. 스타일 지시는 입력 토큰을 더하지만 세션 첫 요청 뒤 프롬프트 캐싱이 비용을 줄인다. → 서브에이전트, 컨텍스트 비용
내장 스타일 (원본 표)#
| 스타일 | 무엇이 바뀌나 | 언제 맞나 |
|---|---|---|
| Proactive | 바로 작업을 시작하고 일상적인 결정은 묻지 않고 합리적으로 가정한다 | 일상적 결정을 Claude가 계속 처리하고, 가정이 틀리면 사용자가 바로잡을 때 |
| Concise | 결과부터 말하고 서론· | 기본 응답이 원하는 것보다 길 때 |
| Explanatory | 작성한 코드의 선택 이유를 짧은 Insight 블록으로 덧붙인다 | 코드베이스를 익히는 중이거나 변경과 함께 이유를 보고 싶을 때 |
| Learning | 선택을 설명하고 작은 코드 조각을 사용자가 직접 쓰게 남긴다 | 작업을 끝내면서 직접 코딩 연습도 하고 싶을 때 |
스타일별 세부:
- Default: 스타일을 고르지 않은 상태. 스타일 지시가 없고, 소프트웨어 엔지니어링용 표준 시스템 프롬프트로 일한다.
/output-style목록에default로 있어 같은 방법으로 고른다. - Proactive: 작업을 보내면 바로 구현을 시작하고, 계획을 요청하지 않으면 plan 모드로 바꾸지 않는다. 스타일 지시는 데이터를 지우거나 공유·운영 시스템을 바꾸기 전에 대화로 확인하라고도 한다. 원본은 이 확인이 Claude가 따르는 지시이고 권한 확인 창과는 별개라고 밝힌다. Proactive로 바꿔도 권한 모드는 바뀌지 않으며, 어떤 도구 호출을 묻지 않고 실행할지는 계속 권한 모드가 정한다. → 권한 모드
- Concise: 응답 첫 문장이 무슨 일이 있었는지나 답을 말한다. 단순한 질문에는 1~3문장으로 답한다. 엔지니어링 작업은 Default만큼 철저히 한다. 사용자가 설명·세부를 요청할 때, 그리고 안전하게 행동하는 데 필요한 내용(오류 보고, 실패한 테스트 출력, 보안 경고, 파괴적 동작 확인)은 전체 길이로 쓴다. v2.1.237 이상.
- Explanatory: Default처럼 작업하고 선택 이유를
★ Insight블록으로 대화에 붙인다. 블록 하나에 코드베이스나 작성한 코드에 관한 요점 2~3개. 파일에 주석으로 쓰지 않는다. - Learning: Explanatory의
Insight블록에 더해, 오류 처리·자료 구조·여러 방식이 가능한 비즈니스 로직처럼 실제 설계 결정이 있는 곳에서 몇 줄을 사용자에게 남긴다. 파일에TODO(human)주석을 달고 "Learn by Doing" 요청(이미 만든 것, 쓸 것, 따져 볼 것)을 보낸 뒤 멈춰 기다린다. 사용자가 다 썼다고 알리면 그 코드에 대한Insight하나를 주고 이어 간다.
바꾸는 방법 (2026-10-18 기준)#
/output-style <style>(예:/output-style concise). 인자 없이 실행하면 고를 수 있는 스타일과 현재 스타일을 보여 준다. 비대화형 모드·Agent SDK 세션, 그리고 Remote Control로 모바일 앱·웹에서도 쓸 수 있다(Remote Control에서는 내장 스타일만 나열·선택). 원본은 이 단락에 v2.1.269 이상을 붙인다.- 터미널 메뉴:
/config→ Output style. - VS Code 확장:
/로 명령 메뉴를 열고 Output styles. 커스텀 스타일도 고른다. v2.1.257 이상. 같은 메뉴에서 커스텀 스타일 파일을 만들 수도 있다(v2.1.261 이상). - 데스크톱 앱: 설정 파일(예:
.claude/settings.local.json)의outputStyle필드. 데스크톱에서/config는 메뉴 대신 Settings > Claude Code를 연다. - 명령과 두 메뉴는 선택을 로컬 프로젝트 레벨인
.claude/settings.local.json에 저장한다. outputStyle값은 대소문자를 구분한다(Proactive,Concise,Explanatory,Learning).explanatory처럼 정확히 맞지 않으면 Default가 된다./output-style명령은 대소문자를 무시한다.- 여러 프로젝트의 기본으로 쓰려면
~/.claude/settings.json에outputStyle을 둔다. 프로젝트 자체 설정 파일이 이 값보다 우선한다. - 세션 중 바꾸면 다음 메시지부터 새 스타일을 쓴다. 그 첫 메시지의 프롬프트 캐싱 비용은 원본이 Prompt caching 문서로 넘긴다.
커스텀 스타일 만들기 (2026-10-18 기준)#
- 파일 위치 세 레벨: 사용자
~/.claude/output-styles, 프로젝트.claude/output-styles, managed policy는 managed settings 디렉터리 안의.claude/output-styles.name을 두지 않으면 파일 이름이 스타일 이름이 된다. - 프로젝트 스타일은 작업 디렉터리와 저장소 루트 사이의 모든
.claude/output-styles/에서 로드되고, 같은 이름이 여럿이면 작업 디렉터리에 가장 가까운 것을 쓴다. - 원본 예시 "Diagrams first":
keep-coding-instructions: true로 코딩 동작은 유지하고, 코드·아키텍처·데이터 흐름을 설명할 때 Mermaid 다이어그램부터 그리게 한다. 원문은 Claude Code 출력 스타일 설정·만들기에 옮겼다. - 터미널에서는 시작할 때 스타일 파일을 읽으므로, 실행 중에 만들거나 고치면 Claude Code를 재시작한다.
- frontmatter: 모든 필드 선택, 소문자와 하이픈. 철자가 틀린 필드는 오류 없이 무시된다. YAML이 파싱되지 않으면 필드 없이 파일 이름으로 로드되고,
claude --debug로 파싱 오류를 본다.
| 필드 | 필수 | 설명 |
|---|---|---|
name | 아니오 | / 선택 창에 보이는 이름. 기본값: 파일 이름 |
description | 아니오 | / 선택 창에 보이는 설명 |
keep-coding-instructions | 아니오 | true면 전체 시스템 프롬프트에만 있는 Claude Code 내장 소프트웨어 엔지니어링 지시 절을 스타일과 함께 유지. 기본값: false |
force-for-plugin | 아니오 | 플러그인 출력 스타일 전용. true면 플러그인이 켜져 있을 때 사용자가 고르지 않아도 자동 적용되고 사용자의 outputStyle 설정을 덮어쓴다. 여러 플러그인이 설정하면 먼저 로드된 것. 기본값: false |
다른 기능과 고르기 (원본 표)#
원본: 출력 스타일은 세션의 모든 응답에 적용되는 지시라서 "아무것도 강제하지 않는다". 원하는 것이 모든 응답보다 좁거나 반드시 일어나야 하면 다른 기능이 맞다.
| 원하는 것 | 쓸 것 | 맞는 이유 |
|---|---|---|
| 모든 응답을 특정 목소리· | 출력 스타일 | 세션 전체에 적용되고 명령 하나로 바꾼다 |
| 프로젝트 관례· | CLAUDE.md | 코드베이스에 대해 알아야 할 것을 담고, 어떤 스타일을 고르든 계속 로드된다 |
| 릴리스 체크리스트· | 스킬 | 부르거나 작업이 맞을 때만 로드돼 관련 없는 응답을 바꾸지 않는다 |
| 편집마다 포맷, 명령 차단처럼 예외 없이 매번 일어날 일 | 훅 | Claude Code가 생명주기 이벤트에 직접 실행해 Claude가 지시를 따르는지에 기대지 않는다 |
| 집중된 작업용으로 자기 지시· | 서브에이전트 | 자기 시스템 프롬프트로 별도 컨텍스트에서 돌고 대화에 요약을 돌려준다 |
| Claude Code를 시작할 때 넘기는 지시 추가 | --append-system-prompt | 아무것도 지우지 않고 시스템 프롬프트에 덧붙인다 |
기능은 조합된다. 원본 예: 알아야 할 것은 CLAUDE.md, 응답 방식은 출력 스타일, 보장돼야 하는 것은 훅.
작동 방식#
- 활성 스타일의 지시를 매 요청에 보낸다.
- 전체 시스템 프롬프트에서 커스텀 스타일은 내장 소프트웨어 엔지니어링 지시 절(변경 범위 정하기, 주석 쓰기, 작업 검증 등)을 뺀다.
keep-coding-instructions: true면 남긴다. 짧은 시스템 프롬프트에는 그 절이 없어 이 필드가 효과가 없다. 필드에 기대려면CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT를0으로 두어 어떤 모델에서든 전체 프롬프트를 고른다. - 메인 대화와 포크에 적용되고, 다른 서브에이전트에는 적용되지 않는다.
- 토큰: 스타일 지시가 입력 토큰을 더하고 세션 첫 요청 뒤 캐싱이 줄인다. 내장 Explanatory·Learning은 설계상 Default보다 응답이 길어 출력 토큰이 늘고, Concise는 반대다. 커스텀 스타일의 출력 토큰은 지시 내용에 달렸다.
원본이 링크한 관련 문서#
Memory(CLAUDE.md), Hooks guide, Permission modes, Settings(설정 우선순위), Headless(비대화형 모드), Remote Control 제약, VS Code 명령 메뉴, Desktop, Prompt caching의 "Changing output style", Managed settings 전달 방식, Plugins manifest reference·overview, Glossary(frontmatter), Skills, Sub-agents(포크, 시작 때 로드되는 것), CLI reference(시스템 프롬프트 플래그), Env vars, Features overview, Debug your configuration