Agent Harness의 3가지 핵심 축

세 축의 개요

Agent Harness는 세 가지 핵심 축으로 구성됩니다. 이 세 축은 에이전트 시스템이 장기적으로 안정적이고 효과적으로 작동하기 위한 기반입니다.

축	핵심 질문	없을 때 증상
Context Engineering	에이전트에게 무엇을 언제 알려주는가?	잘못된 결정, 반복 실수
Architectural Constraints	에이전트가 무엇을 할 수 없게 막는가?	예측 불가능한 행동, 보안 사고
Entropy Management	시스템이 어떻게 질서를 유지하는가?	점진적 품질 저하, 기술 부채 누적

축 1: Context Engineering

정의

Context Engineering은 에이전트의 컨텍스트 윈도우에 올바른 정보를 올바른 형태로 올바른 시점에 제공하는 기술입니다.

에이전트는 컨텍스트 윈도우 안의 정보만으로 판단합니다. 필요한 정보가 없으면 틀린 결정을 내리고, 불필요한 정보가 많으면 중요한 내용을 놓칩니다.

네 가지 전략

Write    → 에이전트가 기억해야 할 정보를 명시적으로 기록
Select   → 현재 태스크와 관련된 정보만 선택적으로 주입
Compress → 긴 히스토리를 요약하여 토큰 효율 확보
Isolate  → 서브태스크를 별도 컨텍스트로 격리

코드 예시

class ContextManager:
    def build_context(self, task: str, history: list) -> str:
        # Select: 관련 파일만 포함
        relevant_files = self.select_relevant(task)
        # Compress: 히스토리 요약
        summary = self.compress_history(history)
        # Write: 현재 상태 명시
        current_state = self.write_state()

        return f"""
## 현재 태스크
{task}

## 관련 컨텍스트
{relevant_files}

## 이전 진행 상황
{summary}

## 현재 상태
{current_state}
"""

축 2: Architectural Constraints

정의

Architectural Constraints는 에이전트가 특정 행동을 할 수 없도록 시스템 수준에서 강제하는 구조적 제약입니다. “하지 말라”는 지시가 아니라, 물리적으로 불가능하게 만드는 것이 핵심입니다.

세 가지 제약 유형

1. 린터와 정적 분석

에이전트가 생성한 코드가 컨벤션을 벗어나면 자동으로 차단합니다.

repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    hooks:
      - id: ruff
      - id: ruff-format
  - repo: https://github.com/pre-commit/mirrors-mypy
    hooks:
      - id: mypy

2. 구조적 테스트

의존성 레이어링, 모듈 경계 등 아키텍처 규칙을 테스트로 강제합니다.

# 아키텍처 경계 테스트
def test_domain_has_no_infrastructure_dependency():
    """domain 레이어는 infra 레이어를 import하면 안 된다"""
    imports = get_all_imports("src/domain/")
    infra_imports = [i for i in imports if "infra" in i]
    assert len(infra_imports) == 0, f"위반: {infra_imports}"

3. 권한 시스템

에이전트가 사용할 수 있는 도구와 작업을 스키마 수준에서 제한합니다.

ALLOWED_TOOLS = {
    "plan_mode": ["read_file", "search_code", "list_directory"],
    "execute_mode": ["read_file", "write_file", "run_command", "search_code"],
}

def get_tools_for_mode(mode: str) -> list:
    return ALLOWED_TOOLS.get(mode, [])

축 3: Entropy Management

정의

소프트웨어 시스템은 시간이 지날수록 자연스럽게 복잡성이 증가하고 질서가 무너집니다. AI 에이전트가 코드를 생성하는 시스템에서 이 현상은 더 빠르게 진행됩니다. Entropy Management는 이 자연적 무질서 증가를 주기적으로 역전시키는 전략입니다.

엔트로피 원인

원인	예시
에이전트의 즉흥적 해결책	임시 방편 코드가 영구 코드로 정착
컨텍스트 누적	오래된 결정 사항이 현재 판단을 오염
도구 버전 드리프트	의존성이 조금씩 충돌
문서-코드 불일치	README가 실제 동작과 달라짐

주기적 정리 에이전트

class EntropyCleanupAgent:
    """주기적으로 실행되어 시스템 엔트로피를 감소시키는 에이전트"""

    def run_weekly_cleanup(self):
        tasks = [
            self.remove_dead_code(),
            self.update_stale_comments(),
            self.consolidate_duplicate_logic(),
            self.refresh_dependency_versions(),
            self.sync_docs_with_code(),
        ]
        return self.execute_all(tasks)

세 축의 상호작용

세 축은 독립적이지 않습니다. 서로를 강화합니다.

Context Engineering  →  에이전트가 올바른 정보로 판단
        ↓
Architectural Constraints  →  잘못된 판단도 실행 전 차단
        ↓
Entropy Management  →  시스템이 장기적으로 올바른 상태 유지
        ↑_______________________________________↑

Context가 좋아도 제약이 없으면 위험한 행동이 가능합니다. 제약이 좋아도 컨텍스트가 나쁘면 에이전트가 제약 안에서 잘못된 행동을 반복합니다. 엔트로피 관리가 없으면 두 축 모두 시간이 지나면서 효력을 잃습니다.

요약

세 가지 핵심 축 — Context Engineering, Architectural Constraints, Entropy Management — 은 Agent Harness의 뼈대입니다. 이후 챕터들은 이 세 축을 각기 다른 관점에서 심화합니다. 특히 Section 03(Context Engineering)과 Section 05(Guardrails)에서 첫 번째와 두 번째 축을 깊이 다룹니다.