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

왕초보 설명

  • 이게 뭐야? “AI가 시험 점수는 높은데 왜 내 프로젝트에선 엉망이지?”에 대한 답이다. 답은 대개 AI가 아니라 AI에게 준 작업 환경이 문제라는 것.
  • 비유: 경주마(모델)가 아무리 빨라도 안장·고삐 같은 마구(하네스) 없이는 멀리 못 가고 자주 떨어진다.
  • 왜 중요해? 실패할 때마다 “더 비싼 모델로 바꾸자”고 하면 돈만 쓰고 같은 실패를 반복한다. 같은 모델도 환경만 고치면 결과가 확 달라진다.
  • 나는 뭘 하면 돼? AI가 실패하면 모델 탓을 하기 전에 다섯 가지를 차례로 묻는다. ① 할 일을 분명히 말했나? ② 프로젝트 규칙을 알려줬나? ③ 실행 환경이 갖춰졌나? ④ 다 됐는지 확인할 방법을 줬나? ⑤ 지난번까지 한 일을 기록해 뒀나? 그리고 저장소 맨 위에 AGENTS.md 한 장부터 만든다.

핵심 요약

  • 모델 역량 ≠ 실행 신뢰성. Claude Sonnet 4.5는 SWE-bench Verified 77.2%였지만, 그건 이슈 설명·테스트·환경이 다 갖춰진 엄선된 작업 기준이다. 실제 프로젝트에선 이것들을 직접 마련해야 해서 수치가 더 낮다.
  • 같은 모델, 다른 하네스. Anthropic은 같은 프롬프트(“2D 레트로 게임 메이커”)와 같은 모델(Opus 4.5)을 비교했다. 맨손: 20분·9달러, 입력에 반응하지 않는 앱. 플래너+생성기+평가기 하네스: 6시간·200달러, 핵심 게임플레이는 작동하지만 미완성. 모델은 그대로였고 바뀐 건 마구였다.
  • 실패하면 하네스부터 점검한다. 모델 교체는 가장 비싼 선택지이고, 대부분 모델 문제가 아니다.
  • 모든 실패를 다섯 방어 레이어 중 하나에 귀속시킨다: 작업 명세, 컨텍스트 제공, 실행 환경, 검증 피드백, 상태 관리.
  • AGENTS.md 파일 하나가 더 비싼 모델로 바꾸는 것보다 효과적일 수 있다.

핵심 개념

에이전트가 막히는 다섯 지점(방어 레이어)

레이어무엇이 잘못되나비유
작업 명세”검색 기능 추가해”만 들으면 전문 검색인지, 페이지네이션은 있는지 에이전트가 추측한다식당에서 “생선으로 주세요”만 말하기
컨텍스트 제공팀 규칙(SQLAlchemy 2.0, OAuth 2.0 필수)이 머릿속·슬랙에만 있어 에이전트가 존재 자체를 모른다신입에게 사내 규칙을 안 알려 주기
실행 환경의존성 누락, 버전 불일치로 pip install 실패에 컨텍스트를 낭비한다망치도 작업대도 없는 목수
검증 피드백테스트·린트·검증 명령이 없어 “괜찮아 보이니 완료”답안지 없이 숙제 제출
상태 관리세션이 바뀌면 전에 알아낸 게 사라져 매번 처음부터 탐색. 30분 넘는 작업에서 실패율이 급증매일 기억을 잃는 직원

이 다섯 레이어는 lecture-02의 5개 하위 시스템(지시·도구·환경·상태·피드백)을 “고장 진단” 쪽에서 본 것이다.

핵심 용어

  • 역량 격차(Capability Gap): 벤치마크 성능과 실제 작업 성능의 차이.
  • 하네스 유발 실패(Harness-Induced Failure): 모델은 충분한데 환경의 구조적 결함 때문에 실패한 경우.
  • 검증 격차(Verification Gap): 에이전트의 “완료” 자신감과 실제 정확성의 차이. 가장 흔한 실패 유형이다. 줄이는 도구가 검증 명령어다.
  • 컨텍스트 불안(context anxiety) (context-anxiety): Anthropic 관찰. 에이전트가 컨텍스트가 모자란다고 느끼면 서둘러 마무리하고 검증을 건너뛴다. 시험 종료 직전 남은 문제를 찍는 것과 같다.
  • 진단 루프(Diagnostic Loop) 후보:diagnostic-loop: 실행 → 실패 관찰 → 특정 레이어에 귀속 → 그 레이어 수정 → 재실행. 강의가 꼽는 하네스 엔지니어링의 핵심 방법론이다. 작업별 성공·실패와 원인 레이어를 로그로 남기면 병목 레이어가 보인다.
  • 완료 기준(Definition of Done) (definition-of-done): 기계로 확인할 수 있는 조건 묶음(테스트 통과, 린트 클린, 타입 검사 통과). 없으면 에이전트가 자기 기준을 만든다. 예:
완료 기준:
- 새 엔드포인트 GET /api/search?q=xxx
- 페이지네이션 지원, 기본 20개 항목
- 결과에 하이라이트된 스니펫 포함
- 모든 새 코드가 pytest 통과
- 타입 검사 통과 (mypy --strict)

사례 두 개

  • OpenAI 백만 줄 실험: 2025년 8월부터 5개월간 빈 저장소에서 Codex로 내부 제품을 만들었다. 약 100만 줄, PR 약 1,500개 병합(엔지니어 1인당 하루 3.5개), 엔지니어 3명 → 7명. 규칙: 사람은 코드를 직접 쓰지 않는다. 초기에 느렸던 이유는 모델이 아니라 환경 부족이었고, 실패 때마다 묻는 질문은 “더 열심히”가 아니라 “에이전트에게 어떤 역량이 부족한가”였다.
  • FastAPI 앱(약 15,000줄): 한 문장 지시만 줬을 때 Claude Sonnet은 탐색에 시간을 쓰고, 프로젝트 오류 처리 패턴을 무시하고, 구식 SQLAlchemy 문법을 쓰고, 런타임 오류가 있는데 완료를 선언했다. AGENTS.md, 검증 명령(pytest tests/api/v2/ && python -m mypy src/), 아키텍처 결정 기록을 추가하자 같은 모델이 컨벤션을 따르고 명령으로 확인했다.

다른 강의·프로젝트와의 연결

  • 다음 강의: lecture-02가 “그럼 하네스는 정확히 무엇인가”를 5개 하위 시스템으로 정의한다.
  • 실습: project-01이 같은 작업을 프롬프트만 vs 최소 하네스로 돌려 이 강의의 연습 1(비교 실험)을 그대로 수행한다.
  • 컨텍스트 레이어 심화: lecture-03(저장소를 기록 원천으로), lecture-04(지시 파일 분산).
  • 상태 레이어 심화: lecture-05, lecture-06.
  • 검증 레이어 심화: lecture-09(이른 완료 선언), lecture-10(종단 간 테스트).

원문 경로

  • ko: raw/learn-harness-engineering/docs/ko/lectures/lecture-01-why-capable-agents-still-fail/index.md
  • en: raw/learn-harness-engineering/docs/en/lectures/lecture-01-why-capable-agents-still-fail/index.md
  • 표기 차이: ko 강의 제목은 “강력한 모델도 실행 신뢰성을 보장하지 않는다”인데, ko project-01 페이지는 “강력한 모델이 곧 신뢰할 수 있는 실행을 의미하지는 않습니다”로 적는다.