explanatory-output-style 플러그인 사용법: 클로드 코드 설명 모드, 없이·플러그인·내장 Explanatory 스타일로 6번 비교

클로드 코드에 일을 맡기면 결과는 나오는데, 왜 그렇게 짰는지는 잘 남지 않습니다. 코드를 배우는 중이거나 처음 보는 프로젝트라면 이유까지 듣고 싶습니다. explanatory-output-style(익스플래너토리 아웃풋 스타일)은 클로드 답변에 “★ Insight”라는 짧은 설명 칸을 붙이게 하는 Anthropic 공식 무료 플러그인입니다. 클로드 코드에 같은 일을 하는 내장 출력 스타일(Explanatory)도 있어서, 같은 기능 추가 요청을 플러그인 없이·플러그인으로·내장 스타일로 각각 두 번씩 보내고 채점했습니다.

결과부터 보기: 같은 요청, 마지막 답변 세 개

왼쪽은 플러그인 없이, 가운데는 explanatory-output-style 플러그인으로, 오른쪽은 내장 Explanatory 스타일로 받은 마지막 답변입니다(모두 2회차). 노란 칸이 ★ Insight 설명입니다. 왼쪽에는 노란 칸이 없고, 가운데와 오른쪽은 답변 끝에 하나씩 있습니다. 아래쪽에는 바뀐 코드가 이어집니다.

직접 눌러 보기: 답변 여섯 벌과 바뀐 코드, 채점표 열어 보기(클로드의 마지막 답변과 git diff를 그대로 옮겼습니다)

따라 해 보기: 요청문과 실습 재료

플러그인을 깐 폴더에서 클로드 코드를 열고 아래 요청을 보내면 이번 실험과 같습니다. 클로드 코드가 처음이라면 클로드 코드 설치 방법을 먼저 보세요. 실습 재료(zip)에는 가상 카페의 재료 재고 코드, 기본 테스트, 재료 목록(data.json), 요청문, 숨은 검사와 채점 기준을 넣었습니다.

src/stock.mjs에 두 함수를 추가해 줘. expiringSoon(items, today)는 유통기한이 오늘부터 3일 뒤까지(오늘 포함)인 재료 이름 목록을, expired(items, today)는 유통기한이 이미 지난 재료 이름 목록을 돌려줘. today는 'YYYY-MM-DD' 문자열이야. 순서는 들어온 순서 그대로. test/stock.test.mjs에 테스트도 추가하고 돌려 봐.

좋은 결과라면 함수 두 개와 테스트가 추가되고, 답변 끝에 ★ Insight로 시작해 가로줄로 끝나는 칸이 붙습니다. 칸 안에는 “왜 날짜 문자열 비교 대신 날짜 차이를 썼는지”처럼 이 코드에 대한 요점이 두세 개 들어갑니다.

explanatory-output-style 플러그인에 들어 있는 것

claude plugin details로 뽑은 1.0.0의 구성은 훅 1개가 전부입니다. 스킬·에이전트·MCP 서버는 없습니다. 훅은 클로드 코드가 정해진 순간에 자동으로 실행하는 명령입니다. 이 플러그인의 훅은 대화가 시작될 때(SessionStart) 한 번 돌아, 클로드에게 지시문을 덧붙입니다.

구성	하는 일	분량
훅 SessionStart	대화 시작 때 “설명 모드” 지시문을 클로드에게 넣음	구성 목록에는 상시 약 0토큰으로 나옴. 실제로 넣는 지시문은 영어 약 1,030자(133단어)

훅이 넣는 지시문을 우리말로 옮기면 이렇습니다. ① 코드를 쓰기 전과 뒤에 ★ Insight 칸으로 짧게 설명한다 ② 칸마다 요점은 2~3개 ③ 일반 프로그래밍 상식이 아니라 이 코드베이스와 방금 쓴 코드에 대한 이야기 ④ 설명은 대화에만 쓰고 코드 파일에는 넣지 않는다 ⑤ 끝까지 미루지 말고 코드를 쓰면서 설명한다.

구성 목록의 “상시 약 0토큰”은 훅 자체만 셈한 숫자이고, 실제로는 대화마다 위 지시문만큼 입력이 늘어납니다(비용은 아래 비교 참고).

1단계. 플러그인 깔기 (약 1분)

쓰려는 폴더에서 터미널에 아래 명령을 실행합니다. claude-plugins-official은 클로드 코드에 처음부터 등록된 공식 플러그인 저장소입니다. --scope local은 이 폴더에서만 켜는 옵션입니다.

claude plugin install explanatory-output-style@claude-plugins-official --scope local
claude plugin details explanatory-output-style@claude-plugins-official

이렇게 나오면 성공 ✔ Successfully installed plugin: explanatory-output-style@claude-plugins-official (scope: local)(플러그인 설치 성공, 범위: 이 폴더). 구성 목록에는 Hooks (1) SessionStart(훅 1개, 대화 시작 때)가 나옵니다. 설명 줄의 mimics the deprecated Explanatory output style은 “지원 중단된 Explanatory 출력 스타일을 흉내 낸다”는 뜻입니다.

• 설치 명령이 플러그인을 찾지 못하면 claude plugin marketplace add anthropics/claude-plugins-official로 저장소를 등록한 뒤 다시 설치합니다.
• 클로드 앱에서는 디렉터리에서 설치합니다(디렉터리 여는 법). 디렉터리에는 클로드 코드와 코워크에서 쓸 수 있다고 나옵니다. 이 글은 클로드 코드 터미널 기준입니다.
• 훅은 대화가 시작될 때 돌기 때문에, 이미 열어 둔 대화에는 적용되지 않습니다. 설치한 뒤 클로드 코드를 새로 엽니다.

필요 없어지면 같은 폴더에서 아래 명령으로 지웁니다.

claude plugin uninstall explanatory-output-style@claude-plugins-official --scope local

플러그인 대신 내장 스타일로 켜기

출력 스타일 공식 문서(2026-10-18 확인)에는 기본 말고 내장 스타일이 4개 있습니다. Proactive(묻지 않고 바로 진행), Concise(짧게), Explanatory(설명 칸 추가), Learning(설명에 더해 일부 코드를 직접 쓰게 함)입니다. Explanatory는 클로드 코드 안에서 /output-style explanatory로 켜거나, 폴더의 .claude/settings.local.json에 아래 한 줄을 넣어 켭니다. 이번 실험의 세 번째 조건이 이 방법입니다.

{ "outputStyle": "Explanatory" }

설정 파일에 쓸 때는 대소문자를 지켜 Explanatory로 적어야 합니다. 문서에 따르면 explanatory처럼 다르게 쓰면 기본 스타일로 돌아갑니다. /output-style 명령은 대소문자를 가리지 않고, 클로드 코드 2.1.269 이후 버전에서 됩니다.

같은 요청, 세 가지 조건 비교

가상 카페의 재료 재고 코드(20줄 남짓)에 위 요청문을 보냈습니다. 조건마다 새 대화로 두 번씩, 모두 Opus 5.5 · 생각 깊이 중간입니다. 채점 기준 9개는 실행 전에 플러그인 지시문과 요청 내용에서 뽑아 고정했고, 요청문에는 넣지 않았습니다. 설명 형식 5개는 대화 기록에서 자동으로 셌습니다. 일 완료 4개는 숨은 검사로 봤습니다. 숨은 검사는 오늘·3일 뒤는 들어가고 4일 뒤는 빠지는지, 어제 날짜만 “지남”에 들어가는지, 들어온 순서를 지키는지, 테스트가 통과하는지입니다.

검사	① 플러그인 없음 (1·2)	② explanatory-output-style (1·2)	③ 내장 Explanatory (1·2)
일 완료(4개 중)	4 · 4	4 · 4	4 · 4
설명 형식(5개 중)	0 · 0	4 · 4	4 · 4
★ Insight 칸 수	0 · 0	1 · 1	1 · 1
칸 안 요점 수	해당 없음	2 · 3	2 · 3
코드 쓰기 전 설명	해당 없음	없음 · 없음	없음 · 없음
마지막 답변 길이	539 · 694자	950 · 1,117자	742 · 870자
걸린 시간	1분이 안 걸림	1분이 안 걸림	1분이 안 걸림
사용량(API 단가)	0.27 · 0.29달러	0.28 · 0.28달러	0.44 · 0.45달러

설명 형식에서 ②·③이 똑같이 1점씩 빠진 이유는 “코드 쓰기 전 설명”입니다. 여섯 번 모두 코드를 고치는 동안에는 대화에 글을 쓰지 않았습니다. ②·③ 네 번은 일을 다 끝낸 뒤 마지막 답변에서 무엇을 했는지 정리하고, 그 끝에 ★ Insight 칸을 하나 붙였습니다. 칸마다 daysBetween, expiringSoon 같은 이 코드의 이름이 하나 이상 들어 있었습니다. 코드 파일에 설명이 섞여 들어간 경우는 없었습니다.

붙은 설명은 이런 내용

아래는 ② 1회차의 마지막 답변 끝에 붙은 칸입니다. 왜 날짜 문자열을 직접 비교하지 않았는지, 두 함수의 경계가 어떻게 맞물리는지를 이 코드 기준으로 설명합니다.

실행 기록 · 작업 폴더 · logs/plug1.jsonl의 마지막 답변에서 옮김

`★ Insight ─────────────────────────────────────`
- 3일 경계를 날짜 문자열 비교(`'2026-10-21' <= ...`)가 아니라 날짜 차이(`daysBetween`)로 잡았습니다. 문자열 비교로는 "오늘+3일"을 직접 만들어야 하고, 그러면 달이나 연도가 바뀌는 경우를 따로 처리해야 합니다. 날짜 차이를 쓰면 이 문제가 생기지 않습니다. 월 경계 테스트가 바로 이 점을 확인합니다.
- `expired`의 `< 0`과 `expiringSoon`의 `>= 0`이 정확히 맞물려서, 어떤 재료도 두 목록에 동시에 들어가지 않습니다. 겹치지 않는다는 점은 나중에 화면에 "만료"와 "임박"을 나눠 보여 줄 때 중요합니다.
`─────────────────────────────────────────────────`

플러그인 없이 받은 답변(①)도 무엇을 추가했고 어떤 경우를 테스트했는지는 정리해 줍니다. 다만 “왜 이렇게 짰는지”는 칸으로 따로 나오지 않았습니다. ①의 두 답변에도 월 경계·빈 목록 같은 테스트 목록이 있었고, 1회차는 날짜 형식이 틀린 재료는 따로 처리하지 않았다고, 2회차는 기존 daysBetween이 UTC로 계산해 날짜가 하루씩 밀리지 않는다고 덧붙였습니다.

설명도 틀릴 수 있다: ③ 2회차의 요점 하나

칸 안 요점 열 개를 직접 읽어 코드와 맞춰 봤습니다. 한 개가 틀렸습니다. ③ 2회차는 “4일 뒤를 테스트에 넣은 이유는 <= 3을 실수로 < 4나 <= 4로 바꿨을 때 테스트가 바로 실패하게 하려는 것”이라고 썼습니다. 그런데 남은 날수는 daysBetween이 정수로 돌려주기 때문에 < 4와 <= 3은 결과가 같고, 테스트도 실패하지 않습니다. <= 4로 바꿨을 때만 실패합니다. 설명 칸은 그럴듯하게 읽히지만, 배우는 용도라면 요점을 코드와 한 번 맞춰 보는 편이 안전합니다.

플러그인과 내장 스타일의 차이: 이번에는 비용 쪽

설명의 모양과 수는 ②와 ③이 같았습니다. 차이는 사용량이었습니다. ③은 한 번에 0.44~0.45달러로, ①·②(0.27~0.29달러)보다 1.6배쯤 들었습니다. 사용량 기록을 보면 차이의 대부분은 “캐시에 새로 쓴 입력”입니다. ①·②는 약 2.5만 토큰, ③은 약 4.7만 토큰이었습니다.

공식 문서는 스타일 지시문이 입력 토큰을 늘리지만 첫 요청 뒤로는 프롬프트 캐시가 이 비용을 줄여 준다고 설명합니다. 이번 실험은 요청 한 번짜리 대화라 첫 요청 비용이 그대로 드러났고, 긴 대화에서의 차이는 재지 않았습니다.

2단계. 내 코드에 써 보기 (약 5분)

• 설치한 폴더에서 클로드 코드를 새로 열고, 평소처럼 일을 시킵니다. 설명을 따로 요청할 필요는 없습니다.
• 처음 보는 프로젝트에서 “이 폴더 구조 설명하고, 로그인 부분에 비밀번호 길이 검사 추가해 줘”처럼 일과 설명을 함께 맡기면 쓸모가 큽니다. 칸 안의 요점이 그 프로젝트의 이름을 들어 설명하도록 지시돼 있기 때문입니다.
• 설명이 거슬리는 작업에서는 플러그인을 잠시 끕니다. claude plugin disable explanatory-output-style@claude-plugins-official --scope local로 끄고, enable로 다시 켭니다.

• 이렇게 나오면 성공 답변에 ★ Insight ─────로 시작해 가로줄로 끝나는 칸이 있고, 그 안에 요점이 2~3개 있습니다.
• 칸이 안 보이면: 플러그인을 깐 그 폴더에서 새 대화를 열었는지 확인합니다. local 범위 플러그인은 다른 폴더에서는 꺼져 있습니다.

이런 사람에게 권합니다

• ✅ 팀에 “설명 모드”를 플러그인으로 나눠 주거나, 설명 지시문을 자기 식으로 고쳐 쓰고 싶은 사람. 지시문이 훅 파일 하나에 들어 있어 고치기 쉽습니다. hookify 리뷰처럼 훅을 다뤄 본 사람이면 금방 바꿉니다.
• ✅ 코드를 배우는 중이라 결과마다 “왜”를 한두 줄씩 듣고 싶은 사람. 다만 내장 스타일로도 같은 설명이 나옵니다.
• ❌ 그냥 설명 칸만 원하는 사람. 설정 한 줄("outputStyle": "Explanatory")이나 /output-style explanatory로 충분하고, 플러그인을 따로 깔 이유가 적습니다.

한계와 주의할 점

• 20줄 남짓한 가상 코드에 함수 두 개를 더하는 작은 일로, 조건마다 두 번씩만 돌렸습니다. 여러 파일을 고치는 긴 작업에서는 설명이 중간에 나올 수 있습니다.
• 모두 claude -p(요청 한 번에 답 한 번) 방식으로 돌렸습니다. 대화를 주고받는 평소 화면에서는 설명이 나오는 때와 횟수가 다를 수 있습니다.
• 자동 채점은 설명의 형식만 셉니다. 내용은 직접 읽어 확인했고, 위에 적은 한 개 말고는 틀린 요점을 찾지 못했습니다.
• 플러그인 설명의 “지원 중단(deprecated)”은 2026-10-18 공식 문서와 맞지 않습니다. 내장 출력 스타일이 다시 바뀌면 이 글의 비교도 달라질 수 있습니다.

대안

방법	다른 점	이럴 때 고르세요
explanatory-output-style 플러그인(이 글)	훅으로 지시문을 덧붙임. 지시문 파일을 고쳐 쓸 수 있음	팀에 나눠 주거나 지시문을 바꾸고 싶을 때
내장 Explanatory 스타일	설정 한 줄로 켬. 이번 실험에서 설명 형식 점수는 플러그인과 같음	설명 칸만 원할 때
내장 Learning 스타일 · learning-output-style 플러그인	공식 문서 기준: 설명에 더해, 설계 판단이 필요한 몇 줄을 TODO(human)으로 남기고 직접 쓰게 함. 비교 리뷰에서는 요청에 “직접 짜 보고 싶다”는 문장이 있을 때 확실히 자리를 남김	손으로 코드를 짜며 배우고 싶을 때
CLAUDE.md에 직접 적기	“고친 뒤 이유를 두세 줄로 설명해 줘”처럼 프로젝트 규칙으로 남김	이 프로젝트에서만 늘 설명을 받고 싶을 때

자주 묻는 질문

explanatory-output-style은 무료인가요?

플러그인 자체는 무료(Apache-2.0)입니다. 설명 지시문과 길어진 답변만큼 Claude 사용량이 늘어납니다. 이번 요청에서는 마지막 답변이 플러그인 없이 539·694자, 플러그인으로 950·1,117자였고, 사용량 차이는 거의 없었습니다(0.27·0.29달러 대 0.28·0.28달러). 구독 요금제라면 그만큼 사용량 한도에서 빠집니다.

내장 Explanatory 스타일과 동시에 켜도 되나요?

둘 다 같은 형식의 설명을 요구하는 지시문이라 함께 켤 이유가 적습니다. 이번에는 함께 켠 경우를 시험하지 않았습니다. 하나만 고르세요.

클로드 코드 플러그인을 더 찾아보려면요?

claude-code-setup 플러그인 리뷰는 내 프로젝트에 맞는 플러그인·훅·스킬을 추천받는 방법을 다룹니다. 디렉터리에서 직접 고르려면 클로드 스킬·플러그인 디렉터리 글을 보세요.

출처

explanatory-output-style 플러그인 폴더, 훅이 넣는 지시문(session-start.sh), 클로드 코드 출력 스타일 문서, 클로드 코드 훅 안내 (모두 2026-10-18 확인, 저장소 별 42,124개)