핵심 요약
Walking Labs AI 코딩 에이전트 하네스 엔지니어링 코스 12강의 강의별 핵심 내용 정리. "유능한 에이전트가 왜 실패하는가"에서 출발해 하네스 설계, 저장소 운영, 상태 관리, 검증 전략, 세션 정리까지 체계적으로 다룬다. 핵심 실험 데이터: 동일한 Opus 4.5 모델로 맨손 실행(20분/$9, 핵심 기능 미작동) vs 완전한 하네스(6시간/$200, 실제 플레이 가능한 게임) — 모델이 아닌 하네스 설계가 결과를 결정한다는 것이 코스 전체의 주제다.
Lecture 01: 유능한 에이전트가 여전히 실패하는 이유
하네스 정의: "AI 코딩 에이전트가 안정적으로 동작하도록 환경·상태·검증·제어를 제공하는 외골격 시스템"
Anthropic 통제 실험:
- 맨손 실행: 20분, $9, 핵심 기능 미작동
- 완전한 하네스: 6시간, $200, 실제 플레이 가능한 게임
- 모델(Opus 4.5)은 동일
에이전트 실패 4원인: 작업 명세 부족 / 아키텍처 컨벤션 미공유 / 환경 설정 미흡 / 검증 방법 부재
컨텍스트 불안(Context Anxiety): 컨텍스트 한계 감지 시 조기 수렴, 검증 건너뜀
5대 방어 레이어: 작업 명세, 컨텍스트, 실행 환경, 검증, 상태 관리
OpenAI 백만 줄 코드 실험 (2025): 5개월, ~100만 줄, 3명 엔지니어, ~1,500 PR (1인당 일 3.5개)
Lecture 02: 하네스란 무엇인가
5개 하위 시스템:
- Instruction (AGENTS.md/CLAUDE.md) — 프로젝트 개요, 기술 스택, 실행 명령, 제약
- Tool — 최소 권한 원칙, 필요한 도구 충분히 제공
- Environment (pyproject.toml, .nvmrc, Docker) — 자기 서술적 상태
- State (PROGRESS.md) — 완료/진행/차단 항목 추적
- Feedback — 명시적 검증 명령(pytest, type check, lint)
TypeScript/React 팀 사례: 4회 반복 개선으로 성공률 20% → 100% (모델 변경 없음)
Lecture 03: 저장소를 System of Record로
Cold-Start Test (신선한 세션이 답해야 할 5가지):
- 이 시스템은 무엇인가?
- 어떻게 구성되었는가?
- 어떻게 실행하는가?
- 어떻게 검증하는가?
- 현재 진행 상황은?
지식 가시성 격차: 저장소 외부에 존재하는 프로젝트 지식 비율, 클수록 실패율 증가
ACID 프레임워크: Atomicity(원자적 커밋) / Consistency(검증 조건) / Isolation(동시 에이전트 상태 격리) / Durability(git 추적)
e-커머스 30개 마이크로서비스 사례: Confluence/Slack 분산 → 저장소 중앙화 → 인간 개입 70% 감소
Lecture 04: 단일 지시 파일이 실패하는 이유
문제들:
- 컨텍스트 예산 고갈: 600줄 파일 = 10-20K 토큰 = 컨텍스트 8-15% 선점
- Lost in the Middle 효과 (Liu et al., 2023): 중간 정보 무시
- 신호 대 잡음비 붕괴
- 유지보수 붕괴(삭제 두려움, 추가는 자유)
Progressive Disclosure 아키텍처:
- Entry File (AGENTS.md): 50-200줄, 최대 15개 글로벌 제약
- Topic Documents: 50-150줄, docs/ 폴더, 필요 시에만 로드
- Code-Embedded Information: 타입 정의, 인터페이스 주석
SaaS팀 사례: 600줄 → 80줄 + 토픽 문서 → 성공률 45% → 72%, 보안 컴플라이언스 60% → 95%
Lecture 05: 장기 작업의 연속성 유지
컨텍스트 불안: 한계 감지 시 조기 수렴, 검증 건너뜀, 간단한 해결책 선택
4가지 상태 영속화 도구:
- PROGRESS.md: 현재 상태, 완료, 진행 중, 이슈, 다음 단계
- DECISIONS.md: "어떤 결정, 왜, 언제" 로그
- Git 체크포인트: 원자적 단위 커밋
- 초기화 루틴: 세션 시작/종료 절차
정량 효과: 재구축 시간 78% 감소 / 기능 완료율 58% → 100% / 숨겨진 결함 43% → 8%
Lecture 06: 초기화를 별도 단계로
Bootstrap Contract (4개 비협상 조건):
- 실행 가능한 환경 (의존성 설치, 환경 문제 없음)
- 검증된 테스트 프레임워크 (최소 1개 통과 예시)
- 명확한 문서화 (명령어, 현재 상태, 구조, 태스크 분해)
- 작업 분해 (수락 기준 포함 순서화된 태스크 목록)
Warm Start 전략: 빈 디렉토리가 아닌 프로젝트 템플릿 사용
근거: 초기화 전용 첫 세션 → 다중 세션 기능 완료율 31% 향상, 3-4 세션 내 시간 회수
Lecture 07: 과도한 범위 확장과 미완성 방지
WIP=1 원칙: 한 번에 하나의 기능만 활성화, 완료 후 다음 시작
공식: k개 동시 작업 → 각 C/k 인지 자원 → 임계값 이하 시 완성 불가
완료 증거 (Completion Evidence): "curl -X POST /api/register | jq .status == 201" 형태의 검증 가능한 조건
검증 완료율(VCR) = 검증된 작업 / 활성화된 작업. VCR < 1.0이면 새 작업 차단
비교:
- 무제한: 5기능 → 800줄 → 20% 검증 통과 → 3세션 후 1기능 완료
- WIP=1: 1기능 → 200줄 → 100% 검증 → 4세션 후 8기능 중 7 완료
Lecture 08: 기능 목록을 하네스 기본 단위로
3요소 구조 (기능 항목당 필수):
- 행동 설명: 구체적, 테스트 가능 ("POST /cart/items returns 201")
- 검증 명령: 실행 가능한 검증 로직
- 현재 상태: not_started / active / blocked / passing
4개 의존 하네스 컴포넌트: 스케줄러 / 검증기 / 핸드오프 리포터 / 진행 추적기
Pass-state gating: passing 전환은 검증 명령 성공 시에만, 되돌릴 수 없음
효과: 기능 완료율 45% 향상, 중복 구현 0건
Lecture 09: 조기 완료 선언 방지
자신감 보정 편향: 에이전트가 보고하는 신뢰도와 실제 품질 간 체계적 격차 (Guo et al., 2017)
Verification-Validation 이중 게이트:
- Verification: 코드가 명세한 동작을 올바르게 구현하는가
- Validation: 시스템 수준 E2E 요구사항 충족하는가
3단계 종료 검증: 문법/정적 분석 → 런타임 동작 검증 → 시스템 수준 확인
핵심: 완료 판단을 하네스가 독립적으로 수행 (에이전트 자기 평가 금지)
Lecture 10: 엔드투엔드 테스트
Testing Adequacy Gradient: 단위 ≤ 통합 ≤ E2E (각 레이어가 이전 레이어가 놓치는 결함 포착)
단위 테스트 사각지대: 인터페이스 불일치 / 상태 전파 오류 / 리소스 생명주기 / 환경 의존성
행동 변화: E2E 테스트 존재 시 에이전트가 컴포넌트 상호작용 고려, 아키텍처 경계 존중
파일 내보내기 사례: 단위 테스트 0건 발견 → E2E 5개 경계 결함 발견
Lecture 11: 하네스 내부 관측 가능성
Runtime Observability: 로그, 트레이스, 프로세스 이벤트 ("시스템이 무엇을 했는가")
Process Observability: 계획, 채점 기준, 수락 기준 ("이 변경이 왜 수락되어야 하는가")
Sprint Contract: 코딩 전 협상, 범위/검증 기준/제외 항목 명시
Evaluator Rubric: 주관적 품질 판단 → 증거 기반 구조화 채점
효과: 3배 효율 향상, 재현 가능한 품질 평가
Lecture 12: 클린 상태 세션
5차원 완료 기준: 빌드 / 테스트 / 진행상황 / 아티팩트 / 시작경로
정량 비교 (12주):
- 정리 없음: 빌드 통과율 68%, 세션 시작 60분
- 체계적 정리: 빌드 통과율 97%, 세션 시작 9분
Quality Document: 모듈별 A-C 등급 (검증 상태, 에이전트 이해도, 테스트 안정성, 아키텍처 준수)
Idempotent Operations: 정리 스크립트는 여러 번 실행해도 안전해야 함