12-Factor Agents — 신뢰할 수 있는 LLM 애플리케이션 설계
HumanLayer의 에이전트 설계 가이드. “프롬프트 + 툴 루프”보다 소프트웨어 설계를 먼저 보라는 메시지를 12개 원칙으로 정리한다.
개요
이 저장소는 LLM-powered software를 프로덕션 고객용으로 충분히 신뢰할 수 있게 만들기 위한 설계 원칙을 정리한 가이드다. 핵심 메시지는 에이전트를 거대한 프레임워크로 감싸기보다, 상태·제어 흐름·프롬프트·툴 결과를 애플리케이션 소프트웨어의 일부로 명시적으로 소유하라는 것이다. ^[raw/articles/github-humanlayer-12-factor-agents.md]
문서의 중심 축은 12가지 팩터다. 자연어를 툴 호출로 바꾸는 법, 프롬프트와 컨텍스트 윈도우를 소유하는 법, 툴 출력과 실행 상태를 구조화하는 법, launch/pause/resume API, human-in-the-loop 개입, 작은 에이전트로 나누기, 그리고 stateless reducer로 동작시키는 방식까지 포함한다. ^[raw/articles/github-humanlayer-12-factor-agents.md]
왜 중요한가
- 에이전트 설계를 “모델 능력”보다 “운영 가능한 소프트웨어” 관점으로 바꾼다.
- 컨텍스트 관리, 에러 압축, 상태 분리, 인간 개입 같은 실제 실패 지점을 정면으로 다룬다.
- Claude Code, Codex, OpenCode 같은 코딩 에이전트뿐 아니라 일반적인 제품형 LLM 앱 설계에도 그대로 적용된다.
저장소 포인트
- TypeScript 기반이며 템플릿 생성 경로
npx/uvx create-12-factor-agent를 제공한다. ^[raw/articles/github-humanlayer-12-factor-agents.md] - GitHub Topics는 framework, ai, memory, orchestration, agents, prompt-engineering, llms, context-window를 포함한다. ^[raw/articles/github-humanlayer-12-factor-agents.md]
- 릴리스 페이지 기준으로는 현재 공개 release가 없다.