두 플러그인을 하나로 — devex 사상의 실무 적용

TL;DR 개인 프로젝트용 devex와 사내 프로젝트용 workflow, 두 플러그인을 따로 관리하다가 한계에 부딪혔습니다. “왜 두 개인가?”라는 질문에서 출발하여, Philosophy→Strategy→Tactics 프레임워크로 통합 방향을 잡았습니다. Provider 추상화로 플랫폼 차이를 흡수했습니다. 결과적으로 이슈 생성부터 PR까지의 흐름을 플랫폼에 관계없이 하나의 도구로 관리하게 되었습니다.

1. 두 플러그인이 생긴 이유

이전 글에서 만든 devex는 GitHub 기반 개인 프로젝트에 맞춰져 있었습니다. 이슈 생성, 커밋, PR — 모두 GitHub API를 직접 호출하는 구조였습니다.

문제는 사내 프로젝트였습니다. 사내에서는 Dooray를 이슈 트래커로, GitHub Enterprise를 코드 저장소로 사용합니다. devex의 GitHub 이슈 스킬을 그대로 쓸 수 없었고, 결국 사내 전용 workflow 플러그인을 별도로 만들었습니다.

합리적인 선택이라고 생각했습니다. 두 플랫폼의 API가 다르고, 이슈 관리 방식도 다르다고 생각했기 때문입니다.

2. 이중 관리의 고통

시간이 지나면서 문제가 드러났습니다.

문제	구체적 상황
로직 중복	커밋 메시지 규칙, PR 생성 절차가 양쪽에 거의 동일하게 존재
동기화 비용	한쪽에 개선하면 다른 쪽도 수정해야 하는데, 잊기 쉬움
컨텍스트 낭비	Claude가 두 플러그인을 모두 로드하면서 컨텍스트 소모
용어 불일치	devex는 “이슈 사이클”, workflow는 “이슈 플로우” — 같은 개념, 다른 이름

“두 플러그인을 관리하는 비용이 두 플러그인의 가치를 넘어서고 있다”는 판단이 들었습니다.

3. 사상으로 방향을 잡다

이전 글에서 정리한 Philosophy→Strategy→Tactics 프레임워크(도구 설계 시 ‘왜→방향→구현’ 순서로 결정하는 사고 틀)를 이 문제에 적용했습니다.

Philosophy (왜 이렇게 하는가)

“개발 경험 도구는 플랫폼이 아니라 개발자의 워크플로우에 집중해야 합니다.”

devex의 핵심 가치는 “이슈에서 PR까지의 흐름을 자동화하는 것”이지, “GitHub API를 호출하는 것”이 아닙니다. 플랫폼은 수단이고, 워크플로우가 본질입니다.

Strategy (어떤 방향으로 갈 것인가)

“플랫폼 차이를 추상화하여 하나의 도구로 통합합니다.”

두 플러그인을 유지하는 대신, devex 하나에 플랫폼 어댑터를 두는 구조로 전환합니다.

Tactics (구체적으로 어떻게 구현하는가)

“Provider 패턴으로 플랫폼별 동작을 분리합니다.”

4. Provider 추상화 — 전략의 구현

Provider는 플랫폼별 이슈 동작을 정의하는 마크다운 파일입니다.

devex/
├── providers/
│   ├── PROVIDER.md          # 템플릿
│   └── github.md            # GitHub 기본 내장
└── ~/.claude/devex/
    └── providers/
        └── internal.md      # 사내 provider (로컬 전용)

핵심 설계 결정은 사내 provider를 배포 범위에 포함하지 않는 것이라고 판단했습니다. 사내 API 엔드포인트와 인증 정보는 로컬에만 존재해야 합니다. devex는 GitHub provider를 기본 내장합니다. 사내 provider는 각 개발자가 로컬에 설정합니다.

SessionStart 훅에서 git remote의 host를 감지하여 적합한 provider를 자동으로 선택합니다. 개발자가 프로젝트를 열면 GitHub인지 사내인지 자동으로 판단됩니다.

여기서 한 걸음 더 나아간 것이 있습니다. 같은 SessionStart 훅이 스킬 트리거 매핑도 세션에 주입합니다. 프로젝트에 어떤 설정 파일이 있든 없든, “이슈 완료”라는 자연어가 올바른 워크플로우로 연결됩니다. 디스크에 아무것도 쓰지 않고, 프로젝트 파일을 건드리지 않습니다. 빈 디렉토리에서도 동작합니다.

5. 통합 과정에서 내린 결정들

Provider 추상화 외에도 여러 설계 결정이 필요했습니다.

용어 통일: 이슈 사이클 → 이슈 플로우

“사이클”은 반복을 암시하지만, 실제 이슈는 생성→시작→완료의 단방향 흐름입니다. “플로우”가 더 정확한 표현이라고 판단했습니다. 스킬명도 /cycle → /flow, /github-issue → /issue로 변경했습니다.

implement 스킬 제거

devex v1.0의 /implement는 범용 코드 생성 스킬이었습니다. 그런데 실무에서는 프로젝트마다 아키텍처가 다르고, 코드 생성 규칙도 다릅니다. 사내 프로젝트는 헥사고날 아키텍처를 따르고, 개인 프로젝트는 그렇지 않습니다.

범용 implement를 유지하는 대신, 프로젝트별 구현 스킬(.claude/skills/implement/)로 분리했습니다. devex는 워크플로우에 집중하고, 구현은 프로젝트가 정의합니다. Philosophy에 부합하는 결정이라고 생각했습니다.

이슈 생애주기 확장: create/start/complete

기존에는 이슈 생성(/github-issue)만 지원했습니다. 통합하면서 이슈의 전체 생애주기를 /issue 서브커맨드로 관리할 수 있게 확장했습니다. 코드 없는 이슈(조사, 문서 작업)도 지원하여 브랜치 생성을 선택 사항으로 만들었습니다.

6. 만들고, 좁히고, 통합하다

도구의 진화는 세 단계를 거쳤습니다.

처음에는 일단 만들었습니다. GitHub 전용 이슈 사이클 5종. 완벽한 추상화보다 동작하는 도구가 먼저였습니다. 실제로 쓰기 시작하니 어디가 부족한지 보였습니다.

다음으로 범위를 좁혔습니다. 핵심이 아닌 기능을 과감히 제거하고, 도구가 책임져야 할 영역을 확정했습니다. 이슈에서 PR까지의 흐름만 남기고 나머지는 프로젝트에 위임했습니다.

마지막으로 사상으로 통합했습니다. “왜”를 먼저 정하니 “어떻게”는 따라왔습니다. Provider 추상화라는 기술적 선택은 “워크플로우가 본질”이라는 판단에서 나온 것입니다.

그 이후에도 자동화, 캐시 정리, 스킬 주입 등 운영 편의 개선이 이어졌습니다. 도구는 한 번 만들고 끝이 아니라, 사용하면서 계속 다듬어야 합니다. 그리고 다듬을 때마다 “이 도구가 정말 설정 없이 동작하는가”를 기준으로 점검합니다.

7. 돌아보며

두 플러그인을 하나로 합치는 작업은 단순한 리팩토링이 아니었습니다. “이 도구의 본질이 무엇인가”를 다시 묻는 과정이었습니다.

앞선 글에서 “사람은 프로세스를 짜야 한다”고 했고, “사상이 설계를 만든다”고 했습니다. 이 글은 그 사상을 실제 도구 설계에 적용한 기록입니다.

Provider 추상화라는 기술적 선택의 뒤에는 “워크플로우가 본질이다”라는 판단이 있었습니다. 그 판단이 없었다면 두 플러그인을 계속 따로 관리하거나, 단순히 코드를 합치는 데 그쳤을 것입니다.

AI 도구를 만들고 운영하면서 느끼는 것은, 도구의 품질이 결국 만드는 사람의 판단력에 비례한다는 점입니다. AI가 코드를 짜주는 시대에 개발자에게 남는 것은 “왜 이렇게 만들어야 하는가”에 답하는 능력입니다.

그리고 하나 더 — 도구가 진짜 완성되려면, 프로젝트 파일을 건드리지 않고 어떤 디렉토리에서든 자연어만으로 동작해야 합니다. 설정 파일을 요구하는 순간 그것은 도구가 아니라 의존성입니다.

이 글은 Claude와 함께 작업했습니다.