하네스 엔지니어링

김진효·2026년 9월 28일

[CS] 면접 대비

목록 보기

12/12

유튜브 '아는 개발자' 분의 영상을 보고 정리하고 싶었던 하네스 엔지니어링... 밑에 출처에 남기겠지만 이 분 영상을 보고 정리했다고 보면 될 것 같다 (사실 영상으로 보는게 나을 것 같기도 하하)
최근 채용 공고에 AI 활용 역량을 요구하는 경우도 많아지고있기에 한 번쯤 짚고 가면 좋을 것 같아 정리하게 되었다!

하네스 엔지니어링

'에이전트의 반복되는 같은 실수를 어떻게 해결할 수 있을까'에서 시작
🏇 Harness Engineering
에이전트가 실수를 할 때마다, 그 실수가 다시는 반복되지 않도록 엔지니어링 하는 것
공식으로 치면 에이전트 = 모델 + 하네스 로 표현한다

AI를 야생말로 생각해보면, 하네스는 마구라고 할 수 있다!
마구를 채운다고 말이 느려지는 게 아니라 그 힘이 올바른 방향으로 모여 더 빠르고 정확해지도록 한다

AI도 마찬가지로 AI를 올바른 방향으로 이끌어 잘 쓰기 위해서는 하네스가 필요!
사실 우리가 쓰는 대화 채팅창 자체도 일종의 하네스라고 볼 수 있다
→ 이전 메시지를 기억하고 그것을 배경으로 대화를 이어가기 때문

넓게 보면 모델을 둘러싸고 에이전트의 행동을 조정하는 것들이 모두 하네스가 될 수 있다

CLAUDE.md
AGENTS.md
MCP
Skills
Hooks
Test
권한
메모리 ...

엔지니어링 발전 흐름

구분	주요 방식	한계
프롬프트 엔지니어링	구체적인 지시, 조건 및 형식 지정, 예시 제공	프로젝트 상황을 모르면 좋은 프롬프트만으로 정확한 작업이 어려움
컨텍스트 엔지니어링	프로젝트 구조, 코드 스타일, 관련 문서 같은 배경 상황을 알려줌	필요한 정보를 제공해도 실제 행동과 결과를 강제하거나 검증하는 데 한계가 있음
하네스 엔지니어링	가이드, 도구, 테스트, 권한, 메모리, 실행 루프 등을 함께 설계	실행 환경 전체를 설계하고 지속적으로 관리해야 함

프롬프트 엔지니어링
AI한테 명령을 잘하는, 즉 말을 잘 거는 기술
단, 아무리 말을 잘 걸어도 프로젝트 상황을 잘 모르면 엉뚱한 코드 나올 수 있다
컨텍스트 엔지니어링
프로젝트 구조나 코드 스타일 같은 프로젝트 배경 정보를 AI에게 알려주는 것
아래와 같은 도구를 활용
- MCP: AI가 쓸 수 있는 도구 목록을 미리 정해주는 것
- Skills: 특정 작업을 할 때 참고할 가이드 문서
  단, 정보가 많아지면서 AI가 헷갈리는 상황 발생

이런 한계에서 나아가 정확하게 일할 수 있는 환경 자체를 설계해 보자 해서 나온 게 하네스 엔지니어링
프롬프트는 모델이 말하는 것을, 컨텍스트는 모델이 보는 것을, 하네스는 모델이 할 수 있는 것을 결정

하네스가 왜 필요한가

1. 컨텍스트 부패

컨텍스트 창은 AI가 한 번에 볼 수 있는 정보의 양
작업이 길어질수록 컨텍스트 창이 꽉 차며 AI는 앞 내용을 잊어버리기 시작한다

발생하는 문제
- 컨텍스트 소진: 절반만 구현하고 중단
- 조기 종료 선언: 어느 정도 구현되면 다 끝난 줄 알고 작업을 마침

2. 규칙과 울타리 부재

AI가 정보를 다 알고 있어도 이걸 가지고 엉뚱한 작업을 할 수 있다
이를테면 결제 기능을 만드는 일을 시켰는데 갑자기 DB 테이블을 삭제할 수도 있다
→ "이건 절대 하면 안 돼"라는 구조적 제약이 없어서 일어나는 일

이 두 가지 문제를 해결하는 방법
- CLAUDE.md
  클로드의 경우 새 세션마다 리셋되는 기억을 CLAUDE.md 가 잡아준다
  담당자가 바뀌어도 신규 입사자가 첫날 읽는 온보딩 문서처럼 이 프로젝트가 뭔지, 어떤 규칙으로 돌아가는지, 절대 하면 안 되는 건 뭔지 등을 적어둔다
- 훅(Hooks)
  클로드가 작업을 마치려는 순간 자동으로 실행되는 스크립트
  코드 저장 시 자동 실행되면서 에러가 있을 시 Claude한테 돌려보내 사람 개입 없이 스스로 수정하도록 만들 수 있다
  "잘 짜달라"고 부탁하는 것이 아니라, 못 짜면 통과되지 않는 구조를 만드는 것

하네스 핵심 철학

핵심은 구조
프롬프트로 부탁하는 게 아닌 하네스로 강제하는 것
규칙이 사람 판단이 아닌 시스템에 내장되어, 실수 자체가 불가능한 구조를 만드는 것이 중요

AGENTS.md: AI 업무 지침서로 해야되는 것과 하면 안 되는 것을 적어두기
CI 게이트: 저장할 때마다 자동 테스트 실행
도구 경계: AI가 접근할 수 있는 범위와 권한을 미리 설정
피드백 루프: AI가 직접 코딩 → 리뷰 → 규칙 보강 → 반복

하네스 핵심 구성 요소

컨텍스트 파일 (AGENTS.md, CLAUDE.md)
- AI가 작업 시작 전 가장 먼저 읽는 파일
- 다 설명하려고 하지 말고 보편적으로 적용되는 내용만 적어야 한다
- 세부 내용은 다른 파일에 나눠서 넣고 필요할 때만 가져다 쓰기
- 작업 중 실패한 경우를 추가하면서 점진적으로 개선해 나가면 된다
자동 강제 시스템
말로 전하는 게 아니라 규칙으로 강제하기
- 린터: 코드 맞춤법 검사기, 규칙 위반 시 자동 에러
- 프리커밋 훅: 저장 전 자동 검사
- 자동 교정 루프: 린터 오류가 나면 에이전트가 스스로 수정하며 사람 개입 불필요
- 성공은 조용히, 실패만 시끄럽게: 테스트가 통과한 결과는 보여주지 말고 실패했을 때만 보여주도록 하여 에이전트가 해야 할 일에 집중하게 한다
가비지 컬렉션
AI가 만들어놓은 안 좋은 코드를 주기적으로 자동 청소
→ 기존에 나쁜 코드가 있으면 AI는 기존 코드를 보고 따라 하기 때문에 나쁜 패턴이 계속 늘어나게 된다
- 주기적 청소 에이전트 점검 사항
  - 문서가 실제 코드와 달라진 건 없는지
  - 규칙을 위반한 코드가 생겼는지
  - 사용하지 않는 코드가 쌓였는지
실패가 새 규칙이 되고, 새 규칙이 하네스를 진화시키며, 하네스는 점점 정교해짐

하네스 적용

컨텍스트 파일 작성
CLAUDE.md파일은 온보딩 문서
Claude가 새 세션을 시작할 때 가장 먼저 읽는 파일

사용 시 주의할 점
- 중요한 걸 다 적으면 어떤 게 제일 중요한지 모름
- 오래된 규칙이 쌓이면 3개월 전에 쓴 규칙이 아직 유효한지 모름
- 토큰 낭비 → 파일이 커질수록 AI가 그것을 읽는 데 토큰을 다 써버림
원칙
- 60줄 이하로 유지 권장
- 보편적으로 항상 적용되는 내용만
- 절대 자동 생성하지 말기(CLAUDE.md를 AI에게 직접 만들어주라고 시키면 AI가 생성한 파일이 성능을 낮추고 비용만 20% 올렸다는 연구 결과 있음)
- 중요한 결정이 생겼을 때마다 기록해 두기(에이전트 관점에서 볼 수 없는 것은 존재하지 않는 것과 같다)

    # 기본 템플릿
    PROJECT: [이름]
    LANGUAGE: [주 언어]
    BUILD: [정확한 빌드 명령]
    TEST: [정확한 테스트 명령]
    LINT: [정확한 린트 명령]

    RULES:
    - /config는 묻지 않고 수정하지 않는다
    - 코드 변경 후에는 반드시 테스트를 돌린다
    - [케이스]에는 [패턴]을 쓴다

    ANTI-PATTERNS:
    - [실제로 있었던 실패, 날짜 포함]
    - [관찰된 또 다른 실패 유형]

    # 절대 하지 말아야 할 것들
    - 내 허락 없이 파일 삭제하지 말 것
    - 모르면 추측하지 말고 물어볼 것
    - 작업 중간에 임의로 다른 방향으로 바꾸지 말 것

실수를 하게 되면 추가하면서 점진적으로 개선해 가면 된다

도구 연결
대표적인 도구는 MCP
MCP를 연결하면 그 도구에 대한 설명도 자동으로 컨텍스트에 들어가며 쌓임
따라서, 도구 관리가 곧 컨텍스트 관리
```
최대한 많은 MCP를 연결하려고 하면 많이 연결할수록 Claude의 인스트럭션 예산을 잡아먹는다
인스트럭션 예산 = 지시 사항을 처리할 수 있는 용량
인스트럭션이 도구 설명으로 꽉 차버리면 정작 사용자의 명령을 처리할 공간이 없어짐
```
MCP는 지금 써야 하는 것, 꼭 필요한 것만 쓰는 것이 중요
- MCP 고를 때 기준 3가지
  - MCP 대신 CLI 사용하기
    클로드는 CLI를 어떻게 다뤄야 하는지 알기 때문에 MCP 서버를 연동하는 것보다 CLI를 직접 쓰게 하는 게 토큰 절약되고 좋음
  - 쓰는 기능만 감싼 경량 도구 만들기
  - 지금 안 쓰는 MCP는 꺼두기
세션 관리
긴 작업을 끊기지 않고 이어가는 방법
- 진행 파일 CLAUDE-PROGRESS.TXT - 인수인계 문서
  - 작업 마칠때마다 "오늘 뭘 했고, 어디까지 했고, 다음엔 뭘 해야 해"를 기록
  - 자동으로 인수인계 문서를 만들고 새 세션이 시작되면 가장 먼저 읽게 한다
    컨텍스트가 꽉 차서 세션이 끊겨도 해당 파일을 만들면 어디까지 했는지 즉시 파악하고 바로 이어서 작업할 수 있음
- 작업 목록 feature_list.json - 작업 목록 관리
  - 조기 종료를 막기 위해 만들어야 할 기능을 전부 나열하고
    완료는 passes: true, 미완료는 passes: false로 표시
  - 목록의 모든 항목이 완료될 때까지 Claude는 작업을 끝냈다고 선언할 수 없다 → 완료 기준이 명시적으로 존재
  - JSON을 쓰는 이유는 마크다운보다 에이전트가 내용을 멋대로 바꾸는 일이 적기 때문이다
```
-- 한 번에 하나의 기능만 하기! -- 
1. 기능 하나를 완료하고 Git 커밋 → 메시지는 자세하게 쓰기
2. 진행 파일을 업데이트
3. 다음 세션은 깔끔한 상태에서 시작
```
```
-- fork (맥락이 쌓인 세션을 그대로 복제) --
1. 맥락이 충분히 쌓인 메인 세션에서 포크(Fork)실행
2. 복제본에서 세부작업을 진행한다 → 컨텍스트가 오염돼도 메인은 안전
3. 작업 완료 후 복제본은 폐기 → 메인 세션은 그대로 보존
```
  구현 작업이 끝났을 때 이상적인 컨텍스트 상한선: 40%
  초과 시
  - 작업 단위가 너무 크거나
  - 중간에 불필요한 정보가 너무 많이 쌓이고 있거나