AI 에이전트에게 일을 맡기기 전
하네스 엔지니어링부터 설계해야 한다
AI 코딩 에이전트가 72시간 동안 대량 코드 변경과 PR을 만들었다는 사건은 단순한 해프닝이 아니다. 문제의 본질은 모델의 똑똑함이 아니라, 에이전트가 움직이는 작업장·권한·평가·제한 장치가 설계되어 있었느냐다.
최근 AI 코딩 도구는 단순 코드 자동완성을 넘어 저장소를 읽고, 이슈를 만들고, PR을 열고, 테스트를 돌리고, 리뷰까지 시도한다. 여기서 중요한 것은 “AI가 코드를 잘 짜는가”만이 아니다. 더 중요한 질문은 “AI가 잘못 움직였을 때 시스템이 어디서 멈추는가”다. 이 영역이 바로 하네스 엔지니어링이다.
먼저 결론
- AI 에이전트의 생산성은 모델 성능보다 하네스 품질에 크게 좌우된다. 좋은 하네스는 AI가 할 일, 하지 말아야 할 일, 멈춰야 할 조건을 명확히 만든다.
- GitHub 대량 코드 변경·PR 사건은 “AI가 많이 일했다”가 아니라 “AI의 작업량을 인간 협업 시스템이 감당할 수 있었는가”의 문제다.
- AI 코딩 에이전트는 권한, 실행 환경, 테스트, PR 제한, 로그, 리뷰 게이트가 없으면 빠르게 노이즈 생산자가 될 수 있다.
- 하네스 엔지니어링은 프롬프트 작성이 아니라 작업 시스템 설계다. AGENTS.md, 테스트 스크립트, 체크리스트, 권한 정책, 실패 처리까지 포함한다.
- 실무 도입은 “자율 에이전트 100%”보다 “작은 업무 단위 → 자동 점검 → 인간 승인 → 점진적 권한 확대”가 안전하다.
1. 하네스 엔지니어링이란 무엇인가
하네스는 원래 무언가를 안전하게 묶고 제어하는 장치라는 뜻이다. AI 에이전트에서 하네스는 모델이 작업하는 실행 환경, 도구, 권한, 컨텍스트, 테스트, 평가, 승인 흐름을 묶은 운영 장치다. 즉 “AI에게 어떤 말을 할 것인가”보다 “AI가 어떤 환경에서 어떤 규칙으로 움직일 것인가”를 설계하는 일이다.
프롬프트가 에이전트의 말이라면, 하네스는 에이전트의 작업장이다. 작업장이 엉성하면 좋은 모델도 엉뚱한 파일을 건드리고, 지나치게 큰 PR을 만들고, 테스트 없는 변경을 쌓고, 사람 리뷰를 병목으로 만든다.
2. 대량 코드 변경·PR 사건이 던지는 질문
영상 제목에서 언급된 “72시간 동안 엄청난 코드 변경과 PR을 올려 벤당한 사건”은 AI 에이전트 시대의 상징적인 문제를 보여준다. AI가 빠르게 작업할 수 있다는 사실 자체는 장점이다. 그러나 오픈소스 저장소나 팀 저장소에서는 속도가 곧 가치가 아니다. 메인테이너가 읽을 수 있고, 테스트할 수 있고, 병합 여부를 판단할 수 있어야 한다.
AI가 100개의 PR을 만들 수 있어도, 사람이 100개의 PR을 검토할 수 없다면 그것은 생산성이 아니라 운영 부채다. 에이전트는 코드 생산자가 아니라 협업 시스템의 참가자여야 한다.
3. 좋은 하네스는 다섯 가지를 제한한다
하네스가 좋은 팀은 AI에게 자유를 많이 주지 않는다. 오히려 작은 단위로 정확히 일을 시킨다. 예를 들어 “코드베이스 개선해줘”가 아니라 “이 모듈의 타입 오류 3개만 고치고, 테스트 통과 후 PR 하나로 제출해줘”라고 제한한다. 제한이 많을수록 AI의 작업은 협업 가능해진다.
4. 하네스 없이 에이전트를 쓰면 생기는 문제
| 문제 | 어떻게 발생하나 | 막는 방법 |
|---|---|---|
| PR 폭주 | 작업 크기 제한 없이 여러 이슈를 동시에 처리한다. | 동시 PR 수, 일일 PR 수, PR당 변경량 제한 |
| 테스트 없는 변경 | AI가 컴파일만 보고 실제 회귀 테스트를 생략한다. | 필수 테스트 명령과 실패 시 중단 규칙 지정 |
| 권한 과다 | 수정·삭제·푸시·배포 권한이 한 번에 열려 있다. | 읽기, 수정, PR 생성, 배포 권한을 단계별 분리 |
| 컨텍스트 오염 | 오래된 문서, 잘못된 이슈, 노이즈 로그를 그대로 믿는다. | AGENTS.md, 작업 범위 문서, 최신 명령어만 하네스에 주입 |
| 리뷰 병목 | 사람이 읽기 어려운 거대 변경을 만든다. | 작은 PR, 변경 요약, 테스트 증거, 롤백 방법 필수화 |
5. AGENTS.md는 하네스의 시작점이다
AI 코딩 에이전트가 저장소에서 일하려면 저장소 안에 작업 규칙이 있어야 한다. 대표적인 방식이 AGENTS.md, CONTRIBUTING.md, TESTING.md 같은 문서다. 이 문서는 에이전트에게 프로젝트 구조, 금지 작업, 테스트 명령, 코드 변경 규칙, 리뷰 기준을 알려준다.
AGENTS.md
에이전트가 따라야 할 저장소별 작업 규칙. 어디를 읽고, 무엇을 수정하고, 어떤 명령을 돌릴지 적는다.
TESTING.md
수정 유형별 최소 검증 명령을 정한다. 작은 수정, UI 수정, API 수정, DB 수정의 테스트 기준이 달라야 한다.
PR 템플릿
변경 이유, 범위, 테스트 결과, 리스크, 롤백 방법을 적게 만들어 리뷰 부담을 낮춘다.
6. 실무 하네스 체크리스트
AI 에이전트 도입 전에는 아래 항목을 먼저 정해야 한다. 이 체크리스트가 없으면 모델 성능이 좋아질수록 오히려 사고의 속도도 빨라진다.
| 항목 | 질문 | 최소 기준 |
|---|---|---|
| 작업 단위 | AI가 한 번에 어디까지 바꿀 수 있는가 | 이슈 1개, PR 1개, 파일 수 제한 |
| 권한 | 삭제·푸시·배포를 허용할 것인가 | 초기에는 PR 생성까지만 허용 |
| 검증 | 무엇이 통과되어야 완료인가 | lint, test, typecheck 중 해당 명령 필수 |
| 관측성 | AI가 무엇을 했는지 추적 가능한가 | 명령 로그, 변경 파일, 실패 이유 기록 |
| 중단 조건 | 언제 멈추고 사람에게 물어야 하는가 | 테스트 실패, 권한 부족, 대규모 변경, 외부 API 쓰기 |
7. 바로 써볼 수 있는 에이전트 작업 지시 템플릿
하네스가 준비되면 에이전트에게도 작업 범위와 중단 조건을 명확히 줘야 한다. 아래 템플릿은 작은 PR 단위 작업에 맞춘 기본형이다.
AI 코딩 에이전트 작업 지시 템플릿
8. Ouroboros 사례에서 배울 점
GitHub 검색 결과에서 Ouroboros는 “agent first software engineering infrastructure”, “self-creating AI agent” 같은 표현으로 설명된다. 표현만 보면 강력한 자율 에이전트처럼 보이지만, 실무자가 봐야 할 핵심은 자율성 자체가 아니다. 자율 에이전트가 실제 저장소에서 일하려면 계획, 구현, 테스트, 리뷰, 병합 흐름이 모두 관리되어야 한다.
자율 에이전트의 경쟁력은 혼자 끝까지 달리는 능력이 아니라, 사람과 저장소 규칙 안에서 안전하게 반복하는 능력이다. 따라서 에이전트 인프라는 모델 호출보다 권한·테스트·리뷰·로그·중단 정책을 더 중요하게 다뤄야 한다.
9. 회사에서 도입할 때의 안전한 순서
처음부터 AI에게 대규모 리팩터링이나 자동 병합을 맡기는 것은 위험하다. 작은 업무부터 시작해 하네스를 강화하는 편이 낫다.
이 순서를 지키면 AI 에이전트는 위험한 자동화가 아니라 팀의 보조 개발자로 들어올 수 있다. 반대로 권한부터 열면 생산성보다 통제 비용이 먼저 커진다.
10. 결론: AI 에이전트 시대의 실력은 하네스에서 갈린다
AI 모델은 계속 좋아진다. 하지만 실무 현장에서 성패를 가르는 것은 모델 하나의 지능이 아니라, 그 모델을 어떤 작업 시스템 안에 넣느냐다. 하네스가 없는 AI 에이전트는 빠르게 움직이는 인턴과 비슷하다. 의욕은 넘치지만 범위와 기준이 없으면 팀 전체를 바쁘게 만든다.
AI 에이전트를 잘 쓰는 조직은 “더 똑똑한 모델”보다 “더 안전한 작업장”을 먼저 만든다. 권한을 쪼개고, 테스트를 강제하고, PR 크기를 제한하고, 로그를 남기고, 사람이 승인해야 할 지점을 명확히 한다. 이것이 하네스 엔지니어링의 핵심이다.
출처와 참고 링크
본 글은 공개 영상 제목과 GitHub 검색 결과, 공개 문서를 바탕으로 AI 코딩 에이전트 운영 원칙을 정리한 일반 정보입니다. 특정 프로젝트나 인물에 대한 사실 판단을 확정적으로 단정하지 않으며, 실제 도입 시에는 조직의 보안 정책, 저장소 권한, 라이선스, 개인정보·영업비밀 보호 기준을 별도로 검토해야 합니다.