같은 모델·같은 프롬프트, 성패를 가른 '하네스 엔지니어링' 핵심 구조

원작자 @0x0SojalSec가 X에 소개한 무료 입문 강좌 walkinglabs/learn-harness-engineering의 핵심을 정리합니다. 같은 모델에 같은 프롬프트를 줘도, 한쪽은 20분 만에 실패하고 다른 쪽은 동작하는 게임을 완성했다는 것이 이 강좌의 출발점입니다. 차이를 만든 것은 모델이 아니라 하네스(harness)라는 주장입니다.

이미지 출처: @0x0SojalSec via X

하네스는 프롬프트 파일이 아니다: 5대 하위 시스템

이 강좌가 제시하는 하네스의 정의는 단순합니다. 하네스는 프롬프트 파일 한 장이 아니라, AI 코딩 에이전트가 안정적으로 동작하도록 만드는 5개의 하위 시스템입니다.

• 지침(instructions): 저장소 안에 맥락을 구조화해 두는 지시 체계. 강좌는 "저장소 자체가 명세"라는 원칙을 강조합니다.
• 도구(tools): 에이전트가 실제로 호출할 수 있는 수단.
• 환경(environment): 에이전트가 실행되는 격리·재현 가능한 작업 공간.
• 상태(state): 작업 진행 상황과 공유 컨텍스트의 관리.
• 피드백(feedback): 검증과 관측 가능성을 통한 결과 환류.

각 하위 시스템에는 명확한 책임과 평가 기준이 있으며, 이 다섯 가지를 갖추는 것이 강좌 전반의 뼈대입니다.

4개 층위와 자율 루프 /goal의 3요소

강좌는 에이전트 스택을 4개의 층으로 쌓아 설명합니다. 프롬프트(prompt) 위에 컨텍스트(context), 그 위에 루프(loop), 최상위에 그래프(graph)가 올라갑니다. 하네스는 이 전체의 토대이며, 루프와 그래프는 그 위에 구축됩니다.

수동 프롬프트에서 자율 루프로 넘어가는 전환점이 강좌 후반부의 주제입니다. 2026년 초 Claude Code와 OpenAI Codex가 각각 독립적으로 선보인 /goal 기능이 그 예시로 등장합니다. 터미널에 목표를 입력하면 에이전트가 스스로 분석·코딩·테스트·수정을 반복하고, 막히면 접근법을 바꾸며, 끝나면 멈춥니다. 강좌에 따르면 자율 루프는 정확히 세 가지 요소로 구성됩니다.

• 목표(goal): 달성해야 할 것.
• 검증 방법(verification method): 목표 달성 여부를 판정하는 수단.
• 독립적인 중단 조건(stopping condition): 사람의 개입 없이 루프를 끝내는 판단.

여기서 한 단계 더 나아가면 그래프 엔지니어링입니다. 루프 안에 숨겨져 있던 구조를 노드(nodes), 간선(edges), 공유 상태(shared state), 라우팅 규칙(routing rules)으로 명시적으로 옮기는 과정이며, 메이커-체커(maker-checker) 루프를 직접 그려 보고 병렬 분기와 조건부 롤백을 추가하는 실습으로 이어집니다.

무료 강좌 구성: 14개 강의와 8개 프로젝트

이 강좌는 루프(loop), 그래프(graph), 검증(verification), 관측 가능성(observability)을 다루는 프로젝트 기반 무료 강좌로, 14개 강의와 8개 프로젝트로 구성되어 있습니다. Claude Code, Codex, DeepSeek이 실제로 결과물을 만드는 과정을 다룬다고 소개되어 있습니다. 영어 포함 15개 언어로 제공되며 한국어 자료도 포함되어 있습니다.

학습 순서는 하네스의 정의에서 시작해 환경·상태·검증·제어 메커니즘을 쌓고, 첫 자동화 루프 만들기와 첫 그래프 그리기 프로젝트로 마무리되는 흐름입니다. 프롬프트를 바꾸는 데 막혔다면, 더 비싼 모델로 바꾸기 전에 하네스 쪽을 점검해 보라는 것이 강좌의 메시지입니다. 다만 "같은 모델·같은 프롬프트, 한쪽은 실패·한쪽은 완성"이라는 도입부 사례는 강좌 측이 제시한 적용 사례 비교이며, 단일 하네스 요소만을 분리한 동등 예산 통제 실험으로 읽어서는 안 됩니다.

원문 출처

• @0x0SojalSec 원문 포스트: Learn Harness engineering, beginner tutorial, from 0 to 1
• 무료 강좌 저장소: walkinglabs/learn-harness-engineering