하네스 엔지니어링의 등장 배경
AI 코딩 에이전트의 성능은 이제 꽤 좋아졌습니다.
간단한 프롬프트만으로도 괜찮은 결과물이 나오고, 버그 수정이나 UI 변경 같은 작업도 무리 없이 처리합니다.
그런데 규모가 크거나 복잡한 작업을 맡기면 이야기가 달라집니다.
코드 품질이 떨어지고, 버그와 중복 코드가 늘어나며, 작업을 대충 마무리하려는 경우도 많습니다.
이는 모두 AI의 컨텍스트 크기 한계 때문입니다. 컨텍스트는 AI가 한 번에 생각할 수 있는 용량인데, 보통 20만에서 100만 토큰 수준으로 큰 작업을 한 번에 완수하기엔 꽤 부족한 양입니다.
결국 복잡한 작업은 AI에게 맡기기보단 사람이 직접 하는 경우가 많아졌습니다. 하지만 이렇게 되면 AI의 도움을 받는 부분이 줄어들고, 결국 생산성 향상도 제한적일 수밖에 없습니다.
이 문제를 해결하기 위해 등장한 개념이 하네스 엔지니어링입니다.
하네스 엔지니어링을 적용하면 에이전트를 역할이 분리된 TF처럼 운영할 수 있습니다. 큰 작업은 잘게 쪼개고, 구현 담당, 검증 담당 에이전트가 협력하게 만들어 작은 컨텍스트 한계를 극복하고 복잡한 작업도 높은 품질로 완수할 수 있게 됩니다.
사실 하네스 엔지니어링은 완전히 새로운 개념이 아닙니다. 기존에도 많은 개발자들이 컨텍스트 한계를 극복하기 위해 유사한 방법을 사용해 왔으며, 최근 이를 체계화하여 '하네스 엔지니어링'이라는 이름을 붙인 것에 가깝습니다.
핵심 기능 상세
하네스 엔지니어링에서 자주 사용되는 기능은 세 가지입니다. 스킬(Skill), 서브 에이전트(Sub-agent), 포크(Fork). 각각의 역할은 다르지만, 모두 컨텍스트를 효율적으로 관리하기 위한 도구라는 공통점이 있습니다.
스킬 (Skill)
작업 시 참고해야 할 지침, 라이브러리 사용법, 주의 사항 등을 저장해두는 기능입니다. 상황에 따라 동적으로 불러와지는 프롬프트로, 가장 단순하게 작동합니다. 예를 들어, 프로젝트에서 사용하는 API 스펙을 스킬로 정의해두면 관련 작업 시 자동으로 참조됩니다.
서브 에이전트 (Sub-agent)
특정 작업을 하위 에이전트에게 위임하는 기능입니다. 메인 에이전트가 하위 에이전트에게 지시하는 방식으로 작동하며, 직원에게 일을 맡기는 것과 비슷합니다. 하위 에이전트는 별도의 세션에서 작업을 수행한 뒤 결과만 메인 세션에 전달하고 소멸하므로, 메인 세션의 컨텍스트를 거의 소모하지 않습니다.
코드 리뷰에 특히 적합합니다. 구현 맥락 없이 제3자의 시선에서 코드를 평가할 수 있고, 가볍게 시작할 수 있기 때문입니다.
다만, 일상에서도 '설명하느니 차라리 내가 하는 게 낫겠다' 싶은 일이 있듯이, 짧은 지시만으로 맥락을 충분히 전달하기 어려운 고관여 작업에는 적합하지 않습니다. 이런 경우에 사용하는 것이 포크입니다.
포크 (Fork)
현재 대화 세션의 컨텍스트를 그대로 복제하여 새로운 분기를 만드는 기능입니다. 동일한 이해도를 가진 상태에서 시작하기 때문에, 이전 맥락을 다시 설명할 필요 없이 곧바로 작업에 착수할 수 있습니다.
설계를 깊이 논의하거나 리서치를 진행한 뒤, 그 양질의 맥락을 보존한 채로 후속 작업을 진행해야 할 때 유용합니다. 코드 리뷰 반영, 설계 의도 문서 작성, UX 세부 논의 등이 대표적인 활용 사례입니다.
코드 리뷰 자동화 파이프라인
앞서 소개한 기능들을 실전에서 어떻게 조합할 수 있을까요? 대표적인 사례로 코드 리뷰 자동화 파이프라인을 소개합니다. 저는 아래 그래프와 같은 구성의 하네스를 사용하고 있습니다.
코드 리뷰 파이프라인을 통해 품질을 충분히 끌어올리면, 구현 뒷단의 리뷰 과정에서 사람의 개입을 완전히 제거할 수 있습니다. 사람은 앞단의 설계 논의에만 집중하게 되고, 개발 프로세스의 큰 병목이 사라집니다. 결과적으로 코드 작성 자체를 효율화하는 것보다 더 큰 생산성 향상을 기대할 수 있습니다.
물론 이 정도의 자동화 수준에 도달하는 것은 쉽지 않습니다. 사람의 개입을 완전히 제거하기 위해선 AI가 사람과 거의 동일한 수준의 리뷰를 해야하며, 이에 대한 구성원들의 신뢰가 선행되어야만 합니다. 제가 파이프라인 컨설팅을 진행하는 경우 이 부분을 해결하기위해 고객사 개발자가 AI의 리뷰와 사람의 리뷰를 구분하지 못할 때까지 반복적으로 파이프라인을 튜닝하는 작업을 거칩니다.
결론적으로 AI를 통한 코드 리뷰 완전 자동화는 충분히 도달가능한 영역입니다. 그런데 왜 아직 많은 개발자들이 AI 코드 리뷰에 완전히 의존하지 못하고 있을까요?
왜 AI 코드 리뷰는 아직 부족한가
이미 AI 코드 리뷰를 활용하는 사람은 많지만, 대부분 전적으로 신뢰하지는 못하고 있습니다. 이는 AI의 리뷰가 사람보다 품질이 떨어지기 때문이며 그 이유는 대부분 두 가지 맥락이 빠져 있기 때문입니다.
- 깔끔한 코드에 대한 기준: 기술 조직 구성원들이 암묵적으로 공유하고 있지만, 대부분 문서화되어 있지 않은 코드 스타일과 품질 기준입니다.
- 설계자의 구체적인 의도: 여러 구현 방법 중 왜 이 방식을 선택했는지에 대한 판단 근거입니다. PR 본문에도 세세하게 적히지 않는 경우가 많습니다.
이 두 가지 맥락 공백을 해결하면 AI 코드 리뷰의 품질이 극적으로 향상됩니다. 근거 없는 취향 리뷰가 아니라, 팀이 합의한 기준에 기반한 리뷰가 가능해집니다.
평가 기준 만들기
첫 번째로 깔끔한 코드 기준 맥락 공백을 해결하기 위해 두 가지 문서를 필요합니다.
코드 컨벤션(code-convention.md): 어떤 작업에서든 참고해야 할 조직의 코딩 스타일 지침입니다. 변수명 규칙, 에러 처리 방식 등이 포함됩니다. 프레임워크 표준을 따르는 경우 뻔한 내용을 반복할 필요는 없고, 조직 고유의 규칙만 기록하면 됩니다.
ADR(Architecture Decision Record): '우리 조직은 어떤 설계를 지향하는가'를 담은 문서입니다. 어떤 상황에서 어떤 아키텍처 결정을 했고, 그 이유는 무엇인지를 기록합니다. 개인 개발자도 AI를 위해 ADR을 작성하는 것이 좋습니다.
다만 ADR 문서가 방대해질 경우, 진행하는 작업과 관련없는 내용이 과하게 포함될 가능성이 있습니다. 여기서 서브 에이전트를 활용합니다. 먼저 서브 에이전트가 작업 설계를 분석하여 관련 ADR 항목만 추출하고, 코드 컨벤션과 합쳐 해당 작업에 특화된 평가 기준 문서를 자동으로 생성합니다. 일종의 RAG처럼 서브 에이전트를 활용하는 방식입니다. 결과적으로 구현 에이전트와 리뷰 에이전트는 서브에이전트가 생성한 문서를 기준으로 코드를 생성 및 평가하게 됩니다.
설계 의도 문서화
두 번째 맥락 공백은 설계 의도입니다. 대부분의 작업에는 여러 구현 방법이 존재하고, 그중 현재 상황에서 최적의 선택지를 고르는 것이 핵심입니다. 때문에 이 '왜 이 설계를 선택했는가'를 모른다면 코드를 평가할 수도 없습니다.
설계 의도 문서를 작성할 때는 포크 기능을 활용합니다. LLM과 대화하며 요구 사항과 설계를 확정한 뒤, 포크로 분기하여 별도 세션에서 설계 의도 문서를 작성하는 것입니다. 이미 컨텍스트에 있는 정보를 정리하는 작업이므로 메인 세션의 컨텍스트를 소모하지 않기 위함입니다.
리뷰 반영 시 주의사항
많은 개발자들이 리뷰 반영 시 새로운 세션을 생성하는데요, 절대 이렇게 하시면 안 됩니다. 리뷰 반영은 반드시 보존된 메인 세션을 활용해야 합니다. 작업에 대해 가장 깊이 이해한 상태의 컨텍스트이기 때문입니다. 새로운 세션을 열면 이 맥락이 유실되어, 리뷰에 대해 정확한 판단이 어려워질 수 있습니다.
따라서 작업 명세 작성, QA 등 부수적인 작업은 포크하여 별도로 진행하고, 메인 세션의 컨텍스트는 리뷰 검토 및 반영을 위해 보존해야 합니다. 그래야 가장 핵심적인 컨텍스트만 담긴채로 구현/개선을 진행할 수 있습니다.
컨텍스트에 핵심 내용만 담아야하는 자세한 이유가 궁금하다면, 다음 글을 참고하시면 좋습니다.
적용 시 고려사항
위 내용이 어렵게 느껴졌다면, 크게 걱정할 필요는 없습니다. 이 수준의 하네스 설정이 모두에게 필요한 것은 아니며, 개념을 이해하는 것만으로도 충분히 가치가 있습니다. 중요한 것은 지금 내 상황에서 이것이 필요한가를 판단하는 것입니다.
가장 중요한 건 '무엇을 만들 것인가'
하네스를 아무리 정교하게 구축해도, 문제 정의와 UX가 좋지 않으면 좋은 서비스가 나오지 않습니다. 아이디어가 아직 모호하거나 검증되지 않은 단계라면, 하네스 구축보다는 결과물을 빠르게 만들어 피드백 루프를 도는 편이 훨씬 유리합니다. 화면만 먼저 만들거나 목업/페이크 테스트를 활용하는 것도 좋은 방법입니다.
입문자를 위한 대안
레플릿(Replit)이나 러버블(Lovable) 같은 서비스는 웹서비스 제작에 특화된 하네스가 이미 내장되어 있는 코딩 에이전트입니다. 이런 도구들을 경험해보지 않고 Claude Code와 하네스 엔지니어링부터 시작하는 것은 순서가 맞지 않습니다. 높은 자유도가 꼭 필요한 상황이 아니라면, 먼저 이러한 서비스를 활용해보는 것을 권장합니다.
하네스 엔지니어링의 의의
크고 복잡한 작업을 높은 품질로 완수해야 하는 상황이라면, 하네스 엔지니어링을 도입할 가치가 충분히 있습니다.
좋은 하네스를 구축하면 다음과 같은 효과를 기대할 수 있습니다.
- 더 나은 설계와 코드 품질을 달성할 수 있습니다.
- 버그 수정 프롬프트 반복 등 개발자의 반복 개입이 줄어듭니다.
- 개발자는 문제 정의와 설계에 집중하고, 구현과 검증의 반복은 에이전트에게 맡길 수 있게 됩니다.
이 글을 통해 하네스 엔지니어링의 개념과 실제 적용 사례를 이해하고, 자신의 프로젝트에 어떻게 활용할 수 있을지 고민해보는 계기가 되었으면 좋겠습니다.
마치며
많은 개발팀이 코드 정합성을 사람의 개입으로 해결하려고 하지만, 이제는 전략을 바꿔야할 때입니다.
직원이 실수를 자주한다고해서, 사장인 내가 매번 검토하고 수정해야할까요? 매뉴얼을 제공하고, 스스로 점검할 수 있는 체계를 만들어주는 것이 더 효율적일 것입니다.
코딩 에이전트도 마찬가지입니다. 불안함을 인간의 개입으로 해결하기보단, 정확한 코드를 생성하고 강제하는 체계를 만드는데 집중해보세요. 그때 비로소 인간 본연의 업무인 문제 정의와 설계에 집중할 수 있게 될 것입니다.
감사합니다.
💡 실전 적용 TIP
- 구현 작업 완료 시 컨텍스트가 약 40% 소모되는 것이 이상적입니다.
- 메인 세션은 티켓(기능) 단위로 생성하고 관리합니다.
- 프로젝트 상황에 맞는 스킬, 서브 에이전트를 맞춤으로 추가해보세요.
