새벽 5시 47분, 둘째 깨기 전에 쏘렌토 운전석에서 노트북 열어 봤더니 밤새 클로드 코드가 PR 3개를 올려놨더라구요. 솔직히 처음엔 좀 무서웠어요. “내가 보는 동안만 일하던 애가 왜 혼자 일하지?” 하는 그런 느낌이요. 알고 보니까 며칠 전에 만든 하네스 엔지니어링 시스템이 잘 돌아가고 있는 거였습니다. 정보보안 일하면서 AI 에이전트한테 권한을 풀어 준다는 게 한참 동안 어색했는데, 이 개념을 알고 나서는 오히려 마음이 편해졌어요. 오늘은 이 하네스 엔지니어링이 도대체 뭔지, 왜 지금 갑자기 핫해졌는지, 그리고 어디서부터 적용해야 하는지 정리해 볼게요.
한눈에 보기
- 프롬프트 → 컨텍스트 → 하네스 엔지니어링으로 이어지는 AI 활용법의 진화
- AI가 사람 개입 없이 스스로 일할 수 있도록 환경·로그·검증 훅을 강제하는 시스템
- OpenAI 팀이 5개월간 사람 코드 거의 없이 서비스 만든 사례로 다시 주목받음
- 핵심 3축: 가시성(로그), 컨텍스트 목차화, CI/CD 강제
- 초기 구축에 시간이 들지만 한번 갖춰지면 작업 속도가 폭발적으로 줄어듦
하네스 엔지니어링이 도대체 뭔가요
하네스(Harness)는 원래 강아지 산책시킬 때 몸에 채우는 그 띠에서 온 말입니다. 우리집 강아지 설이 산책시킬 때 쓰는 그거 맞아요. 강아지가 도로로 막 뛰어나가면 큰일이니까, 갈 수 있는 범위를 미리 정해 두는 그 역할 그대로를 AI한테 적용한 게 하네스 엔지니어링입니다.
이거 저도 글 정리하면서 처음 제대로 알게 된 건데, 단순히 “AI한테 하지 말라고 말하는 것”이 아니라 “AI가 룰을 어겼을 때 자동으로 잡아내고 되돌려놓는 장치”까지 포함하는 개념이에요. 말로만 시키면 AI는 무시할 때가 정말 많거든요. 그래서 어겼을 때 빨간불이 들어오게끔 환경 자체를 짜 두는 게 핵심입니다.
최근에 다시 핫해진 이유는 OpenAI 팀이 공개한 한 사례 때문입니다. 약 5개월 동안 사람이 코드를 거의 안 쓰고 AI들끼리 어떤 서비스를 만들었다는 내용이었어요. 정확한 서비스 이름이나 세부 수치까지는 제가 100% 확신은 못하겠는데, 핵심 메시지는 분명했어요. “AI를 이렇게까지 자율적으로 굴릴 수 있는 시스템을 어떻게 짰느냐”였습니다. 그 문서가 공개된 뒤로 개발자들 사이에서 “이거 우리도 만들어야 하는 거 아냐?” 하는 분위기가 생긴 거죠.
저는 정보보안 쪽 일하면서 AI 에이전트 통제 문제를 실무에서 자주 보는데, 이 개념이 막연하던 걸 한방에 정리해 줬어요. 결국 권한 경계 안에서만 AI가 움직이게 만들고, 벗어나면 즉시 차단하는 거니까요. 보안 사람한테는 너무 익숙한 발상이거든요. (아마 보안 직무 분들은 다들 비슷하게 느끼실 거예요.)
프롬프트에서 하네스까지, 진화의 흐름
왜 갑자기 하네스 엔지니어링이라는 말이 나왔는지 보려면, 그동안 우리가 AI를 어떻게 다뤄 왔는지 흐름부터 봐야 해요. 단계가 꽤 명확합니다.
1단계 – 프롬프트 엔지니어링. “말 잘 거는 기술”이에요. 개떡같이 말하면 AI가 못 알아들으니까 최대한 자세하게, 구체적으로, 단계별로 설명하는 거. 이게 처음 나왔을 때 다들 그랬잖아요. “프롬프트만 잘 짜면 GPT가 다 해 준다”라고. 근데 이게 한계가 있었어요.
2단계 – 컨텍스트 엔지니어링. AI한테 일의 히스토리를 알려 주는 거예요. 신입 사원보다 6개월 인턴이 일을 잘하는 이유, 회사 돌아가는 맥락을 알기 때문이잖아요. AI한테도 그 맥락을 잘 전달하는 방법을 고민하기 시작한 단계입니다. 클로드 코드의 CLAUDE.md, 커서의 .cursorrules 같은 게 다 컨텍스트를 잡아 주는 도구예요.
3단계 – 하네스 엔지니어링. 컨텍스트를 줘도, 프롬프트를 잘 짜도, AI가 자기 마음대로 가는 경우가 너무 많았던 거예요. “빨간색 쓰지 마”라고 분명히 적어 놨는데도 어느 순간 보면 빨간색이 들어가 있는 거죠. 그래서 등장한 게 “어겼을 때 자동으로 막아 주는 장치까지 만들어 두자”는 발상입니다.
이 진화 과정에서 한 가지 재미있는 게, AI 자체가 똑똑해진 만큼 “AI를 어떻게 가둘 것인가”가 더 큰 문제가 됐다는 점이에요. 신입 직원이 너무 일을 잘하고 빨라지니까, 검토하는 시니어가 병목이 되는 거랑 똑같습니다. OpenAI 팀이 발견한 핵심 통찰도 정확히 이거였어요. “생산성의 적폐는 AI가 아니라 인간이다.” 좀 충격적인 말인데 솔직히 부정 못 하겠더라구요.
핵심 3축: 눈, 목차, 강제
OpenAI 팀이 공개한 문서를 뜯어 보면, 하네스 엔지니어링은 결국 세 가지 축으로 정리됩니다. 이거 진짜 중요해서 한 번 외워 두시면 좋아요.
1) 가시성(Visibility) – AI에게 눈을 달아 주기
AI가 자기 행동의 결과를 볼 수 있게 만드는 겁니다. 핵심은 로그예요. 보통 개발자들은 “쓸데없는 로그 지워” 라는 잔소리 듣고 자랐잖아요. 저도 옛날에 그랬어요. 근데 하네스 엔지니어링 세계에서는 정반대예요. 오히려 로그를 더 풍부하게 남겨야 합니다. AI가 자기가 만든 코드의 출력을 보고 “어, 이거 내가 의도한 결과가 아니네” 하면서 스스로 피드백 루프를 돌려야 하니까요.
실무에서는 로그 파일, 스크린샷, 콘솔 출력, 에러 트레이스 같은 걸 다 모아서 AI가 접근할 수 있는 위치에 저장해 둡니다. 정보보안 관점에서는 이게 사실 감사 로그(audit log)랑 같아요. 누가 뭘 했는지 추적 가능하게 만들어 두는 거. AI가 작업을 하면 모든 단계가 기록으로 남고, 문제 생기면 그 로그로 거꾸로 추적할 수 있어야 합니다.
2) 컨텍스트 목차화 – 필요할 때만 꺼내 쓰기
AI한테 모든 컨텍스트를 한 번에 다 주면 어떻게 되는 줄 아세요? 사람이랑 똑같아요. 앞부분만 대충 읽고 뒷부분은 안 읽어요. 진짜로요.
OpenAI 팀이 처음에 시도한 게 거대한 AGENTS.md 파일에 모든 규칙을 다 때려넣는 방식이었대요. 결과는 망했답니다. AI가 지침을 무시하고 자기 마음대로 하더라는 거예요. 그래서 바꾼 방식이 “AGENTS.md를 거대한 문서가 아니라 목차로 만든다”입니다.
“아키텍처 규칙은 이 파일을 봐. UI 검증 룰은 저 파일을 봐”라는 식으로 인덱스만 주고, 실제 내용은 별도 문서에 흩어 놔요. AI가 작업하다가 필요한 시점에 그 문서로 점프해서 읽고 옵니다. 사람으로 치면 “필요할 때 매뉴얼 펼쳐 봐”인 셈이죠.
3) CI/CD 강제 – 어겼을 때 자동으로 빨간불
이게 솔직히 하네스 엔지니어링의 진짜 핵심이라고 봐요. 앞의 두 개는 사실 컨텍스트 엔지니어링하고도 겹치는데, 이 부분이 진짜 다른 점이거든요.
예를 들어 Husky라는 도구로 pre-commit 훅을 걸어 둡니다. AI가 커밋하려고 할 때마다 자동으로 검사를 돌려요. “마스터 브랜치를 직접 건드리려고 하면 차단”, “계획 문서 없이 코드만 들어오면 차단”, “단위 테스트 없으면 차단” 이런 식으로요. 말로 부탁하는 게 아니라 시스템이 강제하는 겁니다.
여기에 ESLint 룰, 빌드 검증 스크립트, 파일 크기 제한 같은 걸 다 엮어 두면 AI가 이상한 코드를 짜도 자동으로 빠꾸 먹는 구조가 돼요. 어찌됐든 이 강제 장치가 있어야만 진짜 사람 손을 뗄 수 있습니다.
바이브 코딩과 하네스 엔지니어링, 어떻게 다를까
요즘 바이브 코딩이라는 말도 많이 들리잖아요. “감으로 AI한테 시키고 결과 보고 또 시키고” 하는 그 방식이요. 하네스 엔지니어링하고 어떻게 다른지 표로 정리해 봤어요.
| 항목 | 일반 바이브 코딩 | 하네스 엔지니어링 |
|---|---|---|
| 사람 개입 | 매 단계마다 테스트·확인 | 최소화 (검증 자동화) |
| 작업 공간 | 현재 브랜치에서 바로 | 별도 git worktree에서 격리 |
| 실수 처리 | 사람이 발견 후 지시 | 훅이 자동 차단 + AI 자가 수정 |
| 로그 | 최소화·정리 대상 | 풍부하게 남김 (피드백 재료) |
| 지침 전달 | 큰 한 덩어리 문서 | 목차 + 분산 문서 |
| 초기 비용 | 거의 없음 | 큼 (시스템 구축 시간) |
| 장기 효율 | 사람이 병목 | AI가 자율적으로 가속 |
저는 솔직히 둘 다 필요하다고 봐요. 잠깐 시제품 만들 때, 1회성 스크립트 짤 때는 바이브 코딩이 훨씬 빠릅니다. 하네스를 짜는 시간이 더 들거든요. 근데 같은 프로젝트를 한 달 이상 끌고 가야 한다, 또는 야간에 자동으로 굴리고 싶다 하면 그때부터는 하네스 엔지니어링이 압도적으로 효율적입니다.
제 경험상 이 분기점은 “이 코드베이스에 같은 종류의 작업을 3번 이상 시킬 것 같다” 싶을 때예요. 3번째부터는 하네스를 짜는 게 결국 시간 절약이 됩니다.
실전 적용: 5단계 워크플로우
OpenAI 문서에서 따온 하네스 엔지니어링 표준 워크플로우는 이렇게 5단계입니다. 클로드 코드든 커서든 적용 가능해요.
1단계 – 계획 문서 생성. “기능 만들어 줘”라고 하면 바로 코드부터 짜는 게 아니라 plans/active/ 폴더에 마크다운으로 계획서부터 작성합니다. 어떤 파일을 어떻게 바꿀지, 테스트는 어떤 식으로 짤지, 예상 리스크는 뭔지 미리 정리하는 거예요.
2단계 – 워크트리에서 구현. 메인 브랜치에서 바로 작업하지 않고 git worktree로 격리된 작업 공간을 만들어서 거기서만 코드를 만집니다. 망가져도 메인은 안전해요. 이거 진짜 중요해요.
3단계 – 단위 테스트 작성. 구현 코드 만들기 전이나 동시에 테스트도 같이 짜요. AI가 자기가 만든 코드를 자기 테스트로 검증할 수 있어야 합니다.
4단계 – 검증 실행. scripts/verify-task.sh 같은 검증 스크립트를 돌려서 lint, build, test, 파일 크기 제한 같은 걸 한꺼번에 통과시켜야 다음 단계로 넘어갑니다. 하나라도 실패하면 처음으로 되돌아가요.
5단계 – 자가 커밋·머지. 검증 통과한 결과물을 AI가 직접 커밋하고 메인에 머지합니다. 커밋 메시지 형식까지 미리 룰로 정해 두기 때문에 일관된 형식으로 들어가요.
여담인데, 제가 처음 이걸 따라 해 봤다가 1단계를 빼먹고 2단계로 바로 넘어가게 둔 적이 있어요. 결과가 어땠냐면 AI가 워크트리 안에서 30분 동안 신나게 코드 짰는데 정작 방향이 완전 엉뚱했더라구요. 시간만 날린 거죠. 그날 이후로 plans/active 폴더가 비어 있으면 코드 작성 자체를 차단하는 훅을 추가했어요. 이런 게 바로 “어겼을 때 잡아내는 장치”입니다.
그래서 어디부터 시작해요
처음부터 완벽한 하네스를 짜려고 하면 시작도 안되요. 진짜로요.
일단 평소처럼 작업하다가 “이거 매번 반복하네” 싶은 순간에 그 부분만 훅이나 스크립트로 자동화하세요. 한 달이면 본인만의 하네스가 생깁니다. 사실 이 부분은 길게 쓸 필요 없어요. 그냥 시작하면 됩니다.
초보자가 자주 하는 실수
여기서 많이들 실수해요. 제가 지난 한 달 동안 직접 겪은 것들이라 좀 자신 있게 적어 봅니다.
실수 1 – CLAUDE.md/AGENTS.md를 안 만들고 시작하기. OpenAI 문서에는 사실 CLAUDE.md 얘기가 직접 안 나와요. 그래서 따라 하다 보면 빼먹게 되는데, 클로드 코드는 이 파일을 무조건 먼저 읽고 시작하기 때문에 여기에 룰을 안 넣으면 하네스가 무력화됩니다. 작은 파일이어도 일단 만들어서 “5단계 워크플로우 무조건 지켜라” 한 줄이라도 적어 두세요.
실수 2 – 훅 없이 프롬프트로만 강제하려는 시도. “마스터 브랜치 건드리지 마”라고 백 번 적어 봤자 AI가 무시할 때가 많아요. 진짜로요. 반드시 git pre-commit 훅이나 verify 스크립트로 강제 차단해야 합니다. (여기서 많이들 헛수고하세요.)
실수 3 – 로그를 너무 적게 남기기. 옛날 습관 그대로 “깔끔한 코드”를 추구하다가 로그를 다 지우는 경우가 많아요. AI 자율화 환경에서는 정반대로 가야 합니다. 로그는 AI의 눈이거든요. 눈 빼앗고 일 시키는 꼴이 됩니다.
실수 4 – 한 번에 너무 큰 작업 맡기기. “이 앱 처음부터 만들어 줘” 같은 요청은 하네스가 잘 짜여 있어도 폭발해요. 한 PR에 한 기능 단위로 끊어 주는 게 안전합니다.
실수 5 – 권한·시크릿 관리 소홀히 하기. 이건 제가 직업병으로 강조하는데, AI가 자율적으로 git 커밋하고 머지하는 환경이면 결국 토큰이랑 키가 노출될 위험이 커져요. .env 파일 절대 커밋 안 되게 .gitignore에 못박고, pre-commit에 secret scan 훅 추가해 두세요. 회사에서 망분리된 환경 점검할 때도 결국 제일 많이 발견되는 이슈가 “코드 안에 박혀 있는 평문 토큰”이었거든요. 이거 안 해 두면 어쨌든 한 번은 사고 납니다.
함께 알면 좋은 개념들
하네스 엔지니어링하고 자연스럽게 엮이는 개념들이 몇 개 있어요. 같이 알아 두면 훨씬 강력해집니다.
MCP (Model Context Protocol). 클로드 코드가 외부 도구·데이터에 접근할 때 쓰는 표준 프로토콜이에요. 하네스 안에서 AI가 사용할 수 있는 도구를 정의할 때 MCP가 자주 등장합니다. 깃허브, 로컬 파일시스템, DB 같은 걸 연결할 수 있어요.
워크트리(git worktree). 같은 저장소의 다른 브랜치를 별도 폴더로 동시에 펼쳐 놓는 git 기능입니다. AI가 메인을 건드리지 않게 격리하는 데 핵심적이에요. 명령은 git worktree add 한 줄이면 끝납니다. 익혀 두면 사람 작업할 때도 편해요.
Husky + lint-staged. JavaScript 생태계에서 pre-commit 훅 관리할 때 거의 표준 도구입니다. AI가 커밋 시도할 때 자동으로 lint·테스트·포맷 검사 돌리는 데 씁니다. 파이썬은 pre-commit이라는 별도 도구가 있어요.
관찰가능성(Observability). 가시성을 좀 더 본격적으로 만들면 결국 이 개념으로 갑니다. 로그·메트릭·트레이스 3종 세트인데, AI 에이전트 운영 환경에선 이게 필수가 될 거예요. 정보보안 일하시는 분은 한번 찾아보시면 좋습니다.
대신 질문 해드릴게요 (FAQ)
Q1. 하네스 엔지니어링, 진짜 지금 당장 해야 하나요?
모든 프로젝트에 다 필요한 건 아니에요. 1회성 스크립트나 시제품에는 오버킬입니다. 같은 코드베이스에서 반복적인 AI 작업을 3번 이상 시킬 것 같다 싶을 때, 그때 도입해도 늦지 않아요.
Q2. 클로드 코드랑 커서 중 뭐가 더 잘 맞나요?
둘 다 됩니다. 클로드 코드는 CLAUDE.md를 시작 시 무조건 읽기 때문에 룰 강제력이 좀 더 강해요. 커서는 .cursorrules 파일이 그 역할을 합니다. 제 경험상 워크트리 운영은 클로드 코드가 좀 더 자연스러웠어요. 그냥 제 취향일 수 있으니 둘 다 써 보시는 걸 추천드려요.
Q3. 한번 구축하면 다른 프로젝트에 재사용 가능한가요?
훅 스크립트, 검증 스크립트, AGENTS.md 템플릿은 거의 그대로 복사해서 쓸 수 있어요. 프로젝트 전용 룰만 갈아끼우면 됩니다. 그래서 두 번째 프로젝트부터는 구축 비용이 확 줄어들어요.
Q4. AI가 훅을 우회하려고 하지는 않나요?
가끔 있어요. –no-verify 플래그를 붙이려고 하거나 .gitignore를 수정하려고 하는 경우가 있어서, 이런 행동도 별도 훅으로 차단하는 게 좋습니다. 메타 훅이라고 부르기도 해요.
Q5. 비용은 얼마나 더 드나요?
토큰 사용량은 늘어나요. AI가 계획 문서 쓰고, 테스트 짜고, 검증 돌리고, 로그 읽고 다 하니까요. 대신 사람 시간은 확 줄어듭니다. 시급으로 환산하면 거의 항상 흑자예요.
Q6. 회사에서 도입하고 싶은데 보안 이슈는 어떻게 풀어야 하나요?
권한 최소화 원칙으로 가면 됩니다. AI 에이전트한테 production 권한은 절대 주지 말고, 별도 sandbox 계정 발급, 모든 작업은 PR로만 들어오게 막고, 시크릿은 vault로 분리하세요. 정보보안 직무 입장에서는 사실 일반 신입한테 적용하는 룰을 그대로 옮기면 됩니다.
Q7. 학습 자료 추천해 주세요.
OpenAI 엔지니어링 블로그(openai.com/blog)에 관련 포스트가 있고, Anthropic의 클로드 코드 공식 문서(docs.claude.com)에 하네스 비슷한 패턴이 많이 나와요. 영상으로는 “코딩알려주는누나” 채널의 하네스 엔지니어링 정리 영상이 입문에 가장 좋습니다.
레추의 총평
솔직히 말해서 처음 하네스 엔지니어링이라는 단어 들었을 때 “또 무슨 신조어야” 싶었어요. 프롬프트, 컨텍스트, 하네스, 다음엔 또 뭐가 나올지 피로하기도 했고요. 근데 한참 들여다보니까 이게 단순한 새 용어가 아니라 “AI한테 사람 손을 뗄 수 있는 환경을 짜는 방법론” 그 자체더라구요.
두 아이 키우면서 코딩 시간 짜내는 입장에선 솔직히 너무 매력적이에요. 잠들기 전에 작업 큐만 던져 놓고 다음날 새벽에 결과 검수만 하는 게 가능해지니까요. 물론 처음 환경 짜는 시간이 들긴 하는데, 한 번 만들어 두면 다음 프로젝트는 폴더 복사 한 번에 끝납니다.
다만 욕심부려서 처음부터 완벽한 하네스를 만들려고 하면 시작도 못 해요. 저도 그랬거든요. 진짜 추천하는 진입 방법은 이거예요. 일단 평소처럼 바이브 코딩으로 시작하다가, “이 작업 자꾸 반복하네” 싶으면 그 부분만 훅이나 스크립트로 자동화. 그렇게 한 달 정도 모아 가면 어느새 본인만의 하네스가 생겨 있을 거예요.
오늘 정리한 내용이 도움 되셨다면 댓글 한 줄 부탁드려요. 본인이 쓰는 클로드 코드/커서 룰 자랑도 환영입니다. 다음 글에서는 제가 실제로 쓰고 있는 CLAUDE.md 템플릿을 통째로 공개해 볼게요.
클로드 일주일 무료 이용권은 아래의 링크에서 가져가시면 됩니다 (선착순)
https://claude.ai/referral/2UaEl8cpPA
참고 링크
- OpenAI 엔지니어링 블로그: openai.com/blog
- Anthropic 클로드 코드 공식 문서: docs.claude.com
- git worktree 공식 문서: git-scm.com/docs/git-worktree
이 글과 함께 많이 보는 상품
클로드 코드를 활용한 바이브 코딩 완벽 입문:기본 사용법부터 MCP, 병…
23,400원
한 걸음 앞선 개발자가 지금 꼭 알아야 할 클로드 코드…
23,400원
요즘 바이브 코딩 클로드 코드 완벽 가이드…
21,600원
이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
