Haeyul Blog

1. 하네스 엔지니어링이란

7 min read

하네스 엔지니어링은 왜 등장했는가?

최신 AI Agent는 많은 데이터와 기술력의 발전으로 단순 한 줄 짜리 프롬프트로 함수 1개 고쳐주는 것이 아닌 하나의 issue를 해결하거나 작업의 전반적인 내용을 지휘하는 등의 작업이 가능해졌다. 이에 따라서 AI Agent들이 지시에 따르지 않고 파일을 없애거나, 아키텍처를 뒤집는 등과 같은 행위를 하기 시작했습니다.

위 문제를 해결하기 위해 등장한 기법이 바로 “하네스 엔지니어링”입니다.

하네스 엔지니어링은, AI 코딩 에이전트가 올바르게 동작하도록 환경을 설계하는 기술이다.

Ai 엔지니어링 세 가지 시대

1 : 프롬프트

"이 함수에서 overflow 버그를 고쳐줘"

초기 AI 시대에는 하나의 입력을 바탕으로 하나의 출력을 이끌어 내는 형태로 작동하고 있었습니다.

Ai는 대화가 끝나면 아무것도 기억하지 못한다는 것이 문제였습니다.

이는 개발자의 설명 능력이 중요한 시대라고 사람들이 주로 말하고 있습니다.

2: 컨텍스트

[파일] + "해당 코드는 인가 인증 코드인데 보안성에서 문제가 생길수 있는 부분을 찾아서 고쳐줘."

컨텍스트 시대에서 부터는 파일과 배경을 함께 제공하여 AI의 출력 물의 질을 높이는 형태로 나아갔습니다. 하지만 이때에도 세션이 끝나면 사라진다는 문제점이 존재하였습니다.

3: 에이전트

"TDD를 활용해서 인가 & 인증 코드를 추가해줘. 그리고 테스트를 성공하면 PR을 올려줘."

에이전트 시대에 들어서는 스스로 파일을 탐색하고, 코드를 작성하고, 테스트를 실행합니다.

사람의 개입 없이도 작업이 완료되었습니다.

하네스 없이 에이전트에세 일을 시키면 생기는 일

1 ) 코드 스타일 불일치

2 ) 구조 무시

팀이 선택한 디자인 패턴 혹은 아키텍처를 건너뛰는 경우가 있습니다. 당장은 동작하지만, 나중에 고치기 어려운 코드가 만들어집니다.

3 ) 같은 실수 반복

에이전트와 이전에한 대화가 기록되고 있지 않아 계속 똑같은 실수를 반복합니다.

4 ) 파일 누적 현상

utils2.py, helpers_new.js, temp_fix.ts와 같은 불필요한 파일이 많아지면서 실제로 사용되는 파일을 찾기 어려워 집니다.

5 ) 컨텍스트 불안

에이전트가 처리할 수 잇는 정보량의 한계에 가까워졌다고 판단하면, 제대로 마무리 하지 않고 완료 처리합니다.

하네스 환경 설정 방법

하네스는 네 가지 요소로 구성됩니다.

  1. 지시 문서 : Agent에 동작에 대한 규칙을 설정한다. Agents.md, CLAUDE.md와 같은 파일을 통해서 불필요한 행위를 줄입니다.
  2. 아키텍처 제약 : 구조적인 잘못된 코드를 차단한다. 린트, 디렉토리 규칙을 통해서 구조를 무시하고 아키텍쳐를 변질하는 행위를 방지합니다.
  3. 피드백 루프 : 에이전트 행동을 실시간으로 교정한다. 테스트, CI 자동화를 통해서 에이전트가 실시간으로 작동하는 고정에서 지속적인 문제점을 분석이 가능하도록 합니다.
  4. 지식 저장소 : 팀의 결정과 맥락을 추적한다. docs/ 디렉토리를 통해서 agent의 작업에 있었던 내용을 문서화 합니다.

하네스가 아닌것들

  • 프롬프트 엔지니어링
  • 코딩 컨벤션 문서
  • CI/CD 파이프라인

하네스 구성 요소

프로젝트 루트/
│ 
├── AGENTS.md ← ① 지시 문서 
├── .eslintrc ← ② 아키텍처 제약 
│ 
├── tests/ ← ③ 피드백 루프 
│   └── ... 
│ 
└── docs/ ← ④ 지식 저장소 
	├── decisions/ 
	└── conventions/

지시 문서

Agents.md 혹은 CLAUDE.md와 같은 파일 에이전트의 작업 시작 전 읽는 메뉴

  • 코드 스타일, 네이밍 규칙
  • 절대 건드리면 안되는 파일, 디렉토리
  • PR 작성 방식, 커밋 메시지 형식

아키텍처 제약

잘못된 코드를 구조적으로 차단

린터, 타입 검사, 디렉토리 규칙처럼 코드가 저장되거나 병합되기 전에 자동으로 검사하는 장치

  • 허용되지 않는 import 경로 차단
  • 코드 스타일 자동 교정
  • 특징 패턴 사용 금지

피드백 루프

에이전트의 행동을 실시간으로 교정하는 공간

  • 가이드
    • 테스트
    • 예제 코드
  • 센서
    • CI 실패
    • 린터 경고

지식 저장소

사람의 결정과 맥랑을 추적

docs/ 디렉토리에 사람이 내린 결정, 채택한 이유, 포기한 대안을 기록합니다.

  • 왜 이 라이브러리를 선택했는가?
  • 이전에 시도했다가 실패한 방법
  • 특정 구조를 유지하는 이유

Graph View