[Claude Code] 클로드 코드 출력 스타일(output-style)에 대해서

클로드 코드를 쓰다 보면 "왜 이렇게 짧게 답하지?", "설명 좀 자세히 해주면 좋겠는데"라는 생각이 들 때가 있습니다. 이럴 때 유용한 기능이 바로 출력 스타일(Output Style)입니다. 오늘은 출력 스타일의 개념부터 커스텀 스타일 만드는 방법, 그리고 자주 헷갈리는 상태 표시줄·토큰 사용량 이슈까지 정리해보겠습니다.

 

출력 스타일이 필요한 이유

클로드 코드의 기본 응답 방식은 효율적인 개발 작업에 최적화되어 있습니다. 코드를 빠르게 작성하고 간결하게 응답하는 것이 기본 모드입니다. 하지만 사용자마다 필요한 응답 방식은 다릅니다. 예를 들자면 아래처럼요.

• 코딩 초보자는 왜 이렇게 짰는지에 대한 설명이 필요합니다.
• 코드를 배우는 중인 사람은 직접 구현해볼 기회가 필요합니다.
• 숙련된 개발자는 빠르고 간결한 결과만 있으면 충분합니다.
• 개발이 아닌 작업을 할 때는 완전히 다른 모드의 응답이 필요합니다.

이런 다양한 요구를 반영하기 위해 클로드 코드는 출력 스타일 기능을 제공합니다.

 

출력 스타일 확인 및 변경 방법

출력 스타일은 /output-style 명령어로 확인할 수 있습니다. 기본으로 제공되는 스타일 중 대표적인 것이 러닝(Learning) 모드입니다. 실제로 러닝 모드로 설정한 뒤 간단한 계산기 HTML을 요청하면, 클로드 코드는 코드를 구현하면서 학습을 위한 다양한 인사이트를 함께 제공합니다. 기본 모드와 달리 핵심 계산 로직은 직접 구현해보도록 유도하는 방식입니다.

 

참고로 작업이 끝나면 해당 파일에서 클로드 코드가 만들어둔 함수 부분을 직접 채워 넣어야 합니다. 즉, 클로드 코드가 전체 컨텍스트와 태스크를 제공하고, 핵심 구현 부분은 사용자가 직접 완성하도록 여지를 남겨두는 방식입니다.

 

출력 스타일은 /output-style 명령어를 통해 언제든 다른 모드로 손쉽게 변경할 수 있습니다. 특정 프로젝트에서 하나의 스타일을 계속 고정해서 쓰고 싶다면, 세팅 파일에서 출력 스타일을 고정하는 것도 가능합니다. 이렇게 설정하면 이후 해당 프로젝트에서는 지정한 스타일로 계속 응답합니다.

 

 나만의 커스텀 출력 스타일 만들기 

모든 프로젝트에서 사용 : ~\.claude\output-styles\beginner.md
현재 프로젝트에서 사용 : 현재 프로젝트 폴더\.claude\output-styles\beginner.md

 

기본 제공 스타일 외에 직접 나만의 출력 스타일을 만들 수도 있습니다. 모든 프로젝트에 적용하고 싶은 경우 사용자 홈 디렉터리의 .claude 디렉터리 안에 output-styles 디렉터리를 만들고, 그 안에 마크다운(.md) 설정 파일을 작성하시면 되고 특정 프로젝트에만 적용하고 싶은 경우 해당 프로젝트 디렉터리 안에 output-styles 디렉터리를 만들어 마찬가지로 마크다운 파일(.md)을 만들어서 적용하시면 됩니다. 참고로 디렉터리 이름을 만들 때 한 가지 주의할 점이 있습니다. 정확한 이름은 output-styles이며, 뒤에 반드시 s가 붙습니다. 오타로 인해 스타일이 적용되지 않는 경우가 많으니 디렉터리명을 꼭 확인하시면 좋을것 같습니다.

 

설정 파일 작성 방법

output-styles 디렉터리 안에 원하는 이름으로 마크다운 파일을 만듭니다. 

---
name: Beginner Developer
description: 코딩 초보자를 위한 친절한 설명 스타일
keep-coding-instructions: true
---

# Beginner Developer Style

당신은 코딩을 처음 배우는 사람을 돕는 친절한 멘토입니다.

## 주요 행동 방식

- 코드를 작성할 때마다 왜 이렇게 작성했는지 이유를 함께 설명하세요
- 전문 용어를 사용할 때는 쉬운 말로 한 번 더 풀어서 설명하세요
- 가능하면 비유나 실생활 예시를 들어 개념을 이해하기 쉽게 전달하세요
- 코드 전체를 한 번에 주지 말고, 핵심 로직 일부는 `TODO(human)` 형태로 남겨서 직접 채워보도록 유도하세요
- 자주 발생하는 실수나 흔한 오해가 있다면 미리 짚어주세요
- 각 단계가 끝날 때마다 짧게 요약하며 다음에 무엇을 배우게 될지 안내하세요

## 톤 & 형식

- 친절하고 격려하는 어조를 유지하세요
- 한 번에 너무 많은 정보를 주지 말고, 단계별로 나누어 설명하세요
- 결과 코드보다 "왜"와 "어떻게"에 더 무게를 두세요

1. 프론트매터(Frontmatter) - 출력 스타일의 메타 정보를 담는 부분입니다. name(스타일 이름)과 description(스타일 설명)을 작성합니다.
2. 본문 - 실제로 클로드 코드가 어떻게 응답해야 하는지에 대한 구체적인 지침을 작성하는 부분입니다.

프론트매터에 입력한 이름과 설명은 /output-style 명령어로 스타일 목록을 확인할 때 그대로 표시됩니다. 참고로 파일을 저장한 직후에는 바로 반영되지 않을 수 있는데, 이때는 클로드 코드를 종료했다가 다시 실행하면 정상적으로 목록에 나타납니다.

 

반드시 주의해야 할 옵션 하나

커스텀 출력 스타일을 만들 때 꼭 확인해야 할 프론트매터 옵션이 있습니다. 바로 코딩 지침 유지 여부를 결정하는 옵션입니다. 클로드 코드에는 기본적으로 "코드를 작성하면 테스트를 수행한다", "변경 사항을 검증한다"와 같은 코딩 관련 지침이 내장되어 있습니다. 이 옵션은 커스텀 스타일을 적용했을 때 이런 기본 코딩 지침을 그대로 유지할지 여부를 결정합니다. 이 옵션의 기본값은 false입니다. 즉, 아무 설정 없이 커스텀 스타일을 만들면 기존의 코딩 관련 지침이 비활성화됩니다.

• 코딩 작업용 커스텀 스타일을 만드는 경우: 이 옵션을 반드시 추가하고 true로 설정해야 합니다.
• 글쓰기 등 코딩과 무관한 작업용 스타일을 만드는 경우: 굳이 값을 바꾸지 않고 기본값(false)으로 두어도 무방합니다.

이 부분을 놓치면 커스텀 스타일 적용 후 코드 검증이나 테스트 관련 동작이 사라져서 당황할 수 있으니 꼭 챙겨야 하는 옵션입니다.

 

상태 표시줄, 출력 스타일과 토큰 사용량의 관계

"상태 표시줄과 출력 스타일이 토큰 사용량에 영향을 줄까?" 문득 이 생각이 들 수 있습니다. 이 부분을 한번 정리해보겠습니다. 클로드 코드의 토큰 비용은 컨텍스트 크기에 비례합니다. 여기서 컨텍스트란 사용자가 작성하는 프롬프트, 첨부한 이미지, 참조하는 파일 등 요청에 포함되는 모든 내용과 클로드 코드가 응답하는 내용을 합친 것을 의미합니다.

 

상태 표시줄(Status Line)

상태 표시줄은 토큰을 전혀 소비하지 않습니다. 상태 표시줄은 클로드의 대화 컨텍스트 밖에서 별도의 스크립트로 실행되기 때문에, 아무리 복잡하게 설정하더라도 토큰 사용량에는 영향을 주지 않습니다.

 

출력 스타일(Output Style)

출력 스타일은 응답 방식 자체를 결정하기 때문에 토큰 사용량에 영향을 줍니다. 이유는 크게 두 가지입니다.

1. 시스템 프롬프트가 변경됩니다. 시스템 프롬프트는 클로드에게 "너는 이런 역할을 하고, 이렇게 행동해라"라고 알려주는 기본 지침 문서로, 메시지를 보낼 때마다 함께 전송됩니다. 출력 스타일을 바꾸면 이 시스템 프롬프트의 내용도 바뀌고, 매 요청마다 함께 전달되기 때문에 길어질수록 처리해야 할 토큰이 늘어납니다.
2. 응답 방식 자체가 달라집니다. 스타일에 따라 간결하게 답할 수도 있고, 더 자세하게 설명을 덧붙일 수도 있기 때문에 자연히 토큰 사용량에 영향을 줍니다.

다만 출력 스타일로 인한 토큰 영향은 크지 않고 미미한 수준입니다. 실제로 신경 써야 할 부분은 컨텍스트 윈도우에 계속 쌓이는, 사용자가 직접 추가하는 컨텍스트들입니다.

 

정리

• 출력 스타일은 클로드 코드의 응답 방식(간결함, 설명 수준, 학습 유도 여부 등)을 사용자에 맞게 조정하는 기능입니다.
• 기본 제공되는 러닝 모드처럼, 핵심 로직은 직접 구현하도록 유도하는 스타일도 있습니다.
• 커스텀 스타일은 .claude/output-styles 디렉터리(또는 프로젝트 디렉터리 내 동일한 이름의 디렉터리)에 파일을 추가해서 만들 수 있으며, 디렉터리명의 마지막 s를 빠뜨리지 않아야 합니다.
• 코딩용 커스텀 스타일을 만들 때는 코딩 지침 유지 옵션을 반드시 true로 설정해야 합니다.
• 상태 표시줄은 토큰을 소비하지 않지만, 출력 스타일은 시스템 프롬프트 변경으로 인해 토큰 사용량에 약간의 영향을 줍니다. 다만 그 영향은 미미한 수준이고, 실제로 중요한 것은 컨텍스트 윈도우 관리입니다.