中文版本 →

코드 예제: code/ 실습 프로젝트: Project 01. Prompt-only vs. rules-first

강의 01. 강력한 모델도 실행 신뢰성을 보장하지 않는다

AI 세계에 꽤 익숙하다고 자부합니다 — Claude Pro 구독, GPT-4o API 키, SWE-bench 리더보드 수치까지 외우고 있죠. 그러던 어느 날 드디어 실제 프로젝트를 AI 에이전트(agent)에게 맡겨봤습니다. 결과는? 기능 하나를 추가했더니 테스트가 깨지고, 버그 하나를 고쳤더니 두 개가 더 생기고, 20분 동안 열심히 실행하더니 당당하게 "완료"를 선언했는데 코드를 보면 요청한 것과 전혀 다른 내용입니다.

에이전트(agent)란 자율적으로 작업을 수행하는 AI 소프트웨어 단위입니다. 코딩 에이전트(coding agent)는 이 중에서도 코드 작성·리팩터·테스트 등 개발 작업을 담당합니다.

처음 든 생각은 이겁니다: "이 모델은 아직 부족해. 더 좋은 걸로 바꿔야겠어." 잠깐, 지갑을 꺼내기 전에 — 문제가 모델에 있지 않을 수도 있다는 점을 먼저 짚어봐야 합니다.

숫자를 봅시다. 2025년 말 기준 SWE-bench Verified에서 가장 강력한 코딩 에이전트들은 대략 50-60%의 정확도를 기록합니다. 그것도 명확한 이슈 설명과 기존 테스트 케이스가 갖춰진 엄선된 작업 기준입니다. 막연한 요구사항, 테스트 없음, 암묵적 비즈니스 규칙이 여기저기 흩어진 실제 개발 환경으로 넘어오면 그 수치는 더 낮아집니다.

그런데 이 수치들 뒤에는 직관에 반하는 진실이 있습니다.

같은 말(馬), 다른 결과

Anthropic이 통제 실험을 진행했습니다. 동일한 프롬프트("2D 레트로 게임 메이커를 만들어라"), 동일한 모델(Opus 4.5). 첫 번째 실행: 아무런 지원 없이 맨손 — 20분, 9달러, 게임의 핵심 기능은 전혀 작동하지 않았습니다. 두 번째 실행: 완전한 하네스(harness) 적용(플래너 + 제너레이터 + 이밸류에이터 3에이전트 아키텍처) — 6시간, 200달러, 게임을 실제로 플레이할 수 있었습니다.

하네스(harness)란 AI 코딩 에이전트가 안정적으로 동작하도록 환경·상태(state)·검증(verification)·제어를 묶어서 제공하는 외골격(스캐폴딩) 시스템입니다. 모델 가중치 외부에 있는 모든 엔지니어링 인프라가 하네스에 해당합니다.

모델은 바꾸지 않았습니다. Opus 4.5는 여전히 Opus 4.5였죠. 바뀐 것은 안장(saddle)이었습니다.

OpenAI의 2025년 하네스 엔지니어링 글은 명확하게 밝힙니다: 잘 갖춰진 저장소(repository)에서의 Codex는 "불안정"에서 "안정"으로 질적 전환을 이룬다고. 표현에 주목하세요 — "조금 나아진"이 아니라 질적 변화입니다. 마치 경주마처럼: 안장 없이도 탈 수 있지만, 멀리 갈 수 없고, 빠르게 달릴 수 없으며, 낙마도 놀랍지 않습니다. 하네스는 그 안장입니다 — 모델 가중치 외부의 엔지니어링 인프라 전체입니다.

에이전트가 실제로 막히는 지점

그렇다면 구체적으로 무엇이 잘못되는 걸까요?

가장 흔한 원인: 작업을 명확하게 정의하지 않았습니다. "검색 기능을 추가해"라고 하면 에이전트의 이해는 여러분의 이해와 전혀 다릅니다 — 무엇을 검색? 전문 검색 아니면 구조화 검색? 페이지네이션은? 하이라이팅은? 명시하지 않았으니 에이전트는 추측합니다. 맞는 추측은 운이고, 틀린 추측은 처음부터 명확히 했을 때보다 고치는 비용이 더 듭니다. 레스토랑에 가서 주방장에게 "생선으로 주세요"라고 하는 것과 같습니다 — 조림이 나올지, 찜이 나올지, 전골이 나올지는 순전히 운에 달려 있습니다.

명확히 지시했더라도, 프로젝트에는 에이전트가 모르는 암묵적 아키텍처 컨벤션이 있습니다. 팀에서는 SQLAlchemy 2.0 문법을 표준으로 쓰는데 에이전트는 기본적으로 1.x 코드를 작성합니다. 모든 API 엔드포인트는 OAuth 2.0 인증을 사용해야 하는데, 그 규칙은 여러분 머릿속과 석 달 전 슬랙 메시지에만 존재합니다. 에이전트는 이것을 볼 수 없습니다 — 따르기 싫어서가 아니라 그 규칙의 존재 자체를 모릅니다.

환경도 함정입니다. 불완전한 개발 환경, 누락된 의존성, 잘못된 도구 버전. 에이전트는 실제 작업 대신 pip install 실패와 Node 버전 불일치를 처리하느라 귀중한 컨텍스트 윈도(context window)를 낭비합니다. 숙련된 목수를 고용했는데 망치도, 못도, 평평한 작업대도 제공하지 않은 것과 같습니다 — 아무리 실력이 좋아도 작업을 할 수 없습니다.

더 흔한 문제: 검증(verification) 방법이 아예 없습니다. 테스트도 없고, 린트도 없고, 검증 명령어도 에이전트에게 전달되지 않습니다. 에이전트는 코드를 작성하고, 보고, 괜찮다고 판단하고, "완료"라고 선언합니다. 답안지 없이 숙제를 제출하도록 한 것과 같습니다 — 학생은 맞혔다고 생각하지만 채점하면 오류 투성이입니다. Anthropic은 흥미로운 현상도 관찰했습니다: 에이전트가 컨텍스트 부족을 감지하면 서둘러 마무리하고, 검증을 건너뛰고, 최선 대신 단순한 해결책을 선택합니다. 이를 "컨텍스트 불안(context anxiety)"이라 부릅니다 — 시험 시간이 거의 다 됐을 때 남은 객관식 문제를 무작위로 찍기 시작하는 것과 같은 현상입니다.

세션에 걸친 장시간 작업은 더욱 나쁩니다 — 이전 세션에서 발견한 모든 것이 사라지고, 매 새 세션마다 프로젝트 구조를 다시 탐색하고 코드 구성을 다시 이해해야 합니다. 영속적인 상태(state)가 없는 에이전트는 30분을 초과하는 작업에서 실패율이 급격히 치솟습니다.

핵심 용어

이 시나리오들을 염두에 두면 다음 개념들이 단순한 전문 용어 이상으로 다가옵니다.

• 역량 격차(Capability Gap): 벤치마크 성능과 실제 작업 성능 사이의 큰 간극. SWE-bench Verified에서 50-60%의 통과율은 실제 이슈의 거의 절반이 해결되지 않는다는 의미입니다.
• 하네스(Harness): 모델 외부의 모든 것 — 지시사항, 도구, 환경, 상태(state) 관리, 검증(verification) 피드백. 모델 가중치가 아니라면 모두 하네스입니다. 우리가 "안장"이라고 부른 것입니다.
• 하네스 유발 실패(Harness-Induced Failure): 모델은 충분한 역량을 갖췄지만 실행 환경에 구조적 결함이 있는 경우. Anthropic의 통제 실험이 이를 이미 증명했습니다.
• 검증 격차(Verification Gap): 에이전트가 자신의 산출물(deliverable)에 대해 갖는 자신감과 실제 정확성 사이의 간극. 에이전트가 "완료했다"고 말하지만 완료하지 않은 상태 — 이것이 가장 흔한 실패 유형입니다.
• 진단 루프(Diagnostic Loop): 실행 → 실패 관찰 → 특정 하네스 레이어에 귀속 → 해당 레이어 수정 → 재실행. 이것이 하네스 엔지니어링의 핵심 방법론입니다.
• 완료 기준(Definition of Done): 기계 검증 가능한 조건들의 집합 — 테스트 통과, 린트 클린, 타입 검사 통과. 명시적인 완료 기준이 없으면 에이전트는 자체 기준을 만들어냅니다.

실패하면 먼저 하네스를 점검하라

핵심 원칙: 실패가 발생하면 먼저 모델을 교체하지 말고 하네스를 점검하십시오. 같은 모델이 비슷하게 잘 구성된 작업에서 성공한다면, 하네스 문제라고 가정하십시오. 자동차가 고장났을 때처럼 — 바로 엔진을 의심하지 않습니다. 먼저 연료가 있는지 확인합니다.

구체적인 단계:

모든 실패를 특정 레이어에 귀속시키십시오. "모델이 별로야"라고만 하지 마십시오. 물어보십시오: 작업이 불명확했는가? 컨텍스트(context)가 불충분했는가? 검증 방법이 없었는가? 각 실패를 다섯 가지 실패 레이어(작업 명세, 컨텍스트 제공, 실행 환경, 검증 피드백, 상태 관리) 중 하나에 매핑하십시오. 이 습관을 들이면 로그에서 "모델이 부족해"라는 말이 점점 사라집니다.

모든 작업에 명시적인 완료 기준을 작성하십시오. "검색 기능을 추가해"라고 하지 마십시오. 이렇게 하십시오:

완료 기준:
- 새 엔드포인트 GET /api/search?q=xxx
- 페이지네이션 지원, 기본 20개 항목
- 결과에 하이라이트된 스니펫 포함
- 모든 새 코드가 pytest 통과
- 타입 검사 통과 (mypy --strict)

AGENTS.md 파일을 만드십시오. 저장소(repository) 루트에 배치하여 에이전트에게 프로젝트의 기술 스택, 아키텍처 컨벤션, 검증 명령어를 알려주십시오. 이것이 하네스 엔지니어링의 첫 번째 단계이자 투자 대비 효과가 가장 높은 단계입니다. AGENTS.md 파일 하나가 더 비싼 모델로 업그레이드하는 것보다 효과적일 수도 있습니다 — 농담이 아닙니다.

진단 루프를 구축하십시오. 실패를 "모델이 또 멍청한 짓을 했네"로 취급하지 마십시오. 하네스에 결함이 있다는 신호로 취급하십시오. 매 실패마다 레이어를 찾아 수정하고, 같은 방식으로 다시 실패하지 않도록 하십시오. 몇 라운드를 거치면 하네스가 강화되고 에이전트 성능이 안정됩니다. 도로 보수처럼 — 모든 움푹 파인 곳을 메울수록 다음 구간이 더 매끄러워집니다.

개선 사항을 정량화하십시오. 간단한 로그를 유지하십시오: 각 작업이 성공했는지 실패했는지, 그리고 어느 레이어가 실패를 야기했는지. 몇 라운드 후에는 어느 레이어가 병목인지 보이기 시작합니다 — 거기에 에너지를 집중하십시오.

백만 줄 코드 실험

OpenAI는 2025년에 공격적인 실험을 진행했습니다: Codex를 사용하여 빈 git 저장소에서 완전한 내부 제품을 구축하는 것. 5개월 후 저장소에는 약 100만 줄의 코드가 생성되었습니다 — 애플리케이션 로직, 인프라, 툴링, 문서, 내부 개발 도구 모두 에이전트가 생성했습니다. 세 명의 엔지니어가 Codex를 운영하며 약 1,500개의 PR을 열고 병합했습니다. 1인당 하루 평균 3.5개의 PR.

핵심 제약: 인간은 코드를 직접 작성하지 않습니다. 이것은 단순한 실험적 설정이 아니었습니다 — 엔지니어의 주요 업무가 더 이상 코드 작성이 아니라 환경 설계, 의도 표현, 피드백 루프 구축이 될 때 무엇이 달라지는지 파악하도록 강제하기 위한 설계였습니다.

초기 진행은 예상보다 느렸습니다. Codex의 역량이 부족해서가 아니라 환경이 아직 충분히 갖춰지지 않았기 때문입니다 — 에이전트에게 고수준 목표를 진전시키는 데 필요한 도구, 추상화, 내부 구조가 부족했습니다. 엔지니어들의 작업은 이렇게 바뀌었습니다: 큰 목표를 작은 구성 요소(설계, 코드, 리뷰, 테스트)로 분해하고, 에이전트가 조합하도록 한 다음, 그 구성 요소들을 활용하여 더 복잡한 작업을 가능하게 하는 것. 무언가 실패했을 때 해결책은 거의 "더 열심히 해봐"가 아니었습니다 — "에이전트에게 어떤 역량이 부족하고, 어떻게 하면 이해 가능하고 실행 가능하게 만들 수 있는가?"였습니다.

이 실험은 이 강의의 핵심 테제를 직접 증명합니다: 동일한 모델이 맨손 환경과 완전한 하네스 환경에서 근본적으로 다른 산출물을 만들어냅니다. 모델은 변하지 않았습니다. 환경이 변했습니다.

출처: OpenAI: Harness engineering: leveraging Codex in an agent-first world

현실적인 예시

한 팀이 중간 규모의 Python 웹 앱(FastAPI + PostgreSQL + Redis, 약 15,000줄)에 새 API 엔드포인트를 추가하기 위해 Claude Sonnet을 사용했습니다.

처음에는 한 문장만 제공했습니다: "/api/v2/users 아래에 사용자 환경설정 엔드포인트를 추가해." 결과는? 에이전트가 컨텍스트(context) 윈도의 40%를 저장소 구조 탐색에 사용했고, 겉으로는 합리적으로 보이지만 프로젝트의 오류 처리 패턴을 따르지 않는 코드를 생성했으며, 구식 SQLAlchemy 문법을 사용했고, 엔드포인트에 런타임 오류가 있는 상태에서 완료를 선언했습니다. 다음 세션은 모든 탐색 작업을 처음부터 다시 해야 했습니다.

이후 AGENTS.md(프로젝트 아키텍처 및 기술 스택 버전 설명), 명시적 검증 명령어(pytest tests/api/v2/ && python -m mypy src/), 아키텍처 결정 기록을 추가했습니다. 같은 모델이 독립적으로 세 번 실행한 모두에서 성공했고, 컨텍스트 효율도 약 60% 향상되었습니다.

모델을 바꾸지 않았습니다. 하네스를 바꿨습니다.

핵심 정리

• 모델 역량과 실행 신뢰성은 별개입니다. 경주마도 좋은 안장이 필요합니다.
• 실패 시 먼저 하네스를 점검하고, 그 다음 모델을 확인하십시오. 모델 교체는 가장 비싼 선택지입니다 — 그리고 대부분 모델 문제가 아닙니다.
• 모든 실패는 신호입니다: 하네스에 구조적 결함이 있습니다. 찾아서 고치십시오.
• 다섯 가지 방어 레이어: 작업 명세, 컨텍스트 제공, 실행 환경, 검증 피드백, 상태 관리. 의사가 가장 흔한 원인부터 먼저 배제하듯이 체계적으로 점검하십시오.
• AGENTS.md 파일 하나가 더 비싼 모델로 업그레이드하는 것보다 효과적일 수 있습니다. 진심입니다.

더 읽을거리

• OpenAI: Harness Engineering — Leveraging Codex in an Agent-First World
• Anthropic: Effective Harnesses for Long-Running Agents
• HumanLayer: Skill Issue — Harness Engineering for Coding Agents
• SWE-bench Leaderboard
• Thoughtworks Technology Radar: Harness Engineering

연습 문제

1. 비교 실험: 잘 아는 코드베이스와 비사소한 수정 작업을 선택하십시오. 먼저 하네스 지원 없이 에이전트를 실행하고 실패를 기록하십시오. 그런 다음 명시적 검증 명령어가 포함된 AGENTS.md를 추가하고 같은 에이전트로 다시 실행하십시오. 결과를 비교하고, 각 실패를 다섯 가지 방어 레이어 중 하나에 귀속시키십시오.

2. 검증 격차 측정: 코딩 작업 5개를 선택하십시오. 각 작업 후 에이전트가 완료를 주장하는지 기록한 다음, 독립적인 테스트로 실제 정확성을 검증하십시오. 에이전트가 실제로는 완료하지 않았는데 완료했다고 주장하는 비율을 계산하십시오 — 그것이 여러분의 검증 격차입니다. 그런 다음 어떤 검증 명령어가 이 비율을 낮출 수 있는지 생각해보십시오.

3. 진단 루프 실습: 프로젝트에서 에이전트가 반복적으로 실패하는 작업을 찾으십시오. 한 번 실행하고 실패를 기록하십시오. 다섯 가지 레이어 중 하나에 귀속시키십시오. 그 레이어를 수정하십시오. 다시 실행하십시오. 3~5라운드를 반복하면서 매번 개선 사항을 기록하십시오.