하네스 엔지니어링 — AI 에이전트를 안전하게 운용하기 위한 실전 가이드#

2026-04-04

이 글을 쓰게 된 이유#

필자는 여러 프로젝트에서 AI 에이전트(Cursor, Claude Code 등)를 적극적으로 활용하고 있습니다. 처음에는 에이전트가 코드를 작성해 주는 것만으로도 충분히 놀라웠지만, 실제로 프로젝트에 깊이 적용하다 보니 반복적으로 부딪히는 문제들이 있었습니다.

• 새 세션을 열 때마다 에이전트가 프로젝트 컨벤션을 잊어버립니다
• 어제 해결한 문제와 같은 실수를 오늘 또 반복합니다
• 에이전트가 생성한 코드의 품질이 세션마다 들쭉날쭉합니다
• 프로젝트가 여러 개가 되면 각각에 같은 설정을 반복해야 합니다

이 문제들의 본질은 에이전트의 지능이 부족한 것이 아니라, 에이전트를 둘러싼 환경이 제대로 갖춰지지 않은 것이었습니다. 2026년에 들어서면서 이 문제의식이 업계 전체로 확산되었고, “하네스 엔지니어링"이라는 이름으로 체계화되기 시작했습니다.

필자는 회사 프로젝트에서 하네스 엔지니어링을 처음 적용한 뒤, 그 효과를 체감하고 개인 프로젝트들에도 같은 구조를 적용하기로 했습니다. 이 과정에서 “어떤 프로젝트든 빠르게 하네스 구조로 만들 수 있는 레퍼런스 문서"가 필요하다고 느꼈고, 학습한 내용을 정리하여 이 글을 작성하게 되었습니다.

이 글은 하네스 엔지니어링의 개념을 설명하는 것에서 그치지 않고, 프로젝트 유형에 따라 무엇을 적용해야 하는지까지 다룹니다. 개인 블로그부터 멀티 에이전트 자동화 시스템까지, 프로젝트의 규모와 복잡도에 맞는 하네스를 설계하는 데 참고할 수 있도록 구성했습니다.

1. 하네스 엔지니어링이란?#

정의#

하네스 엔지니어링은 AI 에이전트를 안전하고 안정적으로 운용하기 위한 인프라 설계 분야입니다. “하네스(Harness)“는 말(馬)의 힘을 제어하는 마구에서 유래한 용어로, 강력하지만 예측 불가능한 AI 에이전트의 힘을 올바른 방향으로 이끄는 시스템을 의미합니다.

“모델은 코모디티(Commodity), 하네스는 해자(Moat)다.” — harness-engineering.ai

비유#

왜 지금 하네스 엔지니어링인가?#

• 2025년은 AI 에이전트가 코드를 작성할 수 있음을 증명한 해
• 2026년은 핵심은 에이전트 자체가 아니라 하네스라는 것을 깨달은 해

LangChain은 모델을 전혀 바꾸지 않고 하네스만 변경하여 Terminal Bench 2.0에서 52.8% → 66.5%로 성적을 향상시켰습니다. OpenAI Codex 팀은 수동으로 작성한 코드 단 한 줄 없이 100만 줄 이상의 프로덕션 애플리케이션을 구축했습니다.

관련 개념과의 비교#

2. 하네스 엔지니어링의 핵심 구성 요소#

2-1. 컨텍스트 엔지니어링 (Context Engineering)#

에이전트가 적시에 적절한 정보를 갖도록 보장하는 것입니다.

정적 컨텍스트:

• 저장소 로컬 문서 (구조 설계서, API 명세서, 스타일 가이드)
• 프로젝트별 규칙을 인코딩하는 CLAUDE.md 파일 (또는 AGENTS.md)
• 서로 링크로 연결된 설계 문서 (린터가 링크 유효성과 문서 최신 상태를 자동 검증)

동적 컨텍스트:

• 에이전트가 액세스할 수 있는 관찰 데이터 (로그, 메트릭, 트레이스)
• 에이전트 시작 시의 디렉토리 구조 매핑
• CI/CD 파이프라인 상태 및 테스트 결과

핵심 규칙: 에이전트의 관점에서, 컨텍스트 내에서 액세스할 수 없는 것은 존재하지 않는 것과 같습니다. Google Docs, Slack 스레드, 사람의 머릿속에 있는 지식은 시스템에 보이지 않습니다. 저장소가 단일 진실 공급원(Single Source of Truth)이어야 합니다. — OpenAI

2-2. 아키텍처 제약 조건 (Architectural Constraints)#

에이전트에게 “좋은 코드를 작성해"라고 말하는 대신, 좋은 코드가 어떤 모습인지 기계적으로 강제합니다.

종속성 레이어링:

Types → Config → Repo → Service → Runtime → UI

각 레이어는 자신의 왼쪽에 있는 레이어에서만 임포트할 수 있으며, 이는 구조적 테스트와 CI 검증을 통해 강제됩니다.

제약 조건 강제 도구:

• 결정론적 린터 — 위반 사항을 자동으로 표시하는 맞춤형 규칙
• LLM 기반 감사자 — 다른 에이전트의 코드를 검토하는 에이전트
• 구조적 테스트 — AI 생성 코드를 위한 아키텍처 테스트
• Pre-commit 훅 — 코드가 커밋되기 전 자동 체크

역설적으로, 솔루션 공간을 제한하면 에이전트의 생산성이 향상됩니다. 에이전트가 무엇이든 생성할 수 있을 때는 막다른 길을 탐색하느라 토큰을 낭비합니다. 하네스가 명확한 경계를 정의하면 에이전트는 올바른 솔루션에 더 빨리 도달합니다. — NxCode

2-3. 가드레일 (Guardrail)#

AI 에이전트의 입력과 출력 양쪽을 기술적으로 제어하여 설계된 목적 범위 밖의 동작을 사전에 차단합니다.

• 입력 단계: 프롬프트 인젝션이나 기밀 정보의 혼입을 감지 / 차단
• 출력 단계: 유해 콘텐츠나 할루시네이션을 자동으로 필터링

2-4. 검증 루프 (Verification Loops)#

에이전트의 작업을 각 단계마다 검증 후 진행을 허용하는 구조입니다. 하네스에서 ROI가 가장 높은 구성 요소입니다.

# 검증 루프 패턴 (의사 코드)
def run_agent_with_verification(task, tools, cost_ceiling):
    context = assemble_context(task)
    total_cost = 0

    while not task.is_complete():
        action = agent.plan(context, tools)
        result = execute_tool(action)

        verification = verify_output(result, action.expected_schema)
        if not verification.passed:
            if verification.retry_recommended:
                result = retry_with_backoff(action, max_retries=3)
            else:
                return TaskResult(status="failed", reason=verification.reason)

        total_cost += result.tokens_used
        if total_cost > cost_ceiling:
            return TaskResult(status="budget_exceeded", partial=context)

        context = update_context(context, result)

    return TaskResult(status="complete", output=context.final_output)

“ROI가 가장 높다"는 것은 들인 노력 대비 효과가 가장 크다는 뜻입니다. 하네스의 여러 구성 요소 중에서 검증 루프가 가장 적은 공수로 가장 큰 품질 향상을 가져옵니다.

• 구현 비용: 단계당 50~150ms의 추가 지연, 코드 몇십 줄 수준
• 효과: 작업 완료율 83% → 96% (모델이나 프롬프트 변경 없이)

하네스를 처음 구축할 때 “뭐부터 만들지?” 고민된다면 검증 루프부터 만드는 게 가성비가 가장 좋습니다.

2-5. 비용 봉투 관리 (Cost Envelope Management)#

작업별 예산 상한선을 설정하고, 하네스가 에이전트의 의도와 무관하게 강제하는 구조입니다.

• 비용 봉투는 단순한 재정 통제가 아니라 신뢰성 신호입니다
• 예산 상한에 도달한 작업은 비정상적으로 작동하고 있음을 의미합니다 (잘못된 업스트림 응답, 컨텍스트 드리프트, 도구 통합 오류 등)

2-6. 엔트로피 관리 (Entropy Management)#

시간이 지남에 따라 AI가 생성한 코드베이스에 쌓이는 엔트로피를 정기적으로 정리합니다.

• 문서 일관성 에이전트 — 문서가 현재 코드와 일치하는지 확인
• 제약 조건 위반 스캐너 — 이전 체크를 통과한 코드를 재탐색
• 패턴 강제 에이전트 — 확립된 패턴에서 벗어난 부분을 식별 / 수정
• 종속성 감사자 — 순환 종속성이나 불필요한 종속성을 추적 / 해결

2-7. 에이전트 메모리 (Agent Memory)#

에이전트가 세션 간에 학습한 지식, 발견한 패턴, 진행 중인 의사결정을 저장소 내에 지속적으로 축적하는 구조입니다. 에이전트는 기본적으로 무상태(stateless)이므로, 세션이 끝나면 모든 컨텍스트가 사라집니다. 하네스가 이 “기억 상실"을 보완합니다.

컨텍스트의 3가지 시간축:

정적 컨텍스트는 프로젝트 시작 시 작성하는 문서이고, 동적 컨텍스트는 실행 시점에 자동으로 생성됩니다. 축적 컨텍스트는 그 사이에 위치하며, 에이전트의 작업이 누적됨에 따라 점진적으로 성장하는 지식 레이어입니다.

축적 컨텍스트의 구현 패턴:

<프로젝트 루트>/
├── docs/
│   └── decisions/                    # 설계 결정 기록 (ADR)
│       ├── 001-static-site-generator-choice.md
│       └── 002-deployment-strategy.md
├── .memory/                          # 에이전트 메모리
│   ├── learnings.md                  # 작업 중 발견한 패턴, 실패 원인, 노하우
│   ├── current-focus.md              # 현재 진행 중인 관심사, 우선순위
│   └── session-notes/                # 세션별 핵심 요약 (선택적)
│       └── 2026-04-04.md

도구별 네이티브 메모리 지원:

Claude Code는 세션 중 발견한 패턴을 자동으로 저장하는 Auto Memory 기능이 있지만, Cursor는 .cursor/rules/와 Notepads를 통해 수동으로 지식을 관리해야 합니다. 도구에 의존하지 않는 저장소 기반 메모리(위 .memory/ 패턴)를 사용하면 어떤 도구로든 접근할 수 있습니다.

핵심 원칙:

• 에이전트가 “같은 실수를 반복하지 않도록” 실패 원인과 해결책을 기록합니다
• “이번 세션에서 알게 된 것"을 세션 종료 전에 저장소에 커밋하는 습관을 만듭니다
• 축적 컨텍스트도 엔트로피 관리 대상입니다 — 오래되거나 무효화된 메모는 정기적으로 정리합니다

2-8. 관측 가능성 및 평가 (Observability & Evaluation)#

• 관측 가능성: 에이전트가 무엇을 했는지, 왜 했는지, 각 단계에서 무엇이 발생했는지를 구조적으로 추적합니다
• 평가: 정의된 기준에 따라 에이전트 성능을 지속적으로 측정하는 자동화 파이프라인입니다

3. 하네스 엔지니어링 적용 수준#

하네스 엔지니어링은 프로젝트 규모와 복잡도에 따라 적용 깊이가 달라집니다.

레벨 1: 기본 하네스 (개인 개발자)#

• 프로젝트 컨벤션이 포함된 CLAUDE.md 파일 (Cursor는 .cursor/rules/에서 참조)
• 린팅 및 포맷팅을 위한 Pre-commit 훅
• 에이전트가 자가 검증을 위해 실행할 수 있는 테스트 스위트
• 일관된 명명 규칙을 가진 명확한 디렉토리 구조
• 에이전트 메모리 (.memory/) 를 통한 세션 간 지식 축적

개인 블로그, 문서 사이트, 개인 도구, 사이드 프로젝트 등 단일 에이전트를 사용자가 직접 지시하여 사용하는 프로젝트에 적합합니다.

레벨 2: 팀 하네스 (소규모 팀)#

레벨 1에 아래 항목을 추가합니다:

• CI에 의해 강제되는 아키텍처 제약 조건
• 공통 작업을 위한 공유 프롬프트 템플릿
• 린터로 검증되는 ‘코드로서의 문서(Documentation-as-code)’
• 에이전트 생성 PR 전용 코드 리뷰 체크리스트
• 에이전트별 역할 경계 및 변경폭 제한

복수의 개발자가 동일 저장소에서 에이전트를 사용하는 환경에 적합합니다. 에이전트 간 충돌 방지와 코드 품질 편차 최소화가 핵심입니다.

레벨 3: 프로덕션 하네스 (엔지니어링 조직)#

레벨 2에 아래 항목을 추가합니다:

• 맞춤형 미들웨어 레이어 (루프 감지, 추론 최적화)
• 관측성 통합 (에이전트가 로그와 메트릭을 읽음)
• 스케줄에 따라 실행되는 엔트로피 관리 에이전트
• 하네스 버전 관리 및 A/B 테스트
• 에이전트 성능 모니터링 대시보드
• 에이전트 교착 상태 시 에스컬레이션 정책

에이전트가 자율적으로 파이프라인을 실행하고, 외부 API와 대규모로 연동하며, 에이전트의 판단 오류가 재정적 / 운영적 손실로 직결되는 시스템에 적합합니다.

4. 프로젝트에 하네스 엔지니어링 적용하기#

4-1. 서비스 특성 분석#

하네스를 설계하기 전에 대상 프로젝트의 핵심 특성을 먼저 파악해야 합니다. 다음 질문들을 통해 프로젝트를 분석합니다:

위 질문에 대한 답변을 기반으로 프로젝트를 아래 유형으로 분류하면, 어떤 Phase까지 적용해야 하는지 판단할 수 있습니다:

4-2. 위험 요소 식별#

프로젝트 특성에 따라 하네스 없이 운용할 경우 발생할 수 있는 위험 요소를 식별합니다:

유형 A (개인 프로젝트) 에서는 주로 2, 7, 8번 위험이 해당되며, Phase 12의 하네스 (규칙 파일, Pre-commit 훅, 에이전트 메모리) 로 충분히 대응할 수 있습니다. 유형 CD로 갈수록 1, 3~6번 위험이 중요해지며, 이를 위해 Phase 3 이상의 하네스가 필요합니다.

4-3. 하네스 엔지니어링 적용 설계#

A. 컨텍스트 엔지니어링 적용#

프로젝트 저장소를 에이전트의 단일 진실 공급원(Single Source of Truth)으로 구성합니다. 권장 디렉토리 구조:

<프로젝트 루트>/
├── CLAUDE.md                          # 에이전트 행동 규칙의 진입점
├── ARCHITECTURE.md                    # 시스템 아키텍처 최상위 맵
├── .cursor/
│   └── rules/
│       └── general.mdc                # Cursor가 CLAUDE.md를 참조하도록 연결
├── docs/
│   ├── design-docs/                   # 주요 기능의 설계 문서
│   ├── api-specs/                     # API 엔드포인트 명세
│   ├── references/                    # SDK/프레임워크 레퍼런스
│   └── quality/                       # 품질 기준

핵심 원칙:

• CLAUDE.md는 백과사전이 아닌 목차로 유지합니다 (약 100줄 이내)
• 모든 설계 결정은 저장소 내 문서로 기록합니다 (Slack / Google Docs 금지)
• 에이전트가 검색할 수 없는 정보는 존재하지 않는 것으로 간주합니다

B. 에이전트 행동 제약 조건 적용#

적용 대상: 프로젝트 유형 B 이상 (팀 / 웹 앱). 단일 에이전트 + 개인 프로젝트에서는 글로브 기반 규칙 파일과 Pre-commit 훅만으로 충분합니다.

프로젝트 특성에 맞게 에이전트의 행동 경계를 명확하게 정의합니다.

1) 에이전트별 역할 경계 (Role Boundary)

각 에이전트가 수행할 수 있는 작업과 금지되는 작업을 명시적으로 정의합니다:

<에이전트 이름> (<역할>)
  - 허용: <이 에이전트가 수행할 수 있는 작업 목록>
  - 금지: <이 에이전트가 절대 수행해서는 안 되는 작업 목록>

역할 경계를 설계할 때의 핵심 원칙:

• 최소 권한 원칙: 각 에이전트는 자신의 역할 수행에 필요한 최소한의 권한만 가집니다
• 분리 원칙: 데이터 조회 / 분석 에이전트와 실행 / 변경 에이전트를 분리합니다
• 승인 필수: 고위험 작업(재정적 영향, 데이터 변경, 외부 시스템 호출)은 반드시 승인 단계를 거칩니다

2) 입출력 가드레일

• 입력: 외부 데이터 소스의 응답 검증, 컨텍스트 격리 확인
• 출력: 변경폭 제한, 할루시네이션 필터링
• 파이프라인: 단계 간 데이터 스키마 검증, 식별자 일관성 체크

3) 작업 비용 봉투

작업 유형별 비용 상한 (프로젝트에 맞게 정의):
  - 단순 조회/분석: 기본값 × 1
  - 복합 분석/진단: 기본값 × 2
  - 전체 파이프라인 실행: 기본값 × 10
  - 리포트 생성: 기본값 × 5
  - 외부 API 호출 수반 작업: 기본값 × 3

  → 상한 초과 시: 작업 중단 + 알림 + 에스컬레이션

C. 검증 루프 적용#

적용 수준: 모든 프로젝트에서 적용 가능하지만 구현 깊이가 다릅니다.

• 유형 A (개인): Pre-commit 훅과 빌드 검증이 자체 검증 역할을 합니다.
• 유형 B (팀): CI/CD 파이프라인에 자동 테스트, 린트, PR 리뷰를 통합합니다.
• 유형 C~D (자동화 / 엔터프라이즈): 에이전트 자체 검증 + Human-in-the-Loop의 이중 / 삼중 구조가 필요합니다.

검증 루프는 이중 구조로 설계하는 것을 권장합니다:

1) 에이전트 자체 검증 (Self-Verification)

파이프라인 단계 실행
  → 에이전트가 결과 생성
  → 결과 자체 검증 (데이터 정합성, 스키마 충족 여부)
  → 미충족 시 자동 재시도 (최대 3회)
  → 충족 시 다음 단계로 전달

2) 인간 검증 (Human-in-the-Loop)

• 고위험 액션은 운영 도구를 통해 승인 요청
• 운영자가 승인 / 반려
• 반려 시 피드백이 에이전트에게 전달되어 대안 제시

3) 산출물 검증 루프

에이전트가 생성하는 산출물에 대해서도 검증 루프를 적용합니다:

• 에이전트가 초안 생성 → 검증(자동 또는 인간) → 반려 시 자동 재작성

D. 멀티 에이전트 하네스 미들웨어#

적용 대상: 프로젝트 유형 C 이상 (멀티 에이전트 / 자동화). 단일 에이전트를 사용자가 수동으로 지시하는 프로젝트에서는 불필요합니다.

멀티 에이전트 시스템의 경우, 파이프라인에 미들웨어를 적용합니다:

파이프라인 실행 요청
  → ContextIsolationMiddleware   (컨텍스트 격리, 데이터 혼선 방지)
  → CostEnvelopeMiddleware       (비용 봉투 확인, 초과 시 차단)
  → LoopDetectionMiddleware      (동일 작업 반복 처리 방지)
  → InputValidationMiddleware    (입력 데이터 정합성 검증)
  → [에이전트 실행]
  → OutputValidationMiddleware   (결과 스키마 검증, 변경폭 제한)
  → ApprovalGateMiddleware       (위험도 판정, 고위험 시 승인 요청)
  → ExecutionAuditMiddleware     (실행 이력 기록)

E. 관측 가능성 통합#

적용 대상: 프로젝트 유형 C 이상. 수동 사용 위주의 프로젝트에서는 에이전트 메모리와 Git 이력만으로 충분합니다.

F. 엔트로피 관리 — 에이전트 품질 유지#

적용 범위: 모든 프로젝트 유형에서 적용 가능하지만, 범위가 다릅니다.

• 유형 A~B: .memory/learnings.md의 주기적 정리, 링크 검증 정도로 충분합니다.
• 유형 C~D: 전용 에이전트가 정기적으로 품질 감사를 수행합니다.

[정기 실행 태스크 — 프로젝트에 맞게 선택/구성]
  - 프롬프트 드리프트 검출기: 시스템 프롬프트와 실제 출력 간 일관성 감시
  - 데이터 정합성 검사기: 참조 데이터/설정이 여전히 유효한지 확인
  - 산출물 품질 감사: 자동 생성 결과가 실제 데이터 기반인지 검증
  - 도구 함수 일관성 검사: 도구 정의가 외부 서비스 스키마와 동기화 상태인지 확인

4-4. 하네스 엔지니어링 적용 로드맵#

모든 Phase를 순차적으로 적용할 필요는 없습니다. 프로젝트 유형 분류를 기반으로, 필요한 Phase만 선택하여 적용합니다.

프로젝트 유형별 적용 예시#

유형 A — 개인 블로그 / 문서 사이트 / 개인 도구

Phase 1: CLAUDE.md (또는 .cursor/rules/), ARCHITECTURE.md, Pre-commit 훅
Phase 2: .memory/learnings.md, current-focus.md, docs/decisions/
         → 이 두 단계만으로 에이전트가 프로젝트를 일관되게 이해하고,
           세션 간 지식을 축적하는 환경이 완성됩니다.

유형 B — 팀 웹 애플리케이션 / SaaS 백엔드

Phase 1~2: (유형 A와 동일)
Phase 3: CI에서 강제하는 아키텍처 린트, PR 리뷰 체크리스트,
         에이전트 생성 코드의 변경폭 제한
         → 팀원 간 코드 품질 편차를 줄이고,
           에이전트의 과도한 변경을 방지합니다.

유형 C — 멀티 에이전트 자동화 시스템

Phase 1~3: (유형 B까지 적용)
Phase 4: 에이전트 간 데이터 격리 미들웨어, 비용 봉투 관리,
         doom loop 탐지 및 자동 중단
Phase 5: 스케줄 기반 태스크의 중복 실행 방지 (멱등성 키),
         외부 API 쿼터 관리, 실패 시 재시도 정책
         → "통제된 자율성"을 확보합니다.

유형 D — 프로덕션 엔터프라이즈 시스템

Phase 1~5: (유형 C까지 적용)
Phase 6: 실시간 대시보드, 자동화된 엔트로피 관리 에이전트,
         에이전트 산출물 A/B 테스트
Phase 7: 반복 패턴에서 자동 승인 임계치 학습,
         에이전트 성능 벤치마크 스위트, 하네스 설정의 버전 관리 및 롤백
         → 지속 가능한 운영 체계를 구축합니다.

5. 에이전트 지침 파일 전략#

“저장소 루트에 에이전트 행동 지침을 마크다운으로 둔다"는 패턴은 사실상 표준(de facto standard)이 되었습니다. 다만 도구마다 인식하는 파일명이 다릅니다:

하나의 파일로 모든 도구를 커버하는 것은 현재 불가능합니다. (2026년 4월 기준)

권장 전략: 메인 지침 파일 + 도구별 연결

사용하는 AI 도구에 따라 메인 지침 파일을 선택하고, 나머지 도구에서는 해당 파일을 참조하도록 연결합니다:

패턴 A: Claude Code 메인 + Cursor 서브

CLAUDE.md                  ← 실제 규칙 작성
.cursor/rules/general.mdc  ← "See CLAUDE.md"

패턴 B: Cursor 메인 + Claude Code 서브

.cursor/rules/<프로젝트>.mdc  ← 실제 규칙 작성 (alwaysApply: true)
CLAUDE.md                     ← "See .cursor/rules/"

프로젝트에서 주로 사용하는 AI 도구를 메인으로 선택합니다. 메인 도구의 지침 파일에 규칙을 작성하고, 서브 도구의 지침 파일은 메인을 참조하는 경량 파일로 유지합니다. 이렇게 하면 규칙은 한 곳에서만 관리하면 됩니다.

6. 에이전트 메모리와 컨텍스트 드리프트#

에이전트 메모리와 컨텍스트 드리프트는 동전의 양면입니다.

컨텍스트 드리프트는 대화가 길어지면서 에이전트가 원래 목표에서 벗어나는 현상입니다. 하네스 관점에서의 대응 전략:

1. 세션 분리: 하나의 긴 세션보다 목적별 짧은 세션 여러 개를 사용합니다. Claude Code의 /compact 명령이나 Cursor의 새 채팅 시작이 이에 해당합니다.
2. 메모리 파일로 연결: 세션 종료 시 핵심 결론을 메모리 파일에 기록하고, 다음 세션에서 해당 파일을 참조합니다.
3. 규칙 파일의 우선순위 활용: .cursor/rules/(alwaysApply)나 CLAUDE.md에 기록된 규칙은 세션 길이와 무관하게 매 턴마다 주입되므로, 핵심 제약 조건은 반드시 규칙 파일에 기록합니다.

[긴 세션의 컨텍스트 드리프트]
  세션 시작 → (규칙 + 목표가 명확) → 작업 진행 → ... → (컨텍스트 창 포화)
    → 초기 규칙의 영향력 ↓ → 드리프트 발생

[메모리 기반 짧은 세션 전략]
  세션 1: 작업 → 결론을 메모리에 기록 → 세션 종료
  세션 2: 메모리 로드 → (규칙 + 이전 결론이 명확) → 작업 계속

개발자가 직접 관리하는 프로젝트(블로그, 개인 프로젝트 등)에서는 무거운 자동 메모리 시스템보다 저장소 내 마크다운 파일(docs/decisions/, .memory/)을 활용하는 것이 실용적입니다. 에이전트에게 “작업 중 발견한 내용을 .memory/learnings.md에 추가해"라고 지시하는 것만으로도 세션 간 지식 연속성을 확보할 수 있습니다.

7. Pre-commit 훅과 에이전트의 관계#

Pre-commit 훅은 .git/hooks/pre-commit에 등록된 스크립트가 git commit 실행 시 자동으로 돌아가며, 규칙 위반 시 커밋 자체를 차단하는 구조입니다.

하네스 엔지니어링의 핵심 원칙: “기계적으로 강제할 수 있는 것은 기계적으로 강제한다.”

에이전트와의 간접 소통: Pre-commit 훅에서 에이전트를 직접 호출할 수는 없습니다. 하지만 훅이 출력하는 에러 메시지를 에이전트가 읽고 반응하는 구조는 이미 작동합니다. OpenAI Codex 팀은 이 점을 활용하여 린터 에러 메시지에 수정 지침을 포함시켜, 에이전트가 에러를 보고 스스로 수정한 뒤 재커밋하도록 합니다.

# 에이전트 친화적인 에러 메시지 예시
Error: line 42 - unused variable 'tempData'.
Fix: Remove the variable or use it in the fetchResult() call below.
Refer to docs/conventions/no-unused-vars.md for examples.

8. 핵심 요약#

1. 하네스 엔지니어링은 AI 에이전트를 안정적으로 만드는 시스템(제약, 피드백 루프, 문서화, 수명 주기 관리)을 설계하는 분야입니다.
2. 프로젝트 특성에 따라 적용 범위가 다릅니다. 개인 프로젝트는 Phase 1~2만으로 충분하며, 멀티 에이전트 자동화 시스템은 Phase 5까지, 엔터프라이즈 시스템은 Phase 7까지 필요할 수 있습니다.
3. 처음부터 완벽한 하네스를 만들 필요 없이, Phase별로 점진적으로 구축하되 기본 컨텍스트 문서부터 시작하는 것이 효과적입니다.
4. 에이전트 메모리를 하네스의 구성 요소로 설계합니다. 에이전트는 기본적으로 무상태이므로, 세션 간 학습과 지식 축적을 저장소 기반 메모리로 보완해야 합니다.
5. 유연한 하네스를 구축해야 합니다. 모델이 개선됨에 따라 과도한 설계는 짐이 될 수 있으므로, 쉽게 제거할 수 있는(rippable) 구조를 유지합니다.
6. 하네스를 처음 구축할 때 “뭐부터 만들지?” 고민된다면 검증 루프부터 만드는 게 가성비가 가장 좋습니다.

실제 적용 사례: 이 블로그에 하네스를 적용한 경험#

필자는 이 글을 작성하면서 동시에, 이 블로그 프로젝트(Ted Factory)에 직접 하네스를 적용했습니다. 유형 A (개인 / 정적) 프로젝트이므로 Phase 1~2만 적용했으며, 실제로 구성한 내용은 다음과 같습니다:

Phase 1 — 에이전트 지침 + 검증 자동화

• .cursor/rules/ted-blog-common-rules.mdc: Cursor 메인 규칙 (문체, 프론트매터, 콘텐츠 구조)
• CLAUDE.md: Claude Code용 경량 참조 파일
• ARCHITECTURE.md: 프로젝트 구조 문서
• scripts/pre-commit: Hugo 빌드 검증, 프론트매터 필수 필드 검증, ko / en 대칭 검증

Phase 2 — 에이전트 메모리

• .memory/learnings.md: 작업 중 발견한 패턴과 노하우
• .memory/current-focus.md: 현재 관심사와 우선순위
• docs/decisions/: 설계 결정 기록 (ADR)

이 두 Phase를 적용한 뒤 체감한 변화:

• 새 세션을 열어도 에이전트가 프로젝트의 컨벤션(문체, 프론트매터 구조, 배포 방식)을 즉시 이해합니다
• Pre-commit 훅이 프론트매터 누락이나 빌드 실패를 커밋 전에 잡아주므로, “배포 후에 발견하는 실수"가 사라졌습니다
• .memory/learnings.md에 축적된 노하우 덕분에 에이전트가 같은 실수를 반복하지 않습니다

개인 프로젝트에 Phase 1~2를 적용하는 데는 하루 정도면 충분합니다. 그에 비해 얻는 안정성과 일관성의 향상은 상당합니다. AI 에이전트를 적극적으로 활용하고 있다면, 가장 먼저 해볼 만한 작업이라고 생각합니다.

지금 바로 적용해 보기#

이 글의 내용을 직접 읽고 하나씩 따라 하셔도 되지만, 더 간단한 방법이 있습니다. 이 글의 URL을 AI 에이전트에게 제시하고, 원하는 프로젝트에 하네스를 적용해 달라고 요청하는 것입니다.

Cursor나 Claude Code 같은 에이전트는 URL을 읽고 내용을 이해한 뒤, 그에 맞게 프로젝트에 하네스를 구성할 수 있습니다. 필자가 이 블로그에 하네스를 적용할 때도, 하네스 엔지니어링 설계 문서를 에이전트에게 제시하고 적용을 요청하는 방식으로 진행했습니다.

Cursor에서:

하네스를 적용하려는 프로젝트를 Cursor로 열고, 채팅에 다음과 같이 입력합니다:

https://blog.iamted.kim/ko/notes/essays/harness-engineering-guide/
위 문서를 참조하여 본 프로젝트에 하네스 엔지니어링을 적용해줘.

Claude Code에서:

하네스를 적용하려는 프로젝트의 루트 디렉토리에서 Claude Code를 실행하고, 다음과 같이 입력합니다:

https://blog.iamted.kim/ko/notes/essays/harness-engineering-guide/
위 문서를 참조하여 본 프로젝트에 하네스 엔지니어링을 적용해줘.

에이전트는 이 글의 내용을 읽고, 프로젝트의 특성을 분석한 뒤, 해당 유형에 맞는 Phase를 적용해 줄 것입니다. 물론 에이전트가 제안하는 내용을 그대로 수용할 필요는 없습니다. 프로젝트의 실제 상황에 맞게 조정하면 됩니다.

참고 자료#

• OpenAI — 하네스 엔지니어링: 에이전트 우선 세계에서 Codex 활용하기
• NxCode — 하네스 엔지니어링 완벽 가이드 (2026)
• 채널톡 — 하네스 엔지니어링이란?
• harness-engineering.ai — What Is Harness Engineering?
• Anthropic — Effective Harnesses for Long-running Agents
• Philipp Schmid — The Importance of Agent Harness in 2026
• harness-engineering.ai — Open Source Persistent Memory for AI Agents
• Augment Code — Context Engineering: Enhancing Agentic Swarm Coding