AI 에이전트 하네스 설계: 장기 작업을 실패하지 않게 만드는 Plan·툴·검증 루프

요약: AI 에이전트의 성능은 모델만으로 결정되지 않습니다. 어떤 파일을 읽게 할지, 어떤 도구를 어떤 스키마로 줄지, 중간 계획을 어디에 남길지, 결과를 어떻게 검증할지가 실제 성공률을 좌우합니다. 이 주변 구조를 하네스라고 부릅니다. 개발팀이 장기 작업용 에이전트를 만들 때는 프롬프트보다 하네스 설계가 먼저입니다.

왜 하네스가 중요한가

요즘 AI 에이전트 논의는 모델 이름 중심으로 흐르기 쉽습니다. 어떤 모델이 더 똑똑한지, 코딩 벤치마크가 몇 점인지, 컨텍스트 창이 얼마나 큰지가 자주 언급됩니다. 하지만 실무에서 에이전트가 실패하는 이유는 모델 지능만이 아닙니다. 컨텍스트를 잘못 받거나, 도구 사용법을 오해하거나, 중간 상태를 잃거나, 검증 없이 결과를 끝내기 때문에 실패합니다.

하네스 엔지니어링은 이 문제를 다룹니다. 에이전트 주변의 실행 환경을 설계하는 일입니다. 계획 문서, 파일 시스템, 도구 스키마, 권한, 테스트, 로그, 메모리, 사람 승인 단계가 모두 포함됩니다. OpenAI, Anthropic, Google, LangChain, Microsoft 등 여러 팀이 2026년에 하네스와 컨텍스트 엔지니어링을 별도 주제로 다루는 이유도 여기에 있습니다.

개발팀이 봐야 할 핵심은 간단합니다. “좋은 모델을 고르면 된다”가 아니라 “모델이 실패하기 어려운 작업 환경을 만들어야 한다”입니다. 특히 장기 작업에서는 이 차이가 큽니다. 한 번에 끝나는 요약은 프롬프트만으로도 됩니다. 하지만 며칠에 걸친 리팩터링, 운영 장애 분석, 대량 문서 정리, 멀티 에이전트 개발은 하네스 없이는 금방 흔들립니다.

하네스를 구성하는 5가지 요소

실무용 하네스는 크게 5가지로 나눌 수 있습니다.

1. 컨텍스트 전달
2. 계획과 상태 저장
3. 도구 인터페이스
4. 검증 루프
5. 권한과 사람 승인

컨텍스트 전달은 에이전트가 무엇을 알아야 하는지 정하는 일입니다. 많은 팀이 관련 문서를 전부 넣으려고 합니다. 하지만 컨텍스트가 많다고 항상 좋지는 않습니다. 오래된 문서, 중복 지시, 서로 충돌하는 요구사항이 섞이면 모델은 더 헷갈립니다.

계획과 상태 저장은 장기 작업에서 필수입니다. 에이전트가 지금 무엇을 하려는지, 이미 어떤 결정을 했는지, 다음에 무엇을 해야 하는지 남겨야 합니다. Plan.md, Implement.md, Decisions.md, Progress.md 같은 파일이 유용합니다.

도구 인터페이스는 에이전트가 외부 세계와 상호작용하는 방식입니다. 파일 읽기, 검색, DB 조회, 테스트 실행, 배포 요청 같은 도구를 줄 때 이름과 파라미터가 명확해야 합니다. 사람에게 좋은 API가 모델에게도 좋은 API는 아닙니다. 모델이 오해하지 않게 입력과 출력이 작고 분명해야 합니다.

검증 루프는 결과를 확인하는 단계입니다. 코드라면 테스트와 타입체크가 있고, 문서라면 링크 검증과 금지어 검사, 데이터 작업이라면 샘플 검산이 있습니다.

권한과 사람 승인은 위험한 액션을 막는 장치입니다. 삭제, 외부 전송, 결제, 운영 변경은 자동 실행하지 않게 해야 합니다.

컨텍스트 설계: 많이 주는 것보다 잘라 주는 것이 낫다

에이전트에게 컨텍스트를 줄 때 가장 흔한 실수는 “전부 읽어”입니다. 작은 프로젝트에서는 통할 수 있습니다. 큰 프로젝트에서는 실패합니다. 문서가 많아질수록 중복과 오래된 정보가 늘어납니다. 모델은 어떤 문서가 최신인지 판단하기 어렵습니다.

좋은 컨텍스트 설계는 레이어를 나눕니다.

• 항상 읽는 핵심 규칙
• 작업별로 읽는 관련 문서
• 필요할 때 검색하는 참고 자료
• 절대 읽지 않아야 하는 민감 자료

예를 들어 코딩 에이전트라면 항상 읽는 파일은 AGENTS.md, README.md, package.json, 주요 아키텍처 문서 정도로 제한합니다. 결제 기능을 수정할 때만 결제 도메인 문서를 읽게 하고, 디자인 수정 때는 디자인 시스템 문서를 읽게 합니다.

컨텍스트에는 우선순위도 있어야 합니다. 오래된 문서와 최신 작업 지시가 충돌하면 최신 작업 지시를 따르게 해야 합니다. 문서 안에 “이 파일은 더 이상 쓰지 않음” 같은 상태 표시가 있으면 좋습니다.

좋은 규칙은 짧습니다.

항상 읽기: README.md, AGENTS.md, docs/architecture.md
작업별 읽기: docs/domains/{domain}.md
최신 기준: docs/decisions/*.md 중 날짜가 가장 최근인 문서
금지: secrets, raw customer exports, production dumps

이 정도만 있어도 에이전트가 엉뚱한 문서를 읽고 잘못된 결정을 할 가능성이 줄어듭니다.

계획 파일: 장기 작업의 기억을 밖으로 빼라

장기 작업에서 에이전트가 흔들리는 가장 큰 이유는 상태를 잃기 때문입니다. 처음에는 목표를 잘 이해했지만, 중간에 오류를 고치고 테스트를 돌리다 보면 원래 목적을 잊습니다. 컨텍스트가 압축되거나 세션이 끊기면 더 심해집니다.

그래서 계획과 상태를 파일로 남겨야 합니다. 메모리 안에만 두면 안 됩니다. 파일은 사람이 볼 수 있고, 다른 에이전트도 이어받을 수 있고, 세션이 바뀌어도 유지됩니다.

추천 구조는 다음과 같습니다.

work/
  Plan.md          # 목표, 범위, 완료 기준
  Implement.md     # 작업 순서와 현재 진행률
  Decisions.md     # 바꾼 결정과 이유
  Verify.md        # 테스트, 체크리스트, 남은 리스크
  Notes.md         # 조사 중 발견한 참고 사항

Plan.md에는 목표와 비목표를 같이 적습니다. 예를 들어 “로그인 UI 개선” 작업이라면 비목표에 “인증 로직 변경 없음”, “DB 스키마 변경 없음”을 적습니다. 그래야 에이전트가 범위를 넓히지 않습니다.

Decisions.md는 생각보다 중요합니다. “왜 이 라이브러리를 선택했는지”, “왜 이 테스트를 스킵했는지”, “왜 기존 API를 유지했는지”가 남아야 나중에 사람이 이해할 수 있습니다.

도구 설계: 모델이 헷갈리지 않는 API가 좋은 API다

에이전트 도구는 사람용 CLI와 다르게 설계해야 합니다. 사람은 도움말을 읽고 맥락을 해석할 수 있지만, 모델은 도구 이름과 스키마를 보고 사용법을 추론합니다. 이름이 애매하면 잘못 씁니다. 출력이 너무 길면 중요한 정보를 놓칩니다. 에러 메시지가 불친절하면 같은 실수를 반복합니다.

좋은 도구는 다음 특징을 가집니다.

• 이름이 동사+대상으로 명확합니다.
• 입력 파라미터가 작고 필수값이 분명합니다.
• 출력은 다음 행동에 필요한 정보만 줍니다.
• 실패 시 원인과 재시도 방법을 같이 줍니다.
• 위험한 작업은 dry-run 또는 approval 모드를 제공합니다.

예를 들어 run이라는 도구보다 run_tests가 낫습니다. query보다 query_orders_by_user_id가 낫습니다. 출력도 전체 로그 10,000줄보다 실패한 테스트 이름, 에러 메시지, 재현 명령만 주는 편이 낫습니다.

도구에는 정책도 들어가야 합니다. 삭제 도구라면 기본값을 dryRun: true로 두고, 실제 삭제는 명시적 승인 없이는 안 되게 해야 합니다. 외부 메시지 전송 도구도 마찬가지입니다.

검증 루프: 완료 조건을 모델의 말로 두지 않는다

에이전트가 “완료했습니다”라고 말하는 것은 완료가 아닙니다. 완료는 검증으로 판단해야 합니다. 코드 작업이라면 테스트, 타입체크, 린트, 빌드가 최소 기준입니다. 문서 작업이라면 링크, 제목 규칙, 길이, 금지 표현, 중복 여부를 검사해야 합니다. 데이터 작업이라면 샘플 조회와 카운트 검산이 필요합니다.

검증 루프는 작업 전에 정해야 합니다. 나중에 붙이면 에이전트가 검증하기 쉬운 방식으로 작업하지 않습니다.

예시:

완료 기준
- npm test 통과
- npm run typecheck 통과
- 변경 파일 10개 이하
- 마이그레이션 없음
- /checkout 수동 스모크 테스트 통과

문서 생성 작업이라면 이렇게 둘 수 있습니다.

완료 기준
- 제목 prefix 금지 정규식 통과
- 본문 첫 줄 H1 금지
- 3000자 이상
- H2 5개 이상
- 체크리스트로 마무리
- 가짜 URL 없음

이런 기준은 모델이 스스로도 확인할 수 있고, 사람이 나중에 검토하기도 쉽습니다.

운영 예시: PR 리뷰 에이전트 하네스

PR 리뷰 에이전트를 만든다고 가정해보겠습니다. 단순히 “이 PR 리뷰해줘”라고 하면 결과가 들쑥날쑥합니다. 하네스를 붙이면 안정성이 올라갑니다.

구조는 이렇습니다.

1. 컨텍스트: 변경 diff, 관련 테스트, 코딩 규칙, 최근 장애 기록만 제공
2. 계획: 보안, 성능, 호환성, 테스트 누락 순서로 검토
3. 도구: 테스트 실행, 파일 검색, 의존성 확인
4. 검증: 지적 사항마다 파일·라인·재현 방법 요구
5. 권한: 코드 수정은 제안만, 자동 push 금지

출력 형식도 고정합니다.

## 반드시 수정
- [파일:라인] 문제 / 이유 / 재현 방법 / 제안 수정

## 확인 필요
- 근거가 부족하지만 위험해 보이는 항목

## 괜찮음
- 검토했지만 문제 없었던 영역

이렇게 하면 리뷰 품질이 좋아집니다. 모델이 추상적인 조언을 늘어놓기보다 근거 있는 항목을 내게 됩니다.

지금 적용할 체크리스트

AI 에이전트 하네스를 만들 때 아래 기준을 먼저 적용하세요.

• 작업별로 항상 읽을 문서와 필요할 때 읽을 문서를 나눈다.
• Plan.md, Decisions.md, Verify.md처럼 상태를 파일로 남긴다.
• 도구 이름은 구체적으로 짓고, 출력은 다음 행동에 필요한 정보만 주게 한다.
• 삭제, 외부 전송, 배포, 결제 같은 액션은 approval 또는 dry-run을 기본값으로 둔다.
• 완료 기준을 작업 시작 전에 정한다.
• 테스트, 타입체크, 링크 검사, 제목 검사처럼 자동 검증 가능한 항목을 우선 둔다.
• 에이전트가 실패했을 때 이어받을 수 있도록 로그와 결정 이유를 남긴다.

좋은 에이전트는 좋은 모델 하나로 만들어지지 않습니다. 모델이 일하기 쉬운 환경, 실패를 줄이는 도구, 사람이 확인할 수 있는 로그가 같이 있어야 합니다. 장기 작업을 맡길 계획이라면 프롬프트를 더 길게 쓰기 전에 하네스부터 설계하세요.