안녕하세요. KT AX플랫폼본부에서 프론트엔드 개발을 담당하고 있는 김수현입니다.

앞선 #1 , #2 편을 통해 지금까지 사장이지 프론트엔드를 어떻게 구축해왔는지 아키텍처 관점에서 이야기해왔다면, 이번에는 앞으로 어떻게 개발해 나갈 것인가에 대해 이야기해 보려 합니다.

기존 프론트엔드 개발 흐름은

1. 기획서, 디자인 가이드를 바탕으로 UI 레이아웃을 잡은 뒤, 

2. 백엔드 API 규격에 맞춰 타입 정의 후 클라이언트 모듈을 개발하고,

3. 마지막으로 UI에 API 응답 값을 매핑하는 통합 작업을 수행합니다.

이 과정은 대부분 개발자가 직접 요구사항을 해석하고 구현해야 하기 때문에, 기획서를 잘못 이해하거나 디자인과 구현 간의 불일치가 발생하는 등 ‘휴먼 에러’가 개입될 여지가 항상 존재했습니다. 또한 요구사항 분석, UI 구현, API 연동이 하나의 흐름으로 이어져 있어 어느 단계에서 문제가 발생했는지 추적하기 어렵고, 수정 시점이 늦어질수록 재작업 비용도 함께 증가했습니다.

반복적인 구현 작업을 줄이고 개발 생산성을 높이기 위해 Cursor, GitHub Copilot과 같은 LLM 기반 코드 에이전트도 적극적으로 사용하였습니다. 실제로 단순한 코드 생성・수정이나 반복 작업에서는 생산성이 크게 향상되는 것을 확인하였습니다. 하지만 작업 범위가 커질수록 한계가 분명하게 드러났습니다.

LLM 기반의 코드 에이전트는 프로젝트 구조와 코딩 컨벤션을 지속적으로 반영하기 어려웠고, 프롬프트와 대화 이력에 따라 코드 품질이 달라지는 문제가 있었습니다. 결과적으로 개발자는 생성된 코드를 다시 검토하고 수정하는 과정이 반복되면서, 안정적인 개발 프로세스를 구축하는 데 한계가 있었습니다.

이를 보완하기 위해 Web개발팀은 반복되는 패턴의 작업을 독립적인 AI 에이전트로 분리하고, 각 에이전트가 프로젝트의 구조와 컨벤션을 항상 동일한 기준으로 참조하며 역할을 수행할 수 있도록 하는 하네스 엔지니어링(Harness Engineering) 방식을 도입했습니다. 이를 통해 프롬프트 작성 방식이나 대화 이력에 따라 결과가 달라지는 문제를 줄이고, 프로젝트 전반에서 예측 가능한 품질의 결과를 생성할 수 있는 개발 환경을 구축할 수 있었습니다.

하네스 엔지니어링의 목표는 에이전트가 반복적인 구현 작업을 담당하고, 개발자는 통합과 비즈니스 로직 검증에 집중할 수 있는 개발 환경을 만드는 것이었습니다. 이를 위해 가장 먼저 고민한 것은 “어떻게 하면 개발자의 최소 개입만으로도 AI가 신뢰할 수 있는 결과물을 생성하도록 만들 수 있을까?” 였습니다.

이를 위해 TDD(Test-Driven Development) 방법론을 개발 워크플로우에 적용했습니다.

TDD는 실제 구현보다 먼저 테스트 코드를 작성하고, 해당 테스트를 통과하는 최소한의 코드를 구현한 뒤 지속적으로 리팩터링 하는 개발 방식입니다. 이러한 접근은 구현보다 요구사항을 명확히 정의한다는 점에서 AI 기반 개발에도 적합하다고 판단했습니다.

초기에는 TDD 개념에 맞춰 가장 먼저 요구사항을 테스트 코드로 정의하고 이후 Layout, API 개발을 진행하는 순서로 워크플로우를 설계했습니다.

하지만 실제 적용 과정에서 예상치 못한 문제가 발생했습니다. 기획서 하나만 보고 테스트 코드를 생성하다 보니 에이전트는 구현에 필요한 세부 사항까지 추론해야 했고 그만큼 많은 자유가 허용되고 있었습니다.

예를 들어 Layout 구현 이전에 생성된 테스트 코드는 컴포넌트의 data-testid를 AI가 추론하여 작성합니다. 하지만 실제 구현에서 다른 data-testid가 사용되면 테스트 코드와 구현 간의 불일치가 발생하여, 이를 맞추기 위한 수정 작업이 반복되었습니다.

또한 프론트엔드의 통합 테스트는 특정 UI 상태를 재현하기 위해 API Mocking이 필요한 경우가 많습니다. 하지만 어떤 API를 Mocking해야 하는지에 대한 기준이 없는 상태에서는 AI가 존재하지 않는 API를 만들어 성공을 가정하거나, 사용자 인터랙션으로 검증해야 하는 항목을 API 응답으로 대체하는 등 신뢰하기 어려운 테스트 코드를 생성했습니다.

결국 문제의 원인은 AI가 구현에 필요한 기준과 제약 없이 테스트를 먼저 생성하고 있다는 점이었습니다.

이를 해결하기 위해 워크플로우의 순서를 변경했습니다. 먼저 API 규격서를 기반으로 API Client와 Mock Server를 생성한 뒤, 이를 활용해 테스트 코드를 작성하도록 변경했습니다. 그리고 Layout 개발 시에는 테스트 코드에서 정의한 data-testid를 그대로 사용하도록 명시하여 테스트와 구현이 동일한 기준을 따르도록 했습니다.

기존의 TDD 순서를 그대로 적용하기보다, 각 단계가 이전 단계의 산출물을 활용하는 워크플로우로 재구성했습니다. 이를 통해 AI가 새롭게 추론해야 하는 영역을 최소화하고, 단계별 기준이 자연스럽게 다음 단계로 전달되는 개발 흐름을 만들었습니다.

1. API 규격서를 기반으로 API Client와 Mock Server를 생성합니다.

2. 앞 단계에서 생성된 API Client와 Mock Server를 참고하여 요구사항을 검증하는 E2E 테스트 코드를 작성합니다.

3. 디자인 가이드를 기반으로 UI 레이아웃을 구현합니다. 이때, 테스트 코드에서 정의한 data-testid를 컴포넌트에 매핑합니다.

4. UI와 API를 통합한 뒤, E2E 검증을 통해 요구사항 충족 여부를 최종 확인합니다.

앞서 살펴본 워크플로우를 실제 개발 프로세스에 적용하기 위해 총 세 가지 하네스를 구축했습니다. 설계 과정에서 가장 중요하게 고려한 점은 각 에이전트가 불필요한 추론에 의지하지 않고, 이전 단계의 결과를 입력으로 사용하는 구조를 만드는 것이었습니다.

이를 위해 개발 과정을 API, TDD, Layout의 세 단계로 분리하고, 각 단계를 담당하는 하네스를 독립적으로 구성했습니다.

➊ API 하네스: API Client와 Mock Server 구축

➋ TDD 하네스: 요구사항 기반의 테스트 코드 생성 및 검증

➌ Layout 하네스: UI 레이아웃 개발

세 하네스는 각각 담당하는 역할과 입출력은 다르지만, 모두 동일한 에이전트 아키텍처를 기반으로 동작합니다. 하나의 에이전트가 계획부터 구현, 검증까지 모두 수행하도록 구성할 수도 있었지만, 각 단계를 독립적인 역할로 분리하여 책임을 명확히 하고 실패 원인을 쉽게 추적하여 필요한 단계만 다시 수행할 수 있도록 설계했습니다.

사용자의 입력이 들어오면 오케스트레이터(Orchestrator)가 전체 작업을 관리하며 각 에이전트를 순차적으로 실행합니다.

(1) 먼저 Bootstrap Agent에서 MCP 서버 연결, 프로젝트 구조 분석, 개발 대상 확인 등 이후 작업 수행에 필요한 실행 환경을 준비합니다.

(2) 이후 Plan Agent를 호출하여 개발 및 테스트에 필요한 계획을 markdown 형태로 작성합니다. 

(3) 이 계획서를 바탕으로 Dev Agent는 실제 코드 생성 및 수정 작업을 수행합니다.

(4) 개발이 모두 끝난 뒤, QA Agent는 생성된 산출물에 대해 테스트와 품질 검증을 수행하여 요구사항 충족 여부와 개선이 필요한 항목을 선별합니다.

(5) 마지막으로 Eval Agent는 QA 결과를 바탕으로 테스트 실패의 원인을 분석합니다. 실패 원인이 계획 수립(Plan), 구현(Dev), 검증(QA) 중 어느 단계에서 발생했는지 판단한 뒤, 해당 단계부터 다시 수행하도록 결정합니다.

오케스트레이터는 eval의 최종 결정을 바탕으로 최대 3회의 루프를 돌리거나 프로세스를 종료시킵니다.

예를 들어 API Client 생성은 정상적으로 완료되었지만 Unit Test가 실패한 경우에는 Plan이 아닌 Dev Agent부터 재실행합니다. 반면 API 규격 자체를 잘못 해석한 경우에는 Plan 단계부터 다시 수행합니다. 이처럼 실패 원인에 따라 필요한 단계만 재실행함으로써 불필요한 작업을 최소화했습니다.

모든 하네스는 Bootstrap → Plan → Dev → QA → Eval의 동일한 실행 구조를 공유합니다. Bootstrap은 실행 환경을 준비하고, Plan은 작업 계획을 수립하며, Dev는 실제 산출물을 생성합니다. 이후 QA는 하네스별 검증 기준에 따라 결과를 검증하고, Eval은 그 결과를 분석하여 실패 원인을 분류하고 어느 단계부터 다시 수행할지 결정합니다. 공통 실행 구조는 동일하지만, 하네스마다 사용하는 입력 데이터와 검증 기준은 목적에 맞게 다르게 구성했습니다.

먼저, API 하네스는 이후 개발 단계에서 사용할 API Client와 Mock Server를 생성합니다.

API 규격서가 입력으로 들어오면 이를 표준화된 OpenAPI 형식의 Spec 문서로 변환한 뒤, 이를 기반으로 API Client와 테스트에 필요한 Mock Server, 그리고 더미 데이터를 생성합니다. API 규격서를 먼저 OpenAPI 형식으로 표준화함으로써 문서 형식에 관계없이 동일한 생성 파이프라인을 사용할 수 있도록 설계했습니다.

기존에는 개발자가 수많은 Endpoint에 대한 API Client를 직접 작성하고 응답 객체의 타입을 하나씩 정의해야 했습니다. 이러한 작업은 구현 자체보다 반복적인 코드 작성의 비중이 높았지만, API 하네스를 도입하면서 대부분 자동화할 수 있었습니다.

API 하네스가 생성한 결과물은 이후 TDD 하네스의 입력으로 사용됩니다. 이를 통해 테스트 단계에서는 API를 다시 해석하거나 추론하지 않고, 이미 정의된 API를 기준으로 테스트를 생성할 수 있습니다.

두 번째로, TDD 하네스는 API 하네스에서 생성한 API Client와 Mock Server를 기반으로 요구사항을 검증 가능한 테스트 코드로 정의하는 역할을 수행합니다.

TDD 하네스는 개발 전 테스트 코드를 생성하는 계약(Contract) 모드와, 개발 후 요구사항 충족 여부를 확인하는 검증(Validation) 모드로 구성됩니다. 기획서가 입력으로 들어오면 요구사항을 바탕으로 테스트 코드를 작성하고 에이전트가 직접 실행까지 수행합니다. 계약 모드에서는 구현 전에 요구사항을 테스트 코드로 명확히 정의하고, 검증 모드에서는 구현 이후 동일한 기준으로 요구사항 충족 여부를 확인합니다.

이 단계에서 생성된 테스트는 단순한 검증 코드에 그치지 않습니다. 특히 테스트에서 정의한 data-testid는 Layout 하네스와 공유되어 테스트와 구현이 동일한 식별 기준을 사용할 수 있도록 합니다.

기존에도 팀 내부에서 E2E 테스트 도입을 검토했지만, 테스트 코드 작성 비용이 높아 모든 도메인에 적용하기는 어려웠습니다. 하지만 AI 에이전트가 기획서를 기반으로 테스트 코드를 자동 생성하면서 테스트 작성 비용이 크게 감소했고, 결과적으로 모든 도메인에서 E2E 테스트를 활용할 수 있는 기반을 마련할 수 있었습니다.

마지막으로 Layout 하네스는 디자인 가이드와 프로젝트 규칙을 바탕으로 화면을 구현하는 단계입니다.

디자인 가이드를 입력받으면 에이전트는 각 화면의 상태(State)를 분석하여 페이지를 구성하고, 이에 맞는 React 컴포넌트를 생성합니다. 이 과정에서 TDD 하네스에서 정의한 data-testid가 그대로 반영되어 테스트와 구현이 동일한 기준을 따르게 됩니다.

소스코드를 생성할 때는 단순한 JSX 출력에 머무르지 않고, 프로젝트의 폴더 구조, 코드 컨벤션, 공통 컴포넌트, 디자인 시스템을 함께 반영하도록 규칙을 정의했습니다. 그 결과 생성된 코드가 기존 프로젝트 구조와 충돌하지 않고 자연스럽게 통합될 수 있도록 했습니다.

이에 따라 개발자는 초기 레이아웃을 직접 구현하는 대신 생성된 초안을 검토하고 필요한 비즈니스 로직과 예외 처리에 집중하게 되었으며, 코드 리뷰 역시 구조보다는 실제 기능 구현에 초점을 맞추게 되었습니다.

하네스 엔지니어링을 개발 프로세스에 적용한 결과, 반복적인 개발 작업을 자동화하는 수준을 넘어 개발 전 과정을 체계적으로 관리할 수 있는 기반이 마련되었습니다. 그 결과 개발 생산성 향상, 단계별 품질 검증, 실행 이력의 체계적 관리라는 세 가지 측면에서 개선 효과를 확인할 수 있었습니다.

 

기존에는 개발자가 디자인 가이드, 기획서, API 문서를 직접 분석해 화면 구조와 컴포넌트 구성, 테스트 범위를 스스로 판단해야 했습니다. 구현 작업 외에도 요구사항 해석, 프로젝트 구조 탐색, 공통 UI 확인 등에 많은 시간이 소요되어 화면 하나를 구현하기 위한 준비 작업의 비중이 상당했습니다.

하네스 도입 이후에는 Plan Agent가 요구사항과 디자인 기준을 구조화하고, Dev Agent가 프로젝트 컨벤션에 맞는 초안을 생성하게 되었습니다. 이에 따라 개발자는 빈 화면에서부터 구현을 시작하는 대신, 생성된 초안을 검토하고 보완하는 방식으로 개발을 진행하게 되었습니다.

그 결과 단순 레이아웃 기준 화면 초안 생성 시간은 내부 적용 기준 페이지당 약 1일에서 1~2시간 수준으로 단축되었으며, 개발자는 반복적인 구현보다 비즈니스 로직과 예외 처리에 더욱 집중할 수 있게 되었습니다.

 

기존 개발 방식에서는 요구사항 분석 단계에서 발생한 휴먼 에러가 개발 과정이나 QA 단계에서 뒤늦게 발견되는 경우가 많았습니다. 수정 시점이 늦어질수록 원인 추적이 어려워지고, 재작업 비용도 함께 증가하는 문제가 있었습니다.

이를 개선하기 위해 API 하네스에서는 Unit Test, Layout 하네스에서는 Visual Regression Test를 수행하는 검증 절차를 배치했습니다. 각 단계는 독립적으로 검증을 수행하기 때문에 문제가 발생하더라도 Plan, Dev, QA 중 어느 단계에서 실패했는지 즉시 식별할 수 있으며, 불필요한 재작업 범위를 최소화할 수 있습니다.

이처럼 테스트는 단순히 개발 이후의 확인 절차가 아니라, 개발 초기에 결함을 차단하고 전 과정의 품질을 지속적으로 보장하는 역할을 수행합니다.

 

하네스 도입 이전에는 요구사항 해석 과정, 구현 판단 근거, 테스트 결과 등이 개인의 기억이나 채팅 기록에 흩어져 있어 재사용하거나 추적하기 어려웠습니다.

하네스에서는 각 실행 과정마다 입력값(input.json), 출력값(output.json), 개발 계획(plan.md), 테스트 결과서 등의 실행 기록을 파일 형태로 저장합니다. 이를 통해 어떤 입력을 기반으로 계획이 생성되었는지, 어떤 구현 결과가 만들어졌는지, 어떤 테스트를 통과했는지 모든 실행 이력을 일관되게 추적할 수 있게 되었습니다.

또한 이후 동일한 기능을 수정하거나 다른 도메인에 적용할 때도 기존 실행 기록을 기반으로 작업을 이어갈 수 있어, 하네스는 단순한 자동화 도구가 아니라 재사용 가능한 개발 운영 자산으로 활용될 수 있습니다.

하네스를 적용한 이후 개발자의 역할은 반복적인 구현 작업에서 벗어나 설계와 의사결정을 담당하는 역할로 변화하고 있습니다. AI 에이전트는 초안 생성과 반복적인 검증을 수행하고, 개발자는 비즈니스 로직 설계와 예외 처리, 그리고 최종 의사결정에 집중하게 되었습니다.

결과적으로 하네스는 단순히 개발 속도를 높이는 도구를 넘어, 개발 생산성과 품질을 높이고 실행 이력을 체계적으로 관리할 수 있는 개발 프로세스의 기반이 되었습니다.

현재까지는 Layout, API, TDD 하네스를 구축해 각 개발 단계를 독립적으로 자동화했습니다. 그러나 UI와 API를 연결하고 실제 서비스의 비즈니스 로직을 구현하는 과정은 여전히 개발자가 직접 수행하고 있습니다. 즉, 개별 하네스는 자동화되었지만, 서비스를 완성하기 위한 통합(Integration) 단계는 아직 자동화되지 않은 상태입니다.

이러한 공백을 해소하기 위해 현재 Integration 하네스를 구축하는 과정에 있습니다. Integration 하네스는 생성된 UI와 API Client를 기반으로 실제 서비스 로직을 통합하고 필요한 비즈니스 로직, 상태 관리, 데이터 흐름을 구현하여 실제 동작 가능한 기능 단위까지 개발 범위를 확장하고자 합니다.

궁극적으로 하네스 엔지니어링은 단순한 코드 생성 도구가 아니라, 프로젝트의 규칙과 개발 프로세스를 기반으로 AI가 일관되고 예측 가능한 방식으로 협업할 수 있도록 만드는 개발 방법론입니다. 앞으로 Integration 하네스를 포함한 통합 개발 파이프라인을 완성하여, 요구사항부터 구현·검증까지 하나의 오케스트레이션 아래에서 수행하는 End-to-End AI 개발 환경을 구축하는 것을 목표로 합니다.