하네스 엔지니어링(Harness Engineering): AI 에이전트 실행 환경 설계와 CAR 모델

TL;DR#

AI 개발의 초점이 "어떻게 질문할 것인가(Prompt Engineering)"에서 "어떤 환경에서 실행하게 할 것인가(Harness Engineering)"로 이동하고 있습니다.
하네스 엔지니어링은 AI 모델이 소프트웨어 생태계 안에서 안전하고 논리적으로 행동하도록 통제 장치와 실행 프레임워크를 설계하는 일입니다.
핵심 아키텍처로 CAR(Control, Agency, Runtime) 구조를 소개하고, Claude Code·Codex·Gemini CLI에 적용되는 방식을 살펴봅니다.
마지막으로 프로젝트 루트에 둘 수 있는 AGENTS.md·CLAUDE.md 하네스 템플릿을 제시합니다.

문제의 배경: 프롬프트를 넘어 '하네스'로#

그동안의 AI 개발이 "어떻게 질문할 것인가(Prompt Engineering)"에 집중했다면, 이제 업계의 관심은 "어떤 환경에서 실행하게 할 것인가(Harness Engineering)"로 옮겨가고 있습니다.

AI 모델 자체의 지능은 이미 상향 평준화되었습니다. 그러나 이 모델을 실제 서비스 개발에 투입하면 할루시네이션, 의도치 않은 파일 수정, 보안 리스크 같은 문제가 발생합니다. 이런 문제는 프롬프트만으로는 해결하기 어렵습니다. 이를 해결하기 위해 등장한 개념이 하네스 엔지니어링입니다.

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

하네스(Harness)는 마차나 말의 '마구'를 뜻합니다. 아무리 힘센 말(LLM)이라도 마구가 없으면 제어할 수 없듯, 하네스 엔지니어링은 AI 모델이 소프트웨어 생태계 안에서 안전하고 논리적으로 행동하도록 설계된 '통제 장치와 실행 프레임워크'를 구축하는 일입니다.

핵심 아키텍처: CAR 모델#

CAR(Control, Agency, Runtime) 구조는 하네스를 세 축으로 나눕니다.

Control (통제): AI의 페르소나와 규칙을 정의하는 불변의 가이드라인입니다. 예를 들어 CLAUDE.md, AGENTS.md가 여기에 해당합니다.
Agency (권한): AI에게 부여된 도구와 권한의 범위입니다. 예를 들어 git 접근, npm 실행 권한이 있습니다.
Runtime (실행): AI가 코드를 작성하고 테스트하며 스스로 수정하는 '자가 치유(Self-healing)' 환경입니다.

실무 적용 사례: Claude Code, Codex, Gemini CLI#

개발자들이 자주 사용하는 AI 도구에 하네스 엔지니어링이 어떻게 적용되는지 살펴보겠습니다.

Claude Code: 규약 기반의 하네스 (Control)#

Anthropic의 Claude Code는 프로젝트 루트의 CLAUDE.md 파일을 하네스로 활용합니다.

적용 예시: 이 파일에 프로젝트의 코딩 컨벤션, 자주 쓰는 테스트 명령어, 절대 수정하면 안 되는 핵심 파일을 명시합니다. Claude는 실행할 때마다 이 하네스를 읽어 자신의 행동을 스스로 제약합니다.
효과: 시니어 개발자가 옆에서 가이드하는 것과 같은 일관성을 유지합니다.

Codex(GitHub Copilot): 컨텍스트 하네스 (Agency)#

Codex 기반의 Copilot은 단순 코드 완성을 넘어, 열려 있는 탭, 최근 수정한 파일, 로컬 DB 스키마 등을 '하네스' 데이터로 엮어냅니다.

적용 예시: @workspace 명령어로 전체 코드베이스의 인덱스를 하네스로 제공합니다. AI가 특정 함수를 수정할 때 연관된 의존성을 자동으로 분석해 사이드 이펙트를 방지합니다.

Gemini CLI: 워크플로우 하네스 (Runtime)#

Gemini CLI는 복잡한 터미널 명령어를 실행하는 하네스 역할을 합니다.

적용 예시: "로그인 기능을 구현해줘"라고 요청하면, Gemini CLI는 코드만 작성하는 데서 그치지 않습니다. pnpm test를 실행해 실패 지점을 확인하고, 그 에러 로그를 다시 입력값으로 넣어 코드를 수정하는 'Closed-loop Runtime'을 형성합니다.

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

AI가 코드를 짜는 속도는 빨라졌지만, 이를 검증하고 배포하는 과정이 병목이 되었습니다(AI Velocity Paradox). 하네스 엔지니어링은 이 '검증과 배포'를 AI가 스스로 수행하도록 자동화합니다.

또한 비용 측면에서도 의미가 있습니다. 무작정 긴 프롬프트를 던지는 대신, 잘 설계된 하네스 환경을 제공하는 편이 토큰 소모를 줄이는 데 유리합니다.

[실무 템플릿] AGENTS.md & CLAUDE.md 설계#

프로젝트 루트에 둘 수 있는 하네스 템플릿 예시입니다. 이 파일 하나만 비치해도 AI 에이전트가 일관된 규칙 아래 동작하도록 유도할 수 있습니다.

# 프로젝트: [이름] - [핵심 목적 한 줄 요약]

## 🛠 Tech Stack
- <strong>Core:</strong> Next.js 16 (App Router), TypeScript 5.x, Tailwind 4
- <strong>State/Data:</strong> TanStack Query, Zustand
- <strong>Database:</strong> Supabase (PostgreSQL) + Prisma
- <strong>Testing:</strong> Vitest + Playwright

## 🏗 Architecture & Patterns
- <strong>Layered Design:</strong> `src/features/*` 내부에 도메인 로직을 응집합니다.
- <strong>Server-First:</strong> 클라이언트 사이드 `useEffect` 대신 Server Components와 Server Actions를 우선합니다.
- <strong>Single Source of Truth:</strong> 모든 외부 연동 로직은 `src/lib/integrations`에 위치시킵니다.

## 📜 Coding Rules (AI 행동 강령)
- <strong>Correctness > Cleverness:</strong> 복잡한 추상화보다 가독성 높고 '지루한' 코드를 선호합니다.
- <strong>Smallest Change:</strong> 수정 범위를 최소화하세요. 요청받지 않은 인접 코드를 리팩토링하지 않습니다.
- <strong>Typing:</strong> `any` 사용 금지. 모든 외부 데이터는 Zod로 런타임 검증을 수행합니다.
- <strong>Naming:</strong> 파일명은 `kebab-case`, React 컴포넌트는 `PascalCase`를 사용합니다.

## 🧪 Verification & Quality
- <strong>Definition of Done:</strong> 모든 코드는 `pnpm lint`, `pnpm typecheck`, 테스트 통과가 필수입니다.
- <strong>Bug Fix Protocol:</strong> 버그 수정 시 반드시 재현 테스트 케이스를 먼저 작성하세요.
- <strong>Manual Repro:</strong> 수정 후에는 직접 실행하여 결과를 확인하고 로그를 보고하세요.

## ⌨️ Essential Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`
- Lint: `pnpm lint --fix`

## 🚫 Anti-Patterns (절대 금지)
- ❌ 기능 폴더 내의 `barrel files` (index.ts) 사용 금지 (순환 참조 원인).
- ❌ 불필요한 에러 핸들링 금지 (글로벌 에러 바운더리에 위임).
- ❌ `localStorage` 직접 접근 금지 (커스텀 훅 `useStorage` 사용).

마치며#

시니어 개발자의 역할은 코드를 직접 타이핑하는 것에서, AI 에이전트가 제대로 작동할 수 있는 '최고 품질의 하네스'를 설계하는 것으로 변하고 있습니다. 여러분의 프로젝트에는 어떤 하네스가 준비되어 있나요?

참고 자료#

Mitchell Hashimoto, "The Era of Harness Engineering" (Feb 2026)
Anthropic Research: Scalable Verification Loops for Coding Agents (March 2026)
LangChain: DeepAgents and Virtual Harness Framework (March 2026)

TL;DR#

AI 개발의 초점이 "어떻게 질문할 것인가(Prompt Engineering)"에서 "어떤 환경에서 실행하게 할 것인가(Harness Engineering)"로 이동하고 있습니다.
하네스 엔지니어링은 AI 모델이 소프트웨어 생태계 안에서 안전하고 논리적으로 행동하도록 통제 장치와 실행 프레임워크를 설계하는 일입니다.
핵심 아키텍처로 CAR(Control, Agency, Runtime) 구조를 소개하고, Claude Code·Codex·Gemini CLI에 적용되는 방식을 살펴봅니다.
마지막으로 프로젝트 루트에 둘 수 있는 AGENTS.md·CLAUDE.md 하네스 템플릿을 제시합니다.

문제의 배경: 프롬프트를 넘어 '하네스'로#

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

핵심 아키텍처: CAR 모델#

CAR(Control, Agency, Runtime) 구조는 하네스를 세 축으로 나눕니다.

Control (통제): AI의 페르소나와 규칙을 정의하는 불변의 가이드라인입니다. 예를 들어 CLAUDE.md, AGENTS.md가 여기에 해당합니다.
Agency (권한): AI에게 부여된 도구와 권한의 범위입니다. 예를 들어 git 접근, npm 실행 권한이 있습니다.
Runtime (실행): AI가 코드를 작성하고 테스트하며 스스로 수정하는 '자가 치유(Self-healing)' 환경입니다.

실무 적용 사례: Claude Code, Codex, Gemini CLI#

개발자들이 자주 사용하는 AI 도구에 하네스 엔지니어링이 어떻게 적용되는지 살펴보겠습니다.

Claude Code: 규약 기반의 하네스 (Control)#

Anthropic의 Claude Code는 프로젝트 루트의 CLAUDE.md 파일을 하네스로 활용합니다.

적용 예시: 이 파일에 프로젝트의 코딩 컨벤션, 자주 쓰는 테스트 명령어, 절대 수정하면 안 되는 핵심 파일을 명시합니다. Claude는 실행할 때마다 이 하네스를 읽어 자신의 행동을 스스로 제약합니다.
효과: 시니어 개발자가 옆에서 가이드하는 것과 같은 일관성을 유지합니다.

Codex(GitHub Copilot): 컨텍스트 하네스 (Agency)#

Codex 기반의 Copilot은 단순 코드 완성을 넘어, 열려 있는 탭, 최근 수정한 파일, 로컬 DB 스키마 등을 '하네스' 데이터로 엮어냅니다.

적용 예시: @workspace 명령어로 전체 코드베이스의 인덱스를 하네스로 제공합니다. AI가 특정 함수를 수정할 때 연관된 의존성을 자동으로 분석해 사이드 이펙트를 방지합니다.

Gemini CLI: 워크플로우 하네스 (Runtime)#

Gemini CLI는 복잡한 터미널 명령어를 실행하는 하네스 역할을 합니다.

적용 예시: "로그인 기능을 구현해줘"라고 요청하면, Gemini CLI는 코드만 작성하는 데서 그치지 않습니다. pnpm test를 실행해 실패 지점을 확인하고, 그 에러 로그를 다시 입력값으로 넣어 코드를 수정하는 'Closed-loop Runtime'을 형성합니다.

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

[실무 템플릿] AGENTS.md & CLAUDE.md 설계#

프로젝트 루트에 둘 수 있는 하네스 템플릿 예시입니다. 이 파일 하나만 비치해도 AI 에이전트가 일관된 규칙 아래 동작하도록 유도할 수 있습니다.

# 프로젝트: [이름] - [핵심 목적 한 줄 요약]

## 🛠 Tech Stack
- <strong>Core:</strong> Next.js 16 (App Router), TypeScript 5.x, Tailwind 4
- <strong>State/Data:</strong> TanStack Query, Zustand
- <strong>Database:</strong> Supabase (PostgreSQL) + Prisma
- <strong>Testing:</strong> Vitest + Playwright

## 🏗 Architecture & Patterns
- <strong>Layered Design:</strong> `src/features/*` 내부에 도메인 로직을 응집합니다.
- <strong>Server-First:</strong> 클라이언트 사이드 `useEffect` 대신 Server Components와 Server Actions를 우선합니다.
- <strong>Single Source of Truth:</strong> 모든 외부 연동 로직은 `src/lib/integrations`에 위치시킵니다.

## 📜 Coding Rules (AI 행동 강령)
- <strong>Correctness > Cleverness:</strong> 복잡한 추상화보다 가독성 높고 '지루한' 코드를 선호합니다.
- <strong>Smallest Change:</strong> 수정 범위를 최소화하세요. 요청받지 않은 인접 코드를 리팩토링하지 않습니다.
- <strong>Typing:</strong> `any` 사용 금지. 모든 외부 데이터는 Zod로 런타임 검증을 수행합니다.
- <strong>Naming:</strong> 파일명은 `kebab-case`, React 컴포넌트는 `PascalCase`를 사용합니다.

## 🧪 Verification & Quality
- <strong>Definition of Done:</strong> 모든 코드는 `pnpm lint`, `pnpm typecheck`, 테스트 통과가 필수입니다.
- <strong>Bug Fix Protocol:</strong> 버그 수정 시 반드시 재현 테스트 케이스를 먼저 작성하세요.
- <strong>Manual Repro:</strong> 수정 후에는 직접 실행하여 결과를 확인하고 로그를 보고하세요.

## ⌨️ Essential Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`
- Lint: `pnpm lint --fix`

## 🚫 Anti-Patterns (절대 금지)
- ❌ 기능 폴더 내의 `barrel files` (index.ts) 사용 금지 (순환 참조 원인).
- ❌ 불필요한 에러 핸들링 금지 (글로벌 에러 바운더리에 위임).
- ❌ `localStorage` 직접 접근 금지 (커스텀 훅 `useStorage` 사용).

마치며#

참고 자료#

Mitchell Hashimoto, "The Era of Harness Engineering" (Feb 2026)
Anthropic Research: Scalable Verification Loops for Coding Agents (March 2026)
LangChain: DeepAgents and Virtual Harness Framework (March 2026)

TL;DR#

문제의 배경: 프롬프트를 넘어 '하네스'로#

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

핵심 아키텍처: CAR 모델#

실무 적용 사례: Claude Code, Codex, Gemini CLI#

Claude Code: 규약 기반의 하네스 (Control)#

Codex(GitHub Copilot): 컨텍스트 하네스 (Agency)#

Gemini CLI: 워크플로우 하네스 (Runtime)#

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

[실무 템플릿] AGENTS.md & CLAUDE.md 설계#

마치며#

참고 자료#

관련 글

TL;DR#

문제의 배경: 프롬프트를 넘어 '하네스'로#

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

핵심 아키텍처: CAR 모델#

실무 적용 사례: Claude Code, Codex, Gemini CLI#

Claude Code: 규약 기반의 하네스 (Control)#

Codex(GitHub Copilot): 컨텍스트 하네스 (Agency)#

Gemini CLI: 워크플로우 하네스 (Runtime)#

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

[실무 템플릿] AGENTS.md & CLAUDE.md 설계#

마치며#

참고 자료#

관련 글