실제 운영 코드에서 테스트를 거쳐, 구조화된 진단 결과물을 생성하는 오픈 소스 프레임워크로 레거시 시스템을 상속받는 고통을 어떻게 변화시켰는지 소개합니다.

당신은 시스템을 상속받습니다. 265개의 백엔드 파일, 209개의 프론트엔드 파일, 80개의 저장 프로시저(Stored Procedures). Spring Boot 2.7과 Angular 14 — 둘 다 2023년 11월 이후 지원이 종료(End-of-life)되었습니다. 비즈니스 로직은 아무도 완전히 이해하지 못하는 SQL Server 프로시저에 들어 있습니다. 테스트는 없습니다. 아키텍처 문서도 없습니다. 현대화 계획도 없습니다.

경영진은 이번 분기 말까지 로드맵을 원합니다.

이런 상황을 겪어본 적이 있다면, 다음에 어떤 일이 일어날지 알 것입니다. 몇 주 동안 코드를 읽고, 화이트보드에 박스를 그리고, 무엇이 고장 났는지 수동으로 목록을 만들며, catch 블록 안에 숨겨진 중요한 무언가를 놓치지 않기를 기도하는 일 말입니다.

저는 이 과정을 충분히 반복하면서 대부분의 작업이 **기계적(mechanical)**이라는 것을 깨달았습니다. 패턴 스캔, 의존성 매핑, 비즈니스 규칙 목록화, OWASP 기준 교차 참조 등이 그것입니다. 판단(judgment) 부분(무엇을 우선시할지, 작업을 어떻게 단계별로 진행할지, 위험 요소가 어디에 있는지)은 진정으로 어렵습니다. 하지만 탐색(discovery) 부분은 수동으로 수행할 때 지루하고 반복적이며 오류가 발생하기 쉽습니다.

그래서 저는 탐색을 자동화하고 계획을 구조화하는 도구를 만들었습니다.

Legacy Squad가 하는 일

Legacy Squad는 프로젝트에 설치되어 구조화된 현대화 진단 결과물을 생성하는 오픈 소스 CLI입니다. 단 하나의 명령어로 실행됩니다:

npx legacy-squad install

이 명령은 저장소를 스캔하고, 결정론적 컴플라이언스 엔진(Compliance Engine, OWASP / CWE 패턴 매칭)을 실행하며, 모듈별 컨텍스트 팩(context packs)을 생성하고, IDE(Claude Code 또는 Codex CLI) 내에서 슬래시 명령어로 사용할 수 있는 5개의 AI 에이전트를 설치합니다.

이 에이전트들은 자유 형식의 채팅이 아닙니다. 각 에이전트는 구조화된 출력을 강제하는 방법론 기반의 프롬프트(prompt)를 따릅니다. 즉, 파일:라인 참조가 포함된 증거, 프레임워크 인용, 영향 평가, 그리고 실행 가능한 권장 사항을 제공합니다.

5개의 에이전트와 4개의 생성기(generators)를 실행하고 나면, 다음과 같은 결과물을 얻게 됩니다:

• PRS — Product Refactor Specification (통합 진단 결과)
• SDD — Software Design Document (현재 및 목표 아키텍처와 ADRs 포함)
• MMP — Modernization Master Plan (롤백 전략을 포함한 단계별 로드맵)
• Execution Specs — 작업 단위당 하나씩 구성된 원자적 (atomic) YAML 파일로, 개별적으로 배포 가능

이 프레임워크는 코드를 절대 수정하지 않습니다. 설계 단계부터 읽기 전용 (Read-only)으로 제작되었습니다.

실제 운영 시스템에서 발견한 내용

저는 두 개의 실제 운영 시스템을 대상으로 프레임워크를 검증했습니다. 하나는 금융 거래를 처리하는 모바일 앱 (~18k LoC, React Native)이고, 다른 하나는 수명이 다한 (end-of-life) 프레임워크를 사용하는 Java/Spring Boot + Angular 백엔드 (~550개 소스 파일)입니다. 두 시스템 모두 실제 사용자가 있는 운영 환경입니다.

백엔드 시스템의 수치:

20개의 발견 사항	심각(critical) 3개, 높음(high) 4개, 중간(medium) 8개, 낮음(low) 5개
...

발견되는 항목의 종류

운영 시스템에 대한 구체적인 내용은 공개할 수 없지만 (실제 활성 시스템이므로), 발견된 항목의 카테고리를 통해 그 깊이를 알 수 있습니다:

• 인증 우회 (Authentication bypasses) — 특정 요청 파라미터 하에서 자격 증명 검증을 건너뛰는 조건부 분기. CWE-287.
• 만료되지 않는 토큰 (Non-expiring tokens) — exp 클레임(claim)이 없는 JWT 서명과 쿼리 스트링을 통해 수락되는 토큰(액세스 로그에 기록됨)의 결합. CWE-613.
• 직관에 반하는 아키텍처 권장 사항 (Counter-intuitive architecture recommendations) — 한 시스템에서는 처음에 코드 스멜 (code smell)로 분류되었던 저장 프로시저 (stored procedures)가 점진적 현대화를 위한 가장 안전한 닻(anchor)임이 밝혀졌습니다. 모든 비즈니스 로직이 애플리케이션 레이어로부터 격리되어 있었기 때문입니다. MMP는 프레임워크 업그레이드 중에 이를 수정하지 않고 그대로 유지할 것을 권장했습니다. 이는 당연한 선택은 아니었지만, 증거에 기반한 선택이었습니다.
• 암묵적인 비즈니스 규칙 (Implicit business rules) — 멱등성 (idempotency) 제약 조건, 쿼리에 하드코딩된 계산 백분율, 내보내기 흐름에서의 off-by-one 기간 로직 등입니다. 문서화된 적은 없지만, 인지하지 못한 채 리팩터링할 경우 조용히 시스템을 망가뜨릴 수 있는 요소들입니다.

모든 발견 사항(finding)은 특정 파일과 라인으로 추적됩니다. 모든 비즈니스 규칙(business rule)은 이를 보존하기 위해 필요한 실행 사양(execution spec)과 연결됩니다.

SonarQube / Snyk / Copilot과 무엇이 다른가

솔직한 답변을 드리자면: Legacy Squad는 이 도구들을 대체하지 않습니다. 대신 다른 영역을 차지합니다.

SonarQube는 지속적인 코드 품질(continuous code quality)을 담당합니다. Snyk는 CVE 스캐닝을 수행합니다. Copilot은 에디터 내 자동 완성(autocomplete)을 제공합니다. 이 중 그 어떤 것도 **아키텍처 평가(architecture assessment)**를 수행하거나, 코드에서 비즈니스 규칙을 추출하거나, **단계별 롤백 전략이 포함된 단계적 현대화 계획(phased modernization plan)**을 생성하지는 않습니다.

Legacy Squad는 이 도구들이 멈추는 지점에서 시작합니다. 이 도구는 결정론적 스캐닝(deterministic scanning, LLM을 사용하지 않는 OWASP/CWE 패턴 매칭)과 방법론에 기반한 AI 에이전트(AI agents)를 결합하여, 단순한 채팅 기록이 아닌 구조화된 엔지니어링 문서(structured engineering documents)를 생성합니다.

핵심 제약 사항: 저장소(repository) 전체가 어떤 LLM으로도 전송되지 않습니다. 컨텍스트 매니저(Context Manager)는 토큰 효율적인 모듈별 컨텍스트 팩(context packs)을 구축하며, AI는 전적으로 사용자의 IDE 내부에서 실행됩니다. 프레임워크 자체에서 요구하는 API 키는 전혀 없습니다. 외부 서버도 전혀 필요하지 않습니다.

2분 만에 체험하기

스캔할 레거시 프로젝트가 없으신가요? 의도적인 레거시 문제(SQL 인젝션, 하드코딩된 비밀값, 비대한 컨트롤러(fat controllers), 중복 로직, 데드 코드)를 포함한 작은 Node/Express HR API인 데모 프로젝트를 구축해 두었습니다.

git clone https://github.com/hrpimenta/legacy-squad-demo.git
cd legacy-squad-demo
npx legacy-squad install

그러면 즉시 .legacy-squad/memory/findings/에서 컴플라이언스 엔진(Compliance Engine)의 발견 사항을 확인할 수 있습니다. 그다음 Claude Code나 Codex CLI에서 프로젝트를 열고 다음을 실행하세요:

/legacy-squad:security

보안 에이전트(Security Agent)가 코드베이스를 분석하고, 모든 발견 사항에 대해 파일:라인(file:line) 증거를 포함한 구조화된 평가서를 .legacy-squad/outputs/assessments/security.md에 작성합니다.

프로젝트가 라이프사이클(lifecycle) 중 어느 단계에 있는지 확인하려면 다음을 실행하세요:

npx legacy-squad status

이것을 만든 이유

저는 "그냥 새로 쓰면 되잖아요"라는 말이 통하지 않는 조직의 레거시 시스템 (Legacy systems)을 다룹니다. 시스템은 운영 환경 (Production)에 있으며 실제 트랜잭션을 처리하고 있고, 엔지니어링 팀이 무엇을 먼저 현대화할지 고민하는 동안 비즈니스는 멈출 수 없습니다.

제가 계속해서 목격한 패턴은 다음과 같습니다. 현대화하겠다는 "결정"은 쉬웠습니다. 하지만 현대화를 위한 "계획"이 병목 현상 (Bottleneck)이었습니다. 팀들은 발견 (Discovery) 단계에서 몇 주를 소비하고, 완료될 때쯤이면 이미 구식이 되어버린 Confluence 페이지를 만들어냈으며, 그 후에는 근거 없이 우선순위를 두고 논쟁하곤 했습니다.

Legacy Squad는 이 발견 단계를 몇 주에서 몇 시간으로 압축하기 위해 존재합니다. 모든 발견 사항은 코드(Code)로 추적 가능하며, 모든 권장 사항은 프레임워크 참조 (Framework reference)를 바탕으로 하고, 모든 실행 사양 (Execution spec)은 롤백 (Rollback)이 가능한 상태로 개별 배포될 수 있습니다.

V1은 오픈 소스 발견 플랫폼 (Discovery Platform)인 '이해 및 계획' 단계입니다. V2 (설계 중)는 유료 엔터프라이즈 (Enterprise) 레이어로 AI 지원 실행 — 리팩터링 (Refactoring), PR (Pull Requests), QA 게이트 (QA gates) — 기능을 추가할 예정입니다.

Links

• GitHub: hrpimenta/legacy-squad
• npm: legacy-squad
• Demo project: hrpimenta/legacy-squad-demo
• Full case study: Case Study — Real Organization

레거시 시스템을 다루고 계시고 이를 사용해보고 싶으시다면, 진심으로 피드백을 부탁드립니다. 그리고 유용하다고 느끼신다면, GitHub의 ⭐ (Star) 하나가 프로젝트의 가시성을 높이는 데 큰 도움이 됩니다.