🐶 TL;DR
무려 지지난주 오프에서 만들었던 에이전트를 이제야 테스트해보니 생각보다 별로였다.
그래서 받았던 스킬(에이전트 설계 스킬)을 분석해 보았다.
이 스킬은 에이전트가 놀 수 있는 울타리를 설계해주는 거였다.
에이전트의 성능은 결국 내가 만들어야 되는 거였다.
🍯 단지 널 사랑해 그렇게 말...하고 싶었지
나의 귀여운 에이전트 '단지'를 이제야 제대로 테스트 해보았다.
야심차게 이름까지 붙여주었건만...
사실 생각보다 실력이 아쉬웠다;;
나름 이것저것 잘 찾아왔지만 그래도 뭔가 결과물이 2% 부족한 느낌?
단지를 사용할 때, 단지의 설계만 참고할 때, 그냥 클코로 찾을 때가 아주 크게 차이가 있지는 않는것 같았다.
나는 어떤 아이를 만든걸까?
이 녀석을 설계했던 과정부터 분석해보기로 했다.
🧐 설계 스킬 분석
단지를 설계하면서 단계별로 클로드한테 물어가면서 진행했지만 사실 다 이해하고 설계한 것은 아니었다.
이제라도 이해해보자. 클코의 도움을 받아서 Step by Step
이 에이전트를 설계하는 스킬의 과정을 문서로 보고 싶어. 각 단계별 질문을 가시적으로 보기 좋게.
* 모르는 용어가 너무 많다.. 비전문가 비개발자 입장에서 알수 없을 만한 용어를 찾아서 설명을 추가해줘.
* 각 단계별로 목적과 어떤 흐름으로 진행하기 원하는 것인지 조금더 자세하고 친절하게 설명해줘.
* 비유로 설명하지마. 그냥 있는 그대로 설명해줘.
* 이 흐름으로 에이전트를 설계했을 때 얻는 최대 효과도 알려줘.이렇게 받은 md 파일을 차분히 읽어보.......지는 못했지만
그래도 공부할 거리를 받으니 마음이 편해졌다.
후루룩 훑어보기라도 해봐야겠지;;
✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️✏️
📖 용어 사전 (먼저 훑어보기)
처음 보는 단어가 나오면 여기로 돌아와 확인하면 된다.
기본 개념
용어
쉬운 설명
에이전트 (Agent)
스스로 계획·실행·점검·수정까지 하는 AI 시스템. 사람의 개입을 최소화한다.
챗봇 (Chatbot)
질문을 받으면 답하는, 한 번 주고받는 대화 중심 AI. 스스로 일을 진행하진 않는다.
워크플로우 (Workflow)
정해진 순서대로 작업을 처리하는 자동화. 분기와 판단이 미리 고정돼 있다.
RPA
Robotic Process Automation. 사람이 하던 단순 반복 컴퓨터 작업(복사·입력 등)을 그대로 흉내 내 자동화하는 기술.
API
Application Programming Interface. 프로그램끼리 데이터를 주고받는 약속된 창구. 예: 날씨 API를 부르면 날씨 데이터를 돌려준다.
에이전트의 행동 방식
용어
쉬운 설명
Agentic (자율적)
AI가 시키는 것만 하지 않고 스스로 판단해 행동하는 성질.
Planning (계획)
목표를 이루기 위해 할 일을 단계로 나누는 것.
Execution (실행)
나눈 단계를 실제로 수행하는 것.
Self-correction (수정)
결과가 잘못됐을 때 스스로 고치는 것.
Reflection (반성)
자신의 과정·결과를 돌아보며 더 나은 방법을 찾는 것.
Tool Use (도구 호출)
AI가 외부 도구(검색·계산기·DB 등)를 직접 불러 쓰는 것.
Function Calling (함수 호출)
AI가 미리 정의된 기능(함수)을 골라 실행하게 하는 방식. 예: "메일 보내기" 함수를 AI가 직접 호출. Tool Use를 구현하는 대표적 기술.
MCP
Model Context Protocol. AI가 외부 도구·데이터와 연결되는 방식을 통일한 표준 규격. 도구를 꽂으면 바로 쓸 수 있게 해주는 일종의 공통 콘센트.
GRAM 루프
Goal(목표)·Reasoning(추론)·Action(행동)·Memory(기억)의 약자. 에이전트가 반복하는 기본 작동 사이클.
ReAct
Reasoning + Acting. AI가 "생각 → 행동 → 관찰 → 다시 생각"을 번갈아 반복하며 문제를 푸는 방식.
검증·안전 장치
용어
쉬운 설명
Evaluator (검증기)
에이전트가 내놓은 결과가 맞는지 점검하는 장치.
Critic
다른 AI가 결과를 비평·검토하는 역할. Evaluator의 한 형태.
HITL
Human-In-The-Loop. 중요한 순간에 사람이 끼어들어 승인·확인하는 것.
Governance (거버넌스)
에이전트가 무엇을 해도 되고 안 되는지 정하는 권한·규칙 체계.
화이트리스트
"이것만 허용" 목록.
블랙리스트
"이것은 금지" 목록.
RBAC
Role-Based Access Control. 역할(직책)에 따라 권한을 다르게 주는 방식.
감사 로그 (Audit Log)
누가·언제·무엇을 했는지 나중에 추적할 수 있게 남기는 기록.
Replanner (재계획)
일이 실패했을 때 계획을 다시 짜는 장치.
Human escalation (사람에게 넘김)
에이전트가 해결 못 하면 사람에게 넘겨 처리하게 하는 것.
Fail-safe
문제가 생겨도 안전한 상태로 멈추거나 무난한 응답을 내놓는 대비책.
구조·설계 철학
용어
쉬운 설명
MSA (멀티 에이전트)
Multi-Agent System. 작고 전문적인 여러 AI가 협업하게 만드는 방식.
Unified Cognition (통합 인지)
하나의 강한 AI가 모든 일을 처리하게 만드는 방식.
Hybrid
위 둘을 섞은 방식. 강한 코어 하나 + 일부만 분산. 실무에서 가장 많이 쓴다.
토폴로지 (Topology)
여러 구성요소를 어떤 모양으로 연결할지에 대한 구조.
Centralized
중앙의 하나가 모두 통제하는 구조.
Hierarchical
상사-부하처럼 위계로 일을 나눠 맡기는 구조.
DAG
Directed Acyclic Graph. 작업 간 순서·의존 관계를 화살표로 그린 그림. 되돌아오는 고리가 없다.
Peer-to-Peer
상하 없이 동등한 구성원끼리 협력하는 구조.
Market-Based
작업을 경매·입찰처럼 나눠 맡는 구조.
Blackboard (공유 칠판)
모두가 같은 저장 공간에 정보를 쓰고 읽으며 협업하는 구조.
Swarm
단순한 규칙을 따르는 다수가 모여 스스로 질서를 만드는 구조.
Cognitive Core (인지 코어)
에이전트의 핵심 두뇌 역할을 하는 메인 AI 모델.
Modular Execution (모듈 실행)
기능을 부품처럼 분리해 따로 실행하는 것.
Orchestration (조율)
여러 부품·AI가 엇박자 없이 협력하도록 지휘·조정하는 것.
Supervisor
하위 작업들을 지시·관리하는 상위 조율자.
Event Bus
구성요소들이 "사건"을 주고받으며 비동기로 소통하는 통로.
CrewAI / LangGraph
에이전트를 만들 때 쓰는 대표적인 개발 도구(프레임워크) 이름.
기억·관찰
용어
쉬운 설명
단기 메모리
지금 진행 중인 대화 내용처럼 잠깐만 기억하는 것.
장기 메모리
사용자 정보·과거 이력처럼 오래 보관하는 기억.
공유 메모리
여러 에이전트가 함께 읽고 쓰는 기억.
외부 메모리
외부 DB나 문서에서 그때그때 찾아 쓰는 정보.
RAG
Retrieval-Augmented Generation. AI가 답하기 전에 외부 자료를 검색해 그 내용을 근거로 답을 만드는 방식.
TTL
Time To Live. 데이터가 자동 삭제되기까지의 보관 기간.
Observability (관찰 가능성)
시스템 안에서 무슨 일이 일어났는지 들여다볼 수 있는 능력.
Reasoning Trace (추론 기록)
AI가 왜 그런 결론에 이르렀는지 그 사고 과정을 남긴 기록.
OpenTelemetry / Datadog
시스템 동작을 수집·관찰하는 데 쓰는 대표 도구.
JSONL
한 줄에 하나의 JSON 데이터를 적는 간단한 기록 파일 형식.
PostgreSQL
널리 쓰이는 데이터베이스(자료 저장소) 프로그램.
기타
용어
쉬운 설명
Bounded Cognition
에이전트의 책임·역할 범위를 명확히 한정하는 것.
Adaptive Topology
상황에 따라 연결 구조를 바꿀 수 있는 능력.
Monolith
모든 기능이 하나로 뭉친 거대한 단일 시스템.
마이크로 에이전트
잘게 쪼갠 작은 에이전트들.
IDE / CLI
IDE는 코드 작성 통합 개발 환경(VS Code 등), CLI는 명령어를 글자로 입력하는 검은 화면 환경. 둘 다 에이전트의 사용 창구가 될 수 있다.
스켈레톤 (Skeleton)
살을 붙이기 전 뼈대만 갖춘 기본 코드 틀.
Mermaid 다이어그램
글자로 적으면 자동으로 그려지는 도식. 구조도를 문서에 넣을 때 쓴다.
시스템 프롬프트
AI에게 "너는 이런 역할이고 이렇게 행동하라"고 미리 알려주는 기본 지시문.
📶 단계별 설명
각 단계별로 뭘하는 건지 알고 싶었다.
STEP 1 — 문제 정의 & "정말 에이전트인가" 판별
이 단계의 목적 무엇을 만들지 명확히 하고, 동시에 정말 에이전트가 필요한지를 판별한다. 챗봇이나 단순 자동화로 충분한 일을 굳이 에이전트로 만들면, 운영 비용만 크게 늘고 관리가 어려워진다. 그래서 이 첫 단계에서 한 번 걸러낸다.
판별 기준: 스스로 계획·실행·수정·반성하는가(자율 행동) + 외부 도구를 부르는가(Tool Use).
진행 흐름 넓은 카테고리 선택 → 구체적 상황 설명 → 성공 기준 → 금지 사항 → 자율성·도구 사용 여부 점검 → (필요시) 챗봇으로 충분한지 최종 판정.
STEP 2 — 작동 루프 8단계
이 단계의 목적 에이전트는 질문에 한 번 답하고 끝나는 게 아니라, 같은 사이클을 반복하며 일한다. 그 한 바퀴를 8단계로 나눠, 각 단계를 어떤 방식으로 구현할지 정한다.
기본 루프: GRAM(Goal·Reasoning·Action·Memory)을 업무용으로 확장한 것이 아래 8단계다.
⚠️ 가장 중요한 점 8단계 중 5번(Evaluator, 결과 검증)과 7번(Governance, 권한 관리)이 비어 있으면 실제 운영에 올리면 안 된다. 사고는 거의 이 두 곳이 비었을 때 난다.
STEP 3 — 설계 철학 선택
이 단계의 목적 에이전트를 "강한 하나로 만들지, 작은 여럿으로 나눌지"라는 근본 방향을 정한다. 이 선택이 이후 구조·비용·복잡도를 크게 좌우한다.
세 가지 입장
MSA(멀티 에이전트): 작고 전문적인 여러 AI가 협업. 유연하지만 조율 비용이 든다.
Unified(통합 인지): 강한 AI 하나가 전부 처리. 단순하지만 한 모델에 의존.
Hybrid: 강한 코어 하나 + 일부만 분산. 실무에서 가장 많이 쓰는 표준.
진행 흐름: 진영 선택 → 그 선택이 의도된 것인지 확인 → 이유 한 줄.
STEP 4 — 토폴로지(연결 구조) 선택
이 단계의 목적 에이전트가 몇 개인지보다 서로 어떻게 연결되는지가 시스템 성격을 결정한다. 연결 구조를 두 축(통제 강도 × 흐름 명시성)으로 나눠 골라본다.
두 축의 의미
통제 강도: 중앙이 강하게 통제하느냐(지휘형) vs 각자 알아서 하느냐(자기조직화).
흐름 명시성: 작업 순서가 명확히 정해졌느냐(명시) vs 상황 따라 흘러가느냐(묵시).
진행 흐름: 큰 분면 선택 → 그 안의 세부 구조 선택.
STEP 5 — 시스템 공식 확정
이 단계의 목적 앞에서 정한 방향을 실제 뼈대로 굳힌다. 세 가지를 정한다: 어떤 AI를 두뇌로 쓸지, 무엇을 분리할지, 어떻게 조율할지.
기억할 원칙: 도구는 풍부하게, 에이전트는 절제. 즉, 기능(도구)은 많이 붙여도 되지만 에이전트 수를 늘리는 건 신중해야 한다. 도구를 나누는 것과 에이전트를 나누는 것은 다르며, 후자는 비용이 훨씬 크다.
완성 공식: 강한 인지 코어 + 분리할 것만 모듈로 + 그래프·공유상태로 조율.
STEP 6 — 메모리(기억) 설계
이 단계의 목적 무엇을, 어디에, 얼마나 오래 기억할지 정한다. 이 선택이 시스템 성격을 좌우한다.
⚠️ 가장 중요한 점 자동 삭제 기간(TTL)이나 삭제 정책이 없는 메모리는 위험하다. 개인정보가 무기한 쌓이고, 저장 비용이 계속 늘고, 오래된 정보로 잘못된 답을 내기 쉽다.
진행 흐름: 기억 종류 선택 → 기억을 어디에 둘지(분산 vs 통합) → 저장·삭제 정책.
STEP 7 — 권한 규칙(거버넌스) & 관찰 장치(Observability)
이 단계의 목적 에이전트가 해도 되는 일과 안 되는 일을 규칙으로 정하고(거버넌스), 무슨 일이 왜 일어났는지 들여다볼 수 있게 만든다(관찰성).
⚠️ 가장 중요한 점 이 두 가지를 비운 채 출시한 에이전트는 거의 100% 사고가 난다. 권한 통제가 없으면 위험한 작업을 막을 수 없고, 관찰 장치가 없으면 사고 원인을 못 찾는다.
진행 흐름: 거버넌스 수준 → 사람 승인이 필요한 지점 → 추론 기록 저장 방식 → 기록 보관 기간 → 절대 금지 행동.
STEP 8 — 검증·재시도 장 치 (자기수정 루프)
이 단계의 목적 챗봇과 에이전트를 가르는 결정적 차이는 스스로 점검하고 다시 하는 루프다. 결과를 검증하는 장치(Evaluator)와, 실패 시 다시 시도하는 장치(Replanner)를 설계한다.
⚠️ 가장 중요한 점 재시도 횟수에 반드시 상한을 둬야 한다. 무제한으로 두면 무한 반복에 빠져 비용이 폭증할 수 있다.
진행 흐름: 검증 주체 → 검증 시점 → 최대 재시도 횟수 → 모두 실패했을 때 처리 → 합격 기준.
STEP 9 — 도구 · 연결 방식 · 사용 창구
이 단계의 목적 에이전트가 쓸 도구를 정하고, 도구를 어떻게 연결할지, 사용자가 어디서 만날지 정한다.
기억할 원칙: 도구는 풍부하게, 에이전트는 절제.
진행 흐름: 기본 도구 선택 → 추가 도구 선택 → 연결 표준 → 사용 창구 → 환영 메시지.
STEP 10 — 6대 핵심 경쟁력 자가진단
이 단계의 목적 지금까지 설계한 에이전트가 실제 운영에 올릴 만한 수준인지 6가지 항목으로 점검한다.
⚠️ 기준: 6개 중 3개 이상에 구체적으로 답하지 못하면 운영 투입은 보류한다.
진행 흐름: 앞의 3개 점검 → 뒤의 3개 점검 → 달성 개수(N/6) 자동 계산.
STEP 11 — 조직의 현재 위치 진단
이 단계의 목적 우리 조직이 에이전트 도입의 어느 단계에 와 있는지 파악한다. 현 위치를 알면 다음에 무엇을 해야 할지 보인다.
배경: 과거 소프트웨어가 "단일 시스템 → 잘게 쪼개기 → 너무 복잡해짐 → 다시 통합" 순서를 밟았는데, 에이전트 시스템도 같은 길을 따라간다.
그래서 이 스킬은 어떤 일을 해주는 것일까?
✅ 이 흐름으로 설계했을 때 얻는 최대 효과
이 11단계를 끝까지 거치면, 단순히 "AI를 하나 만들었다"가 아니라 운영 가능한 수준의 에이전트를 사고 위험 없이 설계할 수 있다. 구체적으로:
운영 중 대형 사고를 사전에 차단한다. 개인정보 유출, 무한 반복으로 인한 비용 폭증, 위험한 자동 실행(삭제·결제 등)을 STEP 1·7·8에서 미리 규칙으로 막는다. 사고 대부분이 이 지점에서 나는데, 그걸 봉쇄한다.
"왜 이렇게 답했는지" 추적할 수 있다. STEP 7의 관찰 장치 덕분에, 문제가 생겼을 때 원인을 찾고 책임 소재를 가릴 수 있다. 추적 안 되는 시스템은 고칠 수도, 신뢰할 수도 없다.
불필요한 과설계를 막아 비용을 아낀다. STEP 1의 판별과 "에이전트는 절제" 원칙이, 챗봇으로 충분한 일을 비싼 에이전트로 만드는 낭비를 걸러낸다.
나중에 확장·인수인계가 쉽다. 각 단계에서 왜 그렇게 정했는지가 기록으로 남는다. 담당자가 바뀌거나 기능을 늘릴 때, 처음부터 다시 분석할 필요가 없다.
설계가 끝나면 바로 개발에 들어갈 수 있다. 시스템 프롬프트·구조 명세서·코드 뼈대가 자동으로 나오므로, 기획과 개발 사이의 공백 없이 곧장 구현으로 넘어갈 수 있다.
"운영해도 되는가"를 객관적으로 판단할 수 있다. STEP 10의 6대 경쟁력과 마지막 투입 체크가, 막연한 감이 아니라 명확한 기준으로 출시 여부를 결정하게 해준다.
🤔 so, 지금까지 이해한 것
이 스킬은 에이전트의 시스템과 가드레일을 잡아준다.
에이전트가 사고없이 잘 뛰어가도록 도와주는 규칙을 넣어준다.
그렇지만 에이전트의 성능이나 능력치를 끌어올려주지는 않는다.
에이전트의 성공은 결국 내가 목적을 제대로 잡고 조직을 기획하고 일의 흐름을 만들어서
이 스킬의 도움을 받아 잘 설계해야 될것이다.
즉, 단지의 애매한 성능은 내가 애매하게 기획해서 나온 결과였다.
(한마디로 콩콩팥팥. 내 머릿속에서 나온 애가 2%부족한 나의 단지 🥲)
🐦🔥 모험가의 앞길
에이전트를 장착하면 내가 최강력 전투 로봇이라도 될 줄 알았다.
근데 내 눈 앞의 단지 (그리고 단도리, 단호박도 사실 비슷한 상황이다 ㅠ)는
나와 같은 모험가 레벨 1의 귀여운 단계에서 슬라임만 때려잡는 정도의 성능을 갖고 있다.
이제 벌써 한번밖에 남지 않은 스터디에서
나는 에이전트 팀을 얻을 수 있을까?
언제쯤 슬라임밭에서 벗어나서 용을 때려잡으러 갈 수 있게 될까?
