도커 샌드박스로 레거시 코드베이스 쪼개기
TuBrief 편집팀
2026년 7월 20일
0
컴퓨터/소프트웨어원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
커뮤니티의 다른 글
댓글 (0)
Log in to leave a comment
아직 작성된 글이 없습니다
원본 영상을 바탕으로 AI의 도움을 받아 작성했습니다. 원본 영상이 기준입니다.
Log in to leave a comment
아직 작성된 글이 없습니다
중소규모 IT 기업에서 레거시 시스템을 유지보수하면서 AI 에이전트 도입을 고민하고 있다면 이미 겪고 있을 문제다. 단일 세션에 거대한 모놀리식 코드를 그대로 집어넣으면 에이전트의 주의력이 분산된다. 중간 손실 현상 때문에 답변 정확도가 떨어지고, 코드가 망가지는 속도가 개발 속도를 앞지른다. Git 워크트리와 Docker 샌드박스를 엮어서 이 혼란을 정리하는 법을 살펴본다.
에이전트가 코드를 고친 뒤 세션 로그를 직접 정리하느라 시간을 낭비하지 마라. 파이썬 기반 커밋 자동화 유틸리티를 프로젝트에 집어넣으면 세션 데이터가 규격화된 Conventional Commit 메시지로 즉시 바뀐다. 제트브레인 리서치에 따르면 관찰 마스킹 기법을 적용할 때 단순 요약 방식보다 작업 해결률이 2.6퍼센트 향상되고 토큰 비용이 52퍼센트 절감된다.
자동화 파이프라인은 세 단계로 구성한다. 먼저 프로젝트 루트에 OpenAI API 키와 기본 엔드포인트를 포함하는 환경 변수를 심는다. 다음으로 세션 동안 생성된 git diff 결과와 터미널 실행 로그를 파싱해 Lore-id, Constraint, Rejected, Confidence 같은 트레일러 메타데이터를 묶어주는 파이썬 변환 스크립트를 짠다. 마지막으로 에이전트 세션이 끝나는 시점에 이 스크립트를 돌려 표준화된 커밋 메시지를 원자적 단위로 자동 생성한다. 이 구조를 쓰면 커밋 메시지 작성에 쏟는 공수가 사라지고 정확한 의사결정 기록이 남는다.
다중 에이전트가 같은 호스트에서 동시에 움직이면 포트 바인딩 경합이나 영속 데이터 오염이 터지기 마련이다. 고유 인덱스 기반으로 포트를 동적으로 할당하고 훅 스크립트를 구동하면 런타임 충돌을 막을 수 있다.
격리된 샌드박스 환경은 세 단계로 세팅한다. 첫째, 프로젝트 루트에 .wtcrc.json 파일을 만들어 백엔드와 데이터베이스 포트 범위를 20000에서 29999 사이 동적 오프셋으로 지정한다. 둘째, .git/hooks/post-checkout 이벤트 훅에 워크트리 전환 감지와 Docker Compose 세션 기동 스크립트를 묶어둔다. 셋째, 워크트리가 만들어지는 순간 npm run lint와 npm run test:unit 명령어가 자동으로 돌게 설정한다. 테스트가 실패하면 .agent-error.log 파일에 실패 지표가 기록되어 에이전트가 스스로 교정 루프를 돌 수 있다. 개발자가 개입하지 않아도 빌드 오류를 실시간으로 잡는 폐쇄 루프가 완성된다.
방대한 모놀리식 코드를 단일 프롬프트에 밀어 넣으면 에이전트가 길을 잃는다. 마이크로소프트 리서치 연구에 따르면 조정자와 작업자 구조로 다중 에이전트 생태계를 쪼개는 방식이 결함 전파를 차단하는 데 효과적이다.
물리적 구조를 완전히 뜯어고치지 않고 도메인을 나누려면 다음 세 가지를 실행한다. 첫째, 프로젝트 내부에 .agent-context/core/ 디렉토리를 파서 에이전트 페르소나와 행동 규칙 규격을 정의한다. 둘째, 인증이나 결제 같은 개별 기능 영역을 논리적으로 분리하고 심볼릭 링크를 활용해 작업 공간에 마운트하는 셸 스크립트를 실행한다. 셋째, 지능형 검색 프레임워크를 연동해 에이전트가 전체 파일을 다 읽지 않고 필요한 바이트 영역만 핀포인트로 조회하게 만든다. 이 방식을 쓰면 토큰 소비량이 최대 95퍼센트까지 줄어들고 불필요한 레거시 소음이 컨텍스트로 흘러 들어가지 않는다.
서로 다른 브랜치에서 일하는 에이전트들이 제각각 패키지 버전을 등록하면 병합할 때 코드가 깨진다. 브랜치 네이밍 컨벤션을 강제하고 교차 스캐너를 돌리면 머지 컨플릭트를 80퍼센트 이상 막을 수 있다.
의존성 충돌을 차단하는 대응 절차는 세 단계다. 첫째, 신규 기능은 ai/feat/{agent-id}/{ticket-id}, 버그 수정은 ai/fix/{agent-id}/{ticket-id} 형태로 브랜치 이름을 고정한다. 둘째, 로컬 호스트의 전체 활성 워크트리를 돌며 각 package.json 의존성 버전을 대조하는 파이썬 교차 스캔 스크립트를 주기적으로 실행한다. 셋째, 버전이 어긋나는 지점이 포착되면 스크립트가 경고를 띄우고 리베이스를 유도한다. 이 프로토콜 하나로 병렬 작업 중 발생하는 패키지 정합성 문제를 사전에 잡을 수 있다.
세션이 끝날 때마다 학습한 컨텍스트가 날아가면 에이전트는 똑같은 실수를 반복한다. AGENTS.md를 단 하나의 원본 지식 출처로 지정하고 지식 생애 주기를 관리하면 영속적인 컨텍스트 상속이 가능하다.
메모리 저장소 표준을 잡으려면 세 가지 단계를 밟는다. 첫째, 리포지토리 루트에 AGENTS.md 파일을 만들어 정적 아키텍처 규칙과 세션 누적 복구 지식을 기록한다. 둘째, 개별 도구의 시작 파일에서 원시 규칙을 직접 쓰지 않고 인클루드 지정이나 심볼릭 링크 매핑을 적용한다. 셋째, lore stale 감사 명령어로 낡은 지식 항목을 스캔하고 새로운 항목으로 대체 등록한다. 인터컴의 Fin AI Agent는 이와 유사한 정밀 지식 격리 모델을 써서 이커머스 도메인에서 최대 84퍼센트 완전 자율 해결률을 달성했고, 쇼피파이는 로컬 샌드박스와 실시간 GraphQL 스키마 컴파일 검증을 도입해 AI 유입 트래픽을 전년 대비 7배 키웠다. 표준화된 거버넌스는 대규모 상업적 소프트웨어의 기술 부채를 지우는 유일한 방법이다.