클로드 코드 Output styles 사용법: 설명형·학습형으로 답변 방식을 고정하는 팁

TL;DR

클로드 코드 Output styles는 Claude Code가 무엇을 아는지를 바꾸는 기능이 아니라, 매 답변을 어떤 역할과 톤, 형식으로 할지 고정하는 설정입니다. 공식 문서 기준으로 Default 외에 Proactive, Explanatory, Learning 스타일이 있으며, 반복해서 "설명도 같이 해줘", "내가 일부 코드를 직접 써 보게 해줘"라고 말하는 사람에게 특히 유용합니다. 다만 Output style은 권한 모드가 아니므로, 파일 수정이나 명령 실행의 안전성은 permissions, permission mode, diff 검토로 따로 관리해야 합니다.

핵심 3줄 요약

• 핵심 1
  Output styles는 Claude Code의 시스템 프롬프트를 바꿔 응답 역할, 톤, 출력 형식을 고정하는 기능입니다.
• 핵심 2
  Explanatory는 코딩을 도와주면서 구현 판단과 코드 구조를 설명받고 싶을 때, Learning은 사용자가 일부 코드를 직접 채우며 배우고 싶을 때 적합합니다.
• 핵심 3
  Proactive는 더 적극적으로 실행하게 만드는 스타일이지만, 권한 승인 자체를 없애는 기능은 아니므로 파일 수정과 명령 실행은 계속 검토해야 합니다.

이 글에서 다룰 내용

클로드 코드 Output styles란?

클로드 코드 Output styles는 Claude Code가 답변하는 방식을 바꾸는 설정입니다. Anthropic 공식 문서는 Output styles가 Claude의 지식을 바꾸는 것이 아니라, 시스템 프롬프트를 수정해 역할, 톤, 출력 형식을 조정한다고 설명합니다.

쉽게 말하면 "이 프로젝트에서는 계속 설명형으로 말해줘", "내가 배우면서 코딩하게 해줘", "일반 코딩 도우미가 아니라 데이터 분석가처럼 말해줘" 같은 반복 지시를 매번 붙이지 않아도 되게 만드는 장치입니다.

한 문장 정의: 클로드 코드 Output styles는 Claude Code의 기본 답변 습관을 프로젝트나 사용자 목적에 맞게 고정하는 응답 방식 설정입니다.

마케터와 기획자에게도 의미가 있습니다. 코딩 에이전트를 쓰다 보면 답변이 너무 짧거나, 반대로 너무 많은 기술 용어로 흐르는 경우가 많습니다. Output style을 잘 고르면 Claude가 변경을 제안할 때 왜 그런 선택을 했는지, 내가 무엇을 확인해야 하는지, 어느 부분을 직접 채워야 하는지 더 일정한 방식으로 받을 수 있습니다.

한 줄 정리: Output styles는 "이번 한 번만 이렇게 답해줘"가 아니라 "이 세션에서는 계속 이런 방식으로 일해줘"에 가깝습니다.

Default, Proactive, Explanatory, Learning 차이

공식 문서 기준으로 Claude Code에는 기본 Default 스타일 외에 세 가지 내장 Output style이 있습니다.

1. Default

Default는 Claude Code의 기본 시스템 프롬프트입니다. 빠르게 코드를 읽고, 수정하고, 검증하는 일반적인 소프트웨어 작업에 맞춰져 있습니다. 이미 Claude Code 사용에 익숙하고, 설명보다 결과와 검증이 우선이라면 Default가 가장 무난합니다.

2. Proactive

Proactive는 Claude가 더 적극적으로 실행하도록 유도하는 스타일입니다. 사소한 결정을 계속 물어보기보다 합리적인 가정을 두고 진행하는 쪽에 가깝습니다.

중요한 점은 Proactive가 권한 모드를 바꾸는 것은 아니라는 점입니다. 공식 문서는 Proactive가 더 강한 실행 지침을 주지만 permission mode를 바꾸지 않기 때문에 도구 실행 전 권한 프롬프트는 계속 보인다고 설명합니다.

3. Explanatory

Explanatory는 Claude가 코딩을 도와주면서 중간중간 구현 선택과 코드베이스 패턴을 설명해 주는 스타일입니다. "고치긴 고쳤는데 왜 이렇게 바꿨는지 모르겠다"는 상황을 줄이는 데 좋습니다.

4. Learning

Learning은 사용자가 직접 일부 코드를 채워 보도록 유도하는 학습형 스타일입니다. 공식 문서는 Learning이 협업형 learn-by-doing 모드이며, Claude가 TODO(human) 표시를 코드에 넣어 사용자가 직접 구현할 작은 부분을 남길 수 있다고 설명합니다.

핵심 인사이트: Explanatory는 "이해하면서 맡기기", Learning은 "직접 해 보면서 배우기", Proactive는 "반복 확인을 줄이고 더 밀도 있게 진행하기"에 가깝습니다.

누가 쓰면 좋은가?

첫째, Claude Code를 막 시작한 비개발자와 기획자에게 좋습니다. 자동화 스크립트, 블로그 발행 도구, 랜딩페이지 문구, CSS 조정처럼 작은 수정은 AI에게 맡길 수 있지만, 왜 바뀌었는지 모르면 다음에 같은 문제가 생겼을 때 대응하기 어렵습니다. Explanatory로 시작하면 변경 이유를 함께 볼 수 있습니다.

둘째, 주니어 개발자에게 좋습니다. Learning 스타일은 Claude가 모든 코드를 대신 완성하기보다 일부 구현을 사용자가 직접 해 보게 만듭니다. 코드 리뷰를 받는 것과 실습을 섞은 방식이라, 단순 복사보다 학습 효과가 큽니다.

셋째, 반복 작업을 빠르게 처리하는 운영자에게 좋습니다. 매번 "간단히 설명해줘", "먼저 계획을 보여줘", "표로 정리해줘" 같은 말을 붙이고 있다면 Output style이나 커스텀 스타일로 고정할 수 있습니다.

반대로 이미 Claude Code의 기본 흐름에 익숙하고, 설명보다 속도가 중요하며, 작은 명령을 자주 실행하는 사람은 Default가 더 편할 수 있습니다.

언제 쓰면 좋은가?

Output styles는 다음 상황에서 특히 유용합니다.

1. Claude에게 매번 같은 답변 형식을 요구한다.
2. 코드 수정 이유를 함께 이해하고 싶다.
3. 초보자가 직접 일부 코드를 써 보며 배우고 싶다.
4. 프로젝트마다 답변 톤이 달라 헷갈린다.
5. 코딩이 아닌 문서 정리, 데이터 분석, 운영 체크리스트처럼 다른 역할로 Claude Code를 쓰고 싶다.

예를 들어 자동화 스크립트를 고칠 때는 Explanatory가 좋습니다. Claude가 어떤 파일을 읽었고, 왜 그 줄을 바꿨고, 어떤 테스트를 확인해야 하는지 설명해 주면 검수 부담이 줄어듭니다.

반대로 코딩 공부를 겸한다면 Learning이 좋습니다. 모든 답을 완성해 주는 대신 핵심 구조를 설명하고, 사용자가 TODO(human) 부분을 채우게 만들 수 있기 때문입니다.

실전 팁: 처음에는 Default에서 바로 Proactive로 가지 말고, Explanatory를 며칠 써 본 뒤 반복 설명이 충분히 이해될 때 Proactive를 검토하는 편이 안전합니다.

따라 하는 순서 1: 현재 문제를 먼저 정한다

Output style을 고르기 전에 지금 불편한 점을 먼저 정해야 합니다.

다음 중 어디에 가까운지 골라 보세요.

1. 결과는 나오지만 이유를 이해하기 어렵다.
2. Claude가 너무 자주 물어봐서 흐름이 끊긴다.
3. 내가 직접 코드를 배워 가며 고치고 싶다.
4. 매번 같은 형식의 보고나 체크리스트가 필요하다.

1번이면 Explanatory, 2번이면 Proactive, 3번이면 Learning, 4번이면 커스텀 Output style 후보입니다.

한 줄 정리: Output style은 멋있어 보이는 이름으로 고르는 기능이 아니라, 현재 작업의 병목에 맞춰 고르는 설정입니다.

따라 하는 순서 2: /config에서 Output style을 선택한다

Anthropic 공식 문서는 Output style 변경 방법으로 /config를 안내합니다. Claude Code 안에서 /config를 실행하고 Output style 항목을 선택하면 메뉴에서 스타일을 고를 수 있습니다.

이때 주의할 점이 있습니다. 예전 standalone /output-style 명령은 공식 문서 기준 v2.1.73에서 deprecated 되었고 v2.1.91에서 제거되었습니다. 최신 문서 기준으로는 /config를 쓰거나 settings 파일의 outputStyle 값을 직접 설정하는 방식이 맞습니다.

설정은 로컬 프로젝트 수준의 .claude/settings.local.json에 저장될 수 있습니다. 개인 실험이라면 local 설정이 좋고, 팀 전체 기준으로 공유할 스타일이라면 프로젝트 설정과 팀 규칙을 따로 검토해야 합니다.

주의: 팀 저장소에 설정을 공유하기 전에는 다른 구성원에게도 같은 방식이 필요한지 확인하세요. 개인 학습용 Learning 스타일을 팀 전체 기본값으로 넣으면 숙련자에게는 오히려 답변이 길고 번거롭게 느껴질 수 있습니다.

따라 하는 순서 3: /clear 또는 새 세션으로 적용한다

Output style은 시스템 프롬프트와 관련된 설정입니다. 공식 문서는 Output style 변경이 /clear 또는 새 세션 이후 적용된다고 설명합니다.

따라서 스타일을 바꿨는데 바로 답변이 달라지지 않는 것 같다면 다음 순서로 확인하세요.

1. /config에서 Output style이 제대로 선택됐는지 확인합니다.
2. /clear를 실행하거나 새 Claude Code 세션을 엽니다.
3. 간단한 설명 요청으로 답변 방식이 바뀌었는지 확인합니다.

예시 확인 프롬프트:

지금 선택된 Output style에 맞춰 이 프로젝트의 package.json 역할을 설명해줘. 아직 파일은 수정하지 말고, 답변 방식이 어떤 스타일인지도 마지막에 한 줄로 알려줘.

실전 팁: 큰 작업 중간에 스타일을 바꾸면 맥락이 흐트러질 수 있습니다. 작업 시작 전 또는 /clear 직후에 바꾸는 편이 깔끔합니다.

따라 하는 순서 4: Explanatory로 변경 이유를 검수한다

Explanatory는 초보자에게 가장 무난한 시작점입니다. 코드 변경과 설명이 함께 오기 때문에 "AI가 뭘 했는지 모르겠다"는 불안을 줄일 수 있습니다.

이 스타일로 작업할 때는 요청을 이렇게 좁히면 좋습니다.

예시 프롬프트:

현재 오류를 고쳐줘. 단, 먼저 원인을 3줄로 설명하고, 바꿀 파일과 바꾸지 않을 파일을 나눠 말해줘. 수정 뒤에는 내가 확인해야 할 테스트나 화면 체크도 알려줘.

Explanatory를 쓴다고 해서 검수가 자동으로 끝나는 것은 아닙니다. 설명이 붙는 만큼, 사람이 확인할 질문도 더 분명해져야 합니다.

검수 질문:

• Claude가 말한 원인이 실제 오류와 맞는가?
• 수정 파일 범위가 요청보다 넓어지지 않았는가?
• 삭제된 코드가 중요한 예외 처리를 없애지 않았는가?
• 테스트나 화면 확인이 실제로 가능한가?

핵심 인사이트: Explanatory의 가치는 친절한 설명 자체가 아니라, 사람이 검수할 기준을 더 빨리 잡게 해 주는 데 있습니다.

따라 하는 순서 5: Learning으로 직접 채우는 부분을 만든다

Learning은 "AI가 다 해 주는 코딩"보다 "내가 일부를 채우는 코딩 연습"에 가깝습니다. 공식 문서에 따르면 Learning 스타일은 사용자가 직접 구현할 작은 코드 조각을 남기고 TODO(human) 표시를 넣을 수 있습니다.

이 스타일은 다음 상황에 잘 맞습니다.

• 코드 구조를 배우고 싶다.
• 작은 버그를 직접 고쳐 보고 싶다.
• Claude가 모든 답을 완성하기보다 힌트를 주길 원한다.
• 팀원이 초보자에게 실습 과제를 남기듯 단계적으로 배우고 싶다.

예시 프롬프트:

Learning 스타일에 맞춰 이 함수의 입력 검증 로직을 함께 고쳐줘. 전체 답을 한 번에 완성하지 말고, 내가 직접 채울 TODO(human) 부분을 하나 남겨줘. 내가 채운 뒤 어떤 테스트로 확인할지도 알려줘.

주의할 점도 있습니다. Learning은 작업 속도를 늦출 수 있습니다. 당장 운영 장애를 고쳐야 하거나, 정해진 시간 안에 배포해야 하는 작업이라면 Learning보다 Default나 Explanatory가 더 적합할 수 있습니다.

따라 하는 순서 6: 커스텀 Output style은 작게 만든다

공식 문서는 커스텀 Output style을 Markdown 파일로 만들 수 있다고 설명합니다. 파일에는 frontmatter와 지시문을 넣고, 사용자 수준, 프로젝트 수준, 관리 정책 수준 위치에 저장할 수 있습니다.

처음부터 거대한 스타일을 만들 필요는 없습니다. 좋은 커스텀 스타일은 짧고 구체적입니다.

나쁜 예:

"마케터처럼 잘 설명하고, 개발자처럼 고치고, 항상 완벽하게 검수해줘."

좋은 예:

"응답은 먼저 변경 목적 2줄, 수정 파일 목록, 검수 체크리스트 순서로 작성한다. 코딩 작업은 유지하되 설명은 비개발자도 이해할 수 있는 표현을 쓴다."

코딩 작업을 계속 할 스타일이라면 keep-coding-instructions 값을 true로 둘지 검토해야 합니다. 공식 문서는 이 값을 true로 설정하면 Claude Code의 기본 소프트웨어 엔지니어링 지침을 유지한 채 말투나 출력 형식만 바꿀 수 있다고 설명합니다.

주의: 커스텀 스타일에서 기본 코딩 지침을 빼면 Claude가 소프트웨어 엔지니어가 아닌 다른 역할처럼 행동할 수 있습니다. 문서 작성이나 데이터 분석에는 유용할 수 있지만, 실제 코드 수정 작업에서는 검수 기준이 약해질 수 있습니다.

바로 쓰는 프롬프트 예시

프롬프트 1: Explanatory로 변경 이유 받기

현재 오류를 고쳐줘. Explanatory 스타일에 맞춰 원인, 수정 파일, 변경 이유, 검수 방법을 나눠 설명해줘. 아직 확실하지 않은 부분은 단정하지 말고 확인 필요로 표시해줘.

프롬프트 2: Learning으로 일부 직접 구현하기

Learning 스타일에 맞춰 이 기능을 같이 구현하자. 전체 코드를 완성하지 말고 내가 직접 채울 TODO(human) 하나를 남겨줘. 그 부분을 채울 때 봐야 할 입력값과 실패 케이스도 설명해줘.

프롬프트 3: Proactive를 쓸 때 범위 제한하기

Proactive하게 진행하되, 파일 삭제, 패키지 설치, 배포, 원격 전송, 환경 변수 변경은 실행하지 말고 먼저 멈춰서 물어봐줘. 수정 범위는 이번 이슈와 직접 관련된 파일로 제한해줘.

프롬프트 4: 커스텀 스타일 초안 만들기

내가 반복해서 요청하는 답변 형식은 "목표, 수정 파일, 변경 이유, 검수 체크리스트, 남은 위험" 순서야. 이 형식을 Claude Code 커스텀 Output style로 만들 수 있게 짧은 Markdown 초안을 작성해줘. 코딩 지침은 유지하는 방향으로 제안해줘.

프롬프트 5: 스타일 적용 여부 확인하기

현재 세션의 답변 방식이 어떤 Output style에 가까운지, 답변 길이와 설명 방식 기준으로 추정해줘. 확실하지 않으면 /config에서 확인해야 한다고 말해줘.

실전 팁

첫째, 초보자는 Explanatory를 기본 출발점으로 삼는 편이 좋습니다. 설명이 길어지는 단점은 있지만, AI가 바꾼 이유를 이해하는 습관이 먼저입니다.

둘째, Learning은 학습용 브랜치나 작은 예제에서 쓰세요. 운영 중인 자동화 파일을 급하게 고치는 상황에서는 직접 채우는 TODO가 오히려 위험할 수 있습니다.

셋째, Proactive를 쓸 때는 금지 행동을 먼저 말하세요. 삭제, 배포, 패키지 설치, 원격 전송, 비밀값 접근 같은 행동은 사전에 멈춤 기준을 줘야 합니다.

넷째, 커스텀 스타일은 한 번에 하나의 문제만 해결해야 합니다. "항상 짧게", "항상 표로", "항상 검수 체크리스트 포함"처럼 한 가지 습관부터 고정하는 편이 오래 갑니다.

다섯째, Output style과 CLAUDE.md를 구분하세요. 프로젝트 규칙, 빌드 명령, 코드 컨벤션은 CLAUDE.md가 더 적합하고, 답변 말투와 형식은 Output style이 더 적합합니다.

주의할 점

첫째, Output style은 보안 설정이 아닙니다. 답변 방식이 더 조심스러워 보이더라도 파일 읽기, 파일 수정, 명령 실행 권한은 별도로 관리해야 합니다.

둘째, Proactive는 "아무거나 자동 실행"이라는 뜻이 아닙니다. 공식 문서 기준으로 Proactive는 더 적극적인 실행 지침이지만 permission prompt는 계속 남습니다. 권한 프롬프트가 보이면 목적과 대상 파일을 확인한 뒤 승인해야 합니다.

셋째, Explanatory와 Learning은 토큰과 시간이 더 들 수 있습니다. 공식 문서도 이 두 스타일이 기본적으로 더 긴 응답을 만든다고 설명합니다. 빠른 반복 수정이 필요한 날에는 Default가 더 효율적일 수 있습니다.

넷째, 커스텀 Output style을 프로젝트에 공유할 때는 팀 합의가 필요합니다. 개인 학습용 스타일이 팀 전체에 강제되면 숙련자에게는 불필요한 질문과 설명이 늘어날 수 있습니다.

다섯째, 설정이 적용되지 않는다고 느끼면 /clear 또는 새 세션을 먼저 확인하세요. Output style은 시스템 프롬프트와 관련돼 세션 시작 시점의 영향을 받습니다.

주의: Output style은 Claude Code의 "말하는 방식"을 바꾸는 기능입니다. "무엇을 실행해도 되는지"는 permissions와 permission mode, diff 검토, 테스트 실행으로 따로 관리해야 합니다.

자주 묻는 질문

Q1. Output styles를 쓰면 Claude Code가 더 똑똑해지나요?

아닙니다. 공식 문서 기준으로 Output styles는 Claude가 무엇을 아는지를 바꾸지 않습니다. 역할, 톤, 출력 형식을 조정하는 기능입니다.

Q2. /output-style 명령을 쓰면 되나요?

최신 공식 문서 기준으로 standalone /output-style 명령은 deprecated 후 제거되었습니다. /config에서 Output style을 선택하거나 settings 파일의 outputStyle 값을 설정하는 방식을 써야 합니다.

Q3. Explanatory와 Learning 중 무엇을 먼저 써야 하나요?

대부분의 초보자는 Explanatory가 먼저입니다. 변경 이유와 검수 기준을 이해한 뒤, 직접 구현 연습이 필요할 때 Learning으로 넘어가는 편이 안전합니다.

Q4. Proactive를 켜면 권한 승인이 사라지나요?

아닙니다. Proactive는 더 적극적으로 실행하도록 돕는 Output style이지만 permission mode를 바꾸는 기능은 아닙니다. 도구 실행 전 권한 프롬프트는 계속 나타날 수 있습니다.

Q5. 커스텀 Output style은 언제 만들면 좋나요?

매번 같은 답변 형식을 반복해서 요구할 때 좋습니다. 예를 들어 "수정 파일, 변경 이유, 검수 체크리스트" 순서를 항상 원한다면 커스텀 스타일 후보입니다.

Q6. Output style과 CLAUDE.md는 어떻게 다르나요?

Output style은 답변 방식과 역할을 바꾸는 데 적합합니다. CLAUDE.md는 프로젝트 규칙, 코드 컨벤션, 빌드 명령처럼 Claude가 항상 알아야 할 프로젝트 맥락을 담는 데 적합합니다.

출처

마무리

클로드 코드 Output styles의 핵심은 Claude에게 더 많은 일을 시키는 것이 아니라, Claude와 일하는 방식을 일정하게 만드는 것입니다. 설명이 필요하면 Explanatory, 직접 배워 가며 코딩하고 싶으면 Learning, 반복 확인을 줄이고 빠르게 진행하고 싶으면 Proactive를 고르면 됩니다.

처음 쓰는 감자나라ai님이라면 Explanatory로 시작해 보세요. 작은 수정 하나를 맡기고, Claude가 왜 그 파일을 바꿨는지, 어떤 검수를 해야 하는지 설명을 읽어 보는 것만으로도 AI 코딩 에이전트를 훨씬 안전하게 다룰 수 있습니다. 그다음 익숙해지면 Learning으로 직접 TODO(human)를 채워 보고, 마지막에 Proactive나 커스텀 스타일로 반복 업무에 맞게 다듬는 순서가 좋습니다.