AI로 풀어보는 AI-DLC v2: 브라운필드 (Brownfield)

본 기사의 위치— 본 기사는 awslabs/aidlc-workflows 리포지토리의 규범 규칙 및 이용 가이드를 소재로 하여, 필자가 AI를 활용해 읽고 정리한 해석입니다. AWS가 공식적으로 발표한 방법론이 아니며, 1차 자료의 번역이나 요약도 아닙니다.

시리즈— 본 기사는 AI로 풀어보는 AI-DLC v2 시리즈의 일부입니다.

참조한 버전— Claude Code 구현을 대상으로, 2026년 6월 시점의 v2.1.3 (커밋 c95070e, core/)을 참조하고 있습니다. Kiro・Codex 구현은 대상에서 제외되며, 기술 내용이 다를 수 있습니다. OSS 구현은 업데이트가 계속되고 있으므로, 최신 상태는 공식 리포지토리를 확인해 주시기 바랍니다.

브라운필드 (Brownfield)란, 이미 작동 중인 코드베이스를 기점으로 하는 공정입니다. AI-DLC v2는 완전히 새로운 신규 개발 (Greenfield)뿐만 아니라, 기존 시스템에 대한 기능 추가나 수정도 정면으로 다루며, 그 분기를 상태 파일의 Project Type이라는 하나의 필드로 결정합니다. 브라운필드로 판정되면, 기존 코드를 다시 이해하는 리버스 엔지니어링 (Reverse Engineering)과 작동 중인 것을 망가뜨리지 않고 개변하기 위한 세이프가드 (Safeguard)가 워크플로우에 자동으로 포함됩니다.

본 기사에서는 이 분기가 어떻게 결정되는지, 그리고 브라운필드일 때 무엇이 추가되는지를 리버스 엔지니어링과 세이프가드라는 두 가지 핵심 축을 따라 풀어봅니다.

신규 개발이라면 '제로에서 만들기'만 하면 됩니다. 반면, 기존 시스템에서는 '현재 있는 것을 올바르게 파악하기', '그것을 망가뜨리지 않기'라는 두 가지 작업이 먼저 추가됩니다. AI-DLC v2는 이 두 가지를 워크플로우의 분기로 포함하고 있습니다.

브라운필드에서 추가되는 작업은 다음 두 가지 핵심 축으로 집약됩니다.

• 기존 코드를 다시 이해하기 — 리버스 엔지니어링 (Reverse Engineering)
• 기존 코드를 망가뜨리지 않고 개변하기 — 6개의 세이프가드 (Safeguard)

둘 다 신규 개발에는 존재하지 않는 기존 시스템 특유의 전제 조건입니다.

브라운필드 여부는 사람이 선언하는 것이 아니라 결정론적으로 판정됩니다. 열쇠를 쥐고 있는 것은 상태 파일의 Project Type 필드로, Greenfield 또는 Brownfield 중 하나가 들어갑니다. 이 하나의 필드가 이후의 모든 분기를 결정합니다. 결정 방식은 3단계입니다.

파일 스캔으로 판정합니다. 초기화 페이즈의 workspace-detection 스테이지가 파일 시스템을 스캔하여 분류합니다. 소스 코드 파일 (.ts / .py / .java …), 앱의 프레임워크 설정, 앱 의존성을 포함하는 패키지 매니페스트 (non-dev 의존성이 있는 package.json, requirements.txt …) 중 어느 하나라도 있으면 브라운필드, 모두 없으면 그린필드입니다. README, .gitignore, LICENSE, CI 템플릿, 하네스 디렉토리 (.claude/ 등), 워크스페이스 기록 트리 aidlc/는 있어도 브라운필드로 판정하지 않습니다. 판정 기준은 '앱의 코드가 있는가'라는 단 한 점에 집중됩니다.

판정 결과로 라우팅합니다. state-init 스테이지가 판정을 받아 첫 번째 구상 스테이지를 분기시킵니다. 브라운필드라면 reverse-engineering부터 시작하고, 그린필드라면 reverse-engineering을 스킵하고 requirements-analysis부터 시작합니다.

엔진이 소비를 좁힙니다. 하류 스테이지가 읽어들이는 결과물 (consumes)에는 conditional_on: brownfield라는 표식이 붙은 것이 있습니다. 엔진은 상태 파일의 Project Type과 일치하는 표식이 있는 엔트리만 가져옵니다. 즉, '브라운필드일 때만 기존 이해 결과물을 읽는다'는 점이 프롬프트가 아닌 결정론적인 도구로 보장됩니다.

이 조건 분기는 '프로젝트 타입에 따라 전환되는' 것으로, 안건의 무게에 따라 공정을 넣고 빼는 스코프 (Scope)와는 별개의 축인 제어입니다. 스코프에 의한 공정 선택은 별도 기사인 「스코프」에서 다룹니다.

브라운필드에서 가장 먼저 실행되는 것이 reverse-engineering (리버스 엔지니어링) 스테이지입니다. 기존 코드를 읽어 들여, '이 시스템은 무엇이며 어떻게 만들어졌는가'를 결과물로서 작성합니다.

이 스테이지의 정의 파일 도입부는 실행 조건을 execution: CONDITIONAL로 선언하며, 그 조건을 "브라운필드(Brownfield)일 때만 실행하고, 최신성을 위해 매번 재실행하며, 그린필드(Greenfield)에서는 스킵한다"라고 기록하고 있습니다. 한 번 만든 이해 문서를 캐시로 재사용하지 않고, 실행할 때마다 새로 만드는 것이 이 스테이지의 특징입니다. 기존 코드는 사람의 손에 의해 계속 변하기 때문에, 오래된 이해를 바탕으로 설계를 진행하면 판단을 그르칠 수 있기 때문입니다. 주 담당자는 데벨로퍼(Developer), 보조는 아키텍트(Architect)로, 코드를 읽는 역할과 설계로 번역하는 역할의 2단계 구조로 되어 있습니다.

데벨로퍼가 코드베이스(Codebase) 전체를 스캔하면, 그 결과를 아키텍트가 **9개의 결과물(Artifacts)**로 통합합니다.

#	결과물	내용
1	business-overview	업무 도메인 · 목적 · 주요 기능
...

9번째인 timestamp는 내용에 대한 지식이 아니라 "이 이해가 어느 시점의 것인가"를 기록하는 메타 결과물(Meta-artifact)로, 앞서 언급한 "매번 재실행하여 최신성을 유지한다"는 운용을 뒷받침하는 내부 장치입니다.

만드는 것은 9개이지만, 하류(Downstream)로 흐르는 것은 8개입니다. timestamp는 메타 정보이므로 하류 스테이지는 소비하지 않으며, 후속되는 practices-discovery 등이 받는 것은 "reverse-engineering의 8개 결과물"입니다. 하류 스테이지는 이를 conditional_on: brownfield로 받아, 브라운필드일 때만 기존 이해를 바탕으로 한 요구사항 · 설계로 진행합니다.

또한, 이 9개의 결과물은 다른 결과물과 달리, intent(작업 기록 단위)를 가로질러 공유되는 공간 레벨의 codekb(코드 지식 베이스, aidlc/spaces/<space>/codekb/<repo>/)에 거주합니다. 결과물 레이아웃의 유일한 예외에 해당하는 이 취급은 별도 기사 「결과물의 흐름」에서 다룹니다. reverse-engineering이 공정 카탈로그 상의 어디에 위치하는지는 별도 기사 「공정과 에이전트」에서 다룹니다.

기존 시스템에 대한 개정은 "작동 중인 것을 망가뜨리는" 리스크와 맞닿아 있습니다. AI-DLC v2는 기존 코드나 기반을 변경하는 스테이지에 대해 **6개의 세이프가드(Safeguard)**를 정의하고 있습니다. 권위 있는 정의는 brownfield.md의 Safeguard Matrix에 있으며, 각 스테이지 본문과 지식(Knowledge)이 운용 측면의 상세 내용을 보완합니다.

세이프가드	수행 내용	적용 단계
Blast Radius Analysis	영향을 받는 파일/부품과 그 하류 의존성을 특정한다	코드 생성 전 (code-generation, 3.5)
...

이 매트릭스는 6개의 세이프가드를 공정 타임라인 상에 배치하고 있습니다. 이해 단계(2.1)에서 영향 범위를 문서화하고, 코드 생성 전(3.5)에 폭발 반경과 테스트 기준을 확인하며, 생성 후(3.6)에 회귀(Regression)가 없는지 확인하고, 배포 전(4.3)에 롤백(Rollback) 절차를 준비합니다. 변경 전 · 도중 · 후 · 배포 전 각각에 확인 지점(Checkpoint)을 두는 설계입니다.

6개 중 2개는 매트릭스에 절차 템플릿까지 첨부되어 있습니다.

Blast Radius Analysis(폭발 반경 분석)는 기존 코드를 변경하기 전에 변경될 파일을 모두 열거하고, 각 파일의 imports/consumers · 테스트 파일 · 설정 참조를 조사합니다. 영향을 low(고립된 변경) / medium(2~3개의 의존처로 파급) / high(횡단적)로 분류하여, 착수 전에 영향 요약(Summary)을 사람에게 제시합니다.

Test Baseline Protocol(테스트 기준 프로토콜)은 어떤 변경보다도 먼저 테스트 스위트(Test Suite) 전체를 실행하여 총수 · 성공 · 실패 · 스킵 · 커버리지(Coverage)를 기록합니다. 코드 생성 후에 재실행하여, 새로운 실패를 이번 변경으로 인한 회귀로 간주하고, 다음 단계로 넘어가기 전에 수정합니다.

이 두 가지는 "변경 전의 스냅샷(Snapshot)"을 찍는 세이프가드입니다. Blast Radius가 공간적인 영향 범위를, Test Baseline이 시간적인 전후 비교를 기록하여, 개정의 영향을 "어디까지 퍼지는가"와 "망가뜨리지 않았는가"라는 양면에서 확인합니다. 참고로 Blast Radius라는 관점은 설계 리뷰어의 핵심 질문에도 등장하지만, 그 상세 내용은 별도 기사 「리뷰어」에서 다룹니다.

브라운필드에서 AI-DLC v2가 더하는 작업은 결국 이 한 세트로 집약됩니다.

신규 개발이 「제로에서부터 만들기」인 것과 달리, 기존 시스템에서는 재이해 (①)와 파괴하지 않는 개변 (②)이 전 단계에 들어갑니다. Project Type이 브라운필드 (Brownfield)로 판정되는 순간, 이 두 기둥이 AI-DLC v2의 브라운필드 대응으로서 자동으로 공정에 포함됩니다.

파일	내용
core/knowledge/aidlc-shared/brownfield.md	6가지 세이프가드 (Safeguard)의 권위 있는 정의 (Safeguard Matrix · Blast Radius 템플릿 · Test Baseline 프로토콜)
aidlc-common/stages/inception/reverse-engineering.md	리버스 엔지니어링 (Reverse Engineering) 스테이지. CONDITIONAL 실행 조건 · lead/support · 9가지 산출물
core/knowledge/aidlc-developer-agent/re-artifacts.md	RE 산출물에 대한 지식 (Knowledge). 9가지 산출물의 정의와 스캔 / 통합 템플릿
core/knowledge/aidlc-shared/state-template.md	상태 (State) 파일의 템플릿. Project Type (Greenfield/Brownfield) 필드
aidlc-common/stages/initialization/workspace-detection.md	greenfield / brownfield의 결정론적인 판정 기준
aidlc-common/stages/initialization/state-init.md	프로젝트 타입에 따른 첫 구상 스테이지의 라우팅 (Routing)
aidlc-common/stages/inception/practices-discovery.md	하류 공정이 RE의 8가지 산출물을 conditional_on: brownfield로 소비하는 예시
aidlc-common/stages/construction/code-generation.md	브라운필드는 현장에서의 개변 (in-place) · 중복 복사 금지
core/agents/aidlc-architecture-reviewer-agent.md	Blast Radius가 설계 리뷰어의 핵심 질문에도 나타나는 점
CHANGELOG.md	엔진이 conditional_on: brownfield/greenfield를 Project Type으로 필터링

이전 기사: 워킹 스켈레톤 (Walking Skeleton)

다음 기사: 승인 게이트 (Approval Gate)

목차: AI로 풀어보는 AI-DLC v2