Jongya

Jonghyuk Park

[시리즈] 하네스 엔지니어링

AI 코딩 시대에 사람 엔지니어가 해야할 일은?

하네스 엔지니어링

1. 개념

AI 코딩에서 2026년 들어 본격적으로 정리되고 있는 개념으로, 코딩 에이전트를 덜 감독하면서도 AI 결과물에 대한 신뢰도를 높이기 위한 제어 방법이다.

하네스 엔지니어링이란, 단순히 AI에게 더 좋은 프롬프트를 쓰는 방벙이 아니다. AI 코딩 에이전트가 안정적으로 일할 수 있도록 실행 환경, 규칙, 검증, 도구 체계를 설계하는 일에 가깝다고 할 수 있으며, 사람 없이 AI만으로 코딩하는 방법론에 가깝다고 본다.

이 안에는 AI가 더 일을 잘 하게 하는 방법도 포함되어있지만, AI 코딩 시대에서 사람 엔지니어는 어떠한 역할을 해야하는가에 대한 고찰 또한 중요한 부분이라고 생각한다. 아마도 이를 가장 잘 표현한 한 마디는 이게 아닐까 싶다.

사람이 조정하고, 에이전트가 수행

하네스 엔지니어링에 대해 OpenAI 의 Codex 활용기를 중점적으로 살펴보면서 이에 대한 개념을 잡아보도록 하자.

2. 핵심 요소

하네스 엔지니어링의 “표면적인” 핵심은 바로 “AI가 코드를 만들기 전에 이해해야 할 것, 만들면서 지켜야 할 것, 만든 뒤 검증받아야 할 것”을 시스템으로 묶는 것이다. 이를 통해 AI 코딩 에이전트가 의도에 맞게 잘 작동하면서, 정해진 범위를 벗어나지 않고 작업할 수 있는 것이다.

(1) 명확한 작업 명세

AI에게 “이 기능 만들어줘”라는 지시문만 주는 것만으로는 부족하다. 목표, 범위, 성공 조건, 금지 조건을 함께 제공한다. 이렇게 명세를 분명히 하면 AI가 임의로 작업 범위를 확장하거나, 의도하지 않은 파일 수정이 일어날 가능성을 줄일 수 있다.

1
2
3
4

목표 : 회원가입 API에 이메일 인증 단계를 추가한다.
범위 : auth 모듈과 email service만 수정한다.
성공 조건 : 기존 로그인 테스트가 깨지지 않고, 신규 인증 테스트가 통과한다.
금지 조건 : DB 스키마는 승인 없이 변경하지 않는다.

(2) 컨텍스트 구조화

AI가 프로젝트를 이해할 수 있도록 코드베이스 설명서, 아키텍처 문서, 도메인 규칙, API 계약을 각 파일에 정리하고, 이를 AI가 잘 읽을 수 있도록 배치하거나 알려준다.

핵심은, 문서를 길게 쓰는 게 아니라, AI가 필요한 정보를 빠르게 찾을 수 있게 문서의 위치와 역할을 명확히 나눠 구조화하는 것이다.

1
2
3
4

ARCHITECTURE.md
DOMAIN_RULES.md
API_CONTRACT.md
CODING_RULED.md

(3) 실행 가능한 검증 루프

하네스 엔지니어링에서 가장 중요한 축 중 하나는, AI가 만든 결과물을 실행 가능한 방식으로 검증하는 것이다. AI가 코드를 작성한 뒤에는 반드시 아래와 같은 명령을 직접 실행하고 검증할 수 있어야 한다.

1
2
3
4

npm run lint
npm run typecheck
npm test
npm run test:e2e

개인적으로 이 검증 루프는 하네스 엔지니어링에서 매우 중요하다고 본다. 새로 추가한 테스트는 이번 작업이 의도대로 동작하는지 확인하는 도구이고, 기존 테스트는 이번 수정이 과거에 구현한 기능을 깨뜨리지 않았는지 확인하는 도구이기 때문이다.

(4) 테스트 하네스

테스트 하네스는 AI가 만든 코드가 실제 의도와 맞게 동작하는지 확인하는 안전망이다. 실행 가능한 검증 루프와 함께 작동하며, 보통 다음과 같은 테스트로 구성된다.

테스트 역할
단위 테스트 함수·모듈 단위 동작 검증
통합 테스트 DB, API, 외부 서비스 연동 검증
E2E 테스트 사용자 시나리오 검증
회귀 테스트 기존 기능이 깨지지 않았는지 검증

(5) 아키텍처 가드레일

아무리 코드를 잘 짠다고 하더라도, 기존 아키텍처를 무너뜨리면 장기적인 유지보수나 추가 서비스 개발에 애로사항이 꽃필 수 있다.

따라서 아키텍처에 대해 명시하고, 이를 무너뜨리지 않게끔 지시를 해야 한다. 또한 규칙을 적어두는 것을 넘어, 가능하다면 이 규칙에 대해서는 검증 루프를 두는 것이 안전하다.

1
2
3
4

domain 계층은 infrastructure 계층을 직접 import하지 않는다.
controller는 repository를 직접 호출하지 않는다.
공통 util에는 특정 서비스 로직을 넣지 않는다.
UI 컴포넌트는 API 클라이언트를 직접 호출하지 않는다.

(6) 권한과 변경 범위 제한

AI가 수정할 수 있는 영역과 건드리면 안 되는 영역을 명확히 나누는 것도 중요하다. 예를 들어 다음과 같이 작업 범위를 제한할 수 있다.

1
2
3
4
5
6
7
8
9

수정 가능:
- src/features/auth/**
- tests/auth/**

수정 금지:
- migrations/**
- billing/**
- infra/**
- package-lock.json

이런 제한은 AI가 불필요하게 큰 범위를 수정하거나, 민감한 영역을 건드리는 것을 막아주며, 특히 인증, 결제, 권한, 인프라, DB 마이그레이션처럼 리스크가 큰 영역은 별도의 승인 없이 수정하지 못하도록 명확히 지시하는 것이 좋다.

(7) 리뷰와 관측 가능성

AI가 작업을 끝낸 뒤에는 무엇을 바꿨는지 추적할 수 있어야 한다. 좋은 하네스는 AI에게 단순히 “완료했다”는 답변을 요구하지 않으며, 대신 다음과 같은 작업 결과를 요구한다.

1
2
3
4
5

변경 요약
수정한 파일 목록
테스트 결과
남은 리스크
사람이 확인해야 할 부분

1
2
3
4
5
6
7
8
9
10
11
12
13

# 예시
변경 요약:
- 이메일 인증 토큰 발급 로직 추가
- 회원가입 시 인증 메일 발송 추가
- 인증 완료 전 로그인 차단 테스트 추가

검증:
- npm run lint 통과
- npm test 통과
- auth e2e 테스트 통과

주의:
- 실제 SMTP 환경에서는 별도 검증 필요

이런 기록이 있어야 사람이 결과를 빠르게 검토할 수 있고, 나중에 작업 이력을 추적할 수도 있다.

또한 관측 가능성도 중요하다. AI가 코드만 수정하는 것이 아니라, 로그·메트릭·에러 메시지를 통해 실제 동작 상태를 확인할 수 있어야 하기 때문이다.

3. 이게 전부인가?

그렇다면 하네스 엔지니어링은 결국 명세를 잘 쓰고, 문서를 정리하고, 테스트를 붙이고, 검증 루프를 만드는 일일까?

물론 이것들은 중요할 것이다. 작업 명세, 컨텍스트 구조화, 테스트 하네스, 아키텍처 가드레일, 권한 제한, 리뷰와 관측 가능성은 모두 하네스 엔지니어링의 중요한 구성 요소라고 보인다.

하지만 이것들이 하네스 엔지니어링의 전부라고 보지는 않는다. 오히려 이 요소들은 비교적 표면에 드러나는 하네스 엔지니어링에 가깝다고 생각한다. 더 중요한 질문은 따로 있다.

1
2

사람 엔지니어가 직접 코딩하지 않는 환경에서,
사람 엔지니어는 무엇을 해야 하는가?

AI 코딩 에이전트가 코드를 작성하고, 테스트를 추가하고, 문서를 고치고, 리뷰 피드백에 대응하는 환경에서는 사람의 역할이 달라진다.

사람은 더 이상 모든 코드를 직접 생산하는 사람이 아니며, 대신 AI 에이전트가 안정적으로 일할 수 있도록 목표를 정의하고, 작업 환경을 만들고, 제약 조건을 설계하고, 검증 루프를 구축하고, 결과의 품질을 판단하는 사람이 된다. (나는 직접 코딩하는 걸 더 재밌어 하긴 하는데..)

즉, 하네스 엔지니어링의 핵심은 단순히 “AI에게 어떤 규칙을 줄 것인가” 보다, 더 근본적으로는 AI가 일하는 개발 환경에서 인간 엔지니어는 어떤 위치에 서야 하는가에 대한 질문이라고 생각한다.

그래서 다음 포스팅부터는 이 표면 너머의 하네스 엔지니어링을 살펴보려고 한다.

1
2
3
4

사람 엔지니어의 역할은 어떻게 바뀌는가?
AI 에이전트가 일하기 좋은 리포지터리는 어떻게 구성해야 하는가?
시스템, 스캐폴딩, 레버리지는 실제 프로젝트에서 어떻게 설계해야 하는가?
검증과 관측 가능성은 어느 수준까지 자동화해야 하는가?

이러한 질문들에 대해 찾아보고, 실험해보고, 직접 느껴보면서 AI 코딩 시대의 프로젝트 운영 방식을 살펴보겠다.

Reference

하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기

[시리즈] 하네스 엔지니어링

AI 코딩 시대에 사람 엔지니어가 해야할 일은?

Comments

You May Also Enjoy