12-팩터 에이전트

실제 서비스에서 버티는 LLM 에이전트를 만들기 위한 12가지 설계 원칙이다. 프레임워크로 만든 에이전트가 80% 품질에서 더 나아지지 않을 때, 잘 만든 소프트웨어에 LLM을 필요한 곳에만 끼워 넣는 구조로 바꿔 프롬프트·상태·제어 흐름을 직접 관리하려고 쓴다.

HumanLayer의 Dex Horthy가 AI 엔지니어 100명 이상을 인터뷰한 뒤, 프로덕션에 나간 에이전트들의 공통점을 정리했다. 이름은 Heroku의 Twelve-Factor App에서 따왔다.

80%에서 막히는 문제를 풀려고 나왔다

에이전트 프레임워크를 쓰면 처음에는 금방 70~80% 품질까지 간다. 그런데 그 뒤로는 에이전트가 없는 단계를 지어내거나 무한 루프에 빠지고, 남은 부분을 고치려면 프레임워크 내부를 뜯어봐야 한다. 12-팩터는 이 부분을 처음부터 내 코드로 가져와 고치고 디버깅할 수 있게 하자는 제안이다.

12가지는 세 묶음으로 보면 쉽다

적용은 작은 에이전트 하나부터

기존 에이전트를 통째로 갈아엎을 필요는 없다. 먼저 한 가지 일만 하는 작은 에이전트로 나누고, 프롬프트를 코드 저장소에 직접 두어 바꿀 때마다 결과를 비교한다. 그다음 진행 기록을 이벤트 목록으로 저장해 중간에 멈췄다 이어 가게 만들고, 승인이 필요한 단계는 사람에게 묻는 도구로 넣는다.

Claude Code라면 CLAUDE.md에 지시를 직접 쓰는 것이 프롬프트 소유이고, 훅으로 파일 수정 뒤 린트를 강제하는 것이 제어 흐름 소유다. 역할별로 나눈 서브에이전트는 작고 집중된 에이전트에 해당한다.

프레임워크를 버리라는 뜻은 아니다

12-팩터는 SDK가 아니라 언어와 상관없는 설계 원칙이다. LangChain이나 CrewAI를 쓰고 있어도 프롬프트·상태·루프를 내가 들여다볼 수 있게 꺼내 두면 된다. 짧은 실험이나 혼자 쓰는 스크립트라면 원칙을 다 지킬 필요는 없다. 사용자에게 내보내 오래 돌릴 에이전트일수록 효과가 크다.

프로덕션 에이전트의 설계 점검표로 쓴다

사람들은 주로 새 에이전트를 설계하거나 데모 수준에서 멈춘 에이전트를 고칠 때, 12가지를 점검표처럼 하나씩 대조한다. 한 번에 다 적용하기보다 지금 가장 아픈 문제에 맞는 원칙부터 고른다.