Claude Code 플러그인, 통째로 깔지 않고 알맹이만 빼왔다

지난 편 → 6편 — 챗GPT랑 클로드, 왜 서로 대화는 못 시킬까 Claude Code로 한동안 일하다 보면, 남이 만들어 둔 도구를 가져다 쓰고 싶어지는 순간이 옵니다. 마켓플레이스에 올라온 플러그인 중 하나가 눈에 들어왔습니다. 코드를 필요 이상으로 부풀리지 않게, "게으른 시니어 개발자"처럼 최소로만 짜도록 붙잡아 주는 도구였습니다. 마음에 들었습니다. 그런데 막상 설치하려니 손이 멈췄습니다. 제가 원한 건 그 안에 담긴 원칙 하나 였는데, 플러그인은 그것 말고도 이런저런 것들을 통째로 데려옵니다. 안 쓸 기능까지 제 환경에 얹히는 게 영 내키지 않았습니다. 그래서 깔지 않고, 열어서 필요한 알맹이만 빼내기로 했습니다. 그러려면 먼저 "플러그인"과 "스킬"이 뭐가 다른지부터 알아야 했습니다. 스킬과 플러그인은 뭐가 다른가 한 줄로 하면 이렇습니다. 스킬은 부품 하나, 플러그인은 부품을 담은 상자. 스킬(Skill) 은 최소 단위입니다. SKILL.md 라는 마크다운 파일 하나가 전부고, 필요하면 옆에 보조 파일(스크립트·데이터)을 둘 수 있습니다. 두는 곳도 단순합니다. 개인용: ~/.claude/skills/<이름>/SKILL.md 프로젝트용: .claude/skills/<이름>/SKILL.md 파일 맨 위 frontmatter에 "이 스킬을 언제 써야 하는지"를 적어두면, Claude가 상황을 보고 알아서 불러 씁니다. 아니면 /스킬이름 으로 직접 부를 수도 있습니다. 말하자면 "이 일은 이렇게 처리해라"라고 적어둔 지침 한 장 입니다. 플러그인(Plugin) 은 그 부품들을 담아 배포하는 상자입니다. .claude-plugin/plugin.json 이라는 매니페스트를 중심으로, 여러 종류의 구성요소를 한 번에 묶습니다. skills/ — 스킬들 agents/ — 커스텀 에이전트(서브에이전트...

음성으로 코딩하기 (5편) — Claude가 답했는데 왜 조용하지?

Claude의 답은 화면에 잘 떴어요. 그런데 소리가 안 났습니다. 분명 음성으로 읽어주게 만들어놨는데 말이죠. 범인은 둘이었고, 그중 하나는 뜻밖에도… AI 자신이었어요.

지난 편 → 4편 — 멀쩡한 마이크를 죽었다고 오판한 이유

TTS는 분명 깔끔하게 됐었는데

2편에서 얘기했듯, 출력(Claude→나)은 MCP로 우아하게 풀렸어요. Claude가 답할 때마다 speak라는 도구를 불러서 음성으로 읽어주는 방식이었죠. 잘 됐어요. 가끔 조용해지기 전까지는요.

미스터리 ① — 껐다 켰더니 영영 조용

TTS를 잠깐 껐다가 다시 켰는데, 그 뒤로 영영 소리가 안 났어요. "재생하는 프로그램(워커)이 어디서 멈췄나?" 싶어서 그쪽 코드를 한참 뒤졌죠.

그런데 코드는 멀쩡했어요. 진짜 원인은 황당했습니다. Claude(AI)가 speak 도구를 아예 안 부르고 있었던 거예요.

TTS가 꺼져 있을 때 speak를 부르면 "지금 꺼져 있음(disabled)"이라고 응답해요. Claude가 그걸 한 번 받고는, "어차피 꺼졌겠지" 하고 그 뒤로 speak 부르기를 스스로 생략한 거였죠. 제가 다시 켰는데도 Claude가 안 부르니 계속 조용했던 겁니다.

도구가 고장 난 게 아니라, 도구를 안 부른 거였어요. 이 둘을 구분 못 해서 한참 헤맸죠.

미스터리 ② — 발성이 끝났는데 입력이 막힌다

또 하나. TTS가 말하는 동안엔 마이크 입력을 잠깐 무시하게 해뒀어요. 스피커에서 나오는 Claude 목소리를 마이크가 다시 주워듣는 걸 막으려고요. 이 "지금 재생 중" 상태를 작은 파일 플래그로 표시했죠.

문제는, 재생이 끝났는데도 그 플래그가 "재생 중"으로 박혀서 입력이 영영 막히는 거였어요. 말을 해도 무시당했죠.

범인은 파일 쓰기 경합이었어요 (WinError 5)

플래그를 "재생 끝(0)"으로 바꾸는 쓰기가 실패하고 있었어요. 로그를 보니 WinError 5(액세스 거부). 이유는 이랬어요.

  • 플래그 파일을 안전하게 교체하려고 임시 파일에 쓴 뒤 바꿔치기(rename)를 하는데,
  • 그 순간 다른 프로세스가 같은 파일을 읽고 있으면 윈도우가 교체를 거부합니다.
  • 그런데 한 번 실패하면 재시도가 없어서, 플래그가 "재생 중"으로 영영 박혀버린 거죠.

해결은 두 가지였어요. 쓰기가 실패하면 잠깐 뒤 다시 시도하고, 혹시 그래도 박히면 너무 오래된 플래그는 자동으로 무시(재생이 그렇게 길 리 없으니)하게 안전장치를 뒀습니다.

교훈 — "안 되는 것"과 "안 부른 것", 그리고 파일 경합

증상진짜 원인
껐다 켰더니 계속 조용도구 고장이 아니라 AI가 도구를 안 부름
발성 끝났는데 입력 막힘플래그 파일 쓰기 경합(WinError 5) → stuck

두 교훈이 남았어요. 하나는 "도구가 고장인지, 안 부른 건지"를 먼저 구분하라는 것. 다른 하나는 여러 프로세스가 같은 파일을 건드리면 경합과 재시도를 반드시 고려하라는 것.

AI는 도구를 잘 만들어줬지만, "약속대로 그 도구를 부르고 있는지" 와 "동시 접근에서 안 깨지는지" 는 결국 제가 챙겨야 했어요.

다음 편

이번엔 인식 자체가 이상해집니다. 한국어로 말했는데 영어로 알아듣는 현상, 그리고 노이즈 제거가 오히려 독이 된 이야기. → 6편 — 한국어로 말했는데 영어로 알아듣는 이유


(이전 편: 4편 — 멀쩡한 마이크를 죽었다고 오판한 이유)

댓글