AI 코딩 에이전트의 환각을 방지하는 방법: Harness Engineering 가이드

AI 코딩 에이전트(Claude Code, Devin 또는 OpenClaw와 같은 오픈 소스 대응 모델)는 믿을 수 없을 정도로 강력합니다. 이들은 디렉토리를 탐색하고, 테스트를 작성하며, 모듈을 리팩터링(Refactor)하고, PR(Pull Request)을 제출할 수 있습니다.

하지만 경계 조건 없이 가공되지 않은 저장소(Repository)에 에이전트를 투입하면, 컨텍스트 윈도우 오염 (Context Window Pollution), 에이전트 건망증 (Agent Amnesia), 그리고 범위 이탈 (Scope Drift) 문제를 겪게 됩니다. 단순한 버그 수정 리팩터링 작업이 에이전트로 하여금 프로젝트의 절반을 재설계하고, 관련 없는 테스트를 삭제하며, "프로세스 연극 (Process Theater)"에 빠져 6시간 동안 루프를 돌게 만드는 상황을 초래할 수 있습니다.

이를 해결하기 위해서는 Harness Engineering이 필요합니다.

Harness Engineering이란 무엇인가?

**에이전트 하네스 (Agent Harness)**는 에이전트의 작업을 안내하고 검증하기 위해 설계된 구조화된 저장소 로컬 제어 계층입니다. LLM (Large Language Model)에 거대한 단일 프롬프트(Monolithic Prompt)를 제공하는 대신, 워크스페이스 내부에 가벼운 기록 시스템과 물리적 피드백 루프를 직접 내장하는 방식입니다.

저는 로컬 에이전트를 조종하고 제약하기 위해 사용하는, 검증된 마크다운(Markdown) 기반의 컨텍스트 규칙들을 하나의 공개 저장소로 패키징했습니다: MasihMoafi/harnesses-I-use.

이 저장소는 복잡한 코드 대신, 가공되지 않은 설정 규칙 시트(Configuration Rule Sheets)를 공유합니다:

• AGENTS.md: 글로벌 라우터 (Global router)이자 기본 진입점입니다. 모든 AI 에이전트는 우선순위 커널 (Priority Kernel; 응답 제약 조건, 영어 기본값, 로컬 우선 동작 등)을 이해하기 위해 이 파일을 가장 먼저 읽습니다.
• CODEX_CODING_GUIDELINES.md: Andrej Karpathy의 코딩 관행에서 채택한 정밀한 코딩 규칙입니다. 최소한의 변경, 스타일 일치, 그리고 목표 중심 실행 (Goal-driven execution)을 강제합니다.
• TERMINAL_AND_GIT_RULES.md: 안전한 터미널 탐색, SOCKS/HTTP 프록시 설정, 명시적인 Git 범위 지정 (예: git add -A를 절대 사용하지 않음), 그리고 변경 안전성 (원시 CLI 비밀번호 프롬프트 대신 루트 명령에 Ubuntu pkexec 사용)에 관한 규칙입니다.
• SESSION_HANDOFF_RULES.md: 문맥 인식 (Context awareness) 및 연속성을 위한 가이드라인입니다. 상태 (State)가 세션 간에 어떻게 캡처되고 전달되어야 하는지를 정의합니다.
• ARTIFACT_RULES.md: 로컬 HTML 레이아웃 검증, 수식 렌더링을 위한 MathML, PDF 검사 등을 포함하여 검증된 시각적 및 수학적 출력을 생성하기 위한 규칙입니다.
• abbn.md: 토큰 수를 절약하고 짧고 효율적인 통신을 유지하기 위한 표준 약어 사전입니다 (예: ctu = continue, fmy = familiarize, ver = verify).

Karpathy와의 연결 고리: 단순함과 엄격함

이 Harness 접근 방식은 Andrej Karpathy의 오픈 소스 교육 저장소(micrograd 및 **makemore**와 같은)에서 큰 영감을 받았습니다.

Karpathy의 프로젝트들이 찬사를 받는 이유는 불필요한 요소(bloat)를 제거하기 때문입니다. 이들은 명확하고 재현 가능한 수학적 베이스라인 (baselines)에 집중하며 과잉 엔지니어링 (over-engineering)을 피합니다.

우리는 에이전트 기반 코드 생성 (agent-driven code generation)에도 동일한 철학을 적용했습니다. 우리 하네스 (harness)의 핵심 규칙은 다음과 같습니다:

1. 정밀한 변경 (Surgical Changes): 요청된 정확한 라인만 수정합니다. 인접한 코드를 무분별하게 리팩토링 (refactoring)하지 않습니다.
2. 검증 가능한 결과 (Verifiable Outcomes): 에이전트가 기능이 완료되었다고 주장하기 전에, 반드시 로컬 스크립트를 실행하여 베이스라인을 검증하고, 코드를 컴파일하며, 성공의 물리적 증거로서 로우 터미널 출력 로그 (raw terminal output logs)를 세션 기록에 첨부해야 합니다.
3. 하네스 단순화 (Harness Simplification): 모든 규칙은 오버헤드 (overhead)로 간주됩니다. 모델이 더 똑똑해짐에 따라, 우리는 테스트를 실행하여 불필요한 규칙을 제거 (prune)합니다.

사례 연구: 머신러닝 연구 보고서의 자율 생성

이를 테스트하기 위해, 저는 이와 동일한 하네스를 사용하여 비교 머신러닝 연구 프로젝트인 **센서 결함 진단 (Sensor Fault Diagnosis)**을 구축했습니다.

에이전트에게는 현실적인 합성 센서 데이터셋이 주어졌으며, 다음과 같은 과업이 부여되었습니다:

1. 베이지안 분류기 (Bayesian classifier, Gaussian Naive Bayes)를 학습시키고 조건부 확률 (conditional probabilities)을 매핑합니다.
2. PyTorch MLP 신경망 (neural network)을 구축하고 학습시킵니다.
3. 표준 이진 교차 엔트로피 (Binary Cross-Entropy, BCE), micrograd 스타일의 최대 마진 (Max-Margin/Hinge) 손실 (loss), 그리고 makemore 스타일의 교차 엔트로피 (Cross-Entropy) 손실을 포함한 여러 손실 함수를 계산하고 비교합니다.
4. ROC 곡선과 결정 경계 (decision boundaries)를 내보내고, 출판 가능한 수준의 LaTeX/HTML 연구 논문을 생성합니다.

에이전트를 단일 제어 표면 (control surface, 구조화된 매뉴얼)으로 제한하고 엄격한 유지/폐기 기준을 강제함으로써, 에이전트는 파이프라인을 완료하고 최종 보고서를 완전히 자율적으로 작성했습니다.

하네스가 없었다면, 에이전트는 장식용 대시보드 스크립트나 가짜 성능 지표로 저장소 (repository)를 비대하게 만들었을 것입니다. 하네스는 에이전트가 본질에 집중할 수 있도록 유지해 주었습니다.

하네스 구축하기

AI 에이전트로 코드를 작성하고 있다면, 2,000단어짜리 시스템 프롬프트 (system prompts)를 쓰는 것을 멈추십시오. 대신 저장소 하네스 (repository harnesses)를 구축하기 시작하십시오.

템플릿과 설정들을 확인해 보세요:
👉 MasihMoafi/harnesses-I-use

저의 더 많은 작업물, 실험, 그리고 연구 결과는 제 웹사이트에서 확인하실 수 있습니다:
👉 masihmoafi.tech