생각 정리 - 하네스 엔지니어링, 결국 맥락을 설계하는 일

최근에 OpenAI 블로그에 올라온 Harness Engineering 글을 읽었다.

솔직히 100% 이해했다고 말하기는 어렵지만, 핵심은 꽤 명확하게 와닿았다.

이 글은 엔지니어의 역할 재정의하기로 되어 있지만 나에게는 "너의 역할도 재정의 해야 할걸?"로 보였다.

AI 에이전트에게 코드를 시키려면, 코드를 잘 짜는 것보다 "일할 환경"을 잘 설계하는 게 더 중요하다.

DECIDE 프레임워크

OpenAI 내부에서 5개월 동안 수동 코드 작성 없이 약 100만 줄의 프로덕션 코드를 만들었다고 한다.

소수의 엔지니어가 코드를 직접 짠 게 아니라, 에이전트가 일할 수 있는 하네스(harness) — 쉽게 말하면 울타리와 가이드레일 —를 만든 거다.

하네스 엔지니어링의 핵심은 무엇일까?

1. Context Engineering — 맥락을 관리하라

OpenAI는 **"맥락(context)은 희소 자원"**이라고 말한다.

거대한 지시 파일 하나를 덩그러니 넘기면, 에이전트는 정작 중요한 코드와 문서를 놓치거나 엉뚱한 방향으로 최적화하기 시작한다. 그래서 AGENTS.md를 백과사전이 아닌 목차로 쓰고, 실제 지식은 구조화된 docs/ 디렉터리에 분산시킨다. 에이전트가 작은 진입점에서 시작해서 "다음에 어디를 봐야 하는지"를 배워가는 방식이다.

이건 내가 요즘 Claude Code를 쓰면서 체감하고 있는 것인데, 해야지 해야지~ 하면서 지식이 짧아서 잘 안된다.

도대체 어떻게 맥락을 구조적으로 배치해야 하는 걸까?

나름의 초기 셋업이 있을 것 같은데, 아직 찾지 못했다.

2. Architecture Constraints — 규칙으로 울타리를 쳐라

알아서 해주세요(딸깍)가 아니라 이건 되고, 이건 안되다 와 같은 규칙을 명확히 하는 것이다.

에이전트한테 코드 구현을 시키되, "이 영역은 건드리지 마", "이건 저쪽에서만 가져와" 같은 구조적인 경계를 정해놓은 거다. 그리고 이 규칙 역시 에이전트를 시킨다. 에이전트가 규칙을 어기면 자동으로 "이건 안 돼"라고 막아준다는 것이다.

이걸 읽으면서 든 생각은, 결국 이 울타리를 설계하려면 전체 구조를 이해하는 사람이 필요하다는 거다.

이건 뭐... 비 개발자는 어떻게 해야 한다는 거냐. AI 에이전트와 CLI 그리고 인간의 역할에서도 느꼈지만, 도구가 발전할수록 인간의 역할 정의가 더 중요해진다.

3. Entropy Management — 엔트로피를 관리하라

코드 베이스는 시간이 지나면 자연스럽게 엉망이 된다. 문서는 코드와 어긋나고, 아키텍처 경계는 슬금슬금 무너진다. OpenAI는 이걸 잡기 위해 정기적으로 에이전트를 돌려서 문서 불일치와 아키텍처 위반을 자동으로 탐지한다.

에이전트가 작업하다 어려움을 겪으면, 그걸 "누락된 도구나 문서가 있다"라는 신호로 받아들이고 하네스를 개선한다.

이건 나도 이미 적용을 했다.

PRD를 가지고 프로토타입을 만들고 프로토타입에 집중하다가 PRD와 차이가 생기면, 소스를 기준으로 PRD를 업데이트하는 워크플로를 만든 것이다.

나는 PRD를 SSOT(Single source of truth)로 판단해서, 모든 기획서를 만들기 위해서 PRD를 업데이트하는 부분을 봤다면 OpenAI는 전체를 봤다는 차이는 있겠지.

비 개발자인 나에게는 어떤 의미가 있을까?

새 프로젝트를 시작할 때마다 MCP를 만들고, skills를 정의하고, CLAUDE.md에 규칙을 쓴다.

어렴풋이 이렇게 해야 할 것 같아서 하고 있었는데, 이 글을 읽고 나니 내가 하고 있던 것이 바로 하네스 엔지니어링의 초보 버전이었다는 걸 깨달았다.

결국 핵심은 아키텍처다. 아키텍처가 있어야 에이전트에게 "여기까지만 건드려"라고 경계를 그어줄 수 있고, 의사결정 히스토리가 있어야 "왜 이렇게 했는지" 맥락을 넘겨줄 수 있다.

이런 게 예전에는 "경험 많은 개발자의 영역"이었다면, 이제는 AI와 협업하는 모든 사람이 조금씩은 알아야 하는 것이 되어가고 있다는 거다.

코드를 못 짜도 되지만, 코드의 구조는 알아야 하는 시대.

비 개발자는 더 힘들다.

결국 하네스 엔지니어링이 말하고자 하는 것은?

하네스 엔지니어링이라는 거창한 이름이 붙었지만, 본질은 단순하다.

AI에게 일을 시키려면, 좋은 맥락을 설계하라.

그 맥락 안에는 아키텍처가 있고, 상황과 의사결정의 히스토리가 있고, "어디까지 해도 되고 어디부터는 안 되는지"에 대한 경계가 있다.

나는 아직 이 여정의 초반에 있지만, 방향은 맞게 가는 것 같다. 도대체 왜 이리 빠른 것이냐에서도 다짐했듯이, 내 맥락에서 필요한 것을 선별하며 묵묵히 가는 수밖에.

#AI #하네스엔지니어링 #HarnessEngineering #맥락관리 #아키텍처 #AI에이전트 #생각정리