AI 코딩의 진짜 핵심은 프롬프트가 아니라 하네스(Harness)다

AI 코딩 도구를 쓰는 개발자라면 한 번쯤 이런 경험이 있을 것입니다. 같은 팀에서 같은 LLM을 쓰는데, 어떤 사람은 10분 만에 끝내는 작업을 다른 사람은 1시간이 걸립니다. 이 차이는 프롬프트 실력이 아니라 하네스(Harness)에 있습니다. 상위 1%의 AI 네이티브 개발자들은 프롬프트를 다듬는 대신, AI가 일관된 결과를 내도록 하는 구조 설계에 수백 시간을 투자합니다.

이 글에서는 하네스의 개념부터 실전 구축법, 그리고 조직 전체의 생산성을 끌어올리는 전략까지, 여러 전문가와 엔지니어링 블로그의 인사이트를 종합하여 정리합니다.

하네스란 무엇인가

하네스는 말 그대로 AI 모델을 감싸서 일할 수 있게 만드는 시스템입니다. LLM 자체는 다음 토큰을 확률적으로 예측하는 엔진일 뿐이고, 하네스가 도구 접근, 권한 관리, 컨텍스트 주입, 실행 환경을 관리해야 비로소 "에이전트"가 됩니다.

새로 입사한 천재 신입 개발자를 떠올려 보세요. 아무리 똑똑해도 코드 리뷰 기준, 브랜치 명명 규칙, 배포 체크리스트를 모르면 매번 물어보거나 추측할 수밖에 없습니다. 하네스는 이 신입에게 회사의 모든 업무 가이드를 미리 학습시키는 것과 같습니다.

왜 프롬프트가 아니라 하네스인가

토스 기술 블로그의 관찰이 이 문제를 명확하게 짚습니다. 엔지니어 A는 코딩 가이드라인, 린팅 규칙, 기존 패턴을 먼저 컨텍스트로 준비한 뒤 Claude에게 리팩터링을 요청합니다. 10분이면 끝납니다. 엔지니어 B는 "이 함수 리팩터링해줘"라고만 던지고, 스타일 불일치를 한 시간 동안 반복 수정합니다.

차이는 개인의 프롬프트 센스가 아니라 사전에 구조화된 컨텍스트, 즉 하네스의 유무입니다. 프롬프트는 휘발되지만, 하네스는 팀 전체에 축적됩니다.

AI 코딩의 4단계 진화

Terry Cho(조대협)는 Keif Morris의 프레임워크를 빌려 인간과 AI의 협업 수준을 4단계로 정리합니다.

현재 업계의 중심은 3단계입니다. 개별 결과를 고치는 것이 아니라, 좋은 결과가 계속 나오도록 시스템(하네스)을 다듬는 단계입니다. 4단계(완전 자율 에이전트)는 아직 위험이 큽니다. 실제로 아마존에서는 AI 에이전트가 라이브 시스템을 삭제하여 13시간 다운타임이 발생하고, Amazon Q 코드가 장바구니/배송 오류를 일으켜 하루 만에 630만 건의 주문이 사라지는 사고가 있었습니다.

Claude Code 하네스의 3가지 핵심 요소

Claude Code에서 하네스를 구축하는 핵심 구성 요소는 Skills, Agents, Commands 세 가지입니다.

1. Skills (전문 지식 모듈)

범용 AI를 특정 도메인 전문가로 변환합니다. .claude/skills/ 디렉터리에 마크다운 파일로 저장하며, 500줄 이하를 권장합니다.

# 예시: FastAPI 백엔드 가이드라인 스킬
/fastapi-backend-guidelines 회원가입 기능 만들어줘

# 예시: 코드 리뷰 스킬
/code-review PR #234 리뷰해줘

2. Agents (자율 작업자)

독립적으로 완전한 작업을 수행합니다. .claude/agents/ 폴더에 정의하며, 역할별 AI 어시스턴트를 만들 수 있습니다.

• Planner Agent: 단계별 개발 계획 수립
• Plan Reviewer Agent: 보안 리스크, 누락 항목 감지
• Web Research Agent: 개발 커뮤니티와 문서를 동시 검색

3. Commands (슬래시 커맨드 매크로)

복잡한 워크플로우를 한 번의 명령으로 자동화합니다. 보안 점검, 스타일 검증, 개선 제안을 하나의 /code-review로 묶을 수 있습니다.

엔터프라이즈 하네스 설계: CPS 프레임워크

실무에서 하네스를 설계할 때는 CPS(Context-Problem-Solution) 프레임워크가 효과적입니다. 비정형적인 고객 요구사항을 구조화하여 AI가 일관된 결과를 내도록 강제합니다.

여기에 린터(Linter)를 결합하면 코드 레벨에서 결과물을 강제할 수 있습니다. 파일 명명 규칙, 아키텍처 구조, 금지 패턴 등을 린터로 잡으면 AI가 어떤 모델이든 멱등성(같은 입력에 항상 같은 구조의 결과)을 보장합니다.

조직 전체의 생산성 저점 높이기

토스 기술 블로그가 제안하는 3계층 하네스 아키텍처는 조직 전체의 AI 활용 수준을 끌어올리는 전략입니다.

핵심은 하네스가 실행 가능한 SSOT(Single Source of Truth)가 된다는 점입니다. 전통적인 문서는 작성 즉시 낡아지지만, 플러그인/스킬로 만든 하네스는 코드로서 즉시 실행됩니다. 사람이 읽으면 운영 가이드라인이 되고, LLM이 읽으면 정확한 시스템 프롬프트가 됩니다.

장기 실행 에이전트의 아키텍처

Anthropic이 공개한 에이전트 하네스 아키텍처는 AI가 몇 시간, 며칠에 걸쳐 작업할 때 필요한 구조를 설명합니다. 핵심은 두 종류의 에이전트를 분리하는 것입니다.

• 초기화 에이전트: 프로젝트 구조 분석, 의존성 파악, 작업 계획 수립
• 코딩 에이전트: 초기화 에이전트가 만든 계획에 따라 실제 코드 작성 및 테스트

이 분리가 중요한 이유는 컨텍스트 윈도우 한계 때문입니다. 200K 토큰이라는 제한 안에서 모든 것을 처리하려면, 계획과 실행을 분리하고 각 단계에서 필요한 컨텍스트만 주입해야 합니다.

실전 CLAUDE.md 작성 팁

하네스의 시작점은 프로젝트 루트의 CLAUDE.md 파일입니다. 세션이 바뀌어도 유지되는 영구 기억으로, 다음 항목을 포함하는 것을 권장합니다.

# CLAUDE.md 예시 구조

## 프로젝트 개요
- 기술 스택: Next.js 14 + FastAPI + PostgreSQL
- 아키텍처: 모노레포 (turborepo)

## 코딩 표준
- 함수명: camelCase
- 컴포넌트: PascalCase
- 커밋 메시지: Conventional Commits

## 금지 패턴
- any 타입 사용 금지
- console.log 프로덕션 코드 금지
- 인라인 스타일 금지

## 테스트 규칙
- 모든 API 엔드포인트에 통합 테스트 필수
- 커버리지 80% 이상 유지

## 배포 절차
- main 브랜치 직접 푸시 금지
- PR 리뷰 1명 이상 필수

데이터 플라이휠: 하네스의 장기적 가치

구조화된 하네스 기반 워크플로우는 고품질 데이터를 축적합니다. 이 데이터로 도메인 특화 모델(sLLM)을 파인튜닝하면, 향상된 모델이 더 좋은 결과를 내고, 그 결과가 다시 데이터가 되는 선순환이 만들어집니다.

1. 표준화된 워크플로우 → 구조화된 데이터 축적
2. 축적된 데이터 → 도메인 특화 모델 파인튜닝
3. 기존 워크플로우 → 평가 벤치마크로 활용
4. 향상된 모델 → 생산성 향상 → 더 많은 데이터

핵심 정리

• 하네스 = AI 모델을 감싸는 실행 시스템. 프롬프트는 휘발되지만, 하네스는 팀에 축적됨
• 현재 업계는 3단계(Human on the Loop): 결과물이 아닌 시스템을 개선하는 단계
• Claude Code 하네스의 3요소: Skills, Agents, Commands
• CPS 프레임워크 + 린터로 멱등성 있는 결과 보장
• 3계층 구조(Global → Domain → Local)로 조직 전체 생산성 저점을 높임
• 장기적으로 데이터 플라이휠을 통해 자체 모델까지 진화 가능

참조 링크

• 상위 1% AI 네이티브의 하네스 깎기 - Builder Josh하네스 엔지니어링, CPS 프레임워크, 멱등성, 린터 활용 실전 사례
• 클로드 코드 Harness의 비밀 - AI ONAnthropic의 에이전트 하네스 아키텍처, 초기화/코딩 에이전트 분리
• AI Coding 개발 단계 - Terry Cho인간-AI 협업 4단계 프레임워크, Amazon 사고 사례
• Software 3.0 시대, Harness를 통한 조직 생산성 - Toss TechLLM Literacy, 3계층 하네스 아키텍처, 데이터 플라이휠
• Claude Code 작동 원리 - Harness, Context, MemoryAgentic Harness 3층 아키텍처, 세션/컨텍스트/메모리 관리
• Claude Code Harness 완벽 가이드Skills, Agents, Commands 3요소 실전 구축법