최근 AI 에이전트 관련 글을 읽다 보면 Harness Engineering이라는 표현이 자주 보입니다. 처음에는 새로운 유행어처럼 느껴졌지만, 실제로 AI 코딩 도구를 매일 쓰다 보니 이 표현이 꽤 정확하다고 느끼게 됐습니다.
모델 자체의 성능도 중요하지만, 모델이 어떤 문서를 읽고, 어떤 도구를 쓸 수 있고, 어떤 순서로 생각하고, 어디까지 수정할 수 있는지를 정하는 주변 구조가 결과물의 품질을 크게 좌우하게 됩니다.
제게 하네스 엔지니어링은 AI를 더 똑똑하게 만드는 일이 아니라, AI가 덜 제멋대로 일하게 만드는 일에 가깝습니다.
개인적으로는 앞으로 AI 코딩의 차이가 모델 선택만으로 결정되지는 않을 것이라 생각합니다. 같은 모델을 써도 결과가 달라진다면, 차이는 프롬프트 한 줄보다 모델이 일하는 환경에서 더 크게 납니다.
어떤 프로젝트에서는 꽤 괜찮은 결과가 나오고, 어떤 프로젝트에서는 계속 만족하지 못하는 코드가 작성됐습니다. 같은 도구를 쓰는데도 결과가 달랐습니다.
다만 이 말이 모든 팀원이 같은 방식으로 AI를 써야 한다는 뜻은 아닙니다. 요즘은 Spec-Driven Development처럼 명세를 먼저 고정하는 방법론이나, gstack처럼 워크플로우를 강하게 구조화하는 도구도 등장하고 있습니다. 이런 흐름은 분명 유용하지만, 팀원마다 개발 방식에는 각자의 취향이 있습니다. 저는 좋은 하네스가 이 취향을 덮어쓰는 방향이 아니라, 좋은 결과를 내기 위한 최소한의 공통 기준을 제공하는 방향이어야 한다고 생각합니다.
아래는 하네스 엔지니어링에 대한 일반적인 정의라기보다, 제가 AI 코딩 에이전트를 사용하며 겪은 시행착오와 지금의 워크플로우를 정리한 기록입니다.
하네스를 어떻게 정의하고 있나
제가 이해한 하네스는 간단합니다.
모델이 아닌 모든 것이 하네스입니다.
조금 더 풀어 말하면, 모델이 좋은 결과를 내도록 둘러싸고 있는 코드, 문서, 도구, 실행 환경, 검증 루프 전체를 하네스라고 보고 있습니다.
예를 들면 이런 것들이 모두 하네스입니다.
- Skills, MCP, Tools
- AGENTS.md, CLAUDE.md
- lint, test, build, CI
- 코드 리뷰 절차
- 서브에이전트와 모델 라우팅
- 파일 시스템, 샌드박스, 브라우저 같은 실행 환경
LangChain의 Agent Harness 글에서도 에이전트를 모델 + 하네스로 설명합니다. 모델 자체는 텍스트를 입력받아 텍스트를 출력할 수 있지만, 상태 유지, 도구 실행, 파일 수정, 피드백 루프는 하네스가 제공하는 영역입니다.
OpenAI의 하네스 엔지니어링 글에서도 비슷한 방향을 이야기합니다. 하나의 거대한 AGENTS.md에 모든 규칙을 넣기보다, AGENTS.md는 맵처럼 두고 실제 지식은 구조화된 docs/에 쌓아 에이전트가 필요한 정보를 찾아가게 만드는 방식입니다.
저에게는 이 정의가 가장 실용적입니다. 모델을 바꾸지 않고도 결과 품질을 개선할 수 있는 지점이 어디인지 명확해지기 때문입니다.
물론 이 글은 하네스의 모든 영역을 다루지는 않습니다. 제가 실제로 많이 다듬어본 부분은 크게 두 가지였습니다. 하나는 개인 워크플로우에 맞춘 Skills이고, 다른 하나는 repo와 팀에 공통으로 적용되는 문서와 규칙입니다.
왜 하네스가 필요한가
하네스를 만드는 가장 큰 이유는, 메인 모델에게 어떤 프롬프트를 적더라도 일정 수준 이상의 품질을 보장하기 위해서입니다.
하네스가 없으면 모델은 기본적으로 본인에게 학습된 패턴과 현재 대화에 들어온 정보만으로 코드를 작성합니다. 그 모델이 아무리 좋아도, Repository의 컨벤션, 최근 의사결정, 팀의 취향, 피해야 하는 패턴까지 항상 정확히 알 수는 없습니다.
그래서 하네스가 약하면 다음과 같은 문제가 자주 생깁니다.
- 기존 코드 스타일과 맞지 않는 코드가 작성됩니다.
- 작은 요청인데도 수정 범위를 과하게 크게 잡습니다.
- 로컬 문서를 읽지 않고 모델의 일반론으로 판단합니다.
- 테스트를 추가해야 할 곳과 추가하지 않아도 될 곳을 구분하지 못합니다.
- 사용자의 진짜 의도보다 프롬프트에 적힌 표면적인 문장만 따라갑니다.
특히 코딩 에이전트는 "그럴듯한 코드"를 빠르게 만들 수 있기 때문에 더 위험합니다. 사람 개발자라면 저장소를 훑고 맥락을 맞추는 데 시간을 쓰겠지만, 모델은 하네스가 강제하지 않으면 곧바로 결론을 내리려는 경향이 있습니다.
저에게 하네스는 모델을 제한하는 장치가 아닙니다. 모델이 제멋대로 잘못 똑똑해지는 일을 줄이는 장치에 가깝습니다.
AI가 만든 코드는 종종 동작은 하지만, 제가 생각하는 좋은 코드와는 거리가 있을 때가 있습니다. 불필요한 추상화를 만들거나, 기존 코드와 스타일이 다르거나, 요청하지 않았던 리팩터링을 함께 수행하는 식입니다. 그래서 저는 하네스를 "AI를 잘 쓰기 위한 장치"이기 전에, 개발자가 반복적으로 좋은 판단을 하게 만드는 환경으로 보고 있습니다.
처음 접한 하네스: oh-my-opencode
제가 처음으로 하네스라는 감각을 강하게 느낀 건 oh-my-opencode를 접했을 때였습니다.
당시 인상 깊었던 점은 역할을 모델별로 분리하는 구조였습니다.
- 코드 작성
- 문서 탐색
- 플랜 작성
- 코드 리뷰
각 작업을 하나의 메인 모델에게 전부 맡기지 않고, 역할별로 분리해서 수행시키는 방식이었습니다. 이 구조를 보고 처음으로 프롬프트 엔지니어링을 넘어 다음 단계의 AI 코딩을 생각하게 되었습니다.
다만 현실적인 문제도 있었습니다.
Claude, ChatGPT 계정 기반으로 연결하면 계정 제재 리스크가 있었고, API 기반으로 연결하면 비용이 너무 컸습니다. 구조는 매력적이었지만, 개인 워크플로우에 지속적으로 붙여두기에는 부담이 컸습니다.
여기서 배운 것은 역할 분리 자체보다도, 좋은 구조가 실제로 지속 가능한 비용 안에 있어야 한다는 점이었습니다. 아무리 정교한 하네스라도 매번 쓰기 부담스러우면 일상적인 개발 흐름에는 붙지 못합니다.
Superpowers에서 배운 것
이후에는 superpowers를 사용하게 됐습니다.
Superpowers에서 가장 좋았던 점은 제가 쓴 허접한 프롬프트를 바로 실행하지 않고, 먼저 브레인스토밍을 통해 숨은 의도를 찾아준다는 점이었습니다. 제가 쓰는 프롬프트가 항상 체계적이진 못했습니다. "이거 좀 고쳐줘"라고 말했지만, 머릿속에는 "수정 범위는 작았으면 좋겠고, 기존 스타일은 유지해야 하고, 테스트는 필요한 범위만 하고, 영향 범위와 검증 시나리오까지 알려주면 좋겠다" 같은 조건이 숨어 있었습니다.
이때 superpowers는 질문을 통해 모호한 부분을 드러내고, 작업을 더 구체적인 형태로 바꿔줬습니다.
또 하나 좋았던 점은 서브에이전트를 활용한다는 점이었습니다. 플랜 작성, 코드 리뷰, 품질 검토 같은 작업을 메인 모델의 컨텍스트를 오염시키지 않고 분리해서 처리할 수 있었습니다.
이 경험을 통해 하네스가 단순한 자동화가 아니라, AI가 항상 비슷한 패턴으로 일하게 만드는 강력한 플러그인이라는 걸 느꼈습니다.
다만 단점도 있었습니다.
작은 수정 요청에도 변경이 너무 커지는 경우가 있었습니다. 예를 들어 5줄짜리 함수를 고쳐달라고 했는데, 200줄짜리 테스트 코드가 함께 붙은 적이 있었습니다. 틀린 방향은 아니었지만, 막상 PR처럼 바라보면 “이걸 리뷰해야 하나?”라는 생각이 먼저 들었습니다.
깊은 브레인스토밍 이후 나온 결과가 만족스럽지 않은 경우도 있었습니다. 특히 할당량이 제한된 환경에서는 브레인스토밍 자체에 많은 토큰을 쓰는 것이 아깝게 느껴졌습니다.
결국 좋은 하네스는 "항상 많이 생각하게 하는 것"이 아니라, 작업의 크기에 맞게 생각의 깊이를 조절하게 해야 합니다. 이때부터 "AI에게 많이 생각하게 하는 것"과 "좋은 엔지니어링 결과를 만드는 것"이 같은 말은 아니라고 보게 됐습니다.
카파시의 가이드에서 배운 최소 수정의 힘
이후 Andrej Karpathy가 언급한 AI 코딩 실패 패턴을 바탕으로 만든 skills 저장소를 접했습니다.
기억에 남는 건, 내용이 60줄 정도의 Markdown에 불과했는데도 효과가 꽤 컸다는 점입니다. 핵심은 단순했습니다.
- 코드 작성 전에 먼저 생각합니다.
- 추측하지 않습니다.
- 필요한 가장 작은 범위만 수정합니다.
- 관련 없는 리팩터링을 하지 않습니다.
- 검증 가능한 목표를 세웁니다.
이 가이드를 적용하자 모델이 작은 요청에 과하게 큰 변경을 만드는 일이 줄었습니다. 코드 스타일이 크게 흔들리는 일도 줄었습니다.
여기서 배운 점은 하네스가 꼭 거대한 시스템일 필요는 없다는 것이었습니다. 잘 쓴 Markdown 한 장도 충분히 하네스가 될 수 있습니다. 중요한 건 모델에게 "어떻게 일해야 하는지"를 반복적으로 주입하는 것입니다.
특히 마음에 들었던 점은, 이 가이드가 모델을 더 똑똑하게 보이게 만들기보다 더 조심스럽게 만들었다는 점입니다. 저는 AI가 "멋진 해결책"을 들고 오는 것보다, 기존 코드의 모양을 먼저 존중해주는 쪽을 더 좋아합니다. 새 추상화를 만드는 능력보다, 안 바꿔도 되는 코드를 안 건드리는 능력이 더 중요하다고 생각합니다.
Grill Me와 질문의 가치
비슷한 시기에 Matt Pocock의 grill-me도 접했습니다.
이 도구는 superpowers의 브레인스토밍과 비슷하게, 사용자의 요청에서 모호한 부분을 찾아 질문해주는 방식이었습니다.
항상 메인 모델에게 체계적인 프롬프트를 작성하기는 어려웠습니다. 실제 작업 중에는 "이거 이상한데?", "이 부분 좀 고쳐줘" 처럼 느슨하게 요청하는 경우가 더 많았습니다.
그럴 때 grill-me는 제가 놓친 조건을 다시 묻고, 문제를 더 선명하게 만들어줬습니다.
이 경험 덕분에 하네스에는 "질문하는 단계"도 필요하다고 보게 됐습니다. 좋은 질문은 작업을 늦추는 게 아니라, 잘못된 방향으로 빠르게 달리는 일을 막아줍니다.
물론 모든 요청에 깊은 인터뷰가 필요한 건 아닙니다. 오타 수정이나 명확한 CSS 수정처럼 물을 가치가 낮은 작업도 있습니다. 그래서 지금은 작업의 모호도에 따라 질문의 깊이를 조절하는 쪽을 선호합니다.
이 부분도 결국 절차의 강도 문제라고 생각합니다. 질문은 좋은 하네스의 중요한 기능이지만, 모든 작업을 회의처럼 만들면 안 됩니다. 좋은 질문은 사용자의 사고를 대신하는 것이 아니라, 사용자가 놓친 결정을 다시 돌려주는 역할이어야 합니다.
나만의 Skills로 옮겨가기
여러 도구를 써본 뒤에는 일부 외부 skills를 제거하고, 직접 사용하는 skills를 만들기 시작했습니다.
ban-dal/skills에 정리해두고 있고, 지금은 기존에 써본 도구들의 장점만 가져와 제 워크플로우에 맞게 커스텀해서 사용하고 있습니다.
직접 Skills를 만들면서 가장 신경 쓰게 된 부분은 SKILL.md의 description이었습니다. 결국 메인 모델은 description을 보고 "이 Skill을 지금 써야 하는가?"를 판단합니다. description이 흐리면 Skill이 의도한 상황에 사용되지 않거나, 반대로 필요 없는 상황에 호출되기도 했습니다. description이 명확할 때는 별도 지시 없이도 메인 모델이 스스로 Skill을 잘 사용했습니다.
다만 모든 규칙을 개인 Skills에 넣지는 않았습니다. repo와 팀에 공통으로 적용되어야 하는 내용은 repo의 .docs/에 적어두고, 모든 개발자가 AI를 쓸 때 같은 기준을 참조할 수 있게 했습니다.
예를 들면 이런 것들입니다.
- 폴더 구조
- 팀의 리팩터링 규칙
- 디자인 시스템 Skills
개인 Skills는 제가 일하는 방식을 모델에게 알려주는 장치에 가깝고, repo 문서는 팀이 합의한 기준을 모델에게 알려주는 장치에 가깝습니다. 둘을 분리해야 개인의 취향과 팀의 규칙이 섞이지 않습니다.
제가 중요하게 본 기준은 다음과 같습니다.
- 작은 작업은 작게 처리하게 할 것
- 큰 작업은 먼저 계획하고 검증하게 할 것
- 모호한 요청은 질문하게 할 것
- 코드 수정 전 로컬 문서를 우선 읽게 할 것
- 모델의 일반론보다 저장소 컨벤션을 우선하게 할 것
- 리뷰와 구현을 분리할 것
Skills도 유지보수해야 한다
AI 모델은 계속 업그레이드되고 있고, 그에 맞춰 Skills도 계속 업데이트해야 합니다. Anthropic도 Claude Opus 4.8 소개 글에서 에이전틱 작업의 신뢰성, 판단력, 불확실성 표시가 개선됐다고 설명합니다.
이런 변화가 쌓이면 예전 Skills에 적어둔 지침 중 일부는 더 이상 필요하지 않을 수 있습니다. 반대로 모델이 더 큰 작업을 수행할 수 있게 되면, 권한 관리, 검증 방식, 작업 범위 제어처럼 새로 추가해야 하는 지침도 생길 것입니다. 결국 Skills는 한 번 잘 써두고 끝나는 문서가 아니라, 모델의 변화에 맞춰 계속 정리해야 하는 워크플로우 문서에 가깝습니다.
그래서 모델이 좋아질수록 하네스의 역할은 사라지기보다 계속 달라집니다. 예전에는 모델의 부족한 점을 보완하기 위한 지침이 중요했다면, 앞으로는 더 큰 작업을 맡길 때 어떤 제약과 검증 루프를 둘지 설계하는 일이 더 중요해질 것입니다.
다만 팀 단위로 하네스를 적용한다면 더 조심스러워야 한다고 생각합니다. 개인 워크플로우에서는 제 취향에 맞게 강하게 커스텀해도 괜찮지만, 팀의 기본값이 되는 순간 그 하네스는 누군가의 개발 방식을 제한할 수 있습니다. 그래서 팀 하네스는 "모두가 따라야 하는 취향"이 아니라 "모두가 동의할 수 있는 품질 기준"에 가까워야 합니다.
지금 내가 생각하는 좋은 하네스
지금 제가 생각하는 좋은 하네스는 모델을 강하게 묶어두는 시스템이 아닙니다.
대신 다음을 잘하게 만드는 시스템입니다.
- 작업 전에 필요한 문서를 읽습니다.
- 요청의 모호도를 판단합니다.
- 작은 작업은 작은 변경으로 끝냅니다.
- 큰 작업은 계획, 구현, 검증을 분리합니다.
- 모델의 일반론보다 로컬 맥락을 우선합니다.
- 검증 가능한 결과를 남깁니다.
- 사용자가 원하지 않은 리팩터링을 하지 않습니다.
반대로 모든 요청에 브레인스토밍, 플랜, 리뷰, 테스트를 강제하는 하네스는 좋은 기본값이 아니라고 생각합니다. 복잡한 기능 추가에는 도움이 되지만, 작은 수정에서는 모델보다 하네스가 더 큰 비용이 됩니다.
결국 하네스 엔지니어링은 AI에게 일을 "시키는" 기술이라기보다, AI와 함께 일하는 방식을 설계하는 기술입니다.
프롬프트를 잘 쓰는 것도 여전히 중요합니다. 하지만 프롬프트만으로는 매번 같은 품질을 보장하기 어렵습니다. 반면 하네스는 좋은 프롬프트를 매번 사람이 직접 떠올리지 않아도, 모델이 일정한 기준으로 움직이게 해줍니다.
그래서 저는 하네스를 도구 모음이나 프롬프트 묶음으로만 보지 않습니다. 하네스는 어떤 개발 습관을 기본값으로 둘지 정하는 일이고, 결국 "내가 좋은 코드라고 생각하는 것"을 AI와 함께 일하는 환경에 반영하는 일이라고 생각합니다.
마치며
결국 제 관심사는 AI가 코드를 얼마나 빨리 쓰는지가 아니라, 좋은 코드가 반복해서 나올 수 있는 조건을 만드는 일에 더 가깝습니다.
어떤 문서를 먼저 읽게 할지, 언제 질문하게 할지, 어떤 도구를 허용할지, 언제 테스트를 돌릴지, 어느 정도까지 수정하게 할지. 이런 것들을 설계하는 일이 결국 하네스 엔지니어링이라 생각합니다.
그래서 저는 앞으로도 모델이 일하는 환경을 더 많이 다듬게 될 것 같습니다. 좋은 코드가 우연히 나오게 두기보다, 좋은 코드가 나올 확률이 높은 환경을 만들고 싶습니다.
참조