도구 설계 베스트 프랙티스 — 에이전트를 똑똑해 보이게 만드는 건 모델이 아니라 Tool Spec이다

시리즈 3편. 1편 하네스 엔지니어링 입문 · 2편 평가 하네스 구축 가이드에 이어, 이번 글은 하네스의 가장 실용적인 구성 요소 — 도구(Tools) 를 다룹니다.

들어가며: 같은 모델, 다른 결과

같은 Claude Opus 4.6을 쓰는 두 팀이 있습니다. A팀의 에이전트는 복잡한 리팩터링을 척척 해내고, B팀의 에이전트는 파일 경로 하나 못 찾아 헤맵니다. 차이는 모델이 아니라 도구에 있습니다.

에이전트 개발자들이 가장 흔히 하는 착각은 "LLM이 똑똑하니까 도구는 대충 만들어도 알아서 쓸 것"이라는 생각입니다. 현실은 정반대입니다. 좋은 도구는 모호한 추론 문제를 결정적인 함수 호출로 바꿉니다. 나쁜 도구는 세상에서 가장 똑똑한 모델조차 바보로 만듭니다.

도구 설계의 원칙: 에이전트에게 "뭘 할 수 있는지"가 아니라 "어떻게 성공하는지"를 가르쳐라.

---

좋은 도구의 5가지 원칙

1️⃣ 명확한 계약 (Clear Contract)

도구의 이름, 설명, 파라미터 타입, 반환 값이 그 자체로 사용 설명서가 되어야 합니다. 에이전트는 사람처럼 직관으로 채워 넣지 않습니다 — 문서에 없으면 모릅니다.

# ❌ 나쁜 예: 모호한 이름, 타입 없음, 무엇이 돌아오는지 불명
def run(cmd):
    """Run a command."""
    return os.system(cmd)

# ✅ 좋은 예: 의도가 드러나는 이름, 명시적 타입, 구조화된 반환
def search_files(
    pattern: str,
    directory: str = "/workspace",
    max_results: int = 50
) -> SearchResult:
    """파일 내용에서 정규식 패턴을 검색합니다.
    
    Args:
        pattern: Python re 모듈 문법의 정규식
        directory: 검색 시작 디렉터리 (기본: /workspace)
        max_results: 반환할 최대 매치 수
    
    Returns:
        SearchResult(matches: list[Match], truncated: bool)
    """

2️⃣ 친절한 에러 메시지 (Informative Errors)

에러는 디버깅의 시작점이 아니라 수정 가이드여야 합니다. 에이전트는 에러 메시지를 읽고 다음 행동을 결정합니다.

상황	❌ 나쁜 에러	✅ 좋은 에러
파일 없음	FileNotFoundError	File not found: /x/config.yml. Did you mean /x/config.yaml? (3 similar files in directory)
권한 부족	PermissionError: [Errno 13]	Cannot write to /etc/hosts. This path is outside the sandbox. Allowed paths: /workspace, /tmp
잘못된 인자	TypeError: expected int	Parameter 'timeout' must be int (seconds), got str "30s". Try: timeout=30

 

핵심: 에러 메시지에는 항상 "그래서 뭘 하면 되는지"가 들어 있어야 합니다.

3️⃣ 적절한 추상화 수준 (Right Granularity)

도구는 너무 저수준이면 에이전트가 매번 복잡한 시퀀스를 조립해야 하고, 너무 고수준이면 유연성이 사라집니다.

❌ 너무 저수준: open_file, read_bytes(1024), decode_utf8, close_file
✅ 적절한 수준: read_file(path) -> str

❌ 너무 고수준: fix_all_bugs(repo)
✅ 적절한 수준: run_tests(), edit_file(), search_code()

 

경험칙: 숙련된 주니어 개발자가 한 번의 지시로 수행할 수 있는 단위가 적절한 도구 크기입니다.

4️⃣ 멱등성 (Idempotency)

가능한 경우 같은 입력 → 같은 결과가 되도록 설계하세요. 에이전트는 재시도가 잦습니다.

# ❌ 비멱등: 매번 새 파일 생성
def create_log_file() -> str:
    path = f"/logs/{uuid4()}.log"
    open(path, 'w').close()
    return path

# ✅ 멱등: 같은 key로 호출하면 같은 결과
def get_or_create_log_file(key: str) -> str:
    path = f"/logs/{key}.log"
    if not os.path.exists(path):
        open(path, 'w').close()
    return path

5️⃣ 관측 가능성 (Observability)

도구 호출은 트레이스에 남는 이벤트입니다. 디버깅 가능한 로그를 자연스럽게 남기도록 설계하세요.

• 호출 전후의 상태 diff를 기록
• 실패 시 재현 가능한 입력 덤프
• 실행 시간과 리소스 사용량

---

Tool Spec 작성 체크리스트

도구 하나를 만들 때마다 다음을 점검하세요.

□ 이름이 동사-명사 형태이고 의도가 분명한가?
□ docstring만 읽고 파라미터를 채울 수 있는가?
□ 모든 파라미터에 타입 힌트가 있는가?
□ 선택적 파라미터에 합리적 기본값이 있는가?
□ 반환 타입이 구조화되어 있는가? (dict가 아니라 TypedDict/dataclass)
□ 모든 에러 경로에 수정 가이드가 들어 있는가?
□ 같은 입력으로 두 번 호출해도 안전한가?
□ 파괴적 작업(삭제/쓰기)은 확인 플래그가 필요한가?
□ 실제 에이전트에게 "이 도구로 X를 해봐"라고 시켜봤는가?

 

마지막 항목이 가장 중요합니다. Tool spec은 실제 에이전트로 드라이브 테스트하기 전까지는 완성된 게 아닙니다.

---

안티패턴 갤러리: 피해야 할 도구 설계

🚫 안티패턴 1: "마법의 도구"

def smart_refactor(code: str) -> str:
    """Intelligently refactor code."""

"Intelligent"가 들어가는 순간 의심하세요. 도구가 해야 할 일이 불명확할 때 쓰는 단어입니다. 대신 extract_function, rename_symbol, inline_variable처럼 구체적인 리팩터링 액션으로 쪼개세요.

🚫 안티패턴 2: "문자열 블롭 반환"

def get_file_info(path: str) -> str:
    return f"File: {path}\nSize: {size}\nModified: {mtime}\n..."

에이전트가 다시 파싱해야 합니다. 구조화된 객체를 반환하세요.

🚫 안티패턴 3: "조용한 실패"

def delete_file(path: str) -> bool:
    try:
        os.remove(path)
        return True
    except:
        return False

왜 실패했는지 모르면 수정할 수 없습니다. 예외는 삼키지 말고 구조화해서 돌려주세요.

🚫 안티패턴 4: "30개의 파라미터"

def run_command(cmd, cwd, env, timeout, shell, stdin, stdout, 
                stderr, encoding, errors, universal_newlines, ...):

파라미터가 10개를 넘으면 도구를 쪼개거나, 설정 객체로 감싸세요. 에이전트는 보이는 모든 파라미터를 채우려는 경향이 있어 불필요한 인지 부하가 생깁니다.

🚫 안티패턴 5: "돌이킬 수 없는 부작용이 기본값"

def deploy(service: str, force: bool = True):  # ← force가 기본 True

파괴적 동작은 명시적으로 요청할 때만 일어나야 합니다. 기본값은 항상 안전한 쪽으로.

---

실전: 나쁜 도구 → 좋은 도구로 리팩터링

Before — 전형적인 "대충 만든" 도구:

def db_query(q):
    """Run a database query."""
    return db.execute(q).fetchall()

문제점: SQL 인젝션 위험, 에러 처리 없음, 반환 포맷 불명, 대용량 결과에 대한 방어 없음.

 

After — 하네스 관점에서 다시 설계:

def query_users(
    filter_by: Literal["email", "id", "status"],
    value: str,
    limit: int = 100
) -> QueryResult:
    """users 테이블을 안전하게 조회합니다.
    
    파괴적 작업(INSERT/UPDATE/DELETE)은 불가능합니다.
    필요한 경우 modify_users 도구를 사용하세요.
    """
    if limit > 1000:
        return QueryResult(
            error="limit cannot exceed 1000. Use pagination with cursor parameter.",
            suggestion="query_users(filter_by=..., value=..., limit=1000, cursor=...)"
        )
    try:
        rows = db.execute(
            "SELECT id, email, status FROM users WHERE {} = %s LIMIT %s".format(filter_by),
            (value, limit)
        ).fetchall()
        return QueryResult(rows=rows, count=len(rows), truncated=len(rows) == limit)
    except DatabaseError as e:
        return QueryResult(
            error=f"Query failed: {e}",
            suggestion="Check if the users table exists and filter_by column is indexed."
        )

 

변화의 본질: 제약(SELECT만 허용, limit 상한), 명확한 계약(구조화된 반환), 친절한 에러(suggestion 포함) — 1편의 하네스 원칙 그대로입니다.

---

마치며: Tool Spec은 프롬프트의 연장이다

많은 팀이 프롬프트 엔지니어링에 시간의 90%를 쓰고, 도구 설계에 10%를 씁니다. 성숙한 팀은 정반대입니다.

그 이유는 간단합니다. 프롬프트는 에이전트에게 "무엇을 하라"고 말하지만, 도구는 "어떻게 할 수 있는지"를 정의합니다. 좋은 도구 위에서는 짧은 프롬프트로도 에이전트가 똑바로 움직이고, 나쁜 도구 위에서는 아무리 정교한 프롬프트도 실패를 막을 수 없습니다.

"에이전트가 멍청해 보인다면, 먼저 의심해야 할 건 모델이 아니라 당신이 만든 도구다."

 

이로써 하네스 엔지니어링 3부작을 마칩니다. 1편에서 큰 그림을 그리고, 2편에서 측정 체계를 세우고, 3편에서 가장 실용적인 레버인 도구 설계를 다뤘습니다. 세 편 모두 한 문장으로 요약하면 이렇습니다.

"에이전트를 더 똑똑하게 만들려 하지 말고, 그 주변을 더 단단하게 만들어라."

 

다음 시리즈에서는 실전 케이스 스터디 — Claude Code, Devin, Cursor가 각자 어떤 하네스 패턴을 선택했는지 비교 분석 — 로 찾아뵙겠습니다.

---

#AI에이전트 #ToolDesign #LLMOps #AgentInfrastructure #하네스엔지니어링