[Claude] Harness Engineering

1. Agentic AI Engineering방식

(1) Prompt Engineering

"LLM에게 말을 잘하는 기술"이라고 볼 수 있습니다. 프롬프트 엔지니어링은 모델에 입력되는 지시어(Instruction) 자체를 최적화하는 기술입니다. 모델의 내재된 지식을 가장 잘 끌어낼 수 있도록 문장 구조, 예시, 제약 조건을 설계하는 데 집중합니다.

A. 핵심 요소: Zero-shot/Few-shot 학습, Chain of Thought(단계별 사고), 페르소나 부여.

B. 목표: 모델이 사용자의 의도를 정확히 이해하고 원하는 형식의 답변을 내놓게 함.

숙련된 비서에게 업무 지시서를 명확하고 상세하게 작성해 주는 것에 비유할 수 있습니다.

(2) Context Engineering

"모델에게 어떤 정보를 참고할지 잘 가르쳐주는 기술"이라고 할 수 있습니다. 컨텍스트 엔지니어링은 프롬프트에 포함될 외부 데이터와 상태 정보를 관리하는 기술입니다. 모델의 파라미터에 없는 실시간 정보나 특정 도메인의 지식을 주입하여 답변의 정확도를 높입니다.

A. 핵심 요소: RAG(검색 증강 생성), 벡터 데이터베이스(Vector DB) 연동, 대화 이력 관리(Memory), 윈도우 슬라이딩.

B. 목표: 모델이 '모른다'고 하거나 환각(Hallucination)을 일으키는 것을 방지하고, 최신 지식에 기반한 답변을 유도함.

비서가 업무를 수행할 때 참고할 수 있도록 최신 보고서와 과거 회의록을 정리해서 책상 위에 올려두는 것에 비유할 수 있습니다.

(3) Harness Engineering

"모델이 만든 결과물을 어떻게 검증하고 통제할 지에 관한 기술"이라고 할 수 있습니다. 하네스 엔지니어링은 모델을 감싸는 평가 및 실행 인프라를 구축하는 기술입니다. 모델의 출력이 안전한지, 정확한지, 비용 효율적인지 등을 테스트하고 자동화된 워크플로우 안에서 안정적으로 작동하게 만듭니다.

A. 핵심 요소: LLM Evals(평가 프레임워크), 벤치마킹, 가드레일(보안 및 윤리 필터링), 단위 테스트 자동화.

B. 목표: 모델의 답변이 일관성을 유지하게 하고, 실제 서비스에 배포 가능한 수준의 신뢰성을 확보함.

비서가 작성한 결과물이 사내 규정에 맞는지 검토하고, 오타나 오류가 없는지 자동으로 체크하는 시스템을 갖추는 것에 비유할 수 있습니다.

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

구성 요소	역할	대표 예시
컨텍스트 파일	런타임 규칙 제공	agents.md, claude.md
자동화된 강제	규칙 위반 차단	린터, 프리커밋 훅
도구 경계	접근 권한 제한	명령어 화이트리스트
피드백 루프	가시성과 정화	로그, 가비지 컬렉션

(1) 기계가 읽는 컨텍스트 파일 (Context Files)

AI 에이전트가 세션을 시작할 때마다 가장 먼저 읽는 런타임 설정 파일입니다. agents.md, claude.md, rules.md 등이 대표적입니다.

오픈AI 팀에 따르면, 이 파일은 1,000페이지짜리 설명서가 아니라 보편적 규칙을 담은 '지도' 역할을 해야 합니다. 지나치게 길거나 세세한 지침은 오히려 모델의 판단을 흐립니다.

# agents.md 예시
- 모든 함수는 타입 힌트를 작성합니다.
- 외부 API 호출 전 반드시 캐싱 레이어를 확인합니다.
- DB 마이그레이션은 별도의 PR로 분리합니다.

(2) 자동화된 강제 및 교정 시스템 (Automated Enforcement)

린터, 프리커밋 훅, 아키텍처 테스트를 통해 규칙 위반을 즉각 차단합니다. AI가 잘못된 코드를 작성하면 시스템이 에러를 띄우고, AI가 스스로 수정하여 테스트를 통과할 때까지 반복하는 자동 교정 루프가 핵심입니다.

# .pre-commit-config.yaml 예시
repos:
  - repo: https://github.com/psf/black
    hooks:
      - id: black
  - repo: local
    hooks:
      - id: pytest-check
        name: pytest-check
        entry: pytest tests/
        language: system

(3) 도구의 경계 및 접근 권한 제한 (Tool Boundaries)

AI가 접근할 수 있는 폴더를 읽기 전용으로 제한하거나, 터미널 명령어의 화이트리스트를 설정합니다. 데이터베이스의 경우 SELECT는 허용하되 DROP TABLE은 물리적으로 불가능하게 막는 식의 차단벽을 세웁니다.

{
  "permissions": {
    "allow": ["Bash(git status)", "Bash(pytest:*)", "Read(./src/**)"],
    "deny": ["Bash(rm -rf:*)", "Write(./.env)"]
  }
}

⚠️ ️ 권한 설정을 너무 느슨하게 두면 AI가 의도치 않게 운영 환경을 건드릴 수 있습니다. 처음에는 좁게 시작하여 필요할 때마다 확장하는 방식을 권장합니다.

(4) 피드백 루프 및 가비지 컬렉션 (Feedback & Garbage Collection)

로그와 스크린샷을 통해 AI가 자신의 작업 결과물을 스스로 모니터링하고 피드백할 수 있게 합니다. 또한 AI가 생성한 나쁜 패턴이나 중복 코드를 주기적으로 청소하고, 발생한 실수를 새로운 규칙으로 추가하여 하네스를 점진적으로 강화합니다.

---

하네스 엔지니어링에서 로그의 중요성

이제 로그는 단순히 디버깅을 위한 부산물이 아니라, 하네스 엔지니어링의 피드백 루프를 작동시키는 원천이 됩니다.

A. 인간 병목을 제거하는 가시성

자동화 시스템에서 가장 큰 걸림돌은 인간이 직접 결과물을 확인해야 하는 순간입니다. 로그가 충분하지 않으면 사람이 매 단계마다 개입해야 하므로, 자율 에이전트의 의미가 사라집니다. 잘 설계된 로그는 AI가 자신의 행동 결과를 스스로 읽고 다음 행동을 결정할 수 있게 해 줍니다.

B. AI의 자기 교정 루프 완성

자동 교정 루프가 작동하려면 AI가 "내가 무엇을 잘못했는지"를 구체적으로 알아야 합니다. 로그는 그 증거를 제공합니다.

💡 에러 메시지뿐 아니라 실행 시점의 입력값, 중간 상태, 호출 스택까지 남겨야 AI가 근본 원인을 파악하고 재시도 전략을 세울 수 있습니다.

C. 하네스 강화를 위한 데이터 축적

AI가 반복적으로 같은 실수를 한다면, 그 패턴은 로그에 남습니다. 이 로그를 분석하여 새로운 린터 규칙이나 프리커밋 훅으로 승격시키면, 같은 실수가 다시 발생하지 않는 구조를 만들 수 있습니다. 즉, 로그는 하네스를 점진적으로 진화시키는 학습 데이터 역할을 합니다.

로그가 없을 때	로그가 잘 갖춰졌을 때
사람이 매번 결과를 확인	AI가 스스로 결과를 검증
같은 실수가 반복됨	실수 패턴을 규칙으로 자동화
디버깅에 추측이 필요	재현 가능한 근거 확보

⚠️ ️ 단, 로그가 너무 장황하면 AI의 컨텍스트 창을 빠르게 소모합니다. 핵심 이벤트만 구조화된 형식(JSON 등)으로 남기고, 상세 로그는 별도 저장소에 두어 필요할 때만 조회하도록 설계하는 것이 좋습니다.

◀ Claude Channel/Dispatch [Claude] Harness Engineering ▶

📋 Table of Contents로 돌아가기