카카오 T 주차 하네스 엔지니어링 적용기

작성자: 로빈(지호진), 세일러(문새롬) | 작성일: 2026.06.10

들어가며

안녕하세요. 카카오모빌리티 서비스클라이언트팀에서 주차 서비스를 개발하는 세일러, 로빈입니다. 현재 저희 팀은 주차를 주축으로 전기차, 발레 등 다양한 연계 서비스를 함께 지원하며 개발하고 있습니다.

저희 팀은 급격하게 커지는 서비스 규모와 늘어나는 개발 업무량을 소화하기 위해 AI 코딩 에이전트를 적극적으로 도입해 왔습니다. 하지만 최근 하루가 다르게 새로운 AI 모델과 코딩 도구들이 쏟아져 나오면서 업무 환경 역시 계속해서 바뀌고 있습니다. 어제 쓰던 최신 툴이 오늘은 구식이 될 정도로 기술 발전이 너무 빠르다 보니, 새로운 툴을 학습하고 쫓아가는 것만으로도 벅찰 때가 많았습니다.

하지만 더 큰 고민은, 이렇게 끊임없이 새로운 툴을 도입해 보아도 실무에서의 본질적인 답답함은 쉽게 해소되지 않는다는 점이었습니다. '새로운 모델은 좀 더 똑똑하겠지'라는 기대로 막상 에이전트에게 업무를 맡겨도, 여전히 내 마음처럼 동작하지 않아 답답함을 느끼신 분들이 많으실 겁니다. 간단한 작업에서는 만족스러운 결과를 내놓지만, 실제 운영 중인 서비스에서의 복잡한 코드를 맡기면 의도와 다른 방향으로 구현되거나 일관되지 않은 결과물이 생성되는 경우가 종종 있었습니다.

물론 이러한 결과가 서비스에 그대로 반영된 것은 아닙니다. 개발자는 AI 에이전트가 생성한 코드를 검토하고 필요한 수정을 거쳐 품질을 관리했습니다. 하지만 서비스는 빠르게 확장되고 있었고, 이러한 검토와 보완 과정을 반복해야 하는 상황에서는 이를 진정한 의미의 효율화라고 부르기 어려웠습니다. 이에 저희 팀은 끊임없이 변하는 특정 AI 툴에 종속되지 않고, 에이전트가 보다 일관되고 안정적인 결과물을 도출할 수 있도록 시스템적인 제어 환경을 구축하는 방향으로 접근했습니다.

이 글에서는 프롬프트와 결과물 사이의 불확실성을 없애고, 예측하기 어려운 AI 에이전트를 우리가 원하는 방향으로 일하게 만드는 하네스 엔지니어링(Harness Engineering)의 개념과 그 구조를 소개하고자 합니다.

📚 추천 독자

이 글은 AI 코딩 에이전트를 실무에 도입했지만 결과물이 들쭉날쭉해 답답함을 느끼는 개발자, 복잡한 운영 서비스에 AI 자동화를 안정적으로 적용하고 싶은 팀, 특정 AI 툴에 종속되지 않는 지속 가능한 개발 체계를 고민 중인 엔지니어분들이 읽으시면 더욱 좋아요!

AI 에이전트 코딩에서 겪은 문제들

하네스 엔지니어링을 본격적으로 설명하기에 앞서, 기존에 AI 에이전트에게 개발을 지시하면서 저희가 겪었던 문제들을 먼저 공유하려고 합니다. 코딩 에이전트에게 일을 맡기는 과정은 기대와 달리 생각보다 많은 시간과 노력이 필요했습니다.

작업을 지시하기 전, 개발자는 기본적인 도메인 지식부터 기획서, 디자인 시안, 각종 문서와 논의 기록까지 여러 곳에 흩어져 있는 콘텍스트(Context)를 일일이 모아 프롬프트에 주입해야 했습니다. 에이전트가 초기 계획을 세운 이후에도 "이 기능은 제외해", "이 파일은 수정하지 마"와 같은 예외 조건을 반복적으로 덧붙여야만 했습니다.

작업을 시작한 후에도 예상치 못한 문제들이 발생했습니다. 특정 라이브러리나 구현 규칙을 사용하도록 지시했음에도 이를 제대로 반영하지 못하거나, 기존 코드의 맥락을 정확히 파악하지 못하는 경우가 있었습니다. 또한 변경 범위를 명확히 지정했음에도 관련 없는 파일까지 함께 수정되는 경우가 있었으며, 때로는 개발자의 추가 수정과 검토가 필요한 결과물이 생성되기도 했습니다. 결과적으로 에이전트가 코드를 작성하기 전후로 사람의 지속적인 확인과 검토가 필요했습니다.

이 과정에서 마주한 가장 큰 문제는 에이전트의 실행 흐름을 파악하거나 통제할 수 없다는 점이었습니다. 똑같은 프롬프트를 입력해도 매번 다른 결과가 나왔고, 내부적으로 수많은 에이전트와 스킬이 호출되는 과정에서 대체 어디서 오류가 발생했는지 원인을 찾고 수정 방향을 잡기가 매우 어려웠습니다.

결국 에이전트의 행동을 명확하게 제어할 방법이 없는 상태에서는 '다음번에는 더 나은 결과가 나오겠지'라는 기대에 의존할 수밖에 없었습니다. 동일한 요청에도 결과가 달라질 수 있었기 때문에, 개발자는 매번 결과물을 검토하고 보완해야 했으며 작업 결과를 예측하기 어려운 시행착오가 반복되곤 했습니다.

하네스 엔지니어링이란

이러한 프롬프트와 결과물 사이의 고질적인 '불확실성'을 해결하기 위해 등장한 개념이 바로 하네스 엔지니어링입니다.

Harness: 마구(馬具)

'하네스(Harness)'란 본래 말을 제어하고 수레를 연결하기 위해 사용하는 고삐나 안장 같은 마구를 뜻합니다. 어디로 튈지 모르는 말을 하네스로 안전하게 제어하듯이, 어떻게 동작할지 예측하기 어려운 AI 에이전트를 다양한 시스템적 구성 요소를 통해 안전하고 효율적으로 통제하는 것이 하네스 엔지니어링의 핵심입니다.

3대 구성 요소

하네스는 에이전트를 효과적으로 통제하고 일관된 고품질의 코드를 얻어내기 위해, 크게 3가지 핵심 요소로 구성됩니다.

• Context: 개발자가 매번 프롬프트에 배경지식을 주입하는 대신, 에이전트가 저장소(Repository) 내부의 문서를 스스로 탐색할 수 있도록 '통합 지식 체계'를 제공합니다. 에이전트는 하네스의 워크플로에 따라 작업에 꼭 필요한 도메인 지식과 코딩 규칙만을 능동적으로 찾아 읽고 개발을 시작합니다.
• Control: 검증 레이어를 통해 에이전트의 행동을 시스템적으로 제어하는 장치들을 구성합니다. 원하지 않는 동작은 원천 차단하고, 코드가 잘못되더라도 사람이 개입할 필요 없이 에이전트 스스로 문제를 파악하고 수정해 오도록 통제합니다.
• Observability & Maintenance: 파악하기 어려웠던 에이전트의 모든 의사결정과 실행 흐름을 상세히 기록하여 투명하게 관측할 수 있는 환경을 구축합니다. '어떤 맥락에서 왜 이렇게 코드를 짰는지'를 명확히 파악할 수 있으며, 이 기록을 바탕으로 시스템과 지식 문서를 지속적으로 업데이트합니다.

카카오 T 주차에 하네스 구성하기

이제 앞서 소개한 3대 구성요소를, 카카오모빌리티의 주차 서비스에서는 어떻게 구현했는지 좀 더 자세히 들여다보겠습니다.

Context

콘텍스트란 AI 에이전트가 작업을 수행할 때 필요한 지식을 제공하는 프로젝트 지식 베이스입니다. 과거에는 개발자가 전체 맥락을 인지한 상태에서 필요한 정보만 필터링하여 수동으로 전달해야 했으나, 하네스 엔지니어링에서는 에이전트에게 필요한 정보를 체계적으로 구성하여 즉시 접근할 수 있는 위치에 배치하는 통합된 콘텍스트를 구축해 수동 전달로 인한 여러 불편을 해소했습니다.

보통 하네스 엔지니어링을 소개하는 글에서는 프로젝트를 처음부터 하네스 엔지니어링으로 구축하는 것을 전제로, 개발 과정에서 개발 내용들을 동시에 문서화해 저장함으로써 지식 베이스를 작성하도록 권장합니다. 하지만 저희는 이미 구현되어 운영되고 있는 주차 서비스에 하네스 엔지니어링을 도입하는 것이므로, 기존의 주차 코드에 대한 지식을 먼저 문서로 정리해야 했습니다. 지난 몇 년 동안 이용자들이 원하는 최적의 주차 서비스를 제공하기 위한 꾸준한 노력과 개선의 결과, 구성해야 하는 초기 지식 문서 역시 방대해 수작업으로 작성하기 어려운 분량이었습니다.

저희는 수집 에이전트와 문서화 스킬을 통해 코드 베이스를 단일 진실 공급원으로 삼아 이 문제를 해소했습니다. 수집 에이전트가 코드 베이스를 분석해 지식 후보를 추출하고 문서화 스킬을 통해 도메인 지식, 코딩 스타일, 아키텍처 규칙 등으로 규격화하여 구성합니다.

또, 단순히 문서가 존재하는 것만으로는 에이전트가 읽지 않을 가능성이 높으므로, 실제로 개발할 때도 관련 문서를 참조하게 하는 구체적인 지식 전달 과정을 추가했습니다. 자동화된 개발 과정 내에서, 설계 에이전트가 관련 지식 문서의 경로를 파악하여 계획 문서에 기록하면, 구현 에이전트가 해당 경로의 문서를 읽고 작업을 수행합니다. 또한, 작업의 진행 상태와 의사결정 이력도 지속적으로 기록되어 다음 구현 계획에 참고될 수 있도록 설계했습니다.

Control

컨트롤은 에이전트의 행동을 통제하고 원하는 동작은 강제하며 원치 않는 동작은 금지하는, 대규모 작업 및 장기 실행의 핵심 레이어입니다. 제어 구조의 진입점으로서 메인 실행 구조(harness.md), 이벤트 트리거(hooks/), 반복 작업 스킬(skills/), 서브 에이전트(agents/), 스크립트 실행(scripts/) 등으로 세분되어 있습니다.

개발 작업에서의 제어는 작업과 완료 사이에 검증 레이어를 설치하여 자율적인 피드백 루프를 구축함으로써 이루어집니다. 워크플로 스킬을 통해 에이전트에게 작업을 지시할 때 단순한 구현이 아닌 작업 절차를 준수하도록 요구합니다. 이 절차에 의하면, 구현 에이전트가 구현을 마치면, 스크립트 기반의 수정 범위 검증(1회)과 빌드/테스트 검증(최대 2회), 그리고 리뷰 에이전트를 통한 코드 리뷰(최대 3회)를 거치게 됩니다. 이 과정에서 실패가 발생하면 에이전트 스스로 재작업을 수행하며, 최대 수정 횟수를 초과해 재실패할 때만 사용자에게 알림을 보내도록 워크플로가 구성됩니다.

이 중, 수정 범위를 스크립트를 통해 기계적으로 엄격하게 검증하도록 한 점이 주차 서비스에서 구현한 하네스의 가장 큰 특징입니다. 주차 서비스는 카카오내비, 카카오T 두 개의 앱에 라이브러리 형태로 배포되며, 카카오모빌리티의 다른 여러 서비스와 함께 개발되고 있습니다. 따라서 수정 범위를 엄격하게 지키지 않으면, 여러 서비스에서 동시에 사용하는 파일이 변경되어 자칫 주차 외의 다른 서비스 화면의 동작에 예기치 못한 영향을 줄 수 있는 위험이 있었습니다.

이 문제를 해결하기 위해 하네스 구성 초기에는 워크플로 스킬에서 에이전트가 수정 범위를 반드시 지키도록 지시문을 통해 강하게 요구했습니다. 하지만 에이전트가 많은 작업을 처리하다 보면, 이전에 입력된 지시 사항은 무시되는 현상이 심심치 않게 발생했습니다. 따라서 수정 범위 검증 레이어를 절차 내에 삽입하고, 검증 결과는 에이전트의 자의적인 판단이 아닌 스크립트를 통한 기계적 판정에 따르도록 하여 빠져나갈 구멍 없는 엄격한 검증을 통과하도록 했습니다.

Observability & Maintenance

개발이 자동화될수록 노후화된 코드가 누적되거나 구현과 문서가 일치하지 않는 '콘텍스트의 노후화'가 발생할 수 있습니다. 이를 해결하기 위해 에이전트의 작동을 기록하고 지속적으로 관리하는 진화하는 하네스 체계를 갖췄습니다.

어떤 정책 문서를 읽었는지, 어떤 스킬을 사용했는지, 사용자가 비즈니스 로직에 대해 어떤 지시를 내렸는지 등을 기록하여 에이전트의 행동을 관측할 수 있게 만듭니다. 이렇게 관측된 결과를 바탕으로 안 읽은 지 오래된 문서를 삭제하거나, 작동하지 않는 스킬의 원인을 파악하고, 코딩 스타일 문서를 최신화하는 등 코드 베이스와 지식 문서, 에이전트 스킬을 지속적으로 개선하고 유지보수를 합니다.

마치며

이번 하네스 엔지니어링 도입을 통해 정보는 통제(Context)하고, 결과는 검증(Control)하며, 동작은 기록(Observability)하는 튼튼한 기반을 마련했습니다. 그 결과, 특정 AI 툴에 종속되지 않는 독립적인 '영속적 레이어'를 구축할 수 있었습니다.

AI 모델의 지능이 아무리 발전하더라도, 이를 실제 프로덕션 환경에서 안전하고 효율적으로 다루기 위해서는 고삐(Harness)와 같은 체계적인 제어 장치가 필수적입니다. 이번에 소개한 구조 외에도 저희는 에이전트 기반 개발 자동화를 이루기 위해 다양한 방법을 모색해 나가고 있습니다. AI 에이전트 코딩이 개발 업계의 표준으로 빠르게 확산하고 있는 지금, 하네스 엔지니어링의 구축은 급변하는 AI 개발 업무 환경 속에서 앞으로도 흔들리지 않는 기반이 되어줄 것입니다.