Claude Code 출력 스타일 — 말투만 바꾸려다 코딩 규칙이 통째로 빠집니다

AI가 쓸데없이 장황하다거나, 매번 같은 말투를 요구하느라 지친 적 있나요. Claude Code에는 이걸 한 번에 정하는 출력 스타일이라는 기능이 있습니다. 그런데 공식 문서를 열어보니 커스텀 스타일을 만드는 순간 내장 코딩 지시가 기본적으로 빠지게 돼 있더군요. 말투만 바꾸려던 사람에게는 예상 못 한 결과입니다. 함정 다섯 가지를 정리했습니다.

📌 30초 요약

• 출력 스타일은 시스템 프롬프트를 직접 고칩니다. "무엇을 아는지"가 아니라 "어떻게 답하는지"를 바꿉니다.
• 커스텀 스타일의 기본값은 내장 코딩 지시를 빼는 것입니다. 변경 범위 잡는 법·주석 쓰는 법·검증하는 법이 함께 사라집니다.
• 바꿔도 지금 세션에는 안 먹습니다. 세션 시작에 한 번만 읽기 때문에 새 세션이나 대화 초기화가 필요합니다.
• 서브에이전트에는 적용되지 않습니다. 자기 시스템 프롬프트로 돌기 때문입니다.
• 내장 스타일 중 둘은 설계상 답이 길어집니다. 출력 토큰이 늘어난다고 문서가 직접 적어놨습니다.
• 검색하면 나오는 /output-style 명령은 이미 제거됐습니다.

무엇을 바꾸는 기능인가

"Output styles change how Claude responds, not what Claude knows. They modify the system prompt to set role, tone, and output format."

— Claude Code 공식 문서, 출력 스타일 페이지

핵심은 시스템 프롬프트를 직접 고친다는 대목입니다. 프로젝트 규칙을 알려주는 CLAUDE.md는 시스템 프롬프트 뒤에 사용자 메시지로 붙는 반면, 출력 스타일은 시스템 프롬프트 자체에 들어갑니다. 문서가 권하는 사용 시점도 분명합니다 — 매 턴 같은 말투나 형식을 계속 요구하고 있을 때, 또는 소프트웨어 엔지니어가 아닌 다른 역할을 시키고 싶을 때입니다. 반대로 프로젝트 관례나 코드베이스 이야기는 CLAUDE.md 쪽이라고 못 박습니다.

기본 제공되는 건 넷입니다. Default가 기존 시스템 프롬프트고, 나머지 셋은 성격이 뚜렷합니다.

스타일	바뀌는 것	답 길이
Default	기존 그대로	기준
Proactive	묻지 않고 바로 실행, 계획보다 행동	문서 언급 없음
Explanatory	작업 중간에 교육용 해설을 끼워넣음	설계상 더 길다
Learning	코드에 표시를 남기고 일부를 직접 짜게 시킴	설계상 더 길다

Learning 스타일이 특이합니다. 문서 설명으로는 코드 안에 사람이 채울 자리를 표시로 남기고 일부를 직접 구현하게 시킵니다. 배우려는 사람에게는 좋지만, 빨리 끝내려는 상황에서 켜두면 곤란해집니다.

함정 하나 — 기본값이 "코딩 지시를 뺀다"입니다

직접 만드는 커스텀 스타일에서 제일 조심해야 할 대목입니다. 마크다운 파일 하나에 앞머리 정보와 지시문을 적으면 되는데, 앞머리에 넣을 수 있는 항목 중 하나가 결정적입니다.

"Custom output styles leave out Claude Code's built-in software engineering instructions, such as how to scope changes, write comments, and verify work, unless keep-coding-instructions is set to true."

— Claude Code 공식 문서, 출력 스타일 동작 방식

그리고 문서의 앞머리 표를 보면 이 항목의 기본값이 거짓입니다. 즉 아무 생각 없이 커스텀 스타일을 만들면 코딩 지시가 빠진 상태로 돌아갑니다. 문서가 예로 든 것만 봐도 변경 범위를 어디까지 잡을지, 주석을 어떻게 쓸지, 작업을 어떻게 검증할지입니다. 말투를 바꾸려고 만든 스타일 때문에 이런 게 사라지면, "왜 갑자기 일을 다르게 하지"라는 상황이 생기는데 원인을 찾기 어렵습니다.

# 말투만 바꾸고 코딩 방식은 그대로 두고 싶을 때
# ~/.claude/output-styles/diagrams-first.md
---
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.

문서의 예시를 그대로 옮긴 것입니다. 파일 이름이 곧 스타일 이름이 되고, 앞머리에 이름을 따로 적으면 그쪽이 쓰입니다.

자동 모드 설정을 뜯어봤을 때도 똑같은 구조를 봤습니다. 거기서는 배열에 기본값을 뜻하는 문자열을 안 넣으면 내장 차단 규칙이 통째로 사라졌습니다. "내 걸 추가한다"고 생각했는데 실은 "전부 갈아치운다"가 기본 동작인 설정이 이 도구에 여럿 있습니다. 설정 파일을 만질 때 기본값을 유지하는 스위치가 따로 있는지부터 찾는 습관이 필요합니다.

함정 둘 — 바꿔도 지금 세션에는 안 먹습니다

스타일을 바꿨는데 답이 그대로라 "설정이 안 먹네" 싶을 수 있습니다. 정상입니다. 출력 스타일은 시스템 프롬프트의 일부라서 Claude Code가 세션 시작에 한 번만 읽습니다. 대화를 초기화하거나 새 세션을 열어야 반영됩니다.

이게 프롬프트 캐시가 깨지는 조건들과도 이어집니다. 시스템 프롬프트가 바뀐다는 건 캐시의 맨 앞부분이 바뀐다는 뜻이니까요. 세션 도중에 이것저것 바꾸는 것보다 시작할 때 정하고 그대로 두는 편이 싸다는 결론은 여기서도 같습니다.

함정 셋 — 서브에이전트는 내 스타일을 안 씁니다

출력 스타일은 메인 대화에만 적용됩니다. 서브에이전트는 자기 시스템 프롬프트로 돌기 때문에 내가 정한 말투나 형식을 따르지 않습니다. 예외가 하나 있는데, 현재 대화를 그대로 복제하는 방식(포크)은 부모의 시스템 프롬프트를 통째로 물려받아서 스타일도 같이 갑니다.

AI 팀원을 여러 명 붙이는 이야기를 정리하면서 리드의 권한은 전원에게 그대로 간다고 썼는데, 스타일은 정반대로 안 갑니다. 권한은 상속되고 말투는 상속되지 않는 셈입니다. 여러 에이전트를 붙여놓고 결과물 형식이 제각각이라면 이 차이가 원인일 수 있습니다.

함정 넷 — 검색해서 나오는 명령어는 이미 없습니다

이 기능을 검색하면 /output-style이라는 전용 명령을 쓰라는 설명이 나옵니다. 문서에 이렇게 적혀 있습니다 — 그 명령은 v2.1.73에서 지원 중단됐고 v2.1.91에서 제거됐습니다. 지금은 /config에서 고르거나 설정 파일의 항목을 직접 고쳐야 합니다.

🕰️ 또 낡은 정보였습니다

바로 어제도 같은 일을 겪었습니다 — 요금이 오른다는 이야기가 돌길래 확인해보니 취소된 계획이었죠. 이번엔 명령어입니다. 둘 다 "틀린 정보"라기보다 "그때는 맞았던 정보"입니다. 도구가 빠르게 바뀌는 동안 설명 글은 그 자리에 남아 있으니까요. 명령어가 안 먹을 때 내 탓부터 하지 말고, 그 명령이 아직 있는지부터 확인하는 게 빠릅니다.

함정 다섯 — 스타일에 따라 토큰이 늘어납니다

문서가 비용 이야기를 직접 합니다. 두 방향입니다. 시스템 프롬프트에 지시를 더하니 입력 토큰이 늘고, 다만 캐시 덕분에 세션 첫 요청 이후로는 부담이 줄어듭니다. 문제는 출력 쪽입니다.

"The built-in Explanatory and Learning styles produce longer responses than Default by design, which increases output tokens."

— Claude Code 공식 문서, 토큰 사용량 설명

출력 토큰은 대개 입력보다 몇 배 비쌉니다. 하루 얼마쯤 든다는 숫자를 정리한 적이 있는데, 설명을 곁들이는 스타일을 켜두면 그 숫자가 조용히 올라갑니다. 배우려고 켰다가 계속 켜둔 채로 잊는 게 흔한 경로겠죠. 반대로 말하면 답이 장황해서 답답하다면 스타일부터 확인해볼 만합니다 — 그게 토큰도 아껴줍니다.

하나 더 있습니다. 플러그인도 출력 스타일을 실어 나를 수 있는데, 플러그인이 특정 항목을 켜두면 사용자가 고른 스타일을 덮어씁니다. 여러 플러그인이 그렇게 해두면 먼저 로드된 쪽이 이깁니다. 스타일이 내가 정한 대로 안 되어 있다면 플러그인 쪽도 의심해볼 자리입니다.

비슷해 보이는 기능들과 뭐가 다른가

문서가 헷갈리기 쉬운 다섯 기능을 한 표로 갈라놨습니다. 기준은 시스템 프롬프트를 건드리느냐입니다.

기능	작동 방식	쓸 때
출력 스타일	시스템 프롬프트를 고침	매 턴 다른 역할·말투·형식
CLAUDE.md	시스템 프롬프트 뒤에 사용자 메시지로 추가	프로젝트 관례·코드베이스 맥락
시스템 프롬프트 덧붙이기	아무것도 제거하지 않고 추가만	한 번 실행에만 필요한 추가
에이전트	자기 프롬프트·모델·도구로 별도 실행	범위를 따로 떼어낸 도우미
스킬	필요할 때만 작업별 지시를 불러옴	재사용하는 작업 흐름

줄여서 보면 출력 스타일만 유일하게 기존 것을 밀어낼 수 있는 자리입니다. 나머지는 더하기만 합니다. 그래서 이 기능이 편한 만큼 조심스러운 겁니다.

🧾 정직하게 — 제가 확인하지 못한 것

• 스타일별로 답이 얼마나 길어지는지 재보지 않았습니다. "설계상 더 길다"는 문서 표현이고, 몇 퍼센트인지는 문서에도 제 손에도 없습니다.
• 코딩 지시가 빠졌을 때 실제로 어떻게 달라지는지도 실험하지 않았습니다. 문서가 나열한 항목을 근거로 "이런 게 사라진다"고 옮겼을 뿐입니다.
• 버전에 따라 다릅니다. 제거된 명령어의 버전 번호도 문서에 적힌 값이고, 오래된 버전을 쓰고 있다면 여전히 동작할 수 있습니다.
• 내장 스타일 넷의 실제 시스템 프롬프트 전문은 공개돼 있지 않아, Proactive가 정확히 얼마나 더 밀어붙이는지는 문서 설명 이상으로 알 수 없었습니다.

🗺️ AI 지출 전체 지도

말투 설정 하나가 출력 토큰을 늘려 청구서에 얹힙니다. 이런 식으로 조용히 새는 자리가 곳곳에 있습니다. 구독과 종량제 선택부터 캐시 관리, 모델 조합, 팀 단위 청구까지 지금까지 확인한 것들을 일곱 단계 지도 한 장으로 묶어뒀습니다.

🧭 출력을 손대는 기능이 여럿이라 헷갈립니다

어디를 건드릴지부터 정하면 사고가 줄어듭니다. 형식을 확실히 고정해야 하면 전용 기능, 유연한 일관성이면 프롬프트 기법입니다. 근거를 고정하고 일을 쪼개는 것도 프롬프트 밖에서 일관성을 올리는 방법입니다. 공식 문서 한 페이지 안에도 이미 막힌 기법이 섞여 있으니 주석 상자를 건너뛰지 마세요.

자주 묻는 것

Q. 답이 장황한 게 싫으면 커스텀 스타일을 만들면 되나요?

만들 수 있지만 앞머리에 코딩 지시를 유지하는 항목을 꼭 켜세요. 그게 이 글의 요점입니다. 그리고 만들기 전에 지금 스타일이 뭔지부터 확인해보는 게 순서입니다 — 설명을 곁들이는 스타일이 켜져 있어서 길어진 거라면, 기본으로 돌리는 것만으로 해결됩니다.

Q. 팀 전체에 같은 스타일을 적용할 수 있나요?

저장 위치가 셋입니다 — 개인 폴더, 프로젝트 폴더, 관리 정책 폴더입니다. 프로젝트 폴더에 두면 저장소를 받는 사람이 같이 씁니다. 주의할 게 하나 있는데, 작업 디렉터리와 저장소 루트 사이의 여러 폴더에서 스타일을 읽어오고, 이름이 겹치면 작업 디렉터리에 가까운 쪽이 이깁니다. 하위 폴더에서 일할 때 다른 스타일이 걸릴 수 있다는 뜻입니다.

Q. Proactive 스타일을 켜면 권한 없이 막 실행하나요?

아닙니다. 문서가 이 부분을 분명히 갈라놨습니다 — Proactive는 자율 실행을 더 강하게 유도하는 지시이고 권한 모드는 그대로입니다. 무엇이 확인 없이 실행되는지는 여전히 권한 모드가 정합니다. 다만 "밀어붙이는 성향"과 "확인 안 하는 모드"가 겹치면 체감은 꽤 달라질 겁니다.

Q. CLAUDE.md에 "짧게 답해"라고 쓰면 안 되나요?

됩니다. 다만 문서의 구분에 따르면 CLAUDE.md는 프로젝트 관례와 코드베이스 맥락용이고, 매 턴 반복되는 말투·형식은 출력 스타일 쪽입니다. 붙는 자리도 다릅니다 — CLAUDE.md는 시스템 프롬프트 뒤에 사용자 메시지로 붙고, 출력 스타일은 시스템 프롬프트 안에 들어갑니다. 어느 쪽이 더 세게 먹히는지는 제가 실험해보지 않았습니다.

🧩 왜 통째로 빠지는지, 용어집이 설명해 줬습니다 (8월 16일 추가)

이 글은 말투만 바꾸려다 코딩 규칙이 통째로 빠진다는 이야기였습니다. 공식 용어집을 읽다가 그게 왜 그런지를 찾았습니다. 용어집은 헷갈리는 쌍을 갈라 설명하면서 CLAUDE.md는 시스템 프롬프트 뒤에 붙는 사용자 메시지, 출력 스타일은 시스템 프롬프트 자체라고 못 박습니다. 붙이는 것과 갈아끼우는 것의 차이입니다 — 그래서 CLAUDE.md는 아무리 써도 기존 규칙이 안 없어지고, 출력 스타일은 말투 한 줄만 적어도 원래 있던 소프트웨어 엔지니어링 지침이 사라집니다. 제가 이 글에서 "왜 이렇게 위험하게 만들었을까" 하고 넘어간 부분이 설계상 당연한 결과였던 셈입니다. 나머지 헷갈리는 쌍은 용어 정리 글에 모아뒀습니다.

✨ 오늘 확인한 것 정리

출력 스타일은 시스템 프롬프트를 직접 고치는, 유일하게 기존 것을 밀어낼 수 있는 설정이었습니다. 그래서 커스텀 스타일을 만들 때 코딩 지시를 유지하는 항목을 켜지 않으면 변경 범위·주석·검증 지시가 통째로 빠집니다 — 기본값이 빼는 쪽입니다. 바꿔도 지금 세션에는 안 먹고, 서브에이전트도 안 따릅니다. 설명을 곁들이는 스타일 둘은 설계상 답이 길어져 출력 토큰이 늘고요. 그리고 검색해서 나오는 전용 명령어는 이미 제거됐습니다.

※ 확인 경로(2026년 8월 16일 기준): code.claude.com/docs/en/output-styles. 인용문은 원문 그대로이며 번역은 제 것입니다.

※ 버전에 따라 동작이 달라지는 항목이 있습니다. 설명대로 안 되면 버전부터 확인하세요. 이 글은 특정 시점의 문서 스냅숏입니다.