Claude Code 출력 스타일 설정 및 변경 방법

Claude Code의 출력 스타일이란 무엇인가

Claude Code의 출력 스타일은 Claude Code가 시스템 프롬프트에 덧붙이는 지침 블록입니다. 이 스타일은 Claude가 사용자에게 응답하는 방식, 즉 Claude가 취하는 역할과 출력물의 형태를 변경합니다. 이 기능은 Claude에게 코드베이스에 관한 정보를 학습시키거나, 무언가를 실행할 권한을 부여하지는 않습니다.

Claude Code는 5가지 내장 스타일을 제공합니다. 사용자가 선택한 스타일은 outputStyle 설정 키에 저장되며, 이 키는 세션이 시작될 때 한 번만 읽힙니다. 세션 도중에 스타일을 변경하더라도 해당 설정은 저장만 될 뿐, 세션을 새로 시작하기 전까지는 적용되지 않기 때문에 이 기능과 관련하여 혼란이 자주 발생합니다.

VPS 환경에서 이는 단순히 보기 좋은 설정을 선택하는 문제를 넘어섭니다. SSH(secure shell) 연결을 통해, 보통 tmux 창 내부에서 대화 내용을 확인하게 되므로, Claude가 출력하는 모든 줄은 사용자가 기다려야 하는 시간이며 고정된 크기의 스크롤백 버퍼를 차지하는 데이터가 됩니다.

outputStyle 설정 위치

/config 메뉴의 Output style에서 스타일을 선택하십시오. Claude Code는 선택한 내용을 작업 중인 프로젝트의 .claude/settings.local.json에 기록합니다.

독립형 /output-style 명령어는 더 이상 존재하지 않습니다. 해당 명령어는 v2.1.73에서 지원이 중단되었고 v2.1.91에서 제거되었으므로, 현재 빌드에서는 아무런 동작을 하지 않습니다. 오래된 가이드를 따르기 전에 현재 실행 중인 버전을 확인하십시오. 이 페이지의 버전은 2026년 8월 기준으로 확인되었습니다.

claude --version

설정 키를 직접 지정할 수도 있습니다. 키를 저장할 수 있는 설정 파일은 4가지가 있으며, 범위가 좁은 설정이 넓은 설정을 덮어씁니다.

• ~/.claude/settings.json은 사용자 파일입니다. 해당 머신의 모든 프로젝트에 적용됩니다.
• .claude/settings.json는 프로젝트 파일입니다. git에 커밋되므로 저장소를 복제하는 모든 사용자에게 적용됩니다.
• .claude/settings.local.json는 로컬 프로젝트 파일입니다. 커밋되지 않으며, 위의 두 파일을 모두 덮어씁니다. /config 메뉴가 기록하는 파일이 바로 이것입니다.
• IT 팀이 Linux의 /etc/claude-code/과 같은 시스템 경로를 통해 배포하는 관리형 설정은 다른 모든 설정을 덮어씁니다.

키 값은 스타일 이름입니다:

{
  "outputStyle": "Concise"
}

단일 세션에만 적용하려면 명령줄에서 동일한 키를 전달하십시오. --settings 플래그는 경로 또는 인라인 JSON 문자열을 인자로 받으며, 해당 실행 동안 설정 파일의 동일한 키 값을 덮어씁니다:

claude --settings '{"outputStyle": "Concise"}'

메뉴 레이블과 슬래시 명령어는 이 기능이 도입된 이후 최소 한 번 이상 변경되었습니다. 하지만 outputStyle 키는 변경되지 않았습니다. 가이드의 스크린샷이 실제 화면과 일치하지 않을 경우, 키를 직접 설정한 뒤 /status을 사용하여 현재 적용 중인 설정 소스를 확인하십시오.

새로운 출력 스타일이 즉시 적용되지 않는 이유

Claude Code는 세션이 시작될 때 시스템 프롬프트를 한 번 빌드하며, 출력 스타일은 해당 시스템 프롬프트의 일부로 포함됩니다. 따라서 세션 실행 중에 설정을 변경하면 값은 저장되지만, 실행 중인 세션은 시작 시점에 빌드된 프롬프트를 계속 전송하므로 눈에 띄는 변화가 없습니다. 새로운 스타일은 다음 /clear 또는 다음 실행 시점에 로드됩니다.

/clear
/context

/context는 시스템 프롬프트를 포함하여 현재 컨텍스트 창을 차지하고 있는 내용을 범주별로 나누어 출력합니다. 각 스타일 하에서 새로운 세션을 시작하고 실행해 보면, 시스템 프롬프트 라인을 통해 입력 측의 차이를 비교할 수 있습니다. 또한 이는 사용자 지정 스타일이 정상적으로 로드되었는지 확인하는 가장 빠른 방법이기도 합니다. 컨텍스트 창을 채우는 요소들에 대한 더 자세한 내용은 Claude Code 세션에서 컨텍스트가 채워지는 방식을 참조하십시오.

설정이 실시간으로 적용되지 않고 대기하는 데에는 이유가 있습니다. API는 각 요청의 시작 부분과 일치하는 프롬프트 캐시에서 반복 요청을 처리하며, 시스템 프롬프트는 바로 그 시작 부분에 위치합니다. 대화 중간에 이를 다시 작성하면 그 뒤에 있는 모든 내용이 무효화되므로, 다음 턴에서 전체 기록을 새로운 입력으로 다시 처리해야 합니다. 세션 시작 시점에 스타일을 고정하면 이러한 비용을 방지할 수 있습니다. 스타일 전환은 비용이 저렴하며, 단지 세션을 초기화(clear)하기만 하면 됩니다.

내장 출력 스타일별 트랜스크립트 변경 사항

• Default는 소프트웨어 엔지니어링 작업을 위해 작성된 Claude Code의 기본 시스템 프롬프트입니다.
• Concise는 결과부터 제시합니다. 서론과 작업 과정에 대한 설명을 생략하며, 상세한 내용을 요청하기 전까지 답변을 간결하게 유지합니다. 이 스타일을 사용해도 내부적인 엔지니어링 작업은 동일하게 수행됩니다. 오류 보고나 보안 경고는 절대 생략하지 않으며, 파괴적인 작업을 수행하기 전에는 반드시 전체 내용을 확인합니다. 이 스타일은 Claude Code v2.1.237 버전 이상이 필요합니다.
• Explanatory는 작업 단계 사이에 교육적인 "Insights(통찰)"를 추가하여, 왜 그러한 구현 방식을 선택했는지와 코드베이스에서 이미 사용 중인 패턴이 무엇인지 설명합니다. 따라서 트랜스크립트의 길이는 의도적으로 길어집니다.
• Learning은 한 단계 더 나아갑니다. Claude가 통찰을 공유한 뒤, 사용자가 직접 코드의 작은 부분을 작성하도록 요청하며 파일 내 각 지점에 TODO(human) 주석을 표시합니다.
• Proactive는 Claude가 질문하는 대신 직접 행동하게 합니다. 일상적인 결정에 대해 합리적인 가정을 내리고 확인을 위해 작업을 멈추지 않습니다.

마지막 항목은 사용자들이 자주 오해하는 부분이므로 주의 깊게 읽어야 합니다. Proactive는 시스템 프롬프트 내의 지침이며, Claude가 시도하는 작업의 방식을 변경합니다. 실제로 사용자에게 묻지 않고 실행되는 작업은 사용자의 권한 모드 설정에 따라 결정되며, 이는 서버를 무인 상태로 둘 때 가장 중요한 설정입니다. 이에 관한 내용은 자동 모드 및 Claude Code의 권한 모드에서 다룹니다.

출력 스타일과 CLAUDE.md, 훅, 서브 에이전트의 차이

이러한 인터페이스는 모두 Claude의 동작 방식을 제어하는 것처럼 느껴지지만, 실제로는 서로 다른 계층에서 작동합니다.

• 출력 스타일(Output style)은 시스템 프롬프트에 추가됩니다. 메인 대화의 모든 응답에 적용됩니다.
• CLAUDE.md는 시스템 프롬프트 이후 사용자 메시지로 추가됩니다. 프로젝트 관례와 코드베이스 관련 사실을 기록하는 곳입니다.
• --append-system-prompt는 시스템 프롬프트에 텍스트를 추가하여 단일 호출에 적용하며, 기존 내용을 삭제하지 않습니다. 출력 스타일의 일회성 버전이라고 할 수 있습니다.
• 훅(Hook)은 특정 이벤트가 발생할 때 Claude Code가 스스로 실행하는 셸 명령어입니다. 하네스(harness)에 의해 강제되므로 Claude가 실행 여부를 결정하는 것과 관계없이 항상 동작합니다. Claude Code 훅의 기능과 제약 사항을 참조하십시오.
• 서브 에이전트(Subagent)는 고유한 시스템 프롬프트와 도구 세트를 가지고 실행됩니다.

첫 두 가지 방식 중 무엇을 선택할지는 간단한 테스트로 결정할 수 있습니다. 프로젝트에 관한 사실 정보는 Claude가 알아야 하므로 CLAUDE.md에 작성합니다. 문체는 답변이 읽히는 방식에 관한 것이므로 출력 스타일에 작성합니다. 모델의 판단과 관계없이 매번 반드시 실행되어야 하는 작업은 훅을 사용합니다.

출력 스타일은 메인 대화에만 적용됩니다. 서브 에이전트는 고유한 시스템 프롬프트로 새로운 대화를 시작하므로 사용자의 스타일을 상속받지 않습니다. 현재 대화를 포크(fork)하는 경우는 예외이며, 포크는 부모의 시스템 프롬프트를 그대로 상속받습니다. 만약 서브 에이전트의 작성 방식이 마음에 들지 않는다면, 출력 스타일을 수정하기보다 해당 에이전트의 파일을 수정하십시오.

사용자 지정 출력 스타일 작성 방법

사용자 지정 출력 스타일은 프론트매터(frontmatter)를 포함한 마크다운 파일입니다. 모든 프로젝트에서 사용하려면 홈 디렉터리 아래에 저장하고, 코드와 함께 관리하려면 리포지토리 내부에 저장하십시오. 사용자 디렉터리는 ~/.claude/output-styles/이며 프로젝트 디렉터리는 .claude/output-styles/입니다.

mkdir -p ~/.claude/output-styles
cat > ~/.claude/output-styles/terse-ops.md <<'EOF'
---
name: Terse ops
description: Command first, explanation after, for SSH sessions
keep-coding-instructions: true
---

Lead with the command or the file change. Put the explanation after it, in two sentences or fewer.

Do not narrate what you are about to do. Report what you did.

When a command can fail, print the one check that proves it worked and say what a healthy result looks like.
EOF

세션을 시작하고 /config을 여십시오. 작성한 설명과 함께 Output style 목록에 스타일이 나타납니다. 목록에 없다면 파일이 읽히지 않는 상태이므로, 경로를 확인하고 --- 프론트매터 블록이 파일의 가장 처음에 있는지 확인하십시오. 프론트매터에서 name를 설정하지 않으면 파일 이름이 스타일 이름이 되므로, 이 파일은 terse-ops이 아닌 Terse ops으로 표시됩니다.

스타일을 선택하거나 해당 이름을 키로 설정하고 초기화하십시오:

{
  "outputStyle": "Terse ops"
}

파일이 조정(adjustment)인지 대체(replacement)인지 결정하는 필드가 하나 있습니다. keep-coding-instructions의 기본값은 false이며, 이는 사용자 지정 스타일이 Claude Code의 내장 소프트웨어 엔지니어링 지침을 제외하고 텍스트만으로 동작함을 의미합니다. 내장 지침은 Claude에게 변경 범위를 지정하고 작업 내용을 검증하는 방법을 알려주는 역할을 합니다. 해당 지침이 필요 없는 글쓰기 보조 도구나 데이터 분석가용으로 사용할 때는 이 필드를 생략하십시오. 코드를 다루는 작업이라면 true로 설정하십시오. 그렇지 않으면 꼼꼼하던 엔지니어가 갑자기 스스로의 작업을 검증하지 않는 이유를 궁금해하게 될 것입니다.

description는 /config 선택기에서 이름 옆에 표시되는 줄입니다. 6개월 뒤 두 가지 스타일 중 하나를 선택해야 하는 상황을 고려하여 작성하십시오.

SSH 환경에서 간결한 스타일이 다른 이유

VPS에서는 로컬 터미널이 가지지 않는 여러 계층을 거쳐 기록을 읽게 되며, 각 계층은 장황함에 따른 비용을 발생시킵니다.

첫 번째는 스크롤백입니다. tmux의 각 창은 history-limit로 설정된 고정된 줄 수를 유지하며, 기본값은 2000입니다. 서술형 기록은 이 버퍼를 더 빨리 채우므로 세션 앞부분이 더 빨리 밀려나고, 확인하려던 출력 내용이 사라집니다. 공간이 더 필요하다면 값을 높이십시오:

echo 'set -g history-limit 20000' >> ~/.tmux.conf
tmux source-file ~/.tmux.conf

이후 생성되는 창은 각각 20000줄을 유지하지만, 창마다 메모리 사용량이 증가합니다. 이미 열려 있는 창은 창 생성 시 버퍼 크기가 고정되므로 기존 제한을 유지합니다. 세션 레이아웃을 구성 중이라면 VPS의 tmux에서 Claude Code 실행하기를 참조하십시오.

두 번째는 지연 시간입니다. 응답은 생성되는 즉시 터미널로 스트리밍됩니다. 왕복 시간(RTT)이 긴 연결 환경에서는 긴 서론을 읽느라 정작 답변이 나타나기까지 기다리는 시간이 길어집니다.

세 번째는 출력 토큰입니다. 서술형으로 작성된 모든 줄은 출력 비용으로 청구됩니다. 'Explanatory'와 'Learning' 스타일은 설계상 더 깁니다. 'Concise' 스타일은 Claude에게 기본적으로 짧은 응답을 유지하도록 지시하므로 설계상 더 짧습니다.

이 페이지를 포함하여 누구의 수치도 맹신하지 마십시오. 차이의 크기는 프롬프트, 모델, 작업 내용에 따라 달라지므로 직접 전후를 측정해야 합니다. 두 개의 새로운 세션에서 동일한 실제 작업을 각각 'Default'와 'Concise' 스타일로 실행한 뒤 비교하십시오. 상태 표시줄(statusline)이 가장 쉬운 측정 도구입니다. Claude Code는 이미 스타일 이름과 토큰 수를 포함한 JSON 객체를 stdin으로 스크립트에 전달하기 때문입니다:

cat > ~/.claude/statusline.sh <<'EOF'
#!/bin/bash
input=$(cat)
style=$(echo "$input" | jq -r '.output_style.name // "default"')
out=$(echo "$input" | jq -r '.context_window.total_output_tokens // 0')
cost=$(echo "$input" | jq -r '.cost.total_cost_usd // 0')
echo "style=$style out=$out cost=$cost"
EOF
chmod +x ~/.claude/statusline.sh

statusLine 설정을 해당 스크립트로 지정하십시오:

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

이제 세션 하단 막대에 활성 스타일과 생성된 토큰 수가 표시되며, 이것이 바로 필요한 전후 비교 데이터입니다. 이 스크립트는 명령줄 JSON 파서인 jq를 필요로 하므로, 먼저 sudo apt install -y jq으로 설치하십시오. 막대가 비어 있다면 스크립트를 직접 실행하고 JSON을 파이프로 전달해 보십시오. 상태 표시줄은 0이 아닌 종료 코드를 반환하면 아무것도 출력하거나 보고하지 않기 때문입니다. 사용자 지정 Claude Code 상태 표시줄에서 해당 객체의 나머지 필드 목록을 확인할 수 있습니다. 세션 측면이 아닌 비용 청구 측면의 정보는 Claude Code 토큰이 실제로 소비되는 곳과 Claude Code 지출 추적 도구를 읽어 보십시오.

현재 적용된 출력 스타일 확인 방법

추측하지 말고 다음 점검 항목을 사용하십시오.

• /status은 현재 세션에 적용된 설정 소스 목록을 나열하며, 조직에서 관리하는 설정이 적용 중인지도 포함합니다.
• /context는 컨텍스트 창 분석에서 로드된 시스템 프롬프트를 하나의 범주로 표시합니다.
• claude doctor은 세션을 시작하지 않고 셸에서 실행하며, 설치 및 설정 진단 정보를 출력하고 유효하지 않은 설정 파일을 보고합니다.

스타일이 적용되지 않는다면 원인은 거의 항상 두 가지 중 하나입니다. 첫 번째는 세션 도중에 스타일을 변경한 경우이므로 /clear를 실행하십시오. 두 번째는 우선순위 문제입니다. .claude/settings.local.json는 .claude/settings.json을 재정의하며, 두 설정 모두 ~/.claude/settings.json보다 우선합니다. /config 선택기는 로컬 파일에 기록하므로, 팀이 .claude/settings.json에 커밋한 스타일은 누군가 메뉴를 한 번이라도 사용한 기기에서 조용히 재정의됩니다. /status은 어떤 소스가 우선권을 가졌는지 알려줍니다.

JSON 구문 오류가 발생해도 동일한 증상이 나타나지만 해결 방법은 다릅니다. claude doctor은 구문 분석에 실패한 파일 이름을 알려주므로, 더 복잡한 원인을 찾기 전에 먼저 실행해 볼 가치가 있습니다.

FAQ

/output-style 명령이 작동하지 않는 이유는 무엇입니까?

해당 명령은 v2.1.73에서 지원이 중단되었고 v2.1.91에서 제거되었습니다. 따라서 2026년 중반 이후 빌드 버전에서는 해당 명령이 존재하지 않습니다. claude --version를 실행하여 현재 버전을 확인하십시오. Output style 항목 아래의 /config에서 스타일을 선택하거나, 설정 파일에서 outputStyle 키를 설정하십시오. 이 키는 명령보다 오래 유지되었으므로, 직접 설정하는 방법을 개인 메모에 기록해 두는 것이 좋습니다.

출력 스타일을 변경했는데 아무런 변화가 없습니다. 왜 그렇습니까?

출력 스타일은 시스템 프롬프트의 일부이며, Claude Code는 세션이 시작될 때 시스템 프롬프트를 한 번만 생성합니다. 세션 도중에 변경한 내용은 저장되지만 적용되지는 않습니다. 실행 중인 세션은 시작 시점에 생성된 프롬프트를 계속 사용하기 때문입니다. /clear를 실행하거나 새 세션을 시작하십시오. 그래도 적용되지 않는다면 /status을 실행하여 어떤 설정 소스가 우선순위를 가졌는지 확인하십시오. .claude/settings.local.json은 .claude/settings.json을 재정의하며, 두 설정 모두 ~/.claude/settings.json보다 우선합니다.

Concise 출력 스타일을 사용하면 비용이 절감됩니까?

이 스타일은 Claude에게 기본적으로 짧은 응답을 하도록 지시하므로, 예상대로 출력 토큰을 줄여줍니다. 절감 폭은 프롬프트와 모델에 따라 다르므로, 공개된 수치는 다른 사용자의 작업 결과로 간주하십시오. 직접 측정하려면 새 세션에서 각 스타일별로 /context을 실행하여 입력 측면을 확인한 뒤, 동일한 작업을 수행하여 출력 토큰 수를 비교하십시오. Concise 스타일은 오류 보고서나 보안 경고를 단축하지 않으므로, 반드시 읽어야 할 내용은 온전히 유지됩니다.

출력 스타일을 바꾸면 서브 에이전트의 작성 방식도 달라집니까?

아니요. 출력 스타일은 메인 대화에만 적용됩니다. 서브 에이전트는 고유한 시스템 프롬프트와 도구 세트를 가진 별도의 대화를 시작하기 때문입니다. 현재 대화를 분기(fork)하는 경우는 예외인데, 분기된 대화는 부모의 시스템 프롬프트를 그대로 상속받기 때문입니다. 서브 에이전트의 응답 방식을 변경하려면 해당 에이전트의 파일을 직접 수정하십시오.

출력 스타일을 설정하면 Claude가 묻지 않고 명령을 실행할 수 있습니까?

아니요. 출력 스타일은 시스템 프롬프트 내의 텍스트일 뿐이므로, Claude가 수행하려는 작업에만 영향을 줄 수 있습니다. Proactive 스타일을 사용하면 Claude가 일상적인 결정에서 멈추지 않고 추측하여 행동할 수 있지만, 여전히 명령을 스스로 승인할 수는 없습니다. 명령 실행 여부는 사용자의 권한 모드(permission mode)가 결정하며, 서버에서 세션을 실행한 채 자리를 비우기 전에 확인해야 할 설정은 바로 이것입니다.