AI 에이전트 이해 및 제작 방법

PART A — AI 에이전트 이해

AI 에이전트가 무엇인지 — 정의·구성·작동원리·분류를 정리한다.

PART A · 1

에이전트란

AI 에이전트는 목표를 받아 스스로 단계를 밟아 달성하는 자율 시스템이다.

ChatGPT에 "내일 회의록 정리해서 메일로 보내줘"라고 시켰을 때, 한 번 답하고 끝나면 챗봇이고, 알아서 캘린더 확인 → 회의록 작성 → 발송까지 다 마치면 에이전트다.

AI 에이전트 = LLM(두뇌)을 중심으로, 목표를 받아 스스로 인지·판단·행동하는 자율 시스템.

📚 권위 있는 정의 — 주요 출처는 어떻게 정의하나 (선택 참고)

처음엔 몰라도 된다. "공식 출처에서도 같은 표현을 쓰는가"가 궁금해질 때 참고.

출처정의
Anthropic
(Building Effective Agents, 2024)		LLM이 스스로 프로세스와 도구 사용을 동적으로 이끌며 작업 완수 방식을 통제하는 시스템
OpenAI
(Platform Docs · Agents, 2024)		사용자를 대신해 작업을 독립적으로 수행하는 시스템
Russell & Norvig
(AI 표준 교과서 Artificial Intelligence: A Modern Approach, 4판, 2020)		환경을 인지하고 행동하는 모든 것

LLM 에이전트의 5요소

본 가이드는 LLM(언어모델)을 두뇌로 쓰는 현재형 AI 에이전트를 다룬다. 이 범위의 에이전트는 아래 5요소를 표준적으로 갖춘다(학계에는 메모리를 옵션으로 두는 정의도 있다). (LLM이 없는 옛 소프트웨어형 에이전트, 즉 규칙·플래너·BDI 기반은 이 섹션 후반의 "유사 개념" 비교에서 별도로 다룬다.)

5요소는 본 가이드의 교육적 종합 프레임이며 산업 표준 단일 정의가 아니다. Anthropic의 "Building Effective Agents"는 LLM+Tools+Loop 중심, Russell & Norvig는 PEAS(Performance·Environment·Actuators·Sensors), Lilian Weng은 4요소(LLM·memory·planning·tools)로 각각 정리한다.

LLM(두뇌)

추론·계획·판단의 핵심 엔진. 사람의 뇌에 해당. 없으면 판단하는 두뇌가 없어 정해진 코드만 실행하는 자동화 스크립트가 된다.

자율 루프

사람이 매 단계를 시키지 않아도 목표 달성까지 스스로 도는 반복 절차. 없으면 한 번 답하고 멈추는 챗봇이 된다.

메모리

작업 상태와 지식을 기억(단기·장기). 기억력에 해당. 없으면 직전에 무엇을 했는지 모르고 루프가 제자리걸음한다.

도구

외부에 실제 영향을 미치는 수단(파일·API·DB·셸). 손발에 해당. 없으면 텍스트만 출력할 뿐 실제 세상을 바꾸지 못한다.

목표

무엇을 이룰 것인가 — 방향과 종료 기준. 목적에 해당. 없으면 언제 멈춰야 할지 몰라 영원히 돈다.

🔗 5요소가 루프 안에서 어떻게 맞물리나 (선택 참고)

5요소는 자율 루프 안에서 서로 맞물려 작동한다. 루프의 ②계획·③판단·⑤평가는 LLM(두뇌)이 사고로 수행하고, ①관찰 단계에서 에이전트는 메모리에서 직전 기록을 꺼내 입력에 더하며, ④실행에서 도구를 호출하고, ⑤평가에서 LLM이 결과를 목표와 대조한다.

1) LLM(두뇌) — 추론·계획·판단의 엔진

에이전트의 두뇌 역할. 텍스트를 입력받아 다음에 무엇을 할지 결정한다. 자율 루프(①관찰→②계획→③판단→④실행→⑤평가, 아래 2)에서 상세) 중 ②계획·③판단·⑤평가 세 단계가 모두 LLM의 사고로 이루어진다.

전통 자동화는 모든 분기를 if-else로 미리 박아두어야 한다. LLM은 맥락을 읽고 그 자리에서 다음 행동을 골라낸다 — 새 상황이 와도 코드를 다시 작성할 필요 없이 자연어 지시로 대응한다.

2) 자율 루프 — 사람 지시 없이 도는 순환

"자율"의 핵심은 사람이 매 단계를 시키지 않아도 에이전트가 스스로 다음 행동을 골라 실행한다는 것. 아래 5단계가 목표 달성까지 반복된다.

① 관찰Observe
② 계획·추론Plan
③ 판단·결정Decide
④ 실행Act
⑤ 평가Evaluate
↩ ①로 복귀목표 미달 시
✓ 종료목표 달성 시
②계획과 ③판단의 차이 — 메일 답장 예시로 보기
  • ① 관찰 — 받은편지함에 미답장 메일 5통이 있음을 인지.
  • ② 계획 — "먼저 긴급 표시된 것부터 처리하고, 그다음 발신자별로 묶어 답장 초안을 만들자"고 전체 순서를 짜는 단계.
  • ③ 판단 — 짠 계획 중 "지금 당장 이 긴급 메일에 답장 도구를 호출할 것"이라고 다음 행동 하나를 고르는 단계.
  • ④ 실행 — 메일 도구를 호출해 답장 작성.
  • ⑤ 평가 — 5통 다 처리됐는지 확인. 안 됐으면 ①로 돌아감.

즉 ②는 "전체 청사진", ③은 "지금 한 발짝". 청사진이 있어도 매 단계 다음 행동은 따로 고른다.

3) 메모리 — 작업을 기억해 루프를 잇는다

메모리는 맥락(context)을 다음 단계로 넘기는 통로다. 10단계 작업에서 7단계를 마쳤다면 ① 무엇을 끝냈는지 ② 어떤 결정을 내렸는지 ③ 어떤 도구를 호출했는지가 메모리에 쌓여야 8단계로 이어진다. 이 맥락이 끊기면 8단계가 7단계 결과를 모른 채 새 작업이 되어, 같은 목표를 향해 가는 자율 루프 자체가 불가능해진다. 작동 시간 범위에 따라 단기·장기로 나뉜다.

구분다른 이름정체
단기 메모리대화창 안의 임시 기억
(개발자 용어: 컨텍스트 / context window)		지금 하고 있는 작업·대화 내용. 대화창을 닫으면 사라진다.
장기 메모리대화창 밖의 저장소
(컴퓨터 폴더·데이터베이스·클라우드 등)		대화창을 닫아도 남는 기억. 다음 대화에서 다시 꺼내 쓴다.

4) 도구 — 세상에 실제 영향을 미치는 손발

두뇌(LLM)는 텍스트만 출력하므로, 손발(도구) 없이는 "회의록을 메일로 보내라"고 결정해도 실제 메일을 보내지 못한다. 도구는 LLM의 결정을 현실 행동으로 옮기는 다리다.

5) 목표 — 어디로 가고 어디서 멈추는가

목표는 단순한 종료 조건이 아니라 에이전트의 행동 경계 그 자체다. 같은 "회의록을 정리해라"도 "한 페이지로 요약" vs "발언자별 발언록 작성"으로 목표를 다르게 설정하면, 에이전트가 선택하는 도구·소요 시간·결과물 형태가 모두 달라진다. 즉 목표의 해상도(얼마나 구체적인가)가 에이전트 행동의 품질을 결정한다.

에이전트의 주요 리스크 — 무엇을 조심해야 하는가

자율 루프가 강력한 만큼 잘못 작동했을 때의 위험도 크다. 입문 단계에서 알아둬야 할 4가지.

유사 개념과의 비교 — 에이전트와 어떻게 다른가

한 줄 판별법 — 자율 루프가 있으면 에이전트, 없으면 아니다. 워크플로우는 순서가 고정돼 있고, 챗봇은 루프가 없다.

유사 개념 5종 — 세 차원이 섞여 있음에 주의

아래 5개는 차원이 다르다 — ① 에이전트가 아닌 자동화(워크플로우·LLM 챗봇·RPA·봇), ② 에이전트의 상위 범주(에이전틱 AI), ③ 본 가이드의 "LLM 에이전트" 옆 계열(소프트웨어형 에이전트 — LLM 없는 옛 에이전트).

워크플로우

사람이 미리 짠 고정된 순서를 그대로 실행하는 자동화. 순서를 스스로 바꾸지 않는다.

용도

동일 작업이 매번 같은 순서로 반복될 때. "메일이 오면 → 슬랙에 알림 → 시트에 기록" 같은 정형 자동화.

대표 사례
  • Zapier — SaaS 간 트리거-액션 연결 (예: Gmail → Slack)
  • Apache Airflow — 데이터 파이프라인 DAG(한 방향으로만 흐르는 작업 순서도) 스케줄링
  • n8n — 오픈소스 워크플로우 자동화
에이전트와 차이

순서가 고정. 환경이 바뀌어도 같은 순서를 돈다. 에이전트는 순서 자체를 상황에 맞게 재계획한다.

LLM 챗봇

대화·단일 응답이 목적인 LLM. 한 번 답하면 거기서 멈춘다.

용도

정보 검색·번역·요약·간단한 질문 답변. 도구 호출이나 다단계 작업이 필요 없을 때.

대표 사례
  • ChatGPT 기본 채팅 (Agent 모드 OFF)
  • Claude.ai 일반 대화
  • Gemini 앱 단순 채팅
에이전트와 차이

자율 루프가 없다. 한 번 답하고 끝. 에이전트는 목표 달성까지 인지→행동을 스스로 반복한다.

에이전틱 AI

에이전트 하나를 쓰든 여러 개가 협업하든, "자율 루프 방식으로 작동하는 AI"를 모두 통틀어 부르는 말. 개별 에이전트보다 한 단계 위의 분류.

용도

"에이전트처럼 작동하는 AI" 부류 전체를 통칭할 때. 에이전트 하나(단일 에이전트)·여러 개가 협업하는 시스템(멀티 에이전트)·여러 에이전트를 함께 지휘하는 도구까지 모두 포괄한다.

대표 사례
  • 자율 루프 패턴을 따르는 모든 에이전트 (ChatGPT Agent 모드·Claude Code 등)
  • 여러 에이전트를 함께 지휘하는 프레임워크 — LangGraph · CrewAI · AutoGen
에이전트와 차이

에이전트 = 개별 작동 단위(에이전트 하나하나). 에이전틱 AI = 그러한 행위 양식을 따르는 AI 시스템 부류 전체.

소프트웨어형 에이전트

LLM 없이 규칙·플래너·BDI로 동작하는 전통 AI 기반 에이전트.

용도

규칙이 명확하고 결정 경로가 예측 가능한 자동 의사결정 (예: 자동매매 알고리즘, 게임 NPC AI).

대표 사례

친숙한 예 — 게임 NPC AI, 자동매매 알고리즘, 산업용 PLC 제어, 자율주행의 규칙 기반 의사결정 모듈.

학술 아키텍처 더 보기 ▾
  • BDI (Belief-Desire-Intention) — Jadex 등 구현체
  • Soar — Allen Newell·John Laird 개발, 현재 미시간 대학교 유지
  • JADE — Java 멀티 에이전트 플랫폼
LLM 에이전트와 차이

두뇌가 규칙·코드지 LLM이 아니다. LLM 에이전트는 같은 개념 위에 LLM을 두뇌로 갈아 끼운 최신 구현.

RPA · 봇

정해진 UI 클릭·스크립트를 반복하는 자동화 도구.

용도

사람이 매번 같은 클릭·키 입력 작업을 반복할 때 (예: 사내 ERP에서 매일 보고서 다운로드 → Excel 정리).

대표 사례
  • UiPath — 글로벌 1위 RPA 플랫폼
  • Microsoft Power Automate — Microsoft 365 통합
  • Automation Anywhere — 엔터프라이즈 RPA
에이전트와 차이

예외·환경 변화에 취약. UI가 살짝만 바뀌어도 멈춘다. 스스로 계획·학습하지 않는다.

PART A · 2

분류 — ① AI 플랫폼 종속형

본 문서가 다루는 AI 에이전트는 모두 LLM을 두뇌로 한다. 차이는 LLM API를 누가 호출하는가(= LLM 회사 서버에 누가 요청을 보내는가)에 있다 — ①형은 AI 플랫폼(Claude Code 등)이 대신 호출하고, ②형은 에이전트가 직접 호출한다.

분류축 — 누가 LLM API를 호출하는가

분류 기준을 "종속(가둠) vs 의존(필요)"로 풀면 — ①은 AI 플랫폼 안에 갇혀 그 플랫폼 없이는 실행 자체가 불가능하지만, ②는 LLM을 필요로 할 뿐이고 특정 플랫폼에 얽매이지 않는다.

한 줄 비유 — 종속 = 그 회사 안에서만 일하는 정규직(회사가 사라지면 일자리도 사라짐). 의존 = 재료(LLM)는 필요로 하지만 특정 공급사에 얽매이지 않는 자영업자(A사 재료가 떨어지면 B사 재료로 바꿔서 가게는 계속 운영).

분류 ①②

① AI 플랫폼 종속형

특정 AI 플랫폼 안에 갇혀 작동. 플랫폼이 LLM 연결을 관리한다.

용도

코딩·문서·에이전트 협업처럼 AI 플랫폼이 제공하는 통합 환경 안에서 작업할 때. 직접 구축 부담이 없어 빠르게 시작 가능.

대표 사례
  • Claude Code 메인 에이전트
  • Cursor 안의 에이전트
  • GitHub Copilot Workspace (Technical Preview)
실용 차이

플랫폼이 사라지면 에이전트도 사라진다. 대신 즉시 사용 가능하고 도구 6종(이 섹션 내 "Claude Code 종속형의 도구 6종" 참조) 같은 풍부한 인프라가 따라온다.

② LLM 의존형

어떤 플랫폼에도 안 갇히고 자체 프로그램으로 실행. LLM API에만 직접 의존.

용도

웹앱·데몬·API·메신저봇 등 원하는 형태로 자유 배포할 때. LLM 회사(OpenAI/Anthropic/Google)를 바꿔도 에이전트는 살아남게 하고 싶을 때.

대표 사례
  • 9가지 구동방식 중 선택해 배포한 자체 에이전트
  • (구체 사례는 PART A · 3 ↗ 9구동방식 카드 참조)
실용 차이

특정 플랫폼에 얽매이지 않음. 9가지 구동방식(다음 섹션 PART A · 3에서 자세히) 중 선택. 만드는 부담은 크지만 자유도·이식성 최대.

① AI 플랫폼 종속형 에이전트

AI 플랫폼의 두 종류 — ① 에이전트 네이티브 AI 플랫폼은 본질이 에이전트라 그 안에서 실행하는 모든 것이 에이전트다(Claude Code · Cursor · Codex CLI · Gemini CLI · Devin · GitHub Copilot Workspace 등 — 단, GitHub Copilot 본체는 IDE 자동완성 보조형으로 분류축이 다르다). ② 챗 AI 플랫폼의 에이전트 기능은 그냥 채팅은 LLM이고 에이전트 기능을 켰을 때만 에이전트가 된다(ChatGPT의 Agent·GPTs · claude.ai의 Projects·Skills · Gemini 앱).

같은 단어, 다른 것 — claude.ai "Skills" ≠ Claude Code "Skill" · 이름은 같지만 전혀 다른 것이다.
  • claude.ai의 Skills — 챗 AI 플랫폼(claude.ai 웹사이트) 안의 Projects에 사용자가 첨부하는 가이드 문서·자료. 예: "내 회사 스타일 가이드.pdf"를 첨부 → Claude가 그 가이드대로 답함.
  • Claude Code의 Skill — CLI 에이전트가 자동으로 호출하는 실행 절차 묶음(SKILL.md 파일). 예: skill-create를 호출하면 9-Phase 제조 절차가 자동 실행.

한 줄 비교 — 전자는 "참고 자료", 후자는 "자동 실행 코드". 같은 단어 쓰는 이유는 둘 다 "Claude의 능력을 늘려주는 추가물"이라는 공통점 때문.

AI 플랫폼 종류 2종 — 종속형 에이전트가 사는 환경

에이전트 네이티브 플랫폼

플랫폼 본질이 에이전트 — 시작부터 끝까지 에이전트 행위.

용도

본격 코딩·자동화·에이전트 협업 작업. 일반 채팅이 아니라 도구 호출·다단계 작업이 일상인 환경.

대표 사례
  • Claude Code (CLI · 3계층 보유 — 본 자료의 주 사례)
  • Cursor (IDE 통합 에이전트)
  • Codex CLI · Gemini CLI · Devin · GitHub Copilot Workspace(Technical Preview)
특징

UI는 채팅처럼 보여도 내부적으로는 모든 입력이 에이전트 루프로 처리된다.

챗 AI의 에이전트 기능

챗 AI 플랫폼 안에 추가된 에이전트 기능. 맨-채팅은 챗봇이고 기능만 에이전트.

용도

일상 채팅 + 가끔 에이전트 작업이 필요할 때. 별도 CLI를 설치하기 부담스러운 일반 사용자에게 적합.

대표 사례
  • ChatGPT의 Agent 모드 · GPTs
  • claude.ai의 Projects · Skills
  • Gemini 앱 (에이전트 기능 활성화 시)
주의

맨-채팅 자체는 LLM(에이전트 아님). 에이전트 기능을 켰을 때만 그 안에 에이전트가 존재.

Claude Code의 3계층 (Claude Code 고유 구조)

이 "메인 · 팀메이트 · 서브에이전트" 3계층 구분은 Claude Code 한정 개념이다. 다른 AI 플랫폼(Cursor·Codex CLI·GitHub Copilot 등)은 자체 명명·계층 체계가 다르거나 단일 에이전트만 제공한다.

메인 에이전트

사용자와 직접 대화하는 루트 행위자. 모든 작업의 시작점.

용도

AI 플랫폼이 시작될 때 자동 생성. 따로 만들 필요 없음 — 사용자가 입력한 모든 것의 최초 수신자.

대표 사례
  • Claude Code 메인 (지금 이 응답을 작성한 그 에이전트)
  • Platoon Formation의 소대장
특징

전체 작업 조율·계획 + 팀메이트·서브에이전트 spawn 권한 보유. 사용자와의 컨텍스트를 끝까지 유지.

팀메이트 에이전트

이름을 갖고 지속 협업하는 자식 에이전트. 메인이 spawn.

용도

여러 대화에 걸쳐 같은 역할로 누적 협업이 필요할 때. 같은 전문성을 반복 호출해야 할 때.

대표 사례
  • Platoon Formation의 분대장 (Alpha-Lead · Bravo-Lead 등)
  • 코드 리뷰 전담 에이전트, 검증 전담 에이전트
특징

SendMessage로 이름 호출 가능. 살아있는 동안 누적 컨텍스트 보유. 다른 주요 CLI에서는 공식 확인되지 않은 Claude Code 고유 계층.

서브에이전트

일회성 위임으로 spawn되는 자식 에이전트. 작업 끝나면 사라짐.

용도

단일 작업·격리 필요·병렬 처리·메인 컨텍스트 보호가 필요할 때. 큰 탐색을 통째로 위임해 메인 컨텍스트 소비를 줄이는 용도.

대표 사례
  • Explore 에이전트 — 대규모 코드 검색 위임
  • general-purpose — 복합 작업 위임
  • Alpha-Lead가 내부적으로 호출하는 일회성 점검 에이전트
특징

작업 끝나면 사라짐 — 결과만 반환. 메인의 컨텍스트를 보호. 병렬 spawn(=새 서브에이전트 인스턴스 생성·일회성 위임) 가능.

Claude Code 종속형의 도구 6종

6종 모두 Claude Code에 한정된 개념이며, 다른 AI 플랫폼은 다른 도구 체계를 가진다.

행위자 ≠ 도구. 에이전트(메인·팀메이트·서브)는 스스로 판단하고 행동하는 행위자이고, 6종(Tool·Skill·Command·MCP·Hook·Plugin)은 그들이 동원하는 도구류다. 비유로 보면 스킬은 작업 매뉴얼 — 매뉴얼 자체는 일을 하지 않지만, 매뉴얼을 본 사람(에이전트)이 그대로 따라 일한다.

도구 6종

Tool

함수처럼 즉시 실행되는 원시 기능. Claude가 가장 자주 부르는 손발이다.

용도

파일을 읽고·쓰고·검색하고·셸 명령을 실행할 때. Claude가 코드를 살피거나 결과를 확인하려면 거의 매번 Tool을 호출한다.

대표 사례
  • Read — 특정 파일을 열어 내용 확인 ("이 함수의 정의를 봐")
  • Bash — 셸 명령 실행 (git status, npm test)
  • Edit — 파일의 정확한 문자열 교체 (코드 한 줄 수정)
  • Grep — 파일 내용 검색 ("이 변수 어디 쓰여?")
  • Agent — 서브에이전트에 작업 위임
호출 예 (참고용 — 사용자가 직접 치지 않음)
// Claude가 내부에서 자동으로 호출함:
Read({ file_path: "/src/app.ts" })
Bash({ command: "git status" })
Skill

한 번 호출하면 정해둔 절차가 통째로 발휘되는 능력 묶음 (SKILL.md 파일).

용도

"이 작업은 매번 같은 절차로 하고 싶다" 할 때. 반복되는 작업을 한 번 정리해두면 이후로는 누구나 호출해 같은 품질로 재현한다 — 재사용 자산화의 핵심.

대표 사례
  • skill-create — 스킬 자체를 만들어주는 메타 스킬 (스킬 제조 공장)
  • 백호-platoon-formation — 작업 규모에 맞춰 소대를 자동 편성
  • 청룡-sal-grid-dev — SAL Grid 3D 개발 방법론을 자동 적용
  • mbo-천상 — MBO(목표에 의한 관리) 기반 최상위 메타 스킬
호출 예
사용자: /skill-create
또는 Claude가 자동 매칭해 호출
Command

슬래시(/) 한 줄로 호출하는 사용자 정의 단축 명령.

용도

"이 프롬프트를 매번 길게 쓰기 귀찮다" 할 때. 자주 쓰는 지시를 한 단어 슬래시 명령으로 단축한다.

대표 사례
  • /init — 새 프로젝트에 CLAUDE.md 자동 생성
  • /review — 현재 PR을 검토
  • /clear — 대화 컨텍스트 초기화
  • /loop 5m /foo — 5분마다 /foo를 자동 반복
호출 예
사용자가 입력창에 직접 타이핑:
/init
/review #42
MCP

Model Context Protocol — 외부 서비스(메일·캘린더·DB 등)를 표준 프로토콜로 MCP 호환 클라이언트(Claude Desktop·Cursor·Zed 등)에 연결하는 서버. 공식 스펙 ↗

용도

Claude가 Gmail을 보거나, Notion에 쓰거나, 내부 DB를 조회해야 할 때. Claude 자체에 없는 외부 능력을 MCP 서버가 표준 인터페이스로 공급한다.

대표 사례
  • claude_ai_Gmail — Gmail 메시지 송수신·검색
  • claude_ai_Google_Drive — 구글 드라이브 파일 접근
  • claude_ai_Google_Calendar — 일정 조회·생성
  • 사내 MCP 서버 — 회사 내부 시스템(ERP·CRM 등)을 안전하게 연결
호출 예
Claude가 자동으로 함수 호출:
mcp__claude_ai_Gmail__send_message({ ... })
Hook

특정 이벤트가 일어나면 자동으로 발동되는 스크립트. "이벤트 → 행동" 규칙을 미리 박아둔다.

용도

"파일을 수정하면 자동으로 prettier 돌려라", "커밋 전에 lint 돌려라", "Claude가 위험한 셸 명령을 치면 차단해라" 같은 자동화·안전장치가 필요할 때. Claude가 시키지 않아도 시스템이 자동 발동한다.

대표 사례
  • PostToolUse Hook — 도구 사용 후 자동 실행. 예: 파일 수정 직후 ESLint(자바스크립트 코드 검사기)·Prettier(코드 포맷터)를 자동으로 돌림
  • PreToolUse Hook — 도구 사용 전 자동 실행. 예: Bash 셸 명령 실행 전에 rm -rf(파일 강제 삭제) 같은 위험 명령 차단
  • Stop Hook — Claude의 응답이 끝났을 때 자동 실행(세션 종료가 아니라 응답 완료 시점). 예: 응답 직후 로그를 파일로 저장
  • pre-commit 가드 — Git(코드 버전 관리 도구) 커밋(저장) 직전 자동 실행. 예: 청룡 스킬 규칙 자동 검사
설정 예 (참고용 — 개발자가 한 번 작성, 일반 사용자는 직접 치지 않음)
~/.claude/settings.json:
"hooks": {
  "PostToolUse": [ ... ]
}
Plugin

위 도구들(Tool·Skill·Command·MCP·Hook)을 묶어서 하나의 패키지로 배포하는 번들.

용도

"내가 만든 스킬·훅·명령어 셋을 다른 사람도 쓰게 하고 싶다" 할 때. 여러 도구를 한 번에 설치·배포·버전 관리할 수 있게 된다.

대표 사례
  • oh-my-wiki — 빈 Obsidian vault를 도메인 WiKi 시드(skill·MOC·태그 체계)로 부트스트랩하는 플러그인
  • frontend-design — UI 디자인 가이드 스킬 묶음
  • claude-code-guide — Claude Code 사용법 가이드 에이전트 묶음
설치 예 (참고용 — 개발자가 처음 등록할 때만)
# marketplace = Claude Code 공개 플러그인 저장소(앱스토어 격).
/plugin marketplace add <owner>/<repo>
/plugin install <plugin-name>

일반 사용자는 직접 치지 않고, 이미 설치된 플러그인의 기능만 그대로 사용한다. (2026-05 기준 베타 기능 — Claude Code 최신 버전에서 동작하며 인터페이스가 변경될 수 있다.)

PART A · 3

분류 — ② LLM 의존형

② LLM 의존형은 특정 AI 호스팅 플랫폼(Claude Code 등)에 종속되지 않고 에이전트가 직접 LLM API(= OpenAI·Anthropic 같은 LLM 회사 서버로 보내는 요청 통로)를 부르는 자체 프로그램이다. 즉 그 요청을 보내는 코드를 우리가 직접 만든다. (LLM 회사 서버 자체에 대한 의존은 별도. 종속/의존 정의는 PART A · 2 ↗ 참조)

9가지 구동방식 (본 가이드 분류) — 사람 개입형 6 + 무인 자율형 3

운영 루프에 사람이 실시간으로 입력·요청하느냐로 갈린다.

👤 사람 개입형 (1~6) — 사용자가 매번 요청할 때마다 작동하는 방식
1. 웹사이트형 (웹앱)

서버 호스팅 → 브라우저 접속. 가장 보편적인 형태. (비유: 누구나 주소만 알면 들어올 수 있는 24시간 카페 — 설치 없이 URL만 알려주면 끝.)

용도

사내·공개 사용자에게 설치 없이 제공. 누구나 URL만 알면 접근 가능. 모바일·데스크톱 어디서나 동일하게 사용.

대표 사례
  • KD엔지니어링 AI 에이전트 하우스 (9개 사내 업무 에이전트 묶음 — 웹사이트형 + 포털형 패턴 적용)
  • 선명AX 포털 (93개 에이전트 통합 — 웹사이트형 + 포털형 패턴 적용)
  • 일반 SaaS형 AI 서비스 (Perplexity·Phind 등)

※ KD엔지니어링·선명AX는 1 호스팅에 N 에이전트를 묶은 포털형 배포 패턴 적용 사례. 포털형은 9구동방식과 별도 축.

만드는 법 (주요 스택)
Next.js/React (UI)
+ LLM API (OpenAI/Anthropic)
+ Vercel/Cloudflare (배포)
2. 로컬 실행형

PC에 설치해 로컬에서 실행 (데스크톱 앱 또는 CLI). (비유: 내 책상 위 전용 도구 — 외부 인터넷 없이도 내 컴퓨터 안에서 일을 처리한다.)

용도

로컬 파일·민감 데이터를 다룰 때. 인터넷 의존을 최소화하고 싶을 때. 개발자용 도구로 가장 적합.

대표 사례 (사용자가 LLM API 키로 직접 만든 도구)
  • 사내 데이터 분석용 Python CLI (OpenAI API 직접 호출)
  • 로컬 파일 정리·요약용 Electron 앱 (Anthropic API 직접 호출)
  • 오프라인 우선 작업을 위한 전용 CLI + 로컬 LLM (Ollama 등)

⚠️ Claude Code CLI·Cursor·Codex CLI는 AI 플랫폼이라 ①형(PART A · 2)에 속한다.

만드는 법 (주요 스택)
Electron (크로스플랫폼 GUI)
또는 Node.js/Python CLI
+ LLM API 키 직접 주입
+ 로컬 파일 시스템 접근
3. 모바일앱형

스마트폰 앱 (iOS/Android).

용도

이동 중 사용, 푸시 알림으로 즉시 대응. 카메라·마이크·위치 등 모바일 센서 활용 필요할 때.

대표 사례 (모바일앱 "형태"의 예 — ①·② 무관)
  • ChatGPT·Claude·Gemini 모바일 앱 (대표적 모바일앱 형태. ①형 챗 AI 플랫폼 사례)
  • ②형 직접 제작 예 — 사내 현장 점검 앱(Anthropic API 직접 호출), 회의 메모 받아쓰기 앱(OpenAI API 직접 호출)
만드는 법 (주요 스택)
React Native (크로스플랫폼)
또는 Flutter
또는 네이티브 (Swift/Kotlin)
+ LLM API 키 직접 주입
4. 메신저봇형

Slack·카톡·Teams·Discord 등 메신저 안에서 봇으로 동작.

용도

기존 협업 흐름에 AI를 통합. 새 도구 학습 부담 없이 평소 쓰던 메신저에서 호출.

대표 사례
  • Slack의 ChatGPT 봇 (@ChatGPT 멘션으로 호출)
  • 카카오톡 채널 AI 챗봇 (기업 고객 응대)
  • Discord LLM 봇
만드는 법 (주요 스택)
Slack/카카오 비즈니스 API
+ LLM 백엔드 (Node.js/Python)
+ Bolt SDK 등
5. 브라우저 확장형

브라우저에 설치되는 확장 — 어느 웹페이지든 작동. (비유: 크롬에 붙여두는 만능 보조 도우미 — 보고 있는 페이지 어디서든 호출 가능.)

용도

웹 페이지를 보면서 그 자리에서 AI 호출이 필요할 때. 페이지 요약·번역·문장 교정 등.

대표 사례 (LLM API 기반 ②형 확장)
  • Monica AI Chrome 확장 (페이지 요약·번역, OpenAI·Anthropic API)
  • WebChatGPT (ChatGPT에 웹 검색 결과 주입)
  • Sider AI (사이드 패널 어시스턴트)
만드는 법 (주요 스택)
Chrome/Firefox Extension
(Manifest V3)
+ Content Script + LLM API
6. 애드인형

Office·Notion·Workspace 등 특정 앱 안에서만 작동하는 애드인. (비유: Word·Notion 안에서만 일하는 전속 비서 — 호스트 앱의 데이터에 직접 접근 가능.)

용도

특정 문서·표 작업 컨텍스트 안에서 즉시 호출. 호스트 앱이 가진 데이터·기능을 직접 활용.

대표 사례
  • Notion AI (Notion 페이지 내장)
  • Google Workspace 사이드 패널 (Docs·Sheets·Gmail)
  • Microsoft Copilot for Word·Excel (Office 365 통합)
만드는 법 (주요 스택)
호스트 앱 Add-in SDK
(Office Add-in JS API,
 Notion Integration API 등)
🤖 무인 자율형 (7~9) — 사람이 매번 요청하지 않아도 알아서 도는 방식
7. 서버상주(데몬)형

서버에 24/7 상주하며 자동으로 동작. 사람 개입 없음. (비유: 건물 경비원처럼 자지 않고 상주하며 이상이 생기면 즉시 대응한다.) Docker 공식 ↗

용도

상시 감시·자동 대응이 필요할 때. 사람이 잠든 새벽에도 알아서 일해야 하는 상황.

대표 사례
  • 장애 모니터링 AI (지표 이상 감지 → 자동 대응)
  • 24/7 이상거래 감시 봇
  • 헬스체크 + 자동 복구 데몬
만드는 법 (주요 스택)
Docker 컨테이너
+ systemd/PM2 상주
+ 메시지 큐 (이벤트 수신)
8. API엔드포인트형

API로 노출되어 타 시스템이 호출하는 형태. (비유: 은행 ATM처럼 여러 곳에서 같은 창구로 접근할 수 있는 표준 입구. REST=가장 보편적 웹 API, gRPC=구글이 만든 더 빠른 형식.) FastAPI 공식 ↗

용도

다른 SW에 AI 능력을 기능으로 제공할 때. 한 에이전트가 여러 시스템에 재사용되어야 할 때.

대표 사례
  • OpenAI API (다른 시스템에 GPT 제공)
  • Anthropic Messages API (Claude 제공)
  • 사내 에이전트 마이크로서비스 (REST·gRPC 등 API 통신 규약 활용)
만드는 법 (주요 스택)
FastAPI/Express
+ LLM 호출 로직
+ API Gateway · 인증
9. 스케줄·트리거형

cron(정해진 시간에 자동 실행되는 예약 기능)이나 webhook으로 정기·이벤트성 기동. (비유: 매일 새벽 5시 신문 배달처럼 정해진 시간·사건이 와야만 깨어나 일한다.) GitHub Actions 공식 ↗

용도

"매일 아침 보고서 자동 생성", "PR이 만들어지면 자동 리뷰", "정기 데이터 정리" 등 시간·이벤트 기반.

대표 사례
  • 일일 리포트 봇 (cron으로 매일 오전 8시 실행)
  • GitHub Actions 트리거형 봇 (PR 생성 시 자동 리뷰)
  • 슬랙 webhook 응답 봇
만드는 법 (주요 스택)
GitHub Actions (가장 빠른 시작)
또는 cron / AWS Lambda + EventBridge

어떤 방식을 고를까 — 2분 체크리스트

이런 상황이면추천 방식
누구나 URL로 접속해 쓰게 하고 싶다1. 웹사이트형
로컬 파일·민감 데이터를 다뤄야 한다2. 로컬 실행형
이동 중·푸시 알림이 필요하다3. 모바일앱형
이미 쓰는 메신저(Slack·카톡) 안에서 호출하고 싶다4. 메신저봇형
웹페이지 보면서 그 자리에서 작동해야 한다5. 브라우저 확장형
Notion·Office 등 특정 앱 안에서만 쓴다6. 애드인형
사람 없이 24/7 상시 감시·대응해야 한다7. 서버상주(데몬)형
다른 시스템이 API로 호출해야 한다8. API엔드포인트형
매일 정기·이벤트 시점에만 돌면 된다9. 스케줄·트리거형
여러 에이전트를 한 화면에 묶고 싶다위 9가지 중 하나 + 포털형 배포 패턴(별도 축)
PART A · 4

양봉장 비유

에이전트의 5요소(LLM·자율 루프·메모리·도구·목표)와 핵심 자산(Skill = 반복 작업 절차서, 도메인 WiKi = 분야 지식 노트)을 양봉장 구조에 빗대 한눈에 매핑한다.

에이전트를 벌통 한 통에 비유하면 이해가 쉽다. 여왕벌은 직접 일하지 않고 페로몬 신호로 벌통의 행동을 조절하고, 벌통 전체는 한 몸처럼 움직인다 — LLM이 두뇌이고 도구·메모리·목표·자율 루프가 한 묶음으로 도는 에이전트의 구조와 유사하다.
※ 엄밀한 생물학 사실은 아니라 교육용 단순화 비유다. 실제 벌통은 여왕벌의 페로몬 외에도 정찰벌의 waggle dance·분산 합의로 의사결정이 이루어지는 분산 시스템에 가깝다.
벌통 구조 한눈에 — 5요소가 한 몸으로 움직인다
🐝 여왕벌 (LLM·두뇌)
↓ 페로몬 (≒ LLM의 출력 신호 — 비유)
🐝 일벌 (도구)
🍯 꿀 칸 (메모리)
🎯 수확량 (목표)
🔄 채집 순환 (자율 루프)
🌸 꽃밭 (도메인 WiKi) · 📓 매뉴얼 (Skill) — 사용자가 누적해 쌓는 자산

핵심 매핑 — 에이전트 구성요소 ↔ 양봉장

AI 에이전트 개념양봉장으로 풀면
에이전트 (전체)벌통 한 통 — 아래 5요소가 묶여 한 몸으로 움직이는 군집(초유기체 = 여러 개체가 한 생명체처럼 작동하는 집단)
1) LLM(두뇌)여왕벌 — 벌통 안에서 페로몬(LLM의 출력 신호 — 텍스트가 기본, 멀티모달 모델은 이미지·음성 입출력도 포함)을 내보내 벌통의 행동을 조절한다
2) 자율 루프벌의 채집 순환 — 정찰→채집→귀환→저장을 사람 지시 없이 반복. 한 사이클이 끝나면 자동으로 다음 사이클이 돌아 목표 수확량을 채울 때까지 계속된다(반복·자율성을 그림으로 보이기 위한 단순화 — 에이전트 5단계의 계획·판단·평가는 비유에 1:1로 들어가지 않는다).
3) 메모리자기 꿀 칸 — 모은 꿀(작업 상태·지식)을 칸에 저장
4) 도구일벌 — 여왕벌이 직접 일하지 않는 대신, 일벌이 페로몬 신호를 받아 실제 움직임을 수행한다
5) 목표꿀 수확 목표량 — 어디서 멈출지 정하는 기준. 단순 "꿀을 많이"가 아니라 "5kg" 같이 구체적이어야 벌통이 폭주하지 않는다(목표 해상도가 곧 에이전트 행동의 품질).
+ Skill (SKILL.md = 절차를 적어 둔 마크다운 파일)양봉가의 작업 매뉴얼 — 사용자가 반복 작업 절차를 누적해 쌓는 자산
+ 도메인 WiKi (Obsidian = 마크다운 기반 개인 지식 노트 앱)양봉가가 직접 가꾼 꽃밭 — 사용자의 분야 지식이 누적된 원천 자료

여왕벌(LLM)은 GPT에서 Claude로 갈아 끼울 수 있고 일벌(도구)도 새로 만들 수 있다. 반면 사용자가 누적한 꽃밭(WiKi)과 매뉴얼(Skill)은 LLM·도구 교체와 독립적으로 보존되며, 누적될수록 사용자만의 작업 맥락을 더 강하게 담는다.

※ "LLM·도구는 교체 가능한 구성 요소"라는 관점은 Anthropic의 에이전트 정의 ↗와도 결이 같다. (본 가이드의 5요소 분류는 Anthropic 자료를 참조해 본 가이드가 종합한 분류임 — Anthropic 원문에는 5요소 프레임이 직접 명시되어 있지 않다.)

🐝 양봉장 비유 슬라이드쇼 →

PART A · 5

멀티 에이전트

에이전트 한 명으로 안 되는 일은 어떻게 할까? 답은 팀이다. 단일 에이전트가 혼자 한다면, 멀티 에이전트는 역할을 나눈 여러 에이전트가 협업한다.

멀티 협업 4패턴

오케스트레이터-워커

상위 1명이 계획·분배, 워커 N명이 개별 작업을 병렬 수행. (비유: 콜센터 슈퍼바이저가 들어온 요청을 보고 각 상담원에게 나눠주는 방식.)

용도

큰 작업을 작은 단위로 나누어 병렬 처리해야 할 때. "이 PR(Pull Request — 코드 변경 검토 요청)을 검토하라" → 보안·성능·스타일 워커가 각자 검토.

대표 사례
구조

오케스트레이터 1명 + 워커 N명. 2층 평면. 워커끼리 직접 통신 없음.

계층형 (Hierarchical)

군대 조직처럼 중간 관리자가 하부 조직을 통제하는 다층 구조. (비유: 사장 → 부서장 → 팀장 → 팀원처럼, 윗사람이 다 부리지 않고 중간 관리자가 분담.)

용도

작업이 매우 복잡해 다층 분업이 필요할 때. 메인이 직접 전부 처리하면 컨텍스트(= LLM이 한 번에 다룰 수 있는 단기 기억 용량)가 과부하 상태가 되므로 중간 관리자가 분담한다.

대표 사례
  • Platoon Formation — 본 자료 저자의 한 구현 사례. 자세히는 아래 사례 섹션 참조.
  • 군대·기업 조직 구조의 디지털 모사
구조

최상위 → 중간 관리자(여러 명) → 워커. 3층 이상.

토론·합의형 (Debate)

동급 에이전트들이 서로 토론·검증해 품질을 올리는 패턴.

용도

한 에이전트의 답이 의심스러울 때, 다관점 검증이 필요할 때 (정치·윤리·복잡 의사결정).

대표 사례
  • Multi-Agent Debate 패턴 — 여러 LLM이 라운드 토론으로 사실성·추론 향상
  • LangGraph — 그래프 안에 토론 사이클을 구성 (전용 "Debate 노드"는 아니고 사용자가 그래프로 설계)
  • pro-persona-debate 스킬 — 3 전문가 페르소나(가상 인격)가 DA(Devil's Advocate — 일부러 반론 역할을 맡아 검증하는 에이전트)와 5단계 토론
구조

평등한 에이전트 여러 명(보통 2~5명 규모)이 다음 단계로 합의에 도달한다:

초안 작성 → 상호 검토·반박 → 의견 수렴 → 합의(또는 다수결) → 종료

블랙보드 / 공유 메모리형

공통 상태(블랙보드)를 두고 여러 에이전트가 자유롭게 협력. (비유: 여러 팀원이 공용 화이트보드에 메모하며 일하는 방식.)

용도

여러 에이전트가 같은 데이터·문맥을 보며 일해야 할 때. 사전 정의된 분업 없이 자율적 협업.

대표 사례
  • 공유 벡터 DB·메모리 시스템 — 여러 에이전트가 같은 저장소에 쓰고 읽음
  • 최근 LLM 프레임워크의 SharedMemory·MultiAgent Memory 옵션
학술적 원조 (참고)

Hearsay-II — 1970년대 CMU에서 개발된 음성인식 시스템. 블랙보드 아키텍처의 고전. (Erman, Hayes-Roth, Lesser, Reddy, 1980, "The Hearsay-II Speech-Understanding System")

구조

중앙 메모리(블랙보드) + 에이전트들이 비동기로 접근한다(비동기 = 동시에가 아니라 각자 편할 때 접근). 약한 결합(= 서로 강하게 묶여 있지 않음) 구조라 유연하지만, 동시에 같은 칸을 건드리면 충돌이 날 수 있어 관리가 필요하다.

⚠️ 트레이드오프 — 에이전트 수가 늘수록 오케스트레이션 복잡도·지연·비용도 함께 커진다. 단일로 충분한 작업까지 멀티로 갈 필요는 없다.

4패턴 한눈 비교 — 어떤 상황에 어떤 패턴?

패턴이런 상황이면대표 프레임워크
오케스트레이터-워커큰 작업을 작은 단위로 나눠 병렬 처리LangGraph Supervisor · CrewAI Manager
계층형다층 분업·컨텍스트 격리 필요Platoon Formation · AutoGen GroupChat
토론·합의형다관점 검증·신뢰도 향상Multi-Agent Debate · pro-persona-debate
블랙보드공용 데이터를 자율적으로 협력공유 벡터 DB · SharedMemory

사례 — Platoon Formation (소대 편성, 계층형의 한 구현)

여러 Claude를 소대(platoon — 군대 단위) 구조로 편성해 협업시키는 멀티 에이전트 방법론. (저자가 정리·구현해 특허 출원한 한 가지 구현 방식. 출처 표기는 섹션 말미.)

계층형 멀티 에이전트의 한 구현으로, 백호-platoon-formation 스킬이 이 방법론을 실행한다. 작업 폴더명을 기준으로 소대를 자동 편성하며, 분대 수와 분대원·예비병 구성에 따라 수십 명 규모까지 확장된다. (백호는 저자가 사용하는 내부 코드네임이며 외부 독자에겐 기능명이 우선이다.)

편성 구조 — 6단 편성표

계급정체모델 등급역할
소대장Orchestrator AI (Team Leader)
= Claude Code 메인 에이전트		Opus급작업 분해·배정·결과 종합 (조율 중심 역할 — 실작업은 하위 계층 위임)
연락병UI 인터페이스 모듈—사용자와 소대 사이의 입출력 매개
분대장Manager AI (Teammate)Sonnet급분대원 지휘·결과 취합. 도메인별 중간 관리 계층
분대원Worker AI (Subagent) — 실무 수행 11종 표준 역할
목록 보기① 프론트엔드 · ② UX/UI · ③ API · ④ 백엔드 · ⑤ DB · ⑥ 코드 리뷰 · ⑦ 테스트 · ⑧ 보안 · ⑨ DevOps · ⑩ 디버깅 · ⑪ 문서 (소프트웨어 도메인 표준. 도메인에 따라 자유 구성 가능)
Haiku 기본
(복잡 시 Sonnet)		위임받은 실무 수행
용병외부 AI — Codex(OpenAI 코딩) · Gemini(구글) · Grok(xAI) · Perplexity(검색)외부특수 전문성·실시간 검색 시 소집. 호출 권한은 소대장·분대장만 보유하며, 모든 용병 호출은 단일 게이트웨이를 경유한다
작전 통제소통합 관제 모듈 (DB+UI)—복수 소대 관제. 다중 소대 운영 시 활성화

편성 공식 — 예측 가능한 팀 구성:

P + N × (1 + M) + K
P = 본부 정원 (소대장 1 + 연락병 1) = 2
N = 분대 수 (사용자 결정, 기본 3~5)
M = 분대당 분대원 수 (도메인에 따라 구성, 표준 11)
K = 용병 수 (외부 AI, 임무에 따라 가변)

예시: 3개 분대 편성이면 P=2, N=3, M=11, K=4
      → 2 + 3 × (1+11) + 4 = 42명
📊 통신 구조 — 계층 라우팅
완전그래프(n(n-1)/2 경로) 대신 직속 상·하위 통신만 사용해 메시지 경로를 줄인다. 단, 트리·계층 구조의 경로 절감은 LangGraph Supervisor·CrewAI Manager·AutoGen GroupChat 등 다른 계층형 패턴도 공유하는 자명한 수학적 결과이며 본 방법론만의 우위는 아니다. 본 방법론의 차별점은 분대장 계층·NATO 호출부호·6단 편성표 등 운영 표준화에 있다.

분대 편성 — NATO 호출부호

편성 타입분대 수호출부호적용
A형 (기본)3개Alpha · Bravo · Charlie일반·중소규모 임무
B형 (확장)5개Alpha ~ Echo대규모·복합 도메인
C형 (지정)6개+Alpha ~ (NATO 순서)초대규모·특수 임무

작동 원리

단일 에이전트로 다루기 어려운 대규모·복합 임무를 계층 지휘와 모델 등급 차등 배치로 비용 효율적으로 처리한다.

사용자 개입은 핵심 결정 지점에 한정된다 — ① 임무 부여, ② 작전 개시 승인, ③ 해산 승인. 그 외 중간 결정·오류 대응은 소대가 자율 수행하되, 사용자가 필요 시 언제든 개입 가능하다.

이 구조가 극복하는 단일 에이전트의 한계는 네 가지다. ① 대규모·복합 임무 처리 한계 — 분대 단위로 쪼개 동시 수행한다. ② 고급 모델 일률 사용으로 인한 누적 비용 — 소대장(opus)·분대장(sonnet)·분대원(haiku/sonnet)으로 등급을 차등 배치해 비용을 최적화한다. ③ 전문성 부족 — 분대마다 도메인 전문성을 분업한다. ④ 컨텍스트 과부하·순차 처리 — 메인의 컨텍스트를 분대원에게 격리하고, 독립 작업은 병렬 처리한다.

출처 — 본 방법론은 저자(선웅규)가 정리·구현한 자료로 특허 출원되어 있다(출원번호 10-2026-0041235, 출원일 2026.03.07 — 출원은 등록·심사 통과를 보증하지 않는다). 특허 슬라이드쇼 ↗

PART B — AI 에이전트 제작 방법

에이전트를 어떻게 만드는가 — 두 갈래의 제작 방법.

PART B · 1

개요

PART A의 두 분류 — ① AI 플랫폼 종속형(남의 오븐을 빌리는 길)과 ② LLM 의존형(재료를 직접 굽는 길) — 각각을 어떻게 만드는지 본다.

제작 트랙만드는 것사용 메타 스킬
① AI 플랫폼 종속형핵심 창조물 = 스킬(에이전트가 쓰는 기능 묶음 — AI 플랫폼 종속형 에이전트의 역량)skill-create
② LLM 의존형LLM 의존형 에이전트 — LLM(두뇌)에는 의존하지만, 어느 호스팅 플랫폼에도 갇히지 않고 인프라·구동방식을 선택해 설계하는 독립 에이전트llm-dependent-agent-create
AI 플랫폼 종속형 에이전트는 그 플랫폼이 정한 틀 안에서만 존재하므로 에이전트 자체는 우리가 별도로 "제조"할 수 있는 대상이 아니다. 트랙 ①에서 실제로 만드는 것은 그 에이전트의 역량 — 즉 스킬이다.

제작 전 — 아키텍처 파일 필수

두 트랙 모두, 본격적으로 만들기 전에 아키텍처 파일(설계도 문서 — 텍스트·다이어그램·또는 둘의 결합)을 먼저 작성한다. 관계도(구성요소 간 관계)와 흐름도(처리 흐름)를 그려둔다. 이렇게 하면 연결이 끊긴 흐름이나, 아무 데도 연결되지 않은 고아 부품을 눈으로 미리 발견할 수 있다. (단일 스킬이라면 SKILL.md 안의 다이어그램 한 장으로 충분하고, 다부품 에이전트일수록 별도 파일로 분리한다.)

공통 원칙 — "분해·선별 후 조립"

발굴오픈소스·사내·HF 등
안전성 진단위험도 감사
분해·선별검증된 것만
조립9-Phase로 위임

다이어그램 → 9-Phase 매핑: 발굴 = Phase 3 / 안전성 진단·분해·선별 = Phase 4(분해·검증)의 두 작업 / 조립 = Phase 5(설계 검증) 거친 후 Phase 6(조립·제조).

① 발굴 — 공개 저장소(오픈소스 등), 사내 자산, Hugging Face, 검증된 상용 부품에서 기존 소스를 찾는다. 검증된 자산이 있을 때 한해, 좋은 자산을 처음부터 다시 만들지 않는다.

② 안전성 진단 — 발굴한 소스의 위험도와 안전성을 감사 방식으로 진단한다. 보안 취약점이 알려진 코드, 지원이 끊긴(deprecated — 더 이상 관리되지 않는) 라이브러리, 과도한 의존성을 가려낸다. ※ 라이브러리 = 코드 부품 모음.

③ 분해·선별 — 발굴물을 통째로 가져다 쓰지 않는다. 부품 단위로 분해한 뒤 안전하고 검증된 것만 골라내고, 문제 있는 부분은 걷어낸다.

④ 조립 — 선별된 부품을 위 아키텍처 파일대로 결합한다. 두 트랙 모두 9-Phase 공장 방식을 공유하되, 이 시점부터 각자의 라인으로 갈라진다. 트랙 ①은 단일 SKILL.md 조립. 트랙 ②는 3단 분해 조립 — 6a 본체(에이전트 코어 로직) · 6b 플랫폼 레이어(호스팅·UI·라우팅) · 6c 공통 인프라(LLM 폴백 체인·DB·로그). 자세히는 PART B · 2·PART B · 3.

PART B · 2

AI 플랫폼 종속형 에이전트 제작 — 트랙 ①

Claude Code 같은 AI 플랫폼 종속형 에이전트의 핵심 창조물은 스킬이다. 트랙 ①은 skill-create(메타 스킬 = 스킬을 만드는 공장)를 사용해 검증된 SKILL.md 파일 하나를 제조한다.

두 트랙은 같은 9-Phase 공장 골격(기획→발굴→분해·선별→조립→검증→자산화→운영 루프)을 공유한다. 같은 자산이 스킬로 출하될 수도, 에이전트로 재포장될 수도 있는 양방향 관계다.

좋은 스킬의 조건

단일 책임

하나의 명확한 목적만 담는다.

자기완결

외부 스킬에 의존하지 않는다. 필요 내용은 자기 폴더에 내장.

간결

거대 스킬 금지. 본 가이드 메타 스킬 권장 500줄 이내 (외부 표준 한도는 없으며 가독·재사용성 기준).

구조 완비

YAML 프론트매터(파일 머리의 메타정보 블록) + Phase 구조 + 사용 예시 + 금지사항.

제작 흐름 — 9-Phase

Phase 0시동·모드
Phase 1스무고개
Phase 2목표·승인
Phase 3발굴
Phase 4분해·검증
Phase 5설계 검증
Phase 6조립·제조
Phase 74단 QC
Phase 8출하·등재
Phase 9운영 루프

모드 (Phase 0): 단일(1개 스킬) · 배치(여러 스킬 묶음). 포털 모드는 인프라가 필요해 에이전트 전용 — 인프라 A(Supabase) 강제 (트랙 ②에서 다룬다).

스무고개 (Phase 1): AI가 질문하고 사람이 답하는 10라운드 기본 문답으로 요구사항을 확정한다. 모드별 구성 — 단일 1a 10 · 배치 1b 5 · 포털 1c 4+3(부족 시 추가 라운드). 초보자 친화 톤(한 번에 한 질문 · 전문 용어 풀이 · 예시 동반). 산출물에 📡 출력 대상 시스템 명세와 🤖 큐레이션 선정 알고리즘(해당 시) 포함.

BOM 5분류 (Phase 4): Phase 4에서 발굴한 부품을 다음 5색으로 라벨링한다 — 🟢 검증 통과 · 🟡 조건부 통과 · 🔴 거부 · 🏭 자체 작성 · 🔵 공통 인프라. 🔵에는 LLM 폴백 체인 모듈(주 LLM이 실패하면 다음 LLM으로 자동 전환되는 안전망 — Claude→Gemini→GPT→Grok 순. 순서는 본 가이드 저자 환경의 품질·비용·가용성 우선 순위로, 사용 환경에 맞춰 조정 가능)이 표준 자산으로 포함된다. (트랙 ②에서는 이 🔵 자산이 PART B · 3의 6c 공통 인프라로 조립된다.)

설계 검증 (Phase 5 — 두 트랙 공통): "자기완결 = 외부 도구 호출 없이 본 스킬·에이전트 안에서 절차를 닫는다"는 원칙으로, 두 레이어로 구성.
· 5A 검토·평가 — 5기준(문법·실행/보안/품질/테스트/완성도)×20점 채점을 반복해 정량 품질 기준에 수렴할 때까지 보강.
· 5B 진단·해체 — 역방향 분해(완성품을 거꾸로 뜯어 부품·관계·의존성으로 재구성하는 방법)로 단계별 진단 카드(의존성 순서대로 묶은 진단 항목 1장)를 만든 뒤 카드별로 진단→개선→재진단을 돌려 자가 수렴.

4단 QC (Phase 7 — 두 트랙 공통): ① 정적 검사 ② 동적 실행 ③ UI 클릭(있는 경우) ④ 외부 검증. ④의 외부 검증 = 별도 Verification Agent가 다시 확인해 자기검증 편향을 차단한다(자기검증 금지). Phase 7-3+ 출력 대상 시스템 실제 화면 확인(curl 200·dry-run·DB SELECT 같은 자가 검증은 사람 눈으로 본 실제 화면을 대체할 수 없다)도 포함한다.

운영 루프 (Phase 9): 출하 후 사용 통계·피드백을 모아 Phase 1로 회귀. 운영 인프라(로그 수집·모니터링)가 다음 임계값을 측정하다 하나라도 닿으면 자동 회귀 — 마지막 N회 호출 에러율 ≥ 5% · 평균 응답시간 ≥ 30초 · 누적 피드백 ≥ 5건 · 비용 가드 ≥ 3회 발동 · 30일간 사용률 0.

Phase 4·5·7 — 세 가지 "검증"의 차이

"검증"이라는 단어가 세 Phase에서 등장하지만 목표가 다르다.

Phase검증 종류대상 / 목표
4 · 분해·검증부품 검증발굴한 부품들이 적격한가 — BOM 5색 라벨링
5 · 설계 검증설계 검증 (자기완결)5A 5기준×20점 채점 + 5B 역방향 분해·진단·재진단
7 · 4단 QC출하 검증정적·동적·UI·외부 검증(별도 Verification Agent)

skill-create 프레임워크 한눈에 보기

skill-create 프레임워크 전체도 — 9-Phase 흐름도 · 관계도 · 핵심 철학 (새 탭에서 크게 보기) ↗

PART B · 3

LLM 의존형 에이전트 제작 — 트랙 ②

트랙 ②는 llm-dependent-agent-create(메타 스킬)로, LLM(두뇌)에는 의존하지만 어떤 플랫폼에도 갇히지 않는 독립 에이전트를 제조한다. 메모리·루프·도구·배포 형태를 처음부터 자유롭게 설계한다.

9-Phase 기본 개념은 PART B · 2 참조.

제작 흐름 — 9-Phase (트랙 ② 적용)

Phase 0시동·인프라★
Phase 1스무고개
Phase 2목표·승인
Phase 3발굴
Phase 4분해·검증
Phase 5설계 검증
Phase 63단 조립★
Phase 74단 QC
Phase 8출하·등재
Phase 9운영 루프

★ 표시한 Phase 0·6은 트랙 ①과 다른 부분.

트랙 ②의 3가지 차이점

Phase트랙 ① skill-create트랙 ② llm-dependent-agent-create
0 · 시동모드(단일/배치) 결정모드(단일/배치/포털) + 인프라 A·B 결정 (상세는 아래 callout)
6 · 조립단일 SKILL.md 조립3단 분해 조립 — 6a 본체(에이전트 코어 로직) · 6b 플랫폼 레이어(호스팅·UI·라우팅) · 6c 공통 인프라(인증·결제·로깅·LLM 폴백 = PART B · 2의 BOM 🔵 자산)
출하 자산스킬 (SKILL.md)에이전트 본체 (코어 + 인프라 + 플랫폼 레이어 통합 패키지)

조립 단계 조합 — 모드별 어떤 단계를 쓰는가

모드6a 본체6b 플랫폼6c 공통 인프라비고
단일✅——최소 구성
배치✅—✅여러 에이전트가 공통 인프라 공유
포털✅✅✅인프라 A(Supabase) 강제
9가지 구동방식 + 포털형은 별개의 축이다.
  • 9가지 구동방식(스무고개 도중 자동 선택, 상세는 PART A · 3) — "에이전트가 어떻게 일하는가"의 축 (대화형 / 자율 실행 / 정기 트리거 / 이벤트 반응 등).
  • 포털형 배포 패턴 — "에이전트들을 어떻게 한 화면에 모으는가"의 축. 9구동방식 중 하나가 아니라 직교한 별도 축이다.
9종 어떤 구동방식이든 1 호스팅 = N 에이전트 구조(포털형)로 묶을 수 있다. 대표 사례 — 선명AX(93개 사내 업무 에이전트를 하나의 포털로 운영) · KD엔지니어링 AI 에이전트 하우스(엔지니어링 도메인 사내 포털). 인프라 A(Supabase) 환경에서 가장 자연스럽게 구현된다.
인프라 2가지 (A·B 이동 자유):
  • A · Supabase 인프라 — 운영 DB·인증·Storage·API를 한 번에 제공하는 클라우드 BaaS(Backend-as-a-Service). 가입만 하면 바로 쓰는 클라우드 백엔드 서비스로, 서버를 직접 짜지 않고도 DB·로그인 기능을 즉시 갖춘다. 포털 모드 강제 + 다중 사용자 대응.
  • B · 로컬 .py + API키 — DB 없이 engine.py + 스킬스/{AGENT_ID}_{skill_id}/SKILL.md + run.py 파일 구성. 로컬 JSON 로그. 인증은 환경변수 또는 .env(dotenv) 파일에 API 키를 두고 단일 사용자 환경 기준으로 작동(다중 사용자가 필요하면 A 인프라로 전환).

SSOT(Single Source of Truth) — 하나의 마스터 파일을 단일 기준으로 삼아 다른 곳을 파생시키는 원칙.
본 트랙의 SSOT 위치 = 스킬스/{AGENT_ID}_{skill_id}/SKILL.md. A↔B 이동 시 로직(.md 본문) 0 변경 — 단, 운영 환경(DB·인증·API)은 인프라 따라 다르므로 배포·연동 코드는 인프라별로 갈아끼운다.

llm-dependent-agent-create 프레임워크 한눈에 보기

llm-dependent-agent-create 프레임워크 전체도 — 9-Phase 흐름도 · 관계도 · 핵심 철학 (새 탭에서 크게 보기) ↗