팀 간 반복 작업, 이제 플러그인으로 해결해요
Claude Code를 쓰다 보니 "이걸 왜 매번 처음부터 설명하지?"라는 생각이 들었어요. 팀의 암묵지를 마크다운으로 구조화해서, AI에게 우리 팀의 일하는 방식을 가르치는 플러그인 마켓플레이스를 만든 이야기예요.
2026-02-12
TL;DR
Claude Code는 강력하지만, 우리 팀의 DB 아키텍처도, 디자인 시스템도, 프롬프트 규칙도 모르는 상태로 매번 시작해요. 같은 컨텍스트를 반복 설명하는 게 지쳐서, 팀의 지식을 마크다운 파일로 구조화하고 GitHub 레포 하나로 공유하는 플러그인 마켓플레이스를 만들었어요. 코딩이 아니라 교육에 가까운 작업이었는데, 지금은 팀의 기본 인프라가 됐어요.
매번 같은 말을 반복하고 있었어요
마인드로직 개발팀은 Claude Code를 일상적으로 써요. 코드 리뷰, 리팩토링, 새 기능 개발, 디버깅 — 거의 모든 개발 작업에 Claude가 들어가 있어요.
근데 한 가지 문제가 있었어요. Claude는 매 세션마다 기억을 잃어요.
"우리 팀은 Tortoise ORM을 쓰고 있고, 읽기 전용 레플리카가 따로 있어서 읽기 쿼리는 거기로 보내야 해요" — 이걸 PR 리뷰할 때마다 설명하고 있었어요. "Gemini API 쓸 때 google-genai 패키지를 써야 하고, 예전 google-generativeai는 deprecated됐어요" — 이것도 매번. "FactChat UI 프로토타입 만들 때 프라이머리 컬러는 #2563eb이고, Pretendard 폰트를 써야 해요" — 이것도요.
CLAUDE.md에 기본적인 규칙은 적어놨지만, 한계가 분명했어요:
- 깊이의 문제 — 모델별 가격표, DB 스키마 탐색법, 디자인 토큰까지 전부 넣으면 파일이 수백 줄이 돼요. 모든 세션에서 전부 로딩되니까 비효율적이고요
- 범위의 문제 — 백엔드 엔지니어한테 디자인 시스템 규칙은 필요 없고, 프론트엔드 엔지니어한테 DB 레플리카 라우팅 규칙은 필요 없어요
- 공유의 문제 — A팀에서 만든 DB 쿼리 패턴을 B팀은 몰라요. 프롬프트 엔지니어링 노하우가 한 사람 머릿속에만 있어요
결국 "아는 사람한테 물어보는" 게 가장 빠른데, 그 사람이 항상 있는 건 아니잖아요.
"이걸 모듈화할 수 없을까?"
Claude Code에는 플러그인 시스템이 있어요. 쉽게 말하면 Claude에게 가르칠 수 있는 지식 모듈이에요.
여기서 핵심적인 걸 하나 짚고 가야 해요 — 플러그인은 코드가 아니라 마크다운이에요. SKILL.md 파일 하나에 "이런 상황에서는 이렇게 해"라는 지침을 자연어로 적어두면, Claude가 그걸 읽고 따라해요. 프로그래밍이 아니라 교육에 가까워요.
플러그인은 다섯 가지 구성 요소를 조합해서 만들어요:
| 구성 요소 | 하는 일 | 비유 |
|---|---|---|
| Skills | 맥락에 맞으면 자동으로 활성화 | 참고서 — 상황에 맞으면 알아서 펼쳐봄 |
| Commands | /명령어로 직접 실행 | 리모컨 버튼 — 누르면 바로 동작 |
| Agents | 복잡한 작업을 자율적으로 수행 | 전문가 — 맡기면 알아서 처리 |
| Hooks | 특정 이벤트에 자동 반응 | 센서 — 조건이 맞으면 자동 실행 |
| MCP | 외부 서비스와 연결 | 전화선 — 외부 시스템과 통신 |
그리고 이 플러그인들을 팀 전체가 쉽게 설치하고 공유할 수 있도록, GitHub 레포 하나를 팀 전용 앱스토어로 만들었어요.
# 마켓플레이스 등록 (최초 1회) /plugin marketplace add mindlogic-ai/mindlogic-plugins # 원하는 플러그인 설치 /plugin install prompt-engineering@mindlogic-plugins
이름만으로 설치하고, 업데이트도 마켓플레이스를 통해 동기화돼요. 현재 프롬프트 설계, DB 쿼리 분석, LLM 트레이싱, UI 프로토타이핑, 문서 변환, PR 리뷰 등 9개 플러그인이 운영 중이에요.
플러그인이 실제로 하는 일
플러그인을 하나하나 나열하는 것보다, 이게 실제로 일하는 방식을 어떻게 바꿨는지를 보여주는 게 더 이해가 빠를 거예요.
"프롬프트 짜야 하는데 어디서 시작하지?"
LLM 기반 서비스를 운영하다 보면 프롬프트를 계속 만들고 수정해요. Gemini, Claude, OpenAI — 모델마다 API가 다르고, 가격이 다르고, 잘 먹히는 패턴이 달라요.
prompt-engineering 플러그인이 설치되어 있으면, Claude가 이미 알아요: Gemini Flash 3을 기본으로 쓰고, gemini-2.0-flash는 deprecated라서 쓰면 안 되고, 우리 팀의 프로바이더 래퍼는 from providers import gemini으로 임포트하고, 테스트 스크립트는 여러 모델에 동시에 돌릴 수 있다는 걸.
/design-prompt "사용자 질문에서 의도를 분류하는 프롬프트를 만들어줘"
이렇게 치면 Claude가 프롬프트를 설계하고, 테스트 케이스를 만들고, 여러 모델로 돌려보고, 결과를 비교해줘요.
"이 요청 왜 이렇게 비싸지?"
LLM 서비스를 운영하면 꼭 필요한 게 있어요. **"이 응답이 왜 이렇게 나왔지?"**를 추적하는 거예요.
"FactChat에서 어제 비용이 많이 나온 요청 top 10 보여줘" — 이렇게만 말하면 Claude가 Langfuse API를 호출하는 Python 스크립트를 실행해서 결과를 가져와요. 트레이스 ID를 주면 그 요청의 전체 호출 체인(프롬프트 → 모델 응답 → 후처리)을 쫓아가며 분석해주고요.
예전에는 Langfuse 대시보드에 로그인해서, 필터 걸고, 요청 하나하나 열어보면서 "이 프롬프트가 너무 길었네" 같은 걸 수동으로 찾았어요. 지금은 Claude가 데이터를 뽑고 해석까지 해줘요.
"PR 올렸는데 쿼리 성능 괜찮을까?"
/review-db 123
이렇게만 치면 Claude가 PR #123의 DB 변경사항을 분석해요. N+1 쿼리 패턴, 인덱스 누락, 읽기/쓰기 라우팅 실수 — 이런 것들을 우리 팀의 ORM(Tortoise)과 DB 아키텍처(읽기 레플리카 분리) 맥락에서 잡아줘요.
특히 읽기 레플리카 라우팅은, 코드만 봐서는 "이게 마스터로 가는 쿼리인지 레플리카로 가는 쿼리인지"가 바로 안 보이거든요. 사람이 리뷰할 때 놓치기 쉬운 건데, 플러그인은 그 규칙을 알고 있으니까 매번 잡아줘요.
"이런 화면 상상해봐" → "이런 화면 만들어줘"
/prototype-ui factchat "회의 녹음 요약 화면"
이 플러그인이 특별한 건, 우리 제품의 실제 디자인 시스템을 알고 있다는 점이에요. FactChat의 프라이머리 컬러, 사이드바 레이아웃, 폰트, 채팅 버블 스타일 — 이런 디자인 토큰이 JSON 파일로 정리되어 있고, 실제 프로덕션 스크린샷까지 레퍼런스로 들어 있어요.
결과물은 단일 HTML 파일이에요. 브라우저에서 바로 열어볼 수 있고, S3에 올려서 URL로 공유할 수도 있어요. 기획 회의 전에 "이런 느낌이에요"를 보여주는 데 피그마를 열 필요가 없어진 거예요.
공통 설계 패턴
9개 플러그인을 만들면서 자연스럽게 정착된 패턴들이 있어요.
패턴 1: Description이 트리거다
플러그인에서 가장 중요한 부분은 스킬의 description 필드예요. Claude가 "이 스킬을 지금 활성화할지 말지"를 이 텍스트 하나로 결정하거든요.
description: This skill should be used when the user asks to "design a prompt", "test prompts", "optimize prompts", "work with LLM APIs", discusses "Gemini", "Claude", "OpenAI" API integration, or needs guidance on prompt engineering...
처음에는 설명을 대충 적었다가, 스킬이 활성화되지 않는 경우가 많았어요. "프롬프트"라고만 적으면 "프롬프트 엔지니어링"이라는 맥락에서만 트리거되고, "LLM API 연동" 같은 상황에서는 작동을 안 해요. 사용자가 실제로 쓸 법한 표현을 최대한 다양하게 넣어야 해요. 검색 엔진 최적화랑 비슷한 감각이에요.
패턴 2: Progressive Disclosure — 깊이를 분리해요
SKILL.md 자체는 500줄 이내로 유지하고, 상세한 참고 자료는 references/ 폴더에 넣어요.
skills/langfuse/
├── SKILL.md # 핵심 지침 (빠르게 읽음)
├── references/
│ ├── integration-patterns.md # 연동 패턴 상세
│ └── helicone-migration.md # 마이그레이션 가이드
└── scripts/
├── fetch_trace.py # 트레이스 상세 조회
└── fetch_metrics.py # 비용/지연 메트릭
일단 핵심만 주고, 필요하면 더 깊이 들어가는 방식이에요. Claude가 필요할 때만 참조하니까, 매 세션마다 모든 정보를 로딩하는 오버헤드가 없어요. 이게 CLAUDE.md에 전부 넣는 것과의 결정적인 차이예요.
패턴 3: 마크다운 + 스크립트 조합
대부분의 지식은 마크다운으로 충분해요. 하지만 외부 API를 호출하거나, DB에 접속해서 데이터를 가져오는 건 마크다운만으로 안 돼요. 이런 건 scripts/ 폴더에 Python 스크립트를 넣어요.
마크다운이 "뭘 해야 하는지"를 가르치고, 스크립트가 "실제로 실행"해요. Claude가 fetch_metrics.py를 적절한 파라미터로 호출하고, 결과를 해석해서 알려주는 거예요.
패턴 4: 도메인 전문가가 직접 만들어요
"코드가 아니라 마크다운"이라는 게 중요한 이유가 여기 있어요. "우리 팀은 이렇게 일해요"를 글로 정리할 수 있는 사람이면 누구나 플러그인을 만들 수 있어요. 백엔드 엔지니어가 DB 리뷰 규칙을, 프론트엔드 개발자가 디자인 규칙을, 각자의 도메인 지식을 직접 가르치는 거라 품질도 높아요.
플러그인 만드는 법
새로운 플러그인 만드는 건 생각보다 간단해요.
plugins/my-plugin/
├── .claude-plugin/
│ └── plugin.json # 이름, 설명, 버전
├── skills/
│ └── my-skill/
│ ├── SKILL.md # Claude가 알아야 할 지식
│ ├── references/ # 상세 참고 자료
│ └── scripts/ # 실행 가능한 스크립트
└── commands/
└── my-command.md # /명령어로 호출
plugin.json에 이름과 설명을 적고, SKILL.md에 Claude가 알아야 할 지식을 적으면 끝이에요. 마켓플레이스의 marketplace.json에 등록하면 팀 전체가 이름만으로 설치할 수 있고요.
어떤 구성 요소를 만들어야 할지 모르겠다면:
| 상황 | 선택 |
|---|---|
| "이 맥락이면 자동으로 이거 해줘" | Skill |
"내가 /명령어로 부를 때만" | Command |
| "알아서 여러 단계 처리해줘" | Agent |
| "특정 이벤트가 발생하면 자동으로" | Hook |
결국은 "팀의 암묵지를 구조화하는 것"
이 작업을 하면서 깨달은 게 있어요. 플러그인을 만드는 건 결국 팀의 암묵지를 명시지로 바꾸는 과정이에요.
"우리 팀은 읽기 쿼리를 레플리카로 보내요" — 이건 팀에서 6개월 이상 일한 사람은 당연히 아는 건데, 새로 온 사람은 모르고, Claude는 더더욱 모르는 지식이에요. 이걸 마크다운 파일로 적어두면, 새 팀원도 Claude도 첫날부터 이 규칙을 따를 수 있어요.
전통적으로 이런 지식은 위키에 적어두고, 아무도 안 읽고, 금방 outdated 되고, 결국 "그건 그냥 물어봐야 해요"가 돼요. 플러그인과의 차이점은 이 지식이 실제로 사용된다는 거예요. 위키에 적어둔 규칙은 사람이 기억해야 하는데, 플러그인에 적어둔 규칙은 Claude가 알아서 따르니까요.
이제 누가 "그거 어떻게 해?" 라고 물으면 이렇게 대답해요:
"그거 플러그인 있어."
지식이 슬랙 어딘가에 묻히지 않아요. 담당자 머릿속에만 있지 않아요. 누가 퇴사해도 워크플로우는 남아요.
마무리하며
플러그인 마켓플레이스를 만든 건 거창한 프로젝트가 아니었어요. "이거 매번 설명하기 귀찮다"에서 시작했거든요.
근데 만들고 보니, 단순히 반복 작업을 줄이는 것 이상의 효과가 있었어요. 팀의 지식이 파편화되지 않고 한 곳에 모이고, 새 팀원이 Claude와 함께 첫날부터 팀의 규칙을 따라 일할 수 있게 됐어요. AI 도구를 "더 잘 쓰는 법"은 결국 "우리 팀의 일하는 방식을 AI에게 잘 가르치는 법"이었어요.
Claude Code 플러그인에 관심이 있다면 공식 문서를 확인해보세요. 그리고 이런 방식으로 AI 도구를 깊게 활용하는 데 관심이 있다면, 마인드로직 팀에서 같이 만들어봐요.