또는: 월 0달러의 자율형 AI 사서(librarian)를 구축하며 배운 프로덕션 환경에서의 LLM 에이전트 운영법.

나의 문서 위키(documentation wiki)가 부식되고 있었다. 극적으로는 아니었지만, 태그가 없는 페이지, 잘못된 선반에 분류된 도서, 중복된 제목, 템플릿에서 복사해 온 오래된 메타데이터 블록 등 일반적인 엔트로피(entropy) 현상이 나타나고 있었다. 나는 거버넌스(governance) 규칙을 작성했다. 하지만 아무도 이를 집행하지 않았다. 유일하게 이용 가능한 "주체"는 밤 11시의 나뿐이었기 때문이다.

그래서 이를 수행할 자율형 에이전트(autonomous agent)를 구축했다. 결과적으로 두 번 만들게 되었다.

버전 1: 프레임워크 반사 (the framework reflex)

첫 번째 버전은 대부분의 엔지니어가 2026년에 만들 법한 형태였다: 바로 Python 서비스였다. 기계적인 체크를 위한 규칙 엔진(rule engine), 판단을 위한 LLM API 호출, 수정을 적용하기 위한 실행 모듈(executor module), SDK 래퍼(wrapper), 재시도 로직(retry logic) 등을 갖추었다. 약 1,000줄 정도의 코드였다.

작동은 했다. 하지만 다음과 같은 문제도 있었다:

• 범위가 잘못 설정된 규칙 하나가 사전 필터링 없이 모든 페이지를 모델로 보내버리는 바람에 실행당 약 $0.70의 비용이 발생했다.
• 첫 실전 운영 밤에 API 크레딧이 소진되어 스캔 도중에 중단되었다.
• 내가 직접 작성해서 신뢰했던 내부 구조(plumbing) 속에 두 개의 실제 통합 버그(도구 호출을 조용히 아무 작업도 하지 않게 만드는 스킵된 프로토콜 핸드셰이크)를 숨기고 있었다.

나는 배포한 당일 바로 이를 폐기했다.

버전 2: 프롬프트가 곧 프로그램이다 (the prompt is the program)

깨달은 점은 이것이다: 에이전트형 CLI(나는 Claude Code를 사용하지만, 그 형태는 일반화될 수 있다)는 이미 규칙 엔진, 도구 실행기(tool executor), 재시도 루프, 그리고 판단 모듈의 역할을 수행하고 있다는 것이다. 나는 내가 돈을 지불하고 있는 서비스를, 더 나쁜 방식으로 재구축하고 있었던 셈이다.

버전 2는 Kubernetes CronJob이다. 컨테이너에는 CLI가 설치되어 있다. 엔트리포인트(entrypoint)는 약 50줄의 셸(shell) 스크립트다: ConfigMap에서 프롬프트를 로드하고, 내 위키의 API를 도구(tools)로 노출하는 MCP 서버를 CLI가 가리키도록 설정한 뒤, 헤드리스(headless)로 실행하고, 요약 내용을 내 채팅 채널에 게시한다. 약 500단어 정도의 프롬프트가 바로 큐레이터 로직(curator logic) 그 자체다.

CronJob (매주 일요일 04:00)
  └─ agent pod (실행 시마다 새로 생성)
       ├─ agentic CLI + auth
...

종량제 API 키 대신 제가 이미 비용을 지불하고 있는 구독 서비스를 통해 인증하기 때문에, 실행당 한계 비용(marginal cost)은 0입니다. 이것은 단순한 회계상의 각주가 아니라, 아키텍처를 변화시킨 핵심 요소입니다. 실행 비용이 무료라면, 증분 상태(incremental-state) 메커니즘을 구축하는 대신 매주 모든 것을 다시 스캔할 여유가 생깁니다. v1 코드의 절반은 API 비용을 피하기 위해 존재했습니다.

그리고 프롬프트 기반 버전은 Python 버전보다 더 많은 실제 문제를 발견하며, 더 나은 판단력을 보여줍니다. 예를 들어, 중복될 뻔한 제목을 맹목적으로 "수정"하는 대신, 사람이 검토할 수 있도록 플래그(flag)를 지정합니다.

실제로 중요한 부분: 에이전트가 직접 수정하게 하기

LLM에 중요한 시스템에 대한 쓰기 권한(write access)을 부여하는 것이 핵심 질문입니다. 권한 설정만으로는 이 질문에 답할 수 없습니다. 세 가지 설계 선택이 그 역할을 수행했습니다.

1. 단일 경로가 아닌 두 개의 경로. 모든 발견 사항은 분류됩니다: Tier 1 (기계적으로 명백함 — 자동 수정) 또는 Tier 2 (판단 필요 — 사람에게 제안, 아무것도 건드리지 않음). 태그 케이스 정규화(Tag-case normalization)는 Tier 1입니다. "이 페이지는 다른 책에 속할 수도 있습니다"는 영원히 Tier 2입니다. 누군가의 콘텐츠를 이동시키는 것은 당신이 옳더라도 파괴적인 영향을 줄 수 있기 때문입니다.

2. 에이전트가 스스로를 대상으로 실행하는 편집-검토 게이트(edit-review gate). 어떠한 쓰기 작업이라도 수행하기 전에, 프롬프트는 에이전트가 정확한 변경 사항을 명시하고 다음과 같이 질문하도록 요구합니다: "합리적인 관리자라면 이에 반대할 수도 있을까요?" 만약 '예'라고 답하거나 그에 근접한 경우, 해당 항목은 이유와 함께 제안(propose) 경로로 강등됩니다. 이 편향(bias)은 명시적입니다. 잘못된 자동 수정은 일주일치 백로그(backlog)가 쌓이는 것보다 더 큰 비용을 초래합니다. 수개월간의 매주 실행 결과, 회귀(regression)는 0건이었습니다.

3. 일급 의존성(first-class dependency)으로서의 실행 취소(Undo). 위키는 전체 페이지의 수정 이력(revision history)을 보관하므로, 모든 에이전트의 수정 사항은 클릭 한 번으로 되돌릴 수 있습니다. 저는 네이티브 버전 관리 기능이 없는 시스템에는 이 패턴을 적용하지 않을 것입니다. 자율성을 안전하게 만드는 것은 권한 범위(permission scoping)가 아니라 가역성(reversibility)입니다.

자리를 잡게 만든 또 하나의 습관은 에이전트가 시작하기 전에 자신의 이전 보고서를 읽는 것입니다. 따라서 모든 요약에는 추세선이 포함됩니다 — "검토 대기 중인 항목 12개, 지난 실행 시 14개였음, 순 변화 -2." 스냅샷은 아무것도 알려주지 않지만, 미분값(derivative)은 시스템이 회복되고 있는지 여부를 알려줍니다.

일반화할 수 있는 교훈들

1. 프레임워크를 삭제하세요. 만약 에이전트 코드가 대부분 오케스트레이션(orchestration) — 라우팅(routing), 재시도(retries), 도구 디스패치(tool dispatch) — 로 이루어져 있다면, 당신은 하네스(harness)를 재구축한 것에 불과합니다. 대신 프롬프트(prompt)와 스케줄(schedule)을 배포하세요. 제 코드는 약 1,000줄에서 50줄 남짓과 500단어의 영어로 줄어들었습니다.
2. 프롬프트는 코드입니다. 큐레이터 프롬프트는 git에 저장되고, 다른 모든 것과 동일한 차트(chart)를 통해 배포되며, 모듈(module)처럼 리뷰를 받습니다. 왜냐하면 그것이 바로 모듈이기 때문입니다.
3. 에이전트에게 허용 목록(allowlist)뿐만 아니라 실행 취소(undo) 기능을 부여하세요. 범위가 제한된 자격 증명(scoped credentials)은 폭발 반경(blast radius)을 제한하지만, 버전 관리되는 대상(versioned targets)은 실수의 비용을 낮춥니다. 둘 다 필요하지만, 하나만 골라야 한다면 저는 실행 취소를 선택하겠습니다.
4. 에이전트가 각 쓰기(write) 작업에 대해 방어하게 만드세요. 스스로 적용하는 "메인테이너(maintainer)가 반대할 것인가?"라는 게이트(gate)는 약하게 들릴 수 있습니다. 하지만 경험적으로 이는 매주 신뢰할 수 있는 에이전트와 계속 지켜봐야 하는(babysit) 에이전트 사이의 차이를 만듭니다.
5. 한계 비용(marginal cost)이 아키텍처를 결정합니다. 영리한 상태(state) 관리보다 비용이 들지 않는 재실행(re-runs)이 더 낫습니다. 에이전트를 최적화하기 전에, 복잡성을 강제했던 경제적 요인이 여전히 존재하는지 확인하세요.

이제 동일한 골격이 제 클러스터(cluster) 내의 다른 작업들을 수행합니다 — 프롬프트는 다르지만, 동일한 이미지, 동일한 MCP 도구, 동일한 보고서-대화(report-to-chat) 패턴을 사용합니다. 각각의 새로운 에이전트는 코드베이스의 변경이 아니라 설정(config)의 변경입니다.

참고로, 위키(wiki)는 깨끗합니다. 사서(librarian)는 잠을 자지도 않고, 지루해하지도 않으며, v1과는 달리 저에게 단 한 번도 비용을 청구하지 않았습니다.

저는 AI 네이티브(AI-native), 셀프 호스팅(self-hosted) IT 자동화에 관한 시리즈를 작성하고 있습니다: 여러분이 소유한 인프라에서 LLM 에이전트를 프로덕션 환경에서 — 안전하고, 저렴하며, SaaS 비용 없이 — 실행하는 방법입니다. 이것이 여러분이 해결하고자 하는 문제라면 계속 지켜봐 주세요.