novice — 비개발자용 Claude Code 플러그인

novice가 실제로 하는 일은 셋이다

비개발자가 Claude Code를 처음 켜면 세 군데에서 막힌다. 답변에 나오는 용어를 모르겠고, 답변이 너무 길어 무엇부터 해야 할지 모르겠고, 터미널에 명령을 붙여 넣는 순간 무언가 되돌릴 수 없게 될까 봐 손이 멈춘다. novice는 이 셋을 각각 다른 층으로 다룬다.

학습층은 용어를 다룬다. commit이나 branch 같은 말을 쉬운 말로 바꾸지 않고 그대로 쓴 뒤 괄호로 뜻을 붙인다. 그리고 같은 용어가 그 세션에서 충분히 나오면 설명을 조용히 걷어낸다. 처음엔 매번 따라오던 괄호가 어느 순간 사라져 있는 식이다.

focus는 답변의 모양을 다룬다. 켜면 첫 줄이 바로 실행할 수 있는 명령이나 경로가 되고, 두 단계 이상은 번호 목록이 되며, 서론과 맺음말이 금지된다. 레벨과는 별개 스위치라 novice를 off로 둬도 focus는 그대로 동작한다.

안전 게이트는 명령을 다룬다. 다만 겁주는 방향이 아니라 반대다. 확실히 파괴적이고 되돌릴 수 없는 것만 막고 나머지는 아예 판정하지 않는다. 왜 그렇게 만들었는지는 아래에 따로 적었다.

여기에 외부 서비스 CLI 부트스트랩이 붙는다. Vercel이나 GitHub CLI를 깔고 로그인하는 과정을 단계별 승인을 받아 가며 대신 밟아 준다. 다만 경계가 분명하다. 계정을 만들고 값을 입력하고 배포하는 것은 사용자가 직접 한다.

설치 — marketplace와 npm 두 갈래다

권장 경로는 marketplace다. Claude Code를 켠 상태에서 아래 세 줄을 차례로 입력한다. 터미널이 아니라 Claude Code 안에서 치는 명령이다.

Claude Code 안에서

/plugin marketplace add hjsh200219/novice
/plugin install novice@novice
/reload-plugins

설치가 됐는지 확인하고, 나중에 갱신하는 법

확인은 두 단계다. `/plugin` 목록에서 novice가 enabled로 보이는지 보고, `/novice`를 실행해 상태 대시보드가 나오면 정상이다. 대시보드에는 현재 레벨, 학습층 상태, 안전 게이트 동작 여부, mute 목록이 함께 나온다.

여기서 한 번은 반드시 걸리는 함정이 있다. 설치된 것은 원본이 아니라 캐시 복사본이라 자동으로 갱신되지 않는다. 새 버전이 나와도 조용히 옛 버전이 계속 돈다. `/plugin` 메뉴에서 novice marketplace를 update한 뒤 플러그인을 다시 설치해야 반영된다.

제거는 `/plugin uninstall novice`다. 제거하면 학습층만이 아니라 안전 게이트도 함께 사라진다. always-on이라는 말은 플러그인이 켜져 있는 동안만 의미가 있다.

GitHub 축약형 대신 git URL이나 로컬 클론 경로를 써도 같은 명령으로 등록된다. `/plugin marketplace add https://github.com/hjsh200219/novice.git`처럼 쓰면 된다.

npm으로 설치하는 경로 — 같은 플러그인, 다른 배송

novice를 npm 패키지 claude-novice로 전역 설치한 뒤 claude --plugin-dir로 세션에 로드하는 터미널 명령과, 자체 marketplace의 source에 npm을 지정하는 방법을 보여 주는 도식.

novice는 npm에도 `claude-novice`라는 이름으로 올라가 있다. marketplace 쪽과 버전이 같이 올라가는 별개 채널이다. marketplace 설치가 GitHub 저장소 트리에서 받아오는 반면 이쪽은 npm 레지스트리에서 받는다. 사내 프록시나 방화벽 때문에 GitHub 접근이 막히는 환경, CI 이미지처럼 npm이 이미 표준 배송 수단인 환경에서 쓸 경로다.

가장 단순한 형태는 전역 설치 후 세션에 직접 로드하는 것이다. 이 명령은 Claude Code 안이 아니라 터미널에서 친다.

터미널에서

npm install -g claude-novice
claude --plugin-dir "$(npm root -g)/claude-novice"

자체 marketplace에서 npm을 소스로 지정

{
  "name": "novice",
  "source": { "source": "npm", "package": "claude-novice" }
}

두 경로 중 무엇을 고르나

혼자 쓰는 개인 환경이면 marketplace 세 줄이 가장 짧다. Claude Code 밖으로 나갈 일이 없고 npm이나 Node 버전을 신경 쓸 필요도 없다.

npm 경로는 두 경우에 쓴다. 하나는 GitHub 직접 접근이 막힌 환경, 다른 하나는 버전을 고정하고 싶은 경우다. 자체 marketplace 항목의 source에 `version`을 박으면 최신 추종 대신 그 버전에 묶인다. 컨테이너나 CI에 미리 심어야 한다면 `CLAUDE_CODE_PLUGIN_SEED_DIR`로 이미지 빌드 시점에 플러그인 캐시를 넣어 둘 수도 있다.

설치 없이 이번 세션에만 붙여 보고 싶으면 `claude --plugin-dir <클론 경로>`가 있다. 세션이 끝나면 사라진다. 호스팅된 ZIP을 한 번만 테스트할 때는 `claude --plugin-url <ZIP 주소>`를 쓴다.

한 가지 하면 안 되는 것이 있다. 스킬 파일만 `~/.claude/skills/`에 손으로 복사하는 방식은 지원하지 않는다. 그렇게 하면 스킬은 로드되지만 hook이 로드되지 않아 안전 게이트도 학습층도 동작하지 않는다. 겉보기에는 설치된 것처럼 보이는데 실제로는 아무 보호가 없는 상태가 된다.

팀에 배포할 때 — 팀원은 명령을 배울 필요가 없다

비개발자 팀원에게 `/plugin` 명령을 가르치는 것 자체가 이미 진입 장벽이다. 그래서 작업 저장소의 `.claude/settings.json`에 아래를 커밋해 두는 경로가 따로 있다. 그 저장소를 신뢰한 사람에게 Claude Code가 novice 설치를 알아서 제안한다.

.claude/settings.json

{
  "extraKnownMarketplaces": {
    "novice": { "source": { "source": "github", "repo": "hjsh200219/novice" } }
  },
  "enabledPlugins": { "novice@novice": true }
}

용어를 쉬운 말로 바꾸지 않는 이유

입문자용 도구가 흔히 택하는 길은 어려운 말을 없애는 것이다. commit을 저장이라 부르고 branch를 사본이라 부르면 당장은 편하다. 문제는 그 사람이 검색을 시작하는 순간이다. 저장으로는 아무것도 안 나온다.

novice는 반대로 간다. 실제 용어를 그대로 쓰고 그 뒤에 뜻을 붙인다. 아래가 실제로 나오는 형태다.

Level 1에서 나오는 형태

commit(현재 변경을 하나의 저장 지점으로 기록하는 것) 완료 — 3개 파일 기록됨.

레벨 1·2·3·off — 설명이 얼마나 오래 따라오나

레벨은 설명의 양이 아니라 설명이 언제 걷히는지를 정한다. 기본값은 1이고 `/novice:mode 2`처럼 바꾼다. 프롬프트 전체가 정확히 `novice 2`일 때도 같은 동작을 한다.

off는 학습층만 끈다. 톤도 설명도 시각화도 사라지지만 안전 게이트는 그대로 돈다. 이건 설정으로도 끌 수 없게 되어 있다. 플러그인 설정의 `novice_enabled`를 꺼도 게이트는 계속 동작한다.

레벨	설명이 붙는 범위	이럴 때 쓴다
1 (기본)	모든 용어에 뜻 병기, 실행 전·후 해설. 같은 용어가 세션에서 3회 나오면 설명이 걷힌다	처음 켠 날
2	3회까지 설명, 핵심 결정만 해설	용어는 눈에 익었는데 흐름이 아직 낯설 때
3	요청할 때만 설명, 아키텍처·유저플로우 중심	무엇을 만들지에 집중하고 싶을 때
off	학습층 전부 제거 (안전 게이트는 유지)	이미 익숙해졌거나 남에게 화면을 보여 줄 때

mute와 reset — 무엇이 세션이고 무엇이 프로젝트인가

이미 아는 용어에까지 설명이 따라붙으면 그게 곧 소음이다. 그래서 용어 단위로 끄고 켜는 명령이 있다. 프롬프트 전체가 정확히 그 형태일 때만 동작하고, 앞뒤 공백과 마침표 하나까지만 허용한다. 더 쉽게 설명해 줘 같은 일반 문장은 이번 답변에만 영향을 주고 설정을 바꾸지 않는다.

reset과 mute는 방향이 반대다. reset은 카운터를 0으로 되돌려 다시 N회 설명하게 하고, mute는 지금 즉시 설명을 끊고 계속 끊어 둔다.

저장 범위도 다르다. mute는 프로젝트 단위로 저장되어 세션이 바뀌어도 유지되고, reset과 용어 카운터는 세션 스코프다. 용어는 한글 별칭으로도 지정할 수 있어 `novice mute 커밋`도 같은 뜻이다. 사전에 없는 용어는 그냥 무시된다.

명령	동작	저장 범위
`novice mute commit`	그 용어 설명을 지금부터 영구 중단	프로젝트 (세션 넘어 유지)
`novice unmute commit`	mute 해제 — 다시 fade 규칙을 따른다	프로젝트
`novice reset commit`	그 용어 카운터를 0으로 — 다시 N회 설명	세션
`novice reset all`	모든 용어 카운터 초기화	세션

focus — 답이 길어질 때 켜는 형태 규칙

0.4.0에서 붙은 다이얼이다. `/novice:focus on`으로 켠다. 답이 길고 정확한데 정작 무엇부터 해야 할지 모르겠는 상황을 겨냥한 것이다.

켜면 규칙 열 개가 강제된다. 첫 줄은 바로 실행할 수 있는 행동이나 명령이나 경로여야 하고 배경은 그 뒤로 간다. 두 단계 이상이면 번호 목록이 되고 한 항목에는 한 동작만 담는다. 남은 일이 있으면 끝에 2분 안에 할 수 있는 다음 행동 하나가 붙는다. 곁가지는 억제되어 두 번째 이슈는 첫 이슈를 끝낸 뒤에 따로 나온다. 그리고 매 턴 현재 상태를 다시 적는다. 5단계 중 3단계 완료 같은 식이다.

나머지 다섯은 시간 추정을 구체 단위로 할 것, 끝난 일은 이제 무엇이 되는지로 보여 줄 것, 에러는 담담하게 원인과 수정만 적을 것, 목록은 다섯 개를 넘기지 말 것, 서론과 사후 요약과 맺음말을 금지할 것이다. 좋은 질문입니다로 시작하거나 도움이 되었으면 좋겠습니다로 끝나는 답변이 사라진다.

규칙에는 예외 여섯 개가 문서로 박혀 있다. 설명해 달라는 요청에는 충분히 길게 쓰고, 파괴적 작업 앞에서는 확인을 먼저 하고, 세 턴 연속 안 된다는 답이 이어지면 코드 수정을 멈추고 틀렸을 수 있는 전제를 지목한다. 규칙이 답 자체를 지워 버리는 경우에는 답이 이긴다. 선택지가 뭐냐는 질문에 한 갈래만 주면 그건 규칙을 지킨 게 아니라 답을 안 한 것이다.

focus는 레벨과 별개 다이얼이다. `novice off` 상태에서도 동작하고, focus를 꺼도 레벨 지시는 유지된다. 둘이 충돌하면 focus가 이기지만 용어 괄호 병기는 예외로 유지된다. `commit(…)`은 서론이 아니라 인라인이기 때문이다. 모든 프로젝트에서 기본으로 켜 두고 싶으면 플러그인 설정의 `focus_default`를 true로 두면 되고, 프로젝트별 `/novice:focus off`가 그보다 우선한다.

규칙 체계 자체는 새로 만든 것이 아니라 ayghri/i-have-adhd(MIT)에서 가져와 한국어로 옮긴 것이다. 원본은 ADHD 독자를 겨냥해 쓰였는데, 그 조건이 입문자가 긴 답변 앞에서 겪는 것과 겹친다. 작업 기억이 좁고, 아는 것과 실제로 하는 것 사이의 간격에서 일이 죽고, 시작이 가장 어렵다는 조건이다.

안전 게이트는 막는 것과 안 막는 것을 나눠 적는다

이 부분이 이 플러그인에서 가장 조심스럽게 쓰인 곳이다. 안전 기능은 과장하기 쉽고, 과장된 안전 기능은 없느니만 못하다. 그래서 README에도 명시적 비보증 절이 따로 있고 여기에도 같은 내용을 옮긴다.

게이트는 최소 deny-only 코어다. 긍정적으로 식별한 파괴 비가역 작업과 노출된 시크릿 값만 차단하고, 파싱할 수 없거나 애매한 명령은 판정하지 않고 Claude Code 자체 권한 프롬프트에 넘긴다.

위협	막는다	안 막는다 (위임)
로컬 파괴 명령	`rm -rf ~`·`/`·프로젝트 루트, `dd`/`mkfs`/`shred`, PowerShell `Format-Volume`/`Clear-Disk`	복잡한 wrapper 옵션, 난독화, 파이프·체인·치환 낀 명령, 일반 폴더 삭제
Git 이력 파괴	보호 브랜치 대상 `push --force`	비보호 브랜치 force-push, `reset --hard`, `clean`, 다른 Git 클라이언트 작업
원격 리소스 삭제	production·불명 대상 파괴 작업 (CLI·MCP)	staging·dev 대상, 외부 콘솔에서 직접 한 작업
시크릿 노출	커밋 대상 트리·배포 인자·명령줄에서 발견된 시크릿 값	미지원 포맷, 암호화·난독화된 값, 스캔 불가한 대용량 파일
비용 루프	batch당 최대 1회 개입 안내	정확한 과금 계산, 하드 결제 상한

왜 확인 질문 티어를 없앴나

처음 버전에는 확인 질문 단계가 있었다. 애매한 명령이면 정말 실행할지 물어보는 층이다. 상식적으로는 안전해 보인다.

실제로는 반대로 갔다. 게이트가 파이프나 `&&` 같은 문법을 해석하지 못하니 `find . | sort`나 `npm run build && npm test` 같은 아무 문제 없는 명령마다 확인 창이 떴다. 확인 창이 계속 뜨면 사람은 읽지 않고 누른다. 그러면 진짜 위험한 순간에도 읽지 않고 누른다. 경보가 잦아 경보를 무시하게 되는 그 상태가 되면 안전 장치는 안전을 깎아먹는다.

그래서 0.2.0에서 확인 티어를 통째로 걷어냈다. 지금은 확실한 것만 막고 애매하면 아예 의견을 내지 않는다. 대신 Claude Code 자체 권한 규칙이 그 자리를 맡는다. 이 선택에는 명시된 대가가 있다. 파이프가 낀 파괴 명령은 novice가 안 잡는다. 안 잡는다는 사실을 문서에 적어 두는 쪽이, 잡는 척하는 쪽보다 낫다고 봤다.

그 밖에도 보증하지 않는 것을 문서에 적어 뒀다. 범용 셸 파서가 아니고, 완전한 DLP도 시크릿 관리자도 악성 MCP 방어도 아니며, 알려진 패턴 기준으로만 탐지한다. 사용자가 전 리스크를 인수한 `bypassPermissions` 모드에서는 게이트가 완전히 물러난다. Git은 추적 중인 로컬 파일만 지켜 주므로 추적되지 않는 파일이나 외부 DB나 배포된 리소스는 복구 대상이 아니다.

외부 서비스는 어디까지 대신하나

입문자가 실제로 가장 오래 막히는 곳은 코드가 아니라 계정과 CLI다. Vercel에 배포하려면 CLI를 깔아야 하고 그걸 깔려면 패키지 매니저를 알아야 하고 로그인하려면 브라우저와 터미널을 오가야 한다. novice는 이 구간을 상태 머신으로 밟는다.

자동화 경계는 딱 한 줄로 고정돼 있다. 탐지에서 설치, 로그인 실행, 인증 상태 확인까지다. 그 뒤는 하지 않는다. 리소스를 만들고 연결하고, env나 시크릿 값을 넣고, 배포하고, 결제하고, 약관에 동의하는 일은 무엇을 왜 어느 명령으로 하는지 단계별로 안내하되 사용자가 직접 실행한다.

CLI는 2단으로 갈린다. Tier 1은 미리 검토해 저장소에 동봉한 manifest로, 현재 Vercel과 GitHub CLI와 Supabase 셋이다. 설치와 로그인을 각각 한 번씩 승인받고 고정된 패키지 좌표로 진행한다. Tier 2는 그 밖의 모든 CLI다. 공식 문서 URL과 패키지 좌표와 실제로 실행할 명령줄을 화면에 그대로 보여 주고, 사용자가 근거를 확인하고 승인한 경우에만 같은 엔진으로 진행한다. 공식 근거를 확인할 수 없으면 안내만 하는 수동 경로로 낮춘다.

CLI 설치를 거부하거나 사전 점검이 실패하면 경로가 한 단계씩 내려간다. CLI에서 공식·동의된 MCP로, 거기서 눈에 보이는 Chrome 조작으로, 마지막은 안내만 하는 수동이다. MCP는 두 경우에만 쓴다. 미리 검토된 allowlist 항목이거나, 사용자가 이미 Claude에 등록해 둔 서버에 이번 작업에 한해 명시적으로 동의한 경우다. 기본 allowlist는 비어 있고 MCP 서버를 자동으로 설치하지 않는다.

credential 값은 어느 경로에서도 요청·보관·전달·자동입력하지 않는다. 안전한 저장소를 지원하는 CLI가 평문 저장으로 떨어지는 환경에서는 자동 로그인을 아예 중단하고, 파일 저장이 공식 기본 동작인 CLI는 저장 위치와 로그아웃 경로를 로그인 승인 전에 먼저 고지한다.

무엇이 어디에 남고, 무엇을 밖으로 안 보내나

상태는 `CLAUDE_PLUGIN_DATA` 아래에만 저장된다. 플러그인이 설치된 폴더에는 아무것도 쓰지 않는다. 저장되는 것은 프로젝트별 설정과 세션별 용어 카운터다.

상태 파일은 atomic write로 쓰고 권한은 0600이며 심볼릭 링크는 거부하고 크기 상한이 있다. 세션 상태는 `/clear` 시 삭제되고 30일이 지나면 만료된다.

시크릿 스캐너는 후보 바이트를 메모리에서만 검사하고 원문을 로그나 상태 파일이나 지표에 남기지 않는다. 부트스트랩 감사 기록에는 서비스 ID와 manifest 리비전과 단계와 종료 상태만 남는다.

원격 telemetry를 보내지 않는다. 이 플러그인은 서버도 cron도 배포 플랫폼도 갖고 있지 않다.

지금 상태와, 무엇이 아직 검증되지 않았는지

현재 0.4.0이다. 외부 런타임 의존성이 0이고 Node 18 이상, 테스트는 195개가 통과한다. 최소 지원 런타임은 Claude Code 2.1.215다.

안전 게이트는 테스트만으로 끝내지 않고 mutation 하네스로도 검증한다. 위험 명령 35건을 106개 변형으로 바꿔 탐지를 우회하는 경로가 없는지 확인한다. 지연도 회귀 테스트로 묶여 있다. 사용자 입력을 막는 hook이라 p95 예산이 UserPromptSubmit 300밀리초, PreToolUse 250밀리초로 강제된다. focus는 별도 eval 하네스로 케이스 16개와 결정적 형태 검사 13종을 돌린다.

코드로 검증할 수 없어 남아 있는 것도 적어 둔다. 실제 CLI 설치와 로그인 전 구간은 사용자 환경과 계정이 있어야 하고, MCP 파괴 payload는 화면 없이 재현할 수 없으며, 무엇보다 사람이 실제로 덜 막히는지는 참가자가 있어야 잰다. 지금은 팀 안에서 먼저 쓰면서 걸리는 지점을 모으는 단계다.

그래서 이 글은 완성품 발표가 아니라 공유에 가깝다. 비개발자에게 Claude Code를 쥐여 줄 일이 있는 분이라면 먼저 써 보고 어디서 막혔는지 알려 주시는 편이 지금 단계에서 가장 쓸모 있다.

원본(MIT): github.com/hjsh200219/novice · npm: claude-novice