팀보다 오래된 코드베이스에서 에이전트 굴리기 — 브라운필드 에이전틱 엔지니어링

홍승아2026.10.1115분

브라운필드 에이전틱 엔지니어링: 숨은 제약을 드러내고, 싼 변경을 믿을 수 있게

Addy Osmani의 글 Brownfield Agentic Engineering(2026-09-14, 부제 "What it takes to run agents in a codebase older than the team")을 읽고 정리한 글입니다.

✍️ 한 줄 요약

오래된 코드베이스에서 에이전트를 성공시키는 건 감독(supervision)이 아니라 구조(structure)입니다. 사람이 위험 구역 지도를 그리고, 코드가 말하지 못하는 것만 적고, 반복되는 지적은 하네스로 옮기고, 지금 동작을 테스트로 잠근 뒤, 완결된 단위로 옮기고, 병렬화는 맨 마지막에 합니다.

요약

브라운필드란: 저장소가 더 이상 시스템이 실제로 어떻게 동작하는지 완전히 설명하지 못하는 코드베이스. 암묵지, 덕트 테이프, 레거시 서비스, 다른 팀이 기대는 동작이 트리 바깥에 있습니다.
구역(Zones): 초록(테스트 좋고 격리됨 → 자율 루프) · 노랑(품질 혼재 → characterization test 먼저) · 빨강(인증·결제·권한·급여 → 매 단계 사람과 페어링). 지도는 사람이 그리고, 구역은 자격을 얻어야 올라갑니다.
코드가 말하지 못하는 것만 적기: 에이전트는 구조는 잘 추론합니다. 비즈니스 뉘앙스, 트레이드오프, 도구로 강제되지 않는 규칙, 도메인 규칙, 직관에 반하는 구현의 역사만 문서로 남깁니다.
리서치는 세션보다 오래 살아야: 노랑·빨강 작업은 읽기 전용 패스로 이해 메모(진입점·소유자·호출자·테스트·운영 신호·열린 질문, 모든 주장에 출처)를 먼저 남깁니다.
반복되는 지적 = 하네스의 빈 칸: 같은 리뷰 코멘트가 두 번 나오면 lint 규칙·훅·타입·테스트·스킬로 옮깁니다. 산문은 기계로 강제할 수 없는 제약에만.
무위험 작업부터, 완결된 단위로: 현재 동작(못생긴 부분까지)을 잠그는 characterization test → 기계적 변환 → 경로 하나를 옛 의존성 삭제까지 끝내기. 테스트와 구현을 같은 세션이 동시에 쓰게 두지 않습니다.
병렬화는 마지막에: 병렬화는 이미 있는 병목을 곱합니다. 한 단위가 믿을 만한 판정·복구 경로·리뷰 포맷을 갖춘 다음에야 늘립니다.
에이전트는 모호함에 가격표를 붙인다: 생성한 줄 수가 아니라 리드 타임·리뷰 시간·개입 횟수·탈출 결함·롤백·남은 옛 import·새 경로 트래픽을 봅니다.

원칙	핵심 문장
구역	자율성은 모델의 자신감이 아니라 폭발 반경·관측성·복구 가능성을 따른다
문서	코드가 말하지 못하는 것만 적어라, 그 외에는 아무것도
리서치	산출물 없는 탐색은 다음 에이전트가 같은 발굴을 다시 하게 만든다
하네스	반복되는 지적은 모두 하네스에서 빠진 조각이다
시작	무언가 개선하게 두기 전에 오늘의 동작부터 잠가라
마이그레이션	새 경로가 동작하고 옛 의존성이 사라졌음이 증명될 때 완료다
대형 사례의 교훈	회사 간에 옮겨지는 건 에이전트 주변의 구조다
무엇이 바뀌었나	여러 구현을 시도하는 비용은 바뀌었지만, 고르는 데 필요한 증거는 그대로
병렬화	병렬화는 이미 가진 병목을 곱한다
지표	에이전트는 모호함에 눈에 보이는 가격을 붙인다

아래부터는 상세 내용입니다.

브라운필드란 무엇인가

브라운필드 시스템은 저장소가 더 이상 그 시스템의 실제 동작을 완전히 설명하지 못하는 코드베이스입니다. 조직의 암묵지, 덕트 테이프로 붙여 둔 땜질, 레거시 서비스, 다른 팀이 의존하는 기대 동작이 코드 트리 바깥에 살고 있습니다. 그래서 새 코드를 쓰기 전에 그 제약을 먼저 배워야 하고, 변경 후에는 그 제약을 깨지 않았음을 증명해야 합니다.

저자는 에이전트로 코딩하는 걸 좋아하지만, 감독 없이 오래된 코드베이스에 던져 넣으면 "돌아가기는" 하는데 시스템 설계는 틀리고 테스트는 깨지기 쉬운 결과물이 나올 수 있다고 경고합니다. AI 이전에도 현대화 작업은 아주 조금씩, 강한 테스트를 깔고, 실제 사용자 여정 테스트와 반복 가능한 테스트 묶음으로 "의도대로 동작함"을 지키며 진행해야 했습니다.

요즘은 "에이전트가 내가 결정 하나하나를 내리지 않은 코드를 떨군 순간 이미 브라운필드"라고 말하는 사람도 있습니다. 어느 쪽이든 목표는 같습니다 — 싼 변경을 안전하게 만드는 것. 에이전틱 엔지니어링이나 소프트웨어 팩토리 같은 자율 패턴을 큰 코드베이스에 들이려면 추가적인 주의를 기울이지 않으면 기술 부채 세계에 가입하는 셈입니다.

글 전체의 전제는 하나입니다. 코드가 진실의 원천(source of truth)이다. 그 위에 덧붙이는 모든 것은 코드에서 쉽게 추론할 수 없는 것이어야 합니다.

구역 나누기

오래된 코드베이스에 들어가면 먼저 알고 싶은 건 "어디를 건드리면 안 되는가"입니다. 이를 구역(Zone)으로 나눕니다.

구역	특징	에이전트가 할 수 있는 일
🟢 초록	테스트 커버리지 좋음 · 최신 컨벤션 · 격리가 잘 됨	촘촘한 자율 루프
🟡 노랑	품질이 섞여 있음	characterization test를 쓴 뒤에 변경
🔴 빨강	인증 · 결제 · 권한 · 급여, 소수만 이해하는 영역	매 단계 사람과 페어링, 아니면 하지 않음

저자가 일했던 커머스 사이트에서는 사용자에겐 하나로 보이는 경험 뒤에 대여섯 부서가 각자 마이크로사이트를 운영하는 경우가 흔했습니다. 최근 몇 년 사이 만든 팀의 영역은 테스트가 탄탄하지만, 다른 팀은 그렇지 않습니다. 같은 저장소 안에서도 구역이 갈리는 이유입니다.

구역을 비유가 아니라 운영 절차로 만드는 규칙은 세 가지입니다.

지도는 사람이 그린다, 에이전트가 아니라. 에이전트에게 고르게 하면 가장 무서운 파일부터 시작합니다. 가장 무서운 파일에 가장 흥미로운 이름이 붙어 있기 때문입니다.
구역은 자격을 얻어야 이동한다. 노랑은 characterization test가 생기고 모듈 소유자가 에이전트의 첫 변경을 리뷰한 뒤에야 초록이 됩니다.
구역이 동사를 정한다. 초록은 촘촘한 루프, 노랑은 테스트 먼저, 빨강은 매 단계 사람과 페어링이거나 아예 하지 않음.

코드가 말하지 못하는 것만 적기

자율성은 폭발 반경(blast radius), 관측성, 복구 가능성을 따라야 한다. 모델의 자신감은 형편없는 지표다.

한때 사람들은 모든 것을 마크다운 파일로 만들어 컨텍스트 창에 밀어 넣었습니다. 하지만 에이전트는 코드만 보고도 시스템의 지도를 꽤 잘 이해합니다. 그러니 줘야 할 것은 코드에서 드러나지 않는 것입니다.

비즈니스 또는 팀 고유의 뉘앙스
시스템이 왜 이런 구조인지 설명하는 트레이드오프
정적 분석이나 도구로 강제되지 않는 가이드라인
도메인 특화 규칙
외부 제약, 그리고 직관에 반하는 구현 뒤에 숨은 역사적 맥락

코드가 말하지 못하는 것만 적어라. 그리고 그 외에는 아무것도 적지 마라.

이 원칙은 에이전트가 실제로 따르는 스펙 쓰는 법에서 다룬 "지시를 늘릴수록 덜 지켜진다"와도 맞닿아 있습니다. 문서가 짧고 날카로울수록 실제로 지켜집니다.

리서치가 세션보다 오래 살게 하기

에이전트의 탐색이 남기는 산출물이 없다면, 다음 에이전트가 같은 고고학 발굴 비용을 또 낸다.

기본 루프는 리서치를 낭비합니다. 에이전트가 인증 흐름이 어떻게 동작하는지 알아내고, 작업을 끝내고, 세션이 끝나면 그 이해를 잃습니다. 채팅 기록은 좋은 기록 시스템이 아닙니다. 컴팩션 이후라면 더더욱.

그래서 노랑·빨강 작업에는 별도의 읽기 전용 패스로 짧은 이해 메모(comprehension memo) 를 먼저 만듭니다.

진입점과 소유자
호출자와 기존 추상화
테스트와 운영 신호(production signals)
관련 히스토리와 열린 질문

모든 주장은 파일, 이슈, 소유권 기록, 대시보드 중 하나를 인용해야 합니다.

리서치 이후의 흐름도 컨텍스트를 끊어 가며 진행합니다.

계획은 깨끗한 컨텍스트에서 — 그럴듯한 접근법들이 어떤 파일을 건드리는지, 어떤 불변식을 지키는지, 어떻게 되돌릴 수 있는지 묻습니다.
경로는 사람이 고릅니다.
구현 중 지도가 틀렸음을 발견하면 멈춥니다.
리뷰는 새 컨텍스트에서 인수 조건부터 거꾸로 읽습니다. 깨끗한 리뷰어일수록 "테스트가 구현은 증명하지만 요구사항은 놓친" 경우를 잘 잡습니다.

지시가 하네스가 될 때

반복되는 지적은 모두 하네스에서 빠진 조각이다.

각 조각의 자리를 정확히 해 두면 유용합니다.

조각	역할
Instructions	저장소에 관한 특이한 사실을 기록
Skills	폭발 반경 확인, 스키마 변경 검증 같은 재사용 절차를 패키징
Plugins	소유권 카탈로그, 장애 아카이브, 대시보드에 대한 통제된 접근 제공

하네스는 에이전트를 둘러싼 작업 환경 전체 — 컨텍스트, 도구, 권한, 테스트, 로그, 복구 — 입니다. 팩토리는 믿을 만한 루프 여러 개를 스케줄링하고, 지속 상태를 유지하며, 새로운 케이스는 사람에게 돌려보냅니다.

실전 테스트는 에이전트가 틀렸을 때 무슨 일이 일어나는가입니다. 조용히 diff를 고쳐 주면 다음 세션이 같은 실수를 반복합니다. 같은 리뷰 코멘트가 다시 나타나면 lint 규칙, 훅, 타입, 테스트, 스킬로 옮기고, 산문은 기계로 강제할 수 없는 제약에만 남깁니다.

deny 규칙, 범위가 제한된 자격 증명, CI 체크는 기억할 필요가 없습니다. 시간이 지나면 하네스는 "팀이 두 번 비용을 치르지 않기로 결정한 실패들의 기록"이 됩니다. (Agent Skills 글에서 다룬 스킬 패키징이 바로 이 자리에 들어갑니다.)

무위험 작업부터 시작하기

무언가를 개선하게 두기 전에, 오늘의 동작부터 잠가라.

기존 코드베이스에 에이전트를 들이는 일은 다른 현대화 작업과 비슷합니다. "모놀리스를 Rust로 다시 쓰자"가 아니라 "먼저 어떻게 동작하는지 설명해 봐" 부터 시작합니다.

Characterization test는 레거시 코드를 안전하게 리팩터링하거나 바꾸기 위해 시스템의 실제 현재 동작을 문서화하는 자동화 테스트입니다. 핵심은 못생긴 부분까지 포함해 모듈이 오늘 하는 일을 고정하는 것입니다. 오래된 시스템에서는 그 못생긴 동작 위에서 비즈니스가 돌아가는 경우가 있고, 에이전트는 초록 테스트 뒤에서 그걸 기꺼이 "고쳐" 버립니다.

이 기법은 오래됐습니다. 문제가 오래됐기 때문입니다. Netflix는 GraphQL 전환 때 같은 아이디어를 운영 규모로 썼습니다 — 옛 경로와 새 경로에 트래픽을 리플레이·섀도잉하고, 페이로드를 diff하고, 일치할 때만 승격했습니다. 홈페이지급 화면에 정직한 단위 테스트가 없다면 이것이 승격 경로입니다. 추측하지 말고, 둘 다 돌려서 비교하라.

그리고 중요한 규칙이 하나 있습니다.

에이전트가 테스트를 통과시키는 쪽이라면, 같은 세션이 테스트의 유일한 작성자가 되게 하지 마세요. 동작은 별도 패스나 사람이 먼저 고정하고, 그다음에 에이전트가 작업합니다. 그렇지 않으면 "방금 발명한 구현을 인코딩한 초록 테스트"를 얻게 됩니다.

그다음은 기계적 변환입니다. 죽은 코드 목록, 사용되지 않는 export 목록 같은 것부터. 가장 까다롭고 털 많은 부분은 처음에 피합니다.

저자는 AOL 시절의 일화를 덧붙입니다. 쉬는 날 회사 근처 만화책 가게에 있다가 상사의 연락을 받았는데, AOL.com 홈페이지가 통째로 깨졌고 고칠 수 있는 JavaScript 전문가가 부족했다고 합니다. "홈페이지가 복잡해 봐야 얼마나 복잡하겠어"라고 생각하기 쉽지만, 수십 개 부서가 각자의 컴포넌트·기준·스크립트·A/B 테스트를 소유하고 있으면 모두의 세상을 깨뜨리지 않는 게 핵심이 됩니다. 결국 단위 테스트가 없는 부분은 사람이 직접 사용자 테스트를 해야 했습니다.

그게 여전히 일이다. 에이전트는 수십 개 부서 문제를 없애지 않는다. 그 문제에 맞서 변경을 시도하는 비용을 싸게 만들 뿐이다.

운영 트래픽만이 진짜로 이해하는 화면은 정의상 빨강 구역이고, 그 트래픽의 대역을 만들기 전까지는 저자가 쉬는 날 했던 사용자 테스트가 여전히 관문입니다.

완결된 단위로 마이그레이션하기

마이그레이션은 새 경로가 동작하고, 옛 의존성이 사라졌음이 증명될 때 완료다.

반쯤 끝난 마이그레이션은 에이전트를 특히 혼란스럽게 합니다. 검색하면 옛 방식이 40개 파일, 새 방식이 12개 파일, 그리고 둘 다 현행인 것처럼 보이게 하는 shim이 나옵니다. 에이전트는 서로 모순되는 선례를 보게 됩니다.

그래서 저자는 30개 파일을 변환해 두 패턴을 다 살려 두기보다, 라우트 하나를 옛 경로 삭제까지 끝까지 마치는 쪽을 택합니다. 삭제가 "나중 정리 티켓"이라면 그 마이그레이션 단위는 완료가 아닙니다.

교체본이 여전히 레거시 구현을 호출하는데도 테스트는 초록일 수 있습니다. SWE Refactor Bench는 이를 마이그레이션 "맹목(Blindness)" 이라 부르는데, 520번의 에이전트 실행 중 마이그레이션 감사·행동 테스트·독립 검증을 모두 통과한 건 28번뿐이었습니다.

코드모드(codemod)로 일상적 변경을 할 수 있다면, 에이전트는 코드모드를 작성하고 검사하는 데 쓰고, 에이전트에게는 예외 큐를 맡깁니다. Stripe의 마이그레이션이 유용한 사례인 이유가 바로 에이전트가 전혀 없었다는 점입니다 — 지속되는 산출물은 마이그레이션 기계 그 자체였습니다.

대형 마이그레이션에서 배운 것

사례	규모 · 기간	옮겨 올 만한 구조
Bun Zig → Rust	53.5만 줄, 약 50개 워크플로, 11일	생성 단위마다 적대적 리뷰어 2명 · 기존 테스트 전체가 머지 게이트 · 에이전트 실행 전 Zig→Rust 관용구 포팅 가이드
Anthropic 마이그레이션 프로세스	—	일회용 미니 마이그레이션으로 규칙집을 스트레스 테스트하고 결과는 버린 뒤 본 실행
VB6 → C# 통제 연구	—	단순 기능 92%, 복잡 기능 47% 행동 동등성 → 단위 크기가 레버
Stripe TypeScript	370만 줄, PR 하나	수개월의 코드모드 작업, 에이전트 없음
Google 대규모 변경	—	코드베이스가 커질수록 원자적 변경 단위는 작아진다
Spotify	월 650건+ 에이전트 PR 머지	수년 전 Backstage가 깔아 둔 레일 위에서
Asana	수년 묵은 Enzyme 백로그, 2주, 약 $12,000	좁은 기계적 마이그레이션 · 기존 테스트 묶음 · 모든 변경을 사람이 리뷰

Asana의 $12,000은 토큰 청구서일 뿐, 장부에 있던 5년치 인력 추정의 대체물이 아닙니다. 저자는 이를 벤더가 보고한 생성 비용으로 봐야지 통제된 절감 연구로 보면 안 된다고 선을 긋습니다.

회사 간에 옮겨지는 건 에이전트 주변의 구조다.

실제로 바뀐 것

에이전트는 그럴듯한 구현 여러 개를 시도하는 가격을 바꿨다. 그중 하나를 고르는 데 필요한 증거는 바꾸지 않았다.

올해 들어 자리 잡은 회사들이 에이전트로 대규모 재작성을 했다는 사례가 늘고 있습니다. 저자가 만난 CTO들 중에는 팀이 에이전트로 여러 언어·프레임워크로 재작성을 동시에 시도하게 허용하는 곳도 있습니다. 이제는 그게 싸게 가능하니까요.

Shopify는 Shop 소비자 앱을 React Native에서 네이티브 Swift·Kotlin으로 12주 만에, 작은 팀과 에이전트 게이트가 걸린 화면 크기의 체크포인트로 재구축했습니다. 하지만 훨씬 큰 머천트 앱은 여전히 브라운필드 문제입니다 — 수백 개 화면, 깊은 플랫폼 통합, 같은 게이트, 더 긴 시계.

예전에는 한 팀이 선택지 하나를 골라 올인했다면, 이제는 경쟁하는 선택지를 모두 구현하게 하고, 전부 단위 테스트로 검사하고, 전부 성능 프로파일링한 다음 결정할 수 있습니다. 경우에 따라 훨씬 싸게요. 팀 입장에서는 완전히 다른 게임입니다.

병렬화는 마지막에

생성되는 코드가 많아질수록 사람의 리뷰는 더 선별적이어야 한다. 사람의 소유권이 줄어서는 안 된다.

루프·목표·병렬화를 생각하기 전에, 무엇이 브라운필드 프로젝트를 성공으로 이끌지를 진지하게 고민해야 합니다. 소프트웨어 팩토리는 많은 변경을 동시에 돌릴 수 있지만, 저자는 한 단위가 믿을 만한 판정(judge), 복구 경로, 사람이 소화할 수 있는 리뷰 포맷을 갖춘 뒤에야 그 부분을 따라 하겠다고 말합니다.

병렬화는 이미 가진 병목을 곱합니다. 자동화된 검증은 검사된 변경 다섯 개를 처리할 수 있습니다. 하지만 모든 줄을 읽는 시니어 한 명은 대기열, 조각난 주의력, 그리고 결국 의례적인 승인을 얻게 됩니다.

자동 리뷰는 다음 순서로 앞에 내세우는 게 좋습니다.

의도(intent)
바뀐 불변식
테스트 결과
패리티 불일치
롤백 경로

전체 diff는 여전히 볼 수 있게 두되, 사람의 주의는 폭발 반경이 가장 크고 오라클(검증 기준)이 가장 약한 곳에 먼저 갑니다.

그리고 하나 더. 워크트리는 변경을 격리하지, 동작을 격리하지 않습니다. Git 메타데이터, 자격 증명, 로컬 서비스, 네트워크 접근을 공유할 수 있습니다. 신뢰된 작업이라면 그 트레이드오프를 받아들일 수 있지만, 신뢰할 수 없는 콘텐츠를 소비하는 무인 에이전트에는 더 강한 샌드박스와 범위가 제한된 자격 증명이 필요합니다.

에이전트는 모호함에 가격을 매긴다

생성한 줄 수는 코드베이스가 나아졌는지 말해 주지 않습니다. 저자가 추적하겠다는 지표는 이렇습니다.

범주	지표
일반	리드 타임 · 리뷰 시간(분) · 사람 개입 횟수 · 탈출 결함 · 롤백 · 오라클 불일치 · 남겨진 suppression
마이그레이션	남은 옛 import · 새 경로가 처리하는 트래픽 · 패리티 불일치 · 제거된 레거시 의존성

모든 트래픽이 여전히 옛 경로로 가는데 테스트만 초록이라면 그건 바쁜 척(busywork) 입니다.

에이전트는 모호함에 눈에 보이는 가격을 붙인다. 부족의 관습(tribal conventions)은 반복되는 리뷰 코멘트가 된다.

그 비용은 원래부터 있었습니다. 온보딩, 리뷰, 장애 복구 때 치르고 있었죠. 에이전트는 그중 더 많은 부분을 셀 수 있게 만들고, 덕분에 팀이 이미 가치 있다고 알던 유지보수 작업을 정당화할 더 강한 근거가 생깁니다.

다음번에 에이전트가 "홈페이지급" 화면을 고친다면, 저자는 수리 이상의 것을 남기길 원합니다 — 합성 사용자 여정(synthetic user journey), 소유권 기록, 회귀 테스트. 다음 엔지니어와 다음 에이전트가 무엇을 물려받는지도 중요하니까요.

마무리

이 글을 한 문장으로 줄이면 "에이전트의 성능보다 에이전트 주변의 구조가 결과를 결정한다" 입니다. Bun, Stripe, Asana, Shopify의 사례가 서로 다른 언어·규모·도구에서도 공유하는 건 기존 테스트라는 게이트, 좁은 단위, 사람의 리뷰, 그리고 에이전트가 돌기 전에 만들어 둔 가이드였습니다.

개인적으로 와닿은 지점은 두 가지입니다. 하나는 "테스트와 구현을 같은 세션이 쓰게 두지 말라" 는 규칙입니다. 에이전트가 만든 초록 테스트가 요구사항이 아니라 방금 만든 구현을 증명하는 장면은 실제로 자주 봅니다. 다른 하나는 "반쯤 끝난 마이그레이션은 에이전트에게 모순된 선례" 라는 관찰입니다. 사람에게도 혼란스럽던 이중 패턴이 에이전트에게는 그대로 학습 데이터가 됩니다.

브라운필드에 에이전트를 들이기 전 체크리스트:

✅ 사람이 초록·노랑·빨강 구역 지도를 그렸는가
✅ 구역 승격 조건(characterization test + 소유자 리뷰)이 정해져 있는가
✅ 지시 문서에는 코드가 말하지 못하는 것만 들어 있는가
✅ 노랑·빨강 작업에 출처가 달린 이해 메모를 먼저 남기는가
✅ 반복된 리뷰 코멘트를 lint·훅·타입·테스트·스킬로 옮기고 있는가
✅ 현재 동작을 잠그는 테스트를 에이전트와 다른 패스(또는 사람)가 작성하는가
✅ 마이그레이션 단위의 "완료"에 옛 의존성 삭제가 포함되는가
✅ 한 단위의 판정·복구·리뷰 포맷이 검증된 뒤에 병렬화하는가
✅ 생성 줄 수 대신 리드 타임·개입·롤백·남은 옛 import를 보고 있는가

참고 문서

Addy Osmani, Brownfield Agentic Engineering (2026-09-14)
Bun, Bun in Rust
Anthropic, AI code migration
Stripe, Migrating to TypeScript
Google, Software Engineering at Google — Large-Scale Changes
이전 글 — 에이전트가 실제로 따르는 스펙 쓰는 법 · Agentic Code Quality · Agent Skills