![\"개발](\"https://tech.umosone.ai/assets/images/compound-triage-hero-v3-2dd7fd48bbe6fcdde9c355f3df15a531.png\")
AI와 함께 개발하며 발견한 시행착오는 대화가 끝나면 사라지기 쉽습니다. WMS 개발팀은 이를 후보로 모으고 사람이 검토해 다음 작업에서 다시 쓰는 규칙으로 남기고 있습니다. 공용 Drawer에서 발견한 문제 하나가 실제 팀 규칙으로 이어진 과정도 함께 소개합니다.
\n
안녕하세요, UMOSONE WMS(Warehouse Management System) 개발팀의 Front Engineer 최영호입니다. 저희 FE팀은 WMS Frontend를 개발하면서 AI 에이전트와 함께 겪은 시행착오를 다음 작업에서도 꺼내 쓸 방법을 고민해왔습니다. 이번 글에서는 그 고민 끝에 도입해 운영하고 있는 컴파운드 트리아지를 소개하려고 합니다. 먼저 저희 팀이 만드는 제품과 이런 과정이 필요했던 배경부터 짧게 이야기해보겠습니다.
\nCapora WMS는 입고, 재고, 피킹, 검수, 출고까지 물류센터에서 일어나는 작업을 관리하는 시스템입니다. 여러 화주와 센터의 재고 흐름을 실시간으로 확인하고 운영자와 현장 작업자가 각 단계의 업무를 이어가도록 돕습니다.
\nWMS에는 서로 닮은 화면과 작업 흐름이 많습니다. 한 기능에서 발견한 문제나 구현 규칙이 다른 기능에서도 반복되곤 합니다. 이런 경험을 한 번의 작업에만 남기지 않고 팀의 자산으로 쌓을 방법을 고민하게 된 배경도 여기에 있습니다.
\n입고부터 출고까지 이어지는 과정에서는 상태 처리, 조회 조건, 공용 컴포넌트 사용법 같은 규칙이 여러 화면에서 반복됩니다.
\nAI 에이전트와 개발하다 보면 대화 안에 여러 경험이 쌓입니다. 어떤 API부터 확인했는지, 처음 고른 구현을 왜 버렸는지, 실제 문제를 잡아낸 테스트는 무엇이었는지 같은 기록입니다.
\n문제는 작업이 끝난 뒤입니다. 새 대화를 열면 이 맥락도 사라집니다. 다음 에이전트는 같은 코드를 다시 살피고 때로는 앞서 겪은 실수를 되풀이합니다. 기능은 완성됐지만 팀의 개발 방식에는 별다른 변화가 남지 않습니다.
\n저희는 이 경험을 다음 작업에서도 꺼내 쓰고 싶었습니다. 그래서 재사용할 만한 교훈을 후보로 모으고 사람이 검토해 팀 규칙으로 남기는 과정을 만들었습니다. 이 과정을 컴파운드 트리아지(Compound Triage)라고 부릅니다.
\n이름은 낯설어도 원리는 간단합니다. AI가 찾은 교훈을 바로 규칙으로 삼지 않고 다른 작업에서도 필요한지 사람이 다시 판단합니다.
\n자동화는 후보를 모으는 일을 돕지만 어떤 후보를 팀 규칙으로 채택할지는 사람이 결정합니다.
\n이 문제를 고민하던 중 Every의 Compound Engineering을 읽었습니다. 이 글에서 말하는 ‘compound’는 작업 하나가 다음 작업을 더 쉽게 만드는 방향으로 경험을 쌓는다는 뜻입니다. 기능만 완성하고 끝내는 대신, 그 과정에서 발견한 패턴과 도구, 문서를 함께 개선하면 시간이 지날수록 개발 환경도 나아진다는 생각입니다.
\n처음에는 작업이 끝날 때마다 배운 점을 문서에 추가하면 되겠다고 생각했습니다. 그런데 곧 문제가 드러났습니다. 한 번 효과가 있었던 방법이 다른 작업에도 통한다는 보장은 없습니다. 특정 버그에서만 필요한 우회 방법일 수도 있고 이미 문서에 있는 규칙을 AI가 다시 발견했을 수도 있습니다. AI가 그럴듯하게 정리했다는 이유만으로 팀 규칙이 되면 문서는 서로 충돌하는 지침으로 금방 뒤엉킵니다.
\n그래서 저희는 ‘배운 점을 모으는 일’과 ‘팀 규칙으로 채택하는 일’을 나눴습니다.
\n이 과정은 에이전트의 Stop hook에서 시작합니다. Stop hook은 에이전트가 작업을 마칠 때 자동으로 실행되는 후처리입니다. WMS Frontend에서는 이 훅이 compound-capture-stop 스킬을 호출합니다.
compound-capture-stop은 이번 작업에서 얻은 경험이 프로젝트 문서의 규칙으로 남길 만큼 재사용 가능한지 따져봅니다. 다른 작업에서도 반복될 근거가 있는지, 어느 문서의 어느 위치에 반영할지, 어디까지 적용하고 어디에는 적용하지 않을지 확인합니다. 이 질문에 구체적으로 답할 수 없다면 티켓을 만들지 않습니다.
기준을 통과해도 문서를 바로 고치지는 않습니다. 사람이 검토할 후보 카드를 먼저 만듭니다. 내부에서는 이를 Raw Ticket이라고 부릅니다. 작업이 끝날 때마다 반드시 생기는 것은 아닙니다. 남길 만한 교훈이 없다면 0건으로 끝납니다.
\n실제로 공용 Drawer를 고치던 작업에서 이 과정이 어떻게 시작됐는지 살펴보겠습니다. Drawer는 현재 목록을 그대로 둔 채 그 위에 상세 정보를 펼치는 UI입니다. 제품 목록에서 제품 링크를 누르면 상세 Drawer가 열립니다. 필요한 내용을 확인하고 닫으면 다시 원래 목록으로 돌아갑니다.
\n당시 공용 Drawer를 닫는 로직을 고치면서 ProductDetail이 열릴 수 있는 overlayId를 하나의 목록에 모아 관리하는 방식을 먼저 택했습니다.
export const PRODUCT_DETAIL_OVERLAY_IDS = [
PRODUCT_DETAIL_OVERLAY_ID,
PRODUCT_DETAIL_OVERLAY_ID_WITH_CURSOR,
SAFETY_STOCK_PRODUCT_DETAIL_OVERLAY_ID,
] as const;
목록에 모든 ID가 들어 있다면 문제없이 동작합니다. 문제는 그 ‘모든 ID’를 사람이 빠짐없이 찾아야 한다는 데 있었습니다. 첫 조사에서는 openBottomDrawer 호출부를 검색해 제품 상세 Drawer가 두 ID로 열린다고 판단했습니다. 하지만 안전 재고 화면은 openBottomDrawer를 직접 호출하지 않았습니다. DeepLinkDrawerConfig.renderDetail에서 같은 ProductDetail을 렌더링하면서 자체 overlayId를 사용하고 있었습니다.
export const SAFETY_STOCK_PRODUCT_DRAWER_CONFIG = {
overlayId: SAFETY_STOCK_PRODUCT_DETAIL_OVERLAY_ID,
renderDetail: () => <ProductDetail />,
};
이 경로를 놓친 채 변경을 마쳤다면 제품 관리 화면에서는 Drawer가 정상적으로 닫히지만, 안전 재고 화면에서 연 Drawer만 닫히지 않는 문제가 생길 수 있었습니다. 공용 컴포넌트를 여러 화면에서 재사용할수록 중앙 목록을 사람이 관리하는 방식은 누락에 취약했습니다.
\n저희는 목록을 더 꼼꼼하게 관리하는 대신, ID를 관리할 책임을 Drawer를 사용하는 화면으로 옮겼습니다. 공용 Drawer가 자신을 사용하는 모든 화면의 ID를 기억하지 않고, Drawer를 여는 화면이 실제로 사용한 ID를 필수 prop으로 넘기도록 바꿨습니다.
\n- const handleCloseDrawer = useCloseDetailDrawer({
- overlayIds: PRODUCT_DETAIL_OVERLAY_IDS,
- searchKey: 'selectedProductId',
- });
+ type ProductDetailProps = {
+ overlayId: string;
+ };
+ const handleCloseDrawer = useCloseDetailDrawer({
+ overlayId,
+ searchKey: 'selectedProductId',
+ });
overlayId가 필수 prop이 되자 빠진 사용처는 컴파일 오류로 드러났습니다. 당시 TypeScript가 찾아낸 렌더링 위치는 ProductDetail 14곳과 ShipmentDetail 7곳, 모두 21곳이었습니다. 사람이 검색어를 잘 고르기를 기대하는 대신 컴파일러가 누락된 곳을 알려주는 계약으로 바뀐 셈입니다.
코드는 이 작업 안에서 이미 고쳤습니다. 하지만 다음 작업의 에이전트는 왜 중앙 목록을 없앴는지 알지 못합니다. 맥락을 모르면 다시 목록을 만들거나, 비슷한 Drawer를 고치면서 openBottomDrawer 호출부만 확인할 수도 있습니다. 저희가 후보로 남기고 싶었던 것은 코드 한 줄이 아니라 그 선택에 이른 판단 기준이었습니다.
작업이 끝난 뒤 Stop hook은 이 사건에서 서로 다른 두 가지 교훈을 찾았고, 각각 Raw Ticket으로 남겼습니다. 첫 번째 티켓에는 공용 Drawer의 ID 계약을 바꿀 때 호출 함수만 검색하지 말고 전체 렌더링 경로를 확인해야 한다는 내용을 담았습니다.
\nsummary: >
공유 상세 Drawer의 overlay ID 계약을 변경할 때는
openBottomDrawer 호출처 검색만으로는 불충분하다.
documentationTargetProposal: docs/llm/url-filter-sync-patterns.md
reuseEvidence: >
safety-stock의 ProductDetail 마운트 경로를 놓쳐
해당 화면의 Drawer가 닫히지 않을 뻔했다.
boundary: >
단일 도메인 Drawer나 내부 UI 변경에는
앱 전체 감사를 요구하지 않는다.
두 번째 티켓에는 더 근본적인 구조 개선을 담았습니다. 교차 도메인에서 재사용하는 Drawer는 ID 목록을 내부에 열거하지 않고, 마운트하는 화면이 필수 prop으로 ID를 주입한다는 내용입니다.
\nsummary: >
교차 도메인에서 재사용되는 상세 Drawer는 overlay ID 목록을
내부에 열거하지 않고, 마운트하는 쪽이 필수 prop으로 주입한다.
reuseEvidence: >
필수 prop을 추가하자 TypeScript가 ProductDetail 14곳과
ShipmentDetail 7곳의 렌더링 위치를 찾아냈다.
boundary: >
단일 ID로만 열리는 기존 Drawer를 한꺼번에 전환하라는 규칙은 아니다.
Raw Ticket에는 “필수 prop으로 바꾸자”는 결론만 적지 않습니다. 어떤 경로를 놓쳤는지, 같은 문제가 왜 다시 생길 수 있는지, 규칙을 어디에 남길지, 어디까지 적용할지를 함께 기록합니다. 이렇게 적어두면 원래 대화를 읽지 않은 사람도 후보가 나온 이유와 적용 범위를 확인할 수 있습니다. 반대로 반복 근거나 적용 범위를 설명하기 어렵다면 아직 팀 규칙으로 다룰 후보가 아니라고 봅니다.
\n후보는 어디까지나 검토 요청입니다. AI가 남겼다는 이유만으로 맞는 규칙이라고 가정하지 않습니다.
\n후보가 모이면 개발자가 트리아지 화면을 엽니다. 여기서 트리아지는 후보를 하나씩 살펴보고 다음에 어떻게 처리할지 정하는 일을 뜻합니다. 검토자는 원래 작업의 근거, 기존 문서, 적용 범위를 확인한 뒤 세 가지 중 하나를 고릅니다.
\n저희는 이 전체 흐름을 compound-triage라는 상위 스킬로 실행합니다. 하나의 스킬이 모든 일을 한꺼번에 처리하는 대신, 책임이 다른 세 단계를 정해진 순서로 연결합니다.
compound-triage는 앞 단계의 결과를 확인한 뒤 다음 하위 스킬을 호출합니다. 사람의 결정 데이터가 없으면 적용 단계로 넘어가지 않고 승격된 그룹만 문서 변경 계획이 됩니다. 이미지를 누르면 크게 열립니다.
![\"compound-triage가](\"https://tech.umosone.ai/assets/files/compound-triage-skill-flow-08b4d6d9b4af0f7949390769ac5dc7c5.svg\")
compound-triage-session은 Raw Ticket을 읽어 비슷한 내용끼리 묶고 사람이 검토할 HTML 화면을 만듭니다. 검토가 끝나면 승격·보류·폐기·미검토 결과가 담긴 결정 데이터를 내보냅니다. 이 단계에서는 아직 파일을 옮기지 않습니다.compound-triage-apply는 사람이 제출한 결정 데이터가 있을 때만 실행됩니다. 검토한 티켓을 각 상태의 폴더로 옮기고 기록을 갱신하며 미검토 티켓은 다음 검토를 위해 Raw 상태로 남깁니다.compound-promote-plan은 승격된 티켓을 주제별로 묶어 문서 변경 계획을 만듭니다. 어느 문서의 어떤 부분을 바꿀지, 규칙의 적용 범위를 어디까지로 제한할지, 변경 후 무엇을 확인할지를 계획에 담습니다.아래 화면은 실제 compound-triage-session의 HTML 템플릿에 설명용 가짜 티켓을 넣어 재현한 것입니다. 검토자는 티켓이 나온 배경과 그대로 뒀을 때의 문제, 제안하는 규칙, 기존 문서와 반영 후 문장의 차이를 한 카드에서 확인합니다.
![\"가짜](\"https://tech.umosone.ai/assets/files/triage-ui-demo-a07b3f4d8fb3bf96aa1e786382d082fc.jpg\")
실제 트리아지 UI를 브라우저에서 렌더링해 캡처했습니다. 화면에 표시된 티켓과 경로는 모두 설명을 위해 만든 가짜 데이터이며 이미지를 누르면 크게 열립니다.
\n공용 Drawer의 두 티켓은 같은 사건에서 나온 진단과 처방으로 묶였습니다. 하나는 놓친 경로를 찾는 방법이었고, 다른 하나는 중앙 목록을 없애 누락을 컴파일 오류로 바꾸는 방법이었습니다. 사람은 둘을 함께 읽고 같은 주제로 승격했습니다. compound-triage-apply가 결정을 반영한 뒤 두 티켓에는 같은 그룹과 Plan 경로가 기록됐습니다.
decision: promoted
groupId: compound-triage-20260728-140841-drawer-overlay-id-contract-23
documentationTarget: docs/llm/url-filter-sync-patterns.md
planStatus: generated
relatedPlanPath: >
docs/superpowers/plans/
2026-07-28-update-shared-drawer-overlay-id-audit-and-ioc-contract.md
자동화가 사람의 판단을 앞질러가지 않도록 단계를 나눴습니다. 검토 화면에서 결정 데이터가 제출되지 않으면 티켓을 옮길 수 없고 승격된 후보도 곧바로 문서가 되는 것이 아니라 먼저 변경 계획을 거칩니다.
\n이 구분은 실제 운영 중 겪은 문제에서 나왔습니다. 한 차례 부분 검토에서는 후보 63개 중 30개만 확인하고 세션을 마쳤는데, 초기 화면은 아직 보지 못한 33개까지 모두 보류로 저장했습니다. 하지만 보류는 “검토해보니 아직 근거가 부족하다”는 사람의 판단입니다. 아직 읽지도 않은 후보와는 의미가 다릅니다.
\n보류는 사람이 내린 결정이고 미검토는 아직 결정하지 않았다는 상태입니다.
\n지금은 검토하지 않은 항목을 미검토(Unreviewed) 상태로 따로 남깁니다. 미검토 후보는 원래 위치에서 다음 트리아지를 기다리고 사람이 실제로 결정한 후보만 승격·보류·폐기 상태로 이동합니다. 작은 상태 하나를 추가한 변화지만 자동화가 사람의 판단을 대신 기록하지 못하게 만드는 데 필요했습니다.
\n트리아지 결과는 대화 속 동의가 아니라 별도의 결정 데이터로 제출합니다. “좋아 보입니다”라는 AI의 추천과 “팀 규칙으로 채택하겠습니다”라는 사람의 결정을 시스템에서도 구분하려고 만든 장치입니다.
\n그렇다면 채택한 규칙은 어디에 남고 다음 에이전트는 어떻게 사용하는 걸까요?
\nWMS Frontend 저장소에는 구조, 구현 패턴, 코딩 규칙, 테스트 방법을 설명하는 문서들이 있습니다. 에이전트는 작업을 시작할 때 먼저 진입 문서를 읽고 현재 작업에 필요한 문서를 찾아가도록 안내받습니다. API를 연동할 때는 API 패턴을, 테스트를 작성할 때는 테스트 규칙을 확인하는 식입니다.
\n새로운 세션은 이전 대화를 기억하지 못해도 저장소의 문서는 다시 읽을 수 있습니다. 저희가 문서를 에이전트와 사람이 함께 사용하는 팀의 장기 기억으로 보는 이유입니다.
\n현재 컴파운드 트리아지에서 승격된 후보는 비슷한 주제끼리 묶이고 하나의 문서 변경 Plan으로 이어집니다. 어떤 문서의 어느 부분을 바꿀지, 사례 하나를 너무 넓은 규칙으로 일반화하지는 않았는지, 변경 후 무엇을 확인할지를 Plan에 적습니다.
\n공용 Drawer 사례에서는 두 티켓을 ‘같은 사건의 진단과 처방’으로 정리했습니다. 필수 prop 주입을 우선 규칙으로 두고, 아직 이 구조를 적용하지 않은 기존 Drawer에만 전체 렌더링 경로 감사를 요구하도록 관계를 정했습니다.
\n## Goal
공유 상세 Drawer의 overlay ID 계약을 하나의 절로 추가한다.
## Scope
- 교차 도메인에서 재사용하는 Drawer는 overlayId를 필수 prop으로 받는다.
- 기존 열거 방식을 고칠 때는 renderDetail과 타 도메인 렌더링까지 감사한다.
- 단일 도메인 Drawer와 내부 UI 변경에는 이 절차를 강제하지 않는다.
## Success Criteria
한 절만 읽어도 IoC 우선 계약과 기존 Drawer 감사 절차의 관계를 알 수 있다.
Plan을 검토한 뒤 docs/llm/url-filter-sync-patterns.md에 Shared Drawer Overlay ID Contract 절을 추가했습니다. 실제 문서에는 규칙과 적용 범위가 다음과 같이 함께 들어갔습니다.
+ 교차 도메인에서 재사용되는 상세 Drawer는 자신이 열릴 수 있는
+ overlay ID 목록을 내부에 열거하지 않는다.
+ 마운트하는 쪽이 overlayId를 필수 prop으로 전달한다.
+ 아직 열거 방식을 쓰는 기존 Drawer를 고칠 때는
+ openBottomDrawer 호출부만 보지 않는다.
+ 컴포넌트 import, DeepLinkDrawerConfig.renderDetail,
+ 다른 도메인 훅의 인라인 렌더링까지 확인한다.
+ 단일 도메인 Drawer, 내부 UI 변경, ID 기반 닫기 계약이 없는
+ Dialog와 Toast는 이 규칙의 적용 대상이 아니다.
다음 에이전트가 공용 Drawer를 새 화면에서 사용하거나 기존 닫기 계약을 손대면, 중앙 ID 목록을 만들면 안 되는 이유와 기존 구조에서 더 확인해야 할 경로를 문서에서 찾을 수 있습니다. 한 작업에서 내린 판단이 다음 작업의 출발점으로 남았습니다.
\n여기서 순서를 구분할 필요가 있습니다. overlayId를 필수 prop으로 바꾼 코드 수정은 트리아지 전에 끝났습니다. 컴파운드 트리아지가 해결 코드를 만들어낸 것은 아닙니다. 작업 중 검증한 해결책과 그 판단 기준을 다음 작업에서도 재사용할 수 있도록 보존한 것입니다.
컴파운드 트리아지가 문서까지 자동으로 고치는 것도 아닙니다. 후보를 수집하고 사람이 분류하고 승격된 후보의 문서 변경 Plan을 만드는 데까지를 담당합니다. 실제 문서 변경과 검증은 별도의 작업으로 남겨두었습니다.
\n문서에 규칙을 남겼다고 해서 모든 문제가 해결되지는 않았습니다. 에이전트가 관련 문장을 놓칠 수도 있고 읽었지만 현재 코드에 어떻게 적용해야 하는지 다르게 해석할 수도 있습니다.
\n공용 Drawer 사례에서는 overlayId 필수 prop이 기계적인 안전장치가 됐습니다. 규칙이 필요한 이유와 적용 범위는 문서가 설명하고, 빠진 prop은 TypeScript가 코드 작성 단계에서 찾습니다. 문서와 타입이 서로 다른 일을 맡습니다.
WMS Frontend에는 이미 이런 실수를 줄이기 위한 프로젝트 전용 lint 규칙도 있습니다. 현재는 Biome의 GritQL 플러그인으로 다음과 같은 패턴을 검사합니다.
\nrenderHook 안에서 렌더링할 때마다 새로운 객체나 배열을 만드는 테스트 코드코드를 작성한 뒤 lint를 실행하면 에이전트가 문서를 기억하고 있는지와 관계없이 위반을 찾습니다. 이 자동 검증 체계는 이미 사용하고 있지만 지금까지 컴파운드 트리아지에서 승격된 후보는 모두 문서 변경 Plan으로만 변환했습니다. 기존 lint 규칙이 컴파운드 트리아지를 통해 만들어졌다는 뜻은 아닙니다.
\n다음 단계에서는 이 두 흐름을 연결해보려고 합니다. 승격된 교훈은 지금처럼 문서에 배경과 적용 범위, 예외를 남깁니다. 그중 코드만 보고도 위반 여부를 명확히 판정할 수 있는 부분은 타입이나 lint, 테스트, 정적 검사로도 구현합니다.
\n모든 규칙의 맥락은 문서에 남기고 기계가 판단할 수 있는 위반만 타입·lint·테스트·정적 검사로 한 번 더 확인합니다.
\n모든 규칙을 자동 검증으로 만들 수는 없습니다. “공용 Drawer의 전체 렌더링 경로를 확인한다”는 절차는 코드 한 조각만 보고 지켰는지 판단하기 어렵습니다. 이런 내용은 문서와 작업 절차로 전달하는 편이 낫습니다. 반면 필수 overlayId prop처럼 코드 구조로 표현할 수 있는 규칙은 TypeScript가 바로 확인합니다.
문서에는 규칙이 필요한 이유와 적용 범위를 남기고 기계가 판정할 수 있는 위반은 자동 검증에서 한 번 더 잡는 방식입니다. 문서를 자동 검증으로 대체하는 것이 아니라, 문서만으로 놓치는 부분에 안전장치를 하나 더 두려는 것입니다.
\n컴파운드 트리아지는 지금도 FE팀에서 운영하며 여러 부분을 고치고 있습니다. 가장 먼저 체감한 문제는 티켓의 양이었습니다. Stop hook의 캡처 기준을 느슨하게 두면 작은 관찰까지 티켓이 되어 쌓입니다. 그러면 한 번의 트리아지에서 모두 검토하지 못하고 다음 회차로 미뤄지는 티켓도 빠르게 늘어납니다. 많이 모으는 것보다 다시 쓸 가치가 있는 경험만 남도록 캡처 기준을 정제하는 일이 중요합니다.
\n앞으로 FE팀의 인원이 늘어나면 티켓 수도 함께 늘어날 가능성이 큽니다. 지금의 운영 방식이 늘어난 티켓을 감당할 수 있을지는 아직 알 수 없습니다. 중요한 후보를 놓치지 않으면서도 트리아지가 밀리지 않도록, 티켓을 모으고 검토하는 방식 역시 팀 규모에 맞게 바꿔가야 합니다.
\n티켓을 만든 사람도 막상 트리아지를 진행할 때는 당시의 작업 맥락을 잊곤 합니다. 공용 Drawer 티켓도 나중에 다시 읽었을 때 “필수 prop으로 바꾼다”는 결론만 있었다면 안전 재고 화면을 왜 놓쳤는지, 두 티켓을 왜 함께 봐야 하는지 판단하기 어려웠을 것입니다. 그래서 트리아지 세션에서 함께 보는 HTML 화면은 단순히 승격·보류·폐기를 선택하는 도구에 그쳐서는 안 됩니다. 원래 작업을 다시 찾아보지 않아도 무엇을 발견했고 왜 규칙 후보가 되었으며 어디까지 적용하려는지 이해할 수 있어야 합니다. 현재 화면도 이런 정보를 담고 있지만 아직 개선할 부분이 많습니다. 앞으로는 배경지식이 없는 사람도 티켓의 내용을 충분히 이해하고 판단하도록 UI와 정보 구조를 계속 다듬을 예정입니다.
\n컴파운드 트리아지가 해야 할 일은 규칙의 개수를 늘리는 것이 아닙니다. FE팀이 WMS Frontend를 개발하며 얻은, 우리 프로젝트에서만 쌓을 수 있는 규칙과 판단 기준을 축적하고 에이전트가 다음 작업에서 꺼내 쓸 컨텍스트로 만드는 일입니다. 컴파운드 트리아지도 이 역할에 맞게 운영 경험을 반영해 계속 개선할 생각입니다.
\n공용 Drawer 사례에서는 안전 재고 화면에서 놓칠 뻔한 경로가 두 개의 Raw Ticket으로 남았습니다. 사람은 두 후보를 같은 주제로 승격했고, Plan은 진단과 처방을 하나의 문서 절로 묶었습니다. 다음 에이전트는 이전 대화를 기억하지 못해도 그 문서와 필수 prop 계약에서 같은 판단을 다시 꺼내 쓸 수 있습니다.
\nAI 에이전트와 일하면서 같은 실수를 반복하거나 매번 같은 맥락을 다시 설명하고 있다면, 작은 범위에서 컴파운드 트리아지를 직접 운영해보는 것도 추천합니다. 처음부터 완벽한 체계를 만들기보다, 한 번의 작업에서 얻은 교훈을 후보로 남기고 사람이 검토하는 흐름부터 시작해보셔도 좋겠습니다.
", "url": "https://tech.umosone.ai/compound-triage", "title": "AI와 개발하며 배운 것을 팀 규칙으로 남기는 법: WMS의 컴파운드 트리아지", "summary": "AI와 함께 개발하며 발견한 시행착오를 후보로 모으고, 사람의 판단을 거쳐 다음 작업에 쓰이는 팀 규칙으로 만드는 과정을 공용 Drawer 사례와 함께 소개합니다.", "date_modified": "2026-08-18T00:00:00.000Z", "author": { "name": "최영호" }, "tags": [ "AI", "AI 에이전트", "Compound Triage", "WMS" ] }, { "id": "https://tech.umosone.ai/tap-flutter-migration", "content_html": "안드로이드와 iOS로 각각 만들어지던 TAP! 사용자 앱을, 왜 그리고 어떻게 Flutter 하나로 합쳤는지 이야기하고자 합니다.
\n안녕하세요, UMOSONE TAP! 개발팀의 민경운입니다.
\nTAP!은 승객 이동, 기업 카셰어링, 사내 이동 솔루션까지 아우르는 B2B 모빌리티 서비스입니다. 사용자를 실제로 만나는 접점은 이용자·운전자·운영자가 각자 쓰는 몇 개의 서비스로 나뉩니다.
\n![\"TAP!](\"https://tech.umosone.ai/assets/images/tap-service-lineup-47719c112e1a0696c0dc93b409059273.png\")
이 글은 이 중 사용자 앱의 Native → Flutter 전환 과정을 다룹니다.
\n사용자 앱은 원래 안드로이드와 iOS가 완전히 분리된 두 개의 네이티브 프로젝트였습니다. 하지만 한정된 인원으로 안드로이드와 iOS를 따로따로 대응하는 것이 리소스 관점에서 문제가 있었고, 자연스럽게 \"하나의 플랫폼에서 두 OS를 효율적으로 커버할 방법이 없을까\"를 고민하게 됐습니다.
\n다만 크로스플랫폼으로 가기로 방향을 잡았다고 해서 곧바로 프레임워크를 정한 것은 아니었습니다. 가장 유력한 두 후보는 React Native와 Flutter였고, 최종 선택에 앞서 두 프레임워크를 여러 관점에서 비교하는 사전 조사부터 진행했습니다.
\n간단히 소개하면, React Native는 Meta(구 Facebook)가, Flutter는 Google이 만든 크로스플랫폼 프레임워크입니다. 화면을 그리는 방식부터 다릅니다.
\n![\"React](\"https://tech.umosone.ai/assets/images/rn-vs-flutter-rendering-2ae7878f636eaa2b2971204779a093e4.png\")
팀 내부에서 정리했던 비교 자료를 간략히 요약하면 다음과 같습니다.
\n| 관점 | React Native | Flutter |
|---|---|---|
| 렌더링 / 성능 | Bridge를 거치는 구조라 복잡한 UI에서 프레임 저하 가능 | 자체 렌더링 엔진(Skia 기반)으로 애니메이션·고난도 UI에 강함 |
| UI 일관성 | 플랫폼 네이티브 컴포넌트에 의존, OS별로 미묘하게 다름 | 위젯을 직접 그려 플랫폼 간 동일한 UI 보장 |
| 생태계 / DX | JS/TS 자산 활용 가능하지만 라이브러리 품질 편차가 큼 | Google 공식 지원, Hot Reload·DevTools 완성도가 높음 |
| 플랫폼 커버리지 | Android/iOS 중심, Web/Desktop은 정식 지원 아님 | Web/Desktop/임베디드까지 지원 범위 확장 중 |
| 학습 난이도 | JS 경험자가 많다면 진입장벽이 낮음 | Dart, Widget Tree를 새로 학습해야 함 |
표로 정리된 일반적인 비교 외에, 실제 판단에는 몇 가지 현실적인 이유가 더 크게 작용했습니다. React Native는 기능 하나를 구현할 때도 서드파티 라이브러리에 의존해야 하는 경우가 많았고, 그 품질과 유지보수 여부가 라이브러리마다 제각각이라 장기적으로 믿고 갈 수 있는 선택인지 확신이 서지 않았습니다. 반면 Flutter는 팀 내에 이미 사용해본 경험이 있는 팀원이 있어 도입 초기 리스크를 줄일 수 있었고, 자체 렌더링 엔진(Skia 기반)을 쓰는 구조 덕분에 여러 성능 비교 지표에서도 꾸준히 우수한 결과를 보여줬습니다.
\nFlutter는 성능·UI 일관성·멀티플랫폼 확장성에서, React Native는 진입장벽과 기존 JS 자산 활용에서 우세하다는 결론이었습니다. 사용자 앱은 지도·실시간 위치 표현처럼 복잡한 UI와 애니메이션 비중이 컸기 때문에, 최종적으로 Flutter를 선택했습니다. 안드로이드·iOS를 넘어 다른 플랫폼까지 확장할 수 있다는 점은 결정적인 이유는 아니었지만, 선택의 폭을 넓혀준다는 점에서는 나쁘지 않은 옵션이었습니다.
\n막상 선택은 했지만, 안드로이드 네이티브 개발자였던 팀원들에게 Flutter가 완전히 낯선 개념은 아니었습니다. Flutter는 위젯(Widget) 단위로 선언하고 상태가 바뀐 부분만 build()로 다시 그리는데, 이는 이미 써오던 Jetpack Compose의 선언형 UI(Declarative UI) 패러다임과 사실상 같은 사고방식입니다. 명령형으로 뷰를 직접 조작하던 XML 기반 Android View 시스템보다 오히려 Compose 쪽에 가까웠던 덕분에, 팀원들은 Flutter의 위젯 트리와 State 개념에 생각보다 빠르게 적응했습니다.
![\"기존](\"https://tech.umosone.ai/assets/images/tap-native-architecture-6746bdbbc791b4e4931897da1d576038.png\")
전환 전략을 세울 때 가장 먼저 잡은 원칙은 \"아키텍처를 새로 설계하지 않는다\"였습니다. 기존 안드로이드 네이티브 프로젝트는 위 그림과 같은 레이어링으로 구성되어 있었습니다.
\n이미 오래 검증된 레이어링이었기 때문에, 새 구조를 고민하기보다는 이 구조를 그대로 Flutter 프로젝트에 옮기는 쪽을 택했습니다.
\nlib/
├── core/ # 기존 Core:XX 자리 — network, storage, design_system 등 N개 모듈
└── feature/ # 기존 Feature 자리 — Feature A, Feature B, Feature C
└── home/
├── data/ # 기존 Repository 패턴
├── domain/ # 기존 UseCase 개념
└── presentation/ # 화면 + ViewModel
각 기능 모듈 내부는 데이터·도메인·화면(프레젠테이션) 세 계층으로 나누어, 기존의 UseCase 개념과 Repository 패턴을 그대로 유지했습니다.
\n흥미롭게도 이 구조는 저희만의 선택이 아니라, Flutter 공식 아키텍처 가이드가 권장하는 형태이기도 합니다. 공식 가이드도 UI 레이어와 Data 레이어를 나누고, 필요하면 그 사이에 UseCase로 구성된 Domain 레이어를 두라고 안내하는데, Jetpack 권장 아키텍처를 써본 안드로이드 개발자라면 익숙한 그림입니다.
\nCI/CD도 새로 설계하기보다는 기존 네이티브 파이프라인의 뼈대를 그대로 옮겼습니다.
\n![\"Android,](\"https://tech.umosone.ai/assets/images/tap-cicd-pipeline-90f31ac04d79f562684dd0c5f196b2bf.png\")
기존에는 안드로이드·iOS 빌드 환경이 플랫폼별로 따로 돌아갔는데, 이제는 하나의 파이프라인 안에서 Android 빌드가 끝난 뒤 iOS 빌드가 순차적으로 이어지는 구조로 합쳤습니다. 두 빌드가 동시에 돌면서 배포 버전이 꼬이는 걸 막기 위한 순서이고, 운영 브랜치에 병합되면 자동으로 릴리즈가 생성되는 것도 이전 네이티브 파이프라인과 동일한 방식입니다.
\n레이어링과 별개로, Flutter의 상태관리는 어떤 프레임워크로 가져갈지 따로 조사가 필요했습니다. 후보는 Provider, Bloc, GetX, Riverpod이었습니다.
\nBuildContext에 의존하는 구조라 테스트하기 까다로웠습니다.BuildContext 없이도 상태에 접근할 수 있고, 컴파일 타임에 의존성을 검증할 수 있다는 점이 눈에 띄었습니다.무엇보다 Riverpod의 Notifier가 안드로이드에서 써오던 ViewModel과 거의 같은 형태(상태를 들고 있고 UI가 그 상태를 구독하는 구조)라는 점이 크게 작용했습니다. 핵심만 단순화한 예시 코드로 보면 다음과 같은 형태입니다.
\n@riverpod
class RideStatusViewModel extends _$RideStatusViewModel {
@override
FutureOr<RideStatus> build() => repository.fetchStatus();
}
final status = ref.watch(rideStatusViewModelProvider);
return status.when(
data: (value) => StatusView(value),
loading: () => const LoadingView(),
error: (e, _) => ErrorView(e),
);
Notifier가 ViewModel 역할을, AsyncValue가 로딩·에러·성공 상태를 표현합니다. 안드로이드에서 ViewModel과 StateFlow를 구독하던 흐름과 사실상 같아서, 상태관리 자체를 새로 배우는 데 드는 적응 비용은 크지 않았습니다.
Flutter 공식 아키텍처 가이드도 UI 레이어의 패턴으로 MVVM(Model-View-ViewModel)을 명시하고 있어서, Riverpod의 Notifier를 ViewModel처럼 쓰기로 한 결정은 이 가이드와 같은 방향이기도 했습니다.
\n전환한 사용자 앱에는 Flutter와 네이티브 코드 사이를 타입 안전하게 이어주는 Pigeon으로 만든 브릿지가 있습니다. 일부 푸시 알림(iOS Live Activity, Android Live Updates처럼 실시간으로 갱신되는 알림)은 이 브릿지를 통해 네이티브 쪽에서 직접 UI를 그리도록 설계했습니다.
\n앱이 백그라운드/종료 상태일 때 푸시가 표시되지 않는 문제가 있었습니다. 포그라운드에서는 멀쩡히 잘 동작했기 때문에, 처음엔 원인을 좁히기가 까다로웠습니다.
\n원인은 FCM(Firebase Cloud Messaging)의 백그라운드 메시지 처리 방식에 있었습니다. 앱이 백그라운드/종료 상태에서 푸시를 받으면, Dart 백그라운드 핸들러는 메인 앱과는 별도의 Isolate, 별도의 Flutter 엔진 인스턴스에서 실행됩니다. Pigeon이 만든 플랫폼 채널은 특정 엔진의 BinaryMessenger에 등록되는 구조라, 메인 엔진에서만 등록해둔 Pigeon 핸들러는 이 백그라운드 엔진에서는 호출되지 않았습니다.
문제는 이 실패가 조용히 일어난다는 점이었습니다. 에러조차 명확히 나지 않고 무시되는 경우가 있어 재현과 원인 파악에 시간이 오래 걸렸습니다. FlutterFire 공식 문서의 백그라운드 메시지 처리 안내에도 이 핸들러가 별도 컨텍스트에서 실행된다는 점이 명시되어 있습니다.
\n네이티브 플러그인을 모든 Flutter 엔진(메인 + 백그라운드)에 등록해 Pigeon 채널을 백그라운드에서도 열어봤지만, urgent 채널처럼 즉시성이 중요한 알림은 여전히 타이밍이 불안정했습니다. 결국 이 알림 타입만큼은 Dart 백그라운드 핸들러를 거치지 않고, 안드로이드의 FCM 서비스 콜백(Dart Isolate가 아니라 시스템 프로세스에서 바로 실행되는 콜백)에서 네이티브가 직접 그리도록 했습니다.
// Android, 실제 코드를 단순화한 예시
override fun onMessageReceived(message: RemoteMessage) {
// Pigeon 브릿지는 백그라운드 isolate의 BinaryMessenger가 달라 호출이 보장되지 않는다.
if (message.data[\"channel\"] == \"urgent\") {
NativeNotification.show(message.data)
return
}
super.onMessageReceived(message) // 나머지는 Dart 백그라운드 핸들러로 위임
}
// Flutter, 실제 코드를 단순화한 예시
@pragma('vm:entry-point')
Future<void> fcmBackgroundMessageHandler(RemoteMessage message) async {
WidgetsFlutterBinding.ensureInitialized();
if (message.data[\"channel\"] == \"urgent\") {
return; // 네이티브 쪽에서 이미 처리했으므로 여기서는 스킵
}
try {
await showLocalNotification(message);
} on PlatformException {}
}
즉시성이 중요하지 않은 나머지 알림은 그대로 Dart 백그라운드 핸들러에서 flutter_local_notifications로 처리하고, 타이밍이 중요한 알림만 네이티브가 직접 책임지는 쪽으로 역할을 나눈 것입니다. Pigeon 자체의 결함이라기보다는, Isolate 경계를 넘나드는 플랫폼 채널의 한계를 인정하고 우회한 사례에 가깝습니다.
사용자 앱 안에는 일부 화면을 완전한 Flutter 네이티브 UI 대신 WebView로 띄우는 페이지가 있습니다.
\n텍스트 입력창을 눌러 키보드가 올라올 때, iOS에서만 페이지 레이아웃이 위로 밀리거나 하단 영역이 키보드에 가려지는 현상이 있었습니다. 같은 페이지를 Android WebView에서 열면 문제가 없었기 때문에, 처음엔 앱의 WebView 위젯 설정 문제로 의심했습니다.
\nflutter/flutter 저장소에도 비슷한 이슈가 등록되어 있었습니다. Safari나 순수 WKWebView에서는 재현되지 않고 Flutter WebView에서만 나타난다는 점까지, 저희가 겪은 상황과 같았습니다.
가장 먼저 확인한 건 Flutter Scaffold의 resizeToAvoidBottomInset 옵션이었습니다. 키보드가 올라올 때 화면(body)을 키보드 높이만큼 자동으로 줄여주는 기능으로 기본값이 true인데, 해당 화면도 이미 true로 켜져 있어 Flutter 쪽은 정상 동작 중이었습니다. Flutter/네이티브 레이어의 문제는 아니라는 뜻이었고, 그래서 원인을 WebView 안쪽, 즉 페이지 자체로 좁힐 수 있었습니다.
원인을 웹팀과 함께 뜯어보니, 핵심은 iOS Safari의 스크롤 동작과 페이지 구조가 맞물린 문제였습니다.
\nscrollY만큼 스크롤시킵니다.#root)가 document 맨 위에 고정된 채였다는 점입니다. document는 스크롤되는데 #root는 그 스크롤을 따라가지 않으니, 실제로는 화면이 위로 밀린 게 아니라 #root는 원래 자리에 그대로 있고 그 위로 빈 document 배경이 드러나는 모습이었습니다. 저희가 영상에서 본, 화면 위쪽에 정체불명의 빈 공간이 잠깐 나타나는 현상이 정확히 이것이었습니다.비슷한 증상은 Flutter 이슈 트래커에도 보고되어 있습니다. iOS 17.2에서 WebView 안 입력 포커스를 옮길 때 화면 상단에 정체불명의 빈 영역이 생기는 사례는 webview_flutter뿐 아니라 flutter_inappwebview에서도 똑같이 보고돼 있어서, 결이 비슷한 문제로 보입니다. 다만 저희 경우는 웹 페이지 자체의 스크롤·포지셔닝 구조에서 원인을 구체적으로 특정할 수 있었습니다.
![\"iOS](\"https://tech.umosone.ai/img/blog/webview-ios-keyboard-issue.gif\")
\n웹팀이 실제로 적용한 대응은 #root 높이 조정, 스크롤 위치 보정, 가상 영역 clamp를 하나의 훅으로 묶은 형태였습니다.
export const useKeyboardViewport = () => {
useEffect(() => {
const viewport = window.visualViewport;
const root = document.getElementById('root');
if (!viewport || !root) return;
const sync = () => {
const isKeyboardOpen = window.innerHeight > viewport.height;
if (isKeyboardOpen) {
root.style.height = `${viewport.height}px`;
// 가상 영역으로의 스크롤 방지
const maxScrollY = document.body.offsetHeight - viewport.height - 1;
if (window.scrollY > maxScrollY) {
window.scrollTo(0, maxScrollY);
}
} else {
root.style.height = '';
}
// 브라우저 scrollY 보정: root가 스크롤을 따라가도록 이동
const viewportTopGap = viewport.pageTop - viewport.offsetTop;
const translateY = window.scrollY - viewportTopGap;
root.style.transform = translateY !== 0 ? `translateY(${translateY}px)` : '';
};
viewport.addEventListener('resize', sync);
viewport.addEventListener('scroll', sync);
window.addEventListener('scroll', sync);
return () => {
viewport.removeEventListener('resize', sync);
viewport.removeEventListener('scroll', sync);
window.removeEventListener('scroll', sync);
root.style.height = '';
root.style.transform = '';
};
}, []);
};
키보드가 열려 있는 동안은 #root 높이를 줄이고 스크롤 위치를 clamp하고, 닫히면 원래 상태로 되돌립니다. visualViewport의 resize/scroll과 window의 scroll을 모두 구독해서, 키보드가 뜨고 닫히는 순간뿐 아니라 그 사이에 일어나는 스크롤에도 계속 위치를 맞춰줍니다.
앱을 감싸는 WebView 위에서 벌어지는 플랫폼 차이가 항상 Flutter나 네이티브 레이어의 문제인 것은 아니었습니다. 이번 경우는 문제가 실제로 발생하는 지점(WebView 컨테이너인지, 그 안의 웹 페이지인지)을 먼저 구분한 덕분에, 앱 쪽을 붙잡고 있는 대신 웹팀과 빠르게 원인을 공유하고 해결할 수 있었습니다.
\n전환 전 사용자 앱은 지도 SDK로 Mapbox를 쓰고 있었는데, Mapbox는 pub.dev에 공식 Flutter 패키지를 제공하고 있어서 다른 화면들처럼 Dart 코드만으로 지도를 붙일 수 있었습니다. 그런데 내부 사정으로 지도 SDK를 네이버 지도로 교체해야 하는 상황이 됐고, 여기서 문제가 생겼습니다. 네이버 지도는 공식 Flutter 패키지가 없고, 안드로이드·iOS 네이티브 SDK만 제공합니다.
\n기존 Feature 코드가 지도 SDK 구현체를 직접 알지 못하도록, MapController라는 SDK 비종속 인터페이스를 두고 Naver 구현체가 이를 만족하도록 설계했습니다. 지도 SDK를 한 번 더 교체하거나, 서비스에 따라 다른 지도 SDK를 함께 써야 하는 상황이 오더라도 이 인터페이스 뒤에 구현체만 추가하면 되도록 확장 지점을 열어둔 셈입니다. 카메라 이동, 마커/오버레이 관리 같은 명령은 Pigeon으로 정의해 Dart → 네이티브로 호출하고, 지도 준비 완료·카메라 정지·마커 탭 같은 이벤트는 반대로 네이티브 → Dart로 콜백을 보냅니다.
![\"지도](\"https://tech.umosone.ai/assets/images/tap-map-sdk-bridge-6b7e88ef128cb5924b8e87476c56f571.png\")
지도 화면 자체는 Android는 AndroidView, iOS는 UiKitView로 네이버 지도의 네이티브 뷰를 그대로 심고, Pigeon 호출은 뷰 ID를 기준으로 해당 네이티브 뷰 인스턴스에 라우팅하는 방식입니다. 제스처 처리, 오버레이 렌더링, 카메라 이벤트 전달까지 하나하나 안드로이드(Kotlin)와 iOS(Swift) 양쪽에 직접 구현해야 했다는 점에서, 이 구조를 만드는 과정 자체가 곧 네이티브 개발이었습니다.
이 밖에도 마이그레이션 과정에서 자잘한 문제를 여럿 마주쳤습니다.
\n공식 Flutter SDK가 없는 지도 서비스를 붙이는 작업은 결국, 네이티브 SDK를 얼마나 자연스러운 Flutter 인터페이스로 감싸 노출하느냐의 문제였습니다.
\n세 가지 트러블슈팅을 거쳐 자리 잡은 프로젝트는 큰 틀에서 다음과 같은 모습입니다.
\n![\"완성된](\"https://tech.umosone.ai/assets/images/tap-flutter-project-structure-44cd9da954a684407a4b0310d8eb55bc.png\")
lib 아래는 3장에서 다룬 레이어링(공통 모듈 / 화면 단위 기능)을 그대로 따르고, android·ios 폴더에는 Pigeon 브릿지나 FCM 서비스처럼 네이티브 코드가 필요한 부분만 최소한으로 남아 있습니다. 빌드 설정도 네이티브 시절 안드로이드·iOS 각각 관리하던 것을, 이제는 하나의 파이프라인에서 환경 값만 갈아 끼우는 방식으로 관리합니다.
전환의 가장 큰 변화는 기술 스택보다 협업 방식에서 나타났습니다.
\n![\"전환](\"https://tech.umosone.ai/assets/images/tap-collaboration-before-after-50c7c41ea26ebd0dd029f63df504a451.png\")
기존에는 안드로이드와 iOS 개발자가 같은 화면을 두고도 서로 다른 언어(Kotlin/Swift)와 코드베이스로 이야기해야 했고, 리뷰도 두 코드베이스에서 따로 이뤄졌습니다. 지금은 한 사람이 하나의 Dart 코드베이스로 화면 전체를 오너십을 가지고 개발합니다. 트러블슈팅 ①처럼 네이티브 코드까지 들여다봐야 하는 예외도 있지만, 대부분은 같은 코드를 보면서 논의합니다.
\n사용자 앱을 시작으로 전환했지만, TAP!이 만드는 모바일 앱은 사용자 앱 하나가 아닙니다. 드라이버 앱(콘솔)도 같은 방식으로 Flutter 전환을 마쳤습니다.
\n더 나아가, Flutter가 Mobile뿐 아니라 Web·Desktop까지 하나의 코드베이스로 다룰 수 있다는 점(2장에서 살펴본 강점이기도 합니다)을 살려서, Web 화면과 Desktop·차량 인포테인먼트 같은 임베디드 환경까지 아우르는 아키텍처로 확장하는 것도 준비하고 있습니다.
\n![\"Flutter](\"https://tech.umosone.ai/assets/images/tap-flutter-expansion-scope-37db1b13dc060879fe15ae4dd5bb96f3.png\")
이런 방향에 확신을 더해주는 사례도 있습니다. Flutter 공식 쇼케이스에는 이미 LG Electronics, BMW, eBay, Google Pay처럼 굵직한 기업들의 실사용 사례가 올라와 있는데, 최근에는 2026년형 Toyota RAV4의 차량 인포테인먼트 시스템도 Flutter로 개발됐다는 사례가 소개됐습니다. 모바일 앱을 넘어 차량 임베디드 환경까지 하나의 코드베이스로 대응할 수 있다는 건, 저희가 지금 준비 중인 Mobile 너머로의 확장 방향에도 좋은 참고가 됩니다.
\n네이티브 두 벌을 유지하던 사용자 앱을, 리소스 문제에서 출발해 Flutter 하나로 합치기까지의 과정을 정리했습니다. 기술 선택의 배경, 기존 아키텍처를 최대한 살린 전환 전략, 그리고 실제로 겪은 세 가지 트러블슈팅까지 다뤘습니다. 결국 이 전환의 핵심은 프레임워크 자체보다, 안드로이드와 iOS로 나뉘어 있던 팀이 하나의 코드베이스와 하나의 언어로 같은 화면을 이야기할 수 있게 됐다는 점이었습니다.
\n환승은 끝났지만, 다음 정거장까지는 아직 갈 길이 남아 있습니다. Mobile 너머로 확장하는 그 여정도 차근차근 기록해 나가겠습니다.
", "url": "https://tech.umosone.ai/tap-flutter-migration", "title": "두 노선에서 한 노선으로: TAP! 앱, Flutter로 환승하다", "summary": "안드로이드와 iOS로 각각 개발되던 TAP! 사용자 앱을 Flutter로 전환한 과정을 공유합니다. 크로스 플랫폼 기술 선택의 배경부터 상태관리 조사, 실제 전환 과정에서 겪은 트러블슈팅, 전환 이후 얻은 변화까지 기록합니다.", "date_modified": "2026-08-07T00:00:00.000Z", "author": { "name": "민경운" }, "tags": [ "모빌리티", "Flutter", "Mobile", "TAP!" ] }, { "id": "https://tech.umosone.ai/delivery-zone-optimization", "content_html": "전용차량 한 대를 더 붙이는 게 이득일까요, 손해일까요? 그리고 어디를 묶어야 그 한 대가 흑자가 될까요? 경로를 최단으로 만드는 최적화는 이 질문에 답해주지 않았습니다. 저희가 만든 건 “가장 짧은 경로”가 아니라 “현장에서 방어 가능한 권역”을 찾는 엔진이었습니다.
\n안녕하세요, UMOSONE TMS(Transportation Management System) 개발팀의 Backend Engineer 백효현입니다.
\n이 글은 전용차량 배송 권역(zone) 을 비용 최소화 관점에서 추천·최적화하는 엔진을 만들면서, 흔히 말하는 “경로 최적화”를 어떻게 실제 물류 도메인을 검증하고 발굴하는 상용화 기술로 끌어왔는지에 대한 기록입니다. 결정의 근거, 실패한 접근, 운영에서 배운 제약을 함께 남깁니다.
\n\n\n이 글의 수치(손익분기 박스 수, 용량 상한, 절감 비율 등)는 방법론을 설명하기 위한 값이며, 실제 계약 단가·거점 위치·거래처 정보는 포함하지 않습니다.
\n
배송 최적화라고 하면 보통 VRP(Vehicle Routing Problem), 즉 “주어진 배송지들을 가장 짧게 순회하라”를 떠올립니다. 많은 회사가 이 문제에 도전하고, 좋은 솔버도 많습니다. 그런데 저희가 실제로 답해야 했던 질문은 조금 달랐습니다.
\n경로 최적화는 “이 배송지들을 어떻게 도느냐”에 답하지만, 위 질문들은 “애초에 어떤 배송지를 한 묶음으로 볼 것이냐”를 묻습니다. 묶음이 정해지기 전에는 경로가 없고, 묶음의 좋고 나쁨은 경로 길이가 아니라 비용과 제약으로 판단해야 합니다. 여기서부터는 경로 문제가 아니라 권역 설계 문제입니다.
\n권역이 이득인지 판단하려면 먼저 비용 모델이 필요했습니다. 전용차량은 거리 기반 계약이라, 한 권역 z의 월 차량비는 고정비와 주행비의 합으로 둘 수 있습니다.
차량비(z) = F + r × 월주행거리(z)
월주행거리(z) = ( 거점↔권역 왕복 스템 + 권역 내 전 읍면동 2-opt 투어 ) × 월 운행일수
절감액(z) = 월박스(z) × p − 차량비(z) # p = 박스당 공동배송 단가
손익분기(z) = 차량비(z) / p # 이만큼은 배송해야 본전
여기서 두 가지가 중요합니다.
\n첫째, 손익분기는 전역 상수가 아니라 권역별로 다릅니다. 차량비에 주행거리가 들어가므로, 거점에서 가까운 권역은 손익분기 박스 수가 낮고(≈900박스대도 흑자 가능), 먼 권역은 높습니다(월 1,200박스를 넘겨도 적자일 수 있음). 그래서 “월 1,200박스”라는 하나의 기준선으로 모든 권역을 재단하면 가까운 흑자 권역을 놓치고 먼 적자 권역을 잘못 채택합니다.
\n둘째, 어떤 흑자 권역에도 들어가지 못한 물량은 자동으로 공동배송으로 낙착됩니다. 즉 “효율화가 안 되면 위탁”이 별도 규칙이 아니라 비용 모델의 자연스러운 결과가 되도록 설계했습니다.
\n초기 버전(임베디드 JS greedy)은 “최대 몇 대까지”, “반경 몇 km까지” 같은 상한을 입력으로 받았습니다. 그런데 이 상한들이야말로 문제의 본질을 가리고 있었습니다. 몇 대가 최적인지는 우리가 정할 게 아니라 절감액이 정해야 했으니까요.
\n그래서 목적함수를 뒤집었습니다.
\nmin 총비용
= min [ Σ 전용권역 차량비(z) + Σ 공동배송 박스 × p ]
= ( 전체 박스 × p ) − Σ 선택권역 절감액(z) ← 앞항은 상수
⟺ max Σ 선택권역 절감액(z)
s.t. 선택된 권역끼리 셀이 겹치지 않음, 절감액(z) > 0
전체 물량에 단가를 곱한 값은 무엇을 선택하든 상수입니다. 따라서 총비용 최소화는 “겹치지 않는 흑자 권역들의 절감액 합을 최대화”하는 문제와 완전히 같습니다. 이는 전형적인 최대가중 집합 패킹(max-weight set packing) 이고, maxZones 같은 상한이 원천적으로 필요 없어집니다. 몇 대를 뽑을지는 최적화가 절감액을 보고 스스로 결정합니다.
이 재정식화 덕분에 구조가 세 개의 레이어로 깔끔하게 갈라졌습니다.
\n| 레이어 | 역할 | 핵심 |
|---|---|---|
| A. Routing | 실행 가능성·비용 추정 | 이동시간 행렬 + 대표운행일 경로시간 게이트 |
| B. Candidates | 후보 권역 생성 | 폴리곤 인접 그래프를 따라 성장 → 중첩 허용 후보 풀 |
| C. Optimize | 선택 | CP-SAT로 절감액 합 최대인 서로소 조합 선택 |
권역을 얼마나 크게 잡을지는 고정 반경으로 정하지 않았습니다. 실제 운영에서 권역 크기는 밀도의 결과였습니다. 서울 도심은 4km, 경기 외곽은 12km, 지방은 20km까지도 한 권역이 됩니다. 이걸 손으로 정하는 순간 현실과 어긋납니다.
\n대신 유일한 크기 제약을 “시간”으로 뒀습니다. 한 권역의 대표적인 하루 운행이 근무시간 안에 끝나면 실행 가능, 넘으면 불가능입니다.
\n하루 경로시간 = 주행시간 + ( 상차·준비 + 배송지 수 × 하차서비스 )
feasible(z) = 대표운행일 경로시간(z) ≤ 근무창(450분)
이동시간 행렬은 오픈소스 라우팅 엔진으로 좌표 간 실측 이동시간을 뽑고(고유 좌표만 dedup, 48블록 단위, .npz로 캐시), 경로는 최근접 이웃(NN)으로 초기해를 만든 뒤 2-opt 로컬서치로 개선합니다.
처음엔 최근접 이웃 경로만으로 시간을 추정했습니다. 그런데 NN 단독 경로는 최적 대비 5~10% 과대추정을 합니다. 그 결과 실제로는 근무시간 안에 도는 흑자 권역이 “경로 초과”로 판정돼 탈락했습니다. 검토해 보니 탈락한 권역들은 경제성이 문제가 아니라 경로 추정이 부풀려진 것이었습니다. 2-opt를 붙이자 초과로 잘못 걸린 권역의 상당수가 회수됐습니다.
\n더 미묘한 함정이 있었습니다. 처음엔 “권역의 모든 배송지를 매일 다 돈다”는 가정(all-cells, 사실상 최번일)으로 시간을 쟀습니다. 그런데 실제 기사는 그날 주문이 있는 배송지만 돕니다. 최악일 기준으로 재면 멀쩡한 권역이 계속 불가능으로 찍혔습니다.
\n그래서 게이트를 대표운행일(p50) 로 바꿨습니다. “그날 실제 주문이 있는 셀만 라우팅한 일별 소요의 중앙값이 근무시간 이하인가”로 판정합니다.
\nfeasible(z) = median_over_days( 그날 활성 셀만 라우팅한 소요 ) ≤ 근무창
여기엔 반직관적인 성능 함정이 하나 더 있었습니다. “최악일이 통과하면 중앙값도 당연히 통과할 테니 건너뛰자”고 최적화하려 했는데, 최악일은 중앙값의 상한이 아니었습니다. 희소한 권역에서는 평균 배송지 수가 0인 날에 희석돼 최악일 추정이 오히려 중앙값보다 작게 나오는 경우가 있었습니다(실제로 이 때문에 근무초과 권역이 통과된 버그가 있었습니다). 해결책은 진짜 상한이 보장되는 피크일 기반 상한값을 따로 만들어, 그게 근무시간 이하일 때만 중앙값 계산을 건너뛰게 한 것입니다. 이 “값싼 문턱” 덕분에 1,200개가 넘는 씨앗을 몇 분 만에 처리할 수 있었습니다.
\n여기가 이 프로젝트에서 가장 “도메인”스러운 부분입니다. 순수한 거리 문제라면 필요 없지만, 실제 배송을 검증하려면 반드시 있어야 하는 제약들입니다.
\n① 근무창 450분 (스템 제외). 근무 8시간에서 식사·버퍼 30분을 뺀 7시간 30분을 예산으로 둡니다. 중요한 건 무엇을 이 예산에 넣느냐였습니다. 기사는 새벽에 거점에서 상차하고 첫 배송지로 이동하므로, 거점↔권역 왕복(스템) 주행은 근무창에서 제외하고 첫 배송지 도착부터 마지막 배송 완료까지만 잽니다. 이 구분을 하지 않았을 때는 거점에서 먼 권역(도심·외곽)이 왕복 스템 때문에 과잉 페널티를 받아 부당하게 탈락했습니다. (단, 계약 거리는 기사의 실주행이므로 차량비 계산에는 스템 왕복을 포함합니다. 시간 모델과 비용 모델의 거리 정의가 다르다는 점이 처음엔 헷갈렸습니다.)
\n② 강 불가침. “한강을 건너 배송하지 않는다”는 현장 규칙입니다. 손으로 그린 근사 중심선(본류 + 지류) GeoJSON을 두고, 두 셀의 중심을 잇는 선분이 이 강과 교차하면 인접이 아닌 것으로 간주해 인접·다리 간선을 제거했습니다. 이것만으로 강을 넘는 인접 쌍 100여 개가 사라졌습니다. 지리 데이터 없이 인접 그래프만 믿었다면, 다리도 없는 곳을 “가깝다”고 묶었을 겁니다.
\n③ 한 권역이 걸치는 시군구 ≤ 2. 성장 과정에서 한 권역이 세 번째 시군구로 번지지 않도록 막았습니다. 관리·정산 단위가 깔끔해지는 운영상의 이유도 있지만, 흥미로운 건 이 제약이 비용도 개선했다는 점입니다. 권역이 컴팩트해지면 주행이 짧아지고, 같은 450분 안에 더 많은 박스를 소화할 수 있어 전용 물량이 늘고 비용이 내려갔습니다. 여기서 “구가 있는 모든 시는 시+구를 한 단위로” 같은 행정구역 처리가 필요했는데, 특례시(예: 천안·청주 등도 시+구 구조)를 특정 지역만 하드코딩하면 다른 지역의 동이 통째로 사라지는 버그가 있어, 주소 레벨을 일반 규칙으로 판정하도록 고쳤습니다.
\n④ 월 용량 상한과 셀 분할. 한 대가 월 1,750박스까지 담는다고 두고, 물량이 큰 읍면동은 50박스 단위 조각으로 쪼갰습니다(월 운행일 × 배송지당 평균 박스 ≈ 50). 이렇게 하면 한 동을 여러 기사와 공동배송이 나눠 담을 수 있고, 넘치는 물량은 자동으로 공동배송으로 낙착됩니다. “한 동에 물량이 몰리면 어떻게 나눌까”라는 질문이 별도 로직 없이, 조각 분할 + 중첩 후보 + 최적화 선택의 조합으로 자연스럽게 풀립니다.
\n이 네 제약이 함께 작동하면, 반경을 한 번도 지정하지 않았는데도 “수도권은 작게, 지방은 넓게”가 저절로 만들어집니다. 권역 크기는 입력이 아니라 제약의 결과입니다.
\n레이어 B는 폴리곤 인접 그래프를 따라 모든 셀을 씨앗으로 성장시킵니다. 손익분기를 넘는 순간과 시간 한계에 닿는 순간 등 여러 크기에서 후보를 방출하므로, 셀이 서로 겹치는 후보 풀이 만들어집니다. 풀의 다양성이 클수록 최적 조합이 그 안에 존재할 확률이 높아집니다.
\n레이어 C는 OR-Tools CP-SAT로 집합 패킹을 풉니다.
\n변수: x_z ∈ {0,1} # 후보 권역 z 채택 여부
제약: 각 셀 c 에 대해 Σ_{z ∋ c} x_z ≤ 1 # 셀 중첩 금지 (미커버 = 공동배송)
목적: max Σ_z x_z · 절감액(z) # 절감액>0 후보만 풀에 포함
maxZones도 반경도 없습니다. 겹치지 않게 고르면서 절감액 합이 최대가 되는 조합을 CP-SAT가 찾고, 어디에도 뽑히지 않은 셀은 공동배송으로 남습니다.
여기까지가 최적화입니다. 그런데 저희가 정말 신경 쓴 부분은 그다음이었습니다. 모델은 낙관한다는 것을 알고 있었기 때문입니다.
\n후보 생성은 읍면동 중심점 기준으로 빠르게 경로를 추정합니다. 중심점은 셀 내부에 흩어진 실제 배송지들을 무시하기 때문에, 특히 배송지가 듬성듬성한 희소 권역에서 소요 시간을 과소평가합니다. 이 낙관을 그대로 “권장안”으로 내보내면, 현장에서 “계산은 되는데 실제로는 안 돌아가는” 안을 파는 셈이 됩니다.
\n그래서 검증 단계를 붙였습니다.
\n실측 재검증. 선택된 권역을 운행일별 실제 배송지 좌표로 다시 라우팅합니다. 방문 순서는 별도 솔버로 최적화하고, 주행거리·시간은 실측 도로망으로 계산합니다. 각 운행일의 원자료(배송지 수·박스·소요·거리)를 캐시해 두어, 나중에 임의의 백분위를 다시 라우팅 없이 재계산할 수 있게 했습니다. 이렇게 재보면 모델이 말하던 절감 폭은 줄어듭니다. 글로벌 재편성 모드 기준 모델은 약 −9%를 말했지만, 실측으로 되돌리면 약 −5%대가 정직한 숫자였습니다. 편향은 밀도에 따라 양방향입니다. 스캐터가 심한 권역은 과소추정, 밀집 권역은 과대추정이라, 실측이 항상 나쁜 쪽으로만 움직이지도 않았습니다.
\n처리량 테스트 — 판정 기준 자체를 바꾸다. 처음엔 “매일 근무시간 이하”를 기준으로 삼았습니다. 그런데 이건 현장 운영과 맞지 않았습니다. 고물량일에 초과분이 생기면 그날은 일부를 공동배송으로 넘기면 그만이고, 전용차량이 매일 근무시간 안에 끝나야 할 이유는 없습니다. 진짜 문제는 다른 데 있었습니다 — 저물량일에 배송지가 파편화돼 시간이 초과되면, 정작 손익분기를 채울 만큼의 물량을 소화하지 못하는 것입니다.
\n그래서 게이트를 “매일 ≤ 근무”에서 처리량으로 바꿨습니다.
\n월 배송가능(z) = Σ_운행일 일박스 × min(1, 근무 / 그날 소요) ÷ 개월수
유효(z) = 월 배송가능(z) ≥ 손익분기(z) # 시간비례 근사임을 명시
즉 “하루 450분까지 소화하고 초과분은 공동배송으로 넘긴다고 했을 때, 그래도 손익분기 이상 배송할 수 있는가”를 봅니다. 저물량일 시간초과 횟수는 파편화 위험 신호로 따로 진단합니다. 이 기준으로 보면 중앙 운행일에 조금 초과하는 권역도 대부분 유효로 판정되고, 정말 걸러야 할 것은 손익분기 근처에서 아슬아슬한 소수 권역이라는 게 드러납니다.
\n\n\n이 “시간비례 근사”는 정확한 시뮬레이션이 아니라 운영 모델을 반영한 근사이며, 리포트에도 근사임을 명시합니다. 검증 리포트는 가설성 보정(안정성 패널티 등)을 섞지 않고 “지금 실제로 이익을 내는가”만 판단한다는 원칙을 지켰습니다.
\n
초기엔 전용 + 공동배송 전체를 글로벌 재편성해 “현행 대비 몇 대 감축, 약 −9%” 같은 결론을 냈습니다. 숫자는 컸지만, 실제 운영 중인 계약과 노선을 통째로 흔드는 안이라 현장 적용이 부담스러웠습니다.
\n그래서 목적을 바꿨습니다. 기존 전용차량은 그대로 고정하고, 공동배송·택배로 위탁 중인 잔여 물량 안에서 추가로 전용화하면 이득인 권역만 발굴하는 방향입니다.
\n추가 절감 = ( 전환된 위탁 물량 × p ) − Σ 신규 발굴권역 차량비(z) = Σ 절감액(z)
발굴 프레임에서는 위탁 물량 풀이 희소해(배송지당 물량이 적어) 후보 성장이 느리지만, 결과적으로 수도권·충청권에서 소수의 권역을 추가로 발굴할 수 있었고 위탁비의 약 10%를 절감하는 것으로 나왔습니다. 다만 이 역시 처리량 테스트로 되돌려 보면 일부 권역은 손익분기 마진이 근소해, 물량 변동 시 이탈 1순위로 관찰 대상에 두었습니다. “발굴했다”로 끝내지 않고 “얼마나 방어 가능한가”까지 붙이는 것이 이 엔진의 핵심입니다.
\n상용화를 목표로 했기에, 잘 되는 것만큼 안 되는 것도 명시적으로 남겼습니다.
\n이 한계들을 숨기지 않은 이유는 분명합니다. 최적화 결과를 “정답”처럼 제시하면 현장은 한 번 어긋나는 순간 도구 전체를 불신합니다. 어디까지 믿을 수 있고 어디부터 다시 확인해야 하는지를 같이 내보내는 편이, 실제로 쓰이는 도구가 되는 길이었습니다.
\n경로 최적화는 이미 많은 회사가 잘 풀고 있는 문제입니다. 저희가 붙들었던 건 그 앞과 뒤였습니다. 앞에서는 순수한 거리 문제를 손익분기·근무창·강·행정경계·용량이라는 도메인 제약이 박힌 집합 패킹 문제로 재정식화했고, 뒤에서는 낙관적인 모델을 실제 배송지 좌표로 되돌려 처리량 기준으로 검증했습니다.
\n정리하면 이렇습니다.
\n단순 최적화를 서비스에 녹이는 일은 더 좋은 솔버를 붙이는 게 아니라, 우리 도메인의 제약과 검증 기준을 최적화 안으로 끌어들이는 일이었습니다. 그 과정에서 최적화 엔진은 “답을 주는 기계”가 아니라 “권역을 검증하고 발굴하는 도구”가 되었습니다.
\n비슷한 고민을 하는 팀이 있다면, 어떤 제약을 모델 안으로 넣었고 어디서 낙관을 걷어냈는지 이야기 나눠보고 싶습니다. 긴 글 읽어주셔서 감사합니다.
", "url": "https://tech.umosone.ai/delivery-zone-optimization", "title": "경로 최적화를 넘어서: 배송 권역을 검증하고 발굴하는 최적화 엔진 만들기", "summary": "단순 경로 최적화로는 답할 수 없는 “이 권역이 사업적으로 이득인가”라는 질문을, 도메인 제약과 실측 검증을 녹인 3-레이어 최적화 엔진으로 푸는 과정을 정리합니다.", "date_modified": "2026-07-31T00:00:00.000Z", "author": { "name": "백효현" }, "tags": [ "VRP", "물류", "TMS", "최적화" ] }, { "id": "https://tech.umosone.ai/tile38-lettuce-oom", "content_html": "![\"FMS](\"https://tech.umosone.ai/img/blog/fms.png\")
\n안녕하세요, UMOSONE FMS 개발팀의 오수진입니다.
\n본론에 앞서 저희 팀이 만드는 서비스를 짧게 소개합니다. FMS(Fleet Management System)는 차량이라는 자산과 현장을 데이터로 연결해, 차량을 실시간으로 관제하고 모니터링하는 서비스를 만드는 팀입니다. 자체 개발한 차량 단말에서 올라오는 데이터뿐 아니라 현대/기아 자동차의 데이터 파이프라인(HMG Connected Car)과도 연동해, 서로 다른 소스에서 들어오는 차량 데이터를 하나의 플랫폼으로 모으고 있습니다.
\n자율주행 시대가 가까워질수록, 사람이 타지 않은 무인 차량이라도 누군가는 위치와 상태를 실시간으로 확인하고 이상 징후에 대응할 수 있어야 합니다. 저희는 그 역할을 책임지는, 자율주행 시대에 꼭 필요한 관제 서비스를 만드는 팀입니다. 차량 한 대에서만도 위치, 속도, 배터리, 도어, 각종 센서 상태 등 수십 가지 종류의 데이터가 끊임없이 올라오고, 이를 실시간으로 수집·적재·조회하는 대용량 데이터 처리 파이프라인을 만들고 운영하는 것이 저희 팀의 핵심 과제입니다. 이번 글의 무대가 된 fms-vehicle-data-consumer도 이 파이프라인의 일부로, 차량에서 올라오는 위치 이벤트를 Kafka로 받아 지오스페이셜 데이터베이스인 Tile38에 반영하는 컨슈머입니다.
fms-vehicle-data-consumer 파드가 반복적으로 OOMKilled 됨DefaultCommandLatencyCollector 인스턴스 1개가 힙 전체의 72.28%(약 404MB) 를 점유ProtocolKeyword 구현체인 Tile38CommandType이 equals()/hashCode()를 구현하지 않은 채 호출할 때마다 새 객체를 반환CommandLatencyId)가 이 객체의 identity로 만들어지다 보니, 커맨드 이름은 8개뿐인데 키는 무한히 늘어남of()를 캐싱하고 equals/hashCode를 추가해서 해결. 검증 결과 객체 수가 0 → 700+ 로 계속 증가하던 것이 캐싱 적용 후 한 자릿수로 수렴하는 것을 직접 확인\n를 캐싱하고 equals/hashCode`를 추가해서 해결. 검증 결과 객체 수가 0 → 700+ 로 계속 증가하던 것이 캐싱 적용 후 한 자릿수로 수렴하는 것을 직접 확인차량의 위치(위도,경도)정보를 실시간으로 geofencing 서버로 보내 관심지역으로 설정한 구역에 입출 로그를 기록하는 핵심기능중 하나를 처리하는데 차량대수가 늘어나면서 kafka message가 급증했고 위치데이터를 처리하는
\n서비스 파드가 반복적으로 OOMKilled 되는 문제가 있었습니다. 힙덤프를 열어보니 원인은 커맨드 이름이 8개뿐인 곳에서, 메트릭 맵의 키가 1,660개까지 불어나 있는 이상한 모습이었습니다.
프로덕션 힙덤프를 Eclipse Memory Analyzer(MAT)로 분석해보니 원인이 명확하게 드러났습니다.
\n| 시점 | Used Heap | Leak Suspect |
|---|---|---|
| 이전 (7/8 17:54) | 129.8 MB | 없음 |
| 현재 (7/10 13:35) | 534 MB | Problem Suspect 1 발견 |
MAT의 Leak Suspects / Leak Hunter / Top Consumers가 한목소리로 지목한 대상은 다음과 같았습니다.
\nio.lettuce.core.metrics.DefaultCommandLatencyCollector
└ Shallow: 32 B / Retained: 404,683,800 B (72.28%)
Dominator 경로:
DefaultCommandLatencyCollector
└ AtomicReference (latencyMetricsRef)
└ ConcurrentHashMap
└ ConcurrentHashMap$Node[4096] ← 404MB 전부 몰림
인스턴스는 딱 3개인데(before/after 동일), 그중 하나가 통째로 404MB를 물고 있는 전형적인 \"런타임 중 점진적으로 자라나는\" 누수 패턴이었습니다.
\nEclipse MAT 헤드리스 OQL로 덤프를 직접 쿼리해보니 다음과 같은 모순이 발견됐습니다.
\n| OQL | 결과 |
|---|---|
SELECT * FROM io.lettuce.core.metrics.CommandLatencyId | 1,660개 인스턴스 |
SELECT DISTINCT t.command FROM ai.dot42.tile38.Tile38CommandType t | distinct 8개 (SET/DEL/DROP/SETHOOK/DELHOOK/PDELHOOK/GET/OUTPUT) |
CommandLatencyId.localAddress | LocalAddress.ANY (고정 상수) |
CommandLatencyId.remoteAddress | 단일 호스트 |
Tile38CommandType 인스턴스 수 (Class Histogram) | 1,654개 |
커맨드 이름은 8개뿐인데, 메트릭 맵의 키(CommandLatencyId)는 1,660개. local/remote 주소는 둘 다 고정값이니, 키를 서로 다르게 만드는 유일한 요인은 Tile38CommandType 객체 그 자체였습니다.
Lettuce는 커맨드 레이턴시를 아래와 같은 키로 집계합니다.
\nCommandLatencyId(local, remote, commandType)
여기서 commandType은 ProtocolKeyword 타입인데, 저희 팀의 Tile38CommandType은 다음과 같이 구현되어 있었습니다.
package ai.dot42.tile38
import io.lettuce.core.protocol.ProtocolKeyword
class Tile38CommandType private constructor(
private val command: String,
) : ProtocolKeyword {
override fun getBytes(): ByteArray = command.toByteArray(Charsets.US_ASCII)
override fun name(): String = command
companion object {
val SET = Tile38CommandType(\"SET\")
val DEL = Tile38CommandType(\"DEL\")
val DROP = Tile38CommandType(\"DROP\")
val SETHOOK = Tile38CommandType(\"SETHOOK\")
val DELHOOK = Tile38CommandType(\"DELHOOK\")
val PDELHOOK = Tile38CommandType(\"PDELHOOK\")
val GET = Tile38CommandType(\"GET\")
// 문제의 그 함수: 호출할 때마다 새 인스턴스를 만들어 반환
fun of(command: String): Tile38CommandType = Tile38CommandType(command.uppercase())
}
}
문제는 두 가지가 겹쳐서 발생했습니다.
\nequals() / hashCode()를 오버라이드하지 않음 → 기본 구현은 객체 identity 비교of()가 호출할 때마다 Tile38CommandType(...)을 새로 생성해서 반환즉 Tile38Client.execute()가 커맨드를 디스패치할 때마다 Tile38CommandType.of(\"SET\")을 호출하는데, 커맨드 이름은 항상 \"SET\"으로 같아도 매번 다른 객체가 만들어집니다. Lettuce의 메트릭 맵은 이 객체를 키의 일부로 쓰기 때문에:
키 = (고정 local, 고정 remote, 매번 다른 Tile38CommandType 객체)
→ 절대 같은 키로 인식되지 않음
→ dispatch할 때마다 새 키가 맵에 쌓임
→ 키 1개당 HdrHistogram 기반 통계 객체가 ~244KB씩 물림
→ 1,654개 유니크 키 × 244KB ≈ 404MB
이 패턴은 Lettuce의 알려진 이슈(#1210: 커스텀 ProtocolKeyword + identity 기반 키잉으로 인한 메트릭 맵 무한 성장)와 정확히 일치합니다.
\n\n참고로,
\nTile38Client.pipeline()이 호출마다 새 물리 커넥션을 여는 부분도 있었지만, Lettuce의localDistinction기본값이false라 local 주소는 항상 고정값(LocalAddress.ANY)으로 잡힙니다. 따라서 이 커넥션 처칠(churn)은 별개의 리소스 이슈일 뿐, 이번 OOM의 직접 원인은 아니었습니다.
말로만 하면 설득력이 떨어지니, 실제로 of()를 반복 호출하면서 힙에 Tile38CommandType 인스턴스가 어떻게 쌓이는지 VisualVM으로 직접 관찰했습니다.
Given(\"of() 결과가 CommandLatencyId 키로 사용되는 시뮬레이션\") {
When(\"동일 커맨드로 1000회 반복 호출\") {
val iterations = 1000
val uniqueInstances = mutableSetOf<Tile38CommandType>()
repeat(times = iterations) {
uniqueInstances.add(Tile38CommandType.of(command = \"SET\"))
delay(duration = 100.milliseconds)
}
}
}
같은 \"SET\" 커맨드로만 호출하는데도, 반복 횟수가 늘어날수록 힙에 살아있는 Tile38CommandType 인스턴스 수가 함께 늘어나는 것을 확인했습니다.
![\"80회](\"https://tech.umosone.ai/assets/images/visualvm-before-80-6eded9906e337344318c1519d4c228c3.png\")
![\"701회](\"https://tech.umosone.ai/assets/images/visualvm-before-701-b11028eb37d40e27035adee6e3a11212.png\")
즉 호출 횟수와 거의 1:1로 인스턴스가 계속 쌓입니다. 실제 서비스에서 QPS가 높은 Tile38 SET 트래픽이 지속될수록 힙이 점점 부풀어 오른 이유가 바로 이것입니다.
\n캐싱과 equals/hashCode를 추가한 뒤 동일한 시뮬레이션을 132회 반복해도, 인스턴스 수는 늘어나지 않고 9개(커맨드 종류 수 + α)로 수렴했습니다.
![\"132회](\"https://tech.umosone.ai/assets/images/visualvm-after-132-e6b31ab95f0bba59db6b71dcd51a7409.png\")
수정 전/후 비교:
\n| 코드 | 반복 횟수 | 살아있는 인스턴스 수 |
|---|---|---|
| 수정 전 | 80회 | 88개 |
| 수정 전 | 701회 | 709개 |
| 수정 후 | 132회 | 9개 |
수정 전에는 반복 횟수만큼 인스턴스가 그대로 쌓이지만, 수정 후에는 반복 횟수와 무관하게 커맨드 종류 수 근처에서 더 이상 늘어나지 않습니다.
\ncompanion object에 ConcurrentHashMap 기반 캐시를 두고, of()가 같은 커맨드 이름에 대해 항상 같은 인스턴스를 반환하도록 바꿨습니다. 방어적으로 equals()/hashCode()도 문자열 기준으로 추가해서, 혹시 어딘가에서 캐시를 거치지 않고 생성되더라도 값 기반으로 동일하게 취급되도록 했습니다.
class Tile38CommandType private constructor(
private val command: String,
) : ProtocolKeyword {
override fun getBytes(): ByteArray = command.toByteArray(Charsets.US_ASCII)
override fun name(): String = command
override fun equals(other: Any?): Boolean {
if (this === other) return true
if (other !is Tile38CommandType) return false
return command == other.command
}
override fun hashCode(): Int = command.hashCode()
companion object {
private val CACHE = ConcurrentHashMap<String, Tile38CommandType>()
val SET = of(\"SET\")
val DEL = of(\"DEL\")
val DROP = of(\"DROP\")
val SETHOOK = of(\"SETHOOK\")
val DELHOOK = of(\"DELHOOK\")
val PDELHOOK = of(\"PDELHOOK\")
val GET = of(\"GET\")
val RENAME = of(\"RENAME\")
val OUTPUT = of(\"OUTPUT\")
// 캐싱: 같은 이름 → 같은 인스턴스 (메트릭 맵 키가 8~9개로 수렴)
fun of(command: String): Tile38CommandType =
CACHE.computeIfAbsent(command.uppercase()) { Tile38CommandType(it) }
}
}
이렇게 하면 equals/hashCode가 값 기반이든, Lettuce가 여전히 객체 identity로 비교하든 상관없이 캐싱된 동일 인스턴스가 반환되므로 어느 경우에도 키가 수렴합니다.
효과: 맵 키 1,660개 → 8~9개 수렴, DefaultCommandLatencyCollector retained heap 약 404MB → 약 2MB.
SELECT * FROM io.lettuce.core.metrics.CommandLatencyId로 인스턴스 수가 한 자릿수로 줄었는지 확인DefaultCommandLatencyCollector의 retained heap이 더 이상 증가하지 않는지 모니터링Tile38Client*Test, Tile38CommandType 관련) 통과 확인수정 배포 후 검증이나 OOM 발생 시점 분석을 위해 운영 클러스터에서 힙덤프를 수집해야 할 때가 있습니다. 아래는 fms-vehicle-data-consumer 파드를 대상으로 검증된 방법입니다.
jmap 미포함)curl, python3, dnf 사용 가능 (Amazon Linux 2023 기반)tar 미포함 → kubectl cp 사용 불가 (대체 전송 방식 필요)Full GC를 유발하는 -dump:live 옵션 대신 -dump (live 생략)로 생성해야 STW(Stop-The-World) 시간을 단축할 수 있습니다.
# 1. JDK 다운로드 및 추출 (컨테이너에 jmap이 없으므로)
kubectl exec -n <namespace> <pod> -c <container> -- sh -c '
curl -sL -o /tmp/corretto-jdk.tar.gz \\
https://corretto.aws/downloads/latest/amazon-corretto-21-x64-linux-jdk.tar.gz
python3 -c \"import tarfile; tarfile.open(\\\"/tmp/corretto-jdk.tar.gz\\\",\\\"r:gz\\\").extractall(\\\"/tmp/\\\")\"
'
# 2. 힙덤프 생성 (live 옵션 제외)
kubectl exec -n <namespace> <pod> -c <container> -- sh -c '
JDK_HOME=$(ls -d /tmp/amazon-corretto-*/ | head -1)
LD_LIBRARY_PATH=\"$JDK_HOME/lib/server:$JDK_HOME/lib\" \\
$JDK_HOME/bin/jmap -dump:format=b,file=/tmp/heap.hprof 1
'
\n\n주의: 힙 크기에 따라 STW 시간이 비례합니다. 예를 들어 4.9GB 힙은 약 39초, 2.7GB 힙은 약 20초간 애플리케이션이 멈춥니다. health check probe의 timeout/threshold에 따라 파드가 재시작될 수 있습니다. 운영 시간이 오래된 파드일수록 힙이 커서 위험이 높아집니다.
\n
컨테이너에 tar가 없어 kubectl cp를 사용할 수 없습니다. Python HTTP 서버와 kubectl port-forward 조합으로 전송합니다.
# 1. 컨테이너에서 HTTP 서버 실행
kubectl exec -n <namespace> <pod> -c <container> -- sh -c '
nohup python3 -m http.server 9999 --directory /tmp > /dev/null 2>&1 &
'
# 2. 로컬에서 port-forward + 다운로드
kubectl port-forward -n <namespace> pod/<pod> 9999:9999 &
curl -o ./heap-dump.hprof http://localhost:9999/heap.hprof
문제가 있던 v1.11.2 버전에서는 kafka event를 처리하던 consumer가 멈추면서 누적된 lag를 처리할 때 순간적으로 메모리 사용량이 급등했고, 이로 인해 OOM이 발생해 애플리케이션이 다운되면서 scale out으로 파드 개수가 늘어나는 현상을 볼 수 있었습니다.
\n![\"v1.11.2](\"https://tech.umosone.ai/assets/images/pod-memory-before-fix-eb7d857ef23c61dcbbd66004bb64c6fb.png\")
메모리 문제를 수정한 v1.11.3 버전에서는 안정적으로 운영되고 있습니다.
\n![\"v1.11.3](\"https://tech.umosone.ai/assets/images/pod-memory-after-fix-e7328a0de4b09cc3f54bf9ace8451b6f.png\")
Tile38CommandType.of()가 매 커맨드 dispatch마다 equals/hashCode가 없는 새 ProtocolKeyword 객체를 만들었고, Lettuce의 CommandLatencyId가 이 객체의 identity로 메트릭 맵 키를 만들다 보니 키가 절대 충돌하지 않고 무한히 누적됐습니다. of()에 캐싱을 적용하고 값 기반 equals/hashCode를 추가해 해결했으며, VisualVM 재현 실험으로 인스턴스 수가 반복 호출과 무관하게 수렴하는 것을 직접 확인했습니다.
모든 팀원이 같은 기준으로 업무를 시작하고, 질문하고, 완료한다면 어떨까요? 요구사항 정리부터 구현, 테스트, MR, JIRA 정리까지 말이죠. 저희가 AI 하네스를 만들며 바란 건 이것이었습니다.
\n안녕하세요 UMOSONE TMS 개발팀의 Frontend engineer 강수아입니다.
\n이 글에서는 저희 팀이 AI 하네스를 만들면서 어떤 문제를 해결하려 했고, 실제로 운영하면서 무엇이 바뀌었는지 공유합니다.
\n본론에 앞서 저희 팀이 만드는 제품을 짧게 소개합니다. Capora TMS는 화물 운송이 필요한 기업(화주)과 화물차 기사(차주)를 연결하는 운송 관리 플랫폼입니다. \"운송의 모든 흐름을 AI로 연결한다\"는 방향 아래, 오더 등록부터 배차, 운송, 정산까지를 하나의 플랫폼에서 처리합니다. 사용자에 따라 세 개의 서비스로 나뉩니다.
\n| 서비스 | 사용자 | 핵심 역할 |
|---|---|---|
| OMS | 화주 (물류 의뢰 기업) | 오더 등록, 운송 현황 추적 |
| Admin | 내부 운영팀 | 배차, 차량 관제, 정산, 회원 관리 |
| Driver App | 차주 (화물차 기사) | 오더 수락, GPS 운송, 정산 조회 |
하나의 오더는 세 서비스를 가로질러 흐릅니다. 화주가 OMS에서 오더를 등록하면 운영자가 Admin에서 배차하고, 차주가 Driver App으로 수락해 운송하고, 하차가 확인되면 정산으로 이어집니다. 웹 프론트엔드 두 개와 모바일 앱, 이를 받치는 백엔드까지 — 배차 정책, 관제, 정산, 세금계산서 같은 물류 도메인이 얽혀 있어 요구사항을 정확히 이해하는 것이 개발의 절반입니다. AI 하네스가 필요했던 이유도 여기서 출발합니다.
\n처음에는 AI를 쓰는 사람이 늘어나는 것만으로도 충분히 좋아질 거라고 생각했습니다. 실제로 작은 작업에서는 효과가 바로 보였습니다. 요구사항을 요약하고, 기존 코드를 찾고, 테스트 초안을 만드는 속도는 확실히 빨라졌습니다. 그런데 팀 단위로 쓰기 시작하자 다른 문제가 보였습니다.
\nAI로 개발해 본 팀이라면 아마 공감하실 겁니다. 팀원마다 AI를 쓰는 방식이 전부 다릅니다. 누구는 JIRA 티켓을 정리한 뒤 시작하고, 누구는 바로 구현부터 시킵니다. 누구는 Figma나 Confluence를 같이 넣고, 누구는 코드만 보여줍니다. BE 엔지니어와 FE 엔지니어가 일을 처리하는 방식도 다릅니다. 그러다 보니 같은 티켓을 다뤄도 산출물의 품질이 사람에 따라 흔들렸습니다.
\n가장 문제가 됐던 건 AI가 애매한 요구사항을 스스로 판단해서 몰래 채워 넣는 것이었습니다. 예를 들어 \"오더 취소\" 기능을 요청하면, 취소 가능한 배차 상태나 수수료 정책이 비어 있어도 AI는 그럴듯한 기준을 만들어 구현을 이어갑니다. 겉으로는 빠르게 진행되는 것처럼 보이지만, 다 완성되고 나서야 잘못된 방향이었다는 걸 알게 됩니다. 테스트를 끝까지 돌려보지 않은 채로 \"구현했습니다\"라고 말하는 것도 마찬가지였습니다. 말로는 완료인데, 실제로 돌려보면 아니었습니다.
\n그래서 저희는 프롬프트 문장이 아니라 작업 방식을 고정하려고 했습니다. AI가 무엇을 보고 시작하는지, 어느 단계에서 질문하는지, 어떤 산출물을 남기는지, 어떤 검증이 실패하면 멈추는지를 팀의 흐름으로 만들기 시작했습니다.
\n저희가 생각하는 하네스는 AI를 감싸는 실행 환경입니다. 입력을 넣으면 결과만 나오는 검은 상자가 아니라, AI가 어떤 순서로 일했고 무엇을 근거로 판단했는지 남기는 장치에 가깝습니다.
\n현재 흐름은 크게 다섯 단계로 나뉩니다.
\n| 단계 | 책임 | 남겨야 하는 것 |
|---|---|---|
| start | 작업 시작 상태를 고정합니다. | 브랜치, 티켓 맥락, 현재 상태 |
| spec | 요구사항을 구현 가능한 수준으로 정리합니다. | 요구사항 요약, AC, 예외 케이스, 질문 목록 |
| plan | 코드 작성 전에 변경 범위와 검증 전략을 정합니다. | 변경 파일, API 계약, 테스트 계획, 구현 순서 |
| implement | 계획을 task 단위로 쪼개 구현합니다. | 코드 변경, task 체크리스트, 빌드타임 검증 |
| test | 실제 실행 결과로 완료 가능 여부를 판단합니다. | API smoke, 브라우저 확인, 테스트 결과, 커밋 가능 여부 |
중요한 점은 각 단계가 산출물과 통과 조건을 가진다는 것입니다. spec 단계에서 모호함이 남아 있으면 plan으로 넘어가지 않습니다. plan이 확정되지 않으면 코드를 먼저 짜지 않습니다. 필요한 테스트가 실패하면 commit이나 MR로 넘어가지 않습니다.
\n이 구조는 전부 repository 안의 .agents 디렉토리에 들어 있습니다. 특정 도구 전용 설정이 아니라 팀 공용 자산으로 두기 위해서입니다. Claude Code에서는 .claude/skills가 이 디렉토리를 가리키는 symlink로 연결됩니다.
.agents/
├── constitution.md # 팀이 지키는 원칙
├── domain/ # 물류 도메인 지식 (용어, 정산, 배차 …)
├── guides/ # 워크플로우, 아키텍처 가이드
├── patterns/ # 반복되는 코드 패턴
├── skills/ # 반복 판단을 문서화한 스킬
│ ├── feature-workflow/ # spec→plan→implement→test 오케스트레이터
│ ├── feature-spec/ # 단계별 스킬 (spec, start, plan, implement, test)
│ ├── browser-test/ # 브라우저 · Figma 검증
│ ├── ...
│ └── creating-mr/ # MR 생성
└── scratch/{TICKET}/ # 티켓별 산출물 (state, spec, plan, tasks)
스킬은 반복되는 판단을 문서화해 AI에게 \"이런 일을 할 수 있다\"고 알려주는 능력이고, scratch의 산출물은 다음 사람이나 다음 AI가 이어서 볼 수 있는 기록입니다. 도구가 Claude든 Codex든 Gemini든, 같은 팀 지식을 읽고 시작합니다.
\n하네스가 책임져야 하는 범위는 생각보다 넓었습니다. 단순히 코드를 생성하는 것이 아니라, 입력 맥락을 모으고, 누락된 질문을 드러내고, 기존 패턴을 먼저 찾고, 실행 결과를 남기고, 실패했을 때 어디서 멈췄는지 재현 가능하게 만들어야 했습니다.
\nAI 에이전트의 실행 로그는 금방 사라집니다. 터미널 출력, 중간 대화, 임시 판단은 그 순간에는 유용하지만 다음 사람이 보기에는 맥락이 부족합니다. 그래서 하네스에서는 실행과 검증을 분리했습니다.
\n실행은 AI가 합니다. JIRA를 읽고, Figma를 확인하고, 기존 코드를 검색하고, 파일을 수정하고, 테스트를 실행합니다. 검증은 산출물이 맡습니다. spec에는 무엇이 요구사항이고 무엇이 아직 질문인지 남깁니다. plan에는 어떤 파일을 왜 바꿀지, 어떤 테스트로 확인할지 남깁니다. tasks에는 실제 구현 단계를 체크박스로 남기고, test 결과에는 어떤 검증을 실행했고 무엇이 실패했는지 남깁니다.
\n이렇게 나누면 몇 가지 장점이 생깁니다.
\n컨텍스트 비용을 줄이는 데도 도움이 됐습니다. 모든 히스토리를 계속 AI에게 먹이는 대신, 산출물만 남기고 필요한 순간에 다시 읽게 하면 됩니다. 작업이 길어질수록 이 차이가 컸습니다. 하네스는 더 많은 맥락을 한 번에 넣는 장치가 아니라, 필요한 맥락만 다시 꺼낼 수 있게 정리하는 장치에 가까웠습니다.
\nAI가 만든 결과를 믿으려면 완료의 기준이 말로만 남아 있어서는 안 됐습니다. 그래서 완료 기준을 실행 가능한 게이트로 옮겼습니다.
\n화주가 쓰는 오더 등록 화면이라면 단위 테스트만으로는 부족합니다. 타입과 lint가 통과해도 실제 브라우저에서 레이아웃이 깨질 수 있고, Figma가 있는 화면이라면 구현 결과가 디자인과 맞는지도 봐야 합니다. 배차나 정산 API라면 단위 테스트에 더해 API smoke, OpenAPI 계약, 예외 응답까지 확인해야 합니다.
\n그래서 test 단계는 단순히 테스트 명령을 실행하는 역할이 아니라 커밋 가능 여부를 판단하는 게이트가 됐습니다. 필요한 검증이 실패하면 commit이나 MR로 넘어가지 못하고, 실패를 사람이 명시적으로 승인하지 않는 한 완료로 포장하지 않습니다. 게이트에서 확인하는 기준은 대략 이렇습니다.
\n이 기준은 코드, 스킬, hook, 문서로 나눠 남겼습니다. 스킬은 AI가 어떻게 판단해야 하는지 알려주고, hook은 사람이 잊어도 특정 이벤트에서 검증이 실행되게 만들고, 문서는 왜 그런 기준이 필요한지 설명합니다.
\n기준이 지나치게 많아지는 것도 경계했습니다. 하네스가 무거워지면 아무도 쓰지 않습니다. 그래서 모든 작업에 같은 깊이의 검증을 강제하기보다, 작업 크기와 위험도에 따라 quick mode와 standard mode를 나눴습니다. 문구 수정 같은 작은 작업은 quick mode로 빠르게 지나가고, 정책이 걸린 작업은 standard mode로 전 단계를 밟습니다. 대신 quick mode를 탔다면 무엇을 생략했는지 남기게 했습니다.
\n운영하면서도 지속적인 수정이 필요했습니다. 예를 들어 화면 구현에서, 코드상으로는 구현이 끝났지만 Figma와 실제 화면이 미묘하게 다른 일이 있었습니다. 이후 browser-test 흐름으로 viewport, Figma, 브라우저 결과를 같이 확인하고 report를 남기는 쪽으로 바꿨습니다.
\n스킬 자체도 운영 대상이었습니다. 만들어둔 스킬이 실제 작업에서 호출되지 않으면 없는 것과 같습니다. 그래서 스킬 사용량을 보고, 잘 쓰이지 않는 스킬은 trigger를 고치거나 내용을 줄이거나 제거합니다. 스킬을 많이 만드는 게 목표가 아니라, 반복되는 판단이 실제 작업 안에서 자연스럽게 호출되게 만드는 게 목표이기 때문입니다.
\n이런 수정은 한 번으로 끝나지 않습니다. 모델이 바뀌고, 도구가 바뀌고, 팀의 작업 방식이 바뀌면 같은 티켓도 다른 결과를 낼 수 있기 때문입니다.
\n가장 크게 바뀐 기준은 AI와 사람의 책임 경계였습니다. 처음에는 AI가 더 많은 일을 하면 좋다고 생각했지만, 운영해 보니 중요한 건 AI가 어디까지 할 수 있느냐보다 사람이 어디에서 최종 판단해야 하느냐였습니다.
\nAI가 잘하는 일은 초안을 만들고, 흩어진 맥락을 모으고, 누락된 질문을 찾아내고, 검증을 실행해 결과를 정리하는 일입니다. 반대로 spec을 최종 확정하는 일, 질문에 답하고 범위를 결정하는 일, 아키텍처를 판단하는 일, gate 통과나 재작업을 결정하는 일, MR을 승인하고 머지하는 일은 개발자의 책임으로 남습니다.
\n하네스는 이 경계를 더 선명하게 만들기 위해 만든 것입니다. AI가 더 많은 초안을 만들수록 사람이 봐야 할 근거가 더 중요해집니다. 그래서 하네스의 산출물은 AI가 자신 있게 말한 문장이 아니라, 사람이 확인할 수 있는 질문, 결정, 테스트 결과, 실패 기록이어야 합니다.
\n가장 많이 고민한 것은 스킬을 얼마나 잘게 나눌지였습니다. FE는 React/TypeScript, BE는 Kotlin/Spring WebFlux로 스택이 다르지만, 티켓을 읽고, 요구사항을 정리하고, 계획을 세우고, 구현하고, 테스트하는 흐름은 같습니다. 그래서 workflow는 하나로 두고 스택 차이는 reference 문서로 분기했습니다. 한 번 고친 운영 원칙이 양쪽에 같이 반영되게 하기 위해서입니다.
\n두 번째는 요구사항 stress test였습니다. AI는 애매한 요구사항을 보면 질문보다 추정을 택합니다. 그래서 spec 단계에서 사용자, 발생 조건, 필요한 데이터, 정책, 예외, 검증 순서로 질문하게 만들었습니다. 질문을 하나씩 흩뿌리면 답이 누락되기 쉬워서, 가능한 한 묶어서 던지고 답이 없으면 plan으로 넘어가지 않는 기준을 뒀습니다.
\n세 번째는 기록의 양이었습니다. 전부 남기면 읽히지 않고, 너무 적게 남기면 이어받을 수 없습니다. 그래서 다음 단계가 실제로 읽는 spec, plan, tasks, test 위주로 남기고 중간 대화는 과감히 줄였습니다.
\n네 번째는 도구 중립성입니다. 특정 AI 도구의 설정에만 묶이면 팀의 지식이 도구 안에 갇힙니다. 도구는 바뀔 수 있지만, 팀의 판단 기준은 repository 안에 남아야 한다고 봤습니다. 원칙과 스킬을 .agents 아래에 둔 이유입니다.
마지막은 하네스 자체의 비용입니다. 하네스가 너무 무거우면 작은 수정에도 부담이 됩니다. 그래서 모든 작업에 풀코스를 강제하기보다 작업의 위험도에 따라 경로를 나누되, 빠른 경로를 탔다는 사실과 생략한 검증은 남깁니다. 빠르게 가더라도 무엇을 믿을 수 있고 무엇을 다시 확인해야 하는지는 보여야 하기 때문입니다.
\n지금의 하네스는 feature 개발 흐름에서 시작했지만, 화면 구현, 코드리뷰, 문서화, 장애 리포트처럼 입력과 산출물과 검증 기준이 반복되는 업무라면 같은 구조를 적용할 수 있습니다. 저희는 두 가지를 준비하고 있습니다.
\n첫째는 대표 작업 기준의 회귀 평가입니다. 모델이나 스킬을 바꾼 뒤 \"대체로 좋아졌다\"고 말하는 대신, 이전에 처리했던 대표 티켓을 다시 실행해 질문 품질, 계획 품질, 검증 누락이 어떻게 달라졌는지 비교하려 합니다. AI 하네스도 테스트 대상이 되어야 합니다.
\n둘째는 결과 정확도를 높이는 반복 루프입니다. 한 번의 실행으로 끝내지 않고, 실행 결과를 평가하고 부족한 부분을 찾아 다시 실행하는 루프를 하네스 안에 넣으려 합니다. 사람이 매번 결과를 뜯어보며 재작업을 지시하는 대신, 평가와 재실행이 구조 안에서 돌게 만드는 것입니다.
\n하네스의 다음 단계는 \"AI가 더 많은 일을 하게 하기\"가 아니라 **\"AI가 한 일을 더 잘 검증하고 다시 사용할 수 있게 하기\"**라고 생각합니다. 팀의 좋은 판단이 한 사람의 프롬프트 창에만 남지 않고, 다음 작업에서도 반복될 수 있어야 합니다.
\n하네스를 만들며 배운 가장 큰 교훈은 신뢰는 말이 아니라 구조에서 나온다는 점이었습니다. AI가 그럴듯하게 설명해도 실행 결과가 없으면 믿을 수 없습니다. 테스트가 실패했는데 완료라고 말하면 안 됩니다. 요구사항이 애매한데 질문 없이 구현하면 빠른 게 아니라 위험한 것입니다.
\n하네스는 AI를 더 자유롭게 풀어놓기 위한 장치가 아닙니다. 같은 순서, 같은 기준, 같은 멈춤 조건을 만들어 AI와 사람이 함께 일할 수 있는 환경을 만드는 일입니다.
\n속도는 AI가 올릴 수 있습니다. 하지만 책임은 사람이 가져야 합니다. 저희가 하네스를 계속 다듬는 이유도 여기에 있습니다. 더 빠른 개발보다 반복 가능한 개발, 더 많은 자동화보다 검증 가능한 자동화. 그 방향으로 팀의 작업 방식을 조금씩 옮겨가고 있습니다.
\n물론 저희 방식이 정답은 아닙니다. 팀마다 제품도, 도메인도, 일하는 방식도 다르니까요. 비슷한 고민을 하고 있는 팀이 있다면 공유해주세요.
\n긴 글 읽어주셔서 감사합니다 😊
", "url": "https://tech.umosone.ai/ai-harness", "title": "AI 하네스: 반복 가능한 에이전트 개발 환경 만들기", "summary": "팀 전체가 같은 기준으로 AI와 일하기 위해 만든 AI 하네스의 구조와, 운영하면서 바뀐 기준을 정리합니다.", "date_modified": "2026-07-13T00:00:00.000Z", "author": { "name": "강수아" }, "tags": [ "AI", "AI 에이전트", "AI 하네스", "TMS" ] }, { "id": "https://tech.umosone.ai/ontology-eval-loop", "content_html": "안녕하세요, UMOS Data/AI 팀에서 지식그래프를 개발하고 있는 데이터 분석가 이민식입니다.
\n저희 팀은 창고(WMS), 배차(TMS), 차량(FMS), 호출(TAP)처럼 서로 다른 시스템에 흩어져 있는 운영 데이터를 하나의 지식그래프로 연결하고, 그 위에서 자연어 질문을 SPARQL(지식그래프에 데이터를 물어보는 질문 언어)로 바꿔 답하는 온톨로지 기반 챗봇을 만들고 있습니다. 여기서 자연스럽게 드는 질문이 있습니다. 왜 하필 온톨로지일까요?
\n각 시스템 안에서는 \"이번 달 정비 예정 차량\"이나 \"오늘 배차 지연 건수\" 같은 조회가 이미 가능합니다. 하지만 \"정비 이력이 배차 지연에 얼마나 영향을 줬는가\"처럼 시스템 경계를 넘나드는 질문에는 답할 수 없었습니다. 데이터가 없어서가 아니라 서로 다른 이름과 구조로 흩어져 있었기 때문입니다. 온톨로지는 이 데이터를 하나의 의미 구조로 묶어, 도메인을 넘나드는 질문에도 답할 수 있게 만드는 방법입니다. 그리고 이 연결은 한 번 만들고 끝나는 게 아니라, 창고·차량의 실제 상태 변화를 놓치지 않고 계속 반영해야 유지됩니다 — 이렇게 디지털 트윈을 촘촘하게 유지하는 일도 온톨로지 작업의 일부입니다.
\n그런데 이렇게 만든 챗봇이 실제로 믿을 만한 답을 내놓는지는 별개의 문제입니다. 이 글은 그 챗봇을 검증하는 일, 그중에서도 판정을 사람이 아니라 AI에게 맡기면서 데이터 품질 자체가 스스로 채워지는 구조로 바뀐 과정을 다룹니다.
\n이 챗봇을 검증하려면 클러스터별로 나눈 테스트 케이스(TC) 수십~수백 개를 하나씩 확인해야 했습니다. 응답이 맞았는지, SPARQL이 의도대로 짜였는지, 틀렸다면 어디가 문제인지를 사람이 하나씩 확인하던 시절에는 검증 속도가 분석가 한 명의 판단 속도에 그대로 묶여 있었습니다. 지금은 그 판정 대부분을 LLM 체인이 대신하고, 사람은 판정 기준을 지키는 역할만 남았습니다.
\n예를 들어 \"이번 달 정비 예정인 트럭이 몇 대야?\"라는 질문 하나를 검증한다고 해보겠습니다. 이 글에서는 같은 질문을 처음부터 끝까지 따라가며 각 단계를 보여드리겠습니다. 사람이 직접 하면 다음 네 가지를 전부 거쳐야 합니다.
TC가 몇 개일 때는 사람이 감당할 수 있습니다. 하지만 도메인이 늘고 클러스터가 늘어날수록, 이 네 가지 작업 전부가 분석가 한 명의 판단 속도에 묶였습니다. 온톨로지를 넓히는 속도가 아니라 사람이 판정하는 속도가 병목이 된 겁니다.
\n그래서 이 판정 작업 자체를 사람이 아니라 AI에게 맡겼습니다. 여기서 클래스는 엑셀로 치면 \"어떤 시트를 봤는지\"(정비 일정, 차량 같은 것), 프로퍼티는 \"그 시트에서 어떤 열(항목)을 가져왔는지\"(예정일, 차량 번호 같은 것)에 가깝습니다. 이 질문에 제대로 답하려면 어떤 시트와 열을 봐야 하는지 미리 정답을 적어두는데, 이걸 expected_classes, expected_properties라고 부릅니다.
같은 질문 — \"이번 달 정비 예정인 트럭이 몇 대야?\" — 이 다음 세 단계를 어떻게 통과하는지 보면 구조가 보입니다.
match_score) 계산하고 원인을 분류합니다.같은 질문은 다음 여섯 가지 결과 중 하나로 분류됩니다.
\n| Cause | 이 질문이 이렇게 실패했을 때 |
|---|---|
API_ERROR | 질문을 보냈는데 API 응답 자체가 오지 않음 |
NO_SPARQL | 답변은 왔지만 \"이번 달 정비 예정\"을 조회할 SPARQL이 만들어지지 않음 |
NO_DATA | SPARQL은 \"이번 달 정비 예정\" 조건을 정확히 걸었지만, 정비 일정 데이터가 아직 적재되지 않아 결과가 0건 |
WRONG_SPARQL | SPARQL이 \"정비 완료\" 조건으로 잘못 짜였고, 답변도 없음 |
HALLUCINATION | SPARQL은 \"정비 완료\" 조건으로 잘못 짜였는데, 그럴듯한 숫자를 답변으로 만들어냄 |
PASS | \"이번 달 정비 예정 트럭 3대\"처럼 정상적으로 답함 |
방금 그 질문이 NO_DATA로 분류되면, 파이프라인은 이런 형태로 결과를 만들어냅니다.
\n{
\"table\": \"maintenance_schedule\",
\"label_ko\": \"정비 일정\",
\"blocked_tcs\": [\"FMS-DE-A-014\"],
\"columns\": [{ \"column\": \"scheduled_date\", \"label_ko\": \"예정일\" }]
}
사람이 로그를 뒤져서 \"이 질문이 왜 안 풀리지\"를 역추적하던 일이, 실행 결과가 곧바로 \"무엇을 적재해야 하는가\" 리스트로 나오는 형태로 바뀐 겁니다.
\n이 세 단계는 처음부터 이렇게 설계된 게 아니었습니다. 처음 설계는 훨씬 단순했습니다. Rubric Judge 하나로 PASS/FAIL만 나누면 될 거라고 생각했습니다.
\n그런데 같은 질문에서 두 가지 문제가 곧 보였습니다.
\n첫째, \"이번 달 정비 예정인 트럭이 몇 대야?\"에 대해 SPARQL이 \"지난달 정비 완료\" 조건으로 완전히 엉뚱하게 짜인 적이 있었습니다. 그런데 마침 그달 정비 완료 대수와 이번 달 정비 예정 대수가 우연히 똑같아서, 답변만 본 Rubric Judge는 PASS를 줬습니다.
둘째, 반대로 SPARQL이 ScheduledMaintenance 클래스 대신 의미상 동등한 MaintenancePlan 클래스로 조회한 적이 있었습니다. 결과는 맞았지만 rubric이 ScheduledMaintenance만 정답 기준으로 잡아둔 탓에 FAIL로 떨어졌습니다. 답변 내용만 보는 판정으로는 \"어떤 방식으로 답에 도달했는가\"를 신뢰할 수 없었습니다.
그래서 SPARQL 자체를 채점하는 두 번째 판정(SPARQL Judge)을 추가했습니다. 그런데 이것도 완벽하지 않았습니다. 두 번째 사례처럼 SPARQL Judge가 \"기대 경로에 못 미친다(SPARQL_GAP)\"고 판정했는데 Rubric Judge는 PASS를 준, 애매한 경계 케이스가 남았습니다. 이 경계 케이스만 따로 모아 세 번째 판정(Alt SPARQL Verify)이 \"의미적으로 유효한 대체 경로인지, 아니면 우연히 통과한 것인지\"를 한 번 더 검증하도록 구조를 다시 짰습니다.
\n판정을 하나에서 셋으로 늘린 이유는 더 정교해 보이고 싶어서가 아니라, 각 단계가 서로 다른 종류의 오판을 잡아내지 못했기 때문입니다.
\n이 루프에서 사람이 손을 뗀 건 아닙니다. 다만 손을 대는 지점이 바뀌었습니다.
\n첫째, 정답 목록을 정하는 일입니다. 방금 그 질문이라면 \"정비 예정\"이라는 데이터를 부르는 이름이 여러 개일 수 있는데(ScheduledMaintenance 또는 MaintenancePlan), 둘 중 뭘 정답으로 쓸지는 사람이 먼저 정해둬야 합니다. 이 기준이 없으면 SPARQL Judge는 애초에 무엇과 비교해야 할지 모릅니다. AI가 판정하는 게 아니라, 사람이 세운 기준 안에서 AI가 판정을 대신 실행하는 구조에 가깝습니다.
둘째, 경계 케이스를 표본으로 확인하는 일입니다. 방금 MaintenancePlan으로 조회해 SPARQL_GAP이 떴던 사례처럼, \"의미적으로는 맞을 수도 있다\"고 LLM이 판단한 ALT 후보는 사람이 주기적으로 표본을 확인합니다. 판정 체인을 무조건 믿지 않기 위해서입니다.
이 루프는 한 번 돌리고 끝나지 않습니다. NO_DATA로 분류된 케이스가 데이터 적재 백로그가 되고, 백로그가 처리되면 같은 TC를 다시 돌렸을 때 PASS로 바뀝니다. \"이번 달 정비 예정인 트럭이 몇 대야?\"도 정비 일정 테이블이 적재되고 나면 다음 실행에서 PASS로 바뀝니다. SPARQL_GAP이 ALT로 확인되면 expected_classes에 MaintenancePlan이 추가되고, 다음부터는 이 표현으로 조회해도 바로 정답으로 인정됩니다.
즉 평가를 반복할수록 온톨로지 커버리지와 데이터 적재 상태가 조금씩 채워지고, 그 결과가 다시 다음 평가에 반영되는 구조입니다. 사람이 매번 원인을 추적하고 우선순위를 매기던 반복 작업이 사라지면서, 이 사이클을 훨씬 자주 돌릴 수 있게 됐습니다. 사람이 매번 손대지 않아도 데이터 품질이 스스로 자라는 구조는, 판정을 AI 루프에 맡기고 나서야 가능해졌습니다.
\n지금까지 설명한 평가·진단·개선 루프는 TC가 이미 있다는 가정에서 시작했습니다. 그런데 TC 자체도 같은 방식으로 만들어집니다.
\n\"이번 달 정비 예정인 트럭이 몇 대야?\"라는 질문도 그냥 떠오른 게 아닙니다. 만들 때부터 정해진 순서를 따릅니다: Stage 결정 → ID 발급 → 질문·채점 기준 작성.
먼저 이 질문은 \"왜 그랬는지\"를 묻는 게 아니라 \"현재 상태\"를 묻고 있으므로 Descriptive로 분류됩니다. 두 개 이상의 데이터를 연계해야만 답할 수 있는 질문이었다면 Diagnostic으로 분류가 달라졌을 겁니다.
\n그다음 질문 문장과 채점 기준을 씁니다. 여기에도 지켜야 하는 규칙이 있습니다.
\nScheduledMaintenance 같은 클래스명을 노출하지 않습니다. 기준은 \"실제 사용자가 챗봇에 물을 법한 표현인가\"입니다.expected_classes는 \"이 질문에 답하는 최소 SPARQL\"을 머릿속으로 스케치해서, 실제로 등장하는 클래스만 넣습니다. 그리고 데이터가 저장된 그래프 데이터베이스인 Fuseki에 실제로 그 데이터가 몇 건 있는지 확인하고서야 TC로 확정합니다.질문을 쓰는 일도 판정을 설계하는 일과 똑같습니다. 사람은 \"무엇을 기준으로 삼을 것인가\"만 정하고, 그 기준을 지키는 역할을 합니다. 그리고 이 기준은 고정되어 있지 않습니다. 앞서 나온 SPARQL_GAP과 ALT 케이스가 확인되면 그 TC의 expected_classes가 갱신됩니다. TC를 만드는 일과 TC를 검증하는 일이 서로의 결과를 되먹임하는 구조입니다.
이 글에서 다룬 평가 루프는 하나의 사례일 뿐입니다. 데이터 관점에서 마주치는 문제는 이보다 넓습니다.
\nAI 에이전트를 어떻게 평가할 것인가. 이 글에서 다룬 판정 체인이 커버하는 범위는 전체 지능 단계 중 일부입니다. 저희는 챗봇의 지능을 Reactive(Descriptive·Diagnostic) → Proactive(Projective·Predictive·Prescriptive) → Adaptive 순으로 나눠 보고 있는데, 지금 이 루프는 Reactive 단계, 즉 현재 상태를 조회하고 원인을 역추적하는 수준까지만 다룹니다. \"이대로 가면 언제 부족해지는가\"를 계산하는 Projective, \"이 차량이 고장 날 확률은?\"을 추론하는 Predictive, \"그럼 어떻게 해야 하는가\"까지 권고하는 Prescriptive로 올라가려면 지금 같은 rubric·SPARQL 매칭만으로는 판정할 수 없습니다. 답이 맞았는지를 넘어 추론 과정 자체가 타당한지를 평가하는 새로운 판정 체계가 필요합니다.
\n온톨로지가 실제 데이터를 정확히 반영하고 있는가. TBox(온톨로지 설계)와 실제로 적재된 데이터(ABox)는 항상 같지 않습니다. 설계는 있는데 데이터가 아직 없거나, 설계와 다른 이름으로 적재된 경우도 있습니다. 이 글에 나온 Fuseki COUNT 검증처럼, 설계상 존재해야 하는 것과 실제로 존재하는 것의 차이를 끊임없이 실측해야 판정 기준 자체를 믿을 수 있습니다.
\n물리적 운영을 온톨로지로 얼마나 충실하게 옮길 것인가. 창고, 차량, 경로 같은 실제 운영이 온톨로지 안에서 얼마나 정확하게 표현되는지가 챗봇이 답할 수 있는 범위의 상한선이 됩니다. 현실의 상태 변화를 놓치지 않고 온톨로지에 반영하는 일, 즉 디지털 트윈을 촘촘하게 유지하는 일이 곧 챗봇의 정확도를 결정합니다.
\n서로 다른 도메인의 데이터를 하나의 지식그래프로 자산화할 것인가. Fleet Management System(FMS), Warehouse Management System(WMS), Transportation Management System(TMS), TAP은 원래 따로 운영되던 도메인입니다. 각자의 온톨로지로만 두면 \"차량 문제가 배차에 미친 영향\" 같은 질문에는 답할 수 없습니다. 도메인을 넘나드는 질의가 가능하려면, 서로 다른 팀이 만든 데이터를 하나의 지식그래프 문법으로 자산화하는 일이 먼저 필요합니다.
\nAI 루프가 판정·진단·개선안 도출까지 이어서 처리하면서, 온톨로지를 넓히는 작업의 병목은 사람의 판단 속도에서 루프가 도는 속도로 옮겨갔습니다. 그렇다고 AI가 데이터 분석가를 대체했다고 말하고 싶지는 않습니다. 정확히는, 분석가가 매번 반복하던 판정·진단·우선순위 작업을 기준만 명확히 세워두면 반복 가능한 형태로 바꿔둔 것에 가깝습니다. 기준을 세우는 일과 그 기준을 감사하는 일은 여전히 사람의 몫으로 남아 있고, 그 사이의 반복 노동만 사라졌습니다.
\n앞으로도 이 판정 체인이 놓치는 경계 케이스를 계속 찾아내면서, 사람이 감사해야 할 지점과 AI에게 맡길 수 있는 지점을 다시 나누는 작업을 이어갈 예정입니다.
", "url": "https://tech.umosone.ai/ontology-eval-loop", "title": "데이터 품질은 스스로 자란다: AI 루프 시스템이 바꾼 온톨로지 자동화", "summary": "WMS, TMS, FMS, TAP 운영 데이터를 연결하는 지식그래프 온톨로지를 AI 에이전트가 스스로 평가하고 개선하는 자기개선 루프 시스템의 설계와 구현 경험을 공유합니다.", "date_modified": "2026-07-06T00:00:00.000Z", "author": { "name": "이민식" }, "tags": [ "온톨로지", "AI 에이전트", "지식그래프", "데이터 품질" ] }, { "id": "https://tech.umosone.ai/welcome", "content_html": "UMOS ONE 개발팀의 기술 블로그를 시작합니다.
\nUMOS ONE은 물류와 모빌리티의 여러 흐름을 하나의 경험으로 연결하는 End-to-End 모빌리티 솔루션을 만들어가고 있습니다. 창고 운영을 지능화하는 WMS, 운송 흐름을 최적화하는 TMS, 자산과 현장을 데이터로 묶는 FMS, 그리고 수요응답형 셔틀과 자율주행 셔틀을 연결하는 TAP!까지, 저희가 다루는 문제는 화면 하나나 API 하나로 끝나지 않습니다.
\n입고부터 출고까지의 재고 가시성, 화주와 차주의 매칭, 운송 자동화, 실시간 관제, 예지보전, 스마트시티 운영처럼 서로 다른 도메인이 한 시스템 안에서 만납니다. 그래서 UMOSONE 개발팀의 일은 단순히 기능을 빠르게 만드는 일이 아니라, 복잡한 이동과 운영 데이터를 안정적으로 연결하고, 현장에서 믿고 쓸 수 있는 제품으로 다듬는 일에 가깝습니다.
\n이 블로그에는 그런 과정을 기록하려고 합니다.
\n좋은 기술 블로그는 완성된 답만 모아두는 곳이 아니라고 생각합니다. 의사결정의 배경, 실패했던 접근, 다시 고친 구조, 운영하면서 알게 된 현실적인 제약까지 남겨야 다음 사람이 더 나은 선택을 할 수 있습니다.
\nUMOS ONE Tech Blog는 저희가 만든 것뿐 아니라, 만들어가는 방식을 공유하는 공간이 되려 합니다. 모든 이동의 가치를 완성하기 위해 저희가 어떤 기술적 선택을 하고, 어떤 문제를 만나고, 어떻게 해결해가는지 차근차근 기록하겠습니다.
", "url": "https://tech.umosone.ai/welcome", "title": "UMOS ONE Tech Blog를 시작합니다", "summary": "WMS, TMS, FMS, TAP!로 물류와 모빌리티를 연결하는 UMOS ONE 개발팀의 기술 블로그를 시작합니다. 도메인 지식, 운영 데이터, 제품 경험을 기술로 연결하는 여정을 기록합니다.", "date_modified": "2026-06-21T00:00:00.000Z", "author": { "name": "임상석" }, "tags": [ "모빌리티", "물류", "AI", "스마트시티", "I ❤ Engineering" ] } ] }