배경

KOP 시스템은 project-web, project-api, project-cms, commerce-legacy — 4개 프로젝트가 REST와 GraphQL로 복잡하게 얽혀 있습니다. 뭔가 하나를 고치려면 4개 프로젝트를 직접 오가며 의존성을 파악해야 했고, 스키마 등록 같은 보일러플레이트도 매번 반복해야 했습니다. 크로스 프로젝트 변경에서 파일 하나를 놓치면 장애로 이어지는 구조였습니다.

project-api가 BFF(API 게이트웨이) 역할을 하면서, 도메인에 따라 커머스 레거시(REST)와 Hasura(GraphQL) 두 갈래로 나뉘는 구조입니다.

해결 방법

"뭘 고쳐야 하는지"만 말하면, 어디를 어떤 순서로 수정할지 알아서 판단하는 Claude Code 스킬을 만들었습니다.

도메인 키워드 기반 스마트 태스크 분석

태스크를 입력하면 키워드를 분석해 Hasura DB인지 커머스 REST인지 자동으로 판별합니다. Full Stack Legacy/Hasura, API+Web, API+CMS 등 7가지 패턴으로 분류해서 어떤 프로젝트를 건드려야 하는지 알려줍니다.

의존성을 고려한 자동 실행 라우팅

패턴에 맞춰 의존성이 깨지지 않는 순서로 코드를 수정합니다. 커머스 레거시든 Hasura든, 데이터 소스 → API → 프론트엔드 순서를 자동으로 지켜줍니다.

핵심 기능 1: OMC 기반 초고속 병렬 탐색

OMC(Orchestrated Multi-Codebase) Explore Agents로 4개 프로젝트의 관련 파일을 동시에 탐색합니다. 하나씩 순회하던 방식과는 비교할 수 없는 속도입니다.

핵심 기능 2: 철벽 방어 스키마 등록 체크리스트

새 GraphQL 스키마를 추가할 때 빠뜨리기 쉬운 등록 과정을 5단계 자동 검증으로 잡아냅니다.

핵심 기능 3: 자동화된 QA 시나리오와 추적 가이드

태스크 패턴과 수정 범위에 맞춰 QA 테스트 항목을 자동으로 만들고, 프로젝트 간 데이터 흐름 추적 가이드도 함께 제공합니다.

효과

지표	Before	After
영향 범위 파악	개발자가 직접 4개 프로젝트 탐색	자동 분석 및 병렬 탐색
수정 파일 누락	스키마 등록 등 간헐적 누락 발생	5단계 체크리스트 기반 자동 검증
프로젝트 간 의존성	수동으로 순서 판단 및 이동	패턴별 최적 실행 순서 자동 라우팅
타입 체크	각 디렉토리에서 수동 명령어 실행	변경된 프로젝트만 타겟팅 병렬 실행

눈여겨볼 점

• 멀티 프로젝트 환경에서 "어디를 고쳐야 하지?"가 가장 큰 시간 낭비입니다. 이 스킬은 7가지 패턴으로 태스크를 분류해 영향 범위를 자동으로 잡아주는데, 비슷한 구조의 프로젝트라면 패턴 정의 방식을 참고해볼 만합니다.
• OMC 병렬 탐색은 프로젝트 수가 늘어날수록 효과가 커집니다. 4개 프로젝트를 순서대로 뒤지는 것과 동시에 탐색하는 것의 차이는, 프로젝트가 많은 환경일수록 체감됩니다.
• GraphQL 스키마 등록 누락은 크로스 프로젝트에서 가장 흔한 실수입니다. 5단계 체크리스트로 자동 검증하는 방식은, 비슷한 보일러플레이트 누락 문제가 있는 팀이라면 바로 적용할 수 있습니다.