seohyun han

[네트워크] idwwt.com으로 DNS 동작 따라가기

sian han — Tue, 23 Jun 2026 16:01:24 +0900

글을 쓸 일이 생겼습니다. 개발자를 위한 글쓰기 플랫폼 rog.idwwt.com에 접속해야겠죠. 주소창에 입력하고 엔터를 칩니다.

이때 컴퓨터 입장에서는 할 일이 있습니다. rog.idwwt.com 이라는 이름만으로는 어디로 가야 할지 모릅니다. 컴퓨터끼리 통신할 때는 결국 IP 주소가 필요합니다. 그러면 rog.idwwt.com 이 어느 IP인지를 먼저 알아내야 합니다.

이 "이름 → IP"를 처리하는 전 세계적인 체계가 DNS(Domain Name System)입니다. 그리고 그 체계 안에서 실제로 "제가 알고 있습니다"라고 답해주는 서버가 네임서버입니다.

네임서버는 역할에 따라 세 종류로 나뉩니다.

루트 서버 — 가장 상위입니다. .com은 저 TLD 서버가 관리해처럼 TLD 서버의 위치만 알려줍니다.
TLD 서버 — .com, .kr 같은 최상위 도메인 단위로 있습니다. 그 도메인은 저 권한 서버가 관리해라고 다음 단계를 안내합니다.
권한 서버 — 특정 도메인의 진짜 답을 들고 있는 서버입니다. idwwt.com의 경우 Cloudflare가 여기에 해당합니다. A 레코드, CNAME 같은 실제 레코드가 여기 등록되어 있습니다.

루트와 TLD는 "저쪽으로 가보세요"만 하고, 권한 서버에서 조회가 끝납니다.

IP를 찾는 순서

rog.idwwt.com에 접속하려 합니다. 그러면 컴퓨터는 우선 내 안에서 먼저 해결하는 것을 시도합니다.

첫 번째, /etc/hosts를 봅니다. 내가 직접 도메인과 IP를 써넣을 수 있는 파일입니다. 127.0.0.1은 "내 컴퓨터 자신"을 가리키는 IP이고, 로컬에서 서버를 띄우고 localhost:3000으로 접속할 수 있는 게 이 줄 덕분입니다.

# localhost is used to configure the loopback interface
# when the system is booting.  Do not change this entry.
##
127.0.0.1       localhost
255.255.255.255 broadcasthost
::1             localhost

예를 들어 여기에 1.1.1.1 idwwt.com을 추가하면, idwwt.com에 접속할 때 DNS 조회 없이 무조건 1.1.1.1로 가게 됩니다.

여기 없으면 두 번째, 로컬 캐시를 봅니다. 한 번 찾아온 답은 버리지 않습니다. 일정 시간 동안 기억해뒀다가 같은 도메인이 오면 바로 꺼내씁니다. 단, 영원히 남아 있지는 않습니다. 각 레코드에는 TTL(Time to Live)이라는 유효기간이 붙어 있고, 그 시간이 지나면 캐시에서 사라집니다.

➜  dscacheutil -q host -a name rog.idwwt.com
name: rog.idwwt.com
ip_address: 116.45.183.36

116.45.183.36 이 지금 rog.idwwt.com 에 연결된 실제 서버 IP입니다. 캐시에 이미 들어 있다는 건, 이전에 한 번 이 도메인에 접속한 적이 있어서 리졸버가 찾아온 답이 저장되어 있다는 뜻입니다.

여기도 없으면 세 번째, 바깥으로 나갑니다. /etc/resolv.conf에 지정된 외부 DNS 서버로 요청을 보내는 겁니다.

조회 순서를 정리하면 이렇습니다.

1. /etc/hosts — 캐시보다 우선, DNS 자체를 건너뜁니다.
2. 로컬 캐시
3. /etc/resolv.conf에 지정된 외부 DNS

/etc/resolv.conf 에는 현재 KT DNS 서버 주소가 적혀 있습니다. 리졸버 주소를 지정하는 파일입니다. 여기 적힌 서버로 DNS 질의가 나갑니다. 비어 있으면 어디에 물어야 할지 모르니까 조회가 안 됩니다.

이 값은 어떤 네트워크에 연결하느냐에 따라 달라집니다. 공유기에 연결하면, 공유기가 DHCP로 IP를 배정해주면서 DNS 서버 주소도 함께 알려줍니다. 그 값이 /etc/resolv.conf에 자동으로 적히는 겁니다. KT 회선의 공유기라면 KT DNS를, SK 회선이라면 SK DNS를 알려주는 식입니다.

그렇지만 macOS 네트워크 설정에서 DNS를 수동으로 지정하면 DHCP가 알려주는 값을 무시합니다. 공유기가 KT DNS를 쓰라고 알려줘도, 이미 지정해놨으니 무시하는 것입니다.

만약 수동 지정을 하는데 8.8.8.7처 럼 오타를 내면 DNS 조회가 안 됩니다. 8.8.8.7은 존재하지 않기 때문에 응답이 없고, 그러면 idwwt.com의 IP를 아무도 알려주지 못하니까 접속이 안 됩니다. 이 경우에는 IP 주소를 직접 치면 됩니다. 브라우저에 116.45.183.36을 직접 입력하면 DNS 조회 없이 바로 연결됩니다. DNS는 이름을 IP로 바꿔주는 역할만 하기 때문에, IP를 이미 알고 있으면 DNS가 없어도 상관없습니다.

DHCP(Dynamic Host Configuration Protocol)

DHCP 는 네트워크에 연결한 기기에 자동으로 설정값을 배정해주는 프로토콜입니다. DHCP가 배정해주는 것은 IP 주소, 서브넷 마스크, 게이트웨이, DNS 서버입니다. /etc/resolv.conf에 자동으로 값이 적히는 이유는, Wi-Fi 연결 시 DHCP가 알려준 값이 자동으로 들어간 것입니다.

리졸버

/etc/resolv.conf 에 지정된 외부 DNS 서버, 즉 바깥으로 나갔을 때 도달하는 곳이 리졸버(Recursive Resolver)입니다.

8.8.8.8(Google), 1.1.1.1(Cloudflare), 아까 본 203.248.252.2(KT) 같은 것들이 전부 리졸버입니다. 운영 주체가 다를 뿐 역할은 동일합니다. 내 컴퓨터 대신 루트 서버부터 권한 서버까지 순서대로 찾아다니며 최종 답을 가져오는 서버입니다.

내가 "이 도메인 IP가 뭐야?" 라고 한 번만 물어보면, 리졸버가 나 대신 전 과정을 돌아다니며 최종 답을 통째로 가져옵니다. 이걸 재귀 조회(recursive query)라고 합니다.

조회 경로는 이렇습니다.

루트 서버 → TLD 서버(.com 담당) → 권한 서버(idwwt.com 담당) → 진짜 IP

여기서 루트 서버, TLD 서버, 권한 서버 — 이 세 가지가 전부 네임서버(Name Server)입니다. 역할이 달라서 이름이 다를 뿐, 본질은 같습니다. "내가 아는 범위에서 답해주거나, 모르면 다음 담당자를 알려주는 서버"입니다.

네임서버라는 단어가 두 가지 맥락에서 쓰입니다.

하나는 DNS 계층 구조를 설명할 때입니다. 루트 서버, TLD 서버, 권한 서버 — 이 셋을 통칭해서 네임서버라고 부릅니다.
다른 하나는 "어떤 DNS 서비스를 쓰냐"를 말할 때입니다. "네임서버를 Cloudflare로 바꿨다"는 말은, 그 중 권한 서버 역할을 Cloudflare 에 맡겼다는 뜻입니다. 루트 서버나 TLD 서버는 공공 인프라라 우리가 선택할 수 있는 영역이 아닙니다.
같은 단어인데 앞에서는 계층 전체를 가리키고, 뒤에서는 권한 서버 하나만 가리킵니다. 문맥으로 구분해야 합니다.

루트 서버

DNS 계층의 맨 꼭대기입니다.

루트 서버가 아는 건 딱 하나입니다. .com은 어느 TLD 서버가 담당하는지, .kr은 어느 TLD 서버가 담당하는지. 그 이상은 모릅니다. idwwt.com의 IP가 뭔지는 전혀 관심이 없습니다. 그냥 ".com 관련이면 저 TLD 서버한테 물어봐" 라고만 합니다.

TLD 서버

루트 서버 다음 단계입니다. TLD(Top-Level Domain)는 도메인 맨 뒤 조각, .com, .net, .kr, .io 같은 것들입니다. TLD 서버는 그 TLD에 속한 도메인들이 어느 권한 서버를 쓰는지 알고 있습니다.

.com TLD 서버를 예로 들면, 세상의 모든 .com 도메인이 어느 권한 서버에 등록돼 있는지 목록을 갖고 있습니다. 리졸버가 "idwwt.com 어디야?"라고 물으면, TLD 서버는 "idwwt.com은 Cloudflare가 관리해"라고 NS 레코드로 알려주고 끝냅니다. 최종 IP는 여기서도 나오지 않습니다.

권한 서버(Authoritative Server)

여기서 진짜 답이 나옵니다. 특정 도메인의 실제 레코드(A, CNAME, MX 등)를 직접 들고 있는 서버입니다. idwwt.com이라면 Cloudflare가 권한 서버 역할을 합니다.

리졸버가 "idwwt.com의 IP가 뭐야?"라고 물으면, 권한 서버는 "116.45.183.36이야"라고 A 레코드를 돌려줍니다. 추측이나 위임이 아니라 실제 등록된 값 그대로입니다. 도메인을 구입한 뒤 Cloudflare 같은 서비스에서 레코드를 설정하는 게 바로 이 권한 서버에 데이터를 쓰는 행위입니다.

각 단계가 직접 최종 답을 주는 게 아니라 "다음엔 저쪽으로 가보세요"라고 길만 알려줍니다. 이걸 위임(delegation)이라고 합니다.

그리고 이 "어느 네임서버에게 가라"는 이정표가 바로 NS 레코드입니다. A나 CNAME처럼 도메인을 목적지로 연결하는 게 아니라, 이 도메인의 관리를 누가 맡고 있는지를 가리키는 레코드입니다.

idwwt.com의 NS 레코드가 Cloudflare를 가리키고 있기 때문에, 리졸버가 TLD 서버에 물어봤을 때 "Cloudflare한테 가봐"라는 답을 받을 수 있는 겁니다.

NS 레코드는 루트 서버, TLD 서버, 권한 서버 모두 갖고 있습니다. 역할은 조금 다릅니다.

서버	NS 레코드 예시	의미
루트 서버	.com NS a.gtld-servers.net	"`.com`은 저 TLD 서버가 담당해" (위임)
TLD 서버	idwwt.com NS toby.ns.cloudflare.com	"`idwwt.com`은 저 권한 서버가 담당해" (위임)
권한 서버	idwwt.com NS toby.ns.cloudflare.com	"이 존의 담당 서버가 나야" (자기 선언)

루트 서버와 TLD 서버의 NS 레코드는 "다음엔 저쪽으로"라는 위임 이정표이고, 권한 서버의 NS 레코드는 "이 도메인의 담당이 나야"라는 선언입니다. 같은 레코드 타입이지만 누가 들고 있느냐에 따라 역할이 달라집니다.

참고로 리졸버가 루트, TLD, 권한 서버를 순서대로 거치는 건 맞지만, 체인처럼 넘어가는 게 아닙니다. 리졸버가 매번 직접 질의합니다.

리졸버 → 루트 서버     "`.com` TLD 서버 주소 알려줘"
리졸버 ← 루트 서버     "여기야: a.gtld-servers.net"

리졸버 → TLD 서버     "`idwwt.com` 권한 서버 주소 알려줘"
리졸버 ← TLD 서버     "여기야: toby.ns.cloudflare.com"

리졸버 → 권한 서버    "`idwwt.com` IP 알려줘"
리졸버 ← 권한 서버    "116.45.183.36"

리졸버 → 내 컴퓨터    최종 답 전달

루트 서버가 TLD 서버로 직접 넘기는 게 아닙니다. 루트 서버는 리졸버한테 TLD 서버 주소를 알려주고 끝냅니다. 리졸버가 그 주소를 들고 TLD 서버로 새로 질의하는 겁니다. 매번 리졸버가 출발점입니다.

레코드 타입 — A와 CNAME

Cloudflare 같은 네임서버 안에는 DNS 관리 영역이 있습니다. 거기에 레코드를 등록하는 겁니다. idwwt.com 은 카페24에서 샀지만 네임서버는 Cloudflare로 옮겼습니다. CNAME이나 A 레코드를 거기서 관리하고 있습니다.

레코드 타입 중 일단 두 개만 알면 됩니다. A랑 CNAME.

A 레코드는 도메인을 IP 주소로 직접 연결합니다. 무조건 숫자, IP 주소로만 등록할 수 있습니다.

CNAME은 도메인을 다른 도메인으로 연결합니다. 문자열로 등록하는 겁니다. 문자열끼리 매핑을 하는 타입이 CNAME입니다.

권한 서버는 어디를 쓰느냐에 따라 지원하는 기능이 달라집니다. 도메인을 산 곳(카페24, 가비아 등)에서 기본으로 제공하는 DNS를 그대로 쓸 수도 있고, Route 53이나 Cloudflare 같은 전문 DNS로 옮길 수도 있습니다.

레지스트라 내장 DNS

레지스트라 내장 DNS(카페24, 가비아 등)는 도메인을 샀을 때 기본으로 딸려오는 겁니다. A, CNAME, MX 정도 기본 레코드는 되는데, 그 이상을 기대하기 어렵습니다. 와일드카드 안 되고, 레코드 타입도 제한적이고, TTL 최솟값도 높아서 설정 바꿔도 반영이 느립니다. 관리 UI도 단순합니다. 간단한 개인 사이트 수준이면 충분하지만, 뭔가 특이한 설정이 필요하면 막히는 경우가 생깁니다.

전문 DNS (Route 53, Cloudflare 등)

전문 DNS(Route 53, Cloudflare 등)는 DNS가 본업이라 지원 범위가 넓습니다. 와일드카드, SRV, CAA 같은 레코드도 되고, Apex 도메인에 CNAME 못 쓰는 제약을 우회하는 기능도 있습니다. TTL을 거의 0에 가깝게 낮출 수 있어서 변경 사항이 빠르게 반영됩니다.

CNAME이 필요한 이유

서브도메인을 여러 개 만들었습니다. 홈서버 IP가 바뀌면 연결된 모든 서브도메인을 일일이 수정해야 합니다. 수백 개가 되면 수백 개를 전부. 그래서 서브도메인은 CNAME으로, 루트 도메인은 A 레코드로 등록합니다. IP가 바뀌어도 idwwt.com A 레코드 하나만 수정하면 나머지가 다 따라옵니다. 변수화를 하는 겁니다.

한 가지 주의할 점이 있습니다. idwwt.com 같은 루트 도메인(apex domain) 자체에는 CNAME을 쓸 수 없습니다. DNS 표준 제약입니다. CNAME은 반드시 서브도메인에만 씁니다.

rog.idwwt.com 에 접속하면 → idwwt.com으로 가봐 → idwwt.com은 116.45.183.36이네 → 연결. 중간에 하나 거쳐서 치환으로 되게끔 하는 겁니다. IP가 바뀌어도 `idwwt.com` A 레코드 하나만 수정하면 나머지가 다 따라옵니다.

실제 레코드로 읽어보면

지금까지 배운 걸 실제 설정을 통해 봐봅시다.

idwwt.com — 카페24 + Cloudflare

카페24 도메인 관리 화면을 보면 아래와 같습니다.

도메인 구입처: 카페24
현재 네임서버: toby.ns.cloudflare.com, vida.ns.cloudflare.com

도메인은 카페24에서 샀지만, 권한 서버는 Cloudflare로 바꿔놓은 상태입니다. .com TLD 서버에는 지금 이렇게 등록되어 있습니다.

idwwt.com  NS  toby.ns.cloudflare.com
idwwt.com  NS  vida.ns.cloudflare.com

누군가 `idwwt.com`에 접속하면, 리졸버가 `.com` TLD 서버에 물어봤을 때 "Cloudflare한테 가봐"라는 답을 받고, Cloudflare 권한 서버에서 최종 IP를 받아오게 됩니다.

[AWS] 서로 다른 VPC에 있는 EC2에서 RDS로 연결하기 (VPC 피어링)

sian han — Wed, 17 Jun 2026 14:56:52 +0900

EC2에서 RDS로 접속하려는데, 둘이 서로 다른 VPC에 있어 McpError('Connection closed') 같은 연결 오류가 나는 상황. 이럴 때 VPC 피어링으로 어떻게 연결하는지 정리한다.

AWS 네트워크 관련 개념은 예전 글에서 한 번 정리했는데, 이번 작업을 이해하는 데 필요한 만큼만 다시 짚고 넘어가자.

VPC

VPC(Virtual Private Cloud) 는 AWS 에서 논리적으로 격리된 네트워크 공간이며, 기본적으로 서로 다른 VPC 에 있는 리소스끼리는 통신이 불가능하다.
VPC 는 하나의 리전 안에만 속하며, 여러 리전에 걸칠 수 없다.

서브넷

서브넷은 VPC 네트워크 공간을 잘게 나눈 하위 공간이다.
EC2 나 RDS 같은 리소스는 VPC 에 직접 놓이는게 아니라, 반드시 어떤 서브넷 안에 배치된다.
각 서브넷은 하나의 가용 영역(AZ)에 연결되며, 여러 AZ 에 걸칠 수 없다.
즉 서브넷 하나 = 하나의 AZ 이다.

라우팅 테이블

라우팅 테이블은 네트워크 트래픽이 어디로 가야 하는지 알려주는 규칙 목록이다.
라우팅 테이블은 '서브넷 단위' 로 붙는다. VPC 전체에 일괄 적용되는 게 아니라, 각 서브넷에 하나씩 연결된다. 따라서 어떤 서브넷이 너떤 라우팅 테이블을 쓰는지는 중요한 포인트이다.
서브넷에 별도 테이블을 명시하지 않으면 VPC 기본 테이블을 쓰지만, 명시적으로 다른 테이블을 연결해두면 기본 테이블에 아무리 라우트를 추가해도 그 서브넷에는 적용되지 않는다.

상황

EC2와 RDS가 서로 다른 VPC에 놓여 있는 구성이다.

리소스	VPC	IP
agent-ec2	vpc-001 (vpc-dev)	10.0.x.x
RDS rds-production	vpc-002 (vpc-prod)	10.1.x.x

agent-ec2에서 rds-production에 접속하려고 하는데, 둘은 서로 다른 VPC에 위치해 있다.
이 경우 기본 상태로는 통신이 되지 않는다.

VPC 피어링 연결을 통해 서로 다른 VPC에 걸쳐 통신 할 수 있다.

VPC 피어링

VPC 피어링은 서로 다른 두 VPC를 직접 연결하는 전용 통로다.

인터넷을 거치지 않고 프라이빗 IP로 통신할 수 있게 해주는 AWS 기능이다.

VPC 피어링이 실제로 동작하려면 아래 3가지가 모두 갖춰져야 한다.

이때 하나라도 빠지면 연결되지 않는다.

VPC 피어링 연결 : 두 VPC 사이에 통로가 뚫려 있는가
라우팅 테이블 : EC2/RDS 서브넷이 실제로 쓰는 테이블에 피어링 라우트가 있는가
RDS 보안 그룹 : RDS 인바운드가 EC2의 접근을 허용하는가

▶ Step 1. VPC 피어링 연결 생성 — 통로 뚫기

VPC → 피어링 연결 → 피어링 연결 생성

요청자 VPC : vpc-001 (vpc-dev)
수락자 VPC : vpc-002 (vpc-prod)

요청자, 수락자 구분은 통신 방향과 아무 상관이 없다.
VPC 피어링은 두 VPC 를 연결할 때 한쪽이 "연결하자"고 요청을 보내고, 다른 쪽이 수락하는 handshake 절차를 거친다.
따라서 이것은 그냥 역할일 뿐이며, 요청자라고 해서 트래픽을 보내기만 하는 것도 아니고, 수락자라고 해서 받기만 하는 것도 아니다.

그럼 요청자, 수락자를 반대로 입력해도 되나 ? >> 된다
두개 역할을 반대로 입력해도 결과는 완전히 동일하다. 요청자, 수락자가 실제로 의미를 갖는 것은, 다른 AWS 계정의 VPC 와 피어링을 할때 이다. 그때는 상대 계정 소유자가 수락 버튼을 눌러줘야 하기 때문이다.

통신이 어느 방향으로 흐를지를 결정하는 것은 요청자 / 수락자가 아니라, 글 뒤쪽에 나오는 라우팅 테이블과 보안그룹이다.

라우팅 테이블 : 어느 VPC 에서 어느 대역으로 가는 길을 열지
보안 그룹 : 어느 IP 의 인바운드를 허용할지

VPC 피어링 연결을 생성한 후 작업 → 요청 수락을 통해 활성화 한다.

이제 통로 뚫기가 완료되었다.

▶ step 2. 라우팅 테이블 설정

피어링 통로를 만들었어도, 각 VPC가 "저쪽으로 가려면 피어링을 타라"는 규칙을 모르면
통신이 되지 않는다. 그 규칙을 적어주는 게 라우팅 테이블이다.

앞에서 짚었듯, VPC를 만들면 메인 라우팅 테이블이 하나 자동 생성되고, 아무것도 지정하지 않은 서브넷은 전부 이 메인 테이블을 따라간다. 그러다 특정 서브넷에 다른 라우팅 테이블을 명시적으로 연결하면, 그 서브넷만 메인에서 떨어져 나와 지정한 테이블을 따른다.

그리고 EC2 인스턴스는 항상 하나의 서브넷에 할당된다. 인스턴스를 시작할 때 서브넷을 지정해야 하고, 한 번 정해지면 그 인스턴스의 기본 네트워크 위치가 된다. 따라서 라우트를 추가할 때는 "VPC의 기본 테이블"이 아니라 그 인스턴스의 서브넷이 실제로 쓰는 테이블을 찾아야 한다.

▷ 2-1. EC2 서브넷의 라우팅 테이블에 추가

EC2 → 인스턴스 → 네트워킹 → 서브넷ID → 라우팅 테이블 → 라우팅 테이블 연결 편집

여기서 step 1 에서 생성한 VPC 피어링 연결 ID 를 선택해서 추가한다.

▷ 2-2. RDS 서브넷의 라우팅 테이블에도 추가

라우팅은 EC2 쪽만 하면 안 되고, RDS가 위치한 서브넷의 라우팅 테이블에도 추가해야 한다.

이유는 라우팅이 방향마다 따로 필요하기 때문이다. EC2가 RDS로 패킷을 보낼 때(가는 길)와, RDS가 그 응답을 EC2로 돌려보낼 때(오는 길)는 각각 출발하는 쪽의 라우팅 테이블을 참조한다. EC2 쪽만 설정하면 패킷이 RDS까지 가긴 하지만, RDS가 답을 돌려보낼 길을 몰라 통신이 반쪽만 되고 끊긴다.

RDS(특히 Aurora)는 여러 서브넷에 걸쳐 배치될 수 있으므로, 먼저 RDS가 어느 서브넷을 쓰는지부터 확인한다.

Aurora and RDS → 데이터베이스 → 인스턴스 → VPC ID 확인
Aurora and RDS → 서브넷 그룹 → 위에서 확인한 VPC 내의 서브넷 그룹 → 서브넷 ID → 라우팅 테이블 연결 편집

여기서 동일하게 step 1 에서 생성한 VPC 피어링 연결 ID 를 선택하여 추가한다.

위와 같이 EC2 와 Aurora RDS 이 위치한 서브넷이 어떤 라우팅 테이블을 실제로 사용하는지 먼저 확인한 뒤, 그 테이블에 라우트를 추가해야한다.

▶ step 3. RDS 보안 그룹 생성 및 연결

step 1 에서 길을 뚫어주고, step 2 에서 이 길로 가면 된다고 안내판을 세워줬다.
step 3 는 출입 허가증을 발급하는 절차라고 보면 되겠다.

보안 그룹은 RDS 앞에 선 방화벽이다. 허용 규칙만 설정할 수 있고, 기본적으로 모든 인바운드가 차단돼 있다. 그래서 라우팅을 통해 패킷이 RDS 문 앞까지 도착해도, 보안 그룹 인바운드에 그 출처가 등록돼 있지 않으면 문턱에서 막힌다.

참고: 보안 그룹은 RDS 쪽만 열면 된다.
(단, EC2 아웃바운드를 일부러 제한해둔 경우라면 RDS 포트로 나가는 것이 허용돼 있는지만 확인한다.)

▷ 3-1. EC2의 프라이빗 IP 확인

먼저 RDS 인바운드에 등록할 EC2의 프라이빗 IP를 확인한다.

EC2 → 인스턴스 → 해당 인스턴스 → [네트워킹] 탭 → 프라이빗 IPv4 주소
여기 표시되는 값(예: 10.0.17.105)이 RDS 인바운드 소스로 넣을 IP다.

▷ 3-2. RDS 보안 그룹 인바운드 규칙 수정

RDS → 데이터베이스 → 해당 인스턴스 → [연결 및 보안] 탭
→ 연결된 보안 그룹 클릭 → [인바운드 규칙] 탭 → [인바운드 규칙 편집]
→ [규칙 추가]

RDS에 보안 그룹이 여러 개 연결돼 있을 수 있다. 규칙은 합집합으로 적용되므로, EC2 접근용으로 목적이 분명한 보안 그룹(예: rds-prd-access처럼 dev 대역 IP가 이미 들어 있는 것) 하나를 골라 거기에 추가하면 된다. 내부 통신용 보안 그룹에 섞지 않는 편이 나중에 관리하기 깔끔하다.

소스에 IP /32 대신 EC2의 보안 그룹 ID를 넣을 수도 있다. 그러면 EC2가 재시작돼 IP가 바뀌어도 규칙을 고칠 필요가 없다. 단, 이 방식은 두 리소스가 같은 VPC이거나 VPC 피어링으로 연결된 경우에만 동작한다.

정리

서로 다른 VPC에 있는 EC2와 RDS를 연결하려면 VPC 피어링을 사용할 수 있다. 다만 단순히
피어링 연결만 생성한다고 통신이 되는 것은 아니며, 다음 3가지가 모두 갖춰져야 한다.

피어링 연결 생성 - 두 VPC 사이의 전용 통로
라우팅 테이블 설정 - EC2와 RDS가 실제로 사용하는 서브넷의 테이블 양쪽에 추가 (기본 테이블 != 실제 사용 테이블일 수 있음)
보안 그룹 설정 - RDS 인바운드에 EC2 IP를 명시적으로 허용

위 세 가지를 갖추면 VPC 피어링을 통해 서로 다른 VPC에 위치한 리소스끼리도 프라이빗 IP로 통신할 수 있다.

[AX] 비개발자 팀을 위한 두 번째 Claude 세미나 : 절반의 성공

sian han — Mon, 15 Jun 2026 17:46:24 +0900

1회차를 끝낸 직후의 상태

1회차 글 에서 적었듯이, 1회차에서는 내가 놓친 것들이 많았다.

1회차에서 준비한 Hands-On 은 매끄럽지 않았다. vscode + 터미널 조합으로 Claude Hands-On 을 구성하여 환경설치 단계에서 참여자들은 무너졌고, 내가 개발자 Hands-On 에 참석하며 좋다고 느꼈던 방식인 git branch(실습용/완성본) 형식으로 안내하여 결국 아래와 같은 피드백으로 이어졌다.

"모든 것이 다 생소해서 어려웠습니다..."

세션이 끝난 직후 솔직히 조금 우울했다. 쉽게 전달하는 것에 초점을 맞추면서 10시간을 준비했는데, 많은 것이 닿지 않은 것 같았다.
그래도 2회차 세미나는 이틀 뒤였고, 우울할 시간이 없었다. 1회차에서 받은 피드백을 참고하여 2회차에서는 무엇을 바꿔야 더 잘 전달할 수 있을지 정리해야 했다.

2회차에서는 무엇을 바꿨는가

1. 도구 — 터미널·VS Code·Git을 전부 뺐다

1회차에 쓴 Claude Code + 터미널 조합은 비개발자에게 진입 장벽이 너무 높다는 게 확인됐다.
그래서 2회차는 Claude Desktop으로 준비했다, Claude Desktop은 설치하고 로그인만 하면 끝난다.

GitHub clone, 브랜치 이동, 영어 에러 메시지 등 1회차에서 참여자들의 에너지를 뺐던 것들을 전부 없앴다.

2. 목표를 푸는 방식 — 수단을 바꿨다

목표 자체는 1회차와 같았다.

"나도 해볼 수 있겠는데?"라는 감각
Claude에게 업무를 위임함으로써 정말 집중해야 할 일에 집중하는 작업 방식에 대한 동경

이것이 1·2회차를 통틀어 내가 가장 만들고 싶었던 결과였다.

1회차에서는 직접 손으로 만들어보면 Claude에 업무를 위임한다는 감각을 알려줄 수 있을 거라고 생각했다.
그래서 아주 쉽게 Skill을 만들 수 있도록 1회차 세션을 설계했고, 이렇게 직접 Skill을 만들어보는 경험이 세미나가 끝난 뒤에도 "나 혼자서도 만들어볼 수 있겠다"는 자신감으로 이어질 거라고 기대했다.

그런데 이런 방법이 효과를 보려면, 먼저 동경을 충분히 불러일으킨 다음 쉽게 만드는 방법을 알려줘야 사람들이 더 적극적으로 따라오는건데, 1회차에는 그 부분이 부족했던 것 같다. 그래서 2회차에서는 직접 만들어보는 데 초점을 맞추기보다, 동경을 불러일으키기 위해 다른 마케터들이 Claude를 어떻게 활용하고 있는지 사례를 보여주는 데 절반을 할애했다.

동경을 충분히 불러일으키기
쉽게 시작하는 방법을 알려주기

이렇게 순서를 바꾼 것이다.

세션 구성

세션은 크게 세 파트로 나눴다.

Part 1. 해외 사례 — "저 사람도 했네 = 나도 할 수 있어 !"

개발을 전혀 모르는 마케터들이 Claude로 어떻게 업무를 하고 있는지 사례를 보여줬다. 그중에서 Anthropic의 퍼포먼스 마케터 Austin의 사례가 가장 좋다고 생각했다.

'Claude를 만든 회사의 마케터'라는 점이 신뢰를 주면서도, 시작점만큼은 우리와 다르지 않았기 때문이다. Austin은 터미널을 어떻게 켜는지도 몰랐다. Claude Code가 처음 나왔을 때 "이게 뭔지 모르겠다"고 했고, 터미널을 어떻게 여는지 구글에 직접 검색했을 정도였다.

그랬던 그가 지금은 다양한 도구를 직접 만들어낸다. 광고 시안 생성을 위한 Figma 플러그인을 만들어, 기존에는 프레임을 일일이 복사하고 텍스트를 붙여넣어야 했던 작업을 단 한 번의 클릭으로 수십 개의 광고 변형을 만들어내도록 바꿨다. 이를 통해 대량의 크리에이티브를 업데이트하는 시간을 약 30분에서 30초로 줄였다. 또 구글 광고 문구 생성 워크플로우를 만들어, 슬래시 명령 하나로 브레인스토밍부터 업로드용 CSV 파일 생성까지 이어지고, 브랜드 톤앤매너와 제품 정확성, 광고 모범 사례까지 자동으로 검증하도록 했다.

물론 Austin이 처음부터 이런 도구를 만들 수 있었던 건 아니다. 그는 Claude가 어떻게 동작하는지 확인하기 위해, 가장 먼저 실험 삼아 간단한 계산기 앱을 만들어봤다고 한다. 그렇게 이전에는 개발자에게 요청해야 했던 기술적인 작업들을 직접 도구로 만들어 해결하면서, '원하는 것'과 '직접 만드는 것' 사이의 격차를 획기적으로 줄였다.

내가 이 사례를 가장 앞에 둔 이유는 분명하다. "저 사람도 터미널을 못 켰는데 저렇게까지 했네"라는 느낌, 그게 곧 "나도 할 수 있겠다"로 이어지길 바랐기 때문이다.

Part 2. Claude Desktop 사용법 — 도구의 세 가지 모드

1회차에서 가장 큰 장벽은 환경 설치였다. 설문에서도 3명 중 2명이 가장 어려웠던 부분으로 환경 설정을 꼽았고, "내 화면은 진행이 멈춰 있는데 설명은 계속 이어져서 혼동이 생겼다"는 피드백도 있었다. 그래서 이번에는 터미널도, Git clone도 없이, 설치하고 로그인만 하면 바로 쓸 수 있는 Claude Desktop으로 안내하기로 했다.

Claude Desktop에는 세 가지 모드가 있다. 이걸 '언제, 무엇을 쓰는지'로 구분해서 설명했다.

Chat — 단발성 질문, 1회성 작업
Cowork — 같은 맥락을 이어가는 반복 작업 (ChatGPT의 프로젝트 폴더 같은 개념)
Code — 컴퓨터의 파일을 직접 읽고/쓰고/실행할 수 있는 모드

권장 순서도 같이 안내했다.

"처음에는 Chat부터 시작해보세요. 같은 작업이 3번 이상 반복되면 Cowork로, 아예 자동화하고 싶으면 Code로 넘어오시면 됩니다."

이 순서를 명시한 건 의도가 있었다.

1회차 이후

"어디서부터 시작해야 할지 모르겠다",
"우선 하나라도 부딪혀보는 게 좋을지, 기초부터 이해하고 시작하는 게 좋을지 모르겠다"

와 같은 피드백이 여럿 있었기 때문이다. 이번엔 자연스러운 진입 경로를 보여주고 싶었다. "막연한 큰 도구"가 아니라 "작은 단계가 있는 도구"로 보이게 하는 게 목표였다.

Part 3. Skill 업그레이드 라이브 시연

1회차때 함께 만들어보았던 Skill 가져와서, 그 자리에서 기능을 추가하는 모습을 보여줬다.

1회차에서 "Skill을 처음부터 만드는 과정" 을 보여줬다면, 2회차에서는 "이미 있는 Skill을 키워가는 과정"을 보여줬다.

이걸 시연으로 넣은 이유는, 0에서 1을 만드는 것보다 1을 2로 만드는 게 사실 더 자주 일어나는 일인데, 사실 이건 하나도 어렵지 않다는 걸 보여주고 싶었기 때문이다. 첫 Skill을 만든 다음에 어떻게 발전시켜 나가는지에 대한 그림이 없으면, 첫 시도가 마지막 시도가 되기 쉽다.

결과적으로 이 시연은 2회차에서 가장 반응이 좋았던 콘텐츠였다. 설문에서 '가장 도움이 됐던 콘텐츠'로 응답자의 80%가 이 라이브 시연을 꼽았다. 추상적인 개념 설명보다, 눈앞에서 Skill이 실제로 자라나는 걸 보여주는 쪽이 훨씬 잘 전달된 것이다.

다만 한계도 분명했다. 보는 것과 직접 하는 것 사이의 거리는 여전히 컸다. "흐름은 이해했지만 직접 하려면 막막할 것 같다", "보면서 흥미는 생겼는데 직접 해볼 자신은 아직 없다"는 응답이 있었다. 시연은 동경을 일으키는 데까지는 성공했지만, 그 동경을 '내가 직접 만들 수 있다'는 자신감으로 바꾸려면 결국 직접 손을 움직여보는 실습이 필요하다는 걸 알 수 있었다.

Part 4. API Key 안전 수칙 안내

이 세미나 이후에 누군가 혼자 Skill을 만들어 볼 수 있는데, 광고주 API를 다루는 작업이라면 사고가 날 수 있다.
키워드 추가, 입찰가 조정, 캠페인 삭제 같은 작업은 반드시 확인을 거쳐야 하고, 사실 의도하지 않았더라도 AI가 자체적으로 실행해버릴 수 있다. 그렇기 때문에

API Key는 절대 대화창에 붙여넣지 않을 것
처음에는 테스트 계정이나 일시정지된 캠페인에서 진행할 것

등의 최소한의 안전 수칙을 공유했다

Part 5. 도파민 그래프 이야기

"지금은 도파민이 터지는 시점입니다. 0에서 1을 만드는 건 재미있어요. > 근데 1을 2로, 3으로 만들면서 유지하는 건 그렇게 재미있지 않을 수 있습니다. 그때부터는 도파민이 아니라, 이 문제를 진짜 풀고 싶다는 의지가 필요합니다"

Part 6. Claude 사내 스터디 수요조사

AI 챔피언, AI 히어로, AI 특공대 등 다양한 이름으로 불리는 AX 조직의 구성원들은 비개발자가 AI 에이전트를 업무에 활용할 수 있도록 돕는 역할을 한다. 이 과정에서 가장 중요한 것은 "온도를 맞추는 일" 이라고 했다. 혼자 앞서 나가면서 이것저것 설명해봐야 온도가 끌어올려지지 않은 상태에서는 아무것도 전달 할 수 없다.

1회차 세미나를 진행한 후 받은 피드백을 통해 사람들의 관심도가 꽤 높다는걸 알 수 있었다.

2회차 끝나고 나면 같이 시작해볼 온도가 맞춰진 사람이 있을 것 같았다.

2회차 세미나가 끝나는 시점은 스터디를 진행하기에 아주 적기라고 생각했다.

스터디를 통해 Claude를 수족처럼 부릴 수 있는 사람이 단 한 명이라도 생긴다면, 정말 많은 문제를 해결할 수 있을 것 같았다.

그래서 'AI 어쩌구'로서 사내 스터디를 기획했고, 홍보하는 시간을 가졌다.

그리고 결과는 기대 이상이었다.

2회차 세미나를 완전히 이해한 사람은 0% 이지만 스터디 참여 희망은 100%였다.

보통 "어려웠다"는 곧 "이탈"로 이어지는데, 이번엔 "어려웠지만 더 배우고 싶다"로 연결됐다.

준비하는 내내 고민했던 '온도 맞추기'가 통했다는 의미로 느껴졌다.

피드백으로 본 2회차 세미나 결과

이해도부터 보면 냉정한 편이었다. "많이 어려웠다"가 40%, "흐름은 이해했지만 직접 하려면 막막할 것 같다"가 40%, "반 정도 이해했다"가 20%였다. "개발 실전에 바로 투입된 느낌", "cmd라는 걸 처음 접했다", "기본 용어를 모르고 들어갔다"는 피드백이 반복적으로 나왔다. 도구 장벽은 걷어냈지만, 그 아래에 개념 장벽이 남아 있었던 것이다.

그런데 그 어려움이 이탈로 이어지지 않았다. 오히려 참여자 전원(100%)이 다음 스터디에 참여하고 싶다고 답했다.

콘텐츠별로는 반응이 갈렸다. 가장 도움이 됐던 콘텐츠로는 Skill 업그레이드 라이브 시연(80%)이 가장 많이 꼽혔고, Claude Desktop 사용법(60%), 해외 마케터 사례(40%)가 뒤를 이었다. 추상적인 설명보다, 눈앞에서 무언가가 실제로 만들어지고 자라나는 걸 보여주는 쪽이 잘 전달됐다.

특히 의미 있었던 건, 해외 사례가 동기 부여에 실제로 작동했다는 점이다. 한 응답자는 세션 후 "전보다 훨씬 친근하게 느껴진다. 나도 쓸 수 있을 것 같다"고 답했다. 1회차와 달리 이번에 새로 넣은 Austin·Sarah·Harold의 사례가 "나도 해볼 수 있겠다"는 감각으로 이어진 것이다. 이번 세션에서 가장 만들고 싶었던 결과가 바로 이거였다.

물론 한계도 분명했다. "직접 실습하면서 배웠으면 더 친근했을 것 같다", "1부터 10까지 같이 보면서 교육받고 싶다", "기초 용어를 미리 알았으면 이해도가 높았을 것"이라는 요청이 반복됐다. 사례와 시연으로 동경을 일으키는 데까지는 성공했지만, 그 동경을 '내가 직접 만들 수 있다'는 자신감으로 바꾸려면 결국 직접 손을 움직여보는 실습이 필요하다는 걸 다시 확인했다.

1·2회차를 모두 끝낸 시점에서 배운 것

"나도 해볼 수 있겠는데?"라는 감각
Claude에게 업무를 위임함으로써 정말 집중해야 할 일에 집중하는 작업 방식에 대한 동경

이것이 1·2회차를 통틀어 내가 가장 만들고 싶었던 결과였고, 이건 어느 정도 만들어낸 것 같다. 그런데 실제로 사람들이 Claude를 수족처럼 부리며 일하게 만드는 것은, 일회성 세션으로 끝낼 수 있는 일이 아니었다.

이게 두 번을 다 진행하고 가장 명확하게 알게 된 것이었다.

1회차에서 도구 장벽을 발견했고, 2회차에서 그 도구 장벽을 걷어냈더니 이번엔 개념 장벽이 남아 있었다.

실제로 2회차 피드백에서도 이게 그대로 드러났다. 도구 장벽을 없앴는데도 세션을 완전히 이해한 사람은 0%였고, "개발 실전에 바로 투입된 느낌", "기본 용어를 모르고 들어갔다"는 피드백이 있었다. 환경 설치라는 눈에 보이는 장벽 아래에, 용어와 개념이라는 또 다른 층이 있었던 것이다.

원래는 두 번의 세미나 정도면 어느 정도 혼자서 시작할 수 있을 만큼의 윤곽이 잡힐거라고 막연히 생각했었다.

두번째 세미나가 끝난 후 한 분이 내가 전달해준 마케팅용 Skill 30개에 대해 "이거 어떻게 쓰는지 정리해서 공유해줄 수 있어요?" 라고 질의 했다. 이 작업 자체는 어려운 것이 아니다. Claude 를 사용하여 아주 쉽게 요약본을 만들어줄 수 있다.

근데 그건 내가 이 세미나에서 만들고 싶었던 게 아니었다.

내가 만들고 싶었던 건 "이 30개에 대한 정보와 어떻게 사용하는지에 대한 내용도 Claude한테 물어보면 알 수 있다" 는 그 사고방식이었다. Claude 를 사용해서 문제해결을 하는 과정에 대해서.

그래서 그 요약본을 Claude와의 질의를 통해 직접 받아보는 방법에 대해서 직접 보여주고 안내했지만,

"그래도 정리해주시면 좋을 것 같아요" 라는 답이 돌아왔다.

이때 좀 깨달은 것은, 도구를 알려주는 것과 사고방식을 옮기는 것은 완전히 다른 일이다.

그리고 사고방식을 바꾸는건 한두 번의 세미나로 만들어줄 수 있는 게 아니었다.

세미나를 시작하던 시점에는 "AI 사용법을 알려주고 싶다"까지였다면, 2회차 세미나를 거치면서 그 역할과 형태가 더 구체화된 것 같다.

AWS Summit에 다녀온 뒤로 전사의 AI 리터러시를 끌어올려야 한다고 대표님께 여러 번 말씀드렸고, 이 부분은 이미 설득이 된 상태였다. 세미나가 진행되면서 예상보다 사람들이 훨씬 관심을 보인다는 걸 회사에서도 느끼고 있었다. 그리고 나도 그 분위기를 느끼고 있었다. 그래서 스터디 진행을 제안하는 건 어렵지 않았다. 조금의 시간과 역할을 주면 책임지고 진행해보겠다고 제안했다.

이건 어떻게 보면 문화를 만들어나가는 일이라고 생각한다. 그리고 문화는 단 한 번으로 만들어지지 않는다.

지속적으로 모이고, 막히고, 다시 풀어가는 과정이 쌓여야 비로소 만들어진다. 무엇보다 문화는 개인이 혼자 만들 수 있는 게 아니다.

그 과정에 내가 조금이나마 기여할 수 있다고 생각하니 두근거리기도 하고, 잘 해내고 싶다.

자료

[AX] 비개발자 팀을 위한 첫 Claude Hands-on, 그리고 내가 놓친 것들

sian han — Tue, 9 Jun 2026 20:58:25 +0900

AWS Summit 2026

AWS Summit Seoul 2026에서 여러 세션들을 들은 후, 팀 전체의 AI 활용 능력을 높이는 것이 현재 가진 많은 문제들을 가장 효과적으로 해결할 수 있는 방법이라는 생각을 했다. 이에 대한 배경은 이전글에서 자세히 확인할 수 있다.

회사에 의견을 공유한 후, 전사 대상 2회 세미나를 진행할 기회를 얻었다.

첫 세미나를 준비하여 나침반이 되어준 글

세미나를 기획하는 동안 가장 많이 펼쳐본 글이 있다. 힐링페이퍼 이윤혁 님이 공유한 AX Voyage 2026 라는 글이다.

이 글은 조직 전체가AI 를 도입하고 활용해 나가는 과정을 풀어낸다. 나의 첫 세미나를 준비하면서 내가 고민했던 거의 모든 결정이 이 글에서 출발했다. 같은 맥락의 내용을 담은 인터뷰 youtube 영상도 있다. 이 영상도 준비하는 동안 반복해서 돌려봤고 많은 도움이 되었다.

세미나의 구성을 결정하기까지

내가 이 세미나에서 가장 만들고 싶었던 결과는 두 가지였다.

"나도 해볼 수 있겠는데 ?" 라는 감각
- 글에서 "쟤도 했다 = 나도 할 수 있겠다"의 문법은 어떤 교육보다 강력하다" 라고 설명하는 부분이 있다. 정교한 기술 설명이 아니라, "어, 저 정도면 나도 ?" 하는 심리적 문턱을 낮추는 것이 무엇보다 중요할거라고 생각했다
AI 를 수족처럼 사용하는 것에 대한 동경
- "사람들에게 배 만드는 법을 가르치고 싶으면, 배 만드는 매뉴얼을 들이밀지 말고 바다를 동경하게 하라"

문제는 어떤 형식으로 세미나를 구성해야 이걸 가장 잘 만들어줄 수 있느냐였다.

단순히 Claude 의 사용법 : Skill 이 무엇인지, Chat/Cowork/Code 가 무엇인지 등을 설명하는 것은 첫 세미나에서는 적절하지 않다고 판단했다. 직접 손으로 뭔가를 만들어보고, "아, 이런게 되는구나 ! 나도 충분히 이런걸 만들 수 있구나 !" 를 느끼는 경험이 가장 빠른 길이라고 봤다. 그래서 Hands-on 형식으로 기획했다.

첫 Hands-on 에서 만들기로 결정한 것

세미나에서 진행한 Hands-On 내용은 Github 실습 폴더에서 확인해보실 수 있습니다.

다같이 만들 것은 네이버 파워링크 광고 순위 확인 도구로 정했다.

이 도구는 팀에서 이미 필요하다는 이야기가 나왔었지만, 우선순위가 높은 개발 feature 가 잔뜩 쌓여서 미뤄지기만 했던 기능이었다.

만들고 나서 실제로 사용하게 될 도구를 만들게 하고 싶었다. (원래 개발팀에 요청하고 한참 있다가 만들어졌는데.. 내가 만들 수 있네 ?)

형식은 Skill 하나를 같이 만들어보는 걸로 정했다.

이건 의도가 있었다. "Skill 만드는 게 진짜 어려운 게 아니다"를 보여주고 싶었다.

AI Agent로 뭔가를 만든다고 하면 거창하게 느껴지지만, 실제로는 마크다운 파일 하나로 시작할 수 있다는 걸 손으로 확인하게 하고 싶었다. 그래서 Skill을 더 쉽게 만들 수 있도록 도와주는 Skill 두 개를 미리 준비해뒀다.

/sharpen : 막연한 아이디어를 명확한 요구사항 명세서로 다듬어주는 Skill
/productify : 명세서를 받아서 어떤 형태로 만들지(Skill인지, 스크립트인지) 결정해주는 Skill

이건 김윤혁님이 공유해주신 자료에서 가져왔다(귀한 자료 공유해주셔서 정말X100 감사합니다 ㅠㅠ)

사용자가 요구사항을 명확하게 정의하는 게 어렵다는 걸 알았기 때문에, 이 부분 자체를 AI가 도와주도록 설계된 Skill이었다.

그리고 만에 하나 시간 안에 완성하지 못하는 분들을 위한 대비도 했다. Git 저장소에 두 개의 브랜치를 준비해뒀다 (세션의 목표가 "직접 만들어보는 경험"이긴 했지만, 못 만든다고 해서 빈손으로 돌아가게 하고 싶지 않았다)

handson 브랜치 : 실습용. 처음부터 같이 만들어 나가는 출발점
main 브랜치 : 완성본. 실습이 막히더라도 main으로 이동하면 동작하는 결과물을 바로 써볼 수 있게 해둠

Hands-on 기술 스택 선택 : Claude Code + VS Code + 터미널

이 결정이 나중에 가장 큰 실수로 돌아왔다.
나는 Claude Desktop 보다 Claude Code (터미널 방식)를 쓰는 게 훨씬 낫다고 판단했다. 이유는 아래와 같았다

Skill을 만들고 확인하는 게 훨씬 쉽다
내가 만들어둔 Skill들이 GitHub에 있어서 `git clone`으로 바로 받을 수 있다
- 실습 중 skill 만들기에 실패할 경우 main 브랜치로 이동하여 완성된 skill 을 사용해볼 수 있다.
GitHub 중심의 Claude Code 생태계와 잘 맞는다

내가 그동안 참석했던 개발자 Hands-on 들이 대부분 이런 방식이었다. 미리 준비된 저장소를 clone 받고, 브랜치를 따라가면서 단계별로 실습하는 흐름. 내 입장에서는 이게 가장 따라가기 쉬운 방식이었고, 막혔을 때 다음 브랜치로 넘어가서 계속 진행할 수 있다는 점이 특히 좋았다. 그래서 이번 세션도 자연스럽게 같은 방식으로 설계했다 (빅 미스테잌 ,,)

Hands-on 구성

세션은 크게 세 파트로 나눴고, 발표 자료는 Notion 으로 준비했다.

Part 1. 왜 AI인가 — 기술이 아니라 태도에 대한 이야기

두 가지를 전달했다.

AI를 잘 활용하는 사람은 기술을 잘 아는 사람이 아니라, 문제를 잘 정의하는 사람이다.
- AI 는 결국 위임이고, 위임을 잘 하려면
  1. 정확한 디렉션
  2. 결과를 평가할 줄 아는 눈, 이 두가지가 필요하다
여러분은 도메인을 알고 있다.
- AE 분들과 대화하면서 느낀 건, 이미 문제가 뭔지 알고 어떻게 해결해야 할지도 어느 정도 알고 계신다는 것. 그러니 AI 활용법만 조금 더해지면 충분히 효율적으로 일할 수 있다.

그리고 — "꼭 해야 한다"고 말하고 싶지 않았다

내가 세션 내내 강조한 메시지가 있었다.

AI를 사용하지 않으면 비효율적으로 일하는 거다,
AI를 쓰는 사람과 안 쓰는 사람은 앞으로 더 격차가 벌어질 거다
— 오늘 이런 얘기는 하지 않겠습니다 !!!

요즘 어디서든 AI 관련 기술을 안 쓰면 큰일 난다는 식의 이야기가 너무 많다.

솔직히 나도 그런 메시지에 좀 지쳐 있는 상태였다(AI 라는 단어가 이젠 좀 징그럽기도 하다)

세션을 준비하면서 가장 경계한 게 이거였다. 나도 싫어하는 말을 말을 굳이 다른 사람에게 하고 싶지 않았다.

사람마다 변화를 받아들이는 속도는 다르고, 각자 잘하는 영역도 다르다.

AI 활용이 누군가에게는 빠르게 와닿을 수 있지만, 다른 누군가에게는 조금 더 시간이 필요한 일일 수 있다.

그래서 톤을 이렇게 잡았다.

오늘은 그냥 가볍게 ! 쟤가 무슨 말 하는지 들어나 보자 ~
그냥 가볍게 찍먹해 보자, 하는 마음으로 임해주셨으면 좋겠습니다.

이 메시지를 처음에 명확하게 깔아둔 이유는, 압박감을 느끼는 상태에서는 어떤 내용도 제대로 들어오지 않는다고 생각했기 때문이다.

"지금 안 하면 큰일 난다"는 분위기에서 학습이 일어나기는 어렵다.

그보다는 부담을 내려놓은 상태에서 한두 가지라도 자기 것으로 가져갈 수 있다면 그게 훨씬 더 가치 있다고 봤다.

Part 2. 데모 먼저 — "이게 되는구나"부터 보여주기

이론을 끝낸 직후, 바로 완성된 Skill을 시연했다.

/naver-ad-rank 비염치료기 / 무선 비염치료기, 노즈굿

이 한 줄을 입력하면 Claude가 네이버 파워링크 광고 순위를 가져와서 알려주는 모습을 보여줬다.

결과를 먼저 본 다음에 만드는 과정으로 넘어가는 순서를 의도적으로 짰다.

"내가 두 시간 뒤에 완성할 수 있는 것" 을 미리 눈으로 볼 수 있게 했다.

Part 3. 환경 설정

Node.js, Git, Claude Code 설치 및 로그인.

준비한 GitHub 저장소를 clone 받고, `handson`

브랜치로 이동시키는 것까지가 이 단계의 목표였다.

Part 4. 직접 만들기 — Skill을 Skill로 만든다

이 파트가 이번 세션에서 보여주고 싶었던 핵심이었다. 흐름은 이렇게 짰다.

1단계. MVP 개념 공유

"네이버 광고 1위를 유지한다"는 큰 목표를 그대로 만들려고 하면 끝이 없다는 걸 먼저 짚었다.

업무를 작은 단위로 쪼개고, 작게 시작해서 동작하는 걸 확인하는 게 먼저라는 메세지를 전달하고 싶었다.

2단계. SKILL.md 구조 보여주기

Claude의 Skill은 .claude/skills/ 폴더 안에 SKILL.md 파일 하나로 만들어진다는 걸 보여줬다. (마크다운 파일 하나면 된다 !)

Skill 이 사실 거창한 게 아니라는 걸 시각적으로 확인하게 하는 게 목표였다.

3단계. /sharpen으로 아이디어 다듬기

여기서부터가 이번 세션의 가장 보여주고 싶었던 흐름이었다.

아이디어를 다듬는 것은 /sharpen 스킬과 함께라면 아래와 같이 막연한 한 줄로 시작할 수 있다.

네이버 파워링크 광고 순위를 확인하고 싶습니다. 
키워드와 내 광고 제목을 입력하면 현재 몇 위인지 알려주는 것을 만들고 싶어요. /sharpen

/sharpen이 문답으로 누가, 왜, 어떤 조건에서, 어디까지를 묻기 시작한다.

몇 번의 대화만으로 막연했던 아이디어가 명확한 요구사항 명세서로 정리되는 과정을 직접 보여주고, 경험할 수 있게 했다.

4단계. /productify로 형태 결정하기

/sharpen이 만든 명세서를 /productify에 넘긴다.

이 skill 은 명세서를 받아서 "이걸 Claude Skill로 만들지, 파이썬 스크립트로 만들지, 단계별 로드맵은 어떻게 가져갈지"를 결정해주는 역할을 한다. 가장 작은 형태로 시작할 수 있도록 범위를 잡아준다.

5단계. 실제 Skill 생성

/productify가 결정한 형태대로 실제 SKILL.md가 만들어진다. 즉, Skill을 만드는 데 Skill을 사용하는 흐름이었다.

AI Agent로 뭔가를 만든다는 게 거창하게 느껴질 수 있지만, 결국 대화 몇 번이면 목표 지점에 도달할 수 있다는 걸 손으로 확인하게 하고 싶었다.

6단계. 만든 Skill 사용해보기

마지막으로, 방금 만든 Skill을 직접 실행해보고 동작하는지 확인한다.

처음에 보여줬던 데모와 같은 결과가, 이번엔 본인이 만든 Skill로 나오는 순간이 이 세션의 도착점이었다.

진행하고 나서

솔직히 말하면, Part 2. 환경 설정에서 무너졌다 !

처음 환경 설치에만 40~50분이 걸렸고, 진행이 막힌 분들이 있었지만 모두 해결하고 갈 수 없다고 판단되어 설명은 계속 이어졌다.

나중에 피드백으로 들은 말이 "제가 진행하는 과정은 멈춰있는데 설명은 이어나가셔서 혼동이 있었다"였다.

근본 원인은, 내가 개발자 입장에서 "이 정도면 쉬울 것"이라고 판단한 방식이, 사실은 전혀 쉬운 게 아니었다. 미리 준비된 저장소를 clone 받고 브랜치로 이동하는 흐름은 내가 그동안 좋다고 느꼈던 방식이었지만, 그 판단의 기준 자체가 이미 개발자 중심이었다.

비개발자 입장에서는 그 흐름의 어떤 부분도 자연스럽지 않을 수 있다는 걸 처음부터 인지하면 좋았을텐데..

세션이 끝나고 받은 질문은 그 사실을 가장 분명하게 보여줬다.

그래서 "VS Code랑 터미널이 어떻게 다른 건가요?"

이 질문을 받은 순간 좀 띵했다. 완전히 잘못 설계했구나 싶었다.

나는 세션 초반에 "VS Code는 텍스트 편집기예요"라고 짧게 설명하고 넘어갔는데, 그게 전혀 와닿지 않았던 거다.

그래서 세션이 다 끝나고 나서야 이 질문이 나온 거였고.

이 질문 자체가 신호였는데, 세션이 끝나는 시점에 이 질문이 나왔다는 건, 처음부터 마지막까지 그 차이를 이해하지 못한 채로 따라오고 있었다는 뜻이었다.

환경 설정도, Skill 만들기도, 결국 어디서 무엇을 하는 건지 명확히 잡히지 않은 상태에서 진행됐던 거다.

그래서 2회차부터는 Claude Desktop으로 전환하여 설명하도록 계획을 변경했다.

피드백으로 보는 1차 Hands-on

전반적 만족도: 평균 4.7점 / 5점
어려웠던 부분: 3명 중 2명이 환경 설정, 1명이 "스킬이 뭔지 이해하기"
다음 세션 참여 의사: 3명 중 2명 "네, 이미 써볼 업무가 떠올랐어요"

의도한 메시지가 통했던 지점

"문답 방식의 AI만 보다가 처음 보는 형식의 AI 사용 방식이 신선해서 기억에 남습니다."
- 이건 Part 4에서 보여주려던 흐름이 그대로 닿았다는 신호였다. 챗봇처럼 묻고 답하는 게 전부가 아니라, 명령어 한 줄로 동작하는 도구를 직접 만들 수 있다는 감각.
"AI가 요구사항을 구체화 하는 과정에서 질문사항의 퀄리티가 높아서 잘 사용하면 업무에 많은 도움이 되겠다라고 생각되었습니다."
- 이 응답이 개인적으로 가장 반가웠다. Part 1에서 "AI를 잘 활용한다는 건 문제를 잘 정의하는 것"이라고 말로 했지만, 그건 사실 말로 해서는 잘 안 와닿는 부분이다. 근데 `/sharpen`이 직접 문답하면서 막연한 요구사항을 다듬어가는 모습을 보면서 그 메시지를 참여자가 직접 체감한 거였다.

의도한 메시지가 통하지 않은 지점

"오늘 가장 어려웠던 부분: 스킬이 뭔지 이해하기"
"개발 기초 지식이 없어 스킬이라는 자체를 어떻게 만들어야 할지 어렵게 느껴집니다. 다른 사람이 만든 걸 복사 붙여넣기 한다고 해도 어디를 커스텀, 수정하면 내 스킬로 만들 수 있을지 모르겠습니다."

이게 환경 설정 문제보다 더 본질적인 실패였다.

이번 세션의 가장 큰 의도가 "Skill 만드는 게 어렵지 않다"를 보여주는 거였는데,

정작 한 분은 Skill 개념 자체가 손에 잡히지 않은 채로 세션이 끝났다.

원인을 돌이켜보면, 환경 설정에서 시간을 너무 많이 쓴 영향이 컸다.

정작 핵심이었던 Part 4에 도달할 즈음에는 이미 집중력이 흩어진 상태였다.

결과적으로 Skill을 만드는 과정이 참여자가 따라오는 속도보다 빠르게 흘러갔고, "이게 어떻게 동작하는 건지"를 충분히 짚어주지 못했다.

준비할 때 가장 보여주고 싶었던 것이 정작 가장 덜 전달된 부분이 됐다는 게 아쉬웠다.

단순히 환경 설정 설치가 오래 걸린 것 보다, 가장 중요한 대목인 Part 4 에 도달할 에너지를 깎아먹은 게 문제였다.

준비하면서 배운 것

상대방의 '당연함'을 기준으로 설계해야 한다.
- 나한테 당연한 것들이 상대방에겐 전혀 당연하지 않았다. 터미널, 영어 에러 메시지, VS Code와 터미널의 차이. 이걸 처음에 몰랐다.

첫 번째 시도는 언제나 뭔가를 잘못 전제하고 있다.
- 1회차에서 명확하게 틀린 지점이 드러났다. 이 경험이 없었다면 2회차도 같은 방식으로 갔을 거다.
- 결국 첫 시도가 가지는 가치는 "어디가 안 통하는지"를 알게 되는 거였다.

준비를 10시간이나 했음에도 환경 설정에서 무너진 게 속상하긴 하다..

그렇지만 이런건 14시간을 더 써서 시뮬레이션을 돌렸봤어도 혼자서는 알 수 없었을 부분이라고 생각한다.

실제 사람을 앞에 두고 진행해봐야만 보이는 것들이 있었다.

앞으로

2회차에서는 기술 스택을 전부 바꿨다. 터미널과 VS Code, Git을 모두 빼고 Claude Desktop으로 간다 !

그 과정과 결과는 ~ 에 별로도 정리했다.

[AX] AWS Summit 2026 참여 후 회사에 제안한 것

sian han — Mon, 8 Jun 2026 19:54:25 +0900

1. 사내 AI 세미나 진행 요청

Summit에서 보니 규모 있는 기업들은 저마다 완성도 높은 AI 에이전트를 선보이고 있었다. 우리 회사도 내부 업무용 AI 에이전트를 개발하고 있는데, 이제 막 v0.0.0.0.0.1 이 갓 나온 참이다.

AWS Summit 2026 의 다양한 세션에서 우리 회사가 궁극적으로 목표로 하는 AI 에이전트들을 소개했고 그 수준에 도달하기까지 얼마나 많은 시행착오가 있었는지도 엿볼 수 있었다.

공통적으로 강조하는 메시지는 작은 것부터 빠르게 시작하라는 것이다. 크고 거창한 시스템을 구상하기보다, 당면한 문제를 조금이라도 해결하는 데 집중하는 것이 AI 도입의 핵심 원칙이라고 한다. 여러 연사가 공통적으로 전한 이 메시지가 가장 깊이 와닿았다.

우리 회사에서 개발 중인 AI 에이전트를 점검해봤다. 이제 막 첫발을 뗀 이 에이전트가 지금 당장 해결할 수 있는 문제는 무엇일까. 현재 리소스(개발자 1명 / 경력 2년차) 로 앞서 본 수준의 결과물을 만들어내려면 얼마나 걸릴까.(ㅠㅠ)

AI 에이전트가 등장하게 된 본질을 다시 떠올려봤다. 애초의 목적은 마케터들의 반복 업무를 줄여 인당 생산성을 높이는 것이었다. 그렇다면 지금 우리는 당장 해결할 수 있는 것에 집중하고 있는가? 아니면 여전히 거창한 미래를 바라보고 있는가? 솔직히 말하면 후자다.
현재의 AI 에이전트가 실제 운영 가능한 수준에 이르기까지는 아직 상당한 시간이 필요하다.

인당 생산성 향상이라는 본질에 집중해보면, 현재 이 문제를 가장 효과적으로 해결할 수 있는 방법은 팀원들이 AI 에이전트를 자유자재로 활용할 수 있게 되는 것이라고 생각했다. AI 에이전트 개발은 계속 이어가되, 그와 동시에 팀 전체의 AI 리터러시를 높이는 것이 필요하다는 결론에 이르렀다.

사실 이런 생각은 이전부터 갖고 있었고, 이번 Summit을 다녀오며 더욱 확고해졌다. 그래서 이번에도 AX 관련 세션을 중심으로 선택했다. 내가 들은 세션의 기업들은 하나같이 AX 조직을 두고 있었고, 각 조직이 이 문제를 어떻게 풀어나가고 있는지 생생한 사례를 들을 수 있었다.

AI 챔피언, AI 히어로, AI 특공대 등 다양한 이름으로 불리는 AX 조직의 구성원들은 비개발자가 AI 에이전트를 업무에 활용할 수 있도록 돕는 역할을 한다. 이 과정에서 가장 중요한 것은 "온도를 맞추는 일" 이라고 했다. 혼자 앞서 나가면서 이것저것 설명해봐야 온도가 끌어올려지지 않은 상태에서는 아무것도 전달 할 수 없다. 먼저 상대방의 관심과 의욕을 충분히 끌어올린 뒤 지식을 전달하고 스스로 할 수 있도록 이끄는 것이 핵심이라는 것이다.
우리 회사에서 AI 에이전트를 일상적으로 활용하는 사람이 나뿐인 만큼, 내가 AI 챔피언, AI 히어로, AI 특공대 등의 AI 어쩌구 역할을 맡아야겠다는 생각이 들었다.

Summit을 다녀온 뒤 대표님께 위 내용을 공유했고, 그 결과 업무 시간 내에 전사를 대상으로 총 2회, 4시간 분량의 세미나를 진행할 기회를 얻었다. 별도의 준비 시간은 주어지지 않았지만, AI 에이전트로 업무가 얼마나 편해질 수 있는지 알리고 싶은 마음이 컸기에 개인 시간을 쓰는 것은 기꺼이 감수했다. 다만 준비가 이렇게 오래 걸릴 줄은 몰랐다.. 1회차 준비에 10시간, 2회차 준비에 4시간의 준비시간이 있었다. 세미나를 진행하며 기록해두고 싶은 것들이 많은데, 이 부분은 따로 잘 정리해서 추후에 글로 남겨보려 한다.

2. 모든 기능을 AI 에이전트로 구현하자는 방향에 제동을 걸기

"마케팅을 처음 접하는 사람도, 첫날부터 마케팅 전문가처럼 일할 수 있게 한다"는 아이디어에서 v0.0.0.0.0.1 에이전트는 출발했다. AI 에이전트와 함께라면 어떤 업무든 해낼 수 있도록 한다는 목표 아래, 모든 기능을 AI 에이전트로 구현해내자는 방향성이 자리잡고 있었다.

"AI-DLC를 활용한 교육자용 AI 에이전트" 세션에서는 AI Agent 를 개발하고 나면, 현장에서 잘 쓰이고 있는지 측정하고 평가하는 것이 중요하다고 강조했다. 아무리 좋은 도구를 만들더라도 실무에서는 사용하지 않을 수 있는데, 지속적인 성과 측정을 통해 실제 사용으로 이어질 수 있도록 관리하는 것이 핵심이라는 것이다.

Summit 다음날, 사내 실제 사용자들에게 직접 물어봤다. 코멘트 자동 생성 기능이 있으면 매우 유용하게 쓸 것 같다는 의견을 받아 개발까지 완료했는데, 막상 사용률이 생각보다 낮아 그 이유가 궁금했다. 돌아온 답변은 이랬다. 코멘트를 생성하려면 데이터 집계 기간과 여러 조건들을 일일이 타이핑해서 입력해야 하는데, 그 과정이 번거로워 자연스럽게 손이 멀어진다는 것이었다.

"바비톡의 AX 여정: 에이전틱 AI로 K-beauty를 바꾸다" 세션에서는 철저히 비즈니스 중심으로 AI를 선택해야 하며, AI 기술의 홍수에 휩쓸리지 말라고 강조했는데, 이때 우리가 무엇을 놓치고 있었는지 명확히 알 수 있었다.

AI 에이전트와 함께라면 어떤 업무든 해낼 수 있도록 한다는 기조 아래, 우리는 AI 에이전트라는 기술을 먼저 놓고 비즈니스를 거기에 어떻게 끼워 맞출지를 고민하고 있던건 아닐까 ?

아래와 같은 형태의, 흔히 보는 AI 에이전트 UI/UX로 모든 기능을 구현한다는 방향을 잊어버리고 보니, 사용자 관점의 UX 를 고민할 수 있었다.

지금은 다양한 검색 조건을 에이전트에 타이핑해야 한다.

검색 조건을 미리 구성해 두고 'AI 코멘트 생성' 버튼 하나로 끝낼 수 있게 하면 어떨까.

아래는 v0로 간단히 만들어본 개선 아이디어이다.

결국 사용자에게 필요한 건 해당 기간의 데이터(데이터 자체도 함께 필요하다)에 대한 전문가 수준의 코멘트를 얻는 것이지, 에이전트와 대화하는 과정 그 자체는 아니기 때문이다.

회사에는 이런 내용을 제안했지만, 아직 결정이 난 상태는 아니다. 회사가 가고자 하는 방향이 따로 있으니, 앞으로 어떻게 될지는 모르겠다. 내 관점에서는 이렇게 만들면 사람들이 좀 더 잘 쓰지 않을까 싶지만, 다른 사람들은 다르게 볼 수도 있다. 또 지금 회사의 사업 방향에서는 당장 사람들이 이 기능을 쓰는지 아닌지가 그리 중요하지 않을 수도 있다. 나는 내 관점에서 더 나아 보이는 쪽을 제안했을 뿐이고, 선택은 회사의 몫이다.

[홈서버] 정전 이후 발생한 DDNS 등록 만료로 인한 서비스 전면 접속 불가

sian han — Thu, 14 May 2026 18:31:28 +0900

이슈

정전 이후 복구 과정에서, 다음 날 새벽 Proxmox pveproxy 일일 재시작 시점에 ipTIME DDNS 등록이 만료되어 외부에서 홈서버 내 운영중인 모든 서비스 접속이 불가한 상태가 발생함

개인 프로젝트 운영 목적으로 집에서 미니PC 1대에 Proxmox VE를 올려 홈서버를 운영 중이며, 해당 환경에서 발생한 이슈이다.

홈서버 환경

현재 홈서버 인프라는 미니PC 1대에 **Proxmox VE** 를 올려 온프레미스 가상화 환경으로 운영 중이다.
외부 접속은 ipTIME 공유기의 DDNS 서비스(`******.iptime.org`)와 포트포워딩을 통해 이루어진다.

발생 이슈

오늘 아침, 서비스 접속 시 아래 오류 문구를 확인할 수 있었다.

DNS_PROBE_FINISHED_NXDOMAIN
ERR_NAME_NOT_RESOLVED

Proxmox 웹 UI (`******.iptime.org`) 접속 불가
홈서버 내부 서비스 (`******.iptime.org` 경유) 접속 불가
운영 서비스 전체 외부 접속 불가

위 항목에 대한 접근이 불가했다. 단, 홈서버 내부망에서는 모든 서비스 정상 접속 가능했다.

점검항목

Proxmox 내부 접속 : ✅ 정상
공유기 인터넷 연결 상태 : ✅ 정상
공인 IP 확인 : ✅ 정상
포트포워딩 설정 : ✅ 정상
ipTIME DDNS 설정 화면 상태 : ✅ "정상등록" 표시

그러나, nslookup 명령어로 DNS 응답 확인 시 Non-existent domain 응답을 받았다.

(nslookup 은 도메인 이름과 IP 주소 사이의 매핑 정보를 확인하기 위해 사용하는 네트워크 관리 명령어이다)

nslookup으로 DNS 응답 확인 : Non-existent domain

❯ nslookup ******.iptime.org
서버: cns3.bora.net
*** cns3.bora.net이(가) ******.iptime.org을(를) 찾을 수 없습니다. Non-existent domain

공유기 화면에서는 "정상등록" 으로 표시되고 있었지만, nslookup 을 통해 직접 확인하니 DNS 서버가 도메인 자체를 모르는 상태였다.

DDNS 서버 실제 등록 상태 : 만료됨

원인

5월 10일 정전으로 집 공유기와 미니PC가 강제로 꺼졌다. 공유기가 재시작되면서 ipTIME DDNS 갱신 타이머가 초기화된 상태가 됐다. ipTIME DDNS 서버는 일정 시간 갱신 신호를 받지 못하면 등록을 만료 처리하기 때문에 DDNS 서버에서 우리집 호스트 정보가 사라지게 된것이다. 정리하자면 아래와 같다.

공유기는 주기적으로 DDNS 에 자신의 정보(외부 IP 주소, 도메인)를 알립니다.
정해진 "주기" 이상으로 정보를 알리지 않으면, DDNS 서버에서 호스트를 비활성화 처리합니다.
우리집 미니 PC 는 강제로 꺼졌다 켜지면서 "주기" 를 계산하는 타이머가 리셋되었습니다.
0부터 시작하게된 타이머때문에 정해진 "주기" 를 넘기게 되었습니다.
따라서 DDNS 서버에서 는 우리 집의 호스트 이름이 삭제되었습니다.

고정 IP 를 사용하고 있어서, 문제가 없을 것이라고 생각했는데

ipTIME DDNS 갱신 타이머가 초기화되어 발생하는 문제는 예상치못했다.

문제를 찾는데 시간이 오래 소요된 이유는, 위 사진과 같이 ipTIME DDNS 설정 UI 상에서 정상 등록되었다고 표시되었기 때문이다. 나중에 알아보니, ipTIME 공유기는 마지막으로 성공한 등록 상태를 캐싱하여 화면에 표시한다고 한다.. 실제 DDNS 서버에서 등록이 만료됐더라도 공유기 입장에서는 "마지막에 등록 성공했다"는 상태를 그대로 보여주기 때문에, 공유기 화면만으로는 문제를 발견하기 어렵다. 이 때문에 nslookup으로 직접 DNS 응답을 확인하기 전까지 원인 파악이 지연됐다.

복구 조치

ipTIME 관리페이지에서 DDNS 갱신 버튼을 클릭한 것이 전부이다.

갱신 후 nslookup 재확인

❯ nslookup ******.iptime.org
서버: cns3.bora.net
권한 없는 응답:
이름: ******.iptime.org
Address: (공인 IP)  ✅

모든 외부 서비스 접속이 정상 복구되었다.

홈서버 운영중에 집에 정전이 나면 공유기 재시작, 서버 데몬 재시작 등 예상치 못한 타이밍에서 DDNS가 조용히 만료되는 문제가 있다. 복구 후 nslookup 명령어를 통해 외부 DNS 응답 확인을 하자.

[LangChain] 데이터 인제스천의 3단계 (Loader, Splitter, Embedding)

sian han — Wed, 29 Apr 2026 18:56:16 +0900

https://feelfreetothink.tistory.com/263

[LangChain] 임베딩과 코사인 유사도의 이해

LLM은 환각(잘못된 정보를 출력하는 현상)을 일으키고 부정확한 정보를 제공할 가능성이 높다.이른 프롬프트를 수정하는 것으로 해결할 수 없으며, 그 이유는 모델의 지식한계로 생기는 문제이

feelfreetothink.tistory.com

위 글에서 설명했듯이 문서 전처리(인제스천) 의 첫 단계는 문서를 텍스트로 변환하는 것이다.

이를 위해 품질 저하 없이 문서의 내용을 파싱 및 추출하는 로직을 구성해야 한다.

랭체인은 문서 로더 (Document Loader) 를 제공한다.

※ 문서 로더 (Document Loader)

문서 로더는 다양한 형식의 원시 데이터를 랭체인이 이해할 수 있는 표준 객체인 Document 형태로 변환해주는 도구이다.

▶ Document 객체

Document 객체는 랭체인에서 데이터를 다루는 가장 핵심 단위이다. 어떤 로더를 쓰든 결과물은 항상 이 동일한 규격의 객체에 담겨 나오기 때문에, 이후의 처리 과정이 매우 단순해 진다.

단순히 String 으로 넘기지 않고 객체화하는 데는 이유가 있다.

사용자가 질문했을 때, 답변과 함께 발췌 출처를 띄워주려면 metadata 에 저장된 정보가 반드시 필요하다
벡터 데이터베이스에서 검색할때, metadata 필터링을 수행할 수 있다 (ex. 2024년에 작성된 문서 중에서만 찾아줘)
추적성 : 복잡한 인프라나 대규모 프로젝트에서 데이터의 유입 경로를 추적하기 용이하다.

▷ Document 객체의 내부구조

Document 객체는 딱 두 가지 필드로 구성된 매우 심플한 구조를 가진다.

page_content (string)

역할 : 실제 텍스트 내용
특징 : LLM이 직접 읽고 분석하게 될 핵심 본문

metadata (dict)

역할 : 텍스트에 대한 부가 정보
특징 : 파이썬의 딕셔너리({}) 형태이며, 검색 성능을 높이거나 출처를 밝힐 때 사용된다.
- ex ) {"source": "신규_인프라_설계안.pdf", "page": 12, "author": "한서현"}

실제로 Document 객체를 코드로 구현하면 아래와 같은 데이터 구조를 갖는다

from langchain_core.documents import Document

# 수동으로 Document 객체를 생성할 때의 모습
doc = Document(
    page_content="이 서버의 Bastion 호스트 설정은 22번 포트를 제한합니다.",
    metadata={
        "category": "Security",
        "location": "Incheon_DC",
        "priority": "High"
    }
)

print(doc.page_content)  # 본문 출력
print(doc.metadata["category"])  # 특정 메타데이터 접근

자 이제 랭체인의 다양한 문서로더에 대해 알아보자.

▶ 랭체인의 문서 로더 (몇개만..)

랭체인의 지원 문서 유형은 랭체인 홈페이지 에서 확인할 수 있다.

1. TextLoader

.txt 파일이나 일반 텍스트 파일을 읽어온다.
파일 전체를 하나의 String 으로 읽어 page_content 에 담는다
간단한 메모, 로그 파일, README 파일 등을 로드할 때 사용

from langchain_community.document_loaders import TextLoader

loader = TextLoader('./test.txt', encoding='utf-8')
docs = loader.load()

문서에 적합한 로더를 선택한다 (TextLoader)
해당 로더의 인스턴스(loader)를 생성하고, 설정용 매개변수를 함께 지정한다
load()를 호출하여 문서를 로드하면, 다음 단계에 전달할 준비가 끝난 문서 목록을 반환한다. (? 어떤 문서라는거지 ? )

랭체인 문서 로더를 사용하는 코드는 모두 구조가 비슷하여 아래부터는 코드 설명을 생략한다.

2. PyPDFLoader

PDF 파일을 읽고 페이지별로 문서를 분할해주는 로더이다.
페이지 번호를 메타데이터로 자동으로 남겨준다. 따라서 나중에 LLM 이 답변할때 출처를 밝히기 좋다

3. CSVLoader

.csv 파일의 각 행을 하나의 Document 객체로 변환한다.
한 행의 데이터를 열 이름 : 값 형태의 텍스트로 만들어준다.
표 형식의 데이터, 사용자 리스트, 상품 목록 등을 처리할 때 유용하다.

4. WebBaseLoader

특정 URL 주소의 HTML 내용을 긁어와서 텍스트만 추출한다.
BeautifulSoup 라이브러리를 내부적으로 사용하여 웹페이지의 불필요한 태그를 걷어내고 본문 위주로 가져온다.
최신 뉴스 기사, 블로그 포스팅, 공식 문서 웹사이트의 내용을 학습 데이터로 쓸 때 사용한다.

로더를 선택할 때는 텍스트를 긁어오는 것을 넘어 "메타데이터를 얼마나 풍부하게 남길 수 있는가" 를 고려해야한다. 그래야 나중에 관리나 검색이 훨씬 수월해진다.

그러나 ! 여기에 문제가 있다.

100장의 PDF 를 PyPDFLoader를 사용해 추출하여 Document 객체로 가지고 있다고 가정해보자, 100,000 자를 초과해서 대다수의 LLM 및 임베딩 모델이 제공하는 컨텍스트 윈도에 수용되지 않는다.

이 제한에 대응하기 위해서는, Document 를 관리 가능한 텍스트 단위로 분할해 추후 임베딩과 의미론적 검색을 할 수 있도록 만들어야 한다.

※ 텍스트 스플리터(Text Splitter)

의미론적으로 연관된 텍스트 조각끼리 유지하며 텍스트를 여러 조각으로 분할하는 작업은 복잡하다.

랭체인에서는 이 역할을 수행하는 도구를 텍스트 스플리터라고 한다.

텍스트 스플리터가 수행하는 작업은 청킹이다.

▶ 청킹(Chunking)

청킹은 거대한 데이터 덩어리를 LLM 이나 임베딩 모델이 처리하기 좋게 의미 있는 작은 단위로 쪼개는 과정을 말한다.

재차 말하지만, 단순히 단어를 쪼개는 것이 아니라, 맥락을 보존하면서 효율적으로 분할하는 전략이다.

컨텍스트 윈도 제한도 청킹을 하는 이유 중의 하나이지만, 이뿐만이 아니다.

검색 정확도 향상 : 문서 전체를 하나로 임베딩 하면 세부 내용이 묻힌다. 주제별로 잘게 쪼개야 사용자의 질문가 가장 유사한 조각을 찾아낼 수 있다.
비용 절감 : 필요한 조각만 모델에게 전달하므로 토큰 사용량을 줄일 수 있다.

▷ 랭체인의 텍스트 스플리터

1. RecursiveCharacterTextSplitter

중요도 순서에 따라 구분자 목록을 작성한다. 기본 구분자 목록은 아래와 같다.

문단 구분자 \n\n
줄 구분자 \n
단어 구분자 : 공백문자

from_language

언어 맞춤형 청커
from_language 는 특정 프로그래밍 언어의 문법을 이해한다.
따라서 하나의 함수나 클래스를 가급적 쪼개지 않고 한 덩어리로 묶어준다.

create_documents

리스트를 Document 객체로
입력값 : 문자열 리스트 (List[str])
출력값 : Document 객체 리스트 ( List[Document] )
용도 : 메타데이터를 포함한 표준 객체가 필요할 때

from langchain_text_splitters import RecursiveCharacterTextSplitter

# 1. 스플리터 설정 (간단히 50자 단위로 설정)
splitter = RecursiveCharacterTextSplitter(chunk_size=50, chunk_overlap=10)

# 2. 여러 개의 원본 데이터 준비
texts = [
    "FastAPI는 파이썬 기반의 현대적이고 빠른 웹 프레임워크입니다.",
    "PostgreSQL은 강력한 오픈 소스 객체 관계형 데이터베이스 시스템입니다."
]

# 3. 각 데이터에 대응하는 메타데이터 준비 (리스트 순서가 중요!)
metadatas = [
    {"source": "fastapi_doc.txt", "category": "Web", "priority": 1},
    {"source": "postgres_doc.txt", "category": "DB", "priority": 2}
]

# 4. create_documents 실행
documents = splitter.create_documents(texts, metadatas=metadatas)

# 5. 결과 확인
for i, doc in enumerate(documents):
    print(f"--- Document {i} ---")
    print(f"Content: {doc.page_content}")
    print(f"Metadata: {doc.metadata}")

위 예시와 같이 create_documents 에서 두 번째 선택 인수를 활용해 메타 데이터 목록을 전달할 수 있다.

이렇게 전달된 메타데이터는 반환되는 객체인 Document 의 메타데이터 필드를 채우는 용도로 활용된다.

※ 텍스트 임베딩 (Embedding)

앞전에 문서를 로드하고, 청킹하는 과정에 대해 알아봤다.

이제 이 텍스트 조각들을 벡터로 변환하는 Embedding 단계에 대해 알아보자.

▶ Embedding 클래스

랭체인의 Embedding 클래스는 텍스트 임베딩 모델과 상호작용하여 텍스트의 벡터 표현을 생성한다.

해당 클래스는 임베딩 모델인 OpenAI, HuggingFace, Cohere 등을 동일한 인터페이스로 사용할 수 있게 해주는 추상화 레이어이다.

Embedding 클래스는 아래 2개의 핵심 메서드를 제공한다.

문서를 임베딩 하는 메서드 : embed_documents(texts)

텍스트 문자열 목록을 입력받는다.
준비된 여러 개의 Chunks 을 한꺼번에 벡터로 변환하여 Vector Store 에 저장할 때 사용한다.
입력값 : List[str]
반환값 : List[List[float]] (2차원 리스트)

질의를 임베딩 하는 메서드: embed_query(text)

단일 텍스트 문자열을 입력받는다.
사용자가 던진 질문 하나를 벡터로 변환할 때 사용한다.
질문과 문서의 유사도를 비교하기 위해 질문도 같은 공간의 숫자로 바꿔야 하기 때문이다.
입력값 : str (문자열 하나)
출력값 : List[float] (1차원 리스트)

두 메서드를 구분하는 이유는,

숫자로 변경하는 것의 목적은 같지만, 일부 최신 모델들은 "검색 대상이 되는 문서" 와 "찾으려는 질문"의 특성을 다르게 파악하여 최적화 하기 때문이다.

▷ Embedding 클래스의 입출력

앞서 배운 문서 로더와 텍스트 스플리터의 결과물은 Document 객체이다.
그러나 임베딩 모델은 수학적인 계산을 하는 모델이라서, 메타데이터는 계산할 줄 모른다. 따라서 Embeddings 클래스는 Document 객체를 직접 받지 않는다.

# ❌ 잘못된 방법
documents = splitter.split_documents(raw_docs)
vectors = embeddings_model.embed_documents(documents) # Error! Document 객체는 계산 불가

# ✅ 올바른 방법 (텍스트만 추출해서 전달)
texts = [doc.page_content for doc in documents]
vectors = embeddings_model.embed_documents(texts)

랭체인은 내부적으로 아래와 같이 동작하는데, 실제 개발할 때는 앞으로 배울 랭체인의 벡터 저장소(Vector Store) 클래스가 이 작업을 대신 해준다.

1. Document 객체에서 page_content 를 뽑아낸다
2. 해당 텍스트를 Embeddings.embed_documents() 에 전달한다.
3. 반환된 숫자 리스트(벡터)를 다시 메타데이터와 연결하여 벡터 저장소에 저장한다.

임베딩 모델은 동시에 여러 문서를 임베딩 할 수 있으므로, 동시 임베딩하는 편이 더 좋다. 모델 구성상 동시 임베딩이 더 효율적이기 때문이다.

지금까지 살펴본 세 가지 기능은 아래와 같다.

문서 로더 : 임의의 문서를 평문으로 변환한다.
텍스트 분할기 : 대형 문서를 다수의 소규모 문서로 분할한다.
임베딩 모델 : 각 분할 요소의 의미를 수치로 표현한다.

문서에서 임베딩을 생성하는 방법을 배웠고, 다음 장에서는 벡터 저장소라는 특별한 DB 에 저장하는 것을 알아보자

[LangChain] 임베딩과 코사인 유사도의 이해

sian han — Tue, 28 Apr 2026 09:18:25 +0900

LLM은 환각(잘못된 정보를 출력하는 현상)을 일으키고 부정확한 정보를 제공할 가능성이 높다.

이른 프롬프트를 수정하는 것으로 해결할 수 없으며, 그 이유는 모델의 지식한계로 생기는 문제이기 때문이다.

LLM에 데이터를 제공할 때 가장 문제가 되는 요소는 바로 입력 크기 제한이다. 방대한 텍스트를 LLM 에 전부 전달할 수 없는데, 이때 아래와 같은 의문이 생긴다.

특정 부분만 선택해야 하는데 어느 부분을 전달해야할까 ?
LLM이 질문에 답할 때 참고하기에 가장 적합한 텍스트는 어떻게 선정해야할까 ?

이 문제는 인덱싱과 검색으로 해결할 수 있다.

인덱싱 : 애플리케이션이 질문에 가장 적합한 자료를 손쉽게 탐색할 수 있도록 문서를 전처리한다.
- 문서를 거대 언어 모델이 이해하고 검색할 수 있는 형식으로 사전 처리 하는 것
검색 : LLM이 데이터를 바탕으로 정확한 답변을 생성하도록 인덱스에서 외부 데이터를 가져와 컨텍스트로 전달한다.

인덱싱에서 문서를 전처리 한다고 했는데, 이 과정이 왜 필요할까 ?

LLM에 특정 문서를 제공하고, 관련한 질문을 했을때, 이에 대한 답변을 받기 위해서는 네 가지 핵심 단계가 필요하다.

1. 문서에서 텍스트를 추출한다
2. 텍스트를 효율적으로 처리할 수 있도록 적절한 단위로 분할한다.
3. 텍스트를 컴퓨터가 이해할 수 있는 숫자 체계로 변환한다.
4. 문서에서 주어진 질문에 대한 부분을 손쉽고 신속하게 조회할 수 있도록 텍스트의 숫자 표현을 적절한 위치에 저장한다.

이 과정을 인제스천이라고 부른다.

인제스천(Ingestion)

인제스천은 기본적으로 데이터 엔지니어링의 ETL 구조를 따른다.

1. Extract 추출 - Document Loaders

다양한 소스에서 raw 데이터를 긁어온다

종류 : PDF, CSV, JSON, Notion, SQL DB 등
역할 : 각기 다른 포맷의 데이터를 랭체인의 공통 규격인 Document 객체로 변환한다.

2. Transform 변환 - Text Splitters

LLM 은 한 번에 읽을 수 있는 양이 정해져 있는데, 그래서 긴 문서를 의미있는 단위로 쪼개야 한다.

이때 핵심은 단순히 글자 수로 자르는 게 아니라,

문맥이 끊기지 않도록 재귀적 분할이나 의미론적 분할 (그니까 암튼 분할을 알잘딱깔센으로 잘한다는 거임) 을 수행한다.

이때 데이터를 너무 크게 쪼개면 노이즈가 섞이고, 너무 작게 쪼개면 문맥이 사라진다. Chunk Size 를 최적화 하는 것이 인제스천 설계의 핵심 역량이다.

3. Load 적재 - Vector Stores

쪼개진 텍스트를 숫자의 형태(Embedding)로 바꾸어 벡터 데이터베이스에 저장한다.

도구 : Chroma, Pinecone, FAISS 등
목적 : 나중에 사용자가 질문했을 때, 유사한 문맥의 데이터를 빠르게 검색하기 위함이다.

인제스천은 문서를 컴퓨터가 이해하고 분석하기 좋은 숫자 데이터로 전환한 뒤, 이를 효율적인 검색 증강 생성을 위해 특화된 데이터베이스에 저장하는 전체 프로세스를 의미한다. 여기서 숫자 데이터는 임베딩이라고 부르고, 특수한 유형의 데이터베이스를 벡터 저장소라고 부른다. 임베딩이 무엇이고 왜 중요한지 알아보자

임베딩

임베딩은 컴퓨터가 자연어의 의미와 맥락을 이해할 수 있도록 텍스트를 다차원 공간상의 수치(벡터)로 변환하는 과정이다.

임베딩은 텍스트를 긴 숫자 시퀀스로 표현한다.
이 과정에서 손실이 발생한다.
숫자 시퀀스에서 원본 텍스트를 복원할 수 없다.
따라서 보통 원본 텍스트와 해당 숫자 시퀀스를 함께 저장한다.

왜 원본 텍스트를 저장하는데 굳이 숫자 데이터를 따로 만들어야 할까 ?

텍스트를 숫자로 변환하면 숫자의 유연함과 강력함을 얻을 수 있다.

컴퓨터는 "사과" 라는 글자가 과일인지, 컴퓨터 회사인지 알지 못한다.

그러나 이를 특정 차원의 숫자로 변환하는 순간, 수학적 공간에서의 관계가 형성된다. 텍스트를 숫자로 바꾸면, 단어와 단어 사이의 추상적인 관계를 벡터 산술 연산으로 풀 수 있다.

원본 텍스트 : 사용자에게 보여주기 위한 용도
숫자 데이터(Embedding) : 수백만 개의 데이터 사이에서 가장 관련 있는 것을 0.01 초 만에 찾아내기 위한 색인 용도

▶ LLM 이전의 임베딩 : BoW 모델

참고 : https://www.youtube.com/watch?v=e9U0QAFbfLI&t=182s

▷ 코사인 유사도

단어가 얼마나 많이 나타났는지 보다는 어떤 단어들이 공통으로 나타났는지 측정한는 지표이다.

▷ 코사인 유사도 계산 절차

1. 단어 빈도수 표 작성

비교하려는 두 문장에 나타난 모든 단어의 갯수를 세어 표로 만든다.

예를 들어 hello world 와 hello 라는 구절이 있다면 아래와 같은 표를 만든다.

2. 벡터의 방향 측정

이 숫자들을 그래프 상의 점으로 찍고 원점에서 그 점까지 선을 긋는다.
이때 코사인 유사도 수식은 이 두 선 사이의 각도를 계산한다.
두 문장이 완전히 같다면 각도는 0도가 되며, 코사인 값은 1이 된다.
두 문장에 공통된 단어가 하나도 없다면 각도는 90도가 되며, 코사인 값은 0이 된다.
위의 경우 "hello world" 와 "hello" 는 hello 라는 단어를 공통으로 가지고 있어, 코사인 값은 71도가 된다.

이는 단어의 빈도만을 따져서 벡터화 하는 전통적인 방식이다.

문장의 길이나 단어의 반복횟수에 영향을 받지 않고, 오직 방향(각도) 에만 집중한다.

이와 같이 단어의 빈도만을 따져서 벡터화 하는 전통적인 방식을 Bag of Words 모델이라고 부른다.

▶ LLM 기반 임베딩

LLM 이전에 벌어진 모든 머신러닝 발전사는 과감히 생략(BoW, 희소 임베딩, 희소 벡터 ..) 하고,

LLM 기반의 임베딩 모델을 학습해보자. LLM 은 단어를 다른 단어와 조합하는 방식을 파악하여 텍스트 문맥에서 단어와 문장의 의미를 이해한다.(단어의 맥락과 속뜻을 숫자로 압축한다).

▷ 임베딩 모델

임베딩 모델은 단순히 단어를 숫자로 치환하는 것이 아니라, Transformer 아키텍쳐 (주로 BERT 계열)을 사용하여 문장 내 단어 간의 관계를 분석한다. 또 그 문장의 의미를 수백~수천개의 숫자로 된 밀집 벡터로 변환한다.

ex ) "배가 맛있다" vs "배를 탄다"

주변 단어들 (맛있다 vs 탄다)을 함께 분석하여 첫번째 배는 광리 공간에, 두번째 배는 탈것 공간에 가깝게 배치한다.

▷ LLM 기반 임베딩의 핵심 특징

1. 의미론적 추론 (Semantic Reasoning)

BoW 모델과 같은 단순한 키워드 일치가 없이도 검색이 가능하다.
각 단어에는 그와 상응하는 의미론적 임베딩이 나란히 배치된다.

의미 유사성이 높은 단어나 문장을 표현하는 숫자 배열은 관련성이 없는 경우보다 가깝게 구성된다.

이때 각 숫자는 부동소수점 값으로, 의미론적 차원(시맨틱 차원)을 나타낸다.

3차원 공간에 모든 벡터를 배치하면 아래와 유사한 형태가 나타난다.

두 벡터 사이의 각도가 작거나 거리가 짧을수록 더욱 유사하다고 판단한다.

이때 두 벡터간 유사도를 산출하는 효과적은 방법은 위에서 설명한 코사인 유사도이다.

2. 다국어 정렬

최신 LLM 모델들은 여러 언어를 같은 공간에 매핑한다. 따라서 다국어 검색 시스템 구축이 매우 쉬워진다.

3. 정보 압축

수만 페이지의 텍스트도 고정된 크기(ex. 1536 개 숫자)의 벡터로 압축된다.

이는 벡터 DB 를 통해 고속으로 검색할 수 있는 기반이 된다.

이제 큰 그림을 이해했으니, 문서 전처리 과정의 첫 단계인 인덱싱을 다시 살펴보도록 하자 ~

[LangChain] 랭체인의 LCEL 구성 컴파일

sian han — Mon, 27 Apr 2026 19:17:24 +0900

※ Runnable 인터페이스

이전 글에서 모델, 프롬프트 템플릿, 출력 파서의 형태에 대해 알아봤다. 이들은 서로 다른 구성 요소를 호출했지만, 유사한 인터페이스와 invoke() 메서드를 사용했다. Runnable 인터페이스는 랭체인의 모든 컴포넌트가 동일한 규격의 입출력 포트를 가지도록 강제하는 표준 프로토콜이다. 만약 각 컴포넌트마다 실행하는 메서드 이름이 제각각이라면, 이들을 하나로 묶기가 매우 까다로울 것이다.

어떤 랭체인 객체이든 Runnable 인터페이스를 상속받았다면 다음 세가지 메서드를 기본적으로 지원한다.

invoke : 하나의 입력을 하나의 출력으로 변환한다.
batch : 여러 입력을 여러 출력으로 변환한다.
stream : 하나의 입력이 생성하는 출력 결과를 실시간으로 전달한다.

컴포넌트가 반복 출력을 지원하지 않아 모든 출력을 하나로 모아 구성하는 경우도 있는데, 방식은 두가지가 있다.

= 이 상황은 여러 번 호출해서 얻은 데이터를 하나의 Response 로 합쳐야 하는 상황을 의미한다. LLM 에게 질문을 던졌을 때, 한 번의 호출로 모든 답을 완벽히 얻기 어려울 수 있다.

명령형 : 직접 model.invoke(...) 를 같은 메서드로 구성 요소를 호출한다.
선언형 : 랭체인 표현 언어 (LCEL LangChain Expression Language) 를 사용한다.

▶ 명령형 구성 (imperative composition)

명령형 구성은 단지 익숙하게 코드를 작성하는 방식의 다른 이름이다.

각 구성 요소를 함수와 클래스로 결합하는 행위가 명령형 구성이다.

아래 예시는 프롬프트와 채팅 모델을 사용해 구성한 챗봇이다.

from langchain_openai import ChatOpenAI
from langchain_core.prompts import PromptTemplate
from langchain_core.output_parsers import StrOutputParser

# 1. 컴포넌트들을 각각 독립적으로 준비
model = ChatOpenAI(model="gpt-4o")
prompt_template = PromptTemplate.from_template("{language}의 주요 특징을 한 문장으로 알려줘.")
parser = StrOutputParser()

# 2. 처리할 데이터 리스트
languages = ["Java", "Python", "Golang"]

# 3. 명령형 방식: 개발자가 직접 흐름을 제어 (Iteration & Aggregation)
final_results = []

for lang in languages:
    # 단계 1: 프롬프트 조립 (PromptValue 생성)
    # 랭체인 내부의 f-string 문법이 여기서 동작합니다.
    prompt_value = prompt_template.invoke({"language": lang})
    
    # 단계 2: 모델 호출 (AIMessage 생성)
    ai_message = model.invoke(prompt_value)
    
    # 단계 3: 출력 파싱 (String 추출)
    parsed_result = parser.invoke(ai_message)
    
    # 단계 4: 결과 모으기
    final_results.append(f"[{lang}]: {parsed_result}")

# 4. 최종 출력
print("\n".join(final_results))

final_results.append() 에서 모든 출력을 하나로 모으고 있다. 컴포넌트 자체가 리스트를 한번에 다 처리해서 주는 기능을 지원하지 않더라도, 개발자가 외부 변수 (final_result) 를 사용해 출력을 하나하나 수집하여 최종 결과물을 구성하기 때문이다.

예상출력 결과는 아래와 같다

[Java]: 정적 타이핑과 객체지향 설계를 바탕으로 대규모 엔터프라이즈 시스템 구축에 최적화된 견고한 언어입니다!!!
[Python]: 간결한 문법과 방대한 라이브러리를 통해 데이터 과학부터 백엔드 개발까지 빠른 생산성을 제공하는 언어입니다!!!
[Golang]: 강력한 동시성 제어와 컴파일 속도를 자랑하며 클라우드 네이티브 환경 및 마이크로서비스 구축에 특화된 언어입니다!!!

▶ 선언형 구성

LCEL (LangChain Expression Language) 는 선언형 언어를 이용해 랭체인 요소를 구성한다.

랭체인은 LCEL 구성을 최적화된 실행 계획으로 컴파일하며, 자동병렬화, 스트리밍, 추적 및 비동기 지원을 수행한다.

최적화된 실행계획으로 컴파일이란,

마치 고수준의 SQL 쿼리를 작성하면, DB 엔진이 가장 빠른 실행계획을 세워 결과를 가져오는 과정같다.

LCEL은 단순히 코드를 짧게 만들어주는 것이 아니라, 프레임워크 수준의 도구이다.

명령형 코드 : 절차 중심으로 작성한다
- ex ) 1단계로 프롬프트를 만들고, 변수를 할당하고, 모델을 부르고, 에러가 나면 재시도하고...
선언형 코드 (LCEL): chain = prompt | model | parser (관계 중심)

이와 같이 파이프로 연결하는 순간, 랭체인은 내부적으로 이 연결 정보를 그래프(Graph) 구조로 저장한다.

개발자는 파이프라인의 입출력 관계만 선언했을 뿐이지만, 랭체인은 이미 전체 지도를 갖게 된다.

▷ 랭체인의 LCEL 구성 컴파일

작성된 LCEL 체인을 실행하는 순간, 랭체인 엔진은 이 그래프를 분석하여 가장 효율적인 실행 경로를 계산한다. 이것이 랭체인의 컴파일 과정이다.

아래는 "최적화된 실행 계획으로 컴파일" 한다는 것의 상세 예시이다

1. 병렬 실행 자동화

만약 체인 안에 여러개의 독립적인 작업이 있다면, 랭체인은 사용자가 멀티스레딩 코드를 짜지 않아도 알아서 동시에 실행한다.

2. 스트리밍 및 비동기 최적화

LCEL 로 구성된 체인은 내부의 모든 컴포넌트가 동일한 인터페이스(Runnable)을 따른다. 랭체인의 모든 컴포넌트(프롬프트, 모델, 파서)가 Runnable 이라는 규격을 따르고 있다는 것은, 모든 부품들이 실시간 스트리밍 모드(stream 메서드)를 공통으로 지원한다는 뜻이다.

모델 : 텍스트를 한꺼번에 주지 않고 토큰 단위로 뱉어냄
파서 : 들어온 텍스트 조각을 즉시 해석해서 다음 단계로 넘길 수 있도록 설계됨

일반적인 명령형 코드에서는 데이터를 다 받을 때까지 기다렸다가 다음 단계로 넘기지만, LCEL은 데이터를 조각 단위로 쪼개서 실시간으로 흘려보낸다. 랭체인은 이를 분석하여, 첫번째 단어가 생성하자마자 파서를 통과시켜 사용자에게 전달하는 최단 거리의 데이터 파이프라인을 구축한다.

예제 : "안녕하세요, 반가워요"
- 1. 모델이 "안" 이라는 첫 토큰을 뱉음
- 2. "안" 은 Runnable 인터페이스를 타고 즉시 파서로 흐름
- 3. 파서는 "안"을 받자마다 가공해서 사용자에게 바로 전달함
- 4. 사용자는 모델이 전체 문장을 다 만들기도 전에 화면에서 첫 글자가 나타나는 것을 보게 됨

3. 지연 시간 최소화

데이터가 모델 내부에서 파서로, 파서에서 사용자에게로 이동할때 완성될 때까지 기다리는 정체 구간이 없음.

랭체인을 사용해 LLM 애플리케이션을 구축하는 필요한 구성요소는 아래와 같다.

LLM 모델: 예측을 수행함
프롬프트 지시사항 : 바람직한 결과물을 도출하도록 유도함
출력 파서 : 모델의 출력 형식을 변환함

LLM 애플리케이션은 위와 같은 구성요소로 체인을 형성한다.

모든 랭체인 구성 요소는 다양한 입력과 출력을 처리하는 동일한 인터페이스를 공유한다.

다음은 AI 챗봇에 외부 데이터를 컨텍스트로 제공하는 방법을 익혀보자.

[LangChain] LLM 에서 특정 형식의 답변 지정

sian han — Mon, 27 Apr 2026 09:22:34 +0900

애플리케이션에서 LLM 이 작업한 결과를 구조화된 형식으로 전달하면 다른 코드가 처리할 수 있어 매우 유용하다.

▶ JSON 출력

JSON 출력은 프런트엔드 코드에 전달하거나 DB 에 저장할 수 있다.

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from pydantic import BaseModel, Field

# 1. 응답 구조 정의 (Pydantic 모델)
# 모델이 내보낼 JSON의 '스키마' 역할을 합니다.
class AnswerWithJustification(BaseModel):
    answer: str = Field(description="사용자의 질문에 대한 핵심 답변")
    justification: str = Field(description="답변에 대한 기술적 근거 또는 이유")

# 2. 모델 설정
llm = ChatOpenAI(model="gpt-4o", temperature=0)

# 3. 모델에 구조적 출력 기능 입히기 (핵심!)
# 이 단계를 거치면 llm은 무조건 AnswerWithJustification 형식을 따릅니다.
structured_llm = llm.with_structured_output(AnswerWithJustification)

# 4. 프롬프트 정의
# 여기서는 지구 복잡한 format_instructions를 넣을 필요가 없습니다.
prompt = ChatPromptTemplate.from_messages([
    ("system", "너는 백엔드 개발 전문가야. 질문에 대해 정확한 답변과 근거를 제공해줘."),
    ("user", "{question}")
])

# 5. 체인 구성 (파서가 필요 없음!)
chain = prompt | structured_llm

# 6. 실행
question_text = "레이어드 아키텍처(Layered Architecture)의 장점은 뭐야?"
response = chain.invoke({"question": question_text})

# 7. 결과 확인
print("--- 결과 타입 ---")
print(type(response))

with_structured_output 메서드는 선언된 스키마 AnswerWithJustification 를 두가지 용도로 활용한다.

스키마를 JSONSchema 객체로 변환하해 LLM 에 전송한다. 해당 객체는 JSON 데이터의 구조를 기술한다.

스키마는 LLM이 변환한 출력물을 반환하기 전에 그 유효성을 검증한다.

JSON 외에도 CSV나 XML 같은 출력물을 생성하도록 지시할 수 있는데, 이 경우 출력파서가 유용한다.

▶ 출력파서

LLM 응답을 구조화 하는 클래스다. 출력 파서는 아래 두 가지 기능을 수행한다.

출력 형식 지정 : 프롬프트에 추가 지시 사항을 삽입해, LLM이 파싱하기 좋은 형식으로 텍스트를 출력하도록 유도한다.
출력 검증 및 파싱 : LLM 또는 채팅 모델의 텍스트 출력 겨로가물을 받아 리스트, XML 등의 구조화된 형식으로 가공한다. 불필요한 정보를 제거하고, 불완전한 출력을 수정하며, 파싱한 값을 검증한다.

▷ CSV 출력 파서 예제

CommaSeparatedListOutputParser 파서는 모델이 내놓은 문자열을 파이썬의 list 객체로 변환해준다.

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import CommaSeparatedListOutputParser

# 1. 모델 설정
model = ChatOpenAI(model="gpt-4o", temperature=0)

# 2. CSV 출력 파서 설정
output_parser = CommaSeparatedListOutputParser()

# 3. 프롬프트 템플릿 정의
# get_format_instructions()는 "쉼표로 구분된 리스트로 답해라"라는 지시문을 생성합니다.
prompt = ChatPromptTemplate.from_messages([
    ("system", "너는 IT 기술 트렌드 전문가야. 사용자가 제시한 주제와 관련된 기술 키워드 5개를 뽑아줘.\n{format_instructions}"),
    ("user", "{subject}")
])

# 4. LCEL 체인 구성
chain = prompt | model | output_parser

# 5. 실행
# format_instructions를 반드시 입력값으로 넣어줘야 모델이 형식을 지킵니다.
response = chain.invoke({
    "subject": "MSA(Microservices Architecture)",
    "format_instructions": output_parser.get_format_instructions()
})

# 6. 결과 확인
print("--- 결과 타입 ---")
print(type(response)) # <class 'list'>

print("\n--- 파싱된 리스트 ---")
print(response)

이때 parser 가 내부적으로 어떻게 작동하냐면

1. 모델의 원본 응답 (AIMessage)

먼저 모델은 내부적으로 아래와 같은 문자열을 생성한다.

"Docker, Kubernetes, Kafka, API Gateway, gRPC"

2. 파서의 처리 (OutputParser)

CommaSeparatedListOutputParser 가 쉼표를 기준으로 문자열을 쪼개고, 각 단어의 앞뒤 불필요한 공백을 제거한다.

3. 최종결과

파이썬 코드에서 즉시 사용가능한 리스트 객체가 된다.

['Docker', 'Kubernetes', 'API Gateway', 'gRPC']

랭체인은 CSV, XML 등 다양한 경우에 대응하는 출력 파서를 제공한다.