개요
하네스 엔지니어링은 AI 개발의 효율성을 극대화하기 위해 등장한 개념이다. 기존 개발 방식에서는 개발자가 AI의 코드를 생성한 후 테스트하고, 문제가 있으면 다시 수정 요청하는 반복 루프에 빠져 있었다. 이 과정에서 AI는 빠르게 코드를 작성하지만 인간의 검증 속도가 느려 생산 병목이 된다.
하네스 엔지니어링은 이 문제를 역발상으로 접근한다. AI가 인간의 개입 없이 스스로 계획하고, 구현하고, 테스트하고, 버그를 찾아 수정하도록 시스템을 설계하는 것이다. 마치 강아지 산책할 때 쓰는 '하네스'처럼, AI에게 명확한 규칙과 경계를 설정하되, 그 안에서 최대한 자율적으로 움직이게 만드는 접근법이다.
배경 / 사전 지식
AI 엔지니어링의 진화 과정
AI 개발 분야는 지난 몇 년간 세 가지 엔지니어링 기법의 진화를 거쳤다:
프롬프트 엔지니어링은 가장 기초적인 단계다. AI가 우리의 요청을 잘 이해하려면 최대한 자세하고 명확하게 설명해야 한다는 개념이다. 예를 들어 "빨간색 문서 만들어"라고 하면 AI가 제대로 이해 못 할 가능성이 높으므로, "CSS 파일에서 색상값을 #FF0000으로 설정하고, 모든 텍스트 요소에 적용해 달라"는 식으로 구체적으로 명시해야 한다.
컨텍스트 엔지니어링은 한 단계 진화한 개념이다. 새로운 직원을 생각해보자. 신입은 명확한 지시를 받아도 회사의 역사, 기존 코드 스타일, 프로젝트 구조를 모르면 실수하기 쉽다. 하지만 6개월간 일한 인턴은 이런 배경을 알고 있어서 더 효과적으로 일한다. 마찬가지로 AI에게 과거 결정 사항, 프로젝트 구조, 코딩 컨벤션 등의 '맥락'을 제공하면 훨씬 나은 결과를 얻는다.
하네스 엔지니어링은 가장 최근에 등장한 개념으로, 단순한 지시나 배경 정보를 넘어 '규칙의 강제'에 초점을 맞춘다. AI에게 "빨간색을 사용하지 마"라고 아무리 말해도 무시할 수 있다. 하지만 빨간색을 사용하려 할 때 자동으로 에러가 발생하도록 시스템을 설정하면 AI는 그 규칙을 무시할 수 없다.
핵심 용어
- 가시성(Visibility): AI가 자신의 작업 결과를 확인할 수 있는 능력. 로그, 스크린샷, 테스트 결과 등을 통해 구현된다.
- 컨텍스트(Context): AI가 작업 수행에 필요한 배경 정보. 프로젝트 구조, 코딩 컨벤션, 과거 결정사항 등을 포함한다.
- CI/CD: Continuous Integration/Continuous Deployment. 코드 변경 시 자동으로 빌드, 테스트, 배포하는 시스템.
- 워크트리(Worktree): Git의 기능 중 하나로, 하나의 저장소에서 여러 개의 독립적인 작업 디렉토리를 동시에 유지할 수 있게 해준다.
핵심 개념
1. 프롬프트 엔지니어링
가장 기초적인 단계로, AI에게 명확하고 상세한 지시를 제공하는 기술이다. 모호한 표현보다는 구체적인 요구사항, 예상 출력 형식, 주의사항 등을 명시해야 한다. 하지만 이것만으로는 충분하지 않다. AI가 복잡한 작업을 수행할 때 과거의 결정이나 문맥을 모르면 일관성 있는 결과를 낼 수 없기 때문이다.
2. 컨텍스트 엔지니어링
AI에게 프로젝트의 히스토리, 구조, 컨벤션을 이해시키는 기법이다. 마치 신입 사원에게 온보딩을 하듯, AI가 필요한 배경지식을 갖추도록 한다. 그러나 모든 정보를 한 번에 제공하면 AI가 문서를 대충 읽고 넘어갈 수 있다. 따라서 정보를 체계적으로 구성하고, AI가 필요할 때마다 관련 정보를 찾아갈 수 있도록 해야 한다.
3. 하네스 엔지니어링
세 가지 핵심 요소로 구성된다:
① 가시성(Visibility)
AI가 자신의 작업 결과를 즉시 확인할 수 있어야 한다. 기존 소프트웨어 개발에서는 쓸데없는 로그를 제거하는 것이 관례였지만, AI 시스템에서는 반대다. AI가 로그를 읽고 "아, 내 출력이 원하는 형식이 아니네"라고 스스로 판단하고 수정할 수 있도록 상세한 로그가 필수다. 로그뿐만 아니라 스크린샷, 테스트 결과, UI 상태 변화 등 다양한 피드백 채널을 제공해야 한다.
② 점진적 컨텍스트 공개(Gradual Context Exposure)
모든 정보를 한 번에 제공하는 대신, 목차 형식의 구조를 만들고 AI가 필요한 부분을 찾아가도록 유도한다. OpenAI 팀의 초기 시도에서 하나의 큰 AGENT.md 파일에 모든 정보를 집어넣었을 때는 AI가 컨텍스트를 제대로 소화하지 못했다. 하지만 목차를 제공하고 "필요한 항목을 찾아서 참고해"라고 지시하면 AI가 더 효율적으로 정보를 활용한다.
③ 규칙 강제(Rule Enforcement)
이것이 하네스 엔지니어링의 가장 중요한 요소다. 프롬프트로만 "이 파일을 수정하지 마" 또는 "빨간색을 사용하지 마"라고 아무리 강조해도 AI가 이를 무시할 수 있다. 대신 ESLint 규칙, Git 커밋 훅, 자동화된 테스트 같은 기술적 장치를 통해 규칙을 강제해야 한다. AI가 규칙을 어기려 하면 자동으로 에러가 발생하고, AI는 이 에러 피드백을 받아 스스로 수정하게 된다.
작동 원리
전통적 AI 개발 워크플로우
기존의 일반적인 AI 개발 방식은 다음과 같다:
- 개발자가 AI에게 "OOO 기능을 만들어 줄래?"라고 요청
- AI가 코드 작성 완료
- 개발자가 코드를 테스트
- 문제 발견 → "이 부분 고쳐 줄래?"
- AI가 수정
- 다시 테스트...
이 과정을 완벽한 결과가 나올 때까지 반복한다. 문제는 AI의 작성 속도는 매우 빠르지만, 인간의 검증 속도는 느리다는 점이다. 따라서 인간이 병목이 되어 전체 생산성이 저하된다.
하네스 엔지니어링 워크플로우
하네스 엔지니어링에서 원하는 최종 형태는 다음과 같다:
- 개발자가 "OOO 기능을 만들어 줄래?"라고 요청
- AI가 스스로 계획 수립 (어떤 파일을 수정할지, 어떤 테스트를 작성할지 등)
- AI가 코드 구현
- AI가 자동으로 테스트 실행 (로그 확인)
- AI가 로그를 분석하여 버그 발견
- AI가 자동으로 수정
- 다시 테스트...
- 모든 테스트 통과 → 완성
이 과정에서 인간은 최종 결과를 받아보면 된다. AI가 자동으로 검증 루프를 수행하므로 인간의 개입이 최소화된다.
단계별 구현 방법
Step 1: 계획 수립 강제
AI가 코드를 작성하기 전에 반드시 계획 문서를 작성하도록 강제한다. "어떤 파일을 수정할 것인가", "어떤 함수를 추가할 것인가", "어떤 테스트를 작성할 것인가"를 미리 명시하게 한다. 이를 위해 CLAUDE.md 파일에 명확한 단계를 지정한다.
Step 2: 격리된 환경에서 작업
Git 워크트리를 사용하여 메인 브랜치와 독립된 작업 디렉토리를 만든다. 이렇게 하면 AI의 실수가 메인 코드에 영향을 주지 않으며, 각 AI 인스턴스가 독립적으로 작동할 수 있다.
Step 3: 가시성 확보
AI가 실행한 모든 작업에 대해 로그, 테스트 결과, 스크린샷 등이 남도록 설정한다. AI는 이 출력을 읽고 자신의 작업이 성공했는지 실패했는지 판단한다.
Step 4: 규칙 강제
- ESLint 규칙으로 코드 스타일 강제
- Git 커밋 훅으로 커밋 메시지 형식 강제
- 자동화된 테스트로 기능 검증
- 타입 체크로 타입 안정성 강제
Step 5: 피드백 루프
AI가 규칙을 어기려 하면 자동으로 에러 메시지가 표시된다. AI는 이 에러를 읽고 원인을 파악하여 수정한다.
코드 예시
1. CLAUDE.md를 통한 하네스 설정
# 개발 프로세스
## 필수 단계
1. **계획 수립**: 코드 작성 전에 무조건 계획 문서를 먼저 작성한다
- 수정할 파일 목록
- 각 파일에서 변경할 부분
- 추가할 함수/클래스
- 작성할 테스트
2. **워크트리에서 구현**: 메인 브랜치와 격리된 환경에서 작업한다
- `git worktree add /tmp/work-branch` 로 워크트리 생성
- 이 디렉토리에서만 작업
- 메인 브랜치는 건드리지 않기
3. **테스트 자동 실행**: 코드 작성 후 반드시 테스트를 실행한다
- `npm test` 또는 `pytest`
- 모든 테스트가 통과할 때까지 수정
4. **린트 규칙 준수**: 코드 스타일 검사를 반드시 통과해야 한다
- `npm run lint` 실행
- 린트 에러가 0이 될 때까지 수정
## 절대 하지 말아야 할 것
- 계획 단계를 건너뛰고 바로 코드 작성 ❌
- 메인 브랜치에서 직접 작업 ❌
- 테스트 없이 코드 완성 선언 ❌
- 린트 에러를 무시하고 커밋 ❌
이 문서를 CLAUDE.md에 저장하면, Claude Code는 매번 작업 시작 전에 이를 읽고 따른다.
2. ESLint 규칙 예시
// .eslintrc.json - 규칙 강제
{
"rules": {
"no-console": "error", // console.log 금지
"no-var": "error", // var 금지, const/let만 허용
"semi": ["error", "always"], // 세미콜론 필수
"indent": ["error", 2], // 2칸 들여쓰기 필수
"quotes": ["error", "single"], // 작은따옴표 필수
"no-unused-vars": "error" // 사용 안 하는 변수 금지
}
}
AI가 console.log를 사용하려 하면 npm run lint에서 즉시 에러가 발생한다. AI는 이 에러를 보고 console.log를 제거한다.
3. Git 커밋 훅 예시
#!/bin/bash
# .git/hooks/commit-msg
# 커밋 메시지가 정해진 형식을 따르는지 확인
COMMIT_MSG=$(cat "$1")
if ! [[ "$COMMIT_MSG" =~ ^(feat|fix|docs|style|refactor|test)\: ]]; then
echo "❌ 커밋 메시지가 올바른 형식이 아닙니다."
echo "형식: feat: 설명 | fix: 설명 | docs: 설명"
exit 1
fi
AI가 "빠꾸 했어요"같은 형식으로 커밋하려 하면 훅이 거부한다. AI는 "fix: 버그 수정" 형식으로 다시 작성한다.
4. 자동 테스트 예시
// tests/calculator.test.js
const { add, subtract } = require('../src/calculator');
test('덧셈이 올바르게 작동한다', () => {
expect(add(2, 3)).toBe(5);
expect(add(-1, 1)).toBe(0);
});
test('뺄셈이 올바르게 작동한다', () => {
expect(subtract(5, 3)).toBe(2);
expect(subtract(-1, 1)).toBe(-2);
});
AI가 calculator.js 파일을 수정한 후 이 테스트를 실행한다. 테스트가 실패하면 AI는 로그를 보고 어느 부분이 잘못되었는지 파악하여 수정한다.
함정·실수
1. AI가 규칙을 무시하는 경우
문제: "제발 이 함수를 수정하지 마"라고 명시했는데도 AI가 수정해 버림.
원인: 프롬프트로만 제약을 설정했기 때문. AI는 주의를 기울이지 않으면 프롬프트 내용을 무시할 수 있다.
해결책: 기술적 장치로 강제하기
- ESLint 규칙으로 특정 파일 수정 금지
- Git 훅으로 특정 파일 변경 차단
- 자동화된 테스트로 규칙 위반 감지
2. 컨텍스트 오버로드
문제: CLAUDE.md 파일에 너무 많은 정보를 집어넣으면 AI가 중요한 부분을 놓침.
원인: 인간처럼 AI도 과도한 정보 앞에서는 집중력을 잃는다.
해결책:
- 파일을 목차 형식으로 구성
- "필요한 섹션을 찾아서 읽으세요"라고 명시
- 각 섹션을 간결하게 유지
- 핵심 규칙은 파일 상단에 배치
3. 불충분한 로그
문제: AI가 자신의 작업 결과를 확인할 수 없어 수정을 못 함.
원인: 로그나 테스트 결과가 부족하면 AI가 작업 성공 여부를 판단하지 못한다.
해결책:
- 모든 실행 단계마다 로그 출력
- 테스트 결과를 상세하게 표시
- 예상 출력과 실제 출력을 비교할 수 있게 구성
- 스크린샷이나 UI 상태 변화도 피드백에 포함
4. 계획 단계 생략
문제: AI가 계획 없이 바로 코드를 작성해서 방향이 잘못됨.
원인: 계획 단계를 강제하지 않으면 AI가 효율성을 위해 건너뜀.
해결책:
- CLAUDE.md에 "반드시 먼저 계획을 수립하세요"라고 명시
- 계획 수립 후 검증받는 단계 추가
- 자동화된 도구로 계획 문서 작성 강제
5. 워크트리 미사용
문제: AI가 메인 브랜치에서 직접 작업해서 메인 코드가 망가짐.
원인: 격리 환경의 중요성을 강조하지 않으면 AI가 편의상 메인에서 작업.
해결책:
- CLAUDE.md에 "반드시 워크트리를 사용하세요"라고 명시
- 메인 브랜치 보호 규칙 설정 (Git의 branch protection)
- 워크트리 사용을 확인하는 자동화 스크립트 추가
베스트 프랙티스
1. 계층화된 지시 구조
프롬프트를 계층으로 나누어 작성한다:
- 상위 계층: 전체 목표와 원칙 (CLAUDE.md)
- 중간 계층: 각 작업별 상세 지시 (작업 요청 시 전달)
- 하위 계층: 자동화된 규칙 (ESLint, 테스트)
이렇게 하면 AI가 각 수준의 정보를 적절하게 활용할 수 있다.
2. 피드백 루프의 자동화
AI가 스스로 다음 단계를 결정하도록 설계한다:
코드 작성 → 테스트 실행 → 로그 분석 → (성공?) → (아니면 수정) → 반복
인간이 "고쳐 줄래?"라고 일일이 지시할 필요 없이 AI가 자동으로 루프를 돈다.
3. 명확한 성공 기준
"다 했습니다"의 정의를 명확히 한다:
- ✅ 모든 단위 테스트 통과
- ✅ 모든 린트 규칙 준수
- ✅ 코드 리뷰 자동화 통과
- ✅ 통합 테스트 통과
AI는 이 기준을 모두 만족할 때까지 작업한다.
4. 점진적 기능 추가
한 번에 큰 기능을 요청하기보다는 작은 단위로 나누어 요청한다:
❌ "전체 결제 시스템을 만들어 줄래?"
✅ "결제 폼 컴포넌트를 만들어 줄래?"
✅ "결제 API 엔드포인트를 만들어 줄래?"
✅ "결제 에러 처리를 추가해 줄래?"
각 단계가 작을수록 AI가 계획을 세우고 검증하기 쉬워진다.
5. 로그와 가시성의 중요성
기존 개발에서는 "쓸데없는 로그는 제거하는 게 좋은 관행"이었지만, AI 시스템에서는 반대다:
// ❌ 나쁜 예
function processData(data) {
return data.filter(x => x > 0);
}
// ✅ 좋은 예
function processData(data) {
console.log('입력 데이터:', data);
const result = data.filter(x => x > 0);
console.log('필터링 결과:', result);
console.log('제거된 항목 수:', data.length - result.length);
return result;
}
AI가 로그를 읽고 자신의 작업이 예상대로 진행되었는지 확인할 수 있다.
6. 워크트리와 독립적 인스턴스
여러 AI 인스턴스가 동시에 작업할 때 각각 독립적인 워크트리를 사용하면:
- 서로의 변경사항이 충돌하지 않음
- 각 AI가 병렬로 작업 가능
- 문제 발생 시 해당 워크트리만 처리 가능
7. 문제 발생 시의 루프 아웃
자동화된 피드백 루프가 진행되지 않을 때를 대비해야 한다:
## 문제 발생 시
- 10번 이상 동일한 에러가 반복되면 작업 중단
- 테스트 실패 원인이 명확하지 않으면 인간에게 알림
- 린트 에러가 계속 발생하면 규칙 재검토
무한 루프에 빠지지 않도록 종료 조건을 명확히 한다.
참고
영상 제시 자료
OpenAI 공식 문서: 영상에서 언급된 OpenAI의 "5개월 개발 프로젝트" 사례는 OpenAI의 공식 기술 문서에서 나온 것. 해당 문서는 하네스 엔지니어링의 3가지 요소(가시성, 컨텍스트 관리, CI/CD 강제)를 구체적으로 설명함.
강의자 제공 자료:
- 하네스 엔지니어링 실전 예제 코드: CLAUDE.md 구조와 워크트리 활용 예시
- 바이브 코딩 스터디: https://forms.gle/2d67DKoFWRsKNA5g7
- 바이브 코딩 강의: https://codingnoona.thinkific.com/courses/vibe-coding
추가 학습 자료
- Git Worktree 공식 문서:
git worktree명령어 상세 사용법 - ESLint 공식 문서: 규칙 설정 및 커스터마이징
- GitHub Actions: CI/CD 자동화 구성
- Claude API Documentation: Claude를 이용한 AI 시스템 구축
관련 개념
- 에이전트 프로그래밍(Agent Programming): AI가 스스로 의사결정을 내리고 행동하는 패러다임
- 프롬프트 캐싱(Prompt Caching): 반복되는 컨텍스트를 효율적으로 관리하는 기법
- 자가 수정(Self-Correction): AI가 자신의 출력을 검증하고 수정하는 능력