Claude Code가 사용하는 아키텍처 패턴으로 AI 에이전트 구축하기

프레임워크 없이, 직접 역설계할 필요 없이 Claude Code가 사용하는 것과 동일한 아키텍처 패턴으로 AI 에이전트를 구축하세요.

이 레포지토리는 프로덕션 체크리스트, 6가지 작동 예제, 그리고 30분 만에 클론하여 자신의 도메인에 맞게 조정할 수 있는 실행 가능한 Python 에이전트를 제공합니다.

AI 코딩 에이전트에게 '나를 위한 에이전트를 구축해 줘'라고 요청하면, API를 한 번 호출하고 답변을 출력하는 스크립트를 받습니다. 이것은 에이전트가 아닙니다. 이는 래퍼(wrapper)일 뿐입니다.

Claude Code와 같은 프로덕션급 에이전트는 근본적으로 다른 아키텍처를 사용합니다: 컨트롤러 루프(controller loop), 스키마를 가진 도구 계약(tool contracts with schemas), 런타임 권한 강제화(runtime permission enforcement), 압축을 포함하는 세션 상태(session state with compaction), 안전성, 관측 가능성(observability), 평가를 위한 후크 파이프라인(hook pipelines).

이러한 패턴들을 배우기 위해 프로덕션 코드를 연구할 필요가 없습니다. 이 스킬은 이러한 패턴들을 패키징하여 여러분의 코딩 에이전트가 자동으로 프로덕션급 디자인을 생성하도록 합니다.

git clone https://github.com/xuanhieu2611/build-your-own-agents-skill.git
cd build-your-own-agents-skill/examples/marketing-agent
pip install -r requirements.txt
...

마케팅 에이전트는 트렌드 가져오기, 캠페인 브리프 읽기, 게시물 초안 작성, 게재 전 승인 요청, 그리고 모든 단계를 기록하는 루프를 반복하며 — 이는 프로덕션 코딩 에이전트를 구동하는 것과 동일한 루프 아키텍처입니다.

저는 Claude Code의 에이전트 하네스(agent harness)가 어떻게 작동하는지 — 모델이 아닌 런타임 측면에서 — 연구하고, 이를 신뢰할 수 있게 만드는 지속 가능한 아키텍처 패턴들을 추출했습니다:

컨트롤러 루프 (Controller loop): 모델이 제안하고, 런타임이 검증하며, 실행하고, 관찰하고, 반복합니다. 툴 계약 (Tool contracts): JSON Schema 입력, 선언된 권한 수준, 타임아웃, 부작용(side effects)을 정의합니다. 권한 파이프라인 (Permission pipeline): 툴 호출 전후에 허용(allow), 거부(deny), 수정(modify), 또는 주석 처리(annotate)할 수 있는 PreToolUse / PostToolUse 후크를 제공합니다. 권한 모드 (Permission modes): ReadOnly, WorkspaceWrite, DangerFullAccess가 있습니다 — 각 툴은 필요한 것을 선언하고, 런타임이 이를 강제합니다. 세션 압축 (Session compaction): 컨텍스트가 임계값을 초과하면, 오래된 기록은 요약되고 최근의 대화 내용은 전체적으로 보존됩니다. 구조화된 이벤트 (Structured events): 모든 모델의 응답(turn)은 유형이 지정된 이벤트(text, tool_use, usage, cache, stop)를 생성하며, 런타임이 이를 검사하고 조치할 수 있습니다.

이것들은 이론적인 패턴이 아닙니다. 이것들이 수백만 명의 사람이 실제로 사용하는 프로덕션 에이전트가 작동하는 방식입니다.

1단계 — 설계 (Design). 스킬을 설치하고 코딩 에이전트에게 해당 도메인에 대한 에이전트를 설계하도록 요청합니다. 이 스킬은 모든 프로덕션 관련 문제를 자동으로 처리할 것을 보장합니다.

2단계 — 골격화 (Scaffold). 스캐폴더(scaffolder) 스킬을 사용하여 설계 명세(design spec)를 컨트롤러 루프, 툴 스텁, 권한, 상태 및 관찰 가능성 등을 갖춘 구조화된 Python 프로젝트로 변환합니다.

3단계 — 구축 (Build). 모의 툴 실행기(mock tool executors)를 실제 통합 기능으로 교체합니다. 아키텍처는 동일하게 유지됩니다.

skills/production-agent-architecture/ 폴더를 프로젝트의 .cursor/skills/production-agent-architecture/에 복사하세요.

동일한 폴더를 툴이 지원하는 스킬 또는 프롬프트 라이브러리 디렉터리에 복사하거나, 빌드 프롬프트에 마크다운 파일을 직접 첨부하세요.

스킬을 설치한 후, 코딩 에이전트에게 다음 내용을 제공합니다:

Use the production-agent-architecture skill.
Design a production-ready AI agent for [your domain].
Do not return a one-shot chatbot design.
...

이 스킬로 구축된 모든 에이전트는 프로덕션 코딩 에이전트가 사용하는 동일한 루프 패턴을 따릅니다:

flowchart TD
UserGoal[사용자 목표] --> ContextBuilder[컨텍스트 빌더]
ContextBuilder --> ModelTurn[모델 턴]
...

여기서 시작하기 (Start here):

심층 분석 (Deep dives):

저는 실제 심각한 수준의 에이전트 시스템이 어떻게 작동하는지 이해하고 싶어서 Claude Code 에이전트 하니스(harness)를 깊이 연구했습니다. 여기에는 컨트롤러 루프, 도구 레지스트리, 권한 파이프라인, 세션 시스템, 훅 아키텍처가 포함됩니다.

이 지식의 대부분은 독점 코드베이스에 잠겨 있습니다. 이 저장소는 지속 가능한(durable) 아키텍처 패턴을 추출하여 모두에게 제공함으로써, 여러분이 몇 주 동안 배관 구조를 파악하는 데 시간을 낭비하지 않고도 자체 도메인용 프로덕션 등급 에이전트를 구축할 수 있도록 합니다.

본 저장소는 Claude Code와 같은 최신 코딩 에이전트에서 관찰된 아키텍처 패턴에서 영감을 받았습니다. 이는 Anthropic과 제휴하지 않은 독립적인 작업물이며, 실용적인 빌드 가이드로 의도되었습니다. 이 저장소에는 독점 소스 코드가 포함되어 있지 않습니다.

CONTRIBUTING.md를 참조하세요

. 좋은 기여: 더 나은 예제, 더 강력한 스킬 출력(skill outputs), 더 명확한 문서화, 더 현실적인 프로덕션 가이드라인.

MIT 라이선스. LICENSE를 참조하세요.