최근 AI를 활용해 코드를 작성하는 것은 더 이상 특별한 일이 아니다.

간단한 컴포넌트나 API 정도는 요구사항만 전달해도 꽤 괜찮은 결과를 만들어낸다.

하지만 실제 프로젝트에서 AI에게

"이 화면 구현해줘"

라고 요청하면 이야기가 달라진다.

화면 자체는 만들어주지만 프로젝트에서 이미 사용하고 있는 공통 컴포넌트를 사용하지 않거나, 비슷한 기능을 다시 구현하거나, 기존 코드 스타일과 전혀 다른 구조를 만들어내기도 한다.

결국 AI가 코드를 작성하는 속도는 빨라졌지만, 프로젝트에 맞는 코드를 작성하도록 만드는 것은 또 다른 문제였다.

이 문제를 해결하기 위해 프론트엔드 구조를 먼저 개선했고, 그 위에 AI가 작업할 수 있는 Harness를 구축했다.

이번 글에서는 프론트엔드 자동화를 준비하면서 프로젝트 구조를 어떻게 바꾸었고, 그 위에 Harness Engineering을 적용했을 때 실제 구현 결과가 어떻게 달라졌는지 정리해보려고 한다.

---

1. 시작은 프론트엔드 자동화였다

기존 프로젝트는 하나의 풀스택 프로젝트 안에서 백엔드와 프론트엔드를 함께 관리하고 있었다.

특히 프론트엔드는 과거부터 기능이 추가되면서 여러 구현 방식이 섞여 있었다.

Backend
 └─ Spring

Frontend
 ├─ FreeMarker
 ├─ jQuery
 └─ Vue.js

사람이 개발할 때는 기존 코드를 찾아가며 어느 정도 맞춰서 개발할 수 있었다.

하지만 AI를 이용해 화면 구현을 자동화하려고 하니 문제가 크게 드러났다.

예를 들어 같은 검색 영역을 구현하더라도 화면마다 구조가 다르고, 버튼이나 테이블도 서로 다른 방식으로 구현되어 있다면 AI 입장에서는 무엇이 이 프로젝트의 표준인지 판단하기 어렵다.

결국 AI가 기존 코드를 참고하기보다는 새로운 코드를 만들어버리기 쉬운 환경이었다.

그래서 Harness를 만들기 전에 먼저 AI가 이해하기 쉬운 프로젝트 구조를 만드는 작업부터 시작했다.

---

2. 먼저 프론트엔드 구조를 바꿨다

가장 먼저 풀스택 프로젝트에서 프론트엔드와 백엔드를 분리했다.

Before

Fullstack Project
 ├─ Backend
 ├─ FreeMarker
 ├─ jQuery
 └─ Vue.js

After

Backend Project
 └─ API

Frontend Project
 ├─ Pages
 ├─ Components
 ├─ Common Components
 └─ Storybook

하지만 단순히 프로젝트를 분리하는 것만으로는 부족했다.

프론트엔드에서도 반복해서 사용되는 UI를 공통 컴포넌트로 만들었다.

예를 들면 다음과 같은 요소들이다.

• 검색 조건
• 데이터 그리드
• 버튼
• 액션 메뉴
• 콘텐츠 패널
• 상태 표시
• Excel 다운로드
• 페이지 레이아웃

이렇게 반복되는 UI를 공통 컴포넌트로 만들면 개발자 입장에서도 중복 구현을 줄일 수 있지만, AI 자동화 관점에서는 더 큰 장점이 생긴다.

AI에게

검색 영역 만들어줘.

라고 하는 것보다,

프로젝트에서 사용하는 SearchControls와 SearchControlField를 활용해서
검색 영역을 구성해줘.

라고 할 수 있기 때문이다.

즉, AI가 직접 UI 구조를 만들어내는 것이 아니라 프로젝트에서 정의한 부품을 조립하도록 만드는 것이다.

---

3. 공통 컴포넌트만 만들어서는 부족했다

여기까지 진행하면 한 가지 의문이 생긴다.

공통 컴포넌트를 잘 만들어두면 AI가 알아서 찾아서 사용하지 않을까?

실제로는 그렇지 않았다.

프로젝트 안에 좋은 컴포넌트가 아무리 많아도 AI가 그 존재를 모르면 사용할 수 없다.

알고 있더라도 다음과 같은 판단이 필요하다.

이 화면에서는 어떤 컴포넌트를 사용해야 하는가?

기존 컴포넌트를 그대로 사용할 수 있는가?

기능이 조금 부족하면 수정해야 하는가?

새로운 컴포넌트를 만들어도 되는가?

Figma가 없다면 화면을 바로 구현해야 하는가?

구현 후 무엇을 검증해야 하는가?

결국 필요한 것은 단순한 코드 생성 프롬프트가 아니었다.

AI가 프로젝트 안에서 어떻게 행동해야 하는지 작업 경로 자체를 정의할 필요가 있었다.

여기서 Harness Engineering을 적용하게 되었다.

---

4. Harness Engineering이란?

내가 이번 프로젝트에서 적용한 Harness는 AI에게 단순히 코딩 규칙만 전달하는 것이 아니다.

AI가 작업을 시작해서 완료할 때까지 따라야 하는 실행 경로를 만드는 것에 가깝다.

구조를 단순화하면 다음과 같다.

요청
 ↓
작업 규칙 확인
 ↓
작업 유형 판단
 ↓
기존 구현 탐색
 ↓
공통 컴포넌트 탐색
 ↓
구현 방법 결정
 ↓
코드 구현
 ↓
영향 범위 확인
 ↓
검증 및 보고

이를 위해 크게 네 가지 요소를 연결했다.

AGENTS.md
    +
Skill
    +
기존 프로젝트 자산
    +
검증 절차

AGENTS.md

프로젝트에서 AI가 지켜야 할 가장 기본적인 규칙을 정의한다.

예를 들면 다음과 같다.

- 작업 범위
- Figma를 확인하는 조건
- 구현 규칙
- 코드 위치
- 공통 컴포넌트 사용 원칙
- 검증 방법
- 결과 보고 방식

Skill

AGENTS.md가 전체적인 규칙을 담당한다면 Skill은 특정 작업을 수행하는 절차를 담당한다.

예를 들면,

신규 화면 구현
기존 화면 수정
코드 리뷰
커밋
배포 요청

과 같은 작업마다 서로 다른 실행 절차를 정의할 수 있다.

기존 프로젝트 자산

AI가 새로운 코드를 마음대로 생성하지 않도록 프로젝트 안의 기존 자산을 구현의 근거로 사용한다.

Storybook
유사 화면
공통 컴포넌트
Theme
기존 코드

검증

마지막으로 구현만 하고 끝내지 않는다.

변경된 코드가 다른 화면에 영향을 줄 가능성이 있는지 확인하고, 실제 수행한 검증과 수행하지 않은 검증도 구분하도록 했다.

결국 내가 생각한 Harness의 핵심은 다음과 같다.

좋은 코드를 생성하도록 프롬프트를 잘 쓰는 것이 아니라, 좋은 코드를 만들 수밖에 없는 작업 경로를 만드는 것

---

5. 핵심 규칙: Reuse → Extend → Create

Harness에서 가장 중요하게 잡은 원칙 중 하나가 컴포넌트 생성 순서다.

Reuse
  ↓
Extend
  ↓
Create

AI는 새로운 화면을 구현할 때 바로 새로운 컴포넌트를 만들면 안 된다.

1. Reuse

가장 먼저 기존 컴포넌트를 확인한다.

Storybook
    ↓
Props / Variant / Slot 확인
    ↓
유사 화면 확인
    ↓
기존 컴포넌트 조합으로 구현 가능한지 판단

가능하다면 기존 컴포넌트를 그대로 사용한다.

---

2. Extend

기존 컴포넌트를 그대로 사용할 수 없다면 새로운 컴포넌트를 만드는 대신 기존 컴포넌트를 확장할 수 있는지 먼저 판단한다.

이때는 반드시 기존 사용처에 영향을 주지 않는지도 확인한다.

---

3. Create

Reuse와 Extend로 해결할 수 없을 때만 새로운 컴포넌트를 만든다.

즉,

새로운 컴포넌트 생성은 가장 마지막 선택지다.

이 규칙만으로도 AI가 화면마다 비슷한 컴포넌트를 새롭게 생성하는 문제를 상당히 줄일 수 있었다.

---

6. 작업 종류에 따라 실행 경로도 다르게 만들었다

모든 프론트엔드 작업을 동일한 방식으로 처리하는 것도 적절하지 않았다.

그래서 작업을 크게 세 가지 흐름으로 나눴다.

---

Figma가 있는 신규 화면

사용자가 Figma 화면 구현을 요청했다면 다음 순서로 진행한다.

요구사항 확인
 ↓
Figma 확인
 ↓
Storybook 확인
 ↓
유사 구현 탐색
 ↓
공통 UI 적용
 ↓
구현
 ↓
영향 범위 확인

중요한 것은 항상 Figma를 확인하는 것이 아니라 사용자가 Figma 기반 구현을 요청한 경우에만 확인하도록 한 것이다.

Figma가 있다는 이유만으로 모든 작업에서 디자인을 조회하게 하면 오히려 불필요한 탐색이 발생할 수 있기 때문이다.

---

Figma가 없는 신규 화면

Figma가 없는 경우에는 조금 다른 흐름을 사용한다.

요구사항
 ↓
Storybook / 유사 화면 확인
 ↓
Mockup 생성
 ↓
사용자 확인
 ↓
승인
 ↓
구현

여기서는 바로 코드를 작성하지 않는다.

먼저 기존 프로젝트 디자인을 참고해서 화면의 구조와 배치를 Mockup으로 제시한다.

Mockup 단계에서는 실제 API나 기능을 구현하지 않는다.

사용자가 화면을 확인한 뒤 명시적으로 승인하면 그때 실제 구현을 시작한다.

이렇게 하면 AI가 요구사항을 잘못 해석한 상태로 화면 전체를 구현하고 다시 수정하는 비용을 줄일 수 있다.

---

기존 화면 수정

기존 화면 수정은 더욱 보수적으로 접근하도록 했다.

현재 동작 확인
 ↓
사용 중인 컴포넌트 확인
 ↓
최소 범위 수정
 ↓
사용처 영향 확인

기존 화면 수정에서 중요한 것은 새로운 구조를 만드는 것이 아니라 현재 구조를 최대한 유지하는 것이다.

---

7. 같은 Figma를 구현시켜봤다

Harness가 실제로 어떤 차이를 만드는지 확인하기 위해 간단한 비교를 진행했다.

조건은 최대한 동일하게 맞췄다.

입력 Figma 동일
요청 문구 동일
API 구현 없음
화면만 구현

프롬프트 역시 동일하게 사용했다.

해당 피그마 화면 구현 진행해줘.
API 없이 화면부터 구현.

차이는 하나였다.

Harness 적용 전
vs
Harness 적용 후

[이미지 6 - 동일 Figma / 동일 Prompt 비교]

---

8. 결과

1. 코드 작성량이 크게 줄었다

Harness 적용 전에는 추가된 코드가 약 1,651줄이었다.

Harness 적용 후에는 318줄이었다.

1,651 lines
     ↓
318 lines

약 80.7% 감소했다.

물론 코드가 적다고 무조건 좋은 것은 아니다.

하지만 이번 사례에서는 이유가 분명했다.

적용 전에는 화면에 필요한 UI를 새롭게 구현하는 부분이 많았고, 적용 후에는 프로젝트에 존재하던 공통 컴포넌트를 조합해서 화면을 만들었기 때문이다.

---

2. 공통 UI 재사용이 0개에서 10개로 증가했다

Harness 적용 전에는 기존 공통 UI를 사용하지 않았다.

반면 적용 후에는 총 10개의 공통 컴포넌트를 활용했다.

ActionButtons
ActionMenuButton
ContentPanel
DataGrid
DataGridToolBar
EventStatus
ExcelDownloadButton
NormalPage
SearchControls
SearchControlField

즉, AI에게 단순히 화면을 그리게 한 것이 아니라

기존 프로젝트의 컴포넌트를 조립해서 화면을 만들도록 작업 방식을 변경한 것

이다.

---

3. 수정 범위도 줄었다

파일 수만 보면 다음과 같다.

구분	Harness 적용 전	Harness 적용 후
전체 수정 파일	60개	3개
실제 코드 파일	4개	3개

여기서 주의할 점이 있다.

적용 전 60개에는 Figma에서 가져온 정적 에셋 파일도 포함되어 있었다.

따라서

60개 → 3개

만 보고 코드 수정량이 95% 감소했다고 해석하면 안 된다.

실제 코드 파일을 기준으로 하면

4개 → 3개

다.

이 부분은 Harness 효과를 측정할 때도 중요했다.

단순히 숫자를 크게 만드는 것보다 어떤 파일이 왜 변경됐는지를 같이 보는 것이 필요하다.

---

4. 구현 시간도 줄었다

최종 집계 기준 작업 시간은 다음과 같았다.

Harness 적용 전
26분 45초

Harness 적용 후
15분 28초

약 42.2% 단축됐다.

정리하면 이번 테스트 결과는 다음과 같다.

측정 항목	Harness 적용 전	Harness 적용 후
총 수정 파일	60개 (코드 4개)	3개
추가 코드	1,651줄	318줄
공통 UI 재사용	0개	10개
작업 시간	26분 45초	15분 28초

물론 이것은 하나의 화면을 대상으로 진행한 단일 사례다.

따라서 모든 화면에서 코드가 80% 감소하고 작업 시간이 40% 단축된다고 일반화할 수는 없다.

하지만 최소한 Harness를 적용했을 때 AI가 프로젝트 구조를 활용하는 방식이 크게 달라졌다는 것은 확인할 수 있었다.

---

9. Prompt Engineering과 무엇이 달랐나

처음에는 AI에게 상세한 프롬프트를 주면 해결할 수 있다고 생각했다.

예를 들어 이런 식이다.

기존 컴포넌트를 최대한 사용하고
코드를 깔끔하게 작성하고
현재 프로젝트 코드 스타일을 따르고
중복 컴포넌트를 만들지 말고...

하지만 작업할 때마다 이런 내용을 반복해서 입력하는 방식은 한계가 있다.

그리고 규칙이 많아질수록 사용자가 빠뜨리는 것도 생긴다.

Harness를 만들고 난 뒤에는 사용자가 모든 규칙을 기억할 필요가 없어졌다.

사용자는 단순히

이 Figma 화면 구현해줘.

라고 요청한다.

그러면 Harness가 내부적으로

Figma 확인
     ↓
Storybook 탐색
     ↓
유사 화면 탐색
     ↓
Reuse
     ↓
Extend
     ↓
Create
     ↓
구현
     ↓
영향 범위 확인

이라는 경로를 만들게 된다.

개인적으로 이 부분이 Prompt Engineering과 Harness Engineering의 가장 큰 차이라고 느꼈다.

---

10. 결국 AI 자동화 전에 프로젝트 구조가 먼저였다

이번 작업을 하면서 가장 크게 느낀 부분이 있다.

코드가 AI가 작업하기 어려운 구조라면 Harness만 잘 만든다고 해결되지 않는다.

만약 프로젝트 안에 같은 버튼이 20개 방식으로 구현되어 있고, 검색 영역도 화면마다 다르고, 재사용 가능한 컴포넌트가 없다면 AI에게

기존 구조를 재사용해.

라고 해도 선택할 수 있는 기준 자체가 없다.

그래서 이번에는 순서를 반대로 잡았다.

Frontend / Backend 분리
        ↓
Frontend 구조 정리
        ↓
공통 컴포넌트화
        ↓
Storybook 구축
        ↓
AI가 탐색할 기준 생성
        ↓
Harness 구축
        ↓
AI 자동화

결국 Harness Engineering의 기반은 정리된 코드베이스였다.

---

11. 마무리

AI Coding Agent의 성능은 계속 좋아지고 있다.

앞으로는 단순히 코드를 얼마나 잘 생성하는지를 비교하는 것보다

AI가 우리 프로젝트에서 얼마나 일관된 방식으로 작업하도록 만들 수 있는가

가 더 중요해질 것이라고 생각한다.

이번 Harness에서는 AI에게 자유롭게 코드를 작성하도록 하는 대신,

무엇을 먼저 확인해야 하는지

기존 코드를 어디까지 재사용해야 하는지

언제 새로운 컴포넌트를 만들어도 되는지

Figma가 없으면 어떤 절차를 거쳐야 하는지

구현 이후 무엇을 검증해야 하는지

리뷰와 Git 작업은 어떤 방식으로 해야 하는지

를 프로젝트의 작업 절차로 정의했다.

그 결과 하나의 사례이기는 하지만,

추가 코드
1,651줄 → 318줄

공통 UI 재사용
0개 → 10개

작업 시간
26분 45초 → 15분 28초

라는 차이를 확인할 수 있었다.

하지만 내가 생각하는 가장 중요한 변화는 숫자가 아니다.

AI가 새로운 코드를 계속 만들어내는 개발자에서, 기존 프로젝트의 구조와 자산을 활용하는 개발자로 바뀌었다는 점이다.

결국 AI 개발 자동화에서 중요한 것은

AI에게 일을 잘 시키는 프롬프트가 아니라
AI가 일을 잘할 수밖에 없는 환경을 만드는 것

이라고 생각한다.

그리고 그 환경을 만드는 작업이 바로 이번에 적용한 Harness Engineering이었다.