팀을 위한 클로드 코드 플러그인 개발

시작하며

이 글에서는 사내에서 클로드 코드 활용 사례 AX 발표부터, 단순 기능 개발을 넘어 서비스를 기획하고 소프트웨어의 가치에 집중하는 플러그인을 개발했던 경험을 공유합니다.

팀 전용 플러그인을 개발하게 된 계기는 우리 팀의 입맛에 맞는 업무용 스킬을 구성하여 새로 합류하는 팀원도 사용할 수 있는 워크플로우를 만들고 싶었습니다.

예상 독자는 팀 플러그인 개발에 관심이 있는 개발자 또는 개발 직군에서 AI 활용 사례가 궁금한 독자입니다.

바쁜 현대인들을 위한 요약

- 클로드 코드 플러그인을 개발 한 경험을 작성했고, 버저닝을 하면서 그 과정 속에서 어떤 작업들을 했는지 작성했어요.
- AI에 의존하게 됨에 따라 업무에 영향을 준다는 것을 언급했고, 플러그인을 개발한 후기와 장/단점을 작성했어요.

안드레 카파시가 언급한 소프트웨어 3.0

안드레 카파시가 설명하는 소프트웨어는 시대가 변할수록 코드 계층이 더욱 더 추상화 되고있다고 설명합니다. 초기에 룰 베이스 기반 코딩방식, 더 나아가 AI가 알고리즘으로 정답을 맞추는 방식 그리고 자연어가 코드가 되는 시대가 왔습니다.

코드 구현 단계에서 고민하던 과정을 추상화 하고, 제품의 기획 단계에서 자연어로 지시하는 방법으로 제품을 만드는 것이 안드레 카파시가 말 하는 소프트웨어 3.0 입니다.

자연어로 대화하며 제품을 만드는 과정이 점차 익숙해짐에 따라 더 이상 사고하지 않고 AI 가 만들어낸 산출물을 점점 신뢰하기 시작했습니다.

그렇게 제품의 안쪽 어디선가 잠재적 보안 문제들이 점차 드러나는 과정을 경험하게 되고, AI는 할루시네이션으로 곱게 포장한 근거 없는 답변을 저희에게 진실인 마냥 유혹하곤 했습니다.

클로드 코드 플러그인 경험

AI가 자유분방하게 활개치던 행동을 보고만 있을 수는 없었던 유능한 개발자들은 제약 사항을 만들기 시작했습니다. 그렇게 엔트로픽에서는 CLAUDE.md 파일을 작성하는 가이드를 제공하고, 점차 Best Practices 자료들이 나오기 시작했습니다.

이렇게 스킬, 커맨드와 같은 개념들이 등장하고, 점차 국내 테크 기업에서도 다양한 사례들을 발표하며 매일 지식이 쏟아져 나올 때 superpowers 라는 플러그인이 등장했고 점차 개발자들 사이에서 생산성을 높여준다는 소문을 접하며 새로운 시대를 직접 몸으로 느끼게 되었죠.

그 중 가장 매력적인 것은 AI 와 함께 일 하면서 무작정 코딩하지 않고 기획 단계부터 정확하게 설계하는 것을 선호했는데, 이 플러그인은 워크플로우를 대부분 따를 수 있도록 설계 되어있었고 굉장히 만족스러운 결과물이 나왔는데요.

이제부터 저희 팀이 갖고 있는 특성을 이해하고 기획 단계에서 오류를 줄이면서 복잡한 기능을 만드는 워크플로우를 만드는 것이 목표였죠.

팀 플러그인 개발

우리 팀만의 플러그인 만들기

감명 받았던 superpowers 플러그인을 그대로 클론하여, 팀의 개발 성격과 상황들을 하나씩 지침으로 설정하여 저희 팀의 입맛에 맞도록 수정하고, 테스트를 위해 어드민 페이지 개발 건을 클로드와 함께 작업하고 PR 까지 작성울 마무리 해봤어요.

동작하는 기능은 물론, 이 플러그인을 사용하면 기획 -> 구현 계획 -> 코드 구현 -> 검증 이라는 플로우를 강제하기 되는데요.

이로인해 기획 단계에서 모호했던 내용들이 명확하게 잡혀가는 것들을 경험하고, 제가 미처 생각하지 못 했던 부분을 정의하며 기능을 개발한 뒤 테스트 코드로 검증하는 과정이 물 흐르듯 진행 되었어요.

이렇게 재밌는 경험을 하고난 후 저는 출근하자마자 플러그인 공유 세션을 잡고, 팀에게 이 플러그인에 대해 설명하고 그 자리에서 사용하는 방법을 공유하는 시간을 가졌는데요.

그 때 사용했던 플러그인의 업무 흐름은 아래 내용과 같습니다.

플러그인 흐름

1. 기획

   이 단계에서는 작업 브랜치 티켓 번호를 입력하고, 분리된 세션에서 작업 연속성을 위해 로컬 디렉터리에 파일을 생성하여 기획 과정에서 모호했던 것을 구체화 하는 과정입니다.

2. 코드 분석

   기획의 의도를 더 구체적으로 파악하기 위해 레거시 코드가 갖고 있는 히스토리를 파악하여, 구체화된 기획 내용을 보정하거나 뒷받침 합니다.

3. 코드 작성 계획

   실제 코드를 작성하기 위한 계획을 수립하고, 기획 단계에서 생성 해두었던 작업 계획 파일에 기록합니다.

4. 서브 에이전트로 분리하여 코드 구현

   서브 에이전트를 호출하여 작업 계획 파일을 불러와 코드 구현에 집중합니다.

이 외에도 코드 리뷰, 디버깅 등 사용할 수 있는 여러가지 스킬들을 활용할 수 있습니다.

이후 저희는 플러그인을 팀 단위 지식을 축적할 수 있도록 개인 레포지토리에서 팀 레포지토리로 옮기고, 버전을 관리하며 사용하는 팀원들의 피드백을 하나씩 받고 개선하기로 하였습니다.

플러그인 v1.0.1

이처럼 플러그인을 통해 불편한 점이 나타나기 시작하였습니다. 그래서 저희 팀에서 실제 코드 리뷰 프로세스에서 사용중인 템플릿을 AI 가 참조하도록 변경하고 그 내용에는 대상 파일, 코드 라인, 리뷰 반영 레벨 등이 표시 되도록 변경 하였죠.

확실히 정형화된 템플릿이 존재하니 읽기 편하고, 리뷰 반영 레벨로 나뉘어서 기획에서 발견하지 못한 오류나 운영 코드에 반영하면 안되는 크리티컬한 이슈들만 필터링 하여 수정할 수 있도록 바뀌니 굉장히 편했습니다.

그리고, AI 코드 리뷰가 단순히 코드 구현 관점에서만 보는 것이 아니라 데이터베이스/아키텍트/성능/코드 품질 등을 고려하여 결과를 받을 수 있도록 커뮤니티에서 다른 사람들이 사용하는 피어리뷰에서 에이전트의 Teams 를 활용한 병렬로 진행하는 피어 리뷰와 리뷰 라운딩을 적용하게 됩니다.

Round 1: 독립 리뷰
├── Batch A: R1(Architecture), R2(Performance)   (Agent tool 병렬 2개)
├── Batch B: R3(Reliability), R4(Maintainability) (Agent tool 병렬 2개)
└── 각 리뷰어가 독립적으로 코드 분석 → 이슈 목록 반환

Round 2: 교차 검증
├── Batch A: R1, R2  (Round 1 전체 결과를 받아서 동의/반박)
├── Batch B: R3, R4
└── 합의 체크 → 모든 항목 합의되면 Round 3 스킵

Round 3: Lead 판정
└── Lead 1명 실행 → 분쟁 항목 최종 판정 + 리포트 작성

복잡성이 높은 서비스 코드를 작성을 끝내면 항상 병렬 리뷰를 통해서 제 코드를 1차적으로 검토하고, PR 을 통해 동료와 피어리뷰를 진행 했었는데요.

이 플러그인 버전을 만들 당시에는 굉장히 잘 사용했었고, 가장 만족스러웠던 스킬 중 하나였습니다.

다만, 이렇게 여러 라운드를 돌며 에이전트끼리 검증을 하게 되면 토큰을 많이 사용하고, 시간이 오래걸린다는 단점이 존재했기 때문에 매번 호출하지는 않았고 메인 서비스 코드에서 복잡한 요구사항을 AI 와 함께 코드를 작성하는 경우 병렬 리뷰를 통해 재검증 하고는 했습니다.

플러그인 v1.0.2

이 버전부터는 superpowers 가 제공하던 스킬을 참조하는 것이 일절 없도록 모두 팀 내 지식만을 이용하도록 변경 되었는데요. 이 때는 스킬을 사용하면서 가독성을 더 높이도록 작업을 많이 했었습니다.

4명의 리뷰어와 1명의 리더가 병렬 리뷰 3라운드를 거치고 난 후 결과를 나타낼 때 보고서 형식으로 나타낼 수 있도록 수정하였고, 현재 호출되는 스킬이 어떤 스킬인지 그리고 플러그인의 워크플로우에서 어떤 단계에 있는지 등을 답변을 시작할 때, 종료할 때 표현하도록 개선 했어요.

⏺ ═══ Mamedene Workflows: Stage 3/6 writing-plans ═══
  내용
  ═══ Mamedene Workflows ═════════════════════════════                                                                                                                                                                             
  [■■■□□□] Stage 3/6: writing-plans                                                                                                                                                                                               
  Skill: skills/writing-plans                                                                                                                                                                                                     
  Refs: skills/spring-api-rules/build.md                                                                                                                                                                                          
  Task: DRAFT-sync-billing | Complexity: LOW | Flags: —                                                                                                                                                                           
  ═════════════════════════════════════════════════════

플러그인 v1.0.3

이 당시 엔트로픽의 클로드 코드가 깃허브에 공개 되던 때입니다. 그리고, 얼마 되지 않아 skill-creator 를 공식 클로드 코드의 스킬로 제공하기 시작했죠. 이 때 부터는 만들고 싶은 스킬만 있다면 곧 바로 skill-creator 를 호출하여 바로 만들던 시기입니다.

팀의 개발 규칙을 전적으로 점검하고 개선하기 시작합니다.

기존에는 팀 미팅을 하면서 컨벤션을 키워드별로 조사하여 어떤 것들을 적용할지 검토하고 작성 했었는데 이 때 부터는 범용적인 사례와 팀의 사례를 결합하게 되었고 추가적으로 관련 예시들을 많이 넣어 AI가 이해하기 쉽게 작성을 했었어요.

개별 스킬의 호출이 끝나는 지점을 명확하게 만들고, 사용자가 우회 하려고 하거나 아직 진행되지 않은 사항들을 무시하고 진행하려고 할 때 강제로 원칙을 준수하게 만들거나 잘못된 선택을 했을 시 돌아오게 만드는 임계점들을 설정하게 됩니다.

이 구성은 모든 스킬에게 적용하여 스킬들을 호출할 때 굉장히 많은 제약을 넣게 되면서 광범위한 행위를 줄여 컨텍스트를 보호하고, 시간을 절약하도록 의도 하였죠.

그리고 현재

이 때는 하네스 엔지니어링이 떠오른 이후 입니다. 바이브 코딩 이라는 용어 이상으로 많이 들었던 기억이 있네요.

하네스 엔지니어링 관련 내용을 구글링하고, 유튜브 영상을 보고, PDF 를 보며 저만의 방법으로 익히고 괜찮았던 자료를 공유하며 저희 팀의 스킬에도 적용하게 됩니다.

스킬들이 서로를 호출하고, 컨텍스트를 공유하는 모든 과정에서 복잡도를 체크하여 병렬로 동작할 것인지 단일로 동작하여 의존성을 유지할 것인지 등 성능을 유지하며 속도 향상에 많은 작업을 쏟았습니다.

그리고, 자주 언급되었던 하네스 엔지니어링의 원칙들을 적용하고 각자 에이전트와 대화 하면서 규칙을 지키지 않을 때 마다 자신들의 로컬 디렉터리에 그 내용들을 기록하고 스킬을 호출할 때 참조 하도록 변경했죠.

에이전트가 갑자기 사과를 하고 답변이 느려지더니 나는 매일 야근을 하고 있었다

플러그인을 개발하고 난 후, 복잡한 기능을 개발 해야 하는 프로젝트에 투입 되었을 때 항상 선두에 나서서 플러그인과 함께 기능을 개발 했었습니다.

그러던 어느 날 유능하던 에이전트가 점차 죄송하단 말이 늘고, 답변이 느려지며 기획 단계에서 10분 이상 머무를 때도 있고 개발 단계에서 간단한 질문임에도 불구하고 2, 3분을 대기한 적도 있었어요.

그 때 클로드 코드가 멍청해졌다 라는 표현을 주변에서 굉장히 많이 했고, 저 또한 많이 했었는데 알고보니 클로드 코드 퀄리티 리포트 에서 성능이 저하 되었다는 것이 사실상 공개 되었죠.

그렇게 단순 작업에도 AI 의존성이 올라가다보니 간단한 구현에도 AI 가 답변해주길 기다리고, 검토 받기를 기다리다가 어느덧 시간은 항상 퇴근 시간이 지나있었습니다.

이 것은 AI 의존성 때문인지, 아니면 코드 품질을 조금 더 보장한 뒤 제 손을 떠나길 희망했는지 그 때의 감정은 도무지 모르겠습니다.

하지만, 요즘은 굉장히 빠릿빠릿하고 일을 잘 하는 친구로 다시 남게 되어서 다행이에요. 안 그래도 코덱스로 건너가서 두 개의 에이전트를 오케스트레이션 할까 했었는데 억누르게 되었어요.

이 때 배운점은 AI에 의존하게 되면 간단한 구현 내용에도 저는 스스로 사고하고 논리적인 코드를 작성하려 하지 않고, 이 조차도 AI에게 맡긴 뒤 다른 업무를 비동기 적으로 처리하고자 한다는 것인데요.

굉장히 큰 딜레마에 빠지기 쉽겠죠. 그 덕분에 AI가 제 역할을 못 하면 저 또한 업무에서 생산성이 떨어지고 초심으로 돌아가 구글링을 해야하니까요.

현재는 아직 오로지 한 회사의 AI 제품만 사용하지만, 향후에는 여러 회사의 AI 제품을 사용하며 업무의 특성 별 스페셜리스트한 것에 집중하도록 노력할 것 같아요.

요즘도 클로드 코드, 코덱스, 제미나이를 모두 다 사용하거나 일부만 사용하는 등 다양하게 사용하는 사례가 많으니 머지 않아 AI 를 사용하는 방식도 금방 변할 것 같네요.

플러그인을 만들고 난 후기

여기서 가장 재밌었던 것은 프로그래밍을 하는 방식이 한 단계 더 추상화 되었다는 것을 경험하며 그 역사의 한 장면 속에 제가 함께하고 있다는 것인데요. 그 시간동안 하루가 빠르게 발전하는 AI 소식을 접하려고 노력하면서 공부 했었던 기억이 있는데, 배움은 언제나 즐겁고 설레는 일 같아요.

마지막으로 플러그인의 장점으로는 스스로 놓칠법한 실수를 최대한 보정할 수 있고, 구현 과정에서의 자신감을 얻게 되었어요.

반대로 단점으로는 사고하는 과정이 많이 생략되고, 구현의 결과에 집중하게 되며 의존하게 되고 또 토큰 사용량과 에이전트의 상태에 따라 업무에 영향을 주었습니다.

마치며

타인이 만든 좋은 도구들을 우리는 항상 잘 사용 해왔지만 가끔은 다수의 선택을 따르며 우리가 겪고 있는 상황을 무시한 채 옳은 선택이라고 스스로 타협하는 경우가 많습니다.

현재 같이 나아가고 있는 팀에게 어울리는 제품을 만든다면 평지를 잘 달릴 수 있는 원형 바퀴가 아닌, 오르막과 산악지형 그리고 계단 같은 것들을 잘 오를 수 있는 새로운 형태의 바퀴를 발명할 수 있다는 것이 필요할 때가 있는 것 같습니다.

참고 자료

www.youtube.com

Andrej Karpathy: Software Is Changing (Again)

www.youtube.com

보리스 체르니의 클로드 코드 인사이트