Claude Code Output Styles 사용법: /output-style과 커스텀 스타일

Claude Code가 답할 때마다 “결론부터 짧게”, “왜 그렇게 고쳤는지도 설명해줘”를 반복해서 붙일 필요는 없습니다. Claude Code Output Styles를 바꾸면 한 번의 작업 지시가 아니라 이후 모든 응답에 적용할 역할·톤·출력 형식을 선택할 수 있습니다.

이 기능은 모델의 지식이나 코딩 권한을 바꾸지 않습니다. 같은 도구와 권한을 유지한 채 답변을 짧게 만들거나, 구현 이유를 더 설명하게 하거나, 사용자가 직접 작은 코드를 작성하는 학습 흐름으로 전환합니다.[1]

아래 내용은 Linux에서 @anthropic-ai/claude-code@2.1.270을 별도 경로에 설치해 확인했습니다. 공식 문서에는 아직 /output-style 제거 안내가 남아 있지만, 2.1.269 릴리스와 2.1.270 실제 명령은 다시 추가된 상태를 보여줍니다.[1][2]

Output Styles가 바꾸는 것

Output Style은 Claude Code가 매 요청과 함께 전달하는 기본 응답 지침입니다. 스타일을 선택하면 다음과 같은 부분이 달라질 수 있습니다.

• 결론을 먼저 말할지, 배경부터 설명할지

• 구현 선택과 코드 패턴을 어느 정도 설명할지

• 바로 실행할지, 사용자의 참여를 유도할지

• 표·체크리스트·고정된 절차처럼 어떤 구조로 답할지

• 소프트웨어 엔지니어가 아닌 다른 역할로 응답할지

반대로 모델, 도구, 샌드박스, 승인 정책은 Output Style의 대상이 아닙니다. 예를 들어 Proactive를 골라도 위험한 명령이 자동 승인되는 것은 아닙니다. Claude가 결정을 덜 되묻고 행동을 우선하도록 지시할 뿐, 무엇을 묻지 않고 실행할지는 기존 permission mode가 계속 결정합니다.[1]

Default 이외의 스타일 지침은 입력 토큰을 추가하며, 응답 길이에 따라 출력 토큰도 달라질 수 있습니다. Prompt caching이 첫 요청 이후 반복 비용을 줄일 수 있지만 “스타일을 써도 토큰 비용이 없다”거나 “Concise를 고르면 항상 비용이 줄어든다”고 단정할 수는 없습니다.[1][3]

기본 Output Styles 5가지

2.1.270의 /output-style 목록에는 Default와 네 가지 추가 스타일이 표시됐습니다. 프로젝트에 만든 Review First는 기본 제공 항목이 아니라 별도의 커스텀 스타일입니다.

Concise는 짧게 답하더라도 오류 보고, 보안 경고, 파괴적 작업 확인까지 생략하도록 만든 모드가 아닙니다. 공식 문서는 이런 정보는 온전히 유지한다고 설명하며 Claude Code 2.1.237 이상을 요구합니다.[1][4]

Learning은 단순히 설명을 길게 만드는 모드와도 다릅니다. Claude Code가 구현할 위치에 TODO(human) 표시를 두고 사용자가 작은 전략적 코드 조각을 작성하도록 유도합니다. 코드를 전부 맡기려는 상황보다 직접 따라 하며 익힐 때 적합합니다.[1]

/output-style로 현재 스타일 확인

Claude Code에서 인자 없이 명령을 실행하면 현재 선택과 사용 가능한 목록을 함께 볼 수 있습니다.

/output-style

2.1.270 격리 실습에서는 다음 항목이 표시됐습니다.

Output style: default

Available styles:
- default (current)
- Proactive
- Concise
- Explanatory
- Learning
- Review First

Usage: /output-style <style>

목록의 Review First는 실습 프로젝트의 .claude/output-styles/review-first.md에서 읽은 사용자 정의 스타일입니다. 기본 제공 항목 수를 셀 때 포함하면 안 됩니다.

스타일 이름을 붙이면 목록 화면을 거치지 않고 바로 전환할 수 있습니다.

/output-style Concise
/output-style Explanatory
/output-style Learning

공백이 있는 커스텀 이름도 그대로 지정합니다.

/output-style Review First

실제 확인한 결과는 다음과 같았습니다.

Output style set to Review First

선택값은 프로젝트 로컬 설정인 .claude/settings.local.json에 저장됐습니다.

{
  "outputStyle": "Review First"
}

2.1.251 이상에서는 세션 중 스타일을 전환하면 /clear나 재시작 없이 다음 메시지부터 새 스타일이 적용됩니다. 다만 스타일 Markdown 파일 자체를 새로 만들거나 수정한 경우에는 재시작이 필요합니다.[1][3]

버전별 /output-style 사용 경로

현재 한국어 공식 문서는 독립된 /output-style이 2.1.73에서 더 이상 사용되지 않게 됐고 2.1.91에서 제거됐다고 안내합니다. 이 설명만 보면 /config 또는 설정 파일을 사용해야 합니다.[1]

하지만 2.1.269 릴리스 노트에는 다음 변경이 별도로 기록돼 있습니다.

Added /output-style [name] to list and switch output styles

2.1.270에서도 인자 없는 목록 조회와 이름을 붙인 전환을 모두 확인했습니다. 따라서 현재 기준은 다음처럼 정리하는 편이 정확합니다.

• 2.1.269에서 재추가, 2.1.270에서 실측: /output-style로 목록 조회와 즉시 전환 가능

• 이전 버전 또는 명령이 보이지 않는 환경: /config의 Output style 메뉴 사용

• 메뉴 없이 설정: settings.json의 outputStyle 문자열 직접 편집

먼저 버전을 확인합니다.

claude --version

2.1.270을 버전까지 고정해 기존 전역 설치와 분리하려면 다음처럼 실행할 수 있습니다.

npx -y @anthropic-ai/claude-code@2.1.270 --version

확인된 출력은 다음과 같습니다.

2.1.270 (Claude Code)

이 글의 확인일은 2026년 9월 14일입니다. npm 배포 기록상 2.1.269는 9월 11일, 2.1.270은 9월 12일 공개됐습니다.[5][6]

같은 질문으로 실제 응답 비교

Output Styles의 차이는 스타일마다 다른 질문을 던지면 판단하기 어렵습니다. 각 실행에서 Claude Code 2.1.270과 --model sonnet --effort low --tools '' 옵션을 사용했으며, 결과 JSON에 기록된 실제 모델은 claude-sonnet-5였습니다. 앞선 대화가 다음 답변에 영향을 주지 않도록 스타일마다 새 프로세스를 시작했습니다.

function sum(values) {
  return values.reduce((total, value) => total + value, 0);
}

다음 JavaScript 함수는 문자열 숫자 배열에서 합계를 구합니다.
문제를 찾고 수정 방향을 설명하세요. 파일은 수정하지 마세요.

실행 형식은 다음과 같습니다. 스타일 이름만 .claude/settings.local.json에서 바꾼 뒤 같은 명령을 반복했습니다.

claude -p "<같은 프롬프트>" \
  --tools '' \
  --model sonnet \
  --effort low \
  --max-turns 1 \
  --output-format json

한 번씩 실행한 결과는 다음과 같습니다. 문자 수는 응답 원문 기준이며, 출력 토큰은 Claude Code JSON 결과에 기록된 값입니다. 한 번의 실행만으로 속도·비용·품질의 우열을 일반화하지 않습니다.

Default와 Proactive

Default는 문자열 연결이 생기는 이유와 Number(value) 또는 parseFloat(value)를 쓰는 방향을 설명했습니다. Proactive는 같은 결론에 더해 실제 계산 흐름과 수정 코드를 바로 제시했습니다.

sum(["1", "2", "3"]) → 0 + "1" = "01"
→ "01" + "2" = "012" → "012" + "3" = "0123"

이번 비교는 --tools ''로 도구를 비활성화했으므로 파일 수정 자체가 불가능했습니다. 따라서 이 실행은 Proactive의 파일 수정이나 권한 처리까지 검증한 실험이 아닙니다. Proactive가 permission mode를 바꾸지 않는다는 설명은 공식 문서에 근거합니다.[1]

Concise

Concise 결과 JSON의 output_tokens는 93으로 여섯 결과 중 가장 작았습니다. 핵심 문장은 다음 두 문단입니다.

`values.reduce` treats each `value` as a string, so `+` does string
concatenation, not addition (e.g. ["1","2"] → "12", not 3).

Fix: convert to number before adding — `total + Number(value)`
(or `parseFloat(value)`).

이번 실행에서는 한국어 질문에도 영어로 답했습니다. 한 번의 표본으로 Concise가 항상 영어를 선택한다고 볼 수는 없지만, “짧은 응답”이라는 문서상 성향은 가장 분명하게 나타났습니다.

Explanatory

Explanatory는 원인, 계산 과정, 수정 코드 뒤에 별도 Insight를 붙였습니다.

★ Insight
- JS의 `+`는 오버로드된 연산자로, 피연산자 타입에 따라
  산술 또는 문자열 연결로 동작이 갈립니다.
- `reduce`의 초기값 타입이 숫자라고 해서 이후 연산까지
  숫자로 고정되는 게 아닙니다.

Explanatory 결과 JSON의 output_tokens는 855로 가장 컸습니다. 단순 수정안보다 JavaScript의 타입 변환 원리와 비슷한 실수를 피할 배경까지 알고 싶을 때 차이가 큽니다.

Learning

Learning 결과 JSON의 output_tokens는 766이었고 다음처럼 타입 변환 과정을 길게 풀었습니다.

초기값 `0`이 숫자라서 첫 연산 `0 + "1"`에서 JS가 `0`을
문자열로 강제 변환해버리고, 그 뒤로는 계속 문자열 연결이 이어집니다.

이번 읽기 전용 질문에서는 사용자가 코드를 작성하도록 요청하거나 TODO(human)을 만들지 않았습니다. 단일 실행만으로 원인을 확정할 수 없으며, 공식 문서가 설명하는 Learning의 참여형 동작은 실제 코딩 과정에서 따로 확인해야 합니다.[1]

Review First 응답

Review First는 다음처럼 지정한 두 제목을 정확한 순서로 사용했습니다.

검토 기준
- 문자열 숫자가 산술 덧셈으로 처리되는가
- 빈 배열과 숫자로 변환할 수 없는 값을 고려했는가
- 반환 타입이 유지되는가

권장 답변
문제: `total + value`에서 `value`가 문자열이므로
`+` 연산이 산술 덧셈이 아니라 문자열 연결로 동작합니다.

기본 스타일은 성향을 고르는 용도이고, 커스텀 스타일은 제목·순서·필수 항목처럼 반복되는 형식을 명시할 때 더 적합합니다.

프로젝트용 커스텀 스타일 만들기

팀 저장소 안에서만 사용할 스타일은 다음 위치에 Markdown 파일로 만듭니다.

.claude/output-styles/review-first.md

이 예시는 답변 전에 검토 기준을 먼저 보여주되 Claude Code의 기본 코딩 지침은 유지합니다.

---
name: Review First
description: State review criteria before the answer
keep-coding-instructions: true
---

For every response, begin with the exact heading `검토 기준`.
Then list the conditions that make the answer correct.
After that, provide the answer under the heading `권장 답변`.
Keep both sections concise.

Frontmatter는 다음 역할을 합니다.

• name: /output-style과 /config에 표시할 이름. 생략하면 파일 이름을 사용

• description: 선택 목록에서 스타일의 목적을 설명

• keep-coding-instructions: Claude Code의 기본 소프트웨어 엔지니어링 지침을 유지할지 결정

keep-coding-instructions의 기본값은 false입니다. 글쓰기 어시스턴트나 데이터 분석가처럼 코딩 역할 자체를 바꾸려는 경우에는 그대로 둘 수 있습니다. 반대로 코드 수정·검증 방식은 유지하고 답변 순서만 바꾸려면 true를 명시하는 편이 안전합니다.[1]

지침 본문은 영어뿐 아니라 한국어로 작성해도 됩니다. 실행 중인 터미널 Claude Code는 시작할 때 스타일 파일을 읽으므로, 파일을 새로 만들거나 수정했다면 터미널 세션을 종료하고 다시 시작합니다.

/output-style
/output-style Review First

/output-style 목록에는 스타일 이름이 보이는지, /config 선택기에는 이름과 설명이 보이는지 확인합니다. 전환 뒤에는 Output style set to Review First와 .claude/settings.local.json의 outputStyle 값을 함께 보면 선택과 저장을 구분할 수 있습니다.

개인용과 프로젝트용 경로

같은 스타일을 여러 저장소에서 사용하려면 사용자 경로에 두고, 팀과 공유할 규칙이면 프로젝트 경로에 둡니다.

Claude Code는 작업 디렉터리와 저장소 루트 사이의 중첩된 .claude/output-styles/도 읽습니다. 같은 이름이 여러 위치에 있으면 작업 디렉터리에 가장 가까운 스타일이 우선합니다.[1]

선택값을 메뉴 없이 직접 지정할 수도 있습니다.

{
  "outputStyle": "Explanatory"
}

사용자 전체 기본값은 ~/.claude/settings.json, 팀 공유값은 .claude/settings.json, Git에 올리지 않을 개인 선택은 .claude/settings.local.json에 둡니다. 프로젝트 로컬 파일의 값은 프로젝트 공유 설정보다 우선하므로, 팀 설정과 다른 결과가 나오면 두 파일을 함께 확인합니다.[7]

공식 문서에 따르면 터미널 /config의 선택은 .claude/settings.local.json에 저장됩니다.[1] 2.1.270 실습에서는 /output-style Review First도 같은 파일에 {"outputStyle":"Review First"}를 기록했습니다.

Output Styles와 CLAUDE.md의 차이

어떤 내용을 어디에 저장할지 헷갈리면 “응답 방식인가, 프로젝트 사실인가, 특정 작업 절차인가”로 구분합니다.

“항상 이 저장소에서는 npm run build를 실행한다”는 프로젝트 규칙이므로 CLAUDE.md가 맞습니다. “모든 답변은 결론부터 말한다”는 응답 형식이므로 Output Style에 둡니다. 배포할 때만 필요한 절차는 Skill, 독립된 리뷰 작업자는 Agent가 어울립니다.

Output Style은 현재 주 대화와 그 대화 설정을 그대로 이어받은 분기 대화에는 적용됩니다. 반면 별도 지침으로 실행되는 서브에이전트까지 같은 말투로 바뀐다고 기대하면 안 됩니다.[1]

스타일이 적용되지 않을 때

파일을 만든 뒤 재시작하지 않음

스타일 전환은 다음 메시지부터 적용되지만, 실행 중 새로 만든 Markdown 파일은 별개입니다. Claude Code를 종료하고 다시 열어 목록을 갱신합니다.

다른 지침이 형식을 강하게 지정함

프롬프트, CLAUDE.md, Skill, Agent의 시스템 프롬프트가 서로 다른 형식을 요구할 수 있습니다. 고정 비교에서는 추가 지침을 동일하게 유지하고 스타일마다 새 세션을 시작합니다.

선택 기준

일반 코딩은 Default에서 시작하면 됩니다. 답변이 길어 결론을 찾기 어렵다면 Concise, 코드가 왜 그렇게 바뀌는지 배우고 싶다면 Explanatory, 직접 작은 부분을 작성하며 익히려면 Learning이 맞습니다. 요구사항과 성공 조건이 분명해 반복 확인을 줄이고 싶을 때만 Proactive를 고릅니다.

팀 고유 형식이 반복된다면 커스텀 스타일로 옮깁니다. 다만 저장소 지식까지 한 파일에 몰아넣지 말고, 프로젝트 사실은 CLAUDE.md, 작업 절차는 Skill, 응답 방식은 Output Style로 나누는 편이 충돌을 줄입니다.

Claude Code 설치부터 필요하다면 Claude Code 처음 설치하고 실행해보기를 먼저 볼 수 있습니다. 설치된 Skill의 비용과 노출 범위는 Claude Code 스킬 관리에서 정리했습니다.

여러 작업자에게 서로 다른 역할을 맡기려면 AI에게 작업을 나눠 맡길 때 역할 정의서 쓰는 법으로 이어집니다.

참고 자료

[1] Claude Code Output Styles 공식 문서
[2] Claude Code v2.1.269 릴리스 — /output-style [name] 재추가
[3] 스타일 변경과 prompt caching
[4] Claude Code v2.1.237 릴리스 — Concise 스타일 지원
[5] npm 패키지 2.1.269
[6] npm 패키지 2.1.270
[7] Claude Code 설정 범위와 우선순위