duck blog | 기술 블로그

최근 여러 팀에서 AI 코딩 에이전트를 도입하면서 개발 생산성이 몰라보게 올라갔습니다. 코드를 짜는 속도 자체는 2배, 3배 빨라졌는데, 의외로 “팀 전체의 최종 딜리버리 속도는 생각보다 늘지 않았다”는 고민을 털어놓는 동료들이 많습니다.

왜 그럴까요? 코딩은 빨라졌지만, 협업과 온보딩 과정의 병목은 그대로 남아있기 때문입니다.

팀원마다 프로젝트의 비즈니스 도메인(예: 복잡한 인증/인가 흐름)에 대한 이해 깊이가 다르고, 커밋이나 PR을 올릴 때마다 지라(Jira) 티켓 매핑이나 사내 컨벤션을 맞추느라 매번 가이드를 찾아보고 질문하는 적응 시간이 여전히 필요합니다.

이 문제를 해결하기 위해, 저는 현재 팀들의 생산성을 높일 수 있도록 여러 레퍼런스(예: Ponytail 등)를 참고하며 **우리 상황에 맞는 프로젝트 특화 AI 플러그인(Plugin)**과 사내 GitHub Private 저장소를 활용한 마켓플레이스 배포 아키텍처를 설계하고 있습니다.

이미 완성된 완벽한 결과물이 아니라, 지금 치열하게 고민하고 구성해 나가는 이 설계 과정 자체를 기록으로 남기고 공유하고자 이번 글을 작성하게 되었습니다.

1. 보안과 공유를 한 번에: GitHub Private 마켓플레이스

에이전트가 지켜야 할 사내 인증 로직이나 깃 커밋 규칙을 퍼블릭 마켓플레이스에 올릴 수는 없습니다. 사내 보안(IP 유출 방지)을 지키면서도 팀원들에게 손쉽게 룰북을 전파하려면 GitHub Private Repository를 활용하는 것이 베스트 프랙티스입니다.

Claude Code나 Copilot CLI 같은 도구들은 자체적인 플러그인 설치 기능을 지원합니다. 사내 스킬셋을 패키징해서 Private 저장소에 올려두면, 팀원들은 터미널에서 다음 명령어 한 줄만 치면 됩니다.

# Claude Code 예시 (GitHub Private Repo 연동)
$ /plugin install https://github.com/my-company/agent-plugin-core

이 명령어 하나로 로컬 워크스페이스 내에 필요한 AI 룰북과 커스텀 명령어가 백그라운드에서 동기화되며, 이후 주기적으로 알아서 최신 버전으로 업데이트됩니다. 개발자들은 평소처럼 코딩만 해도 항상 팀의 최신 컨벤션과 아키텍처 가이드를 적용받게 됩니다.

2. 마켓플레이스, 플러그인, 스킬의 계층 구조 이해하기

AI 에이전트 자동화를 구축하려면 먼저 마켓플레이스 > 플러그인 > 스킬/훅/커맨드로 이어지는 개념적 계층 구조를 이해해야 합니다.

마켓플레이스 (Marketplace): 플러그인들이 모여 있는 중앙 저장소입니다.
- 개발자들에게 익숙한 git remote나 npm registry를 여러 개 추가해서 쓰는 것과 원리가 똑같습니다. Public 주소와 Private 주소를 에이전트에 각각 따로 등록(add)하여 병렬로 관리할 수 있습니다.
- Public 마켓플레이스: 에이전트 개발사나 커뮤니티가 제공하는 오픈소스 플러그인들이 모인 공식 저장소입니다.
- Private 마켓플레이스: 우리 팀의 사내 GitHub Private 저장소 주소를 직접 연동하여, 보안이 유지되는 우리만의 독자적인 저장소로 활용하는 공간입니다.
플러그인 (Plugin): 마켓플레이스에서 배포되는 단일 패키지 단위입니다. 흔히 생각하는 거창한 바이너리 프로그램이 아니라, 에이전트가 읽을 수 있는 텍스트 기반 설정 파일들의 모음(디렉토리)입니다.
구성 요소 (Skills, Hooks, Commands): 하나의 플러그인 안에는 실질적으로 다음 3가지 핵심 요소가 포함됩니다.
- Skills(지식): AI가 코드를 짤 때 참고해야 할 도메인 룰북(Markdown 파일).
- Hooks(자동화): 에이전트의 행동(예: 툴 사용 전/후)에 개입하는 쉘 스크립트.
- Commands(명령어): 사용자가 빠르게 호출할 수 있는 단축 명령어.

저희 팀의 Private 저장소(플러그인) 구조는 대략 이렇습니다:

my-company-agent-plugin/
├── plugin.json                 # 플러그인 메타데이터 (이름, 버전)
├── commands/
│   └── pr-gen.json             # "/pr" 단축 명령어 정의
├── hooks/
│   └── settings.json           # Claude Code 라이프사이클 훅 (실수 방지 등)
└── skills/
    ├── global/                 # ponytail, 공통 네이밍 규칙 등
    └── domain/                 # auth, design 등 도메인 스킬

이 저장소를 땡겨오면, 에이전트가 skills/ 디렉토리를 인덱싱하여 프로젝트 지식을 학습하고, hooks/를 읽어 특정 상황에서 자동 스크립트를 실행하며, commands/를 통해 개발자가 /pr 이라고만 쳐도 PR 초안을 뚝딱 만들어내게 됩니다.

3. 효율적인 스킬 계층(Hierarchy) 구조 설계

skills/ 폴더에 마구잡이로 마크다운 파일을 던져두면, AI가 질문을 받을 때마다 수십 개의 룰북을 전부 읽게 되어 컨텍스트 토큰 비용이 낭비되고 응답이 느려집니다. 그래서 위 트리 구조처럼 **글로벌(global)**과 도메인(domain) 영역으로 계층(Hierarchy)을 나누어야 합니다.

Global 스킬: 팀 공통 룰과 AI 습관 통제

어떤 도메인의 코드를 작성하든 무조건 지켜야 하는 팀 공통 규칙(예: 네이밍 컨벤션)은 global/ 영역에 넣습니다. 또한 이 영역에는 코드 스타일뿐만 아니라 **‘AI의 오버엔지니어링을 통제하는 규칙’**을 함께 넣으면 아주 효과적입니다. 예를 들어 “표준 라이브러리로 가능하면 외부 패키지를 추가하지 않는다”, “YAGNI(You Aren’t Gonna Need It) 원칙을 지킨다” 같은 룰을 글로벌 스킬로 깔아두면 AI가 쓸데없이 비대한 코드를 작성하는 것을 원천 차단할 수 있습니다.

Domain 스킬: 필요할 때만 꺼내 쓰는 지식

인증(Auth)이나 디자인(Design) 같은 비즈니스 도메인 규칙은 AI가 코드를 읽다가 관련 키워드(예: 로그인, 세션)를 마주칠 때만 domain/ 하위의 스킬을 인덱싱하도록 격리합니다. 토큰 소모를 최소화하면서도 핀포인트로 사내 스펙을 준수하게 됩니다.

4. 도메인 지식의 ‘스킬화’: 인증/인가 온보딩과 AI 검토

domain/auth/auth_architecture.md는 아주 훌륭한 예시입니다. 신규 입사자가 들어왔을 때, “우리 프로젝트 인증 처리는 어떻게 되어 있나요?”라는 질문을 자주 듣게 됩니다.

이 파일은 팀원들에게 훌륭한 온보딩 자료가 되고, AI 에이전트에게는 코드를 작성하거나 리팩토링할 때 반드시 지켜야 할 개발 명세서가 됩니다.

---
name: auth_domain_rule
description: 프로젝트 고유의 JWT 및 Session 기반 인증/인가 설계 규칙을 정의하고 코드를 검토합니다.
---

# 인증/인가 아키텍처 규칙

우리 프로젝트는 Next.js Middleware를 사용하여 1차 게이트웨이 보안을 처리하고, 내부 API 요청은 `lib/auth/session.ts`에 정의된 세션 객체를 참조합니다. 인라인으로 쿠키를 파싱해 직접 세션을 검증하는 코드는 금지합니다.

개발자가 “인증 처리가 필요한 API를 만들어줘”라고 요청하면, AI는 이 스킬을 꺼내 읽고 쿠키를 직접 파싱하는 실수를 저지르지 않습니다.

5. 실수를 원천 차단하는 방어막: 훅(Hooks)의 활용

아무리 좋은 룰북(스킬)을 만들어도 에이전트가 실수로 위험한 행동을 할 때가 있습니다. 이때 플러그인의 훅(Hooks) 기능이 방어막 역할을 합니다. 훅은 에이전트가 특정 도구를 사용하기 직전이나 직후에 우리가 만든 스크립트가 자동으로 개입하게 만드는 기능입니다.

위험한 터미널 명령어 차단: 예를 들어 에이전트가 실수로 운영 환경 변수 파일(.env)을 git에 올리려 하거나, git push --force 같은 위험한 쉘 명령어를 실행하려고 하면 어떻게 될까요?
사전 개입(Pre-Hook): 플러그인에 세팅해 둔 훅이 이를 감지하고, 에이전트가 명령어를 터미널에 입력하기 직전에 사내 보안 감지 스크립트를 먼저 실행시킵니다. 스크립트가 “이건 위험한 행동이다”라고 판단하면, 에이전트의 명령어 실행은 그 즉시 차단됩니다.

복잡한 설정 코드 없이도, 팀 플러그인 안에 이런 방어 훅만 잘 세팅해 배포해 두면 팀원 모두가 안심하고 AI에게 코딩을 맡길 수 있습니다.

6. 검증(Verify)과 배포 파이프라인

이러한 사내 플러그인이 팀에 안전하게 전파되는 라이프사이클은 다음과 같습니다.

검증(일부러 망가뜨리기): 규칙을 수정한 후, 고의로 인증 우회 코드나 나쁜 컨벤션의 코드를 작성해 보고 에이전트에게 리뷰를 시켜봅니다. 에이전트가 스킬을 근거로 에러를 지적하면 성공입니다.
PR 및 병합: 회고 때 발생한 트러블슈팅이나 정책 변경점을 SKILL.md로 정리하여 사내 플러그인 GitHub Repo에 PR을 올립니다.
자동 배포: 병합 시 팀원들의 로컬 환경에서는 다음날 업무 시작과 함께 최신 룰북과 훅이 백그라운드에서 동기화됩니다.

7. 마치며

AI 에이전트를 도입했을 때 생산성 상승을 체감하지 못하는 이유는, 코딩 자체의 속도보다 협업 중 발생하는 도메인 인수인계와 컨벤션 위반 검토 비용이 훨씬 크기 때문입니다.

우리 팀만의 Private 에이전트 플러그인 배포, 낭비를 막는 Ponytail과 계층적 스킬 구조, 그리고 치명적 에러를 차단하는 Hooks의 조합은 상상 이상의 시너지를 냅니다. 이제 에이전트를 팀의 복잡한 룰과 아키텍처를 완벽하게 숙지한 훌륭한 시니어 동료로 성장시켜 보세요.

Claude Code Hooks와 Custom Skills로 구축하는 AI 협업 자동화 가이드