Quick Comparison
output style은 모든 응답의 역할·tone·표현 형식을 바꾸는 Claude Code system prompt 설정입니다. 프로젝트 규칙은 CLAUDE.md, 한 번의 실행에만 더할 지시는 --append-system-prompt, 반복 절차는 skill, 독립된 도구·context는 subagent에 둡니다. 어느 방식도 file write·Bash·network 권한을 부여하거나 차단하지는 않습니다.
| 바꾸려는 것 | 먼저 쓸 위치 | 적용 범위 |
|---|---|---|
| 모든 답변의 tone·format·역할 | output style | 선택한 Code session 전체 |
| codebase 규칙·금지 범위·검증 명령 | CLAUDE.md | 해당 project의 session |
| 단일 CLI 실행의 추가 지시 | --append-system-prompt | 해당 invocation |
| 반복되는 작업 절차 | skill | 호출하거나 관련성이 맞는 turn |
| 분리된 조사·review 역할 | subagent | 별도 context와 tool set |
| 실제 실행 권한 | permissions·sandbox·tool server | 설정과 실행 환경이 정한 범위 |
"항상 다이어그램 먼저 설명" -> output style
"이 저장소는 npm test를 실행" -> CLAUDE.md
"이번 CI 실행에서만 JSON으로 출력" -> --append-system-prompt 또는 prompt
"현재 diff를 read-only로 review" -> skill 또는 subagentoutput style의 동작
output style은 Claude가 아는 source를 바꾸지 않고 system prompt를 바꿔 응답 방식을 조정합니다. built-in Proactive는 일상적인 판단에서 바로 행동하도록 유도하지만 permission mode를 바꾸지는 않습니다. Explanatory는 구현 중 insight를 더 설명하고, Learning은 사용자가 채울 TODO(human)을 남기는 학습 방식입니다. 이들은 더 길거나 적극적인 답을 만들 수 있으나 permission prompt와 deny rule은 그대로 적용됩니다.
/config의 Output style에서 선택하면 기본적으로 local project settings인 .claude/settings.local.json에 기록됩니다. settings 파일에서 outputStyle field를 직접 설정할 수도 있습니다. system prompt는 session 시작에 고정되므로 style을 바꾼 뒤에는 새 session에서 확인합니다. 현재 대화의 답이 바뀌지 않는다고 /clear만 반복하기보다, 적용된 settings와 새 session을 함께 확인하는 편이 정확합니다.
| style | 적합한 상황 | 비용·운영 영향 |
|---|---|---|
| Default | 일반 소프트웨어 작업 | 기본 Code 지침을 유지합니다. |
| Proactive | routine decision이 많은 구현 | 더 빠르게 움직여도 승인 경계는 유지됩니다. |
| Explanatory | 구현 이유를 배우며 작업 | 응답과 output token이 길어질 수 있습니다. |
| Learning | 사용자가 일부 코드를 직접 작성 | TODO(human) 처리와 작업 속도를 합의해야 합니다. |
| Custom | 팀·개인에게 반복되는 표현 계약 | instructions 길이와 coding instruction 보존을 검토합니다. |
custom output style
custom style은 frontmatter와 Markdown instruction으로 만든 파일입니다. user scope는 ~/.claude/output-styles/, project scope는 .claude/output-styles/, managed policy는 managed settings directory 아래에 둡니다. coding을 계속 할 custom style이라면 keep-coding-instructions: true가 중요합니다. 이 값을 생략하면 custom instruction은 남지만 Claude Code의 built-in software engineering instruction은 빠집니다.
---
name: Diagrams first
description: Explain code and data flow with one small diagram first.
keep-coding-instructions: true
---
When explaining code or architecture, start with one Mermaid diagram.
Keep it under 15 nodes, then explain the relevant tradeoff in prose.| field | 언제 바꾸는가 | 잘못 두면 생기는 일 |
|---|---|---|
name | 파일명 대신 picker에 보일 이름을 정할 때 | 같은 용도의 style을 찾기 어려워집니다. |
description | 선택 기준을 짧게 알릴 때 | 사용자가 적용 범위를 오해할 수 있습니다. |
keep-coding-instructions | 말투만 바꾸면서 coding 품질 지침을 유지할 때 | 생략하면 scope·comment·verification 같은 기본 지침이 빠집니다. |
force-for-plugin | plugin이 활성화될 때 style을 강제해야 할 때 | 사용자 outputStyle을 덮어 예상 밖 응답이 생길 수 있습니다. |
자주 틀리는 부분
output style은 security policy가 아닙니다. "파일을 수정하지 마" 같은 문장을 style에 넣어도 permission·sandbox·MCP token을 대체하지 못합니다. 실제 위험 경계는 tool permission과 server-side authorization으로 둡니다.
style 안에 project-specific build 명령, secret, 긴 procedure를 전부 넣으면 모든 session의 context와 token 비용이 커집니다. project knowledge는 CLAUDE.md, 필요할 때만 읽을 절차는 skill로 옮깁니다. custom style을 바꾼 뒤에는 representative prompt, 기존 coding workflow, 새 session에서의 적용 여부를 함께 점검합니다.
참고 링크
3 sources