프롬프트는 부탁일 뿐이다 — AI 에이전트 시대를 여는 하네스 엔지니어링

작성자:

“AI한테 이것만은 하지 말라고 분명히 말했는데, 또 해버렸네.”

프롬프트 엔지니어링에 시간을 쏟아본 사람이라면 한 번쯤 겪었을 좌절이다. “DB를 직접 수정하지 마”, “axios 대신 fetch를 써”라고 아무리 정교하게 지시해도, 컨텍스트가 길어지거나 모델이 바뀌면 AI는 약속을 어긴다. 프롬프트는 결국 부탁일 뿐이지, 강제가 아니기 때문이다.

여기서 등장하는 개념이 바로 하네스 엔지니어링(Harness Engineering)이다.

하네스란 무엇인가 — 부탁에서 구조로

하네스(Harness)는 원래 말을 제어하기 위한 마구를 뜻한다. AI 개발에서의 하네스도 같은 역할이다. AI가 활동하는 구조적 환경 자체를 설계하여, 프롬프트 없이도 규칙이 지켜지게 만드는 것이다.

프롬프트 엔지니어링이 “말을 잘 거는 기술”이라면, 하네스 엔지니어링은 “말이 딴길로 새지 못하게 울타리를 치는 설계”다. 엔지니어의 역할이 대화 상대에서 시스템 설계자로 이동하는 것이다.

하네스 엔지니어링의 3대 핵심 메커니즘

1. CPS 프레임워크 — AI에게 세계관을 먼저 준다

AI에게 바로 코드를 짜라고 시키는 대신, 먼저 세 가지 맥락을 명확히 정의한 문서를 제공한다.

  • Context — 이 프로젝트의 비즈니스 배경과 기술 스택은 무엇인가?
  • Problem — 지금 해결하려는 구체적인 문제는 무엇인가?
  • Solution — 어떤 아키텍처와 로직으로 이 문제를 풀 것인가?

이 세 가지가 명확히 정의된 문서가 하네스의 기초 체력이 된다. AI는 코드를 짜기 전에 “왜 이 방식이어야 하는지”를 이해한 상태에서 출발한다.

2. 멱등성과 자동 강제 — 어떤 모델을 써도 같은 결과

하네스의 가장 강력한 무기는 멱등성(Idempotency)이다. 어떤 AI 모델을 써도 동일한 품질이 보장되도록 시스템적으로 강제하는 것이다.

예를 들어 “파일명에 Detail을 쓰지 마”라는 규칙이 있다면, 프롬프트에 적는 대신 린터(Linter)나 프리커밋 훅(Pre-commit Hook)으로 해당 파일명이 포함되면 커밋 자체가 실패하게 만든다.

AI는 실패 메시지를 보고 스스로 코드를 수정한다. 인간이 개입하지 않아도 품질이 유지되는 구조다.

하네스 엔지니어링의 자동 교정 루프를 표현한 추상 일러스트

3. 자동 교정 루프 — AI가 스스로 오류를 고친다

구현 에이전트와 검토 에이전트를 분리하는 것이 핵심이다. 구현 에이전트가 코드를 짜면, 하네스 시스템이 자동으로 테스트를 돌리고 에러 메시지를 다시 에이전트에게 던진다.

AI가 자신의 오류를 보고 수정하고, 다시 테스트를 돌리고, 통과할 때까지 반복한다. 이 피드백 루프가 하네스 엔지니어링의 정수다. 3회 실패하면 작업을 멈추고 인간 엔지니어에게 맥락 요약과 함께 보고한다.

프롬프트 vs 하네스 — 무엇이 다른가

구분프롬프트 엔지니어링하네스 엔지니어링
성격부탁 (Request)강제 (Enforcement)
일관성모델/컨텍스트에 따라 변동어떤 모델이든 동일 결과 (멱등성)
검증 방식사람이 결과를 리뷰린터, 테스트가 자동 검증
오류 대응프롬프트 수정 후 재시도AI가 에러 메시지 보고 자동 교정
확장성프로젝트 커질수록 한계규칙 추가로 확장 가능

하네스 도입 후의 변화 — 선수에서 감독으로

하네스 엔지니어링을 도입하면 개발자는 더 이상 오타나 컨벤션 체크에 시간을 쓰지 않는다. 대신 아키텍처 설계, 비즈니스 로직 검증, 시스템 전체의 품질 전략에 집중하게 된다.

마치 직접 공을 차는 선수에서, 팀의 전술을 짜고 시스템을 운영하는 감독으로 역할이 격상되는 것이다.

OpenAI의 엔지니어들이 코드 한 줄 쓰지 않고 제품을 배포할 수 있었던 비결은 AI가 똑똑해서가 아니다. 그들이 만든 하네스가 견고했기 때문이다.

실전 예제 — 하네스는 이렇게 구성한다

개념만으로는 감이 잡히지 않을 수 있다. 실제로 하네스를 구성하는 핵심 파일 세 가지를 살펴보자.

1. CLAUDE.md — 프로젝트의 세계관을 정의한다

프로젝트 루트에 CLAUDE.md 파일을 만들면, AI는 매 대화 시작 시 이 파일을 자동으로 읽는다. 프롬프트에 매번 반복하지 않아도 되는 “불변 규칙”을 여기에 적는다.

# CLAUDE.md

## 프로젝트 개요
Next.js 14 + TypeScript 기반 SaaS 대시보드.
백엔드는 Supabase, 인증은 NextAuth.

## 코딩 컨벤션
- 컴포넌트 파일명: PascalCase (예: UserCard.tsx)
- 파일명에 Detail, Info, Data 금지 → 구체적 도메인 명사 사용
- API 호출: fetch만 사용 (axios 금지)
- DB 직접 수정 금지 — 반드시 마이그레이션 파일 생성

## 디렉토리 구조
src/
├── app/          # Next.js App Router
├── components/   # 공용 UI 컴포넌트
├── features/     # 도메인별 기능 모듈
└── lib/          # 유틸리티, API 클라이언트

2. settings.json (hooks) — 규칙을 자동으로 강제한다

Claude Code의 hooks 설정으로 AI가 파일을 저장하거나 커밋할 때 자동으로 린터와 테스트를 실행한다. 규칙 위반 시 AI가 스스로 수정한다.

// .claude/settings.json
{
  "hooks": {
    "PreCommit": [
      {
        "command": "npx eslint --max-warnings 0 .",
        "description": "ESLint 통과 필수"
      },
      {
        "command": "npx tsc --noEmit",
        "description": "TypeScript 타입 체크"
      }
    ],
    "PostWrite": [
      {
        "command": "bash -c 'if echo \"$FILEPATH\" | grep -qE \"(Detail|Info|Data)\\.\"; then echo \"ERROR: 파일명에 Detail/Info/Data 사용 금지\" && exit 1; fi'",
        "description": "금지 파일명 자동 차단"
      }
    ]
  }
}

3. 스킬 파일 — 반복 워크플로우를 자동화한다

자주 수행하는 작업을 스킬(슬래시 커맨드)로 정의하면, 복잡한 워크플로우도 한 줄 명령으로 실행된다.

# .claude/commands/add-api.md

## 설명
새로운 API 엔드포인트를 추가한다.

## 실행 흐름
1. $ARGUMENTS에서 엔드포인트명과 HTTP 메서드를 파싱
2. src/app/api/{엔드포인트}/route.ts 파일 생성
3. Zod 스키마로 입력 검증 코드 포함
4. 에러 핸들링 미들웨어 적용
5. 유닛 테스트 파일 자동 생성
6. ESLint + TypeScript 체크 실행
7. 실패 시 자동 수정 후 재시도 (최대 3회)

이 세 파일이 하네스의 뼈대다. CLAUDE.md가 “무엇을 해야 하는지”를 정의하고, hooks가 “하지 말아야 할 것”을 강제하며, 스킬이 “어떻게 할 것인지”를 자동화한다.

정리: 당신의 프로젝트에는 마구가 있는가

바이브 코딩의 결과물이 매번 달라져서 고민이라면, AI가 짠 코드를 리뷰하느라 지쳐있다면 — 이제 프롬프트를 고치는 대신 하네스를 깎아야 할 때다.

프롬프트는 부탁이고, 하네스는 시스템이다.

시스템으로 통제된 자유 안에서, AI의 진정한 생산성이 시작된다.

© 2012 Yapsoft