야생마 같은 AI를 내 완벽한 비서로 만드는 비결: '하네스 엔지니어링'과 'AI 에이전트 팀'

 

요즘 ChatGPT, 클로드(Claude) 같은 AI를 업무에 많이들 활용하지만 AI를 쓰다 보면 꼭 이런 답답한 순간이 찾아옵니다.

"이모티콘 쓰지 말고 표 형식으로 써달라고 어제 말했는데, 왜 오늘 새 대화창을 열니까 또 원래대로 돌아가 있지?"
"처음에는 똑똑하게 일하다가 대화가 길어지니까 중요한 규칙을 자꾸 까먹네?"

 

매번 AI에게 똑같은 규칙을 설명하느라 피곤하셨다면, 오늘 소개해 드릴 하네스 엔지니어링(Harness Engineering)과 AI 에이전트 팀 설계 개념에 주목해 보세요! 

 

 

 

https://youtu.be/g4fZ_hT1Pfc

 

 

---

1. 하네스 엔지니어링(Harness Engineering)이 뭔가요?

가장 알기 쉬운 비유는 **'야생마와 마구(Harness)'**입니다. 현재의 거대 언어 모델(LLM)은 엄청나게 힘이 세고 달리기 속도가 빠른 야생마와 같습니다. 하지만 이 강력한 말에 고삐와 안장을 채우지 않고 벌판에 그냥 풀어놓으면, 제멋대로 날뛰며 엉뚱한 방향으로 도망쳐 버립니다.

 

AI 모델이라는 야생마가 우리가 원하는 트랙 위에서 안전하고 빠르게 달릴 수 있도록 고삐, 안장, 안전 울타리를 채워주는 기술이 바로 하네스 엔지니어링입니다.

• 프롬프트 엔지니어링(과거): AI에게 매번 대화할 때마다 "제발 이렇게 해줘"라고 부탁하는 방식이었습니다.
• 하네스 엔지니어링(현재): AI가 애초에 실수를 할 수 없도록 시스템과 규칙을 통해 행동을 제약하고 강제하는 시스템 설계 방식입니다.

2. 하네스를 구성하는 4가지 안전장치

내 AI 비서가 한 치의 오차도 없이 일하게 만들려면 아래 **4가지 기둥(Pillars)**을 세워주어야 합니다.

1. AI 전용 업무 지침서 (CLAUDE.md): 프로젝트 폴더 최상단에 지침 문서를 만들어 둡니다. AI는 대화 세션을 새로 시작할 때마다 이 문서를 1순위로 읽기 때문에, 매번 배경 설명을 반복할 필요가 없습니다.
2. 자동 검증 시스템 (자동화 게이트): AI가 작성한 결과물을 사람이 확인하기 전에, 시스템이 먼저 자동으로 검사(린터, 자동 테스트 등)를 돌립니다. 만약 규칙에 어긋나면 저장되지 않도록 막고 AI에게 빨간 불(에러)을 보여줍니다. 그러면 AI는 스스로 에러를 인지해 알아서 고쳐 옵니다(자동 교정 루프).
3. 명확한 도구와 권한 경계: AI에게 컴퓨터 전체 권한을 주는 대신, "이 폴더만 읽고 써라", "중요한 파일을 삭제하거나 메일을 발송할 때는 반드시 인간의 최종 승인(게이트)을 받아라"는 식으로 물리적 안전지대를 설정해 줍니다.
4. 자동 청소 에이전트 (가비지 컬렉션): AI가 일을 오래 하다 보면 불필요한 나쁜 패턴의 파일이나 쓰레기 데이터가 쌓입니다. 이를 방지하기 위해 주기적으로 작업 환경을 정리하고 검수하는 청소 에이전트를 돌려 시스템 무결성을 유지합니다.

3. "이제 한 명에게 다 시키지 마세요" — AI 에이전트 팀 설계

아무리 똑똑한 사람이라도 기획, 디자인, 개발, 검토까지 100가지 일을 동시에 혼자 다 하려면 과부하가 걸려 실수하기 마련입니다. AI도 똑같습니다. 한 세션에서 모든 일을 다 처리하게 하면 정보가 가득 차 앞의 내용을 잊어버리는 '컨텍스트 부패(Context Decay)' 현상이 일어납니다.

그래서 페르소나(역할)를 잘게 쪼갠 AI 팀을 설계해야 합니다.

• 플래너 (Planner): 사용자의 모호한 요청을 분석해 구체적이고 꼼꼼한 계획과 사양서를 작성합니다.
• 제너레이터 (Generator): 계획서에 명시된 기준대로 실제 구현(글 작성, 코딩 등)만 전담합니다.
• 이밸루에이터 (Evaluator / QA): 냉정하고 엄격한 눈으로 제너레이터의 결과물을 검토하고, 합격 기준을 통과하지 못하면 반려합니다.

이렇게 에이전트끼리 서로 감시하고 교차 검증하는 팀을 구축해 두면, 메인 대화창의 기억 용량이 낭비되지 않아(토큰 비용 절감) 훨씬 더 오랫동안 높은 품질로 일할 수 있게 됩니다.

 

---

 

 

그럼 실제 사례를 한번 보겠습니다.

 

---

 

CLAUDE.md(또는 agents.md) 파일은 단순한 가이드라인이 아닙니다. AI 에이전트가 작업을 시작할 때 가장 먼저 읽고 동작의 기준으로 삼는 **프로젝트의 '헌법이자 온보딩 문서'**입니다.

실무에서 가장 효과적으로 작동하는 CLAUDE.md의 3대 설계 원칙과 표준 템플릿, 그리고 이를 시스템적으로 강제하는 실전 하네스 연동 가이드를 정리해 드립니다.

1. CLAUDE.md 설계의 3대 핵심 원칙

1. 1,000페이지의 설명서 대신 '지도'를 제공하세요 (점진적 공개) 모든 상세한 규칙과 요구사항을 하나의 파일에 다 우겨넣으면 AI가 주의력을 잃고 중요한 지침을 누락하는 **'컨텍스트 부패(Context Decay)'**가 발생합니다. 최상위 CLAUDE.md 파일은 60~100줄 내외로 간결하게 유지하고, 세부 지침은 별도의 문서로 분리한 뒤 목차(경로)만 안내하여 필요할 때 찾아 읽게 만드는 점진적 공개(Progressive Disclosure) 패턴을 취해야 합니다.
2. '어떻게'는 줄이고 '무엇을·왜'를 선명하게 하세요 (프롬프트 부채 방지) AI 모델(Fable 5 등)이 고도화될수록 과거 구모델의 빈틈을 메우기 위해 덧붙였던 과도하게 규정적인(too prescriptive) 행동 절차나 예외 조항들은 오히려 출력 품질을 떨어뜨리는 '프롬프트 부채'가 됩니다. 구체적인 코딩 절차("어떻게")는 최소화하되, 반드시 지켜야 할 의도, 아키텍처 경계, 그리고 완료 및 검증 기준("무엇을·왜")을 명확하게 정의해 주어야 합니다.
3. 실패를 통한 점진적 진화 처음부터 완벽한 규칙을 만들려고 고심하지 마세요. 개발을 진행하면서 AI 에이전트가 엉뚱한 코드를 짜거나 컨벤션을 어기는 실수를 할 때마다, 그 실패가 구조적으로 반복 불가능하도록 한 줄씩 규칙을 보강해 나가는 것이 하네스를 진화시키는 가장 빠른 방법입니다.

2. CLAUDE.md 표준 마크다운 템플릿

프로젝트의 최상위 루트 디렉토리에 아래 양식으로 CLAUDE.md 파일을 생성하여 관리하는 것을 권장합니다.

# [Project Name] - AI 개발 및 업무 지침서

## 1. 프로젝트 목적 및 컨텍스트 (Purpose & Context)
- **목적**: [예: 대한민국 AI 지원사업/공모전 정보 큐레이션 웹서비스 구현]
- **대상 사용자**: [예: 스타트업, 예비 창업자, 연구자]
- **핵심 목표**: AI가 일방적으로 코드를 구현하기 전에 반드시 `docs/specs/` 내 EARS 형식의 기능 명세를 확인하고 동기화할 것

## 2. 핵심 실행 명령어 (Core Commands)
AI 에이전트가 로컬 환경에서 작업을 검증하고 실행할 수 있도록 명령어 표준을 제공합니다.
- **의존성 설치**: `uv pip install -r requirements.txt` (가상환경은 반드시 `uv` 기반 `.venv` 사용)
- **개발 서버 구동**: `python -m src.main` (포트는 무조건 `3000`번 고정 사용)
- **테스트 실행**: `pytest tests/` (성공 시 메시지 최소화, 실패 시 로그 상세 출력)
- **린트 및 정적 분석**: `ruff check src/`

## 3. 지식 지도 및 디렉토리 구조 (Knowledge Map)
AI가 필요한 세부 지식을 스스로 찾을 수 있는 점진적 공개용 주소록입니다.
- `docs/specs/`: 프로젝트 기능 명세서 (EARS 형식 기반)
- `docs/architecture/`: 도메인 아키텍처 및 데이터베이스 스키마 정의
- `docs/design/`: UI/UX 디자인 시스템 가이드라인 (`DESIGN.md` 포함)
- `.claude/skills/`: 특정 작업 단계별 재사용 가능한 스킬 가이드 파일 목록

## 4. 아키텍처 및 안전 제약 사항 (Constraints & Guardrails)
타협할 수 없는 절대적인 규칙입니다. 규칙 위반 시 테스트나 훅 단계에서 즉시 반려됩니다.
- **ORM 제약**: 데이터베이스는 직접 쿼리(Raw SQL)를 실행하지 말고, 반드시 정의된 ORM을 통해서만 접근할 것
- **라이브러리 제한**: 새로운 외부 패키지 도입 금지. 필요 시 개발자에게 먼저 질문하여 허가를 획득할 것
- **보안 가드레일**: API 키, 개인정보(PII)는 절대 코드나 설정 파일에 직접 기재하지 말고 `.env` 환경 변수로 주입할 것
- **코드 수정 방식**: 파일 전체를 새로 작성하지 말고 변경이 필요한 부분만 타겟팅하여 교체할 것

## 5. 변경 이력 (Change History)
에이전트가 작업을 완료할 때마다 아래에 이력을 간단히 남겨 무결성을 유지합니다.
- v1.0.0 (2026-06-28): 프로젝트 초기화 및 `CLAUDE.md` 기본 헌법 제정
- v1.1.0 (2026-07-06): 폰트 가이드라인 및 프리커밋 훅 검증 단계 추가

3. 실전 하네스 연동 및 자동화 가이드

CLAUDE.md 문서 작성을 넘어, AI가 이 규칙을 **강제적으로 따를 수밖에 없는 환경(하네스)**을 구축해야 진정한 효과가 발휘됩니다.

① 린터(Linter)와 프리커밋 훅(Pre-commit Hook) 연동

AI가 코드를 작성한 뒤 저장하거나 커밋하려는 순간 자동으로 검사가 돌아가게 만듭니다.

• 원리: AI 에이전트가 규칙을 무시하고 커밋을 시도하면 **프리커밋 훅(Husky 등)**이 작동하여 이를 강제로 차단하고 에러 로그를 출력합니다.
• 효과: "실수는 조용히, 실패는 시끄럽게" 원칙에 따라 에러가 발생한 지점을 AI에게 즉시 피드백하면, 인간의 개입 없이 AI 스스로 코드를 고치는 **'자동 교정 루프(Auto-correction Loop)'**가 작동합니다.

② 도구 및 디렉토리 접근 권한 제한

settings.json 설정이나 환경 변수 제어를 통해 AI의 활동 반경을 물리적으로 제한합니다.

• 소스 코드 폴더(src/)는 읽기/쓰기가 가능하게 열어두되, 프로젝트 설정 폴더(config/)나 민감한 보안 자산 폴더는 읽기 전용(Read-Only)으로 가두어 둡니다.
• 데이터베이스 접근 시 일반적인 데이터 조회(SELECT) 권한은 허용하되, 테이블 삭제(DROP)와 같은 위험한 도구 호출 권한은 완전히 제약하여 시스템 붕괴 사고를 사전에 차단합니다.