AI 에이전트 시대의 새로운 개발법, 하네스 엔지니어링
하네스 엔지니어링(Harness Engineering)은 사람이 모든 코드를 직접 작성하는 방식에서 벗어나, AI 에이전트가 요구사항 분석, 코드 작성, 테스트, 수정, 배포 준비까지 수행할 수 있도록 작업 환경과 피드백 루프를 설계하는 방식입니다.
이 글에서 다루는 내용
- 하네스 엔지니어링의 핵심 정의
- AI 에이전트만으로 프로덕션 수준 소프트웨어를 만들기 위한 조건
- 하네스를 사용하는 핵심 목적
- 실제 작업 방식과 단계별 프로세스
- 적용 사례와 개발자 관점의 주의사항, 꿀팁
하네스 엔지니어링(Harness Engineering)이란?
하네스 엔지니어링(Harness Engineering)은 AI 에이전트가 소프트웨어를 안정적으로 개발할 수 있도록 요구사항, 코드베이스, 테스트, 실행 환경, 도구, 검증 기준, 배포 파이프라인을 하나의 작업 장치처럼 묶어 설계하는 개발 방식입니다.
여기서 말하는 하네스는 단순히 테스트 하네스만 의미하지 않습니다. AI가 코드를 만들고, 실행하고, 실패 로그를 읽고, 다시 수정하고, 최종적으로 사람이 승인할 수 있는 수준까지 끌어올리도록 돕는 AI 개발용 운영 프레임워크에 가깝습니다.
쉽게 말하면?
기존 개발자가 직접 코드를 작성했다면, 하네스 엔지니어링에서는 개발자가 코딩 자체보다 AI 에이전트가 일할 수 있는 환경을 설계합니다.
- AI에게 무엇을 만들지 명확히 알려주는 요구사항 문서
- AI가 안전하게 수정할 수 있는 코드 구조
- AI가 스스로 품질을 확인할 수 있는 자동 테스트
- 잘못된 방향으로 가지 않도록 막는 가드레일
- 실패 로그를 바탕으로 반복 수정하는 피드백 루프
왜 지금 하네스 엔지니어링이 중요한가?
최근 AI 코딩 도구는 단순 자동완성을 넘어 AI 에이전트 기반 개발으로 이동하고 있습니다. Cursor, GitHub Copilot Workspace, Devin, OpenAI 기반 에이전트, Claude Code 스타일의 도구들은 단일 파일 수정이 아니라 이슈를 이해하고 여러 파일을 수정하며 테스트까지 실행하는 방향으로 발전하고 있습니다.
문제는 AI가 똑똑해졌다고 해서 바로 프로덕션 품질의 코드를 안정적으로 만들 수 있는 것은 아니라는 점입니다. AI에게 자유롭게 “게시판 만들어줘”, “결제 기능 붙여줘”라고만 지시하면 아키텍처가 흔들리거나, 보안 정책을 놓치거나, 테스트가 부족한 코드가 나올 가능성이 큽니다.
따라서 핵심은 AI 자체보다 AI가 실패를 감지하고 수정할 수 있는 개발 하네스를 얼마나 잘 설계하느냐입니다.
하네스를 사용하는 핵심 목적
1. AI의 작업 범위 통제
AI가 아무 파일이나 수정하지 않도록 모듈, 디렉터리, 규칙, 금지 영역을 정합니다.
2. 반복 가능한 품질 확보
테스트, 린트, 타입 체크, 빌드 검증을 자동화해 AI가 만든 코드를 객관적으로 평가합니다.
3. 프로덕션 수준 완성도
기능 구현뿐 아니라 예외 처리, 로깅, 보안, 성능, 배포 가능성을 함께 검증합니다.
4. 사람의 역할 재정의
개발자는 코드를 한 줄씩 치는 사람이 아니라, AI 작업을 설계하고 리뷰하는 감독자가 됩니다.
하네스 엔지니어링의 주요 구성 요소
1. 명확한 작업 명세서
AI 에이전트에게 가장 먼저 필요한 것은 정확한 작업 명세서입니다. 사람 개발자도 요구사항이 모호하면 헤매듯이 AI도 목표가 불분명하면 그럴듯하지만 엉뚱한 코드를 작성합니다.
좋은 작업 명세서에는 다음이 포함되어야 합니다.
- 기능의 목적
- 사용자 시나리오
- 입력값과 출력값
- 정상 케이스와 예외 케이스
- 변경 가능한 파일 범위
- 금지해야 할 구현 방식
- 완료 기준
2. 자동 테스트와 검증 루프
AI 에이전트 개발에서 테스트는 선택이 아니라 필수입니다. AI가 만든 코드가 맞는지 사람이 일일이 눈으로 확인하면 자동화의 장점이 사라집니다.
하네스 엔지니어링에서는 AI가 코드를 작성한 뒤 다음과 같은 검증을 자동으로 돌리게 만듭니다.
- 유닛 테스트
- 통합 테스트
- E2E 테스트
- 타입 체크
- 린트 검사
- 빌드 테스트
- 보안 취약점 스캔
3. 실행 가능한 개발 환경
AI가 제대로 일하려면 로컬 또는 컨테이너 환경에서 코드를 실행할 수 있어야 합니다. Docker, Dev Container, CI 환경을 이용하면 AI 에이전트가 동일한 환경에서 실패를 재현하고 수정할 수 있습니다.
특히 프로덕션 수준 소프트웨어를 목표로 한다면 “내 컴퓨터에서는 되는데요” 문제를 줄이는 것이 중요합니다. 하네스는 AI와 사람 모두가 같은 명령어로 같은 결과를 얻도록 만들어야 합니다.
4. 에이전트에게 제공할 도구 세트
AI 에이전트는 단순 채팅창보다 도구를 가질 때 훨씬 강력해집니다. 하네스 엔지니어링에서는 에이전트가 다음 도구를 사용할 수 있도록 설계합니다.
- 파일 읽기 및 수정 도구
- 터미널 실행 도구
- 테스트 실행 도구
- 검색 도구
- 문서 조회 도구
- Git diff 확인 도구
- PR 생성 또는 변경 요약 도구
5. 가드레일과 승인 절차
AI가 모든 것을 자동으로 처리한다고 해도, 중요한 변경에는 반드시 가드레일이 필요합니다. 특히 결제, 인증, 개인정보, 인프라, 데이터베이스 마이그레이션은 사람이 최종 승인하는 구조가 안전합니다.
- 특정 디렉터리 수정 금지
- 환경 변수와 시크릿 접근 제한
- DB 스키마 변경 시 승인 필요
- 외부 API 추가 시 보안 검토 필요
- 배포 전 사람 리뷰 필수
하네스 엔지니어링 작업 방식 상세 분석
1단계: 문제를 작은 작업 단위로 쪼갠다
AI에게 너무 큰 목표를 한 번에 맡기면 품질이 떨어질 가능성이 높습니다. “쇼핑몰 전체를 만들어줘”보다 “장바구니에 상품을 추가하는 API와 테스트를 작성해줘”처럼 작고 검증 가능한 단위로 나누는 것이 좋습니다.
- 기능을 사용자 흐름 기준으로 분해합니다.
- 각 기능을 API, UI, DB, 테스트 단위로 나눕니다.
- 하나의 작업이 30분에서 2시간 내에 검증 가능하도록 제한합니다.
- 각 작업마다 완료 조건을 명확히 둡니다.
2단계: AI 에이전트에게 컨텍스트를 제공한다
AI는 프로젝트의 모든 암묵적 규칙을 알지 못합니다. 따라서 README, 아키텍처 문서, 코딩 컨벤션, API 명세, 테스트 전략을 함께 제공해야 합니다.
이때 중요한 것은 정보를 많이 주는 것이 아니라 작업에 필요한 컨텍스트를 정확히 주는 것입니다. 관련 없는 문서를 과하게 넣으면 오히려 AI가 방향을 잃습니다.
3단계: 테스트를 먼저 만들거나 완료 기준을 고정한다
하네스 엔지니어링에서 가장 효과적인 방식 중 하나는 테스트 우선 AI 개발입니다. 사람이 테스트를 먼저 작성하거나, AI에게 먼저 테스트 케이스를 만들게 한 뒤 그 테스트를 통과하도록 구현을 맡기는 방식입니다.
이 방식은 AI가 “그럴듯한 코드”가 아니라 “검증 가능한 코드”를 만들도록 유도합니다.
4단계: AI가 구현하고 직접 검증하게 한다
AI 에이전트가 코드를 수정한 뒤에는 반드시 스스로 검증 명령을 실행해야 합니다. 실패가 발생하면 로그를 읽고 원인을 추론한 뒤 다시 수정합니다.
- AI가 코드 변경
- 테스트 실행
- 실패 로그 분석
- 수정
- 재검증
- 변경 내용 요약
이 루프가 잘 만들어져 있으면 사람이 직접 코드를 치지 않아도 AI만으로 상당히 높은 수준의 결과물을 얻을 수 있습니다.
5단계: 사람은 코드 작성자가 아니라 리뷰어로 개입한다
AI 에이전트만으로 프로덕션 수준 소프트웨어를 완성한다는 말은 사람이 아예 관여하지 않는다는 뜻이 아닙니다. 사람의 역할이 코딩에서 설계, 검증, 리뷰, 승인으로 이동한다는 의미에 가깝습니다.
특히 다음 항목은 사람이 반드시 확인하는 것이 좋습니다.
- 비즈니스 요구사항을 정확히 반영했는가?
- 보안상 위험한 구현은 없는가?
- 예외 상황 처리가 충분한가?
- 기존 아키텍처와 일관성이 있는가?
- 장기 유지보수가 가능한 구조인가?
하네스 엔지니어링을 적용한 실제 사례
사례 1. 백오피스 CRUD 기능 자동 생성
많은 기업 내부 시스템에는 관리자 페이지, 목록 조회, 상세 조회, 생성, 수정, 삭제 같은 반복적인 CRUD 기능이 많습니다. 이런 영역은 하네스 엔지니어링과 AI 에이전트의 궁합이 좋습니다.
| 항목 | 적용 방식 |
|---|---|
| 목표 | 상품 카테고리 관리 페이지 자동 구현 |
| 하네스 구성 | API 스펙, UI 컴포넌트 규칙, 테스트 코드, 린트 규칙 제공 |
| AI 작업 | 목록 UI, 생성 폼, 수정 폼, 삭제 확인 모달, API 연동 구현 |
| 검증 | 컴포넌트 테스트, E2E 테스트, 빌드 테스트 실행 |
반복 패턴이 명확한 기능은 AI가 빠르게 구현할 수 있으며, 사람이 리뷰해야 할 부분도 비교적 제한적입니다.
사례 2. 레거시 코드 리팩터링
하네스가 잘 갖춰져 있으면 AI 에이전트를 이용해 레거시 코드를 안전하게 리팩터링할 수 있습니다. 단, 이때는 기존 동작을 보장하는 테스트가 반드시 필요합니다.
- 복잡한 함수 분리
- 중복 코드 제거
- 타입 안정성 강화
- 오래된 라이브러리 사용 방식 개선
- 테스트 커버리지 보강
리팩터링에서는 “기능을 바꾸지 말 것”이라는 제약을 강하게 줘야 합니다. AI가 선의로 구조를 크게 바꾸다가 기존 비즈니스 로직을 깨뜨릴 수 있기 때문입니다.
사례 3. API 테스트 자동 보강
기존 코드베이스에 테스트가 부족할 때 AI 에이전트를 활용해 테스트를 보강할 수 있습니다. 이 경우 AI에게 구현 변경을 금지하고, 테스트 파일만 수정하게 하는 방식이 효과적입니다.
사례 4. SaaS MVP 기능 개발
초기 스타트업이나 1인 개발자의 경우, AI 에이전트와 하네스를 활용하면 MVP 개발 속도를 크게 높일 수 있습니다. 예를 들어 로그인, 구독 결제, 대시보드, 이메일 알림, 설정 페이지처럼 정형화된 기능은 AI가 상당 부분 구현할 수 있습니다.
다만 결제, 인증, 권한 처리처럼 민감한 영역은 AI 구현 결과를 그대로 배포하지 말고 반드시 수동 리뷰와 보안 검증을 거쳐야 합니다.
AI 에이전트만으로 프로덕션 수준 소프트웨어가 가능한 조건
결론부터 말하면, 조건이 갖춰진다면 AI 에이전트만으로도 프로덕션에 가까운 소프트웨어를 완성할 수 있습니다. 하지만 그 조건은 “좋은 프롬프트 하나”가 아니라 다음과 같은 엔지니어링 체계입니다.
- 요구사항이 명확해야 합니다.
- 코드베이스 구조가 일관적이어야 합니다.
- 자동 테스트가 충분해야 합니다.
- 실행 환경이 재현 가능해야 합니다.
- AI가 실패를 보고 수정할 수 있어야 합니다.
- 보안과 배포에는 사람 승인 절차가 있어야 합니다.
- 작업 단위가 작고 명확해야 합니다.
개발자가 실제 적용할 때 알아야 할 주의사항
1. AI에게 전체 권한을 한 번에 주지 말기
AI 에이전트에게 전체 레포지토리 수정 권한을 주면 의도하지 않은 변경이 발생할 수 있습니다. 처음에는 특정 디렉터리, 특정 파일, 특정 기능으로 범위를 제한하는 것이 좋습니다.
2. 테스트 없는 자동화는 자동 사고에 가깝다
하네스 엔지니어링의 품질은 테스트 품질에 크게 의존합니다. 테스트가 부실하면 AI가 잘못된 구현을 해도 통과해버립니다.
3. 보안 영역은 반드시 수동 리뷰하기
인증, 인가, 결제, 개인정보, 파일 업로드, 관리자 권한, SQL 쿼리 등은 AI 코드만 믿고 배포하면 위험합니다. 특히 환경 변수, 토큰, 시크릿 키가 코드에 노출되지 않았는지 확인해야 합니다.
4. AI가 만든 문서도 검증하기
AI는 코드뿐 아니라 README, API 문서, 변경 요약도 그럴듯하게 작성합니다. 하지만 실제 구현과 문서가 맞지 않는 경우가 있으므로 문서 역시 검증 대상에 포함해야 합니다.
하네스 엔지니어링 실전 꿀팁
개발자 관점에서 바로 적용 가능한 팁
- 작업 지시서 템플릿을 만들어두면 매번 프롬프트를 새로 쓰지 않아도 됩니다.
- AI에게 구현 전에 먼저 작업 계획을 출력하게 하세요.
- 큰 변경 전에는 반드시 Git 브랜치를 따로 만드세요.
- AI가 수정한 뒤에는 Git diff를 기준으로 리뷰하세요.
- 테스트 실패 로그를 AI에게 그대로 주면 수정 정확도가 올라갑니다.
- 코드 스타일은 ESLint, Prettier, TypeScript 같은 도구로 강제하세요.
- 민감한 파일은 수정 금지 목록에 넣으세요.
- AI에게 “추측하지 말고 모르면 질문하라”고 명시하세요.
저는 AI 에이전트를 쓸 때 처음부터 코드를 짜게 하기보다, 먼저 “이 작업을 어떻게 나눌지 계획을 세워줘”라고 시켜요. 그러면 엉뚱한 파일을 건드리는 일이 줄고, 제가 중간에 방향을 잡아주기도 훨씬 편해요. 특히 작은 PR 단위로 끊어가면 실패해도 되돌리기 쉬워서 마음이 훨씬 편하더라고요.
하네스 엔지니어링 추천 작업 템플릿
아래 템플릿은 AI 에이전트에게 작업을 맡길 때 그대로 변형해서 사용할 수 있습니다.
하네스 엔지니어링과 기존 개발 방식의 차이
| 구분 | 기존 개발 방식 | 하네스 엔지니어링 방식 |
|---|---|---|
| 개발자 역할 | 직접 코드 작성 | AI 작업 환경 설계, 리뷰, 승인 |
| AI 활용 | 코드 자동완성, 질문 답변 | 작업 수행 에이전트 |
| 품질 관리 | 사람 중심 리뷰 | 테스트, 린트, 빌드 기반 자동 검증 |
| 작업 단위 | 개발자 판단에 따라 유동적 | 작고 명확한 태스크 단위 |
| 생산성 | 개발자 숙련도에 크게 의존 | 하네스 품질과 자동화 수준에 의존 |
어떤 프로젝트에 하네스 엔지니어링이 잘 맞을까?
모든 프로젝트가 동일하게 적합한 것은 아닙니다. 하네스 엔지니어링은 특히 다음 프로젝트에서 효과가 큽니다.
- CRUD가 많은 관리자 페이지
- 테스트 코드가 어느 정도 있는 웹 서비스
- 반복 패턴이 많은 SaaS 기능
- API 명세가 명확한 백엔드 프로젝트
- 컴포넌트 규칙이 정리된 프론트엔드 프로젝트
- 리팩터링 대상이 명확한 레거시 코드
- MVP를 빠르게 검증해야 하는 스타트업 프로젝트
반대로 조심해야 할 프로젝트
- 도메인 규칙이 문서화되어 있지 않은 프로젝트
- 테스트가 거의 없는 대규모 레거시 시스템
- 금융, 의료, 법률처럼 오류 비용이 큰 시스템
- 보안 요구사항이 매우 높은 인증 인프라
- 실시간 제어, 임베디드, 안전 필수 시스템
이런 프로젝트에서 AI 에이전트를 활용하려면 먼저 테스트와 문서화, 샌드박스 환경을 갖추는 것이 우선입니다.
정리: 하네스 엔지니어링은 AI 시대의 개발 운영법이다
하네스 엔지니어링(Harness Engineering)은 AI에게 코드를 “잘 짜달라”고 부탁하는 수준을 넘어, AI가 실제 개발자처럼 일하고 실패를 고치며 프로덕션 수준에 가까운 결과물을 만들 수 있도록 환경을 설계하는 방식입니다.
앞으로 개발자의 경쟁력은 단순히 코드를 얼마나 빠르게 치느냐보다, AI 에이전트가 안정적으로 일할 수 있는 하네스를 얼마나 잘 구축하느냐로 이동할 가능성이 큽니다.
핵심은 명확합니다. 요구사항을 작게 나누고, 테스트를 만들고, 실행 환경을 고정하고, AI에게 반복 검증 루프를 제공하세요. 그러면 사람은 모든 코드를 직접 작성하지 않아도, AI 에이전트를 통해 훨씬 빠르게 제품 수준의 소프트웨어를 완성할 수 있습니다.
댓글
댓글 쓰기