사내 Claude Code 마켓플레이스 도입 후기

들어가며

안녕하세요. 노머스 백엔드 엔지니어 임승훈입니다.

최근 개발팀 내에서 Claude Code를 비롯한 AI 코딩 도구를 적극적으로 도입하면서 업무 생산성에 많은 변화가 있었습니다.

하지만 사용하는 팀원이 늘어날수록 한 가지 고민이 생겼습니다. 각자 로컬 환경(~/.claude/)에서 기가 막힌 프롬프트나 스킬을 만들어 쓰고 있는데, 이 귀중한 노하우들이 만든 사람의 컴퓨터에만 갇혀 있었던 것입니다. 반대로 AI는 우리 팀의 코딩 컨벤션이나 레이어 구조를 전혀 모른 채 코드를 작성했고, 결국 코드 리뷰에서 사람이 같은 지적을 반복해야 했습니다.

이 문제를 풀기 위해 개발팀 누구나 유용한 스킬과 설정을 쉽게 등록하고 공유할 수 있는 사내 Claude Code 마켓플레이스를 구축했습니다.

이번 글에서는 별도의 복잡한 인프라 없이 Git 저장소 하나와 CI만으로 마켓플레이스를 구성한 방법과, 백엔드 파트에서 실제로 적용해 효과를 보고 있는 워크플로우, 그리고 운영 과정에서 겪은 시행착오와 인사이트를 공유하고자 합니다.

1. 왜 사내 마켓플레이스여야 했을까?

1-1. 사람 머릿속과 로컬에 갇힌 노하우

처음 부딪힌 문제는 지식의 파편화였습니다.

백엔드 파트에는 테스트 작성 구조, DTO와 컨트롤러 분리 기준, PR 전 점검 항목처럼 오랜 시간 합의해 온 규칙들이 있었습니다. 하지만 이 규칙들은 문서로 체계화되기보다 사람의 머릿속과 PR 리뷰 코멘트에 흩어져 있었습니다. AI 도구를 사용하기 시작하자 이 문제가 더 도드라졌습니다. 컨벤션을 모르는 AI가 코드를 작성하니, 리뷰어는 매번 같은 피드백을 반복해야 했습니다.

한편, 팀원들의 로컬 환경(~/.claude/)에는 각자 다듬어 둔 유용한 프롬프트와 절차서가 쌓여가고 있었습니다. 누군가는 PR 리뷰 절차를 멋지게 자동화해 두었고, 누군가는 장애 대응 시 로그 추적 순서를 스크립트로 정리해 두었습니다. 하지만 메신저로 마크다운을 복사해 공유하다 보니 금세 파편화된 복사본이 생겼고, 원작자가 기능을 개선해도 다른 팀원들에게는 반영되지 않았습니다.

1-2. CLAUDE.md 복사-붙여넣기의 한계

각 코드 저장소의 CLAUDE.md에 공통 컨벤션을 적어두는 방법도 고민했습니다. 하지만 두 가지 명확한 한계가 있었습니다.

• 동기화 문제: 여러 저장소에 같은 컨벤션을 복사해 두면, 규칙이 바뀔 때마다 모든 저장소의 CLAUDE.md를 일일이 찾아다니며 수정해야 합니다.
• 컨텍스트 낭비: CLAUDE.md는 세션 시작 시 통째로 로드됩니다. 모든 규칙을 다 집어넣으면 단순한 오타 수정 작업에서도 긴 문서가 컨텍스트 윈도우를 불필요하게 차지합니다.

규칙을 중앙에서 한 번에 관리하면서, 현재 작업에 꼭 필요한 규칙만 그때그때 불러올 수 있는 방식이 필요했습니다.

1-3. “파일 공유”를 넘어 “플러그인 배포”로

Claude Code를 프로젝트에 맞게 맞춤화하는 방법은 다양합니다.

• 스킬(Skill): 특정 작업의 절차서 (SKILL.md) — 호출 시점에 로드
• 훅(Hook): 도구 호출 전후 특정 이벤트에 실행되는 스크립트
• MCP 서버: 외부 시스템(DB, Jira, Figma 등)과의 연동

문제는 스킬 파일만 공유해서는 온전한 자동화가 어렵다는 점이었습니다. 훅을 쓰려면 스크립트 실행 권한과 설정 파일을 맞춰야 하고, MCP는 접속 주소와 클라이언트를 각자 세팅해야 했습니다. 설치 방법을 안내하고 트러블슈팅하는 데만 적지 않은 시간이 들었습니다.

스킬·훅·MCP·커맨드를 하나의 설치 단위인 ‘플러그인’으로 묶고, 이를 사내 마켓플레이스에서 원클릭으로 내려받을 수 있는 구조가 필요했던 이유입니다.

2. 어떻게 만들었는가: Git 저장소 하나와 CI

2-1. 별도 서버 없이 Git 저장소 하나가 곧 앱스토어

Claude Code 공식 규격의 플러그인 마켓플레이스를 활용하면, 별도의 웹 서버나 데이터베이스 없이 공용 Git 저장소 하나로 마켓플레이스를 구성할 수 있습니다.

저장소 루트에는 전체 카탈로그를 두고, plugins/ 하위에 각 플러그인을 모았습니다. 한 플러그인에 관련된 여러 스킬을 함께 담을 수 있는 구조입니다.

<사내 마켓플레이스 저장소>/
├── README.md                         # 설치 및 등록 가이드
├── .claude-plugin/marketplace.json    # Claude Code 카탈로그 (CI 관리)
├── registry.json                     # 사내 플러그인 메타 목록 (CI 관리)
└── plugins/
    └── backend-tools/
        ├── manifest.json             # 공통 메타데이터 (CI 자동 생성)
        ├── .claude-plugin/plugin.json # Claude 플러그인 정의 (CI 생성)
        ├── .codex-plugin/plugin.json  # Codex 호환 정의 (CI 자동 생성)
        └── skills/
            ├── code-review/SKILL.md   # 작성자가 등록한 스킬
            └── conventions/SKILL.md

2-2. “작성자는 스킬만, 배포는 CI가”: 등록 장벽 낮추기

마켓플레이스를 만들 때 가장 중요하게 생각한 원칙은 기여 장벽을 극단적으로 낮추는 것이었습니다.

스킬 하나 공유하려는데 marketplace.json, manifest.json, plugin.json 같은 메타데이터 규격을 공부하고 수동으로 채워 넣어야 한다면 아무도 참여하지 않습니다. 그래서 역할을 명확히 나누었습니다.

“작성자는 스킬 내용과 필요한 설정만 작성해 PR을 올린다. 배포에 필요한 메타데이터와 카탈로그 파일은 CI(GitHub Actions)가 알아서 검증하고 생성한다.”

1. 작성자가 plugins/<플러그인>/skills/<스킬>/SKILL.md를 추가하고 PR을 올립니다.
2. GitHub Actions가 변경된 디렉터리를 감지해 마크다운 규격과 네이밍을 검증합니다.
3. CI가 manifest.json과 카탈로그(marketplace.json)를 자동으로 생성·갱신해 해당 PR에 커밋을 푸시합니다.
4. 리뷰 후 머지되면 즉시 마켓플레이스에 배포됩니다.

2-3. 조직(Organization) 설정으로 전사 0-Click 배포

개별 환경에서 마켓플레이스를 등록하려면 아래 명령어를 실행하면 됩니다.

claude plugin marketplace add <org-name>/<marketplace-repo>

하지만 팀원들에게 이 명령어를 일일이 치게 할 필요도 없습니다. Claude Organization 설정에서 사내 저장소를 연결해 두면, 구성원은 별도 등록 절차 없이 /plugin 명령어만 쳐서 원하는 플러그인을 찾아 설치할 수 있습니다.

3. 실전 적용기: 노머스 백엔드 팀의 3단계 워크플로우

플러그인이 배포 단위라면, 스킬은 작업 단계별 실행 단위입니다. 백엔드 파트에서는 개발 사이클 전체를 3단계 스킬로 나누어 관리하고 있습니다.

3-1. 컨벤션 스킬 — AI가 작성한 코드에 팀의 결을 입히다

가장 먼저 만든 스킬입니다. AI는 우리 팀만의 컨벤션을 스스로 알지 못합니다.

계층 구조, DTO 네이밍, 예외 처리 방식, 테스트 컨벤션 등은 팀마다 다릅니다. 이 기준을 알려주지 않으면 기존 코드베이스와 AI가 생성한 코드의 스타일이 뒤섞여 가독성이 떨어집니다.

컨벤션 스킬은 코드를 작성하거나 수정할 때 관련 규칙을 먼저 참조하도록 유도합니다. 덕분에 코드 작성 시점부터 팀의 컨벤션에 자연스럽게 맞춰지며, 신규 입사자도 리뷰를 거치기 전에 팀의 표준 패턴을 코드로 체득할 수 있게 되었습니다. 컨벤션이 변경되면 마켓플레이스 저장소의 파일 하나만 수정해 머지하면 됩니다.

3-2. 코드 리뷰 스킬 — 반복되는 피드백을 앞으로 당기다

PR에서 반복적으로 나오던 피드백을 스킬로 녹여냈습니다. 특히 상황에 따라 두 가지 모드로 동작하도록 설계했습니다.

• 로컬 모드 (자가 점검): PR을 올리기 전 작업 브랜치에서 실행합니다. 자주 지적받던 규칙 위반을 로컬에서 미리 잡아내고, act를 통해 GitHub Actions CI를 로컬에서 직접 구동하여 테스트 실패를 사전에 차단합니다.
• PR 모드 (동료 리뷰): 동료의 PR diff를 분석하여 팀 컨벤션 기반의 리뷰 코멘트 초안을 작성합니다.

이 방식의 핵심은 작성과 리뷰가 완전히 동일한 규칙 문서를 근거로 삼는다는 점입니다. 덕분에 코멘트에도 근거 규칙을 명확히 명시할 수 있어 리뷰가 개인 취향 논쟁으로 흐르지 않고, 리뷰어는 단순 스타일 지적 대신 아키텍처와 도메인 설계 같은 본질적인 고민에 집중할 수 있게 되었습니다.

3-3. 문서화 스킬 — 코드가 곧 유일한 진실(Single Source of Truth)

도메인 지식과 서비스 간 통신 맵(communication.md)을 코드베이스에서 직접 추출해 문서를 갱신하는 스킬입니다.

문서를 별도로 작성하면 실제 구현과 어긋나기 십상입니다. 저희는 “코드와 문서가 다르면 코드가 진실이다”라는 원칙을 세웠습니다. 스킬이 실제 코드를 분석해 최신 상태를 문서에 반영하므로, 코드 작업이 끝난 흐름 그대로 문서화 부채를 바로 해소할 수 있게 되었습니다.

3-4. 훅(Hook)으로 만든 3단계 안전장치

스킬이 작업 절차를 돕는 가이드라면, 훅은 정해진 시점에 반드시 실행되는 강제 장치입니다. 저희는 Claude Code 훅을 세 가지 형태로 나누어 안전장치를 마련했습니다.

• 차단형 훅: .env나 인증서 등 시크릿 파일에 대한 접근 명령을 원천 차단합니다.
• 승인 게이트형 훅: PR 코멘트 등록이나 머지처럼 외부에 영향을 미치는 작업 직전에 사람의 명시적 승인을 요구합니다.
• 알림형 훅: 비즈니스 로직을 수정했는데 테스트 코드나 도메인 문서 변경이 빠져 있다면 경고 메시지를 띄워줍니다 (작업을 막지는 않고 알림만 제공).

4. 프로덕션에서 굴리며 배운 실전 인사이트

실제로 마켓플레이스를 운영하면서 겪은 시행착오와 기준들을 정리했습니다.

4-1. description은 기능 설명이 아니라 ‘호출 트리거’를 적어야 한다

스킬을 아무리 잘 작성해도 필요한 순간에 Claude가 스킬을 호출하지 않으면 무용지물입니다. Claude는 스킬의 이름과 description을 읽고 현재 대화 맥락에 이 스킬이 필요한지 판단합니다.

초기에는 기능 위주로 짧게 썼다가 스킬이 잘 트리거되지 않는 문제를 겪었고, 이후 팀원들이 실제로 입력할 법한 발화 표현과 동작 조건을 상세히 담는 방식으로 개선했습니다.

# 개선 전 — 무엇을 하는지만 적음 (트리거 확률 낮음)
description: 코드를 리뷰합니다.

# 개선 후 — 언제, 어떤 표현으로 호출되어야 하는지 명시
description: >
  변경된 코드를 팀 컨벤션 기준으로 리뷰하는 스킬. "코드 리뷰", "리뷰해줘",
  "PR 봐줘", "올리기 전에 한번 봐줘" 요청 시 사용. PR 번호를 주면 동료 PR 모드,
  인자가 없으면 로컬 변경사항 자가 리뷰 모드로 동작한다.
  코멘트 등록과 머지는 사용자 승인 없이 하지 않는다.

자연스러운 호출 표현과 함께 파라미터 분기 조건, 사용자 승인 필요 여부까지 적어주니 의도한 시점에 정확히 동작하기 시작했습니다.

4-2. 훅의 생명은 속도: fail-open과 fail-closed 전략

도구 호출에 연결된 훅은 도구가 실행될 때마다 매번 불리기 때문에 찰나의 지연도 체감 속도에 큰 영향을 줍니다. 그래서 대부분의 훅에 3초의 타임아웃을 설정하고, 무거운 작업은 세션 시작 시점(SessionStart)으로 분리했습니다.

더 중요한 것은 실패 시의 처리 전략입니다.

• 보조 작업은 Fail-Open: 외부 저장소 동기화나 알림 같은 보조 훅은 네트워크 이슈 등으로 실패하더라도 개발 세션을 멈춰서는 안 됩니다. 조용히 넘어가고(fail-open) 개발이 계속 진행되도록 했습니다.
• 보안 검사는 Fail-Closed를 고려한 설계: Claude Code의 커맨드 훅은 타임아웃이 발생하면 기본적으로 통과시킵니다. 시크릿 차단 훅이 외부 네트워크 호출을 포함하고 있다면, 3초 타임아웃 시 오히려 검사를 건너뛰는 위험이 생깁니다. 따라서 차단형 훅은 외부 호출을 배제하고 순수 로컬 정규식/경로 매칭만으로 즉시 판정하도록 작성해 구멍을 막았습니다.

4-3. 사내 저장소라도 시크릿은 절대 커밋 금지

공용 마켓플레이스 저장소에는 어떠한 시크릿 값도 커밋하지 않습니다.

MCP 설정에는 서버 URL과 인터페이스 명세만 커밋하고, 인증 토큰은 각 사용자가 OAuth로 발급받거나 로컬 환경변수를 사용하게 했습니다. 사내 비공개 저장소라 할지라도 언젠가 로컬에 복제되고 CI 캐시에 남기 때문에, 보안 경계는 처음부터 엄격하게 분리하는 것이 안전합니다.

4-4. Claude Code를 넘어 멀티 AI 도구 확장

skills/<스킬명>/SKILL.md 구조는 Claude Code뿐만 아니라 Codex 등 다른 AI 에이전트 도구에서도 폭넓게 지원하고 있습니다. 저희는 스킬 본문(SKILL.md)을 단일 원천으로 유지하면서, CI에서 각 도구 규격에 맞는 매니페스트를 자동 생성하도록 구성했습니다. 한 번 작성한 워크플로우를 도구에 구애받지 않고 팀 전체의 표준으로 재활용할 수 있게 되었습니다.

마치며: 개인의 요령에서 팀의 자산으로

사내 마켓플레이스를 도입하면서 얻은 가장 큰 수확은 팀의 컨벤션과 AI 활용 노하우가 “개인의 요령”에서 “설치 가능한 자산”으로 바뀌었다는 점입니다.

예전에는 누군가 좋은 프롬프트를 만들면 메신저로 텍스트를 복사해 받아야 했고, 환경이 바뀌면 다시 세팅하느라 시간을 허비했습니다. 지금은 개발팀 누구나 PR 하나로 팀 전체에 유용한 스킬을 배포할 수 있고, 새로 합류한 팀원도 명령어 한 줄로 팀의 개발 표준을 로컬에 장착할 수 있습니다.

AI 코딩 도구를 팀 단위로 도입하면서 컨벤션의 파편화나 노하우 공유로 고민하고 계신다면, 거창한 시스템 대신 작은 Git 저장소와 CI 자동화로 사내 마켓플레이스를 만들어 보시기를 추천합니다.

읽어주셔서 감사합니다.