Claw-Code에서 시작하는 Harness Engineering
최근 AI 코딩 업계에서 파급력이 매우 높았던 사건이 하나 있었습니다.
Anthropic의 Claude 내부 소스 코드가 유출된 것입니다.
약 51만 2000줄에 달하는 TypeScript 소스코드가 npm을 통해 유출되었고,
이 사고는 해킹이 아닌 휴먼에러로 인한 것이었습니다.
| src/utils (경로) | 564 (파일 수) | 180,472 (코드 라인 수) |
| src/components | 389 | 81,546 |
| src/services | 130 | 53,680 |
| src/tools | 184 | 50,828 |
| src/commands | 207 | 26,449 |
| src/ink | 96 | 19,842 |
| src/hooks | 104 | 19,204 |
| src/bridge | 31 | 12,613 |
| src/cli | 19 | 12,353 |
| src/screens | 3 | 5,977 |
| src/main.tsx | 1 | 4,683 |
| src/native-ts | 4 | 4,081 |
| src/skills | 20 | 4,066 |
| src/entrypoints | 8 | 4,051 |
| src/types | 11 | 3,446 |
| src/tasks | 12 | 3,286 |
| src/keybindings | 14 | 3,159 |
| src/constants | 21 | 2,648 |
이 과정에서 미출시 기능들과, 차세대 모델, buddy, 정규표현식 활용 등이 드러났습니다.
유출된 내용은 claw-code 저장소에 rust 언어로 재작성돼 올라갔으며,
깃허브 역사상 가장 빠른 스타를 돌파했고 04.07 기준 17만개의 스타를 받았습니다.
claw-code는 유출된 해당 코드를 기반으로 rust로 재작성된 클린룸 프로젝트로,
Claude의 유출본이 아닌 Claude Code의 에이전트 harness 구조를 재구현한 결과물입니다.
이 흐름이 말해주는 것은 분명합니다.
이제는 모델의 성능보다도, 모델을 다루는 시스템의 중요도가 더 높아지고 있다는 것입니다.
이번 claw-code를 계기로 Harness Engineering 개념을 다시 보게 되었습니다.
이번 글에서는 이 하네스 엔지니어링이 무엇인지,
왜 프롬프트나 컨텍스트만으로는 부족한지,
그리고 이를 구현해본 경험을 함께 정리해보려 합니다.
Harness
Harness Engineering 은 2026년 2월 경 빠르게 등장하였습니다.
OpenAI는 OpenAI - Harness engineering: leveraging Codex in an agent-first world를 공개하였고,
리팩터링으로 유명한 마틴 파울러도 하네스를 모델 바깥의 통제/실행 구조로 분석하는 글들을 내놓았습니다.
이는 모델이 똑똑해졌다고 해서, 모델의 실용력이 올라가는 것은 아니라는 점을 시사합니다.
모델은 코드를 생성할 수 있고, 도구를 호출할 수 있으며, 테스트를 돌릴 수도 있습니다.
하지만 그 과정에서
- 무엇을 봐야 하는지
- 무엇을 보면 안 되는지
- 어떤 규칙을 따라야 하는지
- 실패했을 때 어떻게 회귀해야 하는지
를 결정하는 것은 모델 자체가 아니라 그 바깥의 구조이고,이를 결정하는 것이 Harness입니다.
프롬프트, 컨텍스트, 그리고 Harness
하네스를 이해하려면 그 이전의 두 층을 먼저 구분할 필요가 있습니다.
- 프롬프트 엔지니어링
프롬프트 엔지니어링은 AI에게 말을 잘 거는 기술입니다.
요청을 더 구체적으로 쓰고, 형식을 명시하고, 목적과 제약을 문장으로 전달하는 방식입니다.
- 컨텍스트 엔지니어링
컨텍스트 엔지니어링은 AI가 일할 때 필요한 정보를 적절하게 골라 제공하는 기술입니다.
프로젝트 구조, API 문서, 기존 코드, 예시 같은 배경을 얼마나 정확하게 주느냐가 품질을 좌우합니다.
그런데 여기서 한계가 생깁니다.
컨텍스트를 아무리 잘 넣어도 해결되지 않는 문제가 있습니다.
AI가 정보를 알고도 엉뚱한 행동을 하는 경우입니다.
예를 들어 결제 기능을 구현하라고 했는데 DB 스키마를 건드리거나,
보안상 금지된 값을 로그에 남기거나,
프론트엔드에서 하면 안 되는 의존성을 직접 끌어오는 경우가 발생합니다.
이를 개선하고자 나온 것이 Harness 엔지니어링입니다.
하네스는 AI에게 이렇게 해줘라고 부탁하지 않습니다.
이 선을 넘으면 저장이 안 되고,
커밋이 안 되고,
빌드가 실패하게 만들어 권한 부족으로 실행도 안 되게 만드는 구조를 만듭니다.
즉, 에이전트가 실수했을 때 프롬프트를 고치는 것이 아니라,
실패가 반복되지 않도록 구조 (하네스)를 고치는 것입니다.
Harness의 구성요소
제가 지금까지 읽은 자료들과 실제로 체감한 내용을 합쳐보면,
하네스는 대체로 다음과 같은 층으로 이해하는 것이 가장 자연스럽습니다.
1. rules 문서
대표적으로 CLAUDE.md, AGENTS.md 등 각종 rules 문서가 여기에 해당합니다.
이 파일들은 단순한 위키 문서가 아니라,
에이전트가 작업을 시작하기 전에 읽는 운영 규칙에 가깝습니다.
어떤 프로젝트인지,
어떤 금지 사항이 있는지,
테스트를 어떤 순서로 돌려야 하는지,
무엇을 먼저 확인해야 하는지 같은 기준이 이 안에 들어갑니다.
2. Hook, lint, Test
규칙은 읽게 하는 것만으로 충분하지 않습니다.
AI는 읽고도 어길 수 있기 때문입니다.
그래서 린터, 프리커밋 훅, 타입 체크, 테스트, CI/CD 게이트 같은 자동 검증 장치가 필요합니다.
에이전트가 금지된 구조를 만들면 저장 전에 막히고,
커밋 전에 막히고,
빌드 단계에서 막혀야 합니다.
3. 도구와 권한의 경계
하네스는 에이전트에게 하지 말라고 부탁하지 않습니다.
애초에 할 수 없게 금지합니다.
예를 들어
- 특정 폴더는 read-only
- 특정 명령만 허용
- 특정 API만 호출 가능
- 특정 DB 작업은 금지
같은 방식입니다.
프롬프트가 부탁이라면, 권한 경계는 물리적 차단에 가깝습니다.
4. 자동 교정 루프
하네스의 진짜 힘은 규칙을 문서화하는 데만 있지 않습니다.
핵심은 생성 -> 검증 -> 실패 -> 수정 -> 재검증의 자동 교정 루프입니다.
- 에이전트가 코드를 작성
- 훅과 테스트와 CI가 자동으로 검증
- 실패하면 그 실패 메시지가 다시 에이전트에게 회귀
- 에이전트는 그 피드백을 보고 수정
이 루프를 통과할 때까지 반복하는 구조가 실제 생산성의 핵심입니다.
Harness 개발기
이를 위한 토이 프로젝트를 개발하며 구현 속도를 높이기 위해 AI를 적극적으로 도입했습니다.
다만, 단순히 코드를 대신 써주는 도구로 접근하지는 않았습니다.
프로젝트를 개발하며 일부로 서비스를 여러 개로 나누고,
각 계층 구조와 테스트 전략, DB 분리, 책임 경계 같은 제약을 많이 넣었습니다.
이런 환경에서 AI를 프롬프트로만 쓰게 되면 아래와 같은 문제가 쉽게 생깁니다.
- 컨텍스트가 꼬이고
- 같은 설명을 반복하게 되고
- 답변 스타일과 구현 방식이 흔들리고
- 과잉 구현이나 잘못된 계층 침범이 발생합니다
그래서 저는 AI를 활용한 SDD를,
Skill + Plan + Agent를 묶어서 하네스처럼 사용하는 방식으로 개발했습니다.
Agent란?
저장소를 읽고, 관련 파일을 찾으며, 코드 수정 및 테스트 실행을 하는 실행 주체
ChatGPT가 자체 컴퓨터를 사용하여 사용자 대신 처음부터 끝까지 복잡한 작업을 처리합니다.
출처 : OpenAI 에이전트
프로젝트를 진행하며 Agent에게 작업 단위를 나눠 맡겨 개발 속도를 높였습니다.
다만, 기능 하나를 통째로 던지지는 않았습니다.
예를 들어 특정 기능을 구현할 때,
먼저 Agent에게 각 서비스 중 어디까지 변경이 전파되는지 추적하게 하고,
어떤 실패 테스트를 먼저 만들어야 하는지 제안받고,
단위별 최소 구현만 허용했습니다.
단계별로 책임 범위를 쪼개고 각 페이즈별로 커밋하며 형상 관리를 했습니다.
이렇게 Agent를 단순한 코드 생성기가 아니라,
설계된 개발 루프 안에서 움직이는 동료 개발자처럼 활용하고자 했습니다.
SKILL이란?
Skill은 앱의 런타임 기능이 아닌, Agent가 따라야 할 로컬의 작업 규칙
Skills are reusable, shareable workflows that tell ChatGPT exactly how to do a specific task, enabling ChatGPT to do that task better and more consistently.
출처 : OpenAI Skills
이번 프로젝트에서 가장 크게 체감한 것은 Codex Skill 기반의 작업 방식이었습니다.
Skill은 어플리케이션 런타임 기능이라기보다,
개발자의 반복 수행 작업을 규칙화한 작업 가이드에 가깝습니다.
현재 프로젝트에서는 .codex 아래에 다음과 같은 개발 보조 규칙들을 두고 사용했습니다.
- 프롬프트 출력 규칙
- 테스트 점검 규칙
- 커버리지 점검 규칙
- TDD 진행 절차 문서
- 각 페이즈별 커밋 규칙
이걸 통해 에이전트는 현재 저장소의 규칙을 이해한 상태에서 작업에 들어갈 수 있었습니다.
AI가 컨벤션을 이해하지 못한 상태에서 개발을 진행하게 되면,
매번 같은 맥락을 장황하게 설명해야 했습니다.
하지만 Skill을 이용하게 되며, 다음과 같은 작업들을 더 빠르게 진행할 수 있었습니다.
- 기능 요구사항을 AC 단위로 쪼개기
- 실패 테스트부터 먼저 작성하기
- 최소 구현만 반영하기
- 리팩터링 범위를 분리하기
- 커버리지 및 회귀 테스트 기준 점검하기
Skill로 규칙을 분리해두니,
작업 컨텍스트를 반복해 재설명하는 비용이 줄었고, 결과물의 일관성도 훨씬 좋아졌습니다.
Plan이란?
코드를 바꾸기 전에, 변경의 목적·범위·순서·완료 기준을 적어두는 실행 문서
a design document that a coding agent can follow to deliver a working feature or system change
출처 : github openai/openai-agents-js/plan.md 작성글
다만 Skill만으로는 충분하지 않았고, Plan을 통해 실제 구현 속도를 끌어 올렸습니다.
기능 하나를 맡기면 AI는 쉽게 과잉 구현하거나 컨텍스트를 잃어버립니다.
그래서 먼저 기능을 AC 단위로 쪼개고,
테스트의 동작 과정과 구현 시점, 회귀 범위를 SPEC으로 고정한 뒤 Plan으로 작업을 진행했습니다.
기능 하나를 구현하더라도 코드를 바로 작성하게 하지 않고,
다음과 같은 순서로 작업을 설계했습니다.
- 어떤 서비스가 영향을 받는가
- 어떤 테스트를 먼저 실패시킬 것인가
- 어떤 계층에 최소 구현을 둘 것인가
- 어떤 순서로 회귀 테스트를 수행할 것인가
이 과정을 거치며 전체 테스트 흐름을 더 면밀히 검증하고,
발생 가능한 에러 전파 범위도 한정할 수 있었습니다.
Plan을 통해 AI는 단순한 구현 도구가 아니라,
설계된 작업 순서를 따라가는 동료 개발자로 활용할 수 있었습니다.
개인적으로 이번 프로젝트를 통해 가장 크게 느낀 것은,
하네스는 거창한 프레임워크라기보다,
이미 개발자가 하던 여러 통제 장치에 이름이 붙은 것에 더 가까웠습니다.
- 저장소를 읽게 하고
- 필요한 Skill을 먼저 불러오게 하고
- Plan에 따라 작업 범위를 제한하고
- 셸 명령으로 테스트를 실행하게 하고
- 실패 로그와 diff를 다시 읽게 하고
- 마지막에 로컬 머지 게이트를 통해 회귀 테스트와 커버리지를 확인하게 만드는
이 일련의 흐름 전체가 바로 하네스에 가까웠습니다.
저의 경우는 AI에게 모든 권한을 허용하는 것을 선호하지 않기에,
완전한 자동 교정 루프까지는 구성하지 않았습니다.
다만 규칙 문서, 금지 규칙, Hook, Lint, 테스트 게이트, 작업 분해 구조를 먼저 두고
하네스의 핵심 요소들을 제한된 범위 안에서 구현해보았습니다.
즉, Harness란 단순히 LLM을 터미널에서 돌리는 도구가 아니라,
AI를 실제 개발 루프 안으로 편입시키는 운영 환경이라고 보는 편이 더 정확했습니다.
물론 Skill을 쓴다고 해서 설계 자체를 대신해주는 것은 아닙니다.
어떤 계층에 로직을 둘지,
어디까지를 동기 호출로 가져갈지,
CQRS를 어느 수준까지 구현할지는 여전히 사람이 결정해야 했습니다.
다만 한 번 방향을 정한 이후에는,
반복되는 구현과 검증 단계를 빠르게 밀어주는 역할은 분명히 해냈다고 느꼈습니다.
마무리
Claude Code 유출과 Claw-Code의 등장은 단순한 사고로만 끝날 사건은 아니라고 생각합니다.
이 사건으로 AI 코딩 에이전트의 진짜 경쟁력이 모델 내부뿐 아니라,
모델 바깥의 실행 환경, 즉 하네스에 있다는 점이 더 선명하게 드러났으니까요.
하네스 엔지니어링은 프롬프트 엔지니어링이나 컨텍스트 엔지니어링을 대체하지는 않습니다.
그 위에서, 에이전트가 실제 프로젝트 안에서
일관되게, 안전하게, 되풀이 가능하게 일하도록 만드는 운영 구조일 뿐입니다.
규칙 문서, 자동 검증, 권한 경계, 그리고 실패를 되돌려주는 교정 루프가 그 핵심입니다.
그 실패가 다시는 반복되지 않도록 시스템을 바꾸는 것,
그것이 지금 많은 사람들이 Harness Engineering에 주목하는 이유라고 생각합니다.