README_KO.md

April 2, 2026 · View on GitHub

AutoHarness Logo

「Aha」— AutoHarness: Automated Harness Engineering for AI Agents

모든 에이전트는 aha 모먼트를 누릴 자격이 있습니다 — 모델은 추론하고, 나머지는 우리가 harness합니다.

AutoHarness Poster

MIT License Python 3.10+ 958 Tests Passed GitHub Ruff mypy

🇬🇧 English · 🇨🇳 简体中文 · 🇯🇵 日本語 · 🇰🇷 한국어 · 🇪🇸 Español · 🇫🇷 Français · 🇩🇪 Deutsch · 🇵🇹 Português · 🇷🇺 Русский

📖 문서 · 🚀 빠른 시작 · 🔧 파이프라인 모드 · 📊 비교표

⚡ 빠른 설치

git clone https://github.com/aiming-lab/AutoHarness.git
cd AutoHarness && pip install -e .

from openai import OpenAI
from autoharness import AutoHarness

client = AutoHarness.wrap(OpenAI())
# 이게 전부입니다. 에이전트가 방금 aha 모먼트를 경험했습니다.

🔥 뉴스

  • [04/01/2026] v0.2.0 출시: 3단계 파이프라인 모드(Core / Standard / Enhanced), 트레이스 기반 진단, 인터페이스 검증 게이트, 개선된 컨텍스트 관리. 958개 테스트 통과.
  • [04/01/2026] v0.1.0 출시: 6단계 거버넌스 파이프라인, 위험 패턴 매칭, YAML 헌법, 감사 트레일, 멀티 에이전트 프로파일, 비용 추적이 포함된 세션 영속성.

🤔 왜 Aha (AutoHarness)인가?

LLM 훈련에서 aha 모먼트는 모델이 갑자기 추론을 배우는 순간입니다.

에이전트에게 aha 모먼트는 "데모용"에서 진정으로 신뢰할 수 있는 시스템으로 도약하는 순간입니다.

그 사이의 간극은 거대합니다: 컨텍스트 관리, 도구 거버넌스, 비용 제어, 관측성, 세션 영속성... 이것들이 장난감 수준과 실제 시스템을 구분하는 패턴입니다. 우리는 이것을 하네스 엔지니어링이라 부릅니다.

AutoHarness는 경량의 계층적 거버넌스 프레임워크로, 모든 에이전트가 자신만의 aha 모먼트를 경험할 수 있도록 만들어졌습니다.

에이전트 = 모델 + 하네스. 모델은 추론하고, 하네스는 나머지 모든 것을 담당합니다.

🚀 빠른 시작

# 기존 LLM 클라이언트에 거버넌스 래핑 (2줄, 즉시 거버넌스)
from openai import OpenAI
from autoharness import AutoHarness

client = AutoHarness.wrap(OpenAI())
response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Refactor auth.py"}],
    tools=[{"type": "function", "function": {"name": "Bash", "description": "Run shell commands",
            "parameters": {"type": "object", "properties": {"command": {"type": "string"}}}}}],
)

# 또는 풀 에이전트 루프 사용
from autoharness import AgentLoop

loop = AgentLoop(model="gpt-5.4", constitution="constitution.yaml")
result = loop.run("Fix the failing tests in auth.py")

더 많은 예시 →

✨ 주요 기능

하네스 없이AutoHarness 적용 후
에이전트가 rm -rf /를 실행해도 아무도 막지 않음6단계 파이프라인이 차단하고, 로그를 남기고, 이유를 설명
토큰 한도를 넘어 컨텍스트 폭발토큰 예산 + 트렁케이션으로 컨텍스트 제어
어떤 도구 호출이 얼마나 비용이 드는지 알 수 없음호출별 비용 귀속과 모델 인식 가격 책정
프롬프트 인젝션이 그대로 통과계층별 검증: 입력 레일, 실행, 출력 레일
컴플라이언스를 위한 감사 트레일 없음JSONL 감사로 모든 결정을 완전한 출처와 함께 기록
모든 에이전트가 동일한 권한 세트 공유멀티 에이전트 프로파일로 역할 기반 거버넌스

핵심 아키텍처: 6단계 거버넌스 파이프라인

모든 도구 호출은 구조화된 파이프라인을 통과합니다:

1. 파싱 및 검증  →  2. 위험 분류  →  3. 권한 확인
4. 실행          →  5. 출력 소독  →  6. 감사 기록

내장 위험 패턴으로 위험한 작업, 시크릿 노출, 경로 탐색 등을 탐지합니다.

핵심 수치

6단계 거버넌스 파이프라인   ·  위험 패턴 매칭          ·  YAML 헌법
토큰 예산 관리             ·  멀티 에이전트 프로파일    ·  JSONL 감사 트레일
통합에 단 2줄              ·  벤더 종속 없음           ·  MIT 라이선스

🔧 파이프라인 모드

AutoHarness는 3가지 파이프라인 모드를 지원합니다. 필요에 맞는 거버넌스 수준을 선택하세요:

모드파이프라인컨텍스트멀티 에이전트사용 사례
Core6단계토큰 예산 + 트렁케이션단일 에이전트경량 거버넌스
Standard8단계+ Microcompact + 트레이스 저장소기본 프로파일프로덕션 에이전트
Enhanced14단계+ LLM 요약 + 이미지 제거Fork / Swarm / Background최대 거버넌스
# 헌법으로 모드 전환
# constitution.yaml
mode: core      # 또는 "standard" 또는 "enhanced"

# 또는 CLI로 전환
autoharness mode enhanced

Enhanced 모드가 기본값입니다. 사용자에게 가장 강력한 거버넌스가 기본 제공됩니다. 최소 오버헤드를 원하면 Core로 전환하세요.

전체 모드 비교 →

🖥️ CLI

autoharness init                          # 헌법 생성 (default/strict/soc2/hipaa/financial)
autoharness init --mode core              # 특정 파이프라인 모드로 생성
autoharness mode                          # 현재 파이프라인 모드 표시
autoharness mode enhanced                 # 파이프라인 모드 전환
autoharness validate constitution.yaml    # 헌법 파일 검증
autoharness check --stdin --format json   # 규칙에 대해 도구 호출 검사
autoharness audit summary                 # 감사 요약 보기
autoharness install --target claude-code  # Claude Code 훅으로 설치 (원커맨드)
autoharness export --format cursor        # 크로스 하네스 헌법 내보내기

📊 비교표

기능AutoHarnessLangGraphGuardrails AIOpenAI SDK
도구 거버넌스 파이프라인✅ 6단계 (최대 14)❌⚠️ 출력만❌
컨텍스트 관리✅ 멀티 레이어❌❌⚠️ Trimming
멀티 에이전트 프로파일✅✅ 그래프 기반❌⚠️ Handoff
검증 (입력+출력)✅❌✅ Rails❌
트레이스 기반 진단✅❌❌❌
비용 귀속✅ 호출별❌❌❌
벤더 종속없음LangChain없음OpenAI
설정 난이도2줄Graph DSLRAIL XMLSDK

🙏 감사의 글

  • Claude Code (Anthropic): Enhanced 모드의 일부 기능에 영감을 준 엔지니어링 패턴
  • Codex (OpenAI): 컨텍스트 관리 설계에 참고가 된 컨텍스트 엔지니어링 사례

📌 인용

연구에서 AutoHarness를 사용하신 경우 다음과 같이 인용해 주세요:

@software{autoharness2026,
  title   = {AutoHarness: The Harness Engineering Framework for AI Agents},
  author  = {{AutoHarness Team}},
  year    = {2026},
  url     = {https://github.com/aiming-lab/AutoHarness},
  license = {MIT}
}

⚠️ 면책 조항

Enhanced 모드의 일부 아키텍처 결정은 2026년 3월 31일 Anthropic의 npm 레지스트리를 통해 의도치 않게 공개된 Claude Code 설계에 대한 공개 분석 및 커뮤니티 논의를 참고했습니다. Claude Code의 원본 소스 코드가 Anthropic의 지적 재산임을 인정합니다. AutoHarness는 Anthropic의 독점 코드를 포함, 재배포 또는 직접 번역하지 않습니다. Anthropic의 지적 재산권을 존중하며 관련 우려 사항에 신속히 대응하겠습니다 — issue 또는 autoharness.aha@gmail.com 로 연락해 주세요.

📄 라이선스

MIT. 자세한 내용은 LICENSE를 참고하세요.