OMS에서 Claude AI를 활용하여 변화된 업무 방식

PM 1명 + 엔지니어 3명이 12개 MSA를 운영하던 OMS팀이 Claude AI에 팀 맥락을 이해시키는 AI Context를 설계해 16명 규모처럼 운영하게 된 사례다. 핵심은 도구를 쓰는 게 아니라 체계적 Context를 설계하는 것이다.

핵심 포인트

인간 4명 + TPM AI 1개 + MSA AI 11개 구조로, 역할별(PO/TPM/Backend/Frontend/Infra)로 컨텍스트 로딩 전략을 다르게 가져간다.
지식(ai-context/)과 행동(skills/)을 분리하고, Skills 자동 로딩 대신 CLAUDE.md 명시적 로딩을 택해 토큰 사용량을 예측 가능하게 했다.
API·Kafka 스펙을 자연어 대신 JSON DSL로 관리해 약 3배 토큰을 절감하고 전체 서비스 간 호출맵을 파악한다.
클린 아키텍처 + MSA가 AI Context에 가장 유리하며, UseCase 단위가 컨텍스트 노이즈를 줄여 약 10배 토큰 효율을 낸다.
검증 우선순위는 코드가 아니라 여러 MSA에 영향을 주는 TPM AI의 1차 설계다.

상세 정리

도입 전 문제: 여러 MSA 동시 개발로 영향도 파악이 곤란했고, 설계 단계에서 코드 레벨 정책이 누락됐으며, MSA 이해도 편차와 하루 7~8건 운영배포 요청서가 부담이었다.
폴더 구조: CLAUDE.md(인덱스) + .claude/ai-context(domain-overview·data-model·api-spec.json·kafka-spec.json·external-integration) + .claude/skills(develop·deploy).
명시적 로딩 이유: 토큰 사용량 예측 가능성·로딩 시점 투명성·역할별 필요한 문서만 선택 로드.
JSON DSL: 자연어 약 200토큰 vs JSON DSL 약 70토큰, api-spec.json은 제공 API + 외부 호출 API, kafka-spec.json은 발행 + 수신을 담아 MSA 간 연동 호출맵을 JSON만으로 파악한다.
학습 프롬프팅: 현행 분석→DSL 구조 제안→요구사항 추가→생성의 4단계로, 틀리면 더 꼼꼼히 분석하라는 힌트를 주고 맞으면 왜 추론 못했는지 되물어 ai-context를 스스로 갱신시킨다.
MCP 연동: Atlassian(Jira/Confluence로 요구사항 기반 하위티켓 자동 생성), Github(PR 리뷰·배포 태그), Datadog(배포 전후 영향도·실시간 Trace 자연어 조회).
아키텍처 난이도: 모놀리식+레이어드(어려움) < MSA+레이어드(중간) < 모놀리식+클린(쉬움) < MSA+클린(가장 쉬움).
클린 아키텍처 이점: 주문 취소를 레이어드 OrderService 500줄이 아니라 CancelOrderUseCase 50줄로 집중해 노이즈가 90%에서 0%로 준다.
1:1 매핑: domain-overview↔Domain/UseCase, data-model↔Entity, api-spec↔Adapter In, kafka-spec↔Adapter Out, external-integration↔API Client.
협업 변화: 코딩 시간이 줄고 분석·토론·리뷰 시간이 늘며, AI 코드를 신입 개발자 코드로 가정해 힌트 방식으로 리뷰하고, 요구사항 변경 시 처음부터 다시 설계가 몇 분 만에 가능해 기술부채를 제거한다.
그라운드 룰: AI 답변이 매끄러워 검증 없이 넘기면 존재하지 않는 메서드·deprecated 방식 제안 위험이 있어 신입 제안으로 가정해 검증한다.
성과·기준: 배포 요청 7~8건/일을 자동화하고 MSA 이해도 편차를 줄였으며(Claude Code v2.0.72·Opus 4.5 기준), 초기 AI Context 구축은 4~5번 재작업하는 반복 비용이 든다.