4장. 좋은 모델만으로 좋은 Agent가 되지 않는 이유 — 하네스라는 개념
3장에서 한 바퀴가 도는 과정을 봤다.
그 순환은 조건이 갖춰졌을 때의 이야기였다.
읽을 코드가 정리되어 있고,
돌아가는 테스트가 있고,
실패가 로그로 돌아오는 프로젝트.
그렇지 않은 프로젝트에서는 같은 도구가
전혀 다른 결과를 낸다.
같은 모델, 다른 결과
두 프로젝트에 똑같은 작업을 맡겨보자.
| 구분 | 프로젝트 A | 프로젝트 B |
|---|---|---|
| 문서 | README 세 줄 | CLAUDE.md 한 장 |
| 테스트 | 없음 | 단위 테스트 12초 |
| 로컬 실행 | 수동 설정 30분 | docker compose up |
| 컨벤션 | 파일마다 다름 | 모듈 구조 일관 |
프로젝트 A에서 Agent는 이렇게 움직인다.
기존 코드와 다른 스타일로 클래스를 만들고,
이미 있는 유틸리티를 또 만들고,
고쳤다고 보고하지만 검증한 근거를 대지 못한다.
프로젝트 B에서는 3장의 순환이 돈다.
모델은 같다.
프롬프트도 같다.
차이는 모델이 아니라
모델을 둘러싼 환경에서 나왔다.
Model, Agent, Harness
세 단어를 구분해두면 이 책 전체가 쉬워진다.
| 용어 | 정의 |
|---|---|
| Model | 텍스트를 읽고 다음 판단을 만드는 부분 |
| Agent | Model에 루프와 도구를 붙인 실행체 |
| Harness | Agent가 일하는 조건 전체 |
하네스라는 단어는 말에 씌우는 마구에서 왔다.
마구는 말의 힘을 줄이는 장치가 아니다.
그 힘이 엉뚱한 방향으로 흩어지지 않게 만드는 장치다.
하네스는 Agent를 제약하는 장치가 아니라,
Agent의 힘을 일에 전달하는 장치다.
프롬프트로는 메울 수 없다
여기서 흔한 시도가 실패한다.
프롬프트를 더 정교하게 쓰면 될 것 같다.
반드시 테스트를 실행해서 검증한 뒤 보고해줘.
기존 컨벤션을 따르고, 중복 코드를 만들지 마.
프로젝트 A에서 이 지시는 아무 일도 하지 못한다.
실행할 테스트가 없고,
따를 컨벤션이 문서로도 코드로도 명확하지 않다.
지시는 조건을 만들지 못한다.
| 프롬프트로 되는 것 | 하네스가 필요한 것 |
|---|---|
| 이번 작업의 목표 전달 | 검증 수단의 존재 |
| 출력 형식 지정 | 프로젝트 규칙의 항구적 보존 |
| 이번만 조심할 점 | 위험한 명령의 차단 |
| 접근 방식 힌트 | 실행 가능한 로컬 환경 |
프롬프트는 이번 한 번에만 유효하다.
하네스는 모든 작업에 유효하다.
그래서 이 책의 초점은 프롬프트가 아니다.
상한선은 하네스가 정한다
모델 성능과 하네스 품질을 두 축으로 놓아보자.
| 나쁜 하네스 | 좋은 하네스 | |
|---|---|---|
| 약한 모델 | 아무것도 못 한다 | 느리지만 안전하다 |
| 강한 모델 | 빠르게 틀린다 | 위임이 성립한다 |
가장 위험한 칸은 왼쪽 아래가 아니다.
⚠️ 강한 모델 + 나쁜 하네스.
그럴듯한 코드가 빠르게 쏟아지고,
검증할 방법이 없으니 그럴듯함이 곧 승인 근거가 된다.
Vibe Coding이 위험해지는 지점이 정확히 여기다.
반대로 하네스가 좋으면 모델의 실수가 걸러진다.
컴파일이 막고, 테스트가 막고, 의존성 규칙이 막는다.
모델은 성능의 기대값을 올린다.
하네스는 성능의 하한선을 올린다.
운영 시스템에서 중요한 것은 하한선이다.
이미 우리가 만들던 것들이다
하네스 엔지니어링이 새로운 기술처럼 들린다면
이렇게 보면 된다.
우리는 사람을 위해 이미 하네스를 만들어왔다.
- 신규 입사자가 첫날 실행할 수 있는 로컬 환경
- 실수를 막는 CI 파이프라인
- 운영 DB에 직접 붙지 못하게 하는 권한 정책
- 리뷰 없이는 머지되지 않는 브랜치 규칙
Agent에게 필요한 것과 목록이 거의 같다.
차이는 하나다.
사람은 문서에 없는 것을 옆자리에 물어본다.
Agent는 묻지 않고 추측한다.
그래서 사람에게는 관행으로 남겨도 되던 것을
Agent에게는 명시해야 한다.
암묵지를 파일로 꺼내는 일,
그것이 이 책에서 하는 작업의 절반이다.
우리가 고칠 대상은 Agent가 아니다
Agent가 같은 실수를 반복할 때
“이 모델은 별로다“로 끝내면 개선이 멈춘다.
질문을 바꿔야 한다.
읽을 것이 부족했는가 → Context
규칙이 어디에도 없었는가 → Instruction
검증할 수단이 없었는가 → Tests
할 수 있는 행동이 없었는가 → Tools
막아야 할 것을 열어뒀는가 → Permission
작업이 너무 컸는가 → Task 설계
이 목록이 곧 하네스의 부품 목록이다.
다음 장에서 부품 하나하나를 펼쳐본다.
그것이 이 책의 지도가 된다.
이 장의 핵심
- 같은 모델과 같은 프롬프트로도 프로젝트에 따라 결과가 갈린다
- Model은 판단, Agent는 실행체, Harness는 일하는 조건 전체를 뜻한다
- 하네스는 힘을 제약하는 장치가 아니라 방향을 주는 장치다
- 프롬프트는 지시를 전달하지만 조건을 만들지 못한다
- 가장 위험한 조합은 강한 모델과 나쁜 하네스다
- 모델은 기대값을 올리고, 하네스는 하한선을 올린다
- 사람에게 관행으로 남겨둔 암묵지를 Agent에게는 파일로 꺼내야 한다
- Agent가 반복해서 틀리면 고칠 대상은 모델이 아니라 하네스다