Harness Engineering 실무 가이드: AI 에이전트가 잘 일하게 만드는 운영 설계

AI 에이전트를 붙였는데 생산성은 오르지 않고, 리뷰 비용만 늘어나는 팀이 있다. 반대로 같은 모델을 써도 PR 품질이 빠르게 안정되는 팀도 있다.

차이는 프롬프트 문장력보다 작업 환경 설계에 있다. OpenAI가 2026년 2월 11일 공개한 글에서 설명한 Harness Engineering은 바로 이 문제를 다룬다. 에이전트가 똑똑해지기를 기다리는 대신, 에이전트가 실수하기 어려운 작업 환경을 만든다는 접근이다.

이 글은 개념 소개보다 실무 적용에 집중한다. "우리 팀에 당장 무엇을 바꾸면 되나?"라는 질문에 답하도록, 실제 개발팀 시나리오 기준으로 정리했다.

Harness Engineering을 한 문장으로 설명하면

Harness Engineering은 AI 에이전트가 일하는 컨텍스트, 제약, 피드백 루프를 설계하는 일이다.

말을 잘 타기 위해 말을 더 세게 채찍질하는 게 아니라, 마구를 잘 맞추는 것에 가깝다. 프롬프트를 조금씩 바꾸는 대신 아래 세 가지를 다듬는다.

축	질문	실무에서 손대는 것
Context Engineering	에이전트가 무엇을 알아야 하나	`AGENTS.md`, `docs/`, 예제, 실패 기록
Architectural Constraints	어디까지 허용하고 어디서 막을까	린터, 구조 테스트, 생성 템플릿
Entropy Management	시간이 갈수록 왜 코드가 흐트러질까	정리 작업, 중복 제거, 문서-코드 동기화

OpenAI는 이 접근으로 엔지니어 3명이 5개월 동안 Codex 에이전트와 함께 100만 줄이 넘는 프로덕션 코드를 작성했고, 사람이 직접 쓴 코드는 0줄이었다고 설명한다. 월 평균 105개의 PR이 에이전트에서 나왔다. 포인트는 "모델이 마법처럼 좋아졌다"가 아니다. 에이전트가 일하는 방식 자체를 설계했다는 데 있다.

왜 읽고 나면 막막했는가

Harness Engineering 글을 처음 읽으면 대체로 두 군데에서 막힌다.

개념은 맞는데 어디부터 손대야 할지 감이 안 잡힌다.
"환경을 설계하라"는 말이 너무 넓어서 우리 팀 체크리스트로 번역되지 않는다.

실무에서는 이걸 이렇게 바꾸면 된다.

추상 개념
→ 에이전트가 자주 내는 실수 목록 작성
→ 그 실수를 막는 파일/테스트/도구 추가
→ 다음 실수가 생기면 또 환경 수정

즉, Harness Engineering은 거대한 프레임워크 도입이 아니라 실수 재발 방지 시스템에 가깝다.

이런 팀이면 바로 효과가 난다

아래 증상이 있으면 Harness Engineering이 잘 맞는다.

같은 요청인데 에이전트 산출물 품질이 들쭉날쭉하다
코드 리뷰에서 늘 같은 지적이 반복된다
새 파일을 만들 때 팀 규칙이 자주 누락된다
세션이 길어질수록 에이전트가 초반 결정을 잊는다
기능은 돌아가지만 구조가 조금씩 망가진다

반대로 아직 에이전트를 거의 안 쓰는 팀이라면, 먼저 작은 워크플로우 하나부터 자동화하는 편이 낫다. 이 순서는 Auto Memory에서 Skill로: 복잡하게 시작하지 않는 지식 관리 순서에서 함께 보면 이해가 쉽다.

실무 적용 1: AGENTS.md를 "규칙집"이 아니라 "실패 로그"로 운영하기

가장 먼저 바꿀 것은 AGENTS.md다. 많은 팀이 여기에 프로젝트 소개, 스택 설명, 코딩 스타일을 길게 적어둔다. 그런데 에이전트 입장에서는 그런 문서보다 **"지난주에 무엇을 틀렸는지"**가 더 중요하다.

흔한 실패 패턴

예를 들어 결제 서비스를 운영하는 팀을 생각해보자.

환불 API를 추가할 때 서비스 레이어를 건너뛰고 DB 접근
새 라우트를 만들었는데 권한 미들웨어 누락
환경변수를 직접 읽어서 타입 안전성 깨짐

이때 AGENTS.md는 백과사전이 아니라 재발 방지 체크포인트가 되어야 한다.

# AGENTS.md
 
## Build & Test
- build: `bun run build`
- test: `bun test`
 
## 반드시 지킬 규칙
- API route에서 DB 직접 접근 금지. `src/services/*` 경유
- 새 route는 `withAuth()`로 감쌀 것
- `process.env` 직접 접근 금지. `src/config.ts` 사용
 
## 자주 발생한 실수
- 환불 API 작성 시 `refundRepo`를 route에서 직접 import하는 실수 반복
- 신규 admin route에서 권한 체크 누락 2회 발생
- Stripe webhook 예제 복사 후 에러 핸들러 누락

이 문서가 잘 작동하면, 에이전트는 "이 프로젝트가 어떤 회사에서 만든 서비스인가"보다 **"무엇을 하면 리뷰에서 바로 되돌려질까"**를 먼저 이해한다.

적용 기준

AGENTS.md에 넣을 내용은 세 가지면 충분하다.

실행 명령: 빌드, 테스트, 린트
아키텍처 규칙: 절대 어기면 안 되는 경계
최근 실패 패턴: 실제로 자주 틀린 것

나머지는 docs/architecture.md, docs/domain.md처럼 분리하는 편이 낫다. 이 주제는 Claude Code 플러그인 구조 — Agents, Commands, Skills 차이와 선택 기준과 함께 보면, 어떤 규칙을 어디에 둬야 하는지 더 선명해진다.

실무 적용 2: 프롬프트가 아니라 빌드 에러로 막기

Harness Engineering의 가장 중요한 원칙은 이것이다.

말로 주의 주지 말고, 위반하면 실패하게 만들어라.

예를 들어 "UI에서 Repository를 직접 import하지 마세요"라는 규칙을 프롬프트에 적어둘 수는 있다. 하지만 에이전트는 급하면 무시한다. 대신 lint나 테스트로 막으면 결과가 완전히 달라진다.

사례: Next.js 서비스에서 import 경계 강제

// eslint.config.mjs 또는 import 규칙 설정
{
  rules: {
    "import/no-restricted-paths": ["error", {
      zones: [
        {
          target: "./src/components",
          from: "./src/repositories",
          message: "UI에서 Repository 직접 접근 금지. src/services를 경유하세요."
        }
      ]
    }]
  }
}

이제 에이전트가 components에서 repositories를 직접 불러오면 바로 실패한다. 중요한 건 실패 메시지다. 단순히 invalid import라고 쓰지 말고, 어떻게 고쳐야 하는지까지 적어줘야 한다.

UI에서 Repository 직접 접근 금지.
src/services/user-service.ts를 경유하세요.
예시: import { getUser } from "@/services/user-service"
참고: docs/architecture.md#dependency-rules

에이전트는 이 메시지를 읽고 다시 시도한다. 사람 리뷰어가 매번 설명할 필요가 없다.

실무에서 바로 넣기 좋은 가드레일

import 제한 규칙
API route 템플릿 강제
필수 미들웨어 누락 검사
테스트 폴더 위치 규칙
금지 라이브러리 사용 검사

핵심은 "코드 품질을 높이는 일반 규칙"이 아니라 에이전트가 반복해서 어기는 규칙부터 막는 것이다.

실무 적용 3: 바로 코딩시키지 말고 계획을 먼저 승인받기

에이전트가 가장 크게 사고 내는 순간은, 문제를 충분히 이해하기 전에 곧바로 구현을 시작할 때다.

예를 들어 사용자 요청이 이렇다고 하자.

"결제 시스템에 부분 환불 기능 추가해줘."

사람 개발자도 바로 코딩하지 않는다. 기존 정산 로직, 환불 한도, 웹훅, 관리자 화면까지 영향을 본다. 에이전트도 마찬가지다. 실무에서는 아래 순서를 강제하는 편이 훨씬 안전하다.

1. Plan: 수정 파일, 영향 범위, 테스트 전략만 먼저 작성
2. Review: 사람 또는 리드 에이전트가 계획 확인
3. Execute: 승인된 계획에 따라 코드 변경

좋은 계획 문서의 최소 형식

## Plan
- 대상 파일: `src/services/refund.ts`, `src/app/api/refunds/route.ts`
- 변경 범위: 부분 환불 금액 검증, 웹훅 이벤트 처리, 관리자 UI 표시
- 아키텍처 영향: 정산 서비스 인터페이스 변경 필요
- 테스트: 단위 테스트 2개, 통합 테스트 1개 추가
- 위험 요소: 중복 환불 방지 idempotency 키 처리 필요

이 단계 하나만 넣어도 품질이 꽤 올라간다. 잘못된 방향으로 300줄 작성한 뒤 되돌리는 비용이 줄기 때문이다.

실무 팁은 단순하다.

새 기능은 plan 없이 시작하지 않기
계획에 수정 파일 목록을 꼭 넣기
테스트 전략이 없으면 구현 승인하지 않기

작은 팀이라도 이 규칙 하나는 효과가 크다. 에이전트를 "빠른 타이피스트"가 아니라 계획을 제출하는 주니어 개발자처럼 다루는 셈이다.

실무 적용 4: 엔트로피 관리를 별도 작업으로 분리하기

에이전트가 만든 코드는 대개 "돌아가는 코드"는 잘 만든다. 문제는 몇 주가 지나면 코드베이스가 미세하게 흐트러진다는 점이다.

비슷한 유틸 함수가 이름만 바뀐 채 두 번 생김
같은 에러 처리 패턴이 파일마다 조금씩 다름
문서와 실제 구현이 어긋남
더 이상 쓰지 않는 export와 의존성이 남음

이건 사람 개발자에게도 생기지만, 에이전트는 속도가 빠른 만큼 작은 불일치를 더 빨리 퍼뜨린다.

그래서 정기 작업이 필요하다.

주간 정리 루프 예시

매주 금요일 오후
1. 사용하지 않는 export 탐지
2. 중복 코드 탐지
3. AGENTS.md와 docs/ 링크 유효성 점검
4. 최근 1주일 PR에서 반복된 리뷰 코멘트 추출
5. 재발 방지 규칙 1개 이상 추가

이 작업은 사람이 직접 해도 되고, 에이전트에게 시켜도 된다. 다만 결과는 반드시 파일 수정 또는 규칙 추가로 끝나야 한다. "정리했습니다"라는 보고만 받고 끝내면 아무것도 바뀌지 않는다.

실무 사례로 보면 더 쉽다

Harness Engineering은 팀 유형마다 적용 방식이 조금 다르다.

1. 스타트업 제품팀

문제:

에이전트가 빠르게 코드를 뽑지만 PR 스타일이 들쭉날쭉함

먼저 할 일:

AGENTS.md 1개
import 규칙 2개
새 기능 plan 승인 규칙

기대 효과:

리뷰 코멘트의 반복 감소
온보딩 문서보다 실제 작업 품질이 먼저 안정화

2. 사내 플랫폼팀

문제:

여러 저장소에서 같은 실수가 반복됨

먼저 할 일:

공통 AGENTS.md 템플릿
서비스 생성 템플릿
구조 테스트 공통 패키지

기대 효과:

저장소마다 프롬프트를 새로 쓰지 않아도 됨
팀별 편차보다 플랫폼 규칙이 우선 적용됨

3. 레거시 시스템 유지보수팀

문제:

에이전트가 맥락을 잘못 잡고 위험한 파일까지 건드림

먼저 할 일:

수정 가능 디렉터리 명시
금지 영역 명시
승인 없는 파일 이동/리네임 금지

기대 효과:

안전하지 않은 대규모 수정 감소
"조심해서 고쳐라" 같은 추상 지시를 구체 규칙으로 대체

30일 도입 순서

처음부터 다 하려 하면 실패한다. 이 순서가 현실적이다.

1주차: 실패 수집

최근 10개 PR에서 반복 리뷰 코멘트 모으기
에이전트가 자주 틀린 규칙 5개 적기
AGENTS.md를 100줄 안팎으로 정리하기

2주차: 제약 추가

import 제한 1개
필수 미들웨어 검사 1개
새 파일 템플릿 1개

3주차: 계획 승인 도입

기능 추가는 plan부터 제출
계획에 파일 목록과 테스트 전략 필수화
승인 없이 구현 시작 금지

4주차: 정리 루프 고정

주간 정리 작업 캘린더 등록
리뷰 코멘트를 규칙으로 환원
더 이상 안 쓰는 규칙 제거

이렇게 하면 한 달 안에 "에이전트가 운 좋으면 잘하는 상태"에서 "대체로 예측 가능하게 일하는 상태"로 옮겨갈 수 있다.

자주 하는 오해

오해 1: 좋은 모델이면 Harness가 덜 중요하다

반대다. 모델이 강할수록 더 넓게 행동하기 때문에, 경계 설계의 가치가 커진다.

오해 2: 프롬프트를 길게 쓰면 해결된다

길어진 프롬프트는 금방 낡고, 중요한 규칙이 묻힌다. 자주 위반되는 내용은 빌드나 테스트로 옮겨야 한다.

오해 3: 문서 작업이라 개발 속도가 느려진다

문서를 늘리는 게 아니다. 리뷰에서 반복되는 설명을 파일과 도구로 옮기는 것이다. 장기적으로는 오히려 더 빠르다.

정리

Harness Engineering의 실무적 의미는 단순하다.

에이전트를 더 잘 설득하려고 애쓰기보다, 실수했을 때 바로 드러나고 다시는 같은 방식으로 틀리기 어려운 환경을 만드는 것이다.

처음부터 완성된 체계를 만들 필요는 없다. 이번 주 리뷰에서 가장 자주 나온 실수 하나를 고르고, 그것을 AGENTS.md, 린터, 테스트, 템플릿 중 하나로 옮기면 된다. 그 한 줄이 Harness Engineering의 시작이다.

Harness Engineering 실무 가이드: AI 에이전트가 잘 일하게 만드는 운영 설계

Harness Engineering을 한 문장으로 설명하면

왜 읽고 나면 막막했는가

이런 팀이면 바로 효과가 난다

실무 적용 1: AGENTS.md를 "규칙집"이 아니라 "실패 로그"로 운영하기

흔한 실패 패턴

적용 기준

실무 적용 2: 프롬프트가 아니라 빌드 에러로 막기

사례: Next.js 서비스에서 import 경계 강제

실무에서 바로 넣기 좋은 가드레일

실무 적용 3: 바로 코딩시키지 말고 계획을 먼저 승인받기

좋은 계획 문서의 최소 형식

실무 적용 4: 엔트로피 관리를 별도 작업으로 분리하기

주간 정리 루프 예시

실무 사례로 보면 더 쉽다

1. 스타트업 제품팀

2. 사내 플랫폼팀

3. 레거시 시스템 유지보수팀

30일 도입 순서

1주차: 실패 수집

2주차: 제약 추가

3주차: 계획 승인 도입

4주차: 정리 루프 고정

자주 하는 오해

오해 1: 좋은 모델이면 Harness가 덜 중요하다

오해 2: 프롬프트를 길게 쓰면 해결된다

오해 3: 문서 작업이라 개발 속도가 느려진다

정리

References

이 글을 참조하는 글

관련 글