모델은 쉬웠다. 어려운 건 그 주변이었다
AI 코딩 에이전트 도입 프로젝트를 시작하면 대부분 같은 자리에서 막힌다. 모델 선택이 아니다. 모델은 API 키 하나면 된다. 막히는 건 그다음이다. "이 에이전트가 방금 한 짓을 믿어도 되나?" "다음엔 같은 실수를 안 할 거라는 보장이 있나?" "이거 프로덕션에 붙여도 되나?"
dev.to의 BypassHire 팀 사례가 정확히 그 문제를 건드린다. 구직 지원 시간을 45분에서 5분으로 줄이는 AI 툴을 만들면서, 팀이 가장 많은 시간을 쏟은 건 LLM 선택이나 프롬프트 튜닝이 아니었다. 에이전트 주변의 구조—Martin Fowler가 최근 명명한 Harness Engineering—를 설계하는 데 스프린트의 상당 부분이 들어갔다.
Harness란 무엇인가: 모델 말고 나머지 전부
Fowler의 정의는 간결하다. 하네스(Harness)는 에이전트 셋업에서 모델 자체를 제외한 모든 것이다. 또 다른 학습 레포지토리는 이걸 공식으로 표현한다.
Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions
모델은 결정한다. 하네스는 실행한다. 모델은 추론한다. 하네스는 맥락을 제공한다. 비유하자면, 모델은 드라이버고 하네스는 차량이다. 드라이버가 아무리 뛰어나도 브레이크 없는 차에 태우면 사고 난다.
그리고 Harness Engineer의 역할은 명확하다. 모델이 생성을 담당하는 동안, 생성이 신뢰 가능하도록 유지하는 시스템을 담당하는 것이다.
두 가지 제어 레이어: Guides와 Sensors
Fowler는 하네스 메커니즘을 두 범주로 나눈다. Guides(가이드)는 피드포워드 제어다—에이전트가 코드를 한 줄 쓰기 전에 행동을 형성한다. Sensors(센서)는 피드백 제어다—생성된 결과물을 관찰하고 오류를 잡아낸다.
Guides 실전 예시
BypassHire 팀은 CLAUDE.md를 1차 가이드로 배치했다. 프로젝트 레벨 지시 파일로, 팀 컨벤션, 강제 워크플로우 순서(/plan → /tdd → /build-fix → /code-review → /verify), 보안 규칙, 커버리지 임계값이 인코딩돼 있다. 매 세션마다 Claude가 이 파일을 먼저 읽는다. 게임의 규칙을 코드 생성 전에 확립하는 것이다.
단일 범용 에이전트 대신, 팀은 역할별 서브 에이전트 위원회를 구성했다. architect, planner, tdd-guide, code-reviewer, security-reviewer, build-error-resolver. 각각 책임 범위가 한정돼 있다. security-reviewer는 OWASP 스코프로만 작동하며, auth 라우트·DB 쿼리·Claude API 프롬프트에 닿는 모든 PR에 자동으로 실행된다. 전문화는 에이전트가 추론해야 할 표면적을 줄이고, 그만큼 신뢰성을 높인다.
Sensors 실전 예시
Sensors는 세션 라이프사이클에 훅(hook)으로 배선된다.
- 편집 즉시 린트:
.ts/.tsx파일이 수정될 때마다 ESLint와 Prettier가 즉각 실행된다. 피드백 루프가 밀리초 단위로 압축된다. - 종료 시 테스트 가드: Claude가 세션을 닫으려 할 때
npm test가 자동으로 돈다. 테스트 실패 시 세션 종료가 구조적으로 차단된다. "나중에 고칠게요"가 아예 불가능해진다. - 추론 기반 센서: linter가 볼 수 없는 아키텍처·행동적 이슈는 code-reviewer와 security-reviewer 서브 에이전트가 담당한다. 계산적 센서(빠르고 결정적)와 추론적 센서(느리지만 의미론적으로 풍부)를 함께 배치하는 구조다.
Harnessability: 코드베이스 자체가 하네스의 기반이다
Fowler가 짚는 또 하나의 개념이 Harnessability다. 모든 코드베이스가 하네스를 동일하게 받아들이지 않는다. 에이전트 센서가 정확하게 작동하려면 시스템 자체가 기계 판독 가능한 계약을 제공해야 한다.
BypassHire 팀이 TypeScript, Prisma, Zod, Next.js App Router를 선택한 건 트렌드 때문이 아니었다. 강타입 시스템, 스키마 검증 ORM, 모든 API 경계의 런타임 입력 검증—이것들이 인간 리뷰어와 에이전트 센서 모두에게 정밀하고 기계 판독 가능한 계약을 제공한다. 하네스는 그것이 그립(grip)하는 표면만큼만 좋다.
Steering Loop: 하네스가 스스로 진화하는 구조
Fowler의 가장 중요한 통찰은 스티어링 루프다. 하네스는 설계하고 끝이 아니다. 반복되는 실패를 모니터링하고 그에 대응해 제어를 조여가는 인간의 루프가 필요하다.
BypassHire 첫 스프린트 이후, 팀은 Claude가 auth 패턴에서 간헐적으로 표류한다는 걸 발견했다. 대응은 즉각적이었다. @clerk/nextjs/server의 직접 임포트를 금지하는 ESLint 규칙을 추가해, 모든 인증이 src/lib/auth 래퍼를 통하도록 강제했다. 하네스가 관찰 결과를 흡수해 더 스마트해진 것이다.
관찰 → 인코딩 → 강제(Observe → Encode → Enforce). 이것이 하네스 엔지니어의 실제 일이다.
로컬 AI의 등장: 하네스 설계에 새로운 변수
한편, Harness Engineering을 복잡하게 만드는 변수가 하나 더 추가됐다. byCode 프로젝트는 25년 경력 개발자가 "우리는 편의를 위해 지적 재산과 코드베이스 프라이버시를 적극적으로 거래하고 있다"는 문제의식에서 만든 100% 로컬 AI IDE다. Ollama를 통해 로컬 LLM을 직접 오케스트레이션하고, 코드·프롬프트·레포지토리 컨텍스트가 자신의 하드웨어 밖을 나가지 않는다.
팀 입장에서 이건 단순한 도구 선택 문제가 아니다. 클라우드 기반 AI 코딩 어시스턴트를 쓴다는 건 팀의 코드베이스가 지속적으로 외부로 전송된다는 의미다. 엔터프라이즈 코드, 독점 알고리즘, 컴플라이언스 의무가 있는 환경에서는 이게 심각한 보안 이슈가 된다. 반면 로컬 LLM은 프라이버시를 보장하지만, 모델 성능과 하네스 통합 복잡도라는 트레이드오프가 따른다.
AI 코딩 에이전트의 하네스를 설계할 때, 어느 레이어에서 실행하느냐는 이제 아키텍처 결정 사항이다.
팀 리드가 지금 해야 할 설계 결정들
Harness Engineering은 이론이 아니다. 지금 AI 코딩 에이전트를 운용 중이거나 도입을 준비하는 팀이라면, 다음 질문들이 내일 당장 답이 필요한 것들이다.
1. 가이드 레이어가 있는가? 에이전트가 코드를 생성하기 전에 읽는 팀 컨벤션 파일이 있는가? CLAUDE.md든 AGENTS.md든 형식은 무관하다. 없다면 에이전트는 매번 즉흥 연주를 하는 것이다.
2. 센서 레이어가 배선됐는가? 에이전트가 생성한 결과물을 자동으로 검증하는 훅이 CI/CD에 걸려있는가? "나중에 리뷰"는 구조가 아니다. 구조적으로 불가능하게 만들어야 한다.
3. 스티어링 루프가 돌고 있는가? 에이전트의 실패 패턴을 관찰하고 하네스에 인코딩하는 리듬이 팀에 있는가? 이 루프 없이는 하네스가 진화하지 않는다.
4. 실행 레이어의 보안 결정이 됐는가? 클라우드 API냐 로컬 LLM이냐는 성능 선택이 아니라 보안·컴플라이언스 결정이다. 팀의 코드베이스 민감도에 따라 답이 달라진다.
전망: 하네스 엔지니어가 팀의 핵심 역할이 된다
AI 에이전트가 코드를 자율적으로 생성하는 시대에, 팀 리드의 역할은 변했다. 직접 코드를 쓰는 것보다, 에이전트가 신뢰 가능하게 코드를 쓸 수 있는 구조를 설계하고 진화시키는 것이 더 중요해졌다.
Harness Engineering이 아직 낯선 개념이라면, 이렇게 생각하면 된다. 좋은 에이전트 셋업은 좋은 신입 온보딩과 구조적으로 같다. 규칙을 문서화하고(Guides), 결과물을 자동으로 검증하고(Sensors), 실패에서 배워 규칙을 업데이트한다(Steering Loop). 사람한테 하던 걸 에이전트한테도 하면 된다.
차이는 하나다. 에이전트는 규칙을 구조로 강제하지 않으면 같은 실수를 다음 세션에 그대로 반복한다. 사람은 혼내면 기억하기라도 한다.