Claude Code 출력 스타일 설정·만들기

확인 날짜 안내

공식 출력 스타일 문서(Claude Code 출력 스타일, 원본 날짜 미상) 수집일 2026-10-18 기준이다. 버전 조건, 설정 키, 경로는 자주 바뀌므로 90일이 지나면 다시 확인한다. 블로그 Steering Claude Code에서 온 권고 한 줄은 2026년 글의 권고라 날짜 계산에서 뺐다.

Claude Code의 응답 방식을 세션 전체에 걸어 두는 출력 스타일을 고르고, 필요하면 직접 만드는 절차다. 개념과 작동 방식은 개념 페이지에 있다.

언제 쓰고 언제 쓰지 않는가#

• 쓴다: 모든 응답을 특정 목소리·길이·형식으로 받고 싶을 때, 또는 Claude를 글쓰기 도우미·데이터 분석가처럼 다른 역할로 쓰고 싶을 때. Claude Code 출력 스타일 더 짧게, 더 설명해서, 같은 형식으로 답하라고 계속 요청하게 될 때가 계기다. Claude Code 확장 기능 개요 → Claude Code 셋업 점진적으로 키우기
• 쓰지 않는다(공식 문서가 다른 기능을 권하는 경우): Claude Code 출력 스타일
  • 프로젝트 관례·명령·구조를 알려 주려면 → 메모리(CLAUDE.md)
  • 한 종류 작업(릴리스 체크리스트, 리뷰 절차)의 지시라면 → 스킬
  • 편집마다 포맷, 명령 차단처럼 예외 없이 매번 일어나야 하면 → 훅. 출력 스타일은 지시라서 아무것도 강제하지 않는다.
  • 자기 지시·모델·도구를 가진 집중 작업 도우미라면 → 서브에이전트
  • 시작할 때 지시를 덧붙이기만 하려면 → --append-system-prompt
• 주의: 출력 스타일은 메인 대화와 포크(대화 전체를 물려받는 서브에이전트, 용어 사전)에만 적용되고, 다른 서브에이전트의 응답은 바꾸지 않는다. Claude Code 출력 스타일

준비물(필요한 것)#

1단계: 내장 스타일부터 고른다#

커스텀 스타일을 쓰기 전에 내장 스타일을 확인한다. Steering Claude Code 공식 문서의 내장 네 가지는 Default의 소프트웨어 엔지니어링 지시를 유지하고 자기 지시를 더한다. Claude Code 출력 스타일

근거: Claude Code 출력 스타일 (원본 "Use it when" 열. 무엇이 바뀌는지는 출력 스타일의 표)

• Proactive는 권한 모드를 바꾸지 않는다. 권한 확인 창은 바꾸기 전과 똑같이 뜬다. 지우거나 공유·운영 시스템을 바꾸기 전에 대화로 확인하라는 것은 스타일 지시일 뿐 권한 확인 창과는 별개다. 묻지 않고 실행할 범위를 바꾸려면 Claude Code 권한 모드 고르기. Claude Code 출력 스타일
• Concise도 사용자가 설명을 요청할 때와 오류 보고·실패한 테스트 출력·보안 경고·파괴적 동작 확인은 전체 길이로 쓴다. Claude Code 출력 스타일
• 토큰: Explanatory·Learning은 설계상 응답이 길어 출력 토큰이 늘고, Concise는 반대다. Claude Code 출력 스타일

2단계: 스타일을 바꾼다#

근거: Claude Code 출력 스타일

• 명령과 두 메뉴는 선택을 .claude/settings.local.json(로컬 프로젝트 레벨)에 저장한다.

• 메뉴 없이 설정 파일에 직접 쓴다:

  {
    "outputStyle": "Explanatory"
  }

• 대소문자 주의: outputStyle 값은 대소문자를 구분한다. Proactive, Concise, Explanatory, Learning으로 쓴다. explanatory처럼 정확히 맞지 않으면 Default가 된다. /output-style 명령은 대소문자를 무시한다.

• 모든 프로젝트의 기본값: ~/.claude/settings.json에 outputStyle을 둔다. 프로젝트 자체 설정 파일이 있으면 그쪽이 우선한다.

• 적용 시점: 세션 중 바꾸면 다음 메시지부터 새 스타일을 쓴다(v2.1.251 이전에는 /clear나 새 세션 뒤).

근거: Claude Code 출력 스타일

3단계: 커스텀 스타일을 만든다#

1. 마크다운 파일을 만든다. 세 레벨 중 하나에 둔다. name을 두지 않으면 파일 이름이 스타일 이름이다.

   • 사용자: ~/.claude/output-styles
   • 프로젝트: .claude/output-styles
   • Managed policy: managed settings 디렉터리 안의 .claude/output-styles → managed settings

   프로젝트 스타일은 작업 디렉터리와 저장소 루트 사이의 모든 .claude/output-styles/에서 로드되고, 같은 이름이 여럿이면 작업 디렉터리에 가장 가까운 것을 쓴다. VS Code 확장에서는 Output styles 메뉴로 파일을 만들 수도 있다(v2.1.261 이상).

2. 코딩 지시를 유지할지 정한다. 소통 방식만 바꾸고 코딩은 그대로 하게 하려면 keep-coding-instructions: true. Claude가 소프트웨어 엔지니어링을 하지 않을 거면 빼 둔다(기본값 false). 빼면 전체 시스템 프롬프트의 내장 엔지니어링 지시 절(변경 범위, 주석, 작업 검증 등)이 빠진다.

3. frontmatter와 지시를 쓴다. 원본 예시(코딩 동작은 유지하고 설명을 다이어그램부터 시작):

   ---
   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.
   
   ## Diagram conventions
   
   Use `flowchart TD` for control flow and `sequenceDiagram` for request paths. Keep diagrams under 15 nodes.

4. 스타일로 바꾼다. /output-style <style> 또는 /config → Output style. 다음 메시지부터 적용된다. 터미널에서는 시작할 때 스타일 파일을 읽으므로, 실행 중에 만들거나 고쳤으면 Claude Code를 재시작한다.

근거: Claude Code 출력 스타일

frontmatter 필드#

근거: Claude Code 출력 스타일 (원본 표 그대로)

4단계: 팀에 나눈다#

• 스타일 파일은 세 레벨(사용자·프로젝트·managed policy) 중 하나에 둔다(3단계 1번의 세 위치). 명령·메뉴로 고른 선택은 로컬 프로젝트 레벨인 .claude/settings.local.json에 저장된다. Claude Code 출력 스타일
  • 편집자 해석: 원본은 팀 공유를 직접 말하지 않는다. 다만 파일 위치가 세 레벨로 나뉜다는 문장("Save it at one of three levels")에 비추어, 누구와 나눌지는 파일을 두는 레벨로 정해진다고 볼 수 있다.
• 플러그인은 output-styles/ 디렉터리로 스타일을 담는다. 사용자가 고르지 않아도 적용하려면 force-for-plugin: true를 쓴다. 이 값은 사용자의 outputStyle 설정을 덮어쓰고, 여러 플러그인이 설정하면 먼저 로드된 것을 쓴다. Claude Code 출력 스타일

됐는지 확인하는 법#

• 지금 어떤 스타일인지: 인자 없이 /output-style을 실행하면 고를 수 있는 스타일 목록이 나오고 현재 스타일에 표시가 붙는다. Claude Code 출력 스타일
• 바꾼 것이 적용됐는지: 새 스타일은 바꾼 다음 메시지부터 쓰인다. 터미널에서 스타일 파일을 만들거나 고쳤다면 Claude Code를 재시작한 뒤 확인한다(3단계 4번). Claude Code 출력 스타일
• 커스텀 스타일 파일이 제대로 읽혔는지: /config 선택 창에 frontmatter의 name·description이 보이는지 본다. YAML이 파싱되지 않으면 필드 없이 파일 이름으로 로드되므로, claude --debug로 파싱 오류를 확인한다. 틀린 필드 이름은 오류 없이 무시된다. Claude Code 출력 스타일
• 안 먹으면 아래 "스타일이 안 먹을 때 점검 순서"로 간다.

스타일이 안 먹을 때 점검 순서#

1. 설정 파일의 outputStyle 철자와 대소문자가 스타일 이름과 정확히 맞는가. 아니면 Default가 된다.
2. 프로젝트 설정 파일이 ~/.claude/settings.json의 값을 덮어쓰고 있지 않은가.
3. 터미널에서 스타일 파일을 만들거나 고친 뒤 재시작했는가.
4. frontmatter 필드 철자가 맞는가. 틀린 필드는 오류 없이 무시된다. YAML이 파싱되지 않으면 필드 없이 파일 이름으로 로드되므로 claude --debug로 파싱 오류를 본다.
5. keep-coding-instructions: true인데 코딩 지시가 빠진 것 같으면, 짧은 시스템 프롬프트에서는 이 필드가 효과가 없다. CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=0으로 전체 프롬프트를 고른다.
6. 서브에이전트 응답에 스타일이 안 보이면 정상이다. 스타일은 메인 대화와 포크에만 적용된다.
7. 켜져 있는 플러그인의 force-for-plugin 스타일이 내 선택을 덮어쓰고 있지 않은가.

근거: Claude Code 출력 스타일. 원본은 "스타일이 왜 적용되지 않는지" 진단을 Debug your configuration 문서로 넘긴다.