2026년 07월 19일
지금 사내 AI 툴은 클로드코드를 사용하고 있습니다. 팀원들 모두 클로드코드를 사용하고 있는 환경에서 어떻게 하면 더 잘 사용할 수 있을까 고민했고, 특히 모두가 같은 규칙과 퀄리티를 가진 코드가 나와야 한다고 생각했습니다. 이를 해결하기 위해 클로드코드 플러그인을 통해 공통의 툴을 공유해보기로 했습니다.
새로운 기능을 구현하거나, 기존 기능을 개선해야 할 때 한 대화 세션마다 일일이 컨텍스트를 제공해야 하는 번거로움이 있었습니다. 물론 context7 , superpowers 등을 통해 컨텍스트를 보존하는 방법은 있었지만 그럼에도 새 세션을 열 때마다 추가 정보를 제공해야하는 건 마찬가지였습니다.
예시: 유저 퍼널 페이지를 만들려고 해.
기존 유저 내부 로그를 트래킹 할 수 있는 로직이 있는데 이걸 기반으로 퍼널 경로를 보려고 해
이미 GA4가 구축되어 있지만 이와 별개로 내부적으로 기준을 세우며 볼 수 있는 페이지를 만들고 싶어
(CSS는 디자인 토큰 가이드를 따라야 하고 E2E 테스트는 Playwright를 사용하고 있고
이 기능을 구현하기 위해 포인트 적립 가이드 문서와 DB 관련한 작업을 위해 MongoDB Prisma를 살펴봐야해)
물론 Plan Mode 를 사용하면 코드베이스를 탐색하고 개발자에게 질문을 하면서 실제 기능 구현을 위해 스스로를 개선하지만 이미 이전에 있는 기능이나, 타 레포지토리에 있는 코드, 정책 같은 것은 개발자가 컨텍스트로 주입해줘야 하는 불편함은 그대로였습니다.
특히 특정 플로우에 익숙하지 않거나 해당 기능에 대한 히스토리를 모르는 개발자가 컨텍스트를 올바르게 주지 못하면 그것 또한 문제가 될 수 있었습니다. 정책에 맞지 않는 코드를 만들거나, 결과적으로 중복된 코드가 생길 수 있는 위험이 있었습니다
결론적으로 사내 환경과 목적에 맞게 최적화된 플러그인을 만들어 더 효과적으로 사용할 뿐만 아니라, 팀원들이 공유할 수 있는 툴을 만들어 코드 품질과 생산성 향상에 기여하고자 마켓플레이스 구축을 시작했습니다.
이러한 불편함을 해소하기 위해 사내 마켓플레이스를 설계하고, 개발 생산성을 높여줄 세 가지 핵심 플러그인을 정의하여 순차적으로 구현을 진행하고 있습니다. 지속적으로 필요한 것이 있을 때마다 추가 및 보완할 수 있는 구조로 설계 했습니다. 각 플러그인은 독립적으로도 사용 가능하며 서로 연계 되어 사용될 수 있도록 했습니다.
클로드코드나 외부 오픈소스에는 이미 코드를 검토해주는 기본 스킬들이 존재합니다. 그럼에도 사내 전용 플러그인을 별도로 구축한 이유는 아래와 같습니다.
AGENTS.md 등에 넣기 힘든 것들을 한 곳에 모았고 플러그인은 실시간으로 가져와 대조할 수 있도록 했습니다.마켓플레이스 내 플러그인들을 구현하기 위해 활용한 클로드코드의 주요 확장 개념들은 다음과 같습니다.
클로드코드의 행동을 확장하는 재사용 가능한 묶음입니다. 플러그인을 사용하면 프로젝트와 팀 전체에서 공유할 수 있는 사용자 정의 기능으로 클로드 코드를 확장할 수 있습니다.
플러그인을 만들려면 크게 4가지 구성 요소가 있습니다.
| 구성 요소 | 한 줄 설명 | 예시 |
|---|---|---|
| Slash command | /명령어 로 부르는 단축 매크로 | /op-code-review:op-review |
| Subagent | 별도 컨텍스트로 도는 "전문가 분신" | 보안 리뷰어, 품질 리뷰어 |
| Hook | 특정 이벤트 후 자동 실행되는 스크립트 | git commit 후 자동 안내 |
| Skill | 상황에 맞게 자동 발동되는 매뉴얼 | "리뷰 요청" 패턴 감지 시 활성화 |
플러그인을 여러 개 묶어 배포하는 단위. 한 GitHub 레포 또는 로컬 디렉토리가 곧 마켓플레이스입니다. 사용자는 마켓플레이스를 등록하고, 그 안에서 원하는 플러그인만 골라 설치합니다.
예시
# 마켓플레이스 등록 (한 번만)
/plugin marketplace add ~/Desktop/local-web/local-claude-marketplace
# 그 안에서 원하는 플러그인 설치
/plugin install op-code-review@example
Claude가 외부 서비스 (Sentry, Linear, Slack) 에 접근하기 위한 표준 프로토콜
우리 마켓플레이스에서는 Context7 MCP 를 통해 reviewer-frontend 가 Next.js 16 / React 19 최신 docs 를 자동 참조합니다.
작업별 워크플로우 및 향상된 컨텍스트 관리를 위해 특화된 AI Sub Agent를 만들 수 있습니다.
예를 들면 같은 컨텍스트의 Claude가 자기 코드를 리뷰하면 self-bias 가 끼어들 수 있습니다.
서브에이전트는 별도 컨텍스트로 출발해 자기 임무만 보기 때문에 가차없이 지적할 수 있습니다.
ADR(Architecure Decision Record)란 소프트웨어 개발 프로젝트에서 기술적 의사결정의 배경, 이유, 대안 결과 등을 구조적으로 기록하는 짧은 문서를 말합니다.
쉽게 말하면 내부 정책, 기술 스택 등을 정리한 문서입니다.
아래 가이드를 참고하면 좋습니다.
https://www.cncf.co.kr/blog/adr-architecture-decision-record/
현재 사내 마켓플레이스는 다음과 같이 독립된 플러그인 구조로 관리되고 있으며, 필요한 플러그인만 골라서 설치할 수 있습니다.
지금 글에서는 코드 리뷰 전담 플러그인인 op-code-review 를 예시로 설명하겠습니다.
onliveplus-claude-marketplace/
├── .claude-plugin/marketplace.json ← 마켓플레이스 매니페스트 (플러그인 등록)
└── plugins/
├── op-code-review/ ← 코드 리뷰 전담
└── op-superpowers/ ← 외부 superpowers ↔ 우리 도구 연결 전담
/op-code-review:op-review 명령어가 실행되면 다음 4개의 서브 에이전트가 동시에 git diff 영역을 교차 검증합니다.
| 리뷰어 | 검사 항목 | 예시 위반 |
|---|---|---|
| 🔴 reviewer-security | 인증/JWT, 시크릿 노출, NoSQL injection, 권한 우회, S3 우회 | JWT_SECRET 코드에 하드코딩 |
| 🟠 reviewer-quality | 타입 안정성, 에러 핸들링, console.log 잔존, N+1, App Router 함정 | any 캐스팅, console.log 잔여 |
| 🔵 reviewer-convention | 사내 ADR 위반 (PointLedger 강제, ObjectId 패턴 등) | 포인트 직접 업데이트 |
| 🟢 reviewer-frontend | Toss Frontend Design Guide 14룰 (Readability/Predictability/Cohesion/Coupling) | 매직 넘버, props drilling |
정책이나 컨벤션이 바뀔 때마다 에이전트의 프롬프트 소스코드를 매번 수정하는 것은 비효율적입니다. 이를 해결하기 위해 플러그인 내부에 conventions/ 폴더를 두고 사내 문서들을 모아두었습니다.
conventions/
├── _shared/ ← 공통 룰
├── repo-A/adr/ ← 레포 A 전용 정책 (cp-adr-001 ~)
├── repo-B/adr/ ← 레포 B 전용 정책 (cpa-adr-001 ~)
└── repo-C/adr/ ← 레포 C 전용 정책 (of-adr-001 ~)
플러그인이 동작할 때 git remote 명령어를 실행하여 현재 개발자가 어떤 레포지토리에서 작업하고 있는지 식별합니다. 식별된 레포지토리에 맞는 ADR 폴더와 공통 룰(_shared/)을 동적으로 읽어와 컨텍스트로 주입합니다. 이렇게 하면 새로운 정책이 생겼을 때 마크다운 문서만 추가하거나 수정하면 에이전트 프롬프트를 건드리지 않고 즉시 반영할 수 있습니다.
클로드코드의 PostToolUse 이벤트를 활용해 개발자가 클로드에게 커밋을 부탁하고 배시(Bash) 도구 사용이 끝난 직후, 플러그인 내부의 post-commit-review.sh가 트리거되도록 설정했습니다. 커밋 직전 변경 라인과 안내 메시지를 자동으로 출력해 주는 구조입니다.
op-code-review로 라우팅되도록 처리했습니다.정책 문서가 바뀌거나 프롬프트 수정이 이루어졌을 때, 혹은 새로운 기능들이 추가 되었을 때 이전에 잘 잡아내던 위반 코드를 여전히 잘 잡아내고 일관성 있는 결과를 출력하는 검증 과정이 필요했습니다. 이를 위해 몇 가지 의도적인 위반 코드 샘플(fixture)을 만들어 두고 자동 검증 스크립트를 작성했습니다.
## fixture 코드 예시
---
fixture_id: "01-point-ledger-bypass"
expected_reviewer: convention
expected_severity: critical
expected_category: point-ledger
adr_id: cp-adr-001
---
# 위반 코드
```ts
import { prisma } from "@/lib/prisma";
export async function rewardUser(userId: string, amount: number) {
await prisma.user.update({
where: { id: userId },
data: { balance: { increment: amount } }, // ❌ 직접 업데이트 우회 (PointLedgerService를 거쳐야 함)
});
}
컨텍스트 주입 피로도 감소: 새로운 대화 세션을 열 때마다 사내 가이드라인이나 기술 스택 문서를 길게 복사-붙여넣기 하던 번거로움이 사라졌습니다. 터미널에서 명령어 한 줄만 입력하면 현재 작업 중인 레포지토리를 인식해 필요한 ADR 문서들을 알아서 가져오기 때문에 진입 장벽이 많이 낮아졌습니다.
코드 품질의 상향 평준화: 프로젝트의 히스토리를 잘 모르거나 특정 플로우에 익숙하지 않은 팀원이 작업하더라도, 에이전트들이 사내 정책을 가차 없이 지적해 줍니다. 덕분에 누락되기 쉬운 휴먼 에러가 리뷰 단계에서 먼저 걸러지게 되었습니다.
프롬프트 관리의 엔지니어링화: AI의 답변 퀄리티를 높이기 위해 시스템 프롬프트를 매번 복잡하게 튜닝하는 대신, 마크다운 문서(ADR)를 자산화하고 이를 회귀 테스트(Regression Test) 스크립트로 검증하는 구조를 만들었습니다. 운영 관점이 훨씬 투명하고 명확해졌습니다.
AI 툴을 단순히 개인의 생산성을 높이는 비서로만 사용하는 것을 넘어, 팀의 규칙과 문서를 결합한 '공통의 플러그인' 형태로 자산화했을 때 팀 전체의 협업 효율과 코드 품질이 함께 올라간다는 것을 체감할 수 있었습니다.
AI를 더 잘 사용하는 개발자분들에 비해 부족할 수도 있으나 사용한다 라는 의미를 넘어 필요에 맞게 활용한다 로 말할 수 있게 되었다고 생각합니다. 이제는 누구나 다 사용하지만 각자에 맞게 활용하는 구조를 설계하는 것이 더욱 중요한 시대라고 생각합니다.
특히 AI Native 라고도 하는 만큼 앞으로 더 잘 활용 할 수 있는 방안을 꾸준히 학습하고 접목 시키면서 발전할 수 있는 개발자가 되어야 겠습니다.