AI 에이전트가 맨날 같은 실수를 반복하는 이유 — 하네스 엔지니어링 입문

Novel·2026년 5월 26일
AIClaudeGPTchatGPT개발코딩하네스엔지니어링

dev

목록 보기
1/1
post-thumbnail

"에이전트가 실수할 때마다, 그 실수를 다시 할 수 없도록 환경을 영구적으로 고쳐라."
— Mitchell Hashimoto, HashiCorp · Terraform 창시자

프롬프트는 "부탁"이다

프롬프트 엔지니어링의 본질적인 한계가 있다.

아무리 정교하게 써도, 결국 부탁일 뿐이다.

그래서 이런 일이 생긴다. Apiiro의 2025년 분석에 따르면, AI가 생성한 코드는 월 1만 건 이상의 보안 취약점을 레포지토리에 도입했다. 2024년 대비 10배다. 에이전트가 나쁜 게 아니다. 에이전트에게 "보안 규칙 따라줘"라고 부탁하는 방식이 문제다.

에이전트에게 "코딩 표준을 따르라"고 프롬프트하는 것과,
표준을 위반하면 PR을 자동으로 차단하는 린터를 연결하는 것은
근본적으로 다르다.

전자는 확률적 준수, 후자는 결정론적 강제다.

하네스 엔지니어링은 바로 이 차이를 시스템으로 만드는 것이다.

하네스 엔지니어링이란?

2026년 2월, HashiCorp와 Terraform을 만든 Mitchell Hashimoto가 자신의 AI 에이전트 사용 습관을 블로그에 기록했다.

"에이전트가 실수할 때마다, 그 실수를 다시 할 수 없도록 환경을 영구적으로 고쳐라."

이게 전부다. 단순하지만 강력하다.

같은 달 OpenAI도 공식 아티클을 냈다. 직접 손으로 쓴 코드 없이 100만 줄짜리 프로덕션 앱을 에이전트로만 출시한 경험담이었다. 그 태그라인:

"Humans steer. Agents execute."
사람은 방향을 잡는다. 에이전트는 실행한다.

LangChain은 한 줄로 정리했다: "Agent = Model + Harness"

프롬프트 / 컨텍스트 / 하네스 — 뭐가 다른가?

처음 들으면 헷갈린다. 세 개를 구분하면 하네스가 왜 필요한지 명확해진다.

프롬프트 엔지니어링컨텍스트 엔지니어링하네스 엔지니어링
뭘 바꾸나모델에게 하는 말모델이 보는 정보에이전트가 동작하는 환경 전체
언제까지 유효한가1회 대화1개 세션프로젝트 내내
강제력없음 (부탁)없음 (참고)있음 (시스템이 막음)
핵심 질문"어떻게 말하면 잘 할까?""뭘 보여주면 잘 할까?""어떤 환경이면 실수가 불가능해질까?"

자동차 비유로 생각하면 쉽다.

  • 모델 = 엔진. 없으면 아무것도 안 됨.
  • 컨텍스트 = 연료와 계기판. 최적화 가능.
  • 하네스 = 핸들, 브레이크, 차선 경계, 경고등, 그리고 고속도로에서 문이 떨어지지 않게 하는 것.

엔진이 좋아도 브레이크가 없으면 위험한 차다.

핵심 아이디어 — 실수를 "영구 기록"으로 바꿔라

하네스 엔지니어링의 본질은 하나다.

에이전트의 반복 실수를 일회성 수정이 아닌, 레포에 남는 영구 아티팩트로 전환한다.

실수가 생길 때마다 이렇게 대응한다:

  • 에이전트가 금지된 패턴을 반복한다 → AGENTS.md에 금지 규칙 추가
  • 이미 실패한 접근법을 또 시도한다 → docs/failures/에 기록
  • 아키텍처 결정을 매번 설명해야 한다 → docs/decisions/에 ADR로 남김
  • 코딩 컨벤션을 어긴다 → lint 규칙으로 자동 차단

에이전트가 바뀌어도, 세션이 새로 시작되어도, 팀원이 바뀌어도 규칙은 레포에 남는다.

프롬프트 창이 닫혀도 사라지지 않는다.

하네스의 3가지 레이어

실제 구현 관점에서 하네스는 세 겹으로 작동한다.

1️⃣ 제약 레이어 — 생성 전에 차단

에이전트가 코드를 쓰기 전에 솔루션 공간을 좁힌다.

AGENTS.md, 린터 설정, 타입 체크, import 경계 규칙이 여기에 해당한다.

# guard.sh — 에이전트가 Bash를 실행하기 전에 자동으로 검사
COMMAND=$(echo "$HOOK_INPUT" | python3 -c \
  "import sys,json; print(json.load(sys.stdin)['tool_input']['command'])")

# 위험 명령은 실행 자체를 막음
if echo "$COMMAND" | grep -qE "git add \.|git add -A"; then
  echo "BLOCKED: git add -A 금지. 파일을 명시적으로 지정하세요."
  exit 2
fi

프롬프트는 무시할 수 있다. 이 레이어는 무시할 수 없다.

2️⃣ 피드백 루프 — 생성 후 자기교정

에이전트가 실수를 하면 스스로 고칠 수 있는 신호를 돌려준다.

중요한 디테일: 오류 메시지가 곧 프롬프트가 된다.

  • ❌ "lint error detected" → 에이전트가 뭘 해야 할지 모름
  • ✅ "console.log 대신 logger.info({event: 'name', ...data})를 사용하세요" → 에이전트가 바로 수정 가능

테스트 실패, CI 실패, lint 오류가 모두 피드백 루프다. 이 신호가 명확할수록 사람 없이 에이전트가 자기교정한다.

3️⃣ 품질 게이트 — 머지 전에 강제

앞의 두 레이어를 통과해도 비준수 코드가 있다면, 머지를 막는다.

// .eslintrc.js — 모든 규칙을 "error"로 (warn이면 에이전트가 무시함)
module.exports = {
  rules: {
    "complexity": ["error", { "max": 10 }],
    "max-lines-per-function": ["error", { "max": 50 }],
    "max-params": ["error", 4],
  }
}

warn은 에이전트에게 "무시해도 된다"는 신호다. error로 설정해야 한다.

AGENTS.md — 모든 에이전트가 읽는 공용 헌법

Claude Code, Cursor, Codex CLI 등 각 툴마다 설정 파일이 따로 있었다. 그래서 Claude는 알지만 Codex는 모르는 컨벤션이 생겼다.

2025년 8월, OpenAI·Google·Cursor 등이 공동으로 AGENTS.md 오픈 표준을 발표했다. 어떤 에이전트 툴이든 이 파일을 네이티브로 읽는다.

AGENTS.md        ← 모든 에이전트 공통 (프로젝트 규칙, 금지 패턴, 테스트 방법)
CLAUDE.md        ← Claude 전용 추가 설정 (@AGENTS.md 임포트 후 확장)

Claude를 쓰든 Codex를 쓰든 Cursor를 쓰든, 같은 규칙 안에서 동작하게 된다.

직접 적용해보기 — harness-starter-kit

개념은 이해했다. 그런데 막상 시작하려면 막막하다.

AGENTS.md를 어떻게 써야 하지? docs/ 구조는? lint 설정은 어디서부터?

그래서 만든 게 harness-starter-kit 이다.

어떤 프로젝트에도 하네스를 바로 적용할 수 있는 스타터킷이다.

사용법은 두 가지뿐이다

방법 1 — 에이전트에게 시키기 (권장)

에이전트에게 이 프롬프트를 준다:

Use this kit to apply harness engineering to this repository:

https://github.com/baskduf/harness-starter-kit

Clone the kit into ./harness-starter-kit, read it, then apply its prompt-first
harness engineering workflow to the current project.

Rules:
- Treat the current working directory as the target repository.
- Treat ./harness-starter-kit as read-only reference material after cloning.
- Inspect this repository before editing.
- Preserve existing architecture, tools, package manager, commands, docs, and
  conventions.
- Do not blindly copy templates.
- Add only the minimum useful harness pieces.
- Prefer updating existing docs/configs over duplicating them.
- Do not overwrite or delete existing files without explaining why.

Expected result:
- project-specific AGENTS.md or updated existing agent instructions
- knowledge store if no equivalent exists
- lightweight drift checks based on this repo's real rules
- local verification commands using existing tools
- adoption report with files changed, checks to run, assumptions, remaining
  manual steps, and whether ./harness-starter-kit should be removed, ignored, or
  kept before commit

에이전트가 프로젝트를 분석해서 알아서 맞춤형으로 적용한다.
참으로 쉽다.

방법 2 — 스크립트로 바로 설치

# 먼저 어떤 파일이 생성될지 미리 확인 (dry-run)
python harness-starter-kit/scripts/apply_harness.py --target . --profile generic --dry-run

# 실제 적용
python harness-starter-kit/scripts/apply_harness.py --target . --profile generic

프로필은 세 가지: generic(언어 무관), python, typescript

적용 후 생기는 것들

my-project/
├── AGENTS.md                  ← 에이전트 행동 규칙
├── docs/
│   ├── decisions/             ← 아키텍처 결정 기록 (ADR)
│   ├── failures/              ← 시도했다 실패한 접근법
│   ├── conventions/           ← 프로젝트 고유 컨벤션
│   └── domain/                ← 비즈니스 용어, 도메인 지식
└── scripts/
    └── check_docs_drift.py    ← 하네스 자체가 낡지 않도록 감지

마치며 — 실수를 시스템으로 만들어라

하네스 엔지니어링의 핵심은 간단하다.

에이전트가 실수할 때마다 → 레포가 조금씩 더 똑똑해진다.

프롬프트는 대화창을 닫으면 사라진다. 하네스는 레포에 남는다.

2025년이 에이전트의 해였다면, 2026년은 하네스의 해다. 에이전트를 만드는 건 쉬운 부분이었다. 에이전트를 일관되고 안전하게 동작하게 만드는 것이 진짜 엔지니어링이다.

부탁하지 않는다. 환경이 강제한다.

👉 harness-starter-kit 바로 가기
어떤 프로젝트에도 바로 적용할 수 있는 하네스 엔지니어링 스타터킷

⭐ 도움이 됐다면 GitHub 스타 부탁드립니다!

참고 자료

profile
Novel
ssafy_elonmusk

0개의 댓글