피터의 개발이야기

[온디바이스AI] 로컬 LLM에서 중요한 것은 CPU가 아니라 메모리다 - 맥미니와 모델 크기의 관계

기록하는 백앤드개발자 — Wed, 20 May 2026 11:20:07 +0900

TL;DR

로컬 LLM 환경에서 가장 먼저 부딪히는 벽은 연산 성능보다 메모리다.

작은 모델은 “문장을 생성”하지만,
큰 모델은 “컨텍스트를 유지하며 추론”한다.

결국 로컬 AI 머신의 핵심은 CPU 속도가 아니라,
얼마나 큰 모델과 Context를 메모리에 안정적으로 올릴 수 있는가에 가깝다.

ㅁ 들어가며

오늘 한 크루가 맥미니를 구매해서 로컬 LLM 기반 서비스를 직접 만들어 보고 싶다고 이야기했다.

그러면서 자연스럽게 이런 질문이 나왔다.

“맥미니를 산다면 CPU가 중요할까, GPU가 중요할까?”

처음에는 보통 코어 수나 GPU 성능을 먼저 보게 된다.

그런데 실제로 로컬 LLM을 구성해보면 병목은 생각보다 다른 곳에서 먼저 나타난다.

좀 더 자세한 글) [AI] GPU vs PIM vs NPU - 내 시스템의 병목은 연산인가, 메모리인가

모델이 커질수록 가장 먼저 부족해지는 것은 연산 성능보다 메모리다.

특히 Apple Silicon은 통합 메모리 구조이기 때문에 이 특징이 더 강하게 드러난다.

ㅁ 로컬 LLM은 왜 메모리를 많이 먹는가

일반적인 PC에서는 CPU 메모리와 GPU VRAM이 분리되어 있다.

하지만 Apple Silicon은 다르다.

CPU, GPU, Neural Engine이 모두 같은 메모리를 공유한다.

즉 로컬 LLM을 실행할 때 메모리는 단순히 “프로그램 실행 공간”이 아니다.

다음 요소들이 모두 메모리를 사용한다.

모델 가중치(weight)
KV Cache
Context Window
Embedding
Attention 중간 상태
RAG 데이터 처리

문제는 모델이 커질수록 단순히 저장 공간만 늘어나는 것이 아니라,
“계속 읽어와야 하는 데이터”가 급격히 증가한다는 점이다.

특히 추론(decode) 단계에서는:

이전 토큰 상태를 계속 참조하고
KV Cache를 반복적으로 읽고
긴 Context를 유지해야 한다.

즉 AI 추론은 생각보다 “계산”보다 “메모리 접근” 비용이 더 커진다.

그래서 로컬 LLM에서는 CPU 성능보다 메모리 용량과 대역폭이 훨씬 중요하게 체감된다.

ㅁ 작은 모델은 왜 쉽게 맥락을 잃는가

처음 로컬 LLM을 접하면 7B~8B 모델만으로도 꽤 놀랍다.

번역도 되고,
요약도 되고,
코드도 어느 정도 작성한다.

하지만 조금만 복잡한 작업을 시키면 한계가 드러난다.

예를 들면:

이전 조건을 잊는다
긴 문서를 읽다가 핵심을 놓친다
여러 제약을 동시에 유지하지 못한다
Agent 흐름이 쉽게 무너진다

처음에는 “프롬프트를 잘못 준 것 아닐까?”라고 생각했는데, 계속 사용하다 보니 단순 프롬프트 문제가 아니었다.

작은 모델은 “문장을 생성”하는 능력은 괜찮지만, 긴 흐름을 유지하며 추론하는 능력은 제한적이다.

즉 말은 자연스럽지만, 생각의 지속성이 약하다.

ㅁ 모델 크기가 커질수록 달라지는 점

14B~16B 정도부터는 확실히 느낌이 달라진다.

이 구간부터는:

여러 조건을 동시에 유지하고
문서 구조를 이해하려 하고
이전 Context를 덜 잊는다.

특히 RAG와 연결했을 때 차이가 크다.

7B에서는 검색된 문서 일부만 참고하다가 핵심을 놓치는 경우가 많았는데,
16B급부터는 “문서를 기반으로 답하려는 느낌”이 생긴다.

그리고 32B 구간부터는 체감이 더 커진다.

이 시점부터는:

장기 Context 유지
설계 reasoning
Multi-Agent 흐름
코드 구조 이해

같은 작업이 꽤 안정적으로 동작한다.

개인적으로는 이 구간부터 로컬 LLM이 단순 장난감이 아니라 “도구”처럼 느껴진다.

실사용 관점으로 정리하면 대략 이런 느낌이다.

모델급	권장 메모리	체감 능력
7B~8B	16GB	번역, 요약, 단순 코드 보조, 짧은 질답	추론 깊이가 얕음. 긴 대화에서 맥락 손실 잦음
14B~16B	24~32GB	간단한 추론, 문서 구조 이해, 기본 Agent 가능	여러 조건 비교/장기 계획 약함
32B	64GB	“생각하는 느낌”이 생김. RAG 활용 안정화	복합 추론에서 아직 실수 존재
70B	128GB+	클라우드 모델에 가까운 품질 체감	비용/속도 부담 큼
MoE 대형 모델	128GB~256GB	특정 영역 매우 강력	로컬 운영 난이도 매우 높음

ㅁ 결국 맥미니에서 중요한 것은 메모리다

흥미로운 점은 로컬 LLM 환경에서는 CPU 업그레이드보다 메모리 업그레이드 체감이 훨씬 크다는 점이다.

실제로는 다음처럼 느껴진다.

여기서 중요한 점은 “실행 가능”과 “안정적으로 운용 가능”은 완전히 다르다는 것이다.

메모리가 부족하면 일부 데이터를 SSD swap으로 넘기게 되는데, 이 순간부터 응답 속도가 급격히 느려진다.

그리고 단순히 느려지는 것을 넘어서, 추론 흐름 자체가 끊기는 느낌이 발생한다.

ㅁ 마무리 — 로컬 LLM의 병목은 결국 메모리다

처음에는 로컬 AI 머신이라고 하면 CPU나 GPU 성능을 먼저 떠올리게 된다.

하지만 실제로 계속 실험해보면 생각보다 더 중요한 것은

“얼마나 큰 모델과 Context를 메모리에 안정적으로 유지할 수 있는가”

였다.

결국 로컬 LLM 환경에서 중요한 것은 단순 FLOPS가 아니라,
Context를 잃지 않고 계속 유지할 수 있는 메모리 구조에 더 가까운 것 같다.

[독후감] 협상의 기술

기록하는 백앤드개발자 — Sun, 10 May 2026 00:25:26 +0900

https://product.kyobobook.co.kr/detail/S000000597965

ㅁ 들어가며

예전에 읽었던 세이노의 가르침에서 추천했던 책이다.
나는 책을 읽을 때 단순히 내용을 따라가기보다, 작가와 대화하듯 읽으려고 한다. 그래서 먼저 작가가 어떤 사람인지 이해하고, 어떤 경험과 관점으로 자신의 생각을 전달하려 하는지 살펴본다. 그리고 각 챕터가 그 핵심적인 생각을 어떤 방식으로 풀어내고 있는지 작가의 입장에서 따라가며 읽으려 노력한다.

ㅁ ChatGPT 작가의 사고방식을 이해하며 읽기

허브 코헨을 이해하기 위해 단순히 책의 내용만 따라가지는 않았다.

책을 읽다가 생기는 궁금한 점이나 이해되지 않는 관점들을 계속 정리하며, 작가가 왜 이런 사례를 들었는지, 결국 어떤 생각을 전달하려 하는지 스스로 해석해보려 했다.

특히 허브 코헨은 일반적인 자기계발서처럼 핵심 이론을 먼저 설명하는 방식으로 글을 쓰지 않는다. 오히려 다양한 사례를 먼저 보여주고, 독자가 그 안에서 스스로 핵심을 발견하도록 유도하는 방식에 가깝다. 그래서 처음에는 “이 사례는 왜 등장했을까?”, “결국 무엇을 말하려는 걸까?”라는 생각이 자주 들었다.

하지만 이런 흐름을 따라가다 보니, 허브 코헨은 단순히 협상 기술을 설명하려는 사람이 아니라, 독자가 기존의 고정된 사고방식을 다시 바라보게 만드는 사람이라는 점을 조금씩 이해하게 되었다. 그는 정답을 직접 설명하기보다, 사례를 통해 독자의 생각을 흔들고 스스로 깨닫게 만드는 방식으로 글을 전개하고 있었다.

이런 흐름을 더 깊게 이해하기 위해, 나는 ChatGPT에게 허브 코헨의 관점과 말하는 방식을 함께 분석하여 작가처럼 답변해달라고 요청했다. 단순히 내용을 요약해달라는 것이 아니라, 마치 허브 코헨 작가와 대화하듯 “왜 이런 사례를 들었는가”, “이 상황에서 무엇을 말하려는 것인가”를 계속 질문하며 읽었다.

특히 이해가 어려웠던 부분은 『세상에 불가능한 협상은 없다』 챕터였다. 사례는 계속 이어지는데 명확한 결론이 바로 드러나지 않아 처음에는 흐름을 따라가기 어려웠다. 하지만 대화를 이어가며, 허브 코헨은 협상 기술 자체를 설명하려는 사람이 아니라 독자의 고정된 사고방식을 흔들고 새로운 관점으로 상황을 바라보게 만드는 사람이라는 점을 조금씩 이해하게 되었다.

이 과정은 단순히 책 내용을 정리하는 것과는 달랐다. 오히려 작가의 머릿속 사고 흐름을 따라가며 “왜 이런 생각을 했는가”를 추적하는 경험에 가까웠다. 덕분에 책의 내용을 외우기보다, 허브 코헨이 세상을 바라보는 방식을 조금 더 이해하며 읽을 수 있었다.

ㅁ 작가에 대한 이해

허브 코헨(Herb Cohen)(1931~2015)은 50년 넘게 미국 대통령, 법무부, FBI, CIA 등에서 협상 자문을 맡아온 세계적인 실전 협상 전문가이다.

그의 특징은 협상을 비즈니스 기술서가 아니라 일상 인간관계의 본질로 본다는 점이다.

여러분 각자 자신의 자리와 신념의 체계 안에서 자신만의 고유한 요구를 바탕으로 자신이 원하는 것을 얻는 방법을 깨닫기 바란다.
머릿말, p9

그는 협상을 기술적이나 법률적으로 설명하지 않고, 일상에 포함한 인간 행동의 문제로 설명한다.

그래서 책에서도 법칙이나 이론보다 실제 사례와 심리 묘사가 많다.

그의 문체 특징도 뚜렷하다.
- 이론보다 이야기 중심
- 우화·실화·농담이 많음
- 상대 심리를 해석하는 방식
- 독자에게 “세상은 이렇게 돌아간다”를 체험시키는 구조
그래서 책을 읽다 보면 “논리적으로 설명한다”기보다, 마치 경험 많은 협상가가 옆에서 사례를 들려주는 느낌이 강하다.

허브 코헨의 핵심 관점은 크게 세 가지로 정리된다.
협상은 정보, 시간, 힘의 게임이다. p22

협상 능력이란 행동에 영향을 미치는 정보, 시간, 힘을 분석하여 요구가 자신이 원하는 방식대로 이루어지도록 만드는 것이다. p23

협상은 한계를 넘어서는 힘인 것이다. 하지만 그것이 윤리적 판단은 중립적이다.

협상가로서 위험을 감수하고, 과거의 경험에서 벗어나 자신이 세운 가정에 도전하고, 목표 수준을 높이고, 기대치를 높여야한다. p33

그래서 그의 글에는 극단적인 초기 입장, 허세, 시간 끌기, 애매한 표현, 심리 압박 같은 요소가 자주 등장한다.

내가 책을 읽으면서 불편함을 느꼈던 부분도 바로 이런 지점이었다.

현대 기준에서는 다소 공격적이거나 조작적으로 보일 수 있는 사례도 많아 비도덕적으로 느껴진다. 예로 말보로 담배 한개비 p78

힘이 그 자체로 좋거나 나쁘지는 않다. 도덕적이거나 비도덕적이지도 않다. 윤리적인 것도 비윤리적인 것도 아니다. 힘은 중립적이다. p73
가능한 여러 목표에 따라 힘을 나눠보면 목표는 유쾌하게 '좋은 것' 또는 가증스럽게 '나쁜 것'일 수 있지만, 그 목표를 달성하는 데 사용하는 힘은 전기나 바람처럼 중립적이다. p74
합당한 범위 내에서, 자신이 가진 옵션에 대해 알고 있고, 자신이 세운 가정을 시험해보고, 확실한 정보를 기반으로 계산한 위험을 감수하고, 자신이 힘을 가지고 있다고 믿는다면 당신은 자신이 원하는 것을 얻을 수 있다. p78

다만 허브 코헨은 협상이 단순히 속이는 기술을 말하려는 사람은 아니다.

오히려 인간 사회 자체가 완전히 합리적이지 않다는 현실을 인정하고, 그 현실 속에서 손해 보지 않기 위한 관찰력을 강조한다.

윤리적인 윈윈 협상가

작가는 이상적인 윤리만으로는 실제 협상에서 밀릴 수 있다는 현실주의적 시각이 강하다. 일반적으로 협상이라고 하면 자신의 이익을 얻기 위한 기술을 떠올리기 쉽지만, 작가는 오히려 상대를 억압하거나 파괴하지 않고 사람들의 사고방식 자체를 변화시키려 했던 인물들을 예로 들고 있다.

두 사람은 초라한 옷을 입고 돌아다니며 사람들에게 질문하며 정보를 수집했다. 1명은 삼단논법을, 다른 1명은 비유를 사용했다. 그들에게는 목표와 기준이 있었다. 그들은 기꺼이 위험을 감수했다. ~중간생략~
그 두 사람은 예수 그리스도와 소크라테스다. 내가 보기에 그 둘은 협상가였다. 그들은 윤리적인 윈윈 협상가들이었고, 힘을 가진 사람들이었다. p23

예수님는 비도더적인 상황에서 십자가에 못박혀 돌아가셨다. 하지만 그의 협상가로서 성경을 통해 오늘도 그 힘은 영향력을 가지고 있다.

소크라테스도 당시 아테네 사회의 기존 가치와 권위에 계속 질문을 던졌고, 결국 많은 사람들에게 불편한 존재가 되었다. 특히 젊은이들을 타락시킨다는 혐의와 신을 부정했다는 이유로 재판에 넘겨졌고, 끝내 사형 선고를 받아 독배를 마시고 죽었다.

예수는 사랑과 용서를 통해 사람들의 삶의 방향을 바꾸려 했고, 소크라테스는 질문과 대화를 통해 스스로 생각하게 만들려 했다. 둘 다 강압적으로 상대를 이기려 하지 않았고, 오히려 사람들에게 새로운 관점을 제시하며 스스로 깨닫게 만들었다는 공통점이 있다.

하지만 현실 세계에서 도덕적 방식은 언제나 환영받는 것은 아니었다. 기존 질서와 사고방식을 흔드는 사람은 결국 불편한 존재가 되기 쉽기 때문이다.

그래서 허브 코헨이 말하는 “윤리적인 윈윈 협상가”라는 표현은 단순히 착하고 부드러운 사람이라는 뜻이 아니라, 자신의 기준과 가치관을 유지하면서도 사람들의 생각과 선택을 변화시키려 했던 사람들에 더 가까워 보였다.

권력에 의지하기 위해 폭력적이 될 필요는 없고,
양심적으로 말하기 위해 온순할 필요는 없다.
가장 효과적인 행동은 권력에 의지하면서
양심적으로 행동하는 것이다. (바바라 데밍) p369

내가 이해한 작가가 말하고자 하는 협상가는 상대를 이기려는 단일 목적이 아니라, 사람들에게 새로운 관점을 제시하여 상생하는 윈윈 협상가이다. 다만 그 협상은 한계를 넘어서기 위해서 자신의 힘, 시간, 정보를 기반으로 합당한 범위 내에서 위험을 감수해야 한다. 작가는 이를 설명하기 위해 이 책에서 법칙이나 이론보다 실제 사례와 심리 묘사로 스스로 해석하게 하였다.

ㅁ 협상으로 이루어진 세상

1. 협상이란 무엇인가

허브 코헨은 협상을 단순한 대화 기술이 아니라, 상대의 선택과 행동을 변화시키는 과정으로 설명한다.
특히 협상은 특별한 상황이 아니라 인간관계 속에서 이미 매일 반복되고 있는 일상적인 구조라고 바라본다.

인상적이었던 점은 협상을 “이기는 기술”보다 “원하는 결과를 얻기 위한 조율 과정”으로 설명한다는 점이었다.
결국 협상은 말을 잘하는 능력보다, 사람과 상황을 어떻게 이해하고 움직이느냐의 문제에 가까워 보였다.

2. 세상에 불가능한 협상은 없다

이 챕터는 처음 읽을 때 가장 이해하기 어려웠던 부분이었다.
사례는 계속 이어지는데 명확한 결론이 바로 드러나지 않았기 때문이다.

하지만 계속 읽다 보니 허브 코헨은 “불가능한 협상은 없다”는 말을 낙관적으로 사용하는 것이 아니었다.
오히려 사람들이 스스로 조건을 고정된 것으로 생각하기 때문에 협상이 막히는 것이며, 관점을 바꾸면 새로운 선택지가 보일 수 있다는 점을 말하려 했던 것 같다.

결국 이 챕터의 핵심은 협상 기술보다, 기존 사고방식을 흔드는 데 있었다.

3. 협상의 세계에 발 들여놓기

허브 코헨은 협상을 거창한 비즈니스 기술이 아니라, 이미 우리의 삶 전체에 포함된 구조로 설명한다.
가족, 친구, 직장, 식당 주문처럼 아주 작은 선택과 조율 속에서도 협상은 계속 일어난다.

이 챕터를 읽으며 느꼈던 것은, 협상을 특별한 능력으로 바라보기보다 인간관계를 이해하는 관점 자체로 받아들이고 있다는 점이었다. 경쟁을 붙이기, 필요 충족하기, 할인 중 등 직원과의 관계에서 안될 것 같은 협상에 정말 다양한 대안을 제시하고 있다.

ㅁ 협상을 좌우하는 3가지 변수

허브 코헨는 협상의 흐름을 결정하는 핵심 요소로

- 힘(당신에게 힘이 있다는 사실을 인지하라),

- 시간(협상은 인내심 싸움이다),

- 정보(상대가 말하지 않는 정보까지 캐내라)

를 제시한다.

그리고 협상은 결국 이 세 가지 변수를 얼마나 잘 이해하고 활용하느냐에 따라 결과가 달라진다고 설명한다.

특히 인상적이었던 점은, 이 요소들이 단순히 객관적인 사실만으로 작동하지 않는다는 점이었다.

실제 힘보다 “힘이 있다고 믿게 만드는 인식”이 더 중요하기도 하고,

시간 자체보다 “누가 더 조급한가”가 협상의 흐름을 결정하기도 한다.

결국 협상은 논리만의 문제가 아니라 인간 심리와 상황 인식의 문제에 더 가까워 보였다.

작가는 힘을 매우 현실적으로 바라본다.
힘은 선하거나 악한 것이 아니라 목표를 이루기 위해 사용하는 중립적인 도구라고 설명한다.

“힘은 그 자체로 좋거나 나쁘지 않다. 힘은 결과가 아니라 수단이다.” p73~76

그래서 책 속에서는 경쟁 유도, 시간 끌기, 애매한 표현, 심리 압박 같은 현실적인 사례들도 자주 등장한다. 처음에는 이런 방식들이 다소 불편하게 느껴졌다. 하지만 허브 코헨은 이를 단순한 속임수로 설명하기보다, 현실 사회가 실제로 어떻게 움직이는지를 보여주려 했던 것 같다.

결국 이 챕터에서 가장 중요하게 느껴졌던 부분은, 협상은 말을 잘하는 사람이 유리한 게임이 아니라는 점이었다. 상대가 무엇을 원하고 있는지, 누가 더 급한지, 어떤 정보와 선택지를 가지고 있는지를 얼마나 잘 이해하느냐가 협상의 흐름을 결정하고 있었다.

ㅁ 2가지 협상 스타일

허브 코헨은 협상 방식을 크게 두 가지 스타일로 나누어 설명한다.

7. “무슨 수를 써서라도 이긴다” 소련 스타일

첫 번째는 상대를 이겨야만 성공이라고 생각하는 “소련 스타일”이다. 이 방식은 극단적인 요구, 심리 압박, 시간 끌기, 허세 같은 방법을 적극적으로 사용한다. 협상을 서로의 조율 과정이 아니라 승패의 문제로 바라보며, 상대보다 우위를 점하는 것 자체를 중요하게 생각한다.

처음에는 이런 방식이 다소 공격적이고 비도덕적으로 느껴졌다. 하지만 허브 코헨은 이런 사례들을 단순히 따라 하라고 설명하기보다, 현실 사회에서는 실제로 이런 방식으로 움직이는 사람들도 존재한다는 점을 보여주려 했던 것 같다. 결국 이런 스타일을 이해해야 상대의 전략에 휘둘리지 않을 수 있기 때문이다.

8. “협상은 쌍방을 위한 것” 윈윈 스타일

반면 작가가 궁극적으로 지향하는 방식은 “윈윈 스타일”이다. 이 방식은 상대를 무너뜨리는 것이 아니라, 서로가 원하는 것을 조율하며 함께 만족할 수 있는 결과를 찾는 협상에 가깝다.

흥미로웠던 점은 허브 코헨이 단순히 착하고 양보하는 태도를 윈윈이라고 설명하지 않는다는 점이었다. 오히려 자신의 힘과 정보, 기준을 명확히 이해한 상태에서 상대와 현실적인 균형점을 찾는 과정을 더 중요하게 바라본다.

9. 상호 만족을 위한 협상의 기술

이 챕터에서는 실제로 어떻게 서로 만족할 수 있는 협상을 만들어가는지 설명한다.

특히 책 초반에 예수와 소크라테스를 “윤리적인 윈윈 협상가”로 설명한 부분이 인상적이었다. 두 사람 모두 상대를 강압적으로 이기려 하기보다, 질문과 대화를 통해 사람들의 사고방식 자체를 변화시키려 했기 때문이다.

나는 유혹이나 사기 게임에 대해 말하는 것이 아니다. 협력적인 셥셩에서는 음해, 위협, 수작을 부리기 위한 유려한 말솜씨, 조작, 허튼소리, 수완이나 흥정이 필요없다.
반대로 지속적인 관계를 만들고 유지하는 방향으로 전략을 수립하기 제안한다. 신뢰하는 당사자들은 동증하며 상호 간에 이익을 취할 수 있는 방향으로 문제를 해결하기 위해 에너지를 쏟아붓는다. p303
승리란 자신의 신념과 가치에 맞게 당신의 요구를 충족시키는 것을 의미한다. 승리는 상대측이 정말로 원하는 것을 아라내고 그들에게 당신이 원하는 것을 얻을 방법을 보여주는 것을 의미한다. p308

결국 이 챕터를 읽으며 느꼈던 것은, 허브 코헨이 말하는 좋은 협상가는 단순히 말을 잘하거나 상대를 이기는 사람이 아니라는 점이었다. 자신의 기준과 가치관을 유지하면서도, 사람들의 선택과 생각을 긍정적인 방향으로 움직일 수 있는 사람이 더 이상적인 협상가에 가까워 보였다.

ㅁ 어디서나, 누구와도 협상하기

허브 코헨은 마지막 파트에서 협상을 단순한 이론이 아니라, 현실 속 인간관계와 실제 상황에서 어떻게 적용해야 하는지 설명한다.
특히 이 챕터에서는 협상이 결국 사람 사이에서 이루어지는 일이라는 점을 반복해서 강조한다.

10. 비대면 전화 협상에서 합의 각서는 필수
허브 코헨은 전화 협상이나 비대면 협상에서는 특히 기록과 문서가 중요하다고 설명한다.
대면 상황에서는 표정과 분위기, 관계를 통해 어느 정도 의도가 전달되지만, 전화나 문서 중심 협상에서는 작은 표현 차이도 오해로 이어질 수 있기 때문이다.
그래서 그는 협상이 끝난 뒤 반드시 합의 내용을 정리하고 확인하는 과정을 중요하게 본다.
특히 기억에 의존하지 말고, 서로가 이해한 내용을 문서로 남겨야 이후의 갈등과 책임 문제를 줄일 수 있다고 말한다.

이 부분은 확실히 공감이 되는 부분인데, 나 또한 회의록을 중요시 여기기 때문이다.

간단한 구두 내용이라도 메신저에 짧게 공유하려고 한다.

읽으며 느꼈던 점은, 협상은 단순히 말을 잘하는 기술이 아니라 결국 신뢰와 책임의 문제라는 점이었다.
좋은 협상은 상대를 설득하는 데서 끝나는 것이 아니라, 이후에도 서로 같은 이해를 유지할 수 있도록 구조를 만드는 과정에 가까워 보였다.

11. 결정권자와 협상하라
이 챕터에서 허브 코헨은 매우 현실적인 이야기를 한다.
아무리 좋은 협상을 해도, 실제 결정을 내릴 수 없는 사람과 이야기하고 있다면 결과는 바뀌지 않을 수 있다는 점이다.

당연한 부분이다.

실무자와 긴 시간 대화를 나누더라도, 결국 최종 승인권자가 따로 있다면 협상 내용이 뒤집히거나 처음부터 다시 시작되는 경우가 많다. 그래서 작가는 협상 초반부터 “누가 실제 결정권자인가”를 파악하는 것을 매우 중요하게 설명한다.

이 부분을 읽으며 협상은 단순히 논리의 문제가 아니라 구조의 문제라는 생각이 들었다.
무엇을 말할 것인가도 중요하지만, 누구와 이야기하고 있는가 역시 협상의 중요한 변수였다.

12. 사람 대 사람으로 협상하라
허브 코헨이 마지막까지 강조하는 것은 결국 협상은 사람과 사람 사이의 관계라는 점이었다.

회사, 조직, 계약이라는 형식을 이야기하고 있지만, 실제로는 결국 감정을 가진 사람들이 선택하고 판단한다. 그래서 그는 지나치게 형식적이거나 딱딱한 태도보다, 인간적으로 관계를 만들고 상대를 이해하려는 태도를 더 중요하게 바라본다.

특히 인상적이었던 부분은, 사람들은 논리만으로 움직이지 않는다는 점이었다.

협상의 터닝 포인트(p375)
1. 경찰관의 고나심을 교통 위반 딱지에서 다른 곳으로 돌린다.
2. 경찰관이 당신을 개인적인 대상으로 인식하게 한다.
3. 경찰관이 교통 위반 딱지에 볼펜을 갖다 대는 것을 막거나 적어도 지연시킨다.

존중받고 있다고 느끼는가, 자신의 입장이 이해받고 있다고 느끼는가 같은 감정적인 요소들도 협상 결과에 큰 영향을 미친다.

결국 허브 코헨이 말하는 좋은 협상가는 단순히 말을 잘하거나 상대를 압박하는 사람이 아니었다. 상대를 하나의 인간으로 이해하고, 서로의 관계 속에서 현실적인 합의점을 만들어갈 수 있는 사람이 더 좋은 협상가에 가까워 보였다.

ㅁ 마무리

『협상의 기술』은 단순히 협상 기술을 설명하는 책이 아니었다.

사실 이 책을 읽으며 힘들었던 점은, 허브 코헨이 정답을 직접 설명하기보다 사례를 통해 그 의도 스스로 깨닫게 만든다는 점이었다. 그래서 이 책은 읽는 과정에서 중심 과제를 놓치게 되는 경향이 있었다. 작가의 핵심 의도를 먼저 파악하는게 중요하였다.

처음에는 말 잘하는 방법이나 설득 기술에 대한 이야기라고 생각했지만, 읽을수록 인간의 심리와 관계, 그리고 사람들이 어떻게 선택하고 움직이는지를 관찰하는 책에 더 가까웠다. 다시 말하지만, 중간 결론이 없어 ??만 남았지만 말이다.

특히 허브 코헨은 협상을 단순한 승패의 문제로 바라보지 않았다. 현실적으로는 힘, 시간, 정보 같은 요소들이 매우 중요하게 작동하지만, 궁극적으로는 상대를 무너뜨리는 것이 아니라 서로가 원하는 방향을 조율하며 함께 살아가는 과정으로 협상을 바라보고 있었다.

물론 책 속 일부 사례들은 지금 기준에서 다소 공격적이거나 불편하게 느껴지기도 했다. 하지만 그런 부분들조차 현실 사회가 실제로 어떻게 움직이는지를 보여주기 위한 관찰의 과정이라고 생각하니, 단순히 기술을 배우는 느낌보다는 세상을 바라보는 새로운 관점을 배우는 경험에 가까웠다.

결국 내가 이해한 허브 코헨의 핵심 메시지는 단순히 “잘 협상하는 법”이 아니었다. 사람과 상황을 더 넓게 이해하고, 자신의 기준을 유지하면서도 서로가 함께 살아갈 수 있는 방향을 찾는 것. 그것이 그가 말하는 궁극적인 윈윈 협상가의 모습에 더 가까워 보였다.

[AI] GPU vs PIM vs NPU - 내 시스템의 병목은 연산인가, 메모리인가

기록하는 백앤드개발자 — Sat, 2 May 2026 07:10:11 +0900

TL;DR

GPU와 PIM은 같은 축의 다음 세대가 아니라, 서로 다른 병목을 푸는 도구다.

GPU는 FLOPS를 늘리고, PIM은 Byte 이동을 줄인다 — 경쟁재가 아니라 조합재.

ㅁ 들어가며

[AI] 인공지능에 대한 이해(2017에 정리한 리포트)에서 PIM을 언급하고,

[AI] PIM(Processing In Memory)란?에서 PIM을 단독으로 정리한 적이 있다.

이번에는 GPU·NPU와 함께 놓고 '병목 위치' 관점에서 다시 본다.

AI 모델에 GPU를 쓰는 이유에 대한 글을 읽다가 자연스럽게 PIM(Processing In Memory)이 떠올랐다.

처음에는 "GPU 다음 세대" 정도로 막연하게 묶어 두고 있었는데,
정리하다 보니 둘은 같은 축이 아니었다.

결론부터 말하면 GPU는 연산을 빠르게 하는 구조, PIM은 데이터 이동을 줄이는 구조다.
같은 문제의 다른 단계를 푸는 도구다. 이 글은 그 차이를 병목 위치 관점에서 정리한다.

ㅁ 연산이 아니라 데이터 이동이 비싸졌다

GPU의 강점은 분명하다.

대규모 병렬 행렬·벡터 연산. 딥러닝의 핵심 연산 — 행렬 곱, 벡터 누적 은 GPU의 SIMT 구조와 정확히 맞아떨어진다.

문제는 모델이 커지면서 병목 위치가 이동했다는 점이다. 파라미터, activation, batch가 늘어나면 다음 증상이 나타난다.

메모리 대역폭이 먼저 포화된다
GPU 코어는 대기 상태인데 데이터가 도착하지 않는다
전력의 상당 부분이 "연산"이 아니라 "이동"하는데 쓰인다

연산은 점점 싸지고, 데이터 이동이 비싸지는 방향으로 비용 구조가 뒤집혔다. 이 지점에서 PIM이 등장한다.

ㅁ GPU vs PIM — 두 구조의 핵심 차이

축	GPU	PIM
설계 목표	FLOPS 극대화	Byte 이동 최소화
연산 위치	코어에서 (DRAM에서 로드 후 계산)	메모리 내부 (in-situ)
강점 워크로드	compute-bound (조밀 행렬곱)	memory-bound (attention, embedding lookup)
약점	메모리 대역폭에 종속	일반 연산 유연성이 낮음
비유	빠른 셰프, 식재료는 매번 멀리서 옮겨 옴	식재료 옆에서 바로 손질하는 작은 부엌

표를 한 줄로 압축하면 -

GPU는 "FLOPS를 늘리는 전략",

PIM은 "Byte 이동을 깎는 전략"이다.

둘은 경쟁재가 아니라 다른 층의 병목을 푸는 조합재다.

ㅁ AI 워크로드는 왜 memory-bound 인가

[온디바이스AI] 내 폰으로 나만의 RAG 만들기(온디바이스 RAG 최소 아키텍처)를 진행하면서 흥미로운 차이를 확인했다.

맥미니 M1(8GB)과 갤럭시 S23 Ultra(12GB)에서 동일 모델을 실행했을 때,

일반적으로는 CPU 성능이 더 좋은 맥이 빠를 것으로 예상했지만 실제 응답 속도는 메모리가 더 큰 갤럭시가 더 빨랐다.

이 결과는 연산 성능보다 메모리 접근이 병목이 되는 상황을 잘 보여준다.

모델 추론 과정에서는 단순한 계산보다, 큰 파라미터와 KV 캐시를 반복적으로 읽어오는 비용이 더 크게 작용한다.

이 말을 풀어서 보면, AI 모델은 “계산을 많이 하는 것”보다 “필요한 데이터를 계속 가져오는 것”에 더 많은 시간을 쓴다.

대표적으로 두 가지 작업이 있다.

첫 번째는 Attention이다.
모델이 문장을 이해하거나 다음 단어를 예측할 때, 앞에서 나온 단어들을 다시 참고하는 과정이다.
이때 이전에 계산해 둔 값(KV 캐시)을 계속 읽어와야 하는데, 문장이 길어질수록 이 데이터 양이 빠르게 증가한다.
즉, 계산 자체보다 “과거 정보를 다시 가져오는 비용”이 더 커진다.

두 번째는 Embedding lookup이다.
단어를 숫자로 바꾸는 과정이라고 보면 된다.
모델은 “사전”처럼 아주 큰 테이블(차원)을 가지고 있고, 각 단어마다 대응되는 벡터가 저장되어 있다.
특정 단어가 들어오면 이 테이블에서 해당 위치를 찾아 값을 꺼내는데, 문제는 이 접근이 랜덤하게 일어난다는 점이다.
그래서 CPU나 GPU의 캐시가 잘 활용되지 않고, 결국 메모리에서 직접 데이터를 가져오는 비용이 커진다.

결국 두 경우 모두 공통점은 하나다.
계산이 복잡해서 느린 것이 아니라, 필요한 데이터를 계속 불러오느라 시간이 걸린다는 점이다.

그래서 AI 워크로드는 “compute-bound”가 아니라 “memory-bound”라고 말한다.

ㅁ 온디바이스/엣지에서 더 명확해진다

모바일과 엣지로 가면 제약이 세 가지로 좁혀진다.

전력, 메모리 대역폭, 발열.

데이터 센터에서는 보조적이던 제약이 여기서는 1차 제약으로 올라온다.

다음 다이어그램은 방향성을 보여 주는 도식이다.

PIM은 아직 데이터센터·온디바이스 모두에서 초기 단계이며, 표준화된 프로그래밍 모델은 자리잡는 중이다.

  워크로드 진화               하드웨어 진화
───────────────       ──────────────────────
순차 알고리즘       ──→         CPU
대규모 병렬 학습     ──→         GPU
거대 모델 추론      ──→          ?    ← bandwidth wall
온디바이스 추론     ──→     NPU + PIM (memory-centric)

NPU는 연산 패턴을 좁혀 와트당 효율을 끌어올리는 쪽이고,

PIM은 이동 비용 자체를 깎는 쪽이다.

둘은 서로를 대체하지 않는다.

같은 디바이스 안에서도 어떤 연산은 NPU로,
어떤 접근은 메모리 근처에서 처리하는 식으로 역할이 갈린다.

여기서 자연스럽게 따라오는 질문이 있다

— GPU는 언제 안 쓰는가?

데이터 이동 전력이 워크로드 본체 전력을 넘기 시작할 때,

그리고 모델이 한 번에 계산하는 방식이 아니라,

단어를 하나씩 생성(decode)하면서 이전에 저장해 둔 값을 계속 꺼내 쓰고(lookup), 그 과정이 반복되는 형태일 때다.

데이터 센터의 학습은 여전히 GPU의 무대지만, 엣지의 추론은 그렇지 않다.

ㅁ 마무리 — 내 시스템의 병목은 연산인가, 메모리인가

GPU와 PIM은 경쟁 관계가 아니다. 같은 문제의 다른 층을 푸는 도구다.

선택의 기준은 "더 좋은 칩"이 아니라 "내 워크로드의 병목이 어디인가"다.

ㅁ 함께 보면 좋은 사이트

ㅇ llm-study-web : LLM 시스템의 전체 흐름을 개념학습, 시스템 맵, 인터랙티브 실험으로 배우는 교육 플랫폼

ㅇ peterica-website: 기록하는 백엔드개발자 피터 포트폴리오 웹사이트

ㅇ

어디서든 브라우저 VS Code로 마크다운만 떨어뜨리면 LLM 이 개인 위키로 자동 정리 - silva-omnium

기록하는 백앤드개발자 — Tue, 28 Apr 2026 01:42:56 +0900

ㅁ 들어가며

ㅇ 언제 어디서든 브라우저 VS Code로 정보를 입력하면, 모든 것이 쌓이는 개인 지식 숲을 만들었습니다.

노트는 한 번만 작성합니다. 분류·요약·교차참조·인용 부착·모순 표시는 LLM 이 알아서 — 영속 위키에 계속 누적되도록.

ㅁ 문제: 매번 0 부터 발견

LLM 으로 문서를 다루는 가장 흔한 패턴 — PDF 나 노트를 챗 인터페이스에 붙여 넣고 질문, 답을 받고, 닫는다. 다음에 같은 주제가 또 떠오르면 같은 문서를 다시 붙이고, 같은 추론을 다시 하게 시킨다.

같은 자료에 10번 질문하면 LLM 은 그 자료를 10번 처음부터 발견한다. 토큰값과 시간이 든다. 더 큰 문제는 이전에 얻은 통찰이 어디에도 누적되지 않는다는 것이다. 다음에 비슷한 주제를 마주쳐도 처음 만나는 것과 같다.

ㅁ 발상: 한 번만 발견하고 위키에 쌓자

소스를 LLM 에 한 번만 읽게 한다. LLM 은:

그 소스를 영속 위키 페이지로 종합한다
기존 페이지와 연관 있으면 합치거나 모순을 표시한다
모든 사실에 원본을 가리키는 각주를 단다
카테고리·태그·별칭 같은 메타데이터를 채운다

다음에 같은 주제가 또 들어오면 LLM 은 새 raw 만 보면 된다. 위키는 이미 그 주제의 누적 종합이다.

10번째 질문 즈음이면 위키가 이미 답을 갖고 있다.

ㅁ 이름은 왜 silva-omnium 인가?

라틴어로 "사물의 숲". 두 가지 계보를 합쳤다:

Andrej Karpathy 의 LLM Wiki 패턴 — 본인 노트를 LLM 으로 정리해 자기만의 위키를 만드는 디자인 원형.
폴란드-리투아니아 연합의 silva rerum — 17~18세기 가문 대대로 이어 쓴 잡록. 일기·계약서·시·여행기·조리법 다 들어가는 두꺼운 한 권. 후손이 이어 쓰면서 가문의 기억이 책 자체에 누적된다.

여기에 Vannevar Bush 의 Memex (1945) — "기억의 확장 장치" 개념 — 도 함께 둔다. 50년 후 하이퍼링크로 절반 정도 구현된 그 아이디어를, LLM 이 나머지 절반을 채워줄 수 있다고 생각했다.

ㅁ 어떻게 동작하는가?

raw/ ──(watcher / make ingest)──▶ wiki/ ──(make build)──▶ 정적 사이트 + Obsidian 그래프

사람: raw/ 디렉토리에 노트를 떨어뜨린다. 형식 자유. 원본은 절대 수정 안 함 (불변).

LLM (Ollama 또는 Claude): 새 raw 가 생기면 읽고, 위키에 어떻게 통합할지 결정한다 — 새 페이지 만들기 / 기존 페이지에 붙이기 / 모순 표시 — 그리고 frontmatter (title, category, tags, src 인용) 까지 채운다.

위키: 시간에 따라 쌓인다. Astro Starlight 로 빌드하면 검색 가능한 사이트가 되고, 같은 디렉토리를 Obsidian vault 로 열면 그래프 뷰가 된다.

핵심은 raw 와 wiki 의 분리다. raw 는 사용자의 원본 흐름 — Obsidian 클리핑이든, 블로그 즐겨찾기든, 회의록이든. wiki 는 LLM 이 그 흐름을 종합한 영속층. 둘 다 마크다운 파일이라 어떤 도구로도 열 수 있다.

ㅁ 작은 설계 결정들

1. 인용 강제

LLM 이 만든 위키 페이지의 모든 사실은 [^src-2026-04-27-tailscale-funnel] 같은 각주를 달고, 페이지 끝에 정의가 붙는다. prompt 에 hard rule 로 박았다. 안 그러면 LLM 이 자기 사전 지식과 raw 의 사실을 섞어 출력한다 — 위키가 LLM 의 환각을 누적하는 도구가 되어버린다.

2. 모순 callout

raw 의 사실이 기존 위키 페이지와 충돌하면 "병합" 하지 않는다. 기존 페이지에 > [!conflict] ... 형태의 callout 으로 양쪽을 다 적는다. 사용자가 직접 판단할 수 있게 — 어느 쪽이 더 최신인지, 더 신뢰할 출처인지.

3. provider 플러그형

scripts/llm_providers/ 에 ollama, claude (Anthropic SDK), claude-cli (claude -p subprocess) 3개.

같은 인터페이스, 다른 백엔드. ingest 명령 하나로 전환:

make ingest                  # default = claude-cli
make ingest-ollama           # 로컬 Ollama (오프라인)
make ingest-claude           # Anthropic API key

처음엔 ollama qwen2.5:3b 로 시작했는데, 8GB RAM 환경에서 큰 raw 가 timeout 났다.

작은 모델은 instruction following 이 약해 카테고리·슬러그도 흔들렸다.

claude-cli 로 default 를 바꾸니 같은 prompt 인데 분류 정확도가 눈에 띄게 좋아졌다.

토큰 비용은 구독 안에 들어가서 추가 청구 없음.

ㅁ 자체호스팅 (선택)

상시 켜져 있는 머신 (예: Mac mini) 에 띄우면 어디서든 브라우저로 편집·열람·AI 협업이 가능하다. 구성:

code-server (VS Code in browser) — 트리·에디터·미리보기·통합 터미널·claude 명령 사전 설치
Caddy — 정적 위키 서빙 + /edit/* 를 code-server 로 reverse_proxy
Tailscale Funnel — 공개 URL (<host>.<tailnet>.ts.net) 자동 발급. 도메인·포트포워딩 불필요. 무료
fswatch + launchd — raw/ 변경 감지 → make ingest && make build 자동 트리거

호스트는 ollama 만 native, 나머지는 Docker로 구성하였다. 다른 프로젝트와 brew 의존이 섞이지 않도록 말이다.

브라우저로 같은 URL 을 열면 mini 의 code-server 가 그대로 뜬다. AI 호출과 git push 모두 mini 의 네트워크에서 발생한다.

ㅁ 한계 — 솔직하게

며칠 운영하며 드러난 것들:

Watcher race condition — raw 여러 파일이 한 번에 도착하면 (예: git pull) 디바운스가 진행 중인 ingest 를 kill 해
부분 누락 가능. lockfile 또는 더 큰 latency 필요.
Funnel + 단일 비밀번호 — code-server 가 password 만으로 보호. 추측 어려운 24자 비밀번호긴 하지만,
다음 단계로 Caddy basic_auth 추가 또는 Cloudflare Access 전환 후보.
Ollama 11434 외부 노출 — OLLAMA_HOST=0.0.0.0 로 두면 같은 LAN 의 다른 디바이스가 인증 없이 접근 가능.
categories.yaml 일관성 — 작은 모델로 ingest 시 새 카테고리 만들고 yaml 등록 안 함. claude-cli 전환으로 거의 해결됐지만 완벽하진 않음.

이런 결함들도 위키에 페이지로 들어간다 — 자기 자신을 자료 삼아 누적되는 게 silva rerum 의 정신.

ㅁ 코드 + 셋업

GitHub: https://github.com/peterica/silva-omnium

Quick start (1분):

git clone https://github.com/peterica/silva-omnium.git
cd silva-omnium
make setup

mkdir -p raw/2026
echo "# 첫 노트" > raw/2026/test.md

make ingest && make build && make dev
# → http://localhost:4321

자체호스팅까지 셋업하려면 infra/README.md 의 1회 부트스트랩 스크립트 실행.

ㅁ 마무리

기억을 쌓는 도구가 결국 자기 자신을 자료로 쌓는다는 게 흥미롭다. 다음 글에선 ingest 파이프라인의 내부 구조 (provider 추상화, 인용 강제 prompt, frontmatter 스키마) 를 더 자세히 다루겠습니다.

[온디바이스AI] 청크는 쌓는 게 아니라 덜어내는 일 — 약한 청크 25개를 덜어내 MRR이 0.15 올랐다

기록하는 백앤드개발자 — Thu, 23 Apr 2026 23:00:10 +0900

ㅁ TL;DR

약한 청크 = moc/·entities/·concepts/의 "관련 포스트", "주요 태그", 연도 그룹, 순수 링크 목록
본문 없고 키워드만 풍부 → 임베딩 유사도가 가짜로 높게 나온다
해법: 경로·헤딩 한 줄 필터 (새 모델·인덱스·리랭커 0개)
실측 기준:
- 청크 수: 118 → 93 (-25, -21%)
- MRR(Mean Reciprocal Rank): 0.794 → 0.947 (+0.15)
- R@3(Recall@3): 0.933 → 1.000
결론: 모델을 바꾸기 전에 청크를 봐야 한다

ㅁ 왜 이 문제를 발견했나

폰에서 "쿠버네티스에서 graceful shutdown이란?"을 물었다.
top-3에 정답 블로그 183번 글과 함께, MOC 파일의 "관련 포스트" 링크 목록이 두 개 섞여 들어왔다.

그 목록 청크의 본문을 열어봤다.

실제 내용 거의 없음
"kubernetes, graceful shutdown, pod, deployment..." 키워드만 나열

링크 목록이 본문보다 먼저 검색된다는 건 설계 실패에 가깝다.
모델을 바꿀까 생각하다가 멈췄다 — 이건 모델 문제가 아니라 청크 문제였다.

ㅁ 약한 청크의 정체

MOC(Map of Content)·entity·concepts 경로의 파일은 원래 지식의 허브 역할이다.

하지만 그 안의 일부 섹션은 검색 관점에서 본문이라고 부를 수 없다.

"관련 포스트" 링크 목록
"주요 태그" 나열
연도 그룹 헤딩 ("2024년", "2023년 작성 글")
반복되는 테이블

정답 본문은 없고 관련 키워드만 모인 청크라서, 임베딩 벡터가 주변 문서들의 키워드 평균처럼 형성된다.
본문이 없으니 구체성은 없는데, 키워드 밀도가 높아 유사도가 가짜로 높게 나온다.

결과:

사용자 쿼리가 어느 주제든 이 청크들이 top-k에 쉽게 얹힌다
정답 본문이 top-3 밖으로 밀려나는 경우가 생긴다
LLM은 근거로 받은 "키워드 목록"으로 답을 짜야 해서 대답이 빈약해진다

ㅁ 해법은 한 번의 경로·헤딩 필터

chunk.py에 경로+헤딩 매칭 필터 한 규칙을 넣었다.

경로: moc/, entities/, concepts/ 중 하나에 속하면
헤딩 또는 섹션 내용이 "관련 포스트", "주요 태그", 연도 그룹, 순수 링크 목록에 해당하면
청크 생성에서 제외

그 외에는 건드리지 않는다.

모델 그대로
차원 그대로
검색 알고리즘 그대로
인덱스 그대로

배포 구성이나 검색 스택을 바꾸지 않는, 데이터 단계의 단일 개입이다.

ㅁ 실측 — 22 쿼리 평가 하네스

변경 전후를 같은 쿼리 세트로 비교해야 의미가 있다.
한국어 22 쿼리(DevOps·RAG·K8s·모니터링)에 정답 청크를 라벨링해 둔 평가 하네스(server/scripts/embed_eval.py)로 돌렸다.

지표필터 전필터 후변화

청크 수	118	93	-25 (-21%)
MRR	0.794	0.947	+0.153
R@3	0.933	1.000	+0.067

모델·차원·검색 알고리즘은 전혀 건드리지 않은 결과다.
이번 실험에서는 모델을 바꾸지 않고도, 데이터 정리만으로 MRR이 0.153 올랐다.

청크 필터 case 문서

ㅁ 운영 — ETag로 자동 재동기화

필터 규칙이 바뀌면 폰의 로컬 DB도 최신으로 맞춰야 한다.

ETag에 chunker_version을 포함시켜, 필터 규칙이 바뀌면 폰 DB가 자동 재동기화되게 했다.
필터 변경 없는 날은 304 — 전송량 0.

청크 필터는 단순 규칙 + 단순 동기화로 운영 복잡도도 거의 없다.

ㅁ 왜 이 결정이 "최소 구현"에 맞는가

추가 인프라 0 — 새 모델·인덱스·리랭커 없음. 데이터 정리 한 번.
평가 하네스가 증거 — 22 쿼리 전후 비교가 의사결정을 대신한다.
단순한 규칙 — 경로·헤딩 매칭만으로 동작. 새 위키 구조에 이식하기 쉽다.
확장 여지 유지 — 청크가 수만 개가 되면 정답 라벨 쿼리 평가를 다시 돌려 필터를 진화시키면 된다.
"덜"이 정당성 — 최소 구현이 "덜 넣는" 쪽으로 편향되는 근거가 됐다.

ㅁ 내가 바꾼 생각

처음에는 이렇게 접근했다.

문서를 많이 쌓자
임베딩만 좋으면 품질은 따라온다

지금은 이렇게 바뀌었다.

문서는 선별해서 쌓자
품질은 모델보다 데이터가 결정한다

결론:

RAG 품질을 올리는 가장 빠른 길은 모델 교체가 아니라, 잘못 넣은 청크를 덜어내는 것이다.

ㅁ 참고

이 프로젝트 문서

청크 필터 case 문서 — 초기 가정·실험 설계·재검토 트리거
임베딩 벤치마크 case — 모델 선택 근거
최소 구현 가이드 — 8단계 파이프라인
문서 허브 — 독자 유형별 읽기 경로

ㅁ 한 줄 정리

청크는 쌓는 작업이 아니라 덜어내는 작업이다. 잘 섞지 않는 것도 엔지니어링이다.

[AI] RTK — AI 에이전트 터미널 출력을 60~90% 압축하는 CLI 프록시

기록하는 백앤드개발자 — Thu, 23 Apr 2026 20:44:55 +0900

ㅁ TL;DR

RTK는 github.com/rtk-ai/rtk 의 실존 OSS다. 아키텍처 개념이 아니라 단일 Rust 바이너리로 배포되는 CLI 프록시.
AI 에이전트(Claude Code, Cursor, Gemini CLI 등)가 실행한 터미널 명령 출력을 가로채, 60~90% 압축한 뒤 LLM에 전달한다.
동작 방식은 shell hook 이 git status 를 rtk git status 로 자동 치환. 에이전트 코드 수정 없이 붙는다.
오버헤드는 <10ms, 공식 지원 서브커맨드 30+ (git, test, jest, vitest, tsc, next, docker, kubectl 등). Apache-2.0 / MIT.

ㅁ 왜 이게 필요한가

AI 코딩 에이전트는 매 작업마다 아래를 실행한다.

npm install
pytest
git status
docker build .

출력은 대부분 진행바, 다운로드 로그, 성공 라인 이다. LLM은 이 노이즈를 전부 context window 에 싣고 추론한다.

결과:

컨텍스트 창이 빠르게 소진된다
토큰 과금이 불필요하게 증가한다
attention 이 노이즈에 분산돼 판단이 무뎌진다

ㅁ RTK 가 실제로 하는 일

공식 문서 기준 12가지 최적화 전략을 사용한다. 핵심만 추리면:

전략	동작
Stats Extraction	git status 의 수십 줄 → 3 modified, 1 added, 1 untracked 한 줄로 요약
Failure Focus	테스트 러너의 통과 로그는 버리고, 실패 블록만 남김
Grouping	TypeScript 에러를 파일별로 묶어 TS2322 (5x) 식으로 집계
Deduplication	동일한 연속 로그는 카운터로 접음
Progress Filtering	ANSI escape, 다운로드 진행바 제거
Three-Tier JSON Parsing	full → partial → passthrough 순서로 JSON 보존
Tree Compression	디렉토리 구조는 20 dir / 10 file 단위로 요약

나머지 5종: NDJSON Streaming, Block-Based State Machine, Language-Aware Code Stripping, JSON Object Extraction, Economic Metrics Tracking.

즉, 단순 텍스트 trim 이 아니라 의미 단위 재구성이다.

ㅁ 설치와 동작 방식

macOS 기준 Homebrew 가 가장 깔끔하다 (공식 formula, Apache-2.0).

# 설치
brew install rtk
# 또는 공식 install.sh (linux/macOS 공용)
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

# 버전 확인
rtk --version   # → rtk 0.37.2 (2026-04 기준)

# 수동 호출
rtk git status
rtk ls -la
rtk tree -L 2

여기서 끝이면 에이전트가 매번 rtk 를 prefix 해야 한다.

핵심은 shell auto-rewrite hook 이다.

rtk init -g   # 전역 hook 설치

hook 을 활성화하면, 에이전트가 git status 를 보내도 shell 이 내부적으로 rtk git status 로 치환한다.

에이전트 코드 수정 0줄, 설정 변경 0줄로 적용된다.

지원 확인된 에이전트:

Claude Code, Cursor, GitHub Copilot (VS Code / CLI)
Gemini CLI, Codex, Windsurf, Cline / Roo Code
OpenCode, OpenClaw, Kilo Code, Google Antigravity

ㅁ Before / After 예시

아래는 이 블로그를 쓰는 리포지토리 (peterica-blog) 에서 rtk 0.37.2 로 직접 측정한 결과다.

git status 비교

Before — 원본 git status (705 bytes)

On branch main
No commits yet
Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
    new file:   CLAUDE_CODE_PROJECT_SETUP_PROMPT.md
    new file:   README.md
    new file:   writing/0415/idea.md
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
    modified:   CLAUDE_CODE_PROJECT_SETUP_PROMPT.md
    ...
Untracked files:
  (use "git add <file>..." to include in what will be committed)
    .gitignore
    PRD.md
    ...

After — rtk git status (475 bytes, 44.1% 절감)

* No commits yet on main
+ Staged: 3 files
   CLAUDE_CODE_PROJECT_SETUP_PROMPT.md
   README.md
   writing/0415/idea.md
~ Modified: 3 files
   CLAUDE_CODE_PROJECT_SETUP_PROMPT.md
   ...
? Untracked: 10 files
   .gitignore
   PRD.md
   ...

사라진 것: (use "git rm --cached ..." to unstage) 류의 도움말 라인 전부. 사람에겐 유용하지만 LLM 에겐 노이즈.

rtk find — 99.8% 절감의 정체

원본 find . -type f 는 2,309 라인을 모두 출력한다 (374KB). rtk find 는 이걸 이렇게 바꾼다:

2309F 26D:

./ PRD.md README.md requirements.txt
data/ posts.jsonl posts_wiki.jsonl reclassify_llm.json urls.txt wiki_id_to_stem.json
data/shards/ 0001.jsonl 0001.raw.jsonl 0001.txt 0002.jsonl ... 0014.txt
+2259 more

ext: .md(2203) .jsonl(42) .py(26) .txt(22) .sh(5)

핵심 변환:

전체 카운트 (2309F 26D) 를 맨 위에 배치
디렉토리별로 파일을 한 줄에 묶음
일정 수 이후는 +2259 more 로 생략
맨 아래 확장자별 통계를 집계 — "이 프로젝트는 md 2203 개가 주류" 를 LLM 이 즉시 파악

단순 truncation 이 아니라 "이 디렉토리가 어떤 곳인지"를 압축해서 보여주는 설계다.

ㅁ 왜 Rust 인가

엔지니어링 관점에서 Rust 선택은 합리적이다.

단일 바이너리: 런타임·인터프리터 없음. 어떤 환경에도 copy & run.
stdin/stdout 스트림 처리: 블로킹 없는 파이프 중계.
<10ms 오버헤드: 매 명령마다 프록시를 통과해도 체감되지 않는다.

단, Rust 는 수단이다. Go 나 Zig 로도 동일 요구사항을 만족할 수 있다. 본질은 터미널 출력 스트림을 낮은 오버헤드로 중간 가공하는 파이프 레이어 라는 구조다.

ㅁ 한계와 주의점

RTK 를 무작정 켜기 전에 알아야 할 것.

exit code 는 보존되지만, 일부 CI 파서는 깨질 수 있다. 에이전트 용 프록시지 CI 용이 아니다.
100+ 명령 외는 passthrough 되거나 압축률이 낮다. 지원 목록 확인 필요.
로그 기반 디버깅이 필요한 순간엔 명령 앞의 `rtk` 를 떼고 원본 출력을 그대로 받아야 한다.
shell hook 방식은 사용자의 shell rc 파일을 수정한다. 팀 환경 배포 시 주의.

ㅁ 유사 제품 비교

RTK 만 있는 건 아니다. 같은 문제를 다른 각도로 푸는 도구들이 있다.

도구	위치	특징
RTK	터미널 출력 단	shell hook, Rust 바이너리, 60~90%
Tamp	에이전트 ↔ API 중간	tool result 분류 후 압축, 60~70%
LeanCTX	파일 read 단	intent-aware, 재읽기 캐시 시 99%

RTK 는 쉘 레이어, Tamp 는 API 레이어, LeanCTX 는 파일 read 레이어 로 삽입 지점이 다르다.

조합해서 써도 된다.

ㅁ 마무리

RTK 는 "AI 에이전트용 로그 전처리 프록시"다. 추상 개념이 아니라 실제로 설치·실행 가능한 OSS.
적용 지점은 shell hook, 효과는 60~90% 토큰 절감, 오버헤드는 <10ms.
단순 길이 축소가 아니라 12가지 의미 단위 재구성 전략을 적용한다.
장기적으로는 RAG 전처리, 온디바이스 LLM 입력 최적화에도 같은 구조가 쓰인다.

에이전트가 느리거나 컨텍스트가 빨리 차는 팀이라면, 붙여보고 rtk gain 으로 실측하는 것이 빠르다.

ㅁ 참고

rtk-ai/rtk — https://github.com/rtk-ai/rtk
DeepWiki: Token Optimization Strategies — https://deepwiki.com/rtk-ai/rtk/3.2-token-optimization-strategies
Tamp (비교군) — https://github.com/sliday/tamp

ㅁ 함께 보면 좋은 사이트

ㅇ 모델

google/embeddinggemma-300m · Hugging Face

We’re on a journey to advance and democratize artificial intelligence through open source and open science.

huggingface.co

ㅇ 도구

Google AI Edge Gallery: https://github.com/google-ai-edge/gallery
minja (llama.cpp 내장 Jinja2): https://github.com/google/minja
LiteRT: https://ai.google.dev/edge/litert
sqlite-vec: https://github.com/asg017/sqlite-vec

ㅇ 더 공부하기 — LLM System Lab

LLM 시스템의 전체 흐름을 개념학습, 시스템 맵, 인터랙티브 실험으로 배우는 교육 플랫폼
RAG Pipeline: https://llm-study-web.vercel.app/topic/rag-pipeline
Embedding: https://llm-study-web.vercel.app/topic/embedding
Production RAG 사례: https://llm-study-web.vercel.app/case-studies/production-rag-system

ㅇ 이전 글

peterica-website: 기록하는 백엔드개발자 피터 포트폴리오 웹사이트
Mac Mini RAG 구축기: https://peterica.tistory.com/1064
sqlite-vec 선택 이유: https://peterica.tistory.com/1065

[온디바이스AI] LiteRT-LM — 온디바이스 LLM을 실제로 “돌리게” 만드는 런타임

기록하는 백앤드개발자 — Thu, 23 Apr 2026 00:00:58 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

ㅇ LiteRT-LM — 온디바이스 LLM을 실제로 “돌리게” 만드는 런타임

ㅁ TL;DR

LiteRT-LM = 온디바이스 LLM 추론 런타임
핵심 차별점: .litertlm (모델 + 토크나이저 + 템플릿 번들)
서버 런타임(vLLM/Ollama)은 모바일에 그대로 못 옮긴다
실제 기준:
- Galaxy S23 Ultra
- Gemma 4 E2B
- 약 40초/응답
- 모델 크기 약 2.4GB
결론: 모델만큼 런타임 선택이 초기에 결정된다

ㅁ 왜 LiteRT-LM까지 오게 됐는가

Gemma 4 E2B를 폰에서 돌리는 데 48시간을 썼다.
시간의 대부분은 모델이 아니라 런타임에서 막혔다.

llama.cpp → Android NDK / NPU 활용 제한
서버 구조(vLLM/Ollama) → 모바일 이식 불가
tokenizer / ABI / 메모리 문제 반복

결국 문제는 하나였다.

“모델이 아니라 실행 계층이 없다.”

ㅁ LiteRT-LM의 핵심 역할 (고유성)

:contentReference[oaicite:0]{index=0}은 단순한 추론 엔진이 아니다.

핵심은 이 포맷이다.

.litertlm

하나의 파일에 포함:

모델 weight
토크나이저
chat template
실행 설정

결과:

별도 tokenizer 배포 불필요
프롬프트 포맷 일관성 유지
모바일 배포 단순화

이게 다른 런타임과의 결정적 차이다.

ㅁ 서버 런타임이 그대로 안 되는 이유

서버 기준 사고:

Docker
GPU
Python runtime

모바일 현실:

arm64 + NDK
제한된 메모리
NPU delegate (Hexagon 등)
앱 내 실행

문제:

cross compile 필요
tokenizer 네이티브 의존성
GPU 대신 NPU 경로 필요

그래서 구조가 바뀐다.

“모델 서버” → “앱 내 추론 시스템”

ㅁ 실제 실행 흐름 (LiteRT-LM 기준)

일반적인 LLM 흐름과 다르게, LiteRT-LM은 이 단계가 핵심이다.

HuggingFace 모델 준비
.litertlm 포맷으로 변환 (핵심 단계)
앱 assets 또는 외부 저장소 배치
LiteRT-LM 런타임 로딩
delegate 선택 (CPU / GPU / NPU)
프롬프트 입력 → 토큰 생성

차이:

tokenizer 별도 로딩 없음
prompt template 내장
디바이스 최적화 포함

ㅁ 실제 측정 기준 (내 환경)

Device: Galaxy S23 Ultra
Model: Gemma 4 E2B
Size: 약 2.4GB
Latency: 약 40초 / 응답
Acceleration: Hexagon NPU

이 수치가 의미하는 건 하나다.

“돌아간다”와 “쓸 수 있다”는 다르다.

ㅁ 내가 바꾼 생각

처음에는 이렇게 접근했다.

어떤 모델이 좋을까

지금은 이렇게 바뀌었다.

어떤 런타임으로 돌릴 수 있을까

결론:

모델을 고르는 문제만큼,
런타임을 고르는 문제도 초기에 결정된다.

ㅁ 참고

LiteRT-LM GitHub
Gemma 4 E2B 실행 케이스 (Galaxy S23)
온디바이스 RAG 전체 구조

ㅁ 한 줄 정리

LiteRT-LM은 “모델을 실행 가능한 형태로 바꾸는 계층”이다.

ㅁ 함께 보면 좋은 사이트

ㅇ llm-study-web : LLM 시스템의 전체 흐름을 개념학습, 시스템 맵, 인터랙티브 실험으로 배우는 교육 플랫폼

ㅇ LiteRT-LM — 온디바이스 LLM을 실제로 “돌리게” 만드는 런타임

[온디바이스AI] 처음 만드는 온디바이스 RAG — 핵심원칙 10가지

기록하는 백앤드개발자 — Wed, 22 Apr 2026 21:00:49 +0900

TL;DR

#	원칙	핵심
1	목표 축소	완벽한 RAG ❌ → 끝까지 도는 최소 사이클 1개
2	모델 통일	서버/모바일 분리 ❌ → 동일 임베딩 모델
3	데이터가 성능	모델보다 청크 품질이 MRR을 움직인다
4	청크는 제거	추가 ❌ → 약한 청크 제거로 R@3 올리기
5	검색은 단순하게	N < 1k → brute-force가 정답
6	배포 단위	모델 ❌ → 모델 + 토크나이저 + 설정 세트
7	양자화는 필수	선택 ❌ → 배포 조건
8	프롬프트 욕심 금지	작은 모델 → 짧고 단순하게
9	속도 기대치 현실화	40초 느림 = 독립성과 바꾼 비용
10	제약을 받아들여라	장애 ❌ → 설계 기준

한 줄 요약: 작게 만들고, 단순하게 유지하고, 끝까지 동작시킨다.

ㅁ 들어가며

서버·네트워크 없이, Galaxy S23 Ultra에서 40초 뒤 두 문장으로 답하는 RAG를 만들었다.
기술 다섯 가지의 실측은 이전 글 1071에 정리했다.

만들면서 설계는 여러 번 뒤집혔다.
"큰 모델", "많은 청크", "복잡한 프롬프트" — 자연스러워 보였던 셋 다 틀렸다.

이 글은 기술이 아니라, 처음 만들 때 반드시 잡아야 할 원칙 10가지다.
각 원칙마다 실측 수치와 case 문서 링크를 같이 붙였다.

전체 문서·소스코드: github.com/peterica/peterica-edge-rag
문서 허브: ondevice-rag/README.md

1. 목표 축소 — 최소 사이클부터 완성

완벽한 RAG ❌ → "질문 한 줄 → 두 문장 답" 한 사이클
재랭크·멀티홉·복합 질의는 나중에
최소 사이클이 돌아야 어디가 병목인지 보인다

→ "안 만드는 것"이 설계의 절반이다.

최소 구현 가이드

2. 모델 통일 — 하나의 벡터 공간

서버/폰 다른 모델 ❌ → 벡터 공간이 다르면 DB도, 임베딩도 두 벌
22쿼리 3모델 벤치마크 → e5-small-ko-v2(384d) 선정
MRR 0.947 · R@3 1.000로 bge-m3(1024d)·EmbeddingGemma(768d) 모두 앞섬
통일 후: DB 2개 → 1개, 임베딩 2회 → 1회

→ 모델이 다르면 시스템도 두 개다.

embedding-benchmark-ko

3. 데이터가 성능 — 모델보다 청크가 MRR을 움직인다

모델 교체로 얻은 이득은 작았다
청크 필터 한 번이 MRR 0.794 → 0.947 (+0.15)
같은 모델에서 데이터만 바꿨을 때의 변화

→ 검색 품질의 뿌리는 모델, 흙은 청크다.

moc-entity-filter

4. 청크는 제거 — 많을수록 나빠진다

MOC·entity의 링크 목록, 연도 그룹 = 본문 없고 키워드만 풍부한 약한 청크
25개(21%) 제거 → 118 → 93
그 결과 R@3 0.933 → 1.000

→ "잘 섞지 않는 것"도 엔지니어링이다.

moc-entity-filter

5. 검색은 단순하게 — N < 1k면 brute-force

sqlite-vec arm64 Android 바이너리 ❌
sqlite에 float32 BLOB 저장 + Kotlin 전수 스캔
93청크 × 384차원 = 143KB, cosine < 1ms
HNSW의 이점은 수만 청크 이상에서 본격화

→ "작은 규모 + 비지원 플랫폼"이면 가장 얕은 알고리즘이 정답.

brute-force-vs-sqlite-vec

6. 배포 단위 — 모델이 아니라 세트

모델만 넣으면 됨 ❌ → 토크나이저가 바이트 단위로 다르면 벡터 공간 붕괴
HuggingFace Fast(Python/Rust), DJL(arm64 native 부재) 모두 실패
해법: onnxruntime-extensions로 SentencepieceTokenizer를 ONNX 그래프 내장
검증: HF Fast ↔ ONNX byte-exact parity 24/24

→ 배포 단위는 "모델 파일"이 아니라 "모델 + 토크나이저 + 설정" 세트.

tokenizer-onnx-embedding

7. 양자화 — 선택이 아니라 배포 조건

원본 fp32: 448MB → APK가 무겁고 다운로드 불친절
optimum-cli export onnx → onnxruntime.quantize_dynamic (INT8)
113MB (원본의 25%) · cosine 0.97~0.98 · Top-1 5/5 일치
거리 0.003~0.006 증가했지만 상대 순위는 동일

→ 엣지에서 양자화는 "해볼까"가 아니라 "안 하면 배포 불가".

onnx-int8-quantization · 블로그 1069

8. 프롬프트 욕심 금지 — 작은 모델은 짧고 단순하게

서버(4B)에서 규칙 준수율 0.57 → 0.89로 올린 v4 JSON 스키마 프롬프트를 폰(2B)에 이식
JSON 파싱은 완벽. 그런데 답변이 "질문 제목 한 줄"로 축소
원인: 2B는 "양식 + 규칙 + 내용"을 동시에 챙길 사고 여유 부족
대응: 자연어 프롬프트로 롤백, 파서·로그 인프라는 보존

→ 큰 모델은 제약이 품질 방어벽, 작은 모델은 제약이 여유 세금.

json-schema-prompt-failure-on-edge

9. 속도 기대치 현실화 — 느리지만 독립적

Gemma 4 E2B + LiteRT-LM + Hexagon NPU → 40초/응답
서버 LLM 기준으론 "쓸 수 있나" 싶은 수준
그러나 40초 동안 네트워크 없이 내 지식에 닿는다
사용 결: 오프라인·비밀·저지연 통신 불가 상황에서 빛남

→ 엣지 LLM의 속도는 "느림"이 아니라 "독립성과 바꾼 비용".

gemma4-e2b-on-galaxy-s23

10. 제약을 받아들여라 — 설계 기준이 된다

제약	결과로 강제된 설계
sqlite-vec arm64 ❌	brute-force cosine
DJL native ❌	ONNX 토크나이저 내장
2B 모델 여유 부족	자연어 프롬프트

제약이 없었다면 HNSW·JSON 프롬프트를 굳이 얹었을 것
유지 부담도, 배포 크기도 지금보다 컸을 것

→ 제약은 자원의 한계가 아니라 가장 단순한 설계를 강제하는 힘이다.

최소 구현 가이드

ㅁ 한 줄 정리

온디바이스 RAG는 "작게 만들고, 단순하게 유지하고, 끝까지 동작시키는 것"이다.

10개 중 절반은 "안 하기"로 시작한다.
기능 줄이기, 듀얼 DB 안 만들기, 청크 덜 쌓기, 인덱스 안 얹기, JSON 안 강제하기.
"안 하기"가 설계의 절반을 차지한다.

ㅁ 함께 보면 좋은 글

이 레포의 다른 문서

문서 허브 README — 8단계 네비게이션 + 독자 유형별 읽기 경로
최소 구현 가이드 — 결론·파이프라인·8단계
아키텍처 — 컴포넌트 경계·데이터 흐름
체크리스트 — 구현 검증 항목

이전 블로그 시리즈

더 공부하기 — LLM System Lab

[온디바이스AI] 내 폰으로 나만의 RAG 만들기(온디바이스 RAG 최소 아키텍처)

기록하는 백앤드개발자 — Tue, 21 Apr 2026 01:39:18 +0900

ㅁ 들어가며

이전 글에서 맥미니 위에 RAG 서버를 올려 내 블로그 1,000편을 검색하게 만들었다.
그 글 마지막에 "문서 1,000개는 보유만으로는 창고. 검색이 붙는 순간 두 번째 뇌가 된다"고 썼다.

그런데 그 뇌는 맥미니가 켜져 있을 때만 일했다.
와이파이가 없으면, 서버가 내려가면, 내 지식에 닿지 않았다.
그래서 질문을 바꿨다 — 내 기억을 내 주머니로 옮길 수 있을까.

Galaxy S23 Ultra를 비행기 모드로 둔 채 물어봤다.

"쿠버네티스에서 graceful shutdown이란?"

40초 뒤 폰이 내 블로그 183번 글의 청크를 인용하며 두 문장으로 답했다.
서버 없이, 네트워크 없이, 내 손 안에서.

이 글은 그 한 번의 응답까지 가기 위해 검토해야 했던 다섯 가지 기술의 요약이다.
상세한 벤치마크·시행착오·case 문서는 GitHub 저장소에 따로 정리했다.

전체 문서·소스코드: github.com/peterica/peterica-edge-rag

ㅁ 결론

내 기계가 내 지식을 안다 — 이 한 줄이 이번 테스트의 결론이다.

테스트를 하면서 알게 된 네 가지이다.

ㅇ 측정이 설계를 이긴다
— "큰 임베딩이 좋다", "청크 많이 넣자", "서버 프롬프트 그대로 이식하자" 셋 다 22개 평가 쿼리 앞에서 뒤집혔다.

ㅇ 제약은 단순함을 강제한다

— sqlite-vec arm64 부재, DJL native 부재, 2B 모델 여유 부족이 합쳐지자 가장 얕은 알고리즘이 정답이 됐다.

ㅇ 인프라는 보존, 결과만 롤백

— 실패한 프롬프트 실험에서 파서·로그 훅은 살리고 프롬프트 문자열만 되돌려 다음 시도의 진입 비용을 낮췄다.

ㅇ 배포 단위는 "기술"이 아니라 "세트"

— 서버에선 pip install 한 줄이 감춰주던 의존성이, 엣지에선 파일 단위로 APK에 직접 넣어야 할 문제가 된다.

ㅁ 전체 파이프라인

[마크다운 위키]
      │  청크 분리 + 약한 청크 필터
      ▼
[청크 N개]
      │  서버에서 임베딩 (sentence-transformers)
      ▼
[float32 벡터 + 메타데이터]
      │  sqlite 단일 파일
      ▼
[mobile.db]
      │  /sync ETag로 폰에 다운로드
      ▼
[폰 내부 저장소]
      │  쿼리 임베딩 (ONNX INT8) + brute-force cosine
      ▼
[top-K 청크]
      │  LiteRT-LM 프롬프트 조립
      ▼
[Gemma 4 E2B 추론]
      │  문장별 [#n] 인용 렌더링
      ▼
[답변 + 근거 링크]

ㅁ 다섯 가지 필수 기술

온디바이스 RAG는 검색과 생성을 모두 폰 안에 넣는 것이다.
다섯 가지를 순서대로 검토해야 했다.

1. 임베딩 모델·차원 선택

서버 bge-m3(1024d) + 폰 EmbeddingGemma(768d) 듀얼 DB로 시작.
22 쿼리 3모델 벤치마크에서 가장 작은 multilingual-e5-small-ko-v2(384d)가

MRR 0.947 · R@3 1.000으로 두 큰 모델을 앞섰다.
결과적으로 서버·폰 같은 모델로 통일, DB 크기 60% 감소.

2. 청크 품질

약한 청크(MOC·entity의 링크 목록, 연도 그룹 헤딩)가 top-k를 오염시켰다.
moc/·entities/·concepts/ 경로의 약한 헤딩을 제외.
청크 118 → 93 (21% 감소), MRR 0.794 → 0.947, R@3 0.933 → 1.000.

3. 폰에서의 벡터 검색

sqlite-vec는 arm64 Android 바이너리가 배포되지 않았다.
대안으로 sqlite에 float32 BLOB만 저장 + brute-force cosine 전수 스캔.
93청크 × 384차원: < 1ms.
수만 청크가 넘어야 HNSW 인덱스의 이점이 드러나는 구간.

4. 임베딩 모델 경량화와 토크나이저 동봉

폰은 모델 파일을 APK에 직접 넣는다. 원본 448MB는 무거웠다.
optimum-cli export onnx → onnxruntime.quantize_dynamic → 113MB (INT8, 원본의 25%).
한국어 5쿼리 cosine 0.97~0.98, Top-1 5/5 일치.

모델만으로는 안 돌아간다. 서버와 바이트 단위로 동일한 토크나이저가 필요.
HuggingFace Fast는 Python/Rust라 안드로이드 불가, DJL은 arm64 native 부재.
onnxruntime-extensions로 SentencepieceTokenizer를 ONNX 그래프로 빌드해 tokenizer.onnx(~5MB) 동봉.
HuggingFace Fast ↔ ONNX byte-exact parity 24/24 통과.

양자화 이론과 파이프라인 상세: 448MB가 113MB 되는 길 — ONNX INT8 양자화 실전

5. 경량 LLM 실행과 프롬프트 여유

Gemma 4 E2B(2B) + LiteRT-LM + Hexagon NPU — S23 Ultra에서 40초/응답.

복병은 프롬프트였다.
서버(4B)에서 규칙 준수율 0.57 → 0.89로 올린 v4 JSON 스키마 프롬프트를 폰에 그대로 이식하자, 답변이 "Kubernetes 환경에서 graceful shutdown이란 [#1]." — 질문 제목 한 줄로 축소됐다.
2B는 "양식 + 규칙 + 내용"을 동시에 챙길 사고 여유가 없었다.

대응: 시스템 프롬프트만 자연어로 롤백. 파서·로그 인프라는 유지.
큰 모델은 제약이 품질 방어벽, 작은 모델은 제약이 여유 세금.

ㅁ 8단계 네비게이션

내가 경험한 8단계와 그 근거를 정리하였다.

	단계	선택	근거 (case)
1	임베딩 모델 선택	e5-small-ko-v2 (384d)	embedding-benchmark-ko
2	청크 분리 + 약한 청크 필터	MOC/entity 제외, 118 → 93	moc-entity-filter
3	서버 임베딩 파이프라인	FastAPI + sentence-transformers	(main만 참조)
4	임베딩 모델 경량화	ONNX INT8 (448MB → 113MB)	onnx-int8-quantization
5	토크나이저 동봉	onnxruntime-extensions (ONNX 그래프)	tokenizer-onnx-embedding
6	폰 벡터 검색	sqlite + brute-force cosine (<1ms)	brute-force-vs-sqlite-vec
7	온디바이스 LLM	Gemma 4 E2B on LiteRT-LM (~40s)	gemma4-e2b-on-galaxy-s23
8	프롬프트 전략	자연어 + 인용 지시 (JSON 강제 반려)	json-schema-prompt-failure-on-edge

→ 선택의 전체 요약 표는 minimal-guide에 있다.

ㅁ 결국 선택한 스택

레이어	기술
LLM (폰)	Gemma 4 E2B on LiteRT-LM
임베딩	multilingual-e5-small-ko-v2 INT8 (113MB, 384d)
벡터 검색 (폰)	sqlite + float32 BLOB + brute-force cosine
토크나이저 (폰)	onnxruntime-extensions (ONNX 그래프 내장)
서버 (dev)	FastAPI + sqlite-vec + Ollama
동기화	/sync ETag (wiki_commit + chunker_version)

ㅁ 전체 문서와 소스코드

이 글은 요약이다.
각 기술의 문제 정의·초기 가정·실험·결과·선택 근거를 case 단위로 분리해 GitHub 저장소에 정리했다.

저장소: github.com/peterica/peterica-edge-rag
문서 허브: ondevice-rag/README.md — 8단계 네비게이션 + 독자 유형별 읽기 경로
최소 구현 가이드: ondevice-rag/00-main/ondevice-rag-minimal-guide.md — 결론·파이프라인·8단계
아키텍처: ondevice-rag/00-main/ondevice-rag-architecture.md
case 문서: 임베딩 벤치마크 / MOC·entity 필터 / brute-force vs sqlite-vec / ONNX INT8 양자화 / 토크나이저 ONNX 내장 / Gemma 4 E2B 실기 / JSON 프롬프트

ㅁ 마무리

폰을 꺼내 물어봤고, 내 블로그가 자기 기억을 꺼내 답했다.
서버 없이, 네트워크 없이.

다섯 가지 기술 검토를 돌고 나니 온디바이스 RAG가 하나의 트릭이 아니라 다섯 겹의 타협으로 성립한다는 걸 알게 됐다.
측정이 설계를 이기고, 제약이 단순함을 강제하고, 실패한 실험도 인프라는 남고, 배포 단위는 기술이 아니라 세트다.

완성보다 경험이, 제품보다 이해가 더 많았다.

ㅁ 함께 보면 좋은 사이트

ㅇ 시스템 구성

LiteRT-LM (Gemma on-device): https://ai.google.dev/edge/litert/models/gemma
sqlite-vec: https://github.com/asg017/sqlite-vec
onnxruntime-extensions: https://github.com/microsoft/onnxruntime-extensions
optimum (HuggingFace ONNX export·양자화): https://github.com/huggingface/optimum

ㅇ 더 공부하기 — LLM System Lab

RAG Pipeline: https://llm-study-web.vercel.app/topic/rag-pipeline
Embedding: https://llm-study-web.vercel.app/topic/embedding
On-Device AI: https://llm-study-web.vercel.app/topic/on-device-ai
Model Capacity: https://llm-study-web.vercel.app/topic/model-capacity
Quantization: https://llm-study-web.vercel.app/topic/quantization

ㅇ 이전 글

Mac Mini RAG 구축기: https://peterica.tistory.com/1064
sqlite-vec 선택 이유: https://peterica.tistory.com/1065
맥미니 RAG를 넘어서 — 모바일 온디바이스 AI를 시작하다: https://peterica.tistory.com/1066
448MB가 113MB 되는 길 — ONNX INT8 양자화 실전: https://peterica.tistory.com/1069

[AI] sqlite-vec vs ANN: 왜 지금은 KNN이 더 적합한가

기록하는 백앤드개발자 — Thu, 16 Apr 2026 03:11:56 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

지난 글, [AI] 1,000개 블로그 글 Wiki에 로컬 RAG 챗봇 붙이기 — peterica-blog-chat에서 sqlite-vec에 대해서 언급하였다.

sqlite-vec는 파일 하나(wiki.db)가 벡터 스토어의 전부이다.

ㅁ 왜 sqlite-vec를 선택하였는가?

ㅇ DB와 인덱스가 파일 하나(`data/wiki.db`)로 구성된다.
→ 별도의 서버 없이도 하나의 파일만으로 데이터와 검색 구조를 함께 관리할 수 있다.

ㅇ 백업과 복구가 단순하다.
→ 백업은 파일을 복사(`cp`)하면 끝이고, 문제가 생기면 파일을 교체하는 방식으로 롤백이 가능하다. 운영 복잡도가 매우 낮다.

ㅇ 별도의 서버나 런타임이 필요 없다.
→ sqlite 확장 형태로 동작하는 순수 C 기반 라이브러리이며,
`better-sqlite3`에서 `.load()` 한 줄로 바로 사용할 수 있다.

ㅇ SQL을 그대로 활용할 수 있다.
→ `chunk_vec`라는 가상 테이블을 사용하여, 기존 메타데이터 테이블과 일반적인 JOIN으로 연결할 수 있다.
→ 새로운 쿼리 언어나 시스템을 배울 필요 없이 기존 SQL 흐름에 자연스럽게 통합된다.

ㅇ 단순하지만 정확한 벡터 검색 방식
→ sqlite-vec는 “가장 가까운 벡터를 찾는 방식(KNN, k-Nearest Neighbors)”을 사용한다.
→ 쉽게 말하면, “질문과 가장 비슷한 데이터를 직접 전부 비교해서 찾아내는 방식”이다.
→ 일부 벡터 DB처럼 속도를 위해 근사값(ANN)을 사용하는 것이 아니라,
모든 데이터를 비교하기 때문에 정확도가 항상 100%다.
→ 수천~수만 개 수준의 데이터에서는 오히려 별도 튜닝 없이 안정적으로 동작하는 장점이 있다.

ㅇ 현재 프로젝트 규모에 적합하다
→ 약 5,000~10,000개의 벡터, 수 ms 단위 응답 속도 기준에서는 과도한 인프라 없이도 충분히 빠르게 동작한다.
→ 만약 데이터가 100만 건 이상으로 증가하거나, p95 기준 20ms 이하의 응답 속도가 필요해진다면
그 시점에서 Qdrant나 pgvector 같은 전문 벡터 DB로 확장하면 된다.

ㅁ ANN vs brute-force KNN — 개념

ㅇ KNN (K-Nearest Neighbors)
“가장 비슷한 것 k개를 찾는다”는 의미다.
방법은 단순하다.
질문(벡터)을 기준으로 저장된 모든 데이터와 하나씩 전부 비교한다.
그래서 항상 가장 정확한 결과를 반환한다. (놓치는 경우가 없다)
대신 데이터가 많아질수록 비교해야 할 대상이 늘어나기 때문에 속도가 점점 느려진다.

“다 비교해서 정확하게 찾는 방식”

ㅇ ANN (Approximate Nearest Neighbors)
속도를 위해 일부만 비교하는 방식이다.
전체를 다 보지 않고, “비슷할 것 같은 후보들만 빠르게 골라서” 그 안에서 찾는다.
그래서 훨씬 빠르지만, 아주 드물게는 최적의 결과를 놓칠 수도 있다.

“빠르게 대충 찾는 대신, 아주 미세하게 틀릴 수도 있는 방식”

ㅇ 왜 이런 방식이 필요할까?
데이터가 수십만~수백만 개로 커지면, KNN처럼 전부 비교하는 방식은 현실적으로 느려진다.
그래서 ANN 같은 “속도 최적화 구조”가 필요해진다.

ㅇ 대표적인 ANN 방식 (참고)
- HNSW: 그래프를 만들어서 가까운 데이터로 빠르게 이동하며 탐색
- IVF: 데이터를 여러 그룹으로 나누고, 관련 있는 그룹만 탐색

하지만 현재 프로젝트 규모(수천~수만 벡터)에서는
이런 최적화 없이도 KNN이 충분히 빠르고, 오히려 더 단순하고 정확하다.

ㅁ 언제 한계가 오는가?

벡터가 수십만~수백만 단위로 커지고, 응답 시간이 민감해지는 순간 ANN 기반 DB를 고려하면 된다.

비슷한 글을 여기에서도 작성한 적이 있다.
[AI] HNSW - ANN부터 파라미터 튜닝까지, RAG 검색 성능의 진짜 핵심

ㅁ 마무리

데이터가 많지 않은 초기 단계에서는
“빠르게 근사값을 찾는 것”보다
“단순하게, 그리고 정확하게 찾는 것”이 더 중요하다.

sqlite-vec는 별도의 인프라 없이도
이 ‘정확한 검색’을 가장 단순한 형태로 제공한다.

그래서 현재처럼
수천 ~ 수만 개 규모의 벡터를 다루는 환경에서는
복잡한 ANN 구조보다 KNN 기반 접근이 더 현실적인 선택이다.

→ 지금은 “단순함 + 정확도”가 최적화다.
→ 규모가 커지는 순간, 그때 ANN으로 확장하면 된다.

기술 선택은 항상 “지금의 문제 크기”에 맞춰야 한다.

ㅁ 함께 보면 좋은 사이트

ㅇ llm-study-web : LLM 시스템의 전체 흐름을 개념학습, 시스템 맵, 인터랙티브 실험으로 배우는 교육 플랫폼

ㅇ peterica-website: 기록하는 백엔드개발자 피터 포트폴리오 웹사이트

[AI] 1,000개 블로그 글 Wiki에 로컬 RAG 챗봇 붙이기 — peterica-blog-chat

기록하는 백앤드개발자 — Thu, 16 Apr 2026 01:15:05 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

나는 AI를 잘 운영하는 개발자로 성장하기위해 노력하고 있다.

그래서 지난 글 [AI] 1000개 블로그 글을 LLM Wiki로 만든 이야기 — Karpathy의 아이디어를 실전에 적용하다에서

1,000개 문서짜리 제 Obsidian Wiki를 만들었다.

이번엔 그 위에 로컬 RAG 챗봇을 올렸다.

이 글은 그 구축 기록이고, 동시에 왜 Vercel을 버리고 맥미니 + Cloudflare Tunnel로 갔는지에 대한 기록이다.

공부하면서 정리한 LLM System Lam 화면

내가 공부한 llm모델의 임베딩, 로컬 시스템으로 연동하여 나에게 필요한 백터디비의 사양을 파악하는 연습을 하기 위해서다.

우리집 맥미니 M1 8GB에서 local LLM으로 가동 중이다. peterica-blog-chat

ㅁ 요구사항

ㅇ 매일 밤 갱신 → 검색에 즉시 반영
ㅇ 위키 원문을 외부 서비스에 업로드하지 않음
ㅇ 어떤 청크가 top-k에 떴는지 직접 확인 가능
ㅇ 임베딩 모델 / 청킹 전략 / 시스템 프롬프트 교체 자유

→ 위 네 줄이 들어가면 "직접 만든다"로 귀결.

ㅁ 아키텍처

peterica-blog-wiki (~1000 .md)
        │  npm run ingest
        ▼
scripts/ingest.ts     gray-matter + 헤딩 단위 청킹 (target 800자, 코드블록 보존)
        │
        ▼
Ollama /api/embed     bge-m3 (1024d)
        │
        ▼
sqlite-vec            chunks + chunk_vec 가상 테이블 (data/wiki.db 단일 파일)
        │  top-k
        ▼
lib/rag.ts            시스템 프롬프트 조립 + citation 강제
        │
        ▼
AI SDK v6 streamText  Ollama(exaone3.5) / Anthropic swap
        │
        ▼
Next.js 15 App Router useChat + DefaultChatTransport
        │
        ▼
Cloudflare Tunnel  →  https://largest-equal-rain-lucas.trycloudflare.com/

ㅁ 주요 컴포넌트

ㅇ 청킹 (lib/chunk.ts)

gray-matter로 frontmatter 분리
헤딩 경계를 유지하면서 target 800자 근처로 병합
코드블록 중간 분할 금지

ㅇ 임베딩 (lib/embed.ts)

Ollama REST /api/embed, 모델 bge-m3 (1024d)
한/영 혼합 코퍼스에서 오픈소스 중 SOTA 체감

ㅇ 검색 (lib/db.ts, lib/rag.ts)

sqlite-vec 가상 테이블 chunk_vec, L2 거리 기준 top-k
외부 VectorDB 없음. 인덱스 = 파일 1개(data/wiki.db)

ㅇ 생성 (lib/provider.ts)

LLM_PROVIDER=ollama|anthropic 한 줄로 LLM 교체
임베딩은 스왑 대상 아님 (공간 바뀌면 인덱스 전체 무효)

ㅇ 인제스트 (scripts/ingest.ts)

DELETE → 재삽입. 중간 상태 없음
출력: indexed N chunks across M files.

ㅁ 의식적으로 뺀 것

ㅇ Weaviate / Qdrant — 1,000개 규모에 서버 한 대 추가는 오버킬. sqlite-vec로 충분, 백업은 cp.

ㅇ LangChain / LlamaIndex — 청킹 + top-k + 프롬프트 조립은 ~300줄. 프레임워크 끼우면 실패 역추적에 레이어 하나 추가.

ㅇ Vercel — Ollama는 로컬 MPS에서 돌아야 의미가 있음. Vercel Function에서 원격 Ollama를 치는 구성은 레이턴시/비용 모두 불리.

ㅇ Pinecone / 관리형 벡터 — 매일 밤 전체 재인덱싱이 전제. 외부 API 비용 및 데이터 유출 리스크 회피.

ㅁ 왜 sqlite-vec인가

ㅇ DB와 인덱스가 파일 하나(`data/wiki.db`). 백업은 `cp`, 롤백은 파일 교체.

ㅇ 별도 서버·런타임 없음. 순수 C 확장, `better-sqlite3`에 `.load()` 한 줄.

ㅇ SQL 네이티브. 가상 테이블 `chunk_vec`를 메타데이터 테이블과 일반 `JOIN`으로 엮음.
ㅇ brute-force KNN(ANN 미지원). 수천~수만 벡터에선 오히려 장점 — 정확도 1.0, 재인덱싱·튜닝 불필요.

이 프로젝트는 5,000~10,000 벡터, 검색 수 ms. 100만 벡터 넘거나 p95 <20ms 요구가 생기면 그때 Qdrant/pgvector로 졸업.
"pgvector가 과한 규모"에 정확히 맞는 도구.

ㅁ 배포 구성

ㅇ 맥미니 M1 8GB에서 앱은 Docker로 상시 가동 중
ㅇ Ollama는 호스트에서 실행, 컨테이너 내부에서는 host.docker.internal:11434로 접근한다.

Docker 컨테이너 안에서는 CPU만 사용하기 때문에 포퍼먼스가 떨어진다.

ㅇ Cloudflare Tunnel이 8600 → 공개 HTTPS URL로 노출

공개 URL: https://largest-equal-rain-lucas.trycloudflare.com/
(trycloudflare 무료 터널이기 대문에 맥미니가 꺼지면 다시 이곳을 수정해야한다.)

ㅁ 품질 게이트

ㅇ 테스트 프레임워크 없음. 대신:

npm run typecheck — 회귀 1차 방어선
/api/search?q=... — top-k 청크 직접 확인 (검색 품질 검증 전용 엔드포인트)
고정 쿼리 세트 10개 → 상위 3개 중 2개 이상 관련 시 PASS

ㅁ 만들면서 확인한 것

ㅇ RAG 품질은 검색에서 결정됨. LLM을 바꿔도 top-k가 틀리면 답도 틀림.
ㅇ 답변 끝의 출처 링크는 시스템 프롬프트에서 강제하지 않으면 누락됨.
ㅇ 청킹 전략 변경 = 전체 재인덱싱. 그래서 ingest는 항상 전량 재삽입.
ㅇ 인덱스가 파일 1개이면 백업·이사·롤백이 cp 한 번.

ㅁ 다음 작업

ㅇ 증분 업데이트 (현재: 전량 재삽입)
ㅇ 리랭커 단 추가

— bge-reranker-v2-m3 후보
ㅇ 고정 쿼리 세트 기반 RAG 회귀 자동화 (verify-rag-quality 스킬 연계)
ㅇ Obsidian 링크 그래프를 검색 결과에 동반 노출

ㅁ 마무리 한 줄

✅ 1,000개 문서는 보유만으로는 창고. 검색이 붙는 순간 두 번째 뇌가 된다.

ㅁ 함께 보면 좋은 사이트

ㅇ llm-study-web : LLM 시스템의 전체 흐름을 개념학습, 시스템 맵, 인터랙티브 실험으로 배우는 교육 플랫폼

ㅇ peterica-website: 기록하는 백엔드개발자 피터 포트폴리오 웹사이트

Claude Code에 FDE 메인 디스패처 붙이기 - 스킬을 부르는 스킬

기록하는 백앤드개발자 — Wed, 15 Apr 2026 00:23:46 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

예전에 "Claude Code를 소프트웨어처럼 설계하기 — 프롬프트 하네스 아키텍처" 라는 글에서 정리한 적이 있다.

프롬프트가 코드이고, 스킬이 함수이며, 에이전트가 마이크로서비스라는 관점이다.

그 위에서 블로그 1,000편을 스크래핑하고 위키로 변환하는 파이프라인을 운영했다.

시간이 지나니 스킬이 17개, 18개, 20개로 늘어났다.

한편으로는 좋았지만, 다른 한편으로는 "어떤 스킬을 언제 불러야 하는지" 를 나조차 자주 잊어버렸다.

"이 초안 팩트체크도 하고 폴리싱도 하고 발행준비도 해줘"라고 말하면,

Claude가 어떤 스킬을 어떤 순서로 부를지 매번 다르게 해석했다.

그래서 하나 더 만들었다.

이번엔 스킬을 부르는 스킬 - FDE(Forward Deployed Engineer) 역할의 메인 디스패처다.

이 글은 그 설계와 동작 방식을 짧게 정리한다.

ㅁ 문제 — 스킬이 늘어날수록 라우팅이 어려워진다

스킬 하나는 잘 정의된 워크플로를 가진다.

blog-factcheck, blog-polish, blog-publish-prep 각자 명확하다.

그런데 사용자는 자연어로 말한다:

"task/11_새주제에 초안 만들고 팩트체크·폴리시·발행준비까지 해줘"

이 한 줄에 4개의 하위 작업이 있고,

각각 다른 스킬과 매칭되며, 일부는 병렬 가능하고 일부는 의존성이 있다.

이걸 매번 사람이 분해해서 "먼저 이거 실행하고, 그다음 저거 실행하고…" 라고 지시하기는 번거롭다.

소프트웨어로 치면 라우터가 없는 마이크로서비스 군집 같은 상태다.

ㅁ 해결 — FDE 역할의 디스패처 스킬

Forward Deployed Engineer의 핵심 역할은

고객의 모호한 요청을 실행 가능한 작업으로 분해하는 것이다.

그 역할을 스킬로 캡슐화했다.

동작은 5단계로 고정한다.

1. 분석 (Analyze)   → 자연어 지시 파싱, 의도·산출물·제약 추출
2. 계획 (Plan)      → 원자 단위로 분해 + 스킬 매칭 + 의존성 그래프
3. 제안 (Propose)   → 실행 계획 테이블 제시 (사용자 승인 대기)
4. 위임 (Dispatch)  → 승인 후 Wave 단위 병렬 실행 (≤3)
5. 통합 (Integrate) → 결과 회수 + 충돌 조정 + 최종 보고

핵심은 3번 제안 단계에서 반드시 멈춘다는 것이다.

소프트웨어의 Plan/Apply 패턴 (Terraform, kubectl diff)과 같다 — 계획을 먼저 보여주고, 승인받은 후에만 상태를 바꾼다.

ㅁ 스킬 매칭은 어떻게 하나 — 3-tier Lookup

사용자 지시에서 추출한 하위 작업을 스킬에 매칭할 때, 우선순위 3단으로 탐색한다.

Tier	방법	근거 파일
1	Exact keyword	skill-cross-reference.md, 4 트리거 매트릭스
2	Category match	skill_info.md, 2 카테고리 분류
3	Fallback	직접 수행 또는 manage-skills 에 신규 스킬 제안 위임

각 매칭에 Confidence (High / Medium / Low)를 부여한다.

Low면 사용자에게 확인을 요청한다.

이 구조는 CDN의 캐시 계층 과 닮았다 — L1 미스면 L2, 그래도 없으면 오리진으로 간다.

ㅁ 왜 승인 단계를 넣었는가

디스패처를 만들면서 가장 고민한 건 "언제 멈출 것인가" 였다.

자연어 지시에서 바로 실행으로 넘어가면 편하지만, 내가 의도하지 않은 스킬이 호출되는 순간 되돌리기 어려워진다.

그래서 실행 계획을 표로 제시하고 승인받는 단계를 강제했다.

Terraform 이나 kubectl 의 plan / diff 가 한 번 검토를 강제하는 것과 같은 이유다.

사람이 "예"라고 말하기 전까지는 어떤 스킬도 건드리지 않는다.

편의를 조금 포기하는 대신, 예상 가능한 실행을 얻었다.

ㅁ 왜 글로벌로 승격했는가

처음엔 블로그 레포 하나에서만 쓰려고 만들었다.

그런데 다른 레포로 옮겨 작업하다가 같은 사고 패턴이 또 필요해졌다.

문제는 같은데 레포마다 스킬 목록·참조 파일·경로가 다르다는 것이다.

그래서 ~/.claude/skills/ 로 올렸다.

대신 프로젝트마다 환경이 다르니 있으면 쓰고, 없으면 다음 층을 본다는 fallback 체인으로 설계했다.

프로젝트 특화 정보가 풍부하면 정확히 매칭되고, 아무것도 없으면 세션 레지스트리 description 만으로도 동작한다.

한 줄로 요약하면 — "환경은 다르지만 사고 패턴은 같다" 를 코드로 옮긴 것이다.

ㅁ 스킬에 스킬을 붙인다는 것

스킬 1~2개일 때는 필요 없는 고민이다. 그때는 그냥 부르면 된다.

그런데 스킬이 20개쯤 되자 내가 먼저 잊기 시작했다.

그 시점부터는 스킬을 더 만드는 것보다 스킬을 고르는 방식 을 설계하는 게 효율적이었다.

함수가 늘면 라우터를, 마이크로서비스가 늘면 API 게이트웨이를 붙이는 것과 같은 순서다.

도구의 수가 임계점을 넘으면, 도구보다 도구를 고르는 방식이 더 중요해진다.

ㅁ 마무리

처음엔 스킬 하나로 시작했다. 몇 개 더 만들면서 편해졌다.

열 개가 넘어가자 어떤 스킬이 있는지 내가 잊기 시작했다.

스무 개쯤 되자 Claude 도 라우팅을 흔들기 시작했다.

그 시점에서 필요한 건 더 많은 스킬이 아니라 스킬을 부르는 스킬이다.

FDE 디스패처는 그렇게 태어났다.

"도구가 늘어나면 도구를 고르는 도구가 필요해진다."

ㅁ 함께 보면 좋은 사이트

Claude Code를 소프트웨어처럼 설계하기 — 프롬프트 하네스 아키텍처 (이 글의 선행 맥락)
Claude Code 공식 문서 — https://docs.claude.com/en/docs/claude-code
Terraform Plan/Apply — https://developer.hashicorp.com/terraform/cli/commands/plan

사용 기술

Claude Code (Opus) — 메인 오케스트레이터
Sonnet subAgent — 병렬 실행 워커 (≤3)
.claude/skills/ — 스킬 레지스트리
skill_info.md — 스킬 카탈로그
skill-cross-reference.md — 의도→스킬 매핑 테이블

Argo CD vs Jenkins — 왜 하나로 묶지 않고 역할을 분리하는가

기록하는 백앤드개발자 — Tue, 14 Apr 2026 23:49:24 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

오늘 회의 시간에 나온 질문이다.

"왜 Argo CD로 다 안 하고 Jenkins로 빌드하죠?" 쿠버네티스 도입 초기 팀에서 자주 나오는 질문이다.

Argo CD 이름에 "CD"가 박혀 있으니 CI/CD 풀스택으로 오해하기 쉽지만, 실제로는 그렇지 않다.

결론부터 말하면 이미지 빌드는 Jenkins, 클러스터 배포는 Argo CD 다.

둘은 경쟁재가 아니라 조합재다. 이 글은 그 역할 분리가 왜 자연스러운 설계인지 정리한다.

ㅁ 역할이 애초에 다르다 — CI vs CD

Jenkins와 Argo CD는 파이프라인에서 서로 다른 영역을 책임진다.

Jenkins
— 코드 변경 → 빌드 → 테스트 → Docker 이미지 생성 → 레지스트리 푸시. CI (Continuous Integration) 영역.
Argo CD
— Git 상태와 Kubernetes 상태를 동기화. CD (Continuous Delivery / GitOps) 영역.

즉 Argo CD는 "이미 만들어진 이미지"를 배포하는 도구이지, 빌드 도구가 아니다.

소프트웨어로 치면 컴파일러와 배포 오케스트레이터가 서로 다른 일을 하는 것과 같다.

ㅁ Docker 이미지 빌드 관점 비교

축	Jenkins	Argo CD
역할	CI (빌드·테스트·푸시)	CD (Git↔K8s 동기화)
Docker 빌드	O	X
주요 기능	플러그인·파이프라인·스캔	Git manifest 동기화 (이미지 태그 자동화는 Image Updater 조합)
강점	병렬·캐싱·분기, OSS/라이선스 체크	GitOps 선언형, 롤백·드리프트 감지
적합 상황	복잡한 빌드/검증 로직	Kubernetes 배포 자동화

Argo CD만으로 "빌드 파이프라인" 자체를 구성하지는 못한다.

빌드가 필요하면 Jenkins나 GitHub Actions 같은 CI 도구를 별도로 둬야 한다.

Jenkins는 오랜 역사 덕에 CI 분야에서 가장 널리 쓰이는 선택지 중 하나다.

ㅁ 현실적인 권장 아키텍처

[개발자 push]
   ↓
Jenkins (CI)
 - Docker build
 - test
 - image push (Docker Hub 등)
   ↓
Git (manifest or helm 업데이트)
   ↓
Argo CD (CD)
 - Kubernetes 배포

빌드 결과물은 레지스트리로, 배포 선언은 Git manifest 로 흘러들어 간다.

Argo CD는 Git을 단일 진실 원천(Single Source of Truth) 으로 삼아 클러스터 상태를 맞춘다.

ㅁ 팀장이 Jenkins를 고집하는 이유 (추정 3가지)

빌드 자동화 경험 — Jenkins는 오래된 표준이라 안정성과 레퍼런스가 많다.
복잡한 파이프라인 필요 — OSS 검증, 라이선스 체크, 사내 하네스 실행 등. Argo CD는 이런 로직을 처리하지 못한다.
"Argo CD = CI/CD" 오해 방지 — 이름 때문에 CD 전용임이 잘 전달되지 않는다.

ㅁ 종합 — 문제 → 해결 → 소프트웨어 대응 개념

문제	해결 메커니즘	소프트웨어 대응 개념
빌드 로직 복잡성	Jenkins Pipeline	빌드 도구 (Make / Bazel)
배포 상태 일관성	Argo CD GitOps	상태 머신 (Reconciliation Loop)
배포 추적·롤백	Git commit 이력	버전 관리 (Git 자체)
클러스터 드리프트	Argo 자동 동기화	선언적 인프라 (Terraform state)

결국 CI와 CD를 한 도구로 묶으려는 시도는 단일 책임 원칙(SRP) 을 위배하는 셈이다. 각자 잘하는 영역이 다르고, 도구를 분리하면 각 영역을 독립적으로 진화시킬 수 있다.

ㅁ 내 선택

이미지 빌드 → Jenkins
클러스터 배포 → Argo CD
연결 고리 → Git manifest 리포지토리 + 이미지 태그 업데이트 훅

소규모 팀이라면 GitHub Actions + Argo CD 조합도 충분하다.

중요한 건 "빌드와 배포를 하나의 도구로 묶지 말 것" 이라는 원칙이다.

ㅁ 마무리

CI와 CD를 같은 박스로 취급하면 파이프라인은 빠르게 엉킨다.

역할이 다른 도구를 억지로 통합하기보다, 책임을 분리하고 계약만 명확히 하자.

Jenkins는 아티팩트를 만들고, Argo CD는 그것을 클러스터에 흘려보낸다. 그 사이를 Git이 이어준다.

"Argo CD는 배포 동기화 도구, Jenkins는 빌드/테스트 실행 엔진이다."

ㅁ 함께 보면 좋은 사이트

Argo CD 공식 문서 — https://argo-cd.readthedocs.io/en/stable/
OpenGitOps Principles (CNCF) — https://opengitops.dev/
[Jenkins] Docker 기반 Jenkins quick start — https://peterica.tistory.com/407
[kubernetes] cdk8s란 무엇인가요? — https://peterica.tistory.com/523
[kubernets] skaffold란, Kubernetes 로컬 개발환경 — https://peterica.tistory.com/245

ㅁ 사용 기술

Jenkins — CI / 빌드 오케스트레이터
Argo CD — CD / GitOps 컨트롤러
Kubernetes — 배포 대상
Docker / ECR — 이미지 빌드 / 레지스트리
Git — 단일 진실 원천 (Single Source of Truth)

샘플 프롬프트 모음 — Claude Code 하네스 설계 실전 예시

기록하는 백앤드개발자 — Tue, 14 Apr 2026 01:58:06 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

이 문서는 이전 글 Claude Code를 소프트웨어처럼 설계하기 - 프롬프트 하네스 아키텍처 에서 설명한 각 설계 패턴을 실제로 구현할 때 사용한 프롬프트 예시를 모아둔 것이다.

그대로 복사해서 쓸 수 있도록 작성했다.

1. CLAUDE.md — 글로벌 행동 규칙 정의

프롬프트: 글로벌 규칙 파일 작성 요청

~/.claude/CLAUDE.md에 다음 규칙을 추가해줘:

1. 코드 수정 전 반드시 해당 파일을 Read 한 후 Edit 한다
2. git commit은 명시적 요청 없이 절대 하지 않는다
3. 임시 파일은 작업 완료 후 반드시 삭제한다
4. 테스트가 있는 프로젝트에서는 코드 수정 후 테스트를 실행한다
5. feature 브랜치에서만 작업하고, main에 직접 커밋하지 않는다

프롬프트: 프로젝트 CLAUDE.md 작성

이 프로젝트의 CLAUDE.md를 작성해줘. 다음 내용을 포함해야 한다:

## 프로젝트 개요
- Tistory 블로그(1,000+ 글) 스크래핑·요약·위키 변환 파이프라인
- Harness 구조: Claude(계획/평가) + Codex(배치 실행)

## 폴더 구조
- scripts/: Python 파이프라인 스크립트
- data/: URLs, JSONL, shards
- docs/: 최종 산출물 (INDEX.md)

## 핵심 규칙
- 생성 결과물(data/, docs/)은 직접 수정하지 말고, scripts/ 수정 후 재생성
- 서브 에이전트 병렬 처리는 동시 최대 3개
- 모든 생성물은 Rubric 평가를 거친 후에만 병합

2. 스킬 파일 작성

프롬프트: 스크래핑 스킬 생성

.claude/skills/blog-scrape.md 스킬을 만들어줘.

트리거: /blog-scrape
입력: shard 파일 경로 (예: data/shards/0001.txt)
동작:
  1. shard 파일에서 URL 목록을 읽는다
  2. scripts/scrape_shard.py를 실행하여 HTML을 fetch하고 본문을 파싱한다
  3. 출력 JSONL의 각 레코드가 스키마를 만족하는지 검증한다
  4. 실패 건이 있으면 에러 리포트를 출력한다

출력 스키마:
  {id, title, url, published_at, body, word_count, source_hash}

검증 조건:
  - 모든 필드 non-null
  - word_count > 10
  - source_hash는 SHA-256 형식

프롬프트: 평가 스킬 생성

.claude/skills/blog-evaluate.md 스킬을 만들어줘.

트리거: /blog-evaluate
입력: shard JSONL 파일 경로
동작:
  1. JSONL의 각 레코드에 대해 Rubric 체크리스트를 평가한다
  2. PASS/FAIL 판정과 사유를 기록한다
  3. FAIL 레코드에 대해 구체적 개선 피드백을 생성한다
  4. 평가 리포트를 reports/ 디렉토리에 출력한다

Rubric 체크리스트:
  - summary가 2문장 이상이고 본문 핵심을 반영하는가?
  - tags가 3~8개이고 관련성이 있는가?
  - category가 허용 목록(12개 MOC)에 포함되는가?
  - keywords가 summary에 1개 이상 등장하는가?

FAIL 시 피드백 형식:
  "id: 0042, reason: summary가 1문장, fix: 본문의 두 번째 핵심 논점을 추가"

3. 에이전트 정의

프롬프트: 하네스 오케스트레이션 규칙 (CLAUDE.md 또는 세션 초두에 입력)

너는 Opus 역할의 메인 에이전트다.
계획 수립, 우선순위 결정, 결과 통합, 최종 판단은 직접 수행하라.
독립적이고 병렬 가능한 조사/구현/검증 작업은 Sonnet 성격의 subAgent에게 위임하라.

규칙:
- 먼저 작업을 하위 작업으로 분해한다.
- 여러 파일 조사, 테스트 확인, 리팩터링 후보 탐색, 초안 작성은 subAgent에 맡긴다.
- 아키텍처 판단, 충돌 조정, 최종 반영 여부는 직접 결정한다.
- subAgent 결과는 근거 중심으로 회수하고, 메인 에이전트가 통합 결론을 작성한다.
- 항상 "분해 → 위임 → 통합 → 최종판단" 순서로 일한다.

이 프롬프트는 개별 에이전트를 정의하기 전에, 메인과 서브의 협력 원칙을 선언하는 것이다.
CLAUDE.md에 영구 규칙으로 넣거나, 복잡한 작업 시작 시 세션 초두에 입력한다.

프롬프트: 배치 워커 에이전트 생성

.claude/agents/blog-batch-worker.md 에이전트를 만들어줘.

역할: Codex 서브워커. 단일 shard(50 URL)를 받아서 scrape → summarize → tag을 수행하고, 검증된 JSONL을 출력한다.

실행 절차:
  1. shard 파일에서 URL 50건을 읽는다
  2. scripts/scrape_shard.py를 실행하여 HTML fetch + 본문 파싱
  3. 파싱 결과에 대해 요약·태그·카테고리·키워드를 생성한다
  4. 출력 JSONL의 각 레코드를 스키마 검증한다
  5. 검증 통과 건만 포함한 .jsonl 파일을 data/shards/에 저장한다

제약 조건:
  - 한 번에 하나의 shard만 처리한다
  - 외부 API 호출 없이 로컬 LLM만 사용한다
  - 실패한 URL은 .failed.txt에 기록한다

사용 도구: Bash, Read, Write, Grep

4. Evaluator-Optimizer 루프

프롬프트: 재생성 루프 실행

data/shards/0003.jsonl에 대해 Evaluator-Optimizer 루프를 실행해줘.

1단계 — 평가:
  /blog-evaluate data/shards/0003.jsonl

2단계 — FAIL 건 재생성:
  평가 리포트에서 FAIL 판정을 받은 레코드에 대해,
  피드백을 반영하여 summary와 tags를 재생성해줘.
  재생성 결과를 0003.retry1.jsonl로 저장한다.

3단계 — 재평가:
  0003.retry1.jsonl을 다시 /blog-evaluate로 평가한다.
  여전히 FAIL이면 2단계를 반복한다. 최대 3회까지.

4단계 — 병합:
  최종 PASS 건만 data/shards/0003.final.jsonl로 출력한다.
  최종 FAIL 건은 reports/fail_0003.md에 사유와 함께 기록한다.

5. 세션 관리

프롬프트: 세션 시작

/session-start

PLAN.md와 PROGRESS.md를 읽고, 현재 상태를 3줄 이내로 보고해줘.
진행 중(`[~]`)인 작업이 있으면 어떤 작업인지 알려줘.
다음으로 착수해야 할 P0 작업이 무엇인지 추천해줘.

프롬프트: 세션 종료

/session-end

이번 세션에서 수행한 작업을 PROGRESS.md에 추가해줘.
형식:
  ## 세션: 2026-04-14
  - 수행: [작업 내용]
  - 결과: [산출물]
  - 다음: [이어서 해야 할 작업]

PLAN.md에서 완료된 항목을 [x]로 변경해줘.
임시 파일이 있으면 정리해줘.

6. FLAGS 활용

FLAGS 시스템은 이 프로젝트의 ~/.claude/FLAGS.md에 정의된 커스텀 규약이다.

Claude Code의 공식 기능이 아니라, CLAUDE.md를 통해
내가 "이 플래그가 오면 이렇게 행동하라"고 사전 지시받은 것이다.

플래그는 자주 쓰는 지시를 단축어로 만든 것이라고 보면 된다.

alias ll='ls -la'처럼.

프롬프트: 깊은 분석이 필요한 경우

--think-hard

현재 프로젝트의 스크래핑 파이프라인에 에러 핸들링이 충분한지 분석해줘.
scripts/ 디렉토리의 모든 Python 파일을 읽고:
  1. 네트워크 에러 처리 현황
  2. 파싱 실패 시 복구 전략
  3. 부분 실패 시 전체 배치에 미치는 영향
을 평가해줘.

프롬프트: 대량 작업 위임

--delegate

data/shards/ 디렉토리에 있는 모든 shard 파일(0001~0020)에 대해
blog-batch-worker 에이전트를 병렬로 실행해줘.
동시 실행 최대 3개로 제한하고,
각 배치 완료 시 진행 상황을 보고해줘.

프롬프트: 토큰 절약 모드

--token-efficient

posts.jsonl의 987개 레코드를 카테고리별로 집계하고,
카테고리당 게시글 수, 평균 word_count, 태그 분포를 표로 정리해줘.
출력은 최소한으로, 표와 수치만.

7. 하네스 전체 파이프라인 실행

프롬프트: 전체 파이프라인 오케스트레이션

블로그 목차 자동 생성 파이프라인을 전체 실행해줘.

Phase 1 — Discover:
  /blog-discover로 전체 URL을 수집하여 data/urls.txt에 저장

Phase 2 — Shard:
  data/urls.txt를 50건 단위로 분할하여 data/shards/에 저장

Phase 3 — Scrape + Summarize:
  각 shard에 대해 blog-batch-worker 에이전트를 실행 (최대 3 병렬)
  각 배치 완료 후 /blog-evaluate로 Rubric 검증
  FAIL 건은 Evaluator-Optimizer 루프로 재생성 (최대 3회)

Phase 4 — Merge:
  모든 shard의 .final.jsonl을 data/posts.jsonl로 병합

Phase 5 — Render:
  /blog-render로 docs/INDEX.md와 docs/INDEX_BY_TAG.md 생성

Phase 6 — Verify:
  /verify-posts-jsonl로 최종 검증
  reports/build_report.md에 전체 결과 기록

각 Phase 완료 시 진행 상황을 보고하고, PLAN.md를 업데이트해줘.

8. Memory 활용

프롬프트: 피드백 기억 요청

이것 기억해줘: Docker 재시작이나 빌드 같은 운영 작업은 sonnet 서브에이전트에 위임해.
이유: Opus 토큰을 운영 작업에 쓰는 건 낭비이고, sonnet이 충분히 처리 가능하다.

프롬프트: 프로젝트 컨텍스트 기억 요청

프로젝트 메모로 저장해줘:
현재 posts.jsonl에는 987개 레코드가 있고,
LLM 카테고리(151건) 중 41건(27.2%)이 오분류되어 있었다.
키워드 기반 재분류로 해결했고, wiki_validate_refs.py로 교차 검증 완료.

활용 팁

스킬은 작게 시작한다 — 처음부터 완벽한 스킬을 만들 필요 없다. 기본 절차와 출력 형식만 정의하고, 실행하면서 검증 조건을 추가한다.
CLAUDE.md는 점진적으로 성장한다 — 처음에는 3줄이어도 된다. 세션을 반복하면서 "이건 매번 설명해야 하네"라는 것을 발견할 때마다 추가한다.
Rubric은 구체적이어야 한다 — "좋은 요약인가?"보다 "2문장 이상이고 본문 키워드를 포함하는가?"가 기계적 판정에 적합하다.
FLAGS는 상황에 맞게 쓴다 — 모든 작업에 --ultrathink를 쓰면 토큰 낭비다. 단순 작업은 기본 모드로, 복잡한 분석만 깊은 모드로.
Memory는 "놀라운 것"만 저장한다 — 코드에서 읽을 수 있는 것은 저장하지 않는다. "사용자가 3000 포트를 싫어한다"처럼 코드에 없는 선호만 기억한다.

Claude Code를 소프트웨어처럼 설계하기 - 프롬프트 하네스 아키텍처

기록하는 백앤드개발자 — Tue, 14 Apr 2026 01:21:44 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

Claude Code를 처음 쓸 때는 대화창에 "이거 만들어줘"라고 치면 됐다.

하지만 1,000개 블로그 글을 자동으로 스크래핑하고, 요약하고, 위키로 변환하는 파이프라인을 만들면서 한계를 느꼈다.

매번 같은 맥락을 설명해야 했고, 세션이 바뀌면 전부 잊어버렸고, 반복 작업에 비싼 모델의 토큰을 낭비했다.

그래서 접근을 바꿨다.

Claude를 "대화 상대"가 아니라 "프로그래밍 가능한 실행 엔진"으로 설계하기로 했다.

프롬프트가 코드이고, 스킬이 함수이며, 에이전트가 마이크로서비스인 구조다.

이 글에서 그 설계를 정리한다.

1. 계층적 프롬프트 주입 — 설정 파일처럼 쓰는 CLAUDE.md

Claude Code는 대화 시작 시 여러 레벨의 설정 파일을 자동으로 로드한다.

글로벌 (~/.claude/CLAUDE.md)        ← 모든 프로젝트에 적용
  ├── RULES.md                      ← 행동 규칙
  ├── PRINCIPLES.md                 ← 엔지니어링 원칙
  └── FLAGS.md                      ← 실행 모드 플래그
프로젝트 (./CLAUDE.md)              ← 이 프로젝트에만 적용
  ├── Skills (.claude/skills/)      ← 재사용 가능한 작업 단위
  ├── Agents (.claude/agents/)      ← 위임 가능한 서브 에이전트
  └── References (.claude/references/) ← 공유 컨텍스트
메모리 (memory/)                    ← 세션 간 지속 학습

이 구조는 소프트웨어의 설정 관리와 같다.

~/.claude/CLAUDE.md는 .gitconfig 같은 글로벌 설정이고,

프로젝트 CLAUDE.md는 .eslintrc 같은 프로젝트 설정이다.

핵심은 관심사의 분리(Separation of Concerns)다.

글로벌 규칙은 "어떻게 일할 것인가"를 정의한다 — 코드 리뷰 스타일, Git 워크플로우, 안전 규칙 등
프로젝트 설정은 "무엇을 할 것인가"를 정의한다 — 스크래핑 대상, 데이터 스키마, 파이프라인 단계 등

같은 사람이 다른 프로젝트를 열면 행동 규칙은 유지하면서 도메인 컨텍스트만 교체된다.

마치 같은 개발자가 다른 프로젝트의 .eslintrc를 따르듯이.

2. 스킬(Skill) 시스템 — 프롬프트를 함수처럼 캡슐화

스킬은 .claude/skills/ 디렉토리에 정의된 마크다운 파일이다.

/blog-discover, /blog-scrape 같은 슬래시 커맨드로 호출한다.

# .claude/skills/blog-scrape.md (예시 구조)
---
name: blog-scrape
description: Shard 단위 HTML 파싱·본문 추출
trigger: blog-scrape
---

###### 입력
- shard 파일 경로 (예: data/shards/0001.txt)

###### 절차
1. shard 파일에서 URL 목록 로드
2. httpx로 병렬 fetch
3. selectolax로 본문·제목·날짜 파싱
4. 결과를 JSONL로 출력

###### 출력 스키마
{id, title, url, published_at, body, word_count, source_hash}

###### 검증 기준
- 모든 필드 non-null
- word_count > 10
- source_hash는 SHA-256

이것의 가치는 세 가지다:

재현성 — "URL 수집해줘"라는 자연어 대신, 사전 정의된 절차·검증 기준·출력 형식이 캡슐화되어 있다. 누가 언제 호출해도 동일한 품질의 결과를 기대할 수 있다.

체이닝 — discover → scrape → summarize → evaluate → render 파이프라인을 스킬 단위로 연결한다. 각 스킬은 입력·출력 스키마가 명확하므로 파이프 연결이 자연스럽다.

위임 가능 — 스킬은 서브 에이전트에 위임할 수 있다. 메인 Claude가 스킬을 호출하면, 해당 작업은 별도 컨텍스트에서 실행된다.

소프트웨어 공학에서 코드를 함수로 분리하듯, LLM의 행동을 스킬로 분리한 것이다.

3. Harness 패턴 — 이중 에이전트 분업 구조

하네스(Harness)는 Claude(Main)와 Codex/로컬 LLM(Sub)의 분업 구조다.

Claude (Main/Orchestrator)          Codex / Local LLM (Sub/Worker)
┌─────────────────────┐            ┌─────────────────────┐
│ 계획 수립            │            │ 배치 스크래핑        │
│ Rubric 평가          │──위임──→  │ 요약 생성            │
│ 병합/렌더            │            │ 태깅                 │
│ 품질 판정            │←──결과──  │ JSONL 출력           │
└─────────────────────┘            └─────────────────────┘

왜 이렇게 나누는가?

토큰 경제성 — Claude Opus는 토큰 단가가 높다. 1,000개 게시글의 반복적 스크래핑/요약을 Opus에서 직접 하면 비용이 폭증한다. 단순 반복 작업은 더 저렴한 모델(Codex, qwen3:8b)에 위임하고, Opus는 판단·평가·오케스트레이션에 집중한다.

컨텍스트 윈도우 보호 — 1,000개 게시글의 HTML을 메인 대화에 로드하면 컨텍스트가 즉시 포화된다. Shard 단위(50건)로 서브 에이전트에 위임하면 메인 컨텍스트는 깨끗하게 유지된다.

병렬성 — 최대 3개 배치를 동시에 처리할 수 있어 처리량이 3배로 늘어난다.

이 구조는 마이크로서비스 아키텍처와 유사하다. 메인 서비스(Claude)가 API 게이트웨이 역할을 하고, 워커 서비스(Codex/로컬 LLM)가 실제 데이터 처리를 담당한다.

4. Evaluator-Optimizer 루프 — 자기 교정 메커니즘

LLM의 근본적 약점은 비결정성이다. 같은 입력에 다른 출력이 나올 수 있다.

이에 대한 대응이 Evaluator-Optimizer 루프다.

생성(Generate) → 평가(Evaluate) → PASS? ──→ 병합
                      ↓ FAIL
               피드백(Feedback) → 재생성 (최대 3회)

Rubric은 기계적 판정 기준이다. 예를 들어:

###### Rubric 체크리스트
- [ ] summary가 2문장 이상인가?
- [ ] tags가 3개 이상인가?
- [ ] category가 허용 목록에 포함되는가?
- [ ] summary가 본문 내용과 관련 있는가?
- [ ] keywords가 summary에 등장하는가?

이 루프가 보장하는 것:

품질 하한선 — Rubric을 통과하지 못하면 최종 산출물에 포함되지 않는다
추적 가능성 — 어떤 기준에서 실패했는지 리포트로 기록된다
수렴성 — 최대 3회 제한으로 무한 루프를 방지한다

소프트웨어의 CI/CD 파이프라인에서 테스트가 실패하면 배포를 막는 것과 같은 원리다.

5. 세션 연속성 — LLM에 장기 기억을 시뮬레이션

LLM의 가장 큰 제약은 세션 간 기억 상실이다. 새 대화를 열면 이전에 무엇을 했는지 전부 잊는다. 이 프로젝트는 세 가지 메커니즘으로 이를 해결한다.

메커니즘	파일	용도	수명
Memory	memory/*.md	사용자 선호, 피드백, 프로젝트 컨텍스트	영구
Plan	PLAN.md	작업 체크리스트와 상태 ([ ], [~], [x])	프로젝트 수명
Progress	PROGRESS.md	세션별 작업 기록	프로젝트 수명

세션 시작 시 session-start 스킬이 이 세 파일을 읽고 상태를 보고한다:

> PLAN.md: P0 작업 8/10 완료, P1 작업 3/7 완료
> PROGRESS.md: 마지막 세션 — wiki concepts 122개 생성, Rubric 100% PASS
> memory: 사용자는 84XX 포트 대역 선호, Docker 작업은 sonnet에 위임

이것은 소프트웨어의 상태 관리(State Management)다. React의 Context나 Redux처럼, 세션 간 공유해야 하는 상태를 파일 시스템에 영속화한 것이다. Memory가 Redux Store, PLAN.md가 To-Do State, PROGRESS.md가 Activity Log에 해당한다.

6. FLAGS 시스템 — 런타임 행동 제어

같은 Claude에게 상황에 따라 다른 행동 모드를 적용하는 플래그 시스템이다.

## 분석 깊이 조절
--think          → 표준 분석 (~4K 토큰)
--think-hard     → 깊은 분석 (~10K 토큰)
--ultrathink     → 최대 깊이 (~32K 토큰)

## 실행 모드
--delegate       → 서브 에이전트 병렬 위임
--token-efficient → 압축 커뮤니케이션 모드
--safe-mode      → 최대 검증, 보수적 실행

## 도구 선택
--context7       → 공식 문서 조회 활성화
--sequential     → 구조화된 추론 활성화

이것은 프로그래밍의 Feature Flag 또는 런타임 설정(Runtime Configuration)과 같다.

소프트웨어에서 DEBUG=true로 로그 레벨을 바꾸듯, --think-hard로 분석 깊이를 바꾼다.

핵심 가치는 하나의 모델을 여러 전문가처럼 전환할 수 있다는 것이다.

단순 파일 수정에 --ultrathink를 쓰면 토큰 낭비이고, 아키텍처 설계에 기본 모드를 쓰면 깊이가 부족하다.

상황에 맞는 행동 모드를 선택할 수 있다.

7. 종합 — 이 설계가 해결하는 5가지 문제

문제	해결 메커니즘	소프트웨어 대응 개념
매번 다른 결과	Skill + Rubric	함수 + 단위 테스트
비싼 토큰 비용	Harness (역할 분업)	마이크로서비스
대량 데이터 처리	Shard 병렬 처리	배치 프로세싱
세션 간 기억 상실	Memory + PLAN + PROGRESS	상태 관리 (Redux)
상황별 행동 조절	FLAGS 시스템	Feature Flag

결국 이 구조는 LLM을 소프트웨어 시스템처럼 설계한 것이다.

프롬프트가 코드이고, 스킬이 함수이며, 에이전트가 마이크로서비스이고, CLAUDE.md가 설정 파일이다.

마지막으로 내가 사용한 샘플 프롬프트 모음을 남기도록 한다.

샘플 프롬프트 모음 — Claude Code 하네스 설계 실전 예시

ㅁ 마무리

Claude Code는 강력한 도구지만, "강력한 도구를 잘 쓰는 것"은 별개의 문제다.

대화형으로만 쓰면 매번 같은 설명을 반복하고, 품질이 들쭉날쭉하고, 비용이 제어되지 않는다.

프롬프트를 코드처럼, 스킬을 함수처럼, 에이전트를 서비스처럼 설계하면

— LLM은 "대화 상대"에서 "프로그래밍 가능한 실행 엔진"으로 전환된다.

"좋은 AI 결과는 모델이 아니라, 설계된 시스템에서 나온다."

ㅁ 함께 보면 좋은 사이트

Claude Code 공식 문서: https://docs.anthropic.com/en/docs/claude-code
Karpathy LLM Wiki: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
블로그: https://peterica.tistory.com

ㅁ 사용 기술

Claude Code (Opus) — 메인 오케스트레이터
Codex / qwen3:8b — 서브 워커
Python — 파이프라인 스크립트
Obsidian — 지식 위키 시각화

[AI] 1000개 블로그 글을 LLM Wiki로 만든 이야기 — Karpathy의 아이디어를 실전에 적용하다

기록하는 백앤드개발자 — Mon, 13 Apr 2026 00:17:06 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

블로그 글을 1000개 쓰면 뿌듯할 줄 알았다.

그런데 어느 날 내가 뭘 아는지 스스로 설명하지 못하는 자신을 발견했다. 글은 많은데, 체계가 없었다.

DevOps 글이 여기저기 흩어져 있고, Kubernetes 관련 글은 카테고리가 3개로 나뉘어 있었다.

"내가 Kubernetes에 대해 뭘 알고 있지?"라는 질문에 블로그 목록을 위아래로 스크롤하는 것 말고는 방법이 없었다.

그러던 중 Andrej Karpathy가 공유한 LLM-Wiki 아이디어를 봤다.

핵심은 간단했다.

"RAG처럼 매번 원본을 검색하지 말고, LLM이 위키를 만들고 유지보수하게 하라."

이 글에서는 이 아이디어를 987개 블로그 글에 실제로 적용한 과정을 정리한다.

ㅁ LLM-WIKI의 핵심

Karpathy의 LLM Wiki는 LLM이 단순히 문서를 검색하는 도구가 아니라, 원본 데이터(raw sources)를 읽어 스스로 구조화된 Markdown 위키를 생성·유지하며 지식을 누적(compound)시키는 시스템 패턴으로, immutable한 소스 계층과 LLM이 관리하는 wiki 계층, 그리고 동작 규칙을 정의하는 schema 계층으로 구성되며, 새로운 문서가 들어올 때마다 요약·개념화·상호연결을 수행해 기존 지식을 업데이트하고 모순을 검출함으로써 “질문할 때마다 다시 찾는 RAG”가 아니라 “한 번 컴파일하고 계속 발전하는 지속적 지식 아티팩트”를 만든다는 점이 핵심이다.

ㅁ 포스트 목록 ≠ 지식 위키

먼저 구분해야 할 것이 있다.

포스트 목록은 글의 나열이다. 제목, 날짜, 카테고리로 정렬된 INDEX.md는 "어떤 글이 있는지"를 보여줄 뿐, "내가 무엇을 이해하고 있는지"는 보여주지 못한다.

지식 위키는 여러 글에서 추출한 개념을 재합성한 것이다. 예를 들어 "Kubernetes 네트워킹"이라는 개념 페이지는 Service, Ingress, CNI에 대한 8개 포스트를 읽고 합성한 결과물이다. 개별 글의 요약이 아니라, 글들 사이의 관계와 패턴을 정리한 것이다.

Karpathy는 이것을 3계층으로 설명한다:

Raw Sources (원본)  →  Wiki (합성 지식)  →  Schema (구조 규칙)

내 프로젝트에서는 이렇게 매핑했다:

Karpathy Layer	구현	역할
Raw Sources	posts/ (987개 md)	원본, 수정 안 함
Wiki	concepts/, entities/, moc/	LLM이 합성한 지식 페이지
Schema	SCHEMA.md	위키 구조·규칙

ㅁ 전체 아키텍처

ㅇ 파이프라인 6단계

987개 포스트를 위키로 변환하는 과정은 6단계이다:

Step 1. 카테고리 재정리

- 69개 카테고리를 12개 MOC(Map of Content)로 통합했다.

- LLM이 생성한 카테고리는 "DevOps", "CI/CD", "Infrastructure" 처럼 같은 주제를 다른 이름으로 분류하는 경우가 많았다.

- Python 스크립트(wiki_categorize.py)로 매핑 테이블을 만들어 일괄 정리했다.

Step 2. MOC 페이지 생성

- 12개 카테고리 각각에 대한 진입점 페이지를 자동 생성했다.

- MOC-DevOps, MOC-Kubernetes, MOC-LLM 등.

- 각 MOC에는 해당 카테고리의 포스트 목록과 상위 태그가 포함된다.

Step 3. 위키링크 삽입

- 987개 포스트 md 파일에 [[MOC-DevOps]], #kubernetes 같은 Obsidian 호환 링크를 자동 삽입했다.

Step 4. Concept/Entity 생성

- 이 단계가 핵심이다.

- Local LLM(qwen3:8b)이 MOC별 포스트 메타데이터를 읽고,
"이 글들의 공통 주제는 무엇인가?"를 추출하여 개념(Concept) 페이지와 기술(Entity) 페이지를 생성한다.

Step 5. 크로스링크

- 모든 페이지 간 [[]] 상호 참조를 보강하고, 위키 진입점(_index.md)을 생성한다.

Step 6. Obsidian 설정

- 그래프 뷰 색상 그룹, 커뮤니티 플러그인 설정 등.

ㅇ 위키 페이지 4계층

최종 산출물은 4가지 유형의 페이지로 구성된다:

유형	수량	역할	예시
MOC	12	카테고리 진입점	MOC-DevOps, MOC-Kubernetes
Concept	122	여러 포스트에서 합성한 지식	"CI/CD 파이프라인 설계", "컨테이너 네트워킹"
Entity	61	기술/도구 정의 + 사용 경험	Docker, Jenkins, Terraform
Post	987	블로그 원본	개별 블로그 글

ㅁ 토큰 절약 — Local LLM 하이브리드 전략

987개 포스트에서 개념을 추출하려면 LLM 호출이 대량으로 필요하다.

클라우드 API를 쓰면 비용이 많이 든다.

그래서 3계층 하네스(Harness) 구조를 설계했다.

Claude Main (Opus) ─── 오케스트레이터, 계획·평가만
    ├── Python 스크립트 ─── Steps 1-3, 5-6 (LLM 불필요)
    └── Local LLM (qwen3:8b) ─── Step 4 벌크 생성 (무료)
         └── Codex ─── confidence=low 건만 재생성 (제한적)

핵심 절약 전략: 요약 기반 생성

포스트 전문을 LLM에 넘기면 건당 평균 500자.

하지만 이미 요약·태그·키워드가 posts.jsonl에 있으므로, 이 메타데이터만 전달하면 건당 80자. 84% 토큰 절감이다.

포스트 전문 입력: 500자 × 8건 = 4,000자
요약+태그+키워드: 80자 × 8건 = 640자  → 84% 절감

qwen3:8b는 Ollama로 로컬에서 무료로 실행한다.

Codex는 품질이 낮은 건(confidence=low)에만 선별 사용했다.

ㅇ 대형 MOC 배치 분할

DevOps(147건), Kubernetes(142건), LLM(151건) 같은 대형 MOC는 한 번에 LLM에 넣으면 타임아웃이 발생했다.

60건씩 배치를 분할하여 해결했다.

MAX_POSTS_PER_BATCH = 60
batches = [posts[i:i + MAX_POSTS_PER_BATCH]
           for i in range(0, len(posts), MAX_POSTS_PER_BATCH)]

최종 결과: 122 Concepts + 61 Entities, Rubric 평가 183/183 (100%) PASS.

ㅁ 위키링크 정합성 — 발견과 교정

위키를 생성한 후 Obsidian에서 열어보니, 링크가 대량으로 깨져 있었다.

원인:
LLM이 관련 포스트를 [[722]] 같은 숫자 ID로 참조했는데,

실제 포스트 파일명은 0722-Linux-ssh-keygen-명령어를-사용하여-SSH-키를-생성.md였다.

Obsidian은 파일명(stem) 기준으로 링크를 해석하므로, [[722]]를 클릭하면 빈 파일이 생성되었다.

해결:

포스트 ID → 파일명 매핑 JSON을 생성하고, 정규식으로 815건의 숫자 링크를 일괄 교정했다.

# [[722]] → [[0722-Linux-ssh-keygen-명령어를-사용하여-SSH-키를-생성]]
new_content = re.sub(r"\[\[(\d+)\]\]", replacer, content)

두 번째 문제: 카테고리 오분류로 인한 무관한 참조.

SSO 글이 "프롬프트 엔지니어링" entity에 연결되어 있었다.

근본 원인은 posts.jsonl의 category 필드 자체가 오염된 것이었다.

LLM MOC 151건 중 41건(27.2%)이 오분류. 이를 키워드 기반으로 재분류하고,

MOC 교차 검증(wiki_validate_refs.py)으로 30건의 무효 참조를 자동 제거했다.

최종: 792/792 (100%) 참조 정합.

ㅁ Obsidian 그래프 뷰 - 지식의 시각화

위키의 최종 시각화는 Obsidian의 그래프 뷰다. 4색 그룹으로 계층을 구분했다:

빨강: MOC (카테고리 허브, 12개)
청록: Concept (개념 페이지, 122개)
주황: Entity (기술/도구, 61개)
회색: Post (블로그 원본, 987개)

처음에는 Post가 MOC에 직접 연결되어 있어서 계층 구조가 안 보였다.

Post → Concept 역링크를 삽입하고, concept가 있는 포스트에서는 MOC 직접 링크를 제거하여,

MOC → Concept → Post 3계층 구조가 그래프에서 시각적으로 드러나게 만들었다.

ㅁ 순환 파이프라인 — 살아있는 위키

Karpathy Wiki의 핵심은 "한 번 만들고 끝"이 아니라 지속적으로 유지보수되는 것이다.

새 블로그 글 작성 → 스크래핑 → 요약·태깅
    ↓
wiki/INDEX.md 업데이트 (블로그 인덱스)
wiki/posts/ 에 md 생성 (포스트)
wiki/concepts/ 업데이트 (위키)
    ↓
Obsidian에서 지식 갭 발견 → 새 블로그 글 작성 → 반복

증분 파이프라인(run_incremental.sh)이 매일 자동 실행되어, 새 글이 추가되면 인덱스와 위키가 함께 업데이트된다.

이 글 자체도 작성 후 위키에 반영될 것이다.

ㅁ 배운 것

LLM의 bookkeeping 능력

Karpathy가 말한 대로, LLM은 "읽기나 사고"보다 "정리 작업(bookkeeping)"에서 가장 큰 가치를 발휘한다. 987개 글에서 공통 주제를 추출하고, 크로스 링크를 만들고, frontmatter를 채우는 작업을 사람이 했다면 며칠이 걸렸을 것이다. Local LLM으로 30분 만에 끝났다.

품질 검증은 자동화해야 한다

LLM이 생성한 결과물을 그대로 쓰면 안 된다. 카테고리 오분류(27.2%), 위키링크 깨짐(815건), 무관한 참조(30건) — 모두 자동 검증 스크립트로 잡았다. Rubric 기반 평가 + MOC 교차 검증의 조합이 효과적이었다.

토큰 절약은 설계의 문제다

"모든 것을 LLM에 넣으면 된다"는 접근은 비용과 품질 모두에서 실패한다. 어떤 단계에 LLM이 필요한지, 입력을 얼마나 줄일 수 있는지, 어떤 LLM을 쓸지를 미리 설계해야 한다. 이 프로젝트에서는 6단계 중 1단계만 LLM을 사용하고, 입력을 84% 줄이는 것으로 비용을 최소화했다.

ㅁ 마무리

987개의 글은 내가 걸어온 길의 기록이다.

LLM Wiki는 그 기록을 시스템으로 전환한 결과물이다.

Karpathy의 통찰처럼, 지식 시스템을 유지하는 것은 "읽고 생각하는 것"이 아니라 "정리하는 것"이 어렵다. LLM이 그 정리를 맡으면, 인간은 읽고 생각하는 것에 집중할 수 있다.

"좋은 AI 결과는 모델이 아니라, 설계된 시스템에서 나온다."

ㅁ 함께 보면 좋은 사이트

Karpathy LLM Wiki: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
샘플 프롬프트 모음 — Claude Code 하네스 설계 실전 예시: https://peterica.tistory.com/1061
포트폴리오: https://peterica-website.vercel.app

ㅁ 사용 기술

Python (httpx, selectolax) — 스크래핑·파이프라인
Ollama + qwen3:8b — Local LLM 개념 생성
Obsidian — 지식 위키 시각화
Next.js 16 + react-force-graph-2d — 포트폴리오 그래프 뷰
Claude + Codex — 하네스 오케스트레이션

SSH에서 쿠버네티스로 — 하네스 엔지니어링이란 무엇인가

기록하는 백앤드개발자 — Fri, 10 Apr 2026 07:02:13 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

최근 LLM을 활용한 개발 방식을 정리하다가,

제가 프롬프트 엔지니어링과 하네스 엔지니어링을 같은 층위의 기술로 착각하고 있었다.

처음에 저는 하네스를 "프롬프트를 잘 쓰는 기술의 확장판" 정도로 봤다.

여러 LLM 호출을 연결해서 토큰을 줄이는 요령, 그 이상도 이하도 아니라고 생각했다.

그런데 실무 하네스를 뜯어보면서 이 생각이 완전히 뒤집혔다.

하네스는 프롬프트를 잘 쓰는 기술이 아니라, 프롬프트를 덜 쓰게 만드는 시스템 설계였다.

이 글은 개발자 관점에서 제가 왜 그렇게 생각이 바뀌었는지를 정리한 글이다.

핵심 질문은 하나이다.

"하네스 엔지니어링은 프롬프트 엔지니어링과 무엇이 본질적으로 다른가?"

ㅁ SSH와 쿠버네티스

비유 하나로 시작하면,

기존 프롬프트 방식은 SSH로 서버에 직접 들어가서 작업하는 것과 유사하다.

매번 사람이 전체 상태를 기억하고, 필요한 명령을 직접 입력하고, 결과를 직접 확인한다.

한 번의 접속 품질이 작업 전체의 품질을 결정한다.

반면 하네스는 쿠버네티스에 가깝다.

사용자는 "무엇을 할 것인가"를 선언하고, 상태는 시스템이 관리하며, 실행은 루프가 담당한다.

상태·루프·컨트롤러가 각각의 계층으로 분리되어 있다.

프롬프트 엔지니어링 = 한 번 잘 질문하기
하네스 엔지니어링 = 질문을 시스템으로 만들기

여기까지는 제가 처음에 가지고 있던 그림이었다.

그런데 실무 하네스를 하나씩 뜯어보니, 이 쿠버네티스 비유가 절반만 맞다는 사실이 드러났다.

ㅁ 상태는 하나가 아니라 계층입니다

첫 번째 전환점이었다.

저는 처음에 "하네스의 상태는 외부 저장소 하나에 두면 된다"고 생각했다.

쿠버네티스의 etcd 같은 이미지였다. 그런데 실무 하네스는 상태를 하나에 두지 않다.

삼중으로 계층화한다.

계층	저장 위치	역할
핫 상태	메모리 싱글턴	세션/비용/캐시, 즉시 접근
체크포인트	파일 / DB	재개·복구용 스냅샷
감사 로그	이벤트 스트림	재생·디버깅·패턴 분석

Claude Code는 부트스트랩 싱글턴(세션·비용·캐시)과 34줄짜리 UI 스토어를 분리하고, 루프가 돌 때마다 완전히 새로운 state 객체를 만들어낸다. 즉 상태를 "불변 스냅샷"으로 취급한다.
AutoGen은 save_state() 결과를 JSON으로 직렬화해 파일/DB에 저장하고, TTL·요약 정책으로 외부 저장소 비용을 제어한다.
Cursor는 초기에 "공유 파일"로 다중 에이전트를 조정하려다 락 경합과 데드락 때문에 이 방식을 폐기한다. 대신 타임스탬프 이벤트 로그에 모든 메시지·명령을 기록한다.

정리하면,

"파일 vs DB vs 메모리"는 이분법이 아니라 계층의 문제였다.

단독·단기 작업이면 파일만으로 충분하고, 멀티 에이전트·장기 작업으로 갈수록 DB와 이벤트 로그를 더한다.

ㅁ 루프는 자동 실행 흐름이다

두 번째 전환점이다.

저는 처음에 “작업을 여러 단계로 잘게 나누는 게 하네스의 본질”이라고 생각했다.

그런데 실제로 동작하는 구조를 보니, 본질은 분해가 아니었다.

핵심은 “언제 멈출지 정하고, 무한 반복하지 않게 제어하는 것”이었다.

참조: How the agent loop works

루프는 사람이 계속 프롬프트를 넣지 않아도, 작업을 이어서 실행해주는 구조이다. 대신 아무 조건 없이 돌리면 끝없이 토큰을 쓰게 되기 때문에, 반드시 종료 조건과 제한이 필요하다.

제가 이해한 루프는 이 정도이다.

언제 작업을 끝낼지 정한다
실패했을 때 다시 시도할지 결정한다
너무 많은 비용을 쓰지 않도록 제한한다

이 세 가지를 시스템이 대신 관리한다.

그래서 중요한 질문도 바뀌었다.

“얼마나 잘게 나눌까?“가 아니라,

- 각 단계가 실패해도 다시 시도할 수 있는가,
- 언제 멈출지 명확한가,
- 작업이 자동으로 이어질 수 있는가.

이 세 가지이다.

분해 단위는 이 조건을 만족하는 범위에서 가장 크게 잡는 게 맞다.

잘게 나눌수록 오히려 프롬프트 호출이 늘어나고, 토큰과 조정 비용이 더 커진다.

ㅁ Planner(기획)-Executor(실행)-Evaluator(평가)는 필수가 아닙니다

세 번째 전환점이다. 이게 가장 충격적이었다.

저는 "하네스라면 당연히 planner-executor-evaluator 3단 구조가 필요하다"고 생각했다.

그런데 업계는 이 질문에 반으로 갈라져 있었다.

LangGraph: Planner → Executor → Replan 노드 기본형. LLM 호출 수와 비용을 줄이고 전체 reasoning을 강제한다.
ReWOO / LLMCompiler: Planner가 DAG를 생성하고 Task Fetching Unit이 병렬 실행, Joiner가 결과를 심사해 재계획 여부를 결정한다. Evaluator가 내장된 3단 구조이다.
AutoGen: Planner Agent + AssistantAgent + UserProxy가 Plan → Act → Observe 루프를 구성한다.
CrewAI: Manager-Worker 모드로 계획 LLM과 실행 LLM을 분리하거나, Flows로 선언적 파이프라인을 구성한다.

여기까지만 보면 3단 구조가 정답처럼 보인다. 그런데 반대 극단이 존재한다.

SmolAgents: 1,000 라인 미만 미니멀 루프 + 코드 실행형 CodeAgent로 단일 에이전트 자율 루프를 지향한다.
OpenAI Swarm: Agent + handoff 함수만으로 경량 라우팅을 한다.
Cognition (Devin 개발사): "멀티 에이전트는 컨텍스트 손실·조정 실패가 잦으므로, 강한 단일 에이전트 + 컨텍스트 엔지니어링이 우선이다"라고 공개적으로 반대 입장을 폈다.
Anthropic: "단일 에이전트 → 스킬 증강 → 멀티 에이전트"로 점진적 확장을 권장한다.

정리하면 이렇다.

Planner-Executor-Evaluator 3단 구조는 기본이 아니다.

기본은 "강한 단일 에이전트 + 컨텍스트 엔지니어링"으로 시작하고, 관측·추적·비용이 문제가 될 때 planner-executor로 분리한다.

Evaluator는 "실패를 기록하고 재계획해야 할 때"만 추가한다.

"하네스 = 멀티 에이전트"는 제가 가지고 있던 잘못된 등식이었다.

ㅁ 마무리

세 가지 전환점을 다시 한 줄씩 정리하면 이렇다.

상태는 하나가 아니라 3계층이다 (핫 + 체크포인트 + 감사 로그).
루프는 분해가 아니라 종료 사유 ladder + 예산 수호자다.
3단 구조는 기본이 아니라, 단일 에이전트로 버티다가 필요할 때 꺼내는 카드다.

이 세 개를 관통하는 메시지는 하나이다.

하네스는 프롬프트를 잘 쓰는 기술이 아니라, 프롬프트를 덜 쓰게 만드는 시스템 설계이다.

토큰 절약은 목적이 아니라 결과이다.

상태를 계층화하면 매번 전체 컨텍스트를 주입할 필요가 없고,

루프가 종료 조건을 가지면 무한 재시도로 토큰을 태우지 않고,

단일 에이전트로 버티면 멀티 에이전트 조정 비용이 들지 않는다.

세 가지 모두 "프롬프트를 잘 쓰는 것"과는 다른 층위의 문제이다.

이 차이를 이해해야 LLM을 도구가 아니라 플랫폼처럼 사용할 수 있다고 본다.

프롬프트 엔지니어링이 SSH 명령어를 잘 치는 기술이라면,

하네스 엔지니어링은 명령어를 직접 치지 않아도 되는 선언적 시스템을 설계하는 기술이다.

마지막으로 한 가지 단서를 달아둔다.

이 글에서 언급한 claude-code-from-source.com은 역공학 기반의 비공식 자료이다.

공식 아키텍처 문서가 아니다.

ㅁ 함께 보면 좋은 사이트

[AI] Autoresearch 기반 지식 진화 시스템 정리

기록하는 백앤드개발자 — Thu, 9 Apr 2026 22:45:40 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

최근 AI를 활용한 개발을 하면서 한 가지 고민이 반복되었다.
“이걸 한 번 잘 만드는 게 아니라, 계속 더 잘하게 만들 수는 없을까?”

단순히 프롬프트를 잘 작성하거나, 좋은 모델을 선택하는 수준에서는
결과의 일관성과 운영 가능성을 확보하기 어렵다는 것을 느꼈다.

그러던 중 autoresearch 기반 접근을 접하게 되었고,
이 방식이 단순한 자동화가 아니라 지식을 계속 발전시키는 구조라는 점에서 인상적이었다.

특히 아래 자료들이 큰 참고가 되었다.

이 글에서는 위 내용을 기반으로
“자동으로 발전하는 시스템”이 무엇인지 정리하고,
실제 어떻게 적용할 수 있을지에 대해 정리해본다.

ㅁ 기존 방식의 한계

우리가 일반적으로 지식을 다루는 방식은 다음과 같다.

문서를 작성한다
사람이 판단한다
필요할 때 다시 참고한다

이 방식은 경험은 쌓이지만,
다음과 같은 문제가 있다.

결과가 반복되지 않는다
품질이 사람에 의존한다
개선이 구조화되지 않는다

즉, 지식이 쌓이긴 하지만 발전하지 않는다.

ㅁ 새로운 관점 — 지식은 “상태”다

autoresearch를 보면서 가장 크게 바뀐 관점은 이것이다.

지식은 문서가 아니라, 계속 개선되는 상태다

이 관점에서 지식은 다음과 같이 정의된다.

지식 = 평가 기준 + 현재 상태
지식은 반복을 통해 개선된다
지식은 고정된 것이 아니라 변화한다

ㅁ autoresearch의 핵심 구조

autoresearch의 구조는 매우 단순하다.

mutate → evaluate → select → repeat

mutate: 다양한 시도 생성
evaluate: 결과 평가
select: 좋은 결과 선택
repeat: 반복

이 구조는 진화 알고리즘과 유사하다.

중요한 점은 “한 번 잘 만드는 것”이 아니라
“반복을 통해 더 나아지는 것”이다.

ㅁ 시스템 구성 관점에서의 이해

이 구조를 시스템으로 보면 3가지 레이어로 나뉜다.

① 방법론 (autoresearch)

지식을 어떻게 발전시킬 것인가
반복 구조 정의

② 실행 엔진 (openclaw-autoresearch)

실제로 지식을 개선
SKILL.md + eval.json 기반 실행

③ 오케스트레이션 (oh-my-claudecode)

여러 작업을 동시에 수행
agent 기반 workflow 구성

이 세 가지가 결합되면
“지식을 자동으로 발전시키는 시스템”이 된다.

ㅁ 자동으로 발전하는 시스템이란?

정리하면 이런 구조다.

[문제 정의]
→ agent 실행
→ 반복 평가
→ 개선
→ 축적

여기서 중요한 포인트는 두 가지다.

평가 기준이 존재한다 (eval)
반복이 자동화되어 있다 (loop)

즉,

사람이 직접 개선하지 않아도 되고
시스템이 스스로 더 나아진다

ㅁ OSS 검증에 적용해보기

이 구조를 현재 하고 있는 OSS 검증에 적용해보면 의미가 명확해진다.

기존 방식:

사람이 license 확인
케이스마다 판단
경험에 의존

적용 방식:

ㅇSKILL.md

license 판단 로직 정의

ㅇ eval.json

정확도
risk 기준

ㅇ loop

다양한 케이스 반복
결과 비교
최적 로직 유지

결과적으로,

검증 로직이 점점 더 정교해진다

이건 단순 자동화가 아니라
검증 시스템 자체가 성장하는 구조다.

ㅁ 핵심 인사이트

이 구조를 이해하면서 얻은 가장 큰 인사이트는 이것이다.

측정할 수 있어야 개선된다
반복이 없으면 지식이 아니다
실패는 버리는 것이 아니라 데이터다
제약이 있어야 성능이 나온다

ㅁ 마무리

autoresearch는 단순한 도구가 아니라
지식을 다루는 방식 자체를 바꾸는 개념이다.

autoresearch → 방법론
openclaw → 실행 엔진
oh-my-claudecode → 운영 시스템

ㅁ 한 문장으로 정리

AI를 사용하는 것이 아니라
AI가 스스로 더 잘하게 되는 시스템을 만든다

AI를 잘 운영하는 개발자로 성장하기

기록하는 백앤드개발자 — Thu, 9 Apr 2026 16:36:58 +0900

[AI] Peterica의 AI공부와 비젼 정리

Backend + SRE 엔지니어가 AI 시스템의 운영 문제를 해결하는 과정

ㅁ 들어가며

요즘 모든 팀이 AI를 도입한다.
ChatGPT API를 붙이고, RAG를 만들고, Agent를 설계한다.

그런데 한 가지 빠져 있다.

"그걸 어떻게 운영할 건데?"

나는 Backend와 SRE를 해온 엔지니어다.
서비스를 만드는 것보다 돌아가게 만드는 것이 얼마나 어려운지 안다.
AI 시스템도 마찬가지다.

이 글은 내가 AI 시스템의 운영 문제를 어떻게 이해하고,
어떤 방식으로 해결하고 있는지를 정리한 글이다.

ㅁ AI 시스템은 왜 운영이 안 되는가

AI를 도입하면 네 가지 문제가 반복된다.

1. 결과가 매번 다르다

같은 질문을 해도 답이 다르다.
모델을 바꾸면 품질이 바뀐다.
프롬프트 한 줄이 달라지면 결과가 완전히 달라진다.

기존 소프트웨어에서는 있을 수 없는 일이다.
하지만 AI 시스템에서는 이것이 기본 상태다.

2. 틀려도 나아지지 않는다

RAG 시스템이 틀린 답을 했다.
사용자가 떠났다.
그리고 다음 날, 같은 질문에 같은 틀린 답을 한다.

실패가 수집되지 않고, 피드백 루프가 없기 때문이다.
시간이 지나도 품질이 그대로다.

3. 사람이 빠지면 멈춘다

검증을 사람이 한다.
판단 기준이 사람 머릿속에만 있다.
그 사람이 휴가를 가면 프로세스가 멈춘다.

AI를 도입했는데, 실행 구조는 여전히 수동이다.

4. 경험이 쌓이지 않는다

AI와 대화한 결과는 어디로 가는가?
대부분 사라진다.
같은 작업을 반복하고, 같은 실수를 반복한다.

경험이 시스템 자산이 되지 않는다.

ㅁ 나는 이걸 어떻게 풀고 있는가

나는 이 문제들을 Backend + SRE 관점에서 접근한다.
AI를 "도구"가 아니라 "운영해야 할 시스템"으로 본다.

비결정성 → 구조로 통제한다

AI 결과가 흔들리는 이유는 단순하다.

선택지가 너무 많기 때문이다.

해결: 입력을 구조화하고, 출력의 범위를 제한한다.
모델이 바뀌어도 결과가 같도록 시스템으로 통제한다.

이것이 Harness Engineering의 핵심이다.

좋은 AI 결과는 모델이 아니라, 설계된 시스템에서 나온다.

ㅁ 운영 부재 → 실패를 개선 루프로 연결한다

RAG 시스템이 틀린 답을 했으면,
그 실패는 다음 개선의 트리거가 되어야 한다.

나는 이런 구조를 설계했다:

질문 → 응답 → 실패 감지 → 지식 개선 → 재인덱싱 → 품질 향상

응답(rag-chat), 관찰(rag-monitor), 지식관리(rag-kms)를 분리하여
시간이 지날수록 품질이 좋아지는 RAG 시스템을 설계했다.

→ (구현 완료 후 링크 추가 예정)

ㅁ 자동화 부재 → Agent + Policy Gate

반복 검증을 사람이 하지 않아도 되는 구조.
Agent가 역할별로 분리되고, Policy Gate를 통과해야만 결과가 확정된다.

Evidence 없는 판단은 금지.
자동 확정도 금지.
구조가 판단하고, 사람은 검토한다.

ㅁ 지식 소멸 → 구조 기반 축적

AI와의 대화 결과가 사라지지 않도록,
컨텍스트를 파일 단위로 분리하고 구조화한다.

자유 텍스트가 아니라 섹션 기반 구조를 강제하여
누가 봐도 이해할 수 있는 형태로 지식을 축적한다.

→ (Context Note 완성 후 링크 추가 예정)

ㅁ 경력 경로: 왜 내가 이 문제를 푸는가

Backend Engineer (서비스 구조)
   ↓
DevOps (자동화, 파이프라인)
   ↓
SRE (안정성, 관측성, 장애 대응)
   ↓
AI Native Engineer (AI 시스템 설계 + 운영)

각 단계에서 배운 것이 다음 단계의 기반이 됐다.

Backend에서 서비스 구조 설계를 배웠다
DevOps에서 자동화와 파이프라인을 배웠다
SRE에서 안정성과 관측성을 배웠다

그리고 지금, 이 모든 경험이 AI 시스템을 운영 가능하게 만드는 문제로 수렴되고 있다.

ㅁ 프로젝트

프로젝트	해결하는 문제	상태
LLM System Lab	AI를 시스템으로 이해하기	완료, git, vercel
Harness Engineering	AI 출력의 비결정성 통제	블로그 발행 완료
RAG Platform	실패해도 개선되지 않는 RAG	설계 완료, 구현 중 → 구현 완료 (모니터링 + 지식 개선 루프)
ContextChat	RAG를 서비스로 제공하기	구현 완료 (멀티테넌트 + Citation 검증)
IntentFlow	LLM 의존 최소화 + 파이프라인 통제	구현 완료 (의도 정확도 87%), git
Context Note	지식이 축적되지 않는 문제	구현 완료 (구조 기반 위키), tistory, git

ㅁ 마치며

AI를 잘 쓰는 시대는 이미 왔다.
다음은 AI를 잘 운영하는 시대다.

나는 그 문제를 풀고 있다.

이 글은 프로젝트가 완성될 때마다 업데이트됩니다.
마지막 업데이트: 2026-04-05

sourcetree 커스텀액션 이용해서 인텔리제이 실행하기

기록하는 백앤드개발자 — Thu, 2 Apr 2026 12:29:53 +0900

ㅁ 들어가며

여러 프로젝트를 동시에 관리하다 보면
SourceTree에서 특정 프로젝트를 선택한 뒤 바로 IntelliJ로 열고 싶은 경우가 많다.
이 글에서는 SourceTree 커스텀 액션을 이용하여 선택한 repository를 IntelliJ로 바로 실행하는 방법을 정리한다.

ㅁ 커스텀 액션 추가 방법

ㅇ 커스텀 액션 > 편집으로 이동한다.

ㅇ 메뉴 설명에 원하는 이름을 적는다.

ㅇ 실행할 스트립트

/Applications/IntelliJ IDEA.app/Contents/MacOS/idea

ㅇ 인자는 $REPO

ㅁ 인텔리 실행

ㅇ 커스텀 액션 > 인텔리 실행을 클릭하면 해당 프로젝트를 볼 수 있다.

LLM은 언제 ‘기억’하는가 — RAG를 넘어서 D2L까지

기록하는 백앤드개발자 — Mon, 30 Mar 2026 12:49:09 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

Sakana AI의 Doc-to-LoRA(D2L) 프로젝트를 살펴보면서, 기존에 내가 익숙하게 사용하던 RAG 구조를 다시 생각하게 되었다.
문서를 검색해서 프롬프트에 붙이는 방식이 아니라, 문서를 모델 내부에 반영한다는 접근은 단순한 개선이 아니라 방향 자체가 다르게 느껴졌다.

특히 인상적이었던 점은,

이 방식이 DB의 옵티마이저처럼 “실행 전에 구조를 바꿔 효율을 높인다”는 점에서는 유사하지만,
결과적으로는 단순한 성능 개선이 아니라 결과 자체를 바꾼다는 점에서 전혀 다른 레벨의 기술이라는 것이었다.

이 글은 그 차이를 이해하기 위해 정리한 개인적인 학습 기록이다.

ㅁ 우리가 익숙한 방식 — RAG는 무엇을 하고 있는가

일반적인 LLM 시스템은 대부분 RAG 구조를 따른다.

질문 → 벡터DB 검색 → 관련 문서 선택 → 프롬프트에 삽입 → LLM 응답

이 구조의 핵심은 명확하다.

LLM은 아무것도 기억하지 않는다. 필요한 정보를 매번 외부에서 가져온다.

이 방식은 매우 실용적이다.

최신 데이터 반영 가능
근거 추적 가능
구현이 비교적 단순

하지만 한계도 분명하다.

retrieval 실패 → 잘못된 답변
context 길이 제한
프롬프트 길이 증가 → 비용/속도 문제

즉, RAG는 결국 “찾는 문제”를 해결하는 구조다.

ㅁ 질문의 전환 — “찾지 말고 기억하게 할 수 없을까?”

여기서 자연스럽게 다음 질문이 나온다.

“문서를 매번 찾지 말고, 모델이 직접 기억하게 만들 수는 없을까?”

이 질문에 대한 하나의 답이 바로 D2L이다.

ㅁ D2L의 핵심 — 문서를 ‘모델로 변환한다’

D2L의 구조를 단순화하면 다음과 같다.

문서 → LoRA weight 생성 → 모델에 주입 → 이후 응답 변화

조금 더 정확히 표현하면:

문서를 입력하면, 그 문서에 맞는 LoRA(weight 변화)를 생성하여
모델을 즉석에서 튜닝한다.

이때 중요한 점은 다음이다.

학습(training)이 아니다
gradient descent가 없다
데이터셋이 필요 없다

“문서를 학습하는 것이 아니라, 문서를 모델 구조로 변환한다”

ㅁ 오해하기 쉬운 부분 — 캐시나 DB가 아니다

처음 보면 D2L은 캐시처럼 보인다.

문서를 넣고
이후에 영향을 준다

하지만 실제로는 완전히 다르다.

RAG / Vector DB

저장 → 검색 → 가져오기

Redis

key → value 조회

D2L

문서 → 모델 weight 변경 → 생성 방식 변화

정보를 꺼내는 구조가 아니라
모델의 해석 방식 자체를 바꾼다

ㅁ DB 옵티마이저와의 비교 — 비슷하지만 결정적으로 다르다

이 지점에서 DB 옵티마이저와의 유사성이 떠올랐다.

ㅇ 공통점

실행 전에 구조를 바꾼다
중간 결과(LoRA / execution plan)를 만든다
성능 향상을 목표로 한다

하지만 결정적인 차이가 있다.

ㅇ DB 옵티마이저

데이터를 더 빠르게 읽기 위한 실행 전략

결과는 동일해야 함
연산 순서만 바뀜

ㅇ D2L

모델 자체를 바꿔 결과를 바꾸는 방식

attention 구조 변화
표현 방식 변화
결과 자체가 달라질 수 있음

정리하면:

옵티마이저는 “길을 바꾸는 것”이고
D2L은 “생각하는 방식을 바꾸는 것”이다

ㅁ “세션 기반 LLM 튜닝”이라는 관점

D2L을 가장 직관적으로 표현하면 다음과 같다.

세션 단위로 LLM을 튜닝하는 방식

코드에서도 이 특징이 드러난다.

model.internalize(doc)  # 적용
model.reset()           # 원복

즉,

필요할 때 모델을 바꾸고
필요 없으면 원래 상태로 돌아간다

이는 기존 Fine-tuning과는 완전히 다르다.

구분	Fine-tuning	D2L
방식	학습	변환
지속성	영구	일시적
비용	높음	낮음
속도	느림	즉시

ㅁ 왜 이 방식이 중요한가

LLM을 “고정된 모델”이 아니라
상황에 따라 변하는 시스템으로 만든다

RAG → 외부 기억
Fine-tuning → 장기 기억
D2L → 단기/즉시 기억

이라는 구조가 된다.

ㅁ 실무 관점 — 대체가 아니라 조합

중요한 점은 D2L이 RAG를 대체하지 않는다는 것이다.

역할이 다르다.

RAG → 찾는 문제 (recall)
D2L → 이해하는 문제 (interpretation)

현실적인 구조는 다음과 같다.

RAG → 전체 정보 탐색
D2L → 핵심 문서 내부화
Fine-tuning → 기본 능력 강화

예를 들어:

LICENSE 원문 → RAG로 확보
LICENSE 해석 → D2L로 강화

ㅁ 개인적인 정리

이번에 D2L을 보면서 가장 크게 느낀 점은 이것이다.

LLM의 발전은 “더 큰 모델”이 아니라
“모델을 어떻게 다루느냐”의 문제로 이동하고 있다

그리고 D2L은 그 흐름에서 중요한 신호처럼 보인다.

아직은 연구 단계에 가깝지만,
Agent, Memory, Personalization 영역에서는
굉장히 큰 변화를 만들 가능성이 있다.

ㅁ 마무리

RAG는 “문서를 찾아서 읽는 방식”이고
D2L은 “문서를 읽고 모델을 바꾸는 방식”이다

하네스는 모델을 보완하는 게 아니라, 시스템을 설계하는 일이다

기록하는 백앤드개발자 — Sun, 29 Mar 2026 12:48:12 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

ㅇ 최근 Anthropic의 “Harness design for long-running application development” 글을 읽었다.

하네스 엔지니어링을 공부하는 입장에서 꽤 인상적인 글이었다.

단순히 “에이전트를 잘 만드는 방법”이 아니라,
모델의 한계를 어떻게 시스템적으로 다루는가에 대한 이야기였기 때문이다.

ㅁ 문제: 모델은 생각보다 쉽게 무너진다

글에서 가장 공감된 부분은 이거다.

긴 작업에서 모델은 결국 망가진다

컨텍스트가 길어지면 일관성이 깨진다
스스로 평가하면 항상 “잘했다”고 한다
복잡한 작업에서는 중간에 방향을 잃는다

이건 내가 직접 실험하면서도 느꼈던 부분이다.

특히 “self-evaluation 문제”는 명확했다.
모델은 절대 자기 작업을 제대로 비판하지 않는다.

여기서 중요한 포인트는 하나였다.

❗ 문제는 모델이 아니라 구조다

ㅁ 구조: 하네스는 역할 분리다

이 글에서 제시한 핵심 구조는 단순하다.

Planner
Generator
Evaluator

이건 그냥 멀티 에이전트 구조가 아니다.
“책임을 분리한 구조”다.

Generator

→ 실제로 무언가를 만든다

Evaluator

→ 만든 것을 깨려고 한다

Planner

→ 방향을 정의한다

여기서 중요한 건

Generator는 절대 판단하지 않는다
Evaluator는 절대 만들지 않는다

이 분리가 만들어내는 효과는 명확하다.

self-bias 제거
반복 개선 루프 생성
품질 기준 명확화

이걸 보고 느낀 건 하나였다.

하네스는 “프롬프트 기술”이 아니라
조직 구조 설계에 가깝다

ㅁ 핵심 인사이트: 좋은 기준이 없으면 개선도 없다

프론트엔드 디자인 실험 부분이 특히 흥미로웠다.

“이 디자인이 좋은가?”
→ 모델은 답을 못 한다

그래서 기준을 이렇게 바꾼다.

Design quality
Originality
Craft
Functionality

즉,
추상적 질문 → 측정 가능한 기준으로 변환

이건 하네스 설계에서 굉장히 중요한 포인트다.

모델은 생각하지 않는다
모델은 “기준에 맞춰 반응”한다

결국 성능을 끌어올리는 핵심은

좋은 프롬프트가 아니라
좋은 평가 기준이다

ㅁ 또 하나의 핵심: Context Reset vs Compaction

이 글에서 기술적으로 가장 인상 깊었던 부분은 이거다.

Compaction → 요약해서 이어가기
Reset → 아예 새로 시작 + 상태 전달

결론은 명확했다.

Reset이 더 강력하다

이건 꽤 반직관적이다.
보통은 “연속성 유지”가 좋다고 생각하니까.

하지만 실제로는

context 불안 제거
오염된 상태 초기화
더 안정적인 장기 실행

이걸 보면서 느낀 건

하네스는 “메모리를 유지하는 기술”이 아니라
언제 버릴지 결정하는 기술이다

ㅁ 실무 관점에서의 깨달음

이 글을 읽고 내 생각이 바뀐 부분은 명확하다.

❌ 기존 생각

프롬프트를 잘 짜면 된다
모델이 좋아지면 해결된다

✅ 바뀐 생각

구조가 없으면 무조건 망한다
모델은 구조 안에서만 성능이 나온다

그리고 가장 중요한 한 줄:

하네스는 모델을 보완하는 게 아니라
모델을 “일하게 만드는 환경”이다

ㅁ 마무리

이 글을 읽고 느낀 건 단순하다.

앞으로 중요한 건
“모델을 어떻게 쓰느냐”가 아니라 “어떤 구조로 일하게 하느냐”다

하네스 엔지니어링은 아직 초기 단계지만, 확실히 다음 단계의 개발 방식이라는 느낌이 든다.

AI를 다루는 방법의 진화(Prompt → Context → Harness → AIOps)

기록하는 백앤드개발자 — Wed, 25 Mar 2026 16:36:26 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

AI를 활용하는 방식은 단순한 “질문”에서 시작했지만,
점점 더 구조화되고, 시스템화되고, 운영 자동화 단계로 진화하고 있다.

이 문서는 AI를 다루는 방식을
4단계 진화 구조로 정리한다.

ㅁ 전체 구조

Prompt → Context → Harness → AIOps
= 요청 → 이해 → 검증 → 운영

ㅁ Prompt Engineering

“AI에게 잘 말하는 단계”

핵심: 질문, 지시문, 포맷 설계
목표: 원하는 출력 유도
특징:
- 문장 구조에 의존
- 결과 변동성 큼

한 줄 정의
→ “좋은 답을 얻기 위해 잘 묻는 기술”

ㅁ Context Engineering

“AI가 이해할 수밖에 없는 상태를 만드는 단계”

핵심: 정보, 역할, 히스토리, 환경 구성
목표: 일관된 이해 기반 제공
구성 요소:
- Memory (대화/지식)
- Role (페르소나)
- Data (문서, RAG)
- Environment (상태)

한 줄 정의
→ “AI의 사고 환경을 설계하는 기술”

ㅁ Harness Engineering

“결과를 통제하고 검증하는 단계”

핵심: 평가, 테스트, 기준 정의
목표: 모델이 달라도 동일한 결과 확보
구성 요소:
- Test Case
- Evaluation Metric
- Feedback Loop

한 줄 정의
→ “결과의 품질을 보장하는 시스템”

ㅁ AIOps

“AI가 시스템을 운영하는 단계”

핵심: 자동화, 모니터링, 대응
목표: 지속적인 운영 최적화
수행 역할:
- 이상 탐지
- 자동 대응
- 성능 최적화

한 줄 정의
→ “AI가 시스템을 계속 굴리게 만드는 것”

ㅁ 단계별 차이 요약

단계	초점	역할
Prompt	입력	말하기
Context	이해	환경 설계
Harness	품질	검증/통제
AIOps	운영	자동 실행

ㅁ 구조적 해석

이 4단계는 단순 기술 구분이 아니라
AI 시스템 성숙도의 단계이다.

Prompt: 개인 사용 수준
Context: 시스템 설계 시작
Harness: 제품/서비스 수준
AIOps: 운영 시스템 수준

ㅁ 마무리

AI 활용은 더 이상 “잘 물어보기”에 머무르지 않는다.

결국 핵심은 "AI를 어떻게 통제하고, 어떻게 운영할 것인가"이다.

이 흐름을 이해하면
단순 활용자에서 → AI 시스템 설계자로 전환할 수 있다.

AI를 잘 쓰는 게 아니라, AI를 통제해야 한다 — Harness Engineering 정리

기록하는 백앤드개발자 — Wed, 25 Mar 2026 08:24:53 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

요즘 AI를 활용한 개발 이야기를 들으면 늘 비슷한 고민으로 돌아온다.
“어떤 모델을 써야 더 잘 나오지?”

하지만 한 영상을 보고 나서 이 질문 자체가 틀렸을 수 있다는 생각이 들었다.
문제는 모델이 아니라, 결과를 만드는 방식에 있었다.

ㅁ 왜 AI는 항상 들쭉날쭉할까

Claude를 쓰다가 Codex를 쓰고, 다시 Gemini를 쓰면
같은 요구사항인데도 결과는 매번 달라진다.

어떤 날은 구조가 깔끔하고
어떤 날은 naming이 엉망이고
어떤 날은 아예 설계가 틀어진다

그래서 우리는 보통 이렇게 생각한다.

“더 좋은 모델을 써야겠다”

하지만 Harness Engineering은 정반대의 이야기를 한다.

“AI는 믿을 수 없다. 대신 시스템으로 통제해야 한다.”

ㅁ 본질 — Harness Engineering이란 무엇인가

Harness Engineering은 단순한 프롬프트 기법이 아니다.
AI를 잘 사용하는 방법이 아니라, AI가 원하는 방식으로 출력하도록 만드는 구조 설계 방법론이다.

핵심은 하나다.

모델이 바뀌어도 결과는 같아야 한다

이를 위해 다음을 통제한다:

문서 구조
설계 방식
코드 규칙
평가 기준

즉, AI를 도구로 쓰는 것이 아니라
규격화된 생산 시스템 안에 넣는 것이다.

ㅁ 구조적 해석 — CPS + 개발 파이프라인

이 방식의 중심에는 CPS 프레임워크가 있다.

Context: 지금 상황은 무엇인가
Problem: 해결해야 할 문제는 무엇인가
Solution: 어떻게 풀 것인가

이건 단순 문서가 아니라
팀의 사고 방식 자체를 정렬하는 도구다.

이 CPS는 개발 전체 흐름으로 이어진다:

요구사항 입력 (비정형 가능)
회의 및 로그 정리
CPS 구조화
PRD 및 설계 문서 생성
코드 생성 + 린터 적용
평가(Evaluation)

여기서 중요한 포인트는 하나다.

코드가 아니라, 프로세스를 통제한다

ㅁ 핵심 메커니즘 — “선택지를 제거한다”

AI 결과가 흔들리는 이유는 단순하다.

naming이 다르고
파일 구조가 다르고
코드 스타일이 다르기 때문이다

Harness Engineering은 이를 이렇게 해결한다.

린터로 강제한다

파일명 규칙 고정
import 순서 고정
구조 패턴 고정

결과적으로,

AI가 선택할 수 있는 경우의 수가 줄어들고
출력은 점점 하나로 수렴한다

이건 중요한 관점이다.

좋은 결과는 생성하는 것이 아니라, 제한해서 만든다

ㅁ 시스템 관점 — Evaluation이 핵심이다

AI의 결과는 항상 불확실하다.
그래서 Harness Engineering에서는 “평가”가 핵심이 된다.

평가 기준 예시:

문맥 적합성
정확성
데이터 근거
누락 여부

하지만 더 중요한 건 이것이다.

평가 기준은 조직마다 달라야 한다

어떤 조직은 정확성이 우선이고
어떤 조직은 속도가 우선이다

즉, AI 품질은 모델이 아니라
조직이 정의한 기준으로 결정된다

ㅁ 운영 관점 — 왜 이 방식이 중요한가

이 접근은 특히 조직 단위에서 강력하다.

장점:

유지보수 용이
협업 효율 증가
모델 교체에도 안정성 유지
엔터프라이즈 환경에 적합

단점:

초기 설계 비용 큼
유연성 감소
AI 입장에서는 비효율적

하지만 실제 개발에서는 명확하다.

유연성보다 일관성이 더 중요하다

ㅁ 정리 — AI 시대의 개발 패러다임 변화

우리는 지금까지 이렇게 생각해왔다.

좋은 프롬프트를 만들면 된다
좋은 모델을 쓰면 된다

하지만 이제는 바뀌어야 한다.

프롬프트 중심 → X
모델 중심 → X
시스템 중심 → O

결국 핵심은 이것이다.

좋은 AI 결과는 모델이 아니라, 설계된 시스템에서 나온다

Context Note — 컨텍스트를 “쌓지 않고 구조화”하는 새로운 방식

기록하는 백앤드개발자 — Mon, 23 Mar 2026 22:44:35 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

LLM과 협업을 하다 보면 공통적인 문제가 발생한다.
대화가 길어질수록 컨텍스트는 계속 누적되고, 결국 핵심 의사결정이 희석된다.

이 문제를 해결하기 위해 만든 프로젝트가 Context Note다.

Context Note는 파일 트리 구조로 컨텍스트를 분리하고, 구조화된 에디터로 의사결정 중심 문서를 작성한다.

빠르게 PRD를 구성하고 MD파일로 저장된 문서는 바로 사용가능한 docs 형태가 된다.

ㅁ 왜 필요한가

일반적인 노트 시스템(Notion, Obsidian 등)은 정보를 “쌓는 구조”다.
하지만 실제 개발이나 의사결정은 “구조화된 컨텍스트 관리”가 핵심이다.

특히 LLM 기반 작업에서는 다음 문제가 반복된다:

컨텍스트가 길어질수록 품질 저하
중요한 의사결정이 묻힌다
실행 가능한 형태로 정리되지 않음

GTP와 Claude의 CoWorking

나의 경우, GPT가 기획자 역할을 수행하고, Claude가 개발을 진행한다.

GPT에서 요구사항을 정리하여 이름 PRD로 구성하고,
Claude는 이를 점검하여 Agentic Workflow로 개발 POC를 진행한다.

PRD를 수립할 때에 에디터를 이용하면
선택된 텍스트 구조로 대화를 이어가고 보충 및 수정이 편리하였다.

ㅁ Context Note의 접근 방식

Context Note는 단순한 노트 앱이 아니다.
“컨텍스트를 구조로 관리하는 시스템”이다.

핵심 개념은 다음과 같다:

File Tree = Context Structure
→ 주제별로 컨텍스트를 분리하여 관리
Structured Editor
→ 자유 서술이 아닌, 구조 기반 작성
Template Injection
→ Problem / Design / Dev / Test / Decision / Next 자동 생성
Decision Required
→ 모든 문서는 반드시 “결정”을 포함해야 함

ㅁStructured Editor

슬래시 메뉴(/)로 Heading, List, Code Block 등 블록을 빠르게 삽입합니다. Toolbar에서 Init Template 버튼으로 기본 섹션 구조를 자동 생성할 수 있습니다.

ㅁ Preview Mode

Editor / Preview 탭 전환으로 렌더링된 문서를 확인합니다. 파일 트리에서 문서 구조를 한눈에 파악할 수 있습니다.

ㅁ 기존 노트와의 차이

항목	기존 노트	Context Note
구조	자유 서술	구조 강제
목적	기록	의사결정
컨텍스트	누적	분리
결과	읽기	실행

ㅁ 기술 스택

Next.js (App Router, TypeScript)
TipTap Editor (WYSIWYG)
Zustand (State)
Tailwind CSS
Docker 기반 실행

로컬에서 바로 실행 가능:

docker compose up -d

ㅁ 핵심 인사이트

LLM 시대에는 “잘 쓰는 것”보다
컨텍스트를 어떻게 구조화하느냐가 더 중요하다.

Context Note는 이 지점을 해결하려는 시도다.

ㅁ 마무리

이 프로젝트는 아직 초기 단계지만,
다음과 같은 방향으로 확장할 수 있다:

LLM Agent와 직접 연결
Context 기반 자동 실행
Decision tracking 시스템

GitHub: https://github.com/peterica/context-note

컨텍스트를 “쌓지 말고 구조화”해보자.

[AI] AI Agent 시대, Garbage Context를 줄이는 방법 - Claude /compact를 포함한 Context Engineering 전략

기록하는 백앤드개발자 — Wed, 18 Mar 2026 22:15:33 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

오늘 한 크루와 컨텍스트 낭비와 토큰 부족에 관해 이야기를 나누면서 정리한 글이다.

LLM을 쓰다 보면 초반에는 정확하던 답변이 점점 흐려지고, 결과는 길어지지만 핵심은 사라진다.

이 현상의 본질은 모델 성능 문제가 아니라, 컨텍스트 오염(Context Pollution)이다.

Agentic 코딩에서는 이 문제가 더 치명적이다.
왜냐하면 LLM은 단순 답변이 아니라 “상태를 기반으로 행동하는 실행 주체”이기 때문이다.

AI agentic 코딩에서는 모델이 “추론”이 아니라 “구조를 따라 실행”하도록 만드는 것이 핵심이다. 이때 SSOT, MECE, DoD는 단순한 문서 원칙이 아니라, 에이전트가 안정적으로 동작하기 위한 제어 장치(control layer) 역할을 한다.

ㅁ 왜 Garbage Context가 문제인가

LLM은 입력된 컨텍스트를 “진실”로 간주한다.
문제는 이 컨텍스트가 다음과 같이 구성된다는 점이다.

- 이전 대화의 잔여 정보

- 이미 해결된 문제의 흔적

- 서로 충돌하는 지시사항

- 중복된 설명과 불필요한 장문

이 상태가 되면 모델은:

- 무엇이 최신 정보인지 판단해야 하고

- 무엇이 중요한지 추론해야 하며

- 모순을 스스로 해결하려 한다

불필요한 추론 비용이 증가하고 정확도는 감소한다.

ㅁ /compact의 의미: 단순 요약이 아니다

Claude의 /compact는 단순한 요약 기능이 아니다.

이 기능의 본질은 다음과 같다:

- 기존 대화 → 핵심 상태만 남김

- 불필요한 토큰 제거

- 현재 작업에 필요한 정보만 유지

/compact는 “대화를 줄이는 기능”이 아니라 “작업 상태를 재정의하는 기능"이다.

ㅁ 구조적으로 보면: Context Engineering 문제

Garbage Context 문제는 도구가 아니라 구조의 문제다.

ㅇ 상태(State)와 기록(Log)을 분리해야 한다

많은 경우 대화는 다음을 혼합한다:

- 현재 상태 (해야 할 일)

- 과거 기록 (왜 이렇게 되었는가)

Agent에게 필요한 것은 대부분 상태(State)이다.

그래서 대화 전체를 유지하지 말고 현재 상태만 재정의해야 한다

/compact는 이 작업을 자동으로 해준다.

ㅁ SSOT (Single Source of Truth)의 필요성

에이전트는 동일한 정보를 여러 곳에서 참조할 때 쉽게 충돌한다.
특히 LLM 기반 시스템에서는 다음 문제가 발생한다.

- 프롬프트 vs 코드 vs 문서 간 불일치

- 여러 agent가 서로 다른 상태를 기준으로 판단

- “그럴듯한 잘못된 판단(hallucination)” 증가

- 컨텍스트를 계속 누적하는 방식 → 실패

SSOT가 없으면 에이전트는 결정을 “추론”으로 메꾼다.

SSOT 기반으로 컨텍스트를 재구성해야 한다

- 기준 문서를 중심으로 재로딩 → 안정

- 모든 판단 기준 → 한 곳에서만 정의

- agent는 추론이 아니라 lookup + execution

- 변경 시 영향 범위 명확 (diff 기반 운영 가능)

예:

- CLAUDE.md

- PRD.md

- task_flow.md

이 문서들이 컨텍스트의 “기준점”이 된다.

→ 대화는 참고, 문서는 기준

ㅁ MECE (Mutually Exclusive, Collectively Exhaustive)의 필요성

MECE는 상호 배타적이면서(중복 없이), 전체 포괄적인(누락 없이) 상태를 의미합니다.

에이전트는 “경계가 모호한 문제”를 가장 어려워한다.

MECE가 없는 경우:
- 동일 작업을 여러 agent가 중복 수행
- 책임 경계 불명확 → 무한 루프/충돌 발생
- 누락 케이스 발생 (특히 edge case)

- 작업이 섞여 있을수록 컨텍스트는 길어진다.

ㄴ 분석 + 설계 + 구현 + 리뷰가 한 대화에 존재
ㄴ 서로 다른 레벨의 정보가 혼재

예를 들면,

“검증”이라는 작업이 → 라이선스 검증 / 코드 origin 검증 / 보안 검증이 섞여 있음

MECE = agent 분업을 가능하게 하는 최소 단위 분해 구조

MECE하게 쪼개야 컨텍스트가 줄어든다.

MECE 적용 시:

- task 단위로 분리

- agent 역할 분리

- 작업 단위가 분해됨

- 각 agent 역할이 명확해짐

- orchestration 가능

이러면 각 컨텍스트는 자연스럽게 작아진다.

ㅁ DoD (Definition of Done)의 필요성

에이전트에게 가장 위험한 상태는 “끝났다고 착각하는 것”이다.

ㅇ DoD가 없으면:
- agent가 중간 결과를 완료로 판단
- 품질 기준 없이 결과 생성
- 재현 불가능 (same input → different output)

ㅇ DoD가 없으면 컨텍스트는 계속 쌓인다

완료 기준이 없으면 대화는 끝나지 않는다.

- “조금 더 수정”

- “이 부분만 다시”

- “이것도 추가”

이 반복이 Garbage Context의 주요 원인이다.

ㅇ DoD를 정의하면:
- 완료 조건이 명시됨 (ex: 테스트 통과, 근거 URL 존재, diff 생성 등)
- 결과 검증이 자동화 가능
- self-check / evaluator agent 설계 가능

DoD를 두면 완료 시점이 명확해지고 새로운 컨텍스트로 전환 가능하다.

DoD = 결과를 ‘판단’이 아닌 ‘검증 가능한 상태’로 만드는 기준이 된다.

ㅁ 실무 적용 패턴 (나의 구조 기준)

ㅇ 세 가지는 개별 개념이 아니라 하나의 구조로 동작한다.
- SSOT → “무엇을 기준으로 판단할 것인가”
- MECE → “누가 무엇을 할 것인가”
- DoD → “언제 끝났다고 볼 것인가”

ㅇ 그래서 내가 만드는 구조는 다음과 같다.

- SSOT → [docs] (architecture, policy, standard)
- MECE → [command] (역할 단위 실행 명령)
- DoD → 각 command의 완료 조건 + 검증 기준

나의 Vibe Coding 흐름은 다음과 같다.

실행 전
→ SSOT 문서 로딩 (docs 기반)

작업 수행
→ 필요한 최소 컨텍스트만 유지

일정 단위 종료
→ /compact 수행

결과 저장
→ 로그는 외부에 기록 (Git, MD)

다음 작업
→ 새로운 상태로 시작

ㅁ 핵심 운영 원칙

정리하면 다음 네 가지로 수렴된다.

- 컨텍스트는 누적하지 말고 재구성한다

- 대화보다 문서를 기준으로 삼는다

- 작업은 작게 나눈다 (MECE)

- 완료되면 끊고 리셋한다 (DoD + compact)

ㅁ Context Engineering은 AI 튜닝이다: DB 최적화 관점에서

나는 AI에게 프롬프트를 주는 일을 단순 질의가 아니라, 일종의 실행 계획 설계라고 본다.
MySQL이 옵티마이저를 통해 최적의 plan을 만들고,

필요하면 중간 결과를 임시 테이블이나 집계 구조로 정리해 성능을 높이듯,

AI Agent 기반 Vibe Coding에서도 agent와 skill을 적절히 분리하고 각 단계에 필요한 컨텍스트만 공급해야 한다.

AI Agent 환경에서도 전체 대화를 계속 누적시키는 대신, 현재 작업에 필요한 상태만 재구성해 넘기는 것이 유사한 역할을 한다. 즉, /compact, SSOT 문서, task별 분리, role별 agent 설계는 AI 쪽의 실행 계획 최적화라고 볼 수 있다.

결국 Context Engineering은 프롬프트를 잘 쓰는 기술이 아니라,

AI 활용 성능을 높이기 위한 구조적 튜닝 작업입니다.
고급 AI Native 개발자로 성장하기 위해서는 컨텍스트에 대한 구조적 튜닝에 대해 공부가 필요하다.

ㅁ 마무리

LLM을 잘 쓰는 사람과 아닌 사람의 차이는 프롬프트가 아니라 컨텍스트 관리 능력이다.

특히 Agentic 환경에서는 더 명확하다. 컨텍스트를 관리하지 않으면 모델이 아니라 “잡음”이 동작한다.

SSOT, MECE, DoD는 AI agent가 ‘생각하는 존재’가 아니라
‘예측 가능한 실행 시스템’으로 동작하게 만드는 최소 조건이다.

좋은 AI 시스템은 더 많이 넣는 것이 아니라, 덜 남기는 시스템이다.

그리고 /compact는 단순한 기능이 아니라 그 철학을 구현하는 하나의 인터페이스다.

[Linux] 운영체제마다 다른 시작 프로그램 관리 방식

기록하는 백앤드개발자 — Wed, 18 Mar 2026 06:40:30 +0900

ㅁ 들어가며

서버를 운영하다 보면 서비스를 시스템 시작과 함께 자동으로 실행해야 하는 경우가 많다.
웹 서버, 모니터링 에이전트, 메시지 큐, 데이터베이스 등 대부분의 인프라 서비스는

부팅과 동시에 올라와야 하기 때문이다.

흥미로운 점은 운영체제마다 시작 프로그램을 관리하는 방식과 명령어가 전부 다르다는 것이다.

Linux에서는 systemd를 사용하고,

macOS는 launchd,

Windows는 Service Manager를 사용한다.

이번 글에서는 운영체제별 시작 프로그램 관리 구조와 명령어의 차이를 정리하였다.

ㅁ 왜 운영체제마다 서비스 관리 방식이 다른가

운영체제가 부팅될 때 가장 먼저 실행되는 프로그램을 init 시스템이라고 한다.

이 init 시스템의 역할은 다음과 같다.

시스템 초기화
서비스 실행
프로세스 관리
시스템 상태 유지

운영체제마다 이 init 시스템을 구현하는 방식이 달라지면서
서비스 관리 방법도 자연스럽게 달라졌다.

대표적인 서비스 관리 시스템은 다음과 같다.

운영체제	서비스 관리 시스템
Linux	systemd
macOS	launchd
Windows	Service Control Manager

ㅁ Linux의 서비스 관리 : systemd

현재 대부분의 Linux 배포판(Ubuntu, Debian, CentOS, RHEL 등)은 systemd를 사용한다.

systemd는 서비스 관리 플랫폼에 가까운 구조를 가지고 있다.

서비스는 Unit 파일이라는 설정 파일로 정의된다.

/etc/systemd/system/my-service.service

서비스 관리는 systemctl 명령어로 수행한다.

대표적인 명령어

systemctl start nginx
systemctl stop nginx
systemctl restart nginx
systemctl enable nginx
systemctl status nginx

여기서 중요한 특징은 systemd가 의존성 기반 서비스 실행 구조를 가진다는 점이다.

ㅁ macOS의 서비스 관리 : launchd

macOS는 launchd라는 시스템을 사용한다.

Linux의 systemd와 유사한 역할을 하지만 구조적으로는 이벤트 기반 서비스 실행 모델에 가깝다.

서비스 설정은 plist 파일로 정의된다.

/Library/LaunchDaemons
~/Library/LaunchAgents

관리 명령어는 launchctl이다.

launchctl load service.plist
launchctl unload service.plist
launchctl start service
launchctl stop service
launchctl list

macOS의 특징은 다음과 같다.

사용자 서비스와 시스템 서비스를 분리
이벤트 기반 실행
로그인 기반 서비스 실행

즉 Linux처럼 서버 서비스 중심 구조라기보다는 데스크톱 환경 중심 구조다.

ㅁ 운영체제별 서비스 관리 구조 비교

OS	서비스 시스템	설정 방식	관리 명령
Linux	systemd	unit 파일	systemctl
macOS	launchd	plist 파일	launchctl
Windows	SCM	registry / service DB	sc, net

겉으로 보면 단순히 명령어 차이처럼 보이지만
사실은 운영체제 철학의 차이가 반영된 결과다.

ㅁ 인프라 운영 관점에서 보는 차이

실제 인프라 환경에서는 다음과 같은 특징이 나타난다.

Linux

서버 인프라 표준
systemd 기반 서비스 운영

macOS

개발 환경 중심
사용자 세션 기반 서비스

Windows

기업 애플리케이션 서비스 중심

특히 클라우드 서버, Docker, Kubernetes 환경에서는 Linux + systemd 구조가 사실상 표준이다.

그래서 DevOps나 SRE 업무를 하다 보면
결국 systemctl 명령어를 가장 많이 사용하게 된다.

ㅁ 마무리

운영체제마다 시작 프로그램 관리 방식이 다른 이유는
단순히 명령어 차이가 아니라 시스템 아키텍처 차이 때문이다.

Linux → 의존성 기반 서비스 그래프 (systemd)
macOS → 이벤트 기반 실행 (launchd)
Windows → 서비스 관리자 구조 (SCM)

이 차이를 이해하면 새로운 운영체제를 접하더라도
서비스가 어떻게 시작되고 관리되는지 구조적으로 이해할 수 있다.

[AI] AI Agent는 모델이 아니라 Workflow다 — Claude가 말하는 Agent 설계 패턴

기록하는 백앤드개발자 — Sun, 15 Mar 2026 12:54:58 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

실제로 Claude을 효율적으로 사용하기 위해서는 워크플로우 구조(workflow)를 이해해야 한다.

LLM은 단지 추론 엔진일 뿐이고, 실제 문제 해결은 여러 단계의 작업을 어떻게 연결하느냐에 따라 결정된다.
Anthropic에서 정리한 글 “Common workflow patterns for AI agents” 역시 같은 메시지를 전달한다.

좋은 Agent 시스템은 좋은 Workflow 설계에서 나온다.

ㅁ Agent 시스템의 본질

AI Agent는 단순한 모델 호출이 아닌, 실제로는 다음 요소들이 결합된 작은 프로그램 구조에 가깝다.

ㅇ LLM reasoning(한번더 생각한다)
ㅇ tool / API 호출
ㅇ 중간 결과 저장
ㅇ 반복적인 평가와 개선

즉 Agent는 다음과 같이 볼 수 있다.

Agent = Model + Tools + Workflow

모델이 똑똑하다고 해서 시스템이 자동으로 좋아지는 것은 아니다.
오히려 workflow 설계가 전체 성능을 좌우하는 경우가 많다.

ㅁ 가장 기본적인 Agent Workflow 패턴

Anthropic은 여러 Agent 구조 중에서도 실제로 자주 사용되는 패턴을 몇 가지로 정리한다.

ㅇ Sequential Workflow (순차 처리)

가장 기본적인 형태이다.

Task → Step1 → Step2 → Step3 → Result

예를 들어 다음과 같은 작업에 사용된다.

ㅇ 문서 분석 → 요약 → 보고서 작성
ㅇ 코드 생성 → 테스트 → 수정
ㅇ 데이터 처리 파이프라인

이 구조의 특징은 단순함이다.

대부분의 문제는 사실 이 구조만으로도 충분히 해결된다.

ㅇ Parallel Workflow (병렬 처리)

여러 Agent가 동시에 작업을 수행하는 구조이다.

Task
├ Agent A
├ Agent B
└ Agent C
↓
결과 통합

예를 들면 다음과 같다.

ㅇ 여러 검색 전략 수행
ㅇ 다양한 답변 후보 생성
ㅇ 여러 관점에서 분석

이 방식은 탐색 문제(exploration)\에서 특히 강력하다.

ㅇ Evaluator – Optimizer Workflow

생성과 평가를 반복하며 결과를 개선하는 구조이다.

Generate → Evaluate → Improve → Evaluate → ...

대표적인 예

ㅇ 코드 생성 → 테스트 → 수정
ㅇ 글 작성 → 품질 평가 → 개선

ㅇ LLM 응답 품질 개선 루프

이 구조는 정답이 명확하지 않은 문제에서 효과적이다.

ㅁ Agent 설계에서 가장 중요한 원칙

이 글에서 특히 인상적인 부분은 다음 메시지이다.

대부분의 문제는 Multi-Agent가 필요하지 않다.

많은 사람들이 Agent 시스템을 만들 때 다음과 같은 실수를 한다.

ㅇ 불필요하게 많은 Agent 생성
ㅇ 복잡한 orchestration
ㅇ 디버깅 어려움
ㅇ 비용 증가

Anthropic의 권장 접근 방식은 다음과 같다.

1️⃣ Single Agent + Simple Workflow
2️⃣ 필요하면 Parallel 확장
3️⃣ 필요하면 Evaluation Loop 추가

즉, Simple → Complex

순서로 발전시키라는 것이다.

ㅁ 개발자 관점에서의 핵심 통찰

이 글을 읽고 나면 Agent 시스템이 사실 특별한 AI 기술이 아니라 “워크플로우 설계 문제”라는 것을 깨닫게 된다.

Agent 시스템은 결국 다음과 같다.

ㅇ 작은 프로그램 구조
ㅇ 단계적 workflow
ㅇ tool orchestration

그리고 여기서 중요한 것은 모델이 아니라

“작업을 어떻게 분해하고 연결할 것인가”이다.

ㅁ 빠르게 MVP 적용해 보자

ㅇ Claude Agent를 이용해 빠르게 개발을 진행했던 프로젝트였다.

ㅇ 아이의 문법교육을 고민하면서 서점을 다녀오면서 아이디어를 얻게 되었다.

ㅇ Claude Agent 연습 + AI Grammar 교육 컨텐츠를 목적으로 작업을 시작하였다.

ㅇ 03-14 14시, 둘째 성당 첫영성체 교리 때문에 성당 카페에서 시작하였다.

ㅇ GPT로 PRD를 구성하기 위해 컨텍스트 레이아웃을 쌓았다.

GPT에서 PRD 구성

이번 작업은 Agent Workflow 기반 개발 준비 과정으로 진행되었다.

먼저 제품 목표를 정의하는

PRD(Product Requirements Document)

를 작성하고, 이를 바탕으로

UI 설계(WIREFRAME), 컴포넌트 구조(COMPONENT), LLM 프롬프트 설계(PROMPT_LIBRARY),

로컬 모델 연동(LLM_INTEGRATION)

문서를 단계적으로 정리하였다.

이 과정에서 AI는 단순 코드 생성 도구가 아니라

제품 기획 → 시스템 아키텍처 설계 → 인터페이스 정의 → LLM 활용 전략 수립

까지 협력하는 에이전트 역할을 수행했다.

최종적으로 Claude Harness와 같은 에이전트 기반 개발 환경에서

바로 구현 가능한 수준의 구조화된 개발 문서 세트를 구축하는 것을 목표로 하였다.

Claude Code AI 에이전트 환경 구축, Harness

Claude CLI에서 AI가 프로젝트를 분석하고 스킬/에이전트/워크플로우를 자동 구축하도록 하였다.

Phase 1: 프로젝트 기반 설정 (CLAUDE.md)
Phase 2: 진행 상황 및 계획 관리
Phase 3: 핵심 파일 관리 정책
Phase 4: 스킬/에이전트 설계
Phase 5: 스킬 및 에이전트 생성 (품질 기준 준수)
Phase 6: 레퍼런스 문서 구성
Phase 7: 검증 및 유지보수 루프
Phase 8: 자율 반복 워크플로우

orchestrator-Worker with Parallelization

패 턴	적용 여부
Orchestrator-Worker	0 (메인이 계획, 서브가 실행)
Parallelization	0 (라운드 내 최대 3개 병렬)
Sequential	0 (라운드 간 의존 관계)
Evaluator-Optimizer	X (평가-재생성 루프 없음)

내가 사용한 Workflow 패턴은 "orchestrator-Worker with Parallelization" 이다.

ㅇ 자율 반복 workflow를 이용하여 PLAN에 따라 순차적, 병렬로 작업을 수행하였다.

ㅇ harness에 정의되어 있는 방향성대로 AI가 메인과 서브로 나뉘어 Orchestrator-Worker를 수행하였다.

ㅇ 03-14 15시 35분 1차 개발이 완료되었다.

ㅇ 일부 버그가 존재하였지만 2시간 미만에 MVP를 구성 및 개발이 가능하였다.

ㅇ 이 프로젝트는 아내와 함께 더 고도화해 나갈 예정이다.

ㅁ 마무리

AI Agent를 설계할 때 많은 사람들이 모델이나 프롬프트에 집중한다.

하지만 실제로 시스템을 만들다 보면 중요한 것은 다음 질문이다.

“이 작업을 어떤 workflow로 구성할 것인가?”

좋은 Agent는 좋은 모델에서 나오는 것이 아니라
좋은 Workflow 설계에서 시작된다.

이번 작업을 통해 다시 한번 느낀 점은 AI는 단순히 코드를 생성해 주는 도구가 아니라

ㅇ 문제를 구조화하고
ㅇ 작업을 분해하고
ㅇ 실행 가능한 개발 흐름을 설계하는
협력형 개발 파트너라는 점이다.

Claude Agent와 Harness 구조를 이용해 실제로 작은 프로젝트를 실행해 보니
기획(PRD) → 설계(Wireframe, Component) → LLM 전략(Prompt, Integration) → 구현

까지 이어지는 Agent 기반 개발 workflow를 비교적 짧은 시간 안에 구성할 수 있었다.

앞으로 AI Agent 기반 개발 방식은 단순한 코드 자동화를 넘어서

ㅇ 제품 기획
ㅇ 시스템 아키텍처 설계
ㅇ 개발 workflow 자동화

까지 확장될 가능성이 높다고 생각한다.

지금은 작은 실험 수준이지만
이러한 workflow를 계속 반복하고 정리하다 보면
언젠가는 개발자와 AI가 함께 만드는 새로운 개발 방식이 만들어질 것이라 기대한다.

나 역시 그 흐름 속에서 기록하고 실험하며 계속 배워가려고 한다.

[AI] 나는 아직도 배우는 중이다

기록하는 백앤드개발자 — Thu, 12 Mar 2026 02:13:55 +0900

나는 02학번으로 가톨릭대 신학교를 졸업했다.
그리고 2013년부터 소프트웨어 개발자로 살아왔다.

처음에는 서로 다른 길처럼 보였다.
신학은 존재와 의미를 묻는 학문이었고,
개발은 현실의 문제를 해결하는 기술이었다.

하지만 삶을 살아가면서 깨닫게 되었다.
배움은 현실과 분리된 것이 아니라
현실을 살아가기 위해 계속 이어지는 과정이라는 것을.

개발자로 일하면서 나는 더 깊이 이해하고 싶었다.
소프트웨어가 어떻게 만들어지는지,
그리고 앞으로 세상을 바꿀 인공지능이 무엇인지.

그래서 다시 학교에 들어갔다.

소프트웨어공학을 공부했고,
그 다음에는 인공지능과 빅데이터를 공부했다.

신학교 이후
사이버대학교를 두 번 더 졸업했다.

돌아보면 나의 길은 단순하다.

현실이 나에게 질문을 던졌고,
나는 그 질문에 답하기 위해 다시 배웠다.
그리고 지금도 여전히 배우고 있다.

[AI] 인공지능에 대한 이해(2017에 정리한 리포트)

소프트웨어공학부를 다니면서 작성했던 인공지능 리포트이다.

AI, 머신러닝, 딥러닝, 그리고 LLM.

그때 공부했던 내용들은
지금 내가 하고 있는 일들과 다시 연결되고 있다.

AI플랫폼팀에 있었지만, 공부는 끝이 없었다.

나는 오늘도 오픈소스 검증을 위한
로컬 LLM 연동 방법을 고민하고 있다.

롤 기반 정적 분석과
맥북에서 동작하는 로컬 LLM을 이용해
코드 분석 도우미를 만드는 작업을 진행하고 있다.

AI는 발전하고 있다.

2017년 리포트에도 언급하였듯이
PIM과 같은 하드웨어적 혁신이 오면
기술성장은 기하급수적으로 발전하게 된다.

현실의 필요성 앞에서
나는 하기 위해 배우고,
배우기 위해 다시 해 나간다.

배움이 끝나서 일이 시작되는 것이 아니라
일을 하면서 다시 배우게 되고
배우면서 또 새로운 일을 시작하게 된다.

그래서 이 과정은
어떤 끝이 있는 길이라기보다
계속 이어지는 하나의 여정처럼 느껴진다.

“나는 하기 위해 배우고, 배우면서 해 나가는 여정 위에 있다.”

[AI] Peterica의 AI공부와 비젼 정리

[AI] 개발자가 직접 만드는 Agent Harness - Ralph Loop와 Agentic Workflow Harness의 차이

기록하는 백앤드개발자 — Wed, 11 Mar 2026 21:35:08 +0900

ㅁ 들어가며

[AI] Agentic Workflow와 harness 개념 중심을 작성하면서 Harness(발음은 "하-니스"이다^^)에 대해서 알게 되었다.
처음에는 단순히 “LLM을 실행시키는 코드” 정도로 이해했지만, 최근 여러 사례를 살펴보면서 생각이 조금 바뀌었다.

LLM 자체는 두뇌일 뿐이다.
실제 시스템에서 일을 하게 만드는 것은 Harness다.

오늘 한 개발자가 다음 두 가지에 대해서 비교 질문을 주었다.

Ralph Loop (Ralph Wiggum Technique)
Agentic Workflow Harness

둘 다 AI 에이전트를 실행하는 구조이지만, 철학과 구현 방식이 상당히 다르다.

이 차이를 이해하면 AI 에이전트 시스템을 어떻게 설계해야 하는지 방향이 보이기 시작한다.

ㅁ Harness란 무엇인가

Harness는 단순히 말하면 다음과 같은 역할을 한다.

ㅇ LLM에게 작업을 전달한다
ㅇ 실행 결과를 수집한다
ㅇ 필요한 도구(tool)를 호출하게 한다
ㅇ 반복 실행을 관리한다
ㅇ 상태와 기록을 관리한다

즉,

LLM을 실제 시스템에서 “일하게 만드는 실행 인프라” 라고 볼 수 있다.

AI 에이전트 시스템을 만들 때 중요한 것은 모델 자체보다 이 Harness 설계다.

ㅁ Ralph Loop의 Harness 구조

Ralph Loop는 매우 단순한 방식이다.
핵심 철학은 순진한 끈기 (naive persistence)이다.

ㅇ 구현 방식

Bash while loop
쉘 스크립트

ㅇ 기본 동작

while true
    LLM에게 작업 요청
    코드 생성
    테스트 실행
    실패하면 다시 요청

이 방식은 놀라울 정도로 단순하다.

AI 코딩 에이전트에게 다음을 계속 반복한다.

ㅇ 작업 명세 (spec.md) 전달
ㅇ 코드 생성
ㅇ 테스트 실행
ㅇ 실패 시 수정
ㅇ 완료될 때까지 반복

이 과정이 밤새도록 돌아간다.

ㅁ Ralph Loop의 특징

ㅇ Stateless 구조

각 실행은 거의 새로 시작된다.

상태는 다음을 통해 간접적으로 유지된다.

Git history
파일 시스템
생성된 코드

즉,

메모리가 아니라 코드 자체가 상태가 된다.

ㅇ 설정이 매우 단순

프레임워크가 필요 없다.

보통 다음 정도면 끝난다.

prompt.md
run_tests.sh
ralph.sh

개인 개발자가 실험하기에는 매우 좋은 방식이다.

ㅇ 문제점

- 목표 검증이 약함
- 무한 루프 가능
- 잘못된 방향으로 계속 수정

즉,

끈기는 있지만 통제가 약하다

ㅁ Agentic Workflow의 Harness

최근 등장하는 Agent 시스템은 완전히 다른 접근을 한다.

핵심 철학은 다음이다.

AI를 통제 가능한 시스템으로 만든다

이때 Harness는 단순 실행 루프가 아니라 소프트웨어 인프라가 된다.

ㅇ 구현 방식

보통 다음과 같은 계층으로 구성된다.

Agent framework (LangChain / CrewAI / custom)
Tool system
Memory system
Guardrails
Human-in-the-loop

즉, LLM을 감싸는 제어 레이어가 존재한다.

ㅁ Agent Harness의 구조

일반적인 구조는 다음과 같다.

Task Planner
     ↓
Agent Executor
     ↓
Tool Layer
     ↓
Memory
     ↓
Observation / Logging

특징은 stateful 시스템이라는 점이다.

이전 행동 기록
실패 로그
작업 진행 상태
메모리

이 모든 것이 관리된다.

ㅁ Ralph Loop vs Agent Harness

핵심 차이는 다음과 같다.

구분Ralph LoopAgent Harness

구분	Ralph Loop	Agent Harness
핵심 개념	단순 반복	시스템 제어
구현 난이도	낮음	높음
상태 관리	거의 없음	Stateful
제어	약함	강함
목적	개인 개발 실험	장기 자동화

정리하면 다음과 같다.

Ralph Loop = 끈기 기반 자동화
Agent Harness = 거버넌스 기반 자동화

ㅁ 앞으로의 방향

최근 AI 에이전트 시스템의 흐름은 점점 명확해지고 있다.

2024 → 모델 경쟁

2025 → Agent 등장

2026 → Agent Harness 경쟁

앞으로 중요한 것은 모델이 아니라 에이전트를 어떻게 통제하는가다.

그리고 이 문제는 결국 소프트웨어 아키텍처 문제가 된다.

ㅁ 마무리

Ralph Loop는 매우 흥미로운 접근이다.

단순한 반복만으로도 AI 에이전트를 꽤 강력하게 활용할 수 있다.

하지만 실제 서비스 환경에서는 다음이 필요하다.

- 상태 관리
- 실행 통제
- 안전 장치
- 장기 작업 관리

그래서 결국 시스템은 Agent Harness 형태로 발전하게 된다.

AI 에이전트 시대에는
모델보다 Harness 설계가 더 중요해질 가능성이 높다.

[독후감] 환율의 대전환, 오건영(읽는 중)

기록하는 백앤드개발자 — Sat, 7 Mar 2026 15:47:45 +0900

ㅁ 들어가며

부의 흐름을 이해하고 싶어서 읽었던 책이 부의 대이동이었다.

당시 책을 읽으며 느낀 점은 하나였다. 이 책은 단순히 투자 전략을 설명하는 책이 아니라, 돈이 이동하는 구조를 설명하는 책이라는 점이다. 금리, 환율, 채권, 달러 같은 요소들이 각각 따로 움직이는 것이 아니라 하나의 시스템 안에서 서로 영향을 주며 움직인다는 관점이 인상적이었다.

그래서 이번에는 환율의 대전환을 읽어 보려고 한다.

하지만 바로 책의 내용을 따라가기보다는, 먼저 저자가 어떤 방식으로 시장을 설명하는 사람인지 이해하는 것이 더 중요하다고 생각했다.

ㅁ 왜 작가를 먼저 이해하려 하는가

경제서를 읽다 보면 같은 현상을 전혀 다른 방식으로 설명하는 저자들을 만나게 된다.

어떤 사람은 시장을 예측하려 하고, 어떤 사람은 특정 자산을 추천한다.

하지만 오건영의 설명 방식은 조금 다르다.

그는 시장을 맞히려 하지 않는다.
대신 시장이 왜 그런 방향으로 움직일 수밖에 없는지를 설명한다.

그래서 그의 책을 읽을 때 중요한 것은 “지금 무엇을 사야 하는가”가 아니라,

왜 자본이 그 방향으로 이동하는가를 이해하는 것이다.

ㅁ 오건영이 시장을 설명하는 방식

오건영의 설명은 항상 하나의 공통된 관점에서 시작된다.

ㅇ 시장을 개별 자산으로 보지 않는다

환율, 금리, 채권, 주식, 달러, 금을 각각 따로 보는 것이 아니라 하나의 시스템으로 바라본다.
한 자산의 변화는 다른 자산의 원인이 되기도 하고 결과가 되기도 한다.

ㅇ 결과보다 구조를 설명한다

특정 시점의 주가나 환율을 맞히는 것에는 큰 의미를 두지 않는다.
대신 금리 정책, 유동성, 자본 이동 같은 요소들이 어떤 구조로 연결되어 있는지를 설명한다.

ㅇ 위기는 예외가 아니라 반복되는 현상으로 본다

금융 위기는 항상 예상하지 못한 방식으로 찾아온다.
하지만 위기가 올 때 강해지는 자산과 자본의 이동 방향은 일정한 패턴을 가진다고 설명한다.

ㅁ 이번 책을 읽는 관점

이런 이유로 나는 환율의 대전환을 투자 전략서로 읽기보다는 금융 시스템을 이해하는 책으로 읽어 보려고 한다.

환율을 단순히 통화의 가격으로 보는 것이 아니라

금리 변화
글로벌 자본 이동
달러 시스템
금융 위기 구조

이 네 가지 축 속에서 바라보는 것이 이 책을 읽는 핵심 관점이 될 것 같다.

결국 오건영의 책은 자산을 추천하는 책이라기보다 시장을 읽는 사고 방식을 훈련시키는 책에 가깝다.

그래서 이 글에서는 먼저 작가의 관점을 정리했고,

환율의 대전환을 읽으며 정리한 내용을 차례로 기록해 보려고 한다.

Part 1 — 달러

달러를 이해해야 환율이 보인다

이 파트의 핵심 메시지는 단순하다.

환율은 통화의 가격이 아니라 자본 이동의 결과다.

그리고 그 중심에는 항상 달러 시스템이 존재한다.

ㅁ 원화는 정말 약한 통화일까?

우리는 흔히 원화를 약한 통화라고 말한다.
하지만 책에서는 이 질문 자체를 다시 생각하게 만든다.

관점에 따라 원화 가치는 달라진다. 오히려 다른 나라보다 안정적이었다.

환율은 절대적인 값이 아니라 두 나라 경제의 상대 비교이기 때문이다.

환율을 결정하는 요소는 크게 다음과 같다.

ㅇ 금리
ㅇ 성장률
ㅇ 무역 구조
ㅇ 자본 이동

즉 원화가 약하다기보다
달러와 비교했을 때 상대적인 위치가 변하는 것이다.

달러원 환율 그래프를 보면 사실상 한국 경제의 역사가 그대로 나타난다.

IMF 외환위기
글로벌 금융위기
중국 성장 특수
최근의 강달러 흐름

환율은 경제 사건들의 결과다.

ㅁ 한국 원화가 강했던 시대, 미국이 약했던 시기

2000년대 이후 원화는 비교적 안정적인 흐름을 보였다.
많은 사람들이 이를 한국 경제의 체력 때문이라고 생각한다.

하지만 책에서는 조금 다른 해석을 제시한다.

핵심은 중국 특수였다.

당시 한국 경제는

중국으로의 대규모 수출
구조적인 무역 흑자
외환보유고 증가

이 세 가지 요소로 인해 달러 유입이 지속되었다.

즉 원화 강세는
한국 자체의 힘이라기보다 글로벌 무역 구조의 결과였던 셈이다.

ㅁ 강달러가 나타나는 구조

최근 글로벌 금융 시장에서 가장 중요한 변화는 강달러 흐름이다.

저자는 그 이유를 미국 경제 구조에서 찾는다.

대표적인 요소는 다음과 같다.

ㅇ 셰일 오일 혁명
ㅇ 기술 산업 성장
ㅇ 높은 생산성
ㅇ 자본시장 규모

미국은 여전히 전 세계 자본이 몰리는 경제다.

위기가 발생하면 자본은 가장 안전한 시장으로 이동한다.
그 결과 달러는 반복적으로 강세를 보이게 된다.

ㅁ 한국 환율 구조의 변화

Part 1에서 가장 중요한 내용은 이 부분이라고 생각한다.

저자는 한국 환율의 큰 흐름이
앞으로 이전과는 다른 방향으로 움직일 가능성을 이야기한다.

그 이유는 다음과 같다.

ㅇ 중국 성장 둔화
ㅇ 대중 수출 감소
ㅇ 무역 흑자 축소
ㅇ 미국과의 금리 역전

과거에는 무역 흑자가 환율을 안정시키는 역할을 했다.
하지만 앞으로는 자본 이동과 금리 차이가 환율을 더 크게 움직일 가능성이 높다.

ㅁ 환율은 방향보다 변동성이 중요하다

최근 글로벌 경제에서 또 하나 중요한 변수는 정치다.

특히 미국 정치 변화는 환율 변동성을 크게 만든다.

책에서는 트럼프 정책을 예로 들며 다음과 같은 구조를 설명한다.

ㅇ 관세 정책
ㅇ 감세 정책
ㅇ 무역 불균형 조정

이 정책들은 달러 강세를 만들기도 하지만 동시에 환율 변동성을 확대시킬 가능성이 높다.

즉 앞으로 환율 시장의 특징은
단순한 상승이나 하락보다 변동성 확대일 수 있다.

ㅁ 달러원 환율의 장기 흐름

Part 1의 결론은 비교적 명확하다.

저자가 보는 구조적 흐름은 다음과 같다.

ㅇ 단기: 환율 변동성 확대

ㅇ 중기: 환율 밴드 상승

ㅇ 장기: 완만한 달러 강세

환율은 한 방향으로 움직이기보다
위아래로 크게 흔들리는 구조 속에서 조금씩 상승할 가능성이 있다는 것이다.

Part 2 — 엔화

Part 1에서 달러를 읽으며 느꼈던 것은 “돈은 결국 달러로 모인다”는 구조였다.
그렇다면 자연스럽게 이런 질문이 생긴다.

“그 돈은 어디에서 시작되는 걸까?”

Part 2를 읽으며 그 답이 엔화라는 것을 이해하게 되었다.

ㅁ 엔화는 투자되는 돈이 아니라, 시작되는 돈이다

처음에는 엔화 약세를 단순하게 생각했다.
일본 경제가 약하니까 통화 가치도 약해지는 것이라고.

하지만 책을 읽으며 이 생각이 완전히 바뀌었다.

엔화는 약한 통화라서 약한 것이 아니라,
역할 자체가 다른 통화였다.

엔화는 투자되는 돈이 아니라
투자하기 위해 빌리는 돈이었다.

ㅁ 왜 하필 엔화인가?

책을 읽으며 이해한 구조는 단순했다.

일본은 오랜 기간 저금리 상태를 유지해 왔다.
돈을 빌리는 입장에서는 가장 부담이 적은 통화다.

반면 다른 나라, 특히 미국은 금리가 높다.
투자하면 더 많은 수익을 얻을 수 있다.

그래서 투자자들은

엔화를 빌리고 → 달러로 바꿔 → 미국에 투자한다.

이 흐름이 반복되면서 엔화는 자연스럽게
글로벌 투자 자금의 출발점이 된다.

ㅁ 이해가 안 됐던 부분

읽으면서 가장 이해가 안 됐던 부분은 이것이었다.

“돈을 계속 풀면 인플레이션이 생겨야 하는 것 아닌가?”

내가 알고 있던 상식은 이랬다.

돈을 많이 찍으면 → 물가 상승 → 통화 가치 하락 → 결국 문제 발생

그런데 일본은 오랫동안 이 구조에서 벗어나 있었다.

ㅁ 왜 일본은 달랐을까

책을 읽으며 이해한 건, 일본은 돈을 풀어도
그 돈이 경제 안에서 강하게 돌지 않는 구조였다는 점이다.

사람들은 소비보다 저축을 선택하고
기업은 투자보다 현금을 쌓아두고
경제 전체의 성장 기대가 낮다

이런 환경에서는 돈이 늘어나도 수요가 크게 증가하지 않는다.

결국 물가도 쉽게 오르지 않는다.

이 구조 덕분에 일본은 오랫동안 저금리를 유지할 수 있었고, 그 결과 엔화는 조달 통화가 될 수 있었다.

ㅁ 그래서 엔화는 두 가지 얼굴을 가진다

이 구조를 이해하고 나니

엔화의 움직임도 자연스럽게 이해되기 시작했다.

평상시에는

엔화를 빌려서 투자하기 때문에
→ 엔화는 계속 시장에 공급되고
→ 약세를 보인다

하지만 위기가 발생하면

투자자들이 자산을 정리하면서
→ 빌렸던 엔화를 갚아야 하고
→ 엔화를 다시 사게 된다

→ 이때 엔화는 강세를 보인다

ㅁ Part 2를 읽고 나서

Part 2를 읽으며 가장 크게 바뀐 점은 엔화를 바라보는 관점이었다.

이전에는 엔화를 단순히“일본의 통화”로만 생각했다.

하지만 지금은

엔화를 보면 일본 경제가 아니라 글로벌 자본이 어떻게 움직이고 있는지를 보게 된다.

엔화는 일본의 통화가 아니라. 글로벌 투자 자금이 시작되는 통화다

[독후감] 처음 만나는 마음챙김 명상

기록하는 백앤드개발자 — Sat, 7 Mar 2026 15:35:35 +0900

ㅁ 작가 이해하기: 존 카밧진은 어떤 사람인가

『처음 만나는 마음챙김 명상』을 읽으면서 한 가지 궁금해졌다.
이 책을 쓴 사람은 어떤 배경에서 이런 언어를 선택했을까.
작가를 이해하면, 글은 설명이 아니라 대화가 된다.

ㅇ 존 카밧진의 배경

존 카밧진(Jon Kabat-Zinn)은 종교 지도자가 아니다. 그는 MIT에서 수학한 분자생물학 박사이며, 매사추세츠 의과대학 교수였다.

그의 출발점은 수행이 아니라 과학이었다.

1979년 그는 병원 내에 MBSR(Mindfulness-Based Stress Reduction, 마음챙김 기반 스트레스 완화) 프로그램을 만들었다.
만성 통증과 스트레스 환자들을 대상으로 8주간 명상 훈련을 진행했고, 그 효과를 임상 데이터로 검증했다.

즉, 그는 명상을 ‘신비 체험’이 아니라 ‘훈련 가능한 기술’로 다룬 사람이다.

ㅇ 그는 무엇을 번역했는가

존 카밧진은 불교 수행 전통(선, 위빠사나)에서 핵심 원리를 가져왔다.
그러나 종교적 용어는 제거했다.

대신 이렇게 번역했다.

깨달음 → 자각
수행 → 훈련
해탈 → 반응하지 않는 주의 상태

그는 명상을 믿음의 영역이 아니라 관찰의 영역으로 이동시켰다.
그래서 그의 문장은 감정적이지 않고, 절제되어 있다.

ㅁ 생각에 문제가 있는 것은 아니다.

생각을 없애라고 하지 않고, 생각을 ‘보라’고 말한다.
감정을 억누르라고 하지 않고, 감정이 일어나는 과정을 알아차리라고 말한다.

생각을 자각(알아차림)이라는 보다 큰 장에 담아 살피지 않는다면 생각은 우리의 통제력을 벗어나 문제를 일으킬 수도 있다. 제대로 살피지 않은 유해한 감정과 결합될 때 생각은 우리 자신과 타인 그리고 어쩌면 세상에 커다란 고통을 입힐 수도 있다.( p24)

한편 우리의 마음 자체는 깊은 바다처럼 그 특성이 깊고 방대하고 본질적으로 고요하다.(p25)

ㅇ 그의 태도

그는 위로하지 않는다.
대신 질문한다.

“지금 이 순간, 무엇을 경험하고 있습니까?”

그 질문은 친절하지만 단호하다.

생각을 없애라고 하지 않고, 생각을 ‘보라’고 말한다.
감정을 억누르라고 하지 않고, 감정이 일어나는 과정을 알아차리라고 말한다.

그의 글이 건조하게 느껴지는 이유는 여기에 있다.
그는 상담가가 아니라 연구자에 가깝다.

ㅇ 그래서 이 책은 무엇인가

이 책은 힐링 에세이가 아니다.
의식의 작동 방식을 설명하는 매뉴얼에 가깝다.

생각은 문제인가? 아니다.
문제는 생각과 동일시되는 자동 반응이다.
자각은 통제가 아니라 관찰이다.

그의 메시지는 단순하다.
삶을 바꾸기 전에, 먼저 주의를 바꾸라.

ㅁ 가톨릭 신자의 관점에서 본 마음챙김 명상

『처음 만나는 마음챙김 명상』을 읽으면서 나는 자연스럽게 ‘기도’를 떠올렸다.

나는 가톨릭 신자이기 때문에,

책에서 말하는 명상의 경험을 전혀 낯설게 느끼지 않았다.

오히려 오래전부터 교회 안에서 경험해 왔던 묵상과 관상 기도의 방식과 상당히 닮아 있다고 느꼈다.

ㅇ 자각에 머문다는 것과 기도

책에서는 끊임없이 “자각(알아차림)에 머무는 것”을 강조한다.
생각과 감정이 일어나더라도 그것을 억누르지 않고,

판단하지도 않고, 그저 알아차리는 상태를 유지하는 것이다.

이 설명을 읽으며 나는 기도할 때의 상태를 떠올렸다.
기도는 단순히 말을 많이 하는 시간이 아니라, 하느님 앞에서 조용히 머무는 시간이기도 하다.

생각이 떠오르기도 하고 감정이 움직이기도 하지만, 그 모든 것을 하느님 앞에서 바라보는 상태가 된다.

결국 명상에서 말하는 자각의 상태는,

신앙의 언어로 말하면 하느님 앞에 머무는 현존의 상태와 크게 다르지 않다고 느껴졌다.

ㅇ 하느님의 사랑 안에서의 자각

책에서는 자각을 “엄마가 아이를 안아 주듯 경험을 품어 안는 상태”라고 설명한다.

이 표현을 읽으며 나는 하느님이 인간을 바라보는 방식과 닮아 있다는 생각이 들었다.

가톨릭 신앙에서 하느님은 인간을 있는 그대로 사랑하시는 분이다.
완벽해서 사랑받는 것이 아니라, 부족함과 약함까지 포함한 존재 자체를 사랑하신다.

그래서 기도 속에서 자신의 생각과 감정, 상처와 불안을 그대로 바라볼 수 있는 것이다.
그 모든 것을 판단하지 않고 받아들이는 자각의 태도는, 어쩌면 하느님의 사랑을 신뢰하는 태도와 연결되어 있는지도 모른다.

ㅇ 명상과 기도의 차이

물론 마음챙김 명상과 가톨릭 기도는 동일한 것은 아니다.

마음챙김 명상은 자각 그 자체에 머무는 훈련에 가깝다.

반면 가톨릭 기도는 그 자각 속에서 하느님과의 관계를 경험하는 행위다.

그러나 두 경험은 서로 충돌하기보다는, 서로를 이해할 수 있는 지점이 있다고 느꼈다.

마음챙김 명상은 주의를 맑게 하는 훈련이고,
기도는 그 맑은 주의 속에서 하느님을 만나는 경험이라고 볼 수 있기 때문이다.

ㅁ 마무리

작가를 알고 나니 이 책의 톤이 이해된다.
따뜻함보다는 명료함, 위로보다는 구조 설명.

존 카밧진과 대화하는 느낌은 누군가가 조용히 옆에 앉아 묻는 질문에 스스로 답하게 되는 경험에 가깝다.

이 책을 읽으며 나는 명상을 새로운 수행으로 받아들이기보다는, 내가 이미 알고 있던 기도의 또 다른 표현처럼 느꼈다.

생각을 억누르지 않고 바라보는 것,

판단하지 않고 현재에 머무는 것,
그리고 그 순간 안에서 존재를 있는 그대로 받아들이는 것.

이 모든 경험은 결국 하나의 질문으로 이어진다.

“지금 이 순간, 나는 무엇을 바라보고 있는가.”

그리고 신앙의 언어로 다시 말하면,
그 질문은 결국 이렇게 바뀌는 것 같다.

“지금 이 순간, 나는 하느님 앞에 어떻게 서 있는가.”

[AI] Agentic Workflow와 harness 개념 중심

기록하는 백앤드개발자 — Fri, 6 Mar 2026 21:08:15 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

ㅇ EP 86. 진짜 내 일을 해결하는 Agentic Workflow (Lablup 신정규 대표) 영상의 핵심 흐름을 Agentic Workflow와 harness 개념 중심으로 챕터화한 요약이다. 각 구간은 실제 대화 흐름 기준으로 묶었으며, 실무 적용 포인트를 중심으로 정리하였다.

ㅁ Agentic AI의 패러다임 전환

핵심 인사이트(약 31:27)

AI 성능 확장은 더 이상 모델 크기 증가만으로 해결되지 않는다.
대신 에이전트 수를 늘리는 방식(agent swarm)으로 확장한다.
즉, 단일 모델 → 다수 에이전트 협업 구조로 패러다임이 이동 중이다.

에이전트를 하나에서 10개, 20개로 늘리는 방향으로 확장이 이동했다

실무 적용

실제 시스템 구조도 동일한 흐름으로 진화한다.

기존

User → LLM → Result

현재

User
  ↓
Planner Agent
  ↓
Tool Agent / Retrieval Agent / Coding Agent
  ↓
Evaluator Agent
  ↓
Result

핵심은 모델 성능이 아니라 orchestration 설계이다.

ㅁ Agentic Workflow의 본질

핵심 인사이트(약 51:45)

Agentic workflow는

"결과를 만드는 것"이 아니라
"결과를 만드는 시스템을 만드는 것"이다.

말로 코딩을 하는데 대상이 결과물이 아니라
코딩을 하는 애를 만드는 것이다

즉

기존 개발
→ 코드 작성

Agentic 개발
→ 코드 생성 시스템 작성

실무 적용

ㅇ 개발자의 역할 변화

기존	Agentic
코드 작성	에이전트 설계
기능 구현	워크플로 설계
테스트	자동 평가 루프

개발자는 "프로그램 작성자 → 시스템 설계자"로 이동한다.

ㅁ Harness 개념 (Agent 운영 프레임워크)

핵심 인사이트(약 50:40)

Harness는 에이전트를 실행·통제하는 자동화 구조이다.

예시:

TDD harness
task 분산 harness
queue harness
workflow harness

대화에서 언급된 내용:

외부 harness들(TDD, 작업 분산 등)을 쓰는 경우도 있다

하지만 실제 실무에서는 “내 일을 줄여주는 harness부터 만들라”는 접근을 강조한다.

실무 적용

Harness 예시

task-harness
 ├ planning agent
 ├ coding agent
 ├ review agent
 └ test agent

실제 개발 자동화 예시

PR 생성
 → 코드 생성
 → 테스트 실행
 → lint 검사
 → 리뷰 생성

ㅁ Harness = 회사의 구조

핵심 인사이트(약 52:30)

여러 harness를 중첩하면 회사 조직 구조와 동일해진다.

여러 harness를 중첩하면 그게 회사가 된다

구조 예

Company Harness
 ├ Product Harness
 │   ├ Dev Harness
 │   └ QA Harness
 └ Marketing Harness

즉

Agent system = 조직 구조

실무 적용

ㅇ AI 조직 구조

역할	Agent
PM	Planner agent
Dev	Coding agent
QA	Test agent
Ops	Deploy agent

ㅁ Agentic 개발의 핵심 철학

핵심 인사이트(약 53:00)

개발자가 직접 결과물을 수정하지 않는다.

대신 "생성하는 장치를 수정한다."

결과물을 직접 고치지 않고
결과를 만드는 장치를 계속 고친다

실무 적용

기존 방식

버그 발생
→ 코드 수정

Agentic 방식

버그 발생
→ 에이전트 프롬프트 수정
→ 테스트 harness 수정
→ 워크플로 수정

즉,

debug 대상이 코드가 아니라 시스템이다.

ㅁ Workflow 설계 방법

핵심 인사이트(약 60:10)

Agent workflow는 처음부터 완성되지 않는다.

step-by-step으로 만들어진다

workflow는 처음부터 만들어지는 것이 아니라 step으로 구축된다

실무 적용

Agent 구축 단계

- 문제 정의
- 필요한 agent 식별
- command 설계
- harness 연결
- 반복 개선

ㅁ 핵심 개념 정리

ㅇ Agentic Workflow

정의

AI 에이전트들이 협력하여
복잡한 작업을 자동으로 수행하는 시스템

구조

Planner → Worker → Evaluator

ㅇ Harness

정의

에이전트들을 실행하고
작업 흐름을 통제하는 자동화 프레임워크

예

CI harness
Dev harness
Research harness

ㅁ 실무 적용 요약 (개발자 관점)

ㅇ 에이전트보다 workflow가 중요

- 잘못된 접근: 좋은 모델 찾기

- 올바른 접근: workflow 설계

ㅇ 결과보다 시스템

기존

코드 작성

Agentic

코드 생성 시스템 작성

ㅇ Harness를 먼저 만든다

예

research harness
coding harness
blog harness

ㅁ 마무리

“우리는 이제 코드를 만드는 것이 아니라
코드를 만드는 시스템을 만든다.”

Agentic Workflow — 이제 우리는 코드를 만드는 것이 아니라 시스템을 만든다

기록하는 백앤드개발자 — Fri, 6 Mar 2026 20:33:34 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

AI 코딩 도구를 처음 접하면 대부분 이렇게 생각한다.

“이제 코드를 대신 써주는 도구가 생겼구나.”

하지만 실제로 Agent 기반 개발을 이해하게 되면 생각이 완전히 바뀐다.

AI는 단순히 코드를 대신 작성하는 도구가 아니라

코드를 만들어내는 시스템 자체를 설계하는 기술로 발전하고 있기 때문이다.

이 흐름을 이해하려면 두 가지 개념이 중요하다.

Agentic Workflow
Harness

이 두 개념은 앞으로 AI 개발 방식의 구조를 설명하는 핵심 키워드가 된다.

ㅁ Agentic Workflow — AI가 일을 수행하는 방식

Agentic Workflow는 간단히 말하면

AI 에이전트들이 협력하여 하나의 작업을 완성하는 구조다.

기존 AI 사용 방식은 매우 단순했다.

사용자 → LLM → 결과

하지만 복잡한 작업에서는 이 구조가 한계를 가진다.

그래서 등장한 구조가 Agent Workflow다.

User
 ↓
Planner Agent
 ↓
Worker Agent (코드 / 검색 / 분석)
 ↓
Evaluator Agent
 ↓
Result

각 에이전트는 서로 다른 역할을 수행한다.

Planner → 문제를 분해한다
Worker → 실제 작업을 수행한다
Evaluator → 결과를 평가한다

이 구조는 흥미롭게도 회사 조직 구조와 매우 유사하다.

ㅁ Harness — 에이전트를 움직이는 운영 시스템

Agent Workflow가 조직 구조라면
Harness는 조직을 운영하는 시스템이다.

Harness는 다음 역할을 한다.

작업을 큐로 관리
에이전트 실행
결과 검증
반복 자동화

예를 들어 코드 개발 자동화 시스템을 만든다면 다음과 같은 구조가 된다.

coding-harness
 ├ planning agent
 ├ coding agent
 ├ review agent
 └ test agent

실제 실행 흐름은 이렇게 돌아간다.

PR 생성
 → 코드 생성
 → 테스트 실행
 → 리뷰 생성
 → 수정

즉 Harness는

에이전트들이 협력하여 일을 수행하도록 만드는 자동화 프레임워크다.

ㅁ Agentic 개발의 본질 — 결과가 아니라 시스템을 수정한다

Agent 기반 개발의 가장 중요한 특징은
개발자의 수정 대상이 바뀐다는 것이다.

기존 개발 방식

버그 발생
 → 코드 수정

Agentic 개발 방식

버그 발생
 → 프롬프트 수정
 → workflow 수정
 → harness 수정

즉 개발자는

결과물을 수정하지 않는다.

대신

결과를 만들어내는 시스템을 수정한다.

이 차이는 매우 크다.

ㅁ Harness를 중첩하면 회사가 된다

Agent 시스템을 조금 더 확장하면 재미있는 현상이 나타난다.

여러 Harness를 조합하면 구조가 회사 조직과 동일해진다.

예를 들어

Company Harness
 ├ Dev Harness
 │   ├ coding agent
 │   ├ review agent
 │   └ test agent
 ├ Research Harness
 │   ├ search agent
 │   └ summarizer agent
 └ Marketing Harness

이 구조는 사실상

개발팀
리서치팀
마케팅팀

과 동일하다.

즉 Agent 시스템은 “디지털 조직 구조”라고 볼 수 있다.

ㅁ Agent Workflow는 한번에 만들어지지 않는다

많은 사람들이 Agent 시스템을 만들 때 처음부터 거대한 구조를 설계하려 한다.

하지만 실제로는 그렇게 만들어지지 않는다.

대부분 다음 단계로 발전한다.

1️⃣ 작은 작업 자동화
2️⃣ 반복 작업 Harness 생성
3️⃣ 여러 Harness 연결
4️⃣ 조직 구조 수준 Workflow 형성

결국 Agent 시스템은 작은 자동화에서 시작해 점진적으로 확장된다.

ㅁ 개발자의 역할 변화

이 변화는 개발자의 역할 자체를 바꾸고 있다.

기존 개발자

코드를 작성한다
기능을 구현한다

Agent 시대 개발자

Workflow를 설계한다
Agent 역할을 정의한다
Harness를 만든다

즉

개발자는 이제

“코드 작성자”에서
“시스템 설계자”로 이동하고 있다.

ㅁ 마무리 — 우리는 이제 코드를 만드는 것이 아니다

Agentic 개발의 핵심은 이 문장으로 정리할 수 있다.

우리는 이제 코드를 만드는 것이 아니라 코드를 만드는 시스템을 만든다.

Agent Workflow는 조직 구조이고 Harness는 그 조직을 운영하는 시스템이다.

이 구조가 완성되면 AI는 단순한 도구가 아니라

실제로 일을 수행하는 디지털 조직이 된다.

선거를 보면 정치가 아니라 유동성이 보인다 - 금리·달러·자산시장으로 해석하는 금융 사이클

기록하는 백앤드개발자 — Thu, 26 Feb 2026 07:24:20 +0900

ㅁ 들어가며 — 선거를 보면 정치가 아니라 금융 조건이 보인다

https://www.youtube.com/watch?v=RyOrBmiAaCI

이 영상은 특정 인물이나 선거 전술을 설명하는 것처럼 보이지만, 실제로는 금리–유동성–달러–자산시장이 하나의 시스템으로 움직이는 구조를 해석하는 내용에 가깝다.

우리는 보통 선거를 이념, 공약, 지지율로 해석한다.
하지만 시장은 전혀 다른 질문을 한다.

“누가 당선되는가?”가 아니라
“어떤 금융 환경이 만들어지는가?”

이 영상은 바로 그 지점을 파고든다.

선거는 원인이 아니라 금리와 유동성 경로를 바꾸는 트리거로 작동한다.

즉, 정치 이벤트를 이야기하지만 본질은 거시 금융 사이클이다.

ㅁ 왜 금리가 모든 것의 중심에 있는가

금리는 단순히 물가를 잡는 도구가 아니다.
시스템 전체의 속도를 조절하는 레버다.

금리가 내려가면

정부의 이자 부담 감소
기업의 자금 조달 개선
자산 가격 상승
소비 심리 회복

금리가 올라가면 그 반대가 발생한다.

즉 금리는

경제 지표 하나가 아니라
자산시장 + 재정 + 고용 + 소비를 동시에 움직이는 축이다.

선거 전에 금리 방향이 중요한 이유는
유권자가 체감하는 경기를 바꾸기 때문이다.

ㅁ 유동성이 만들어내는 “체감 경기”

사람들이 느끼는 경기는 GDP가 아니라

주가
집값
일자리 안정감
대출 부담

으로 결정된다.

이 네 가지는 모두 유동성과 연결되어 있다.

그래서 선거 국면에서 중요한 것은

경기를 실제로 성장시키는 것이 아니라
경기가 좋아 보이게 만드는 금융 환경이다.

ㅁ 달러 패권 구조 — 위기의 시작과 해결이 동시에 미국인 이유

영상에서 반복적으로 깔려 있는 전제는 하나다.

“글로벌 금융 시스템의 중심은 달러다.”

이 구조에서는 특이한 현상이 발생한다.

위기가 발생하면

- 글로벌 자산 하락
- 달러 부채 상환 필요
- 달러 수요 증가
- 달러 강세

즉,

위기의 진원지가 미국이어도
→ 해결 수단도 달러다.

이것이 달러가 최종 안전자산으로 작동하는 이유다.

ㅁ 정치 이벤트의 실제 역할

선거는 방향을 만드는 것이 아니라
이미 필요한 방향을 정당화하는 과정에 가깝다.

시장 입장에서 중요한 것은

재정 확대가 가능한가
금리 인하 압력이 생기는가
유동성이 공급되는가
달러가 약세로 전환되는가

정치 메시지는 표면이고 금융 조건이 실제 내용이다.

ㅁ 시장을 해석하는 새로운 프레임

이 영상이 던지는 핵심적인 사고 방식은 다음과 같다.

기존 질문
→ 누가 이길까?

구조적 질문
→ 어떤 정책 조합이 시장을 움직일까?

이 관점으로 보면

- 선거
- 금리
- 유동성
- 자산시장

이 서로 분리된 이벤트가 아니라
하나의 사이클로 보인다.

ㅁ 마무리 - 선거는 금융 사이클의 일부다

이 영상의 핵심을 한 문장으로 정리하면 다음과 같다.

선거는 정치 이벤트가 아니라
금리와 유동성 경로를 조정하는 매크로 이벤트다.

그래서 시장은 후보의 말이 아니라 그 결과로 만들어질 금융 조건을 먼저 본다.

[AI] HBM은 왜 LLM 시대의 핵심이 되었는가?

기록하는 백앤드개발자 — Mon, 23 Feb 2026 23:09:57 +0900

ㅁ 들어가며

연산이 아니라 데이터 이동이 병목이었다

LLM 인프라를 처음 이해할 때 가장 많이 하는 오해가 있다.
성능이 부족한 이유를 GPU의 FLOPS에서 찾는 것이다.

하지만 실제 운영 환경에서 마주치는 병목은 전혀 다른 곳에 있다.

GPU는 계산을 못 해서 느린 것이 아니라,
계산에 필요한 weight가 메모리에서 도착하기를 기다리느라 멈춰 있는 시간이 대부분이다.

이번 정리를 통해 HBM 세대의 진화는 단순한 속도 향상이 아니라
데이터 이동 구조 자체를 바꾸는 과정이었다는 것을 이해하게 되었다.

FLOPS(Floating Point Operations Per Second)
→ 초당 부동소수점 연산 횟수

ㅁ 왜 LLM은 메모리 중심 워크로드인가

LLM의 연산 흐름은 놀라울 정도로 단순하다.

weight를 메모리에서 가져온다 → activation과 곱한다 → 결과를 다음 레이어로 넘긴다 → 다음 weight를 다시 가져온다.

이 과정이 레이어 수만큼 반복된다.

즉 연산 자체보다 메모리 접근 횟수가 절대적으로 많다.

그래서 LLM에서는 FLOPS보다
메모리 대역폭이 곧 성능이 된다.

ㅁ 개념 정리 – weight와 activation

weight는 모델이 학습을 통해 얻은 장기 기억이다.
평소에는 HBM에 저장되어 있다가 연산 순간에 GPU로 불려와 사용된다.
즉 모델이 알고 있는 지식 자체다.

activation은 현재 문맥에서 실제 계산에 사용되고 있는 작업 기억이다.
토큰이 레이어를 통과할 때마다 계속 형태가 바뀌며 다음 연산으로 전달된다.
사람이 어떤 문제를 풀 때 머릿속에 떠올려 놓고 정리해 나가는 생각의 흐름과 같다.

LLM의 대부분의 연산은 다음 한 줄로 정리된다.

activation × weight → 새로운 activation

ㅁ 기존 DRAM 구조의 한계 – 창고는 큰데 길이 좁다

기존 메모리는 저장 용량은 충분했지만 데이터가 이동하는 통로가 좁았다.

그래서 GPU는 대부분의 시간을 데이터를 기다리는 데 사용하게 된다.

이 상태가 바로 memory-bound다.

ㅁ HBM의 본질 – 컨베이어를 1024차선으로 만든 것

HBM을 단순히 DRAM을 쌓은 기술로 이해하면 핵심을 놓치게 된다.

HBM의 본질은 용량 증가가 아니라
초광폭 I/O 구조다.

기존 메모리가 32차선 도로라면 HBM은 1024차선 고속도로다.

데이터가 병렬로 동시에 이동하면서 GPU가 멈추지 않게 된다.

ㅁ 적층(쌓기)의 진짜 의미 – 용량이 아니라 거리

DRAM을 수직으로 쌓는 이유는 저장 공간을 늘리기 위해서가 아니다.

GPU 바로 옆에 메모리를 붙여

신호 이동 거리를 줄이고
전력 소모를 낮추고
대역폭을 극대화하기 위함이다.

즉 적층의 본질은
물리적 거리 단축을 통한 전송 효율 개선이다.

ㅁ 세대별 변화가 만드는 구조적 체감

HBM2 → HBM3

“GPU가 처음으로 AI에서 굶지 않기 시작”

AI 학습이 가능한 대역폭에 도달한 첫 세대.
GPU가 굶지 않기 시작했다.

대역폭이 딥러닝 학습 요구치에 도달

대형 모델 학습 가능

but, 하나의 GPU에 모델을 담을 수 없어 multi-GPU 사용, 통신 오버헤드 발생

HBM3 → HBM3E

“LLM용 메모리”

1TB/s급 대역폭과 12-Hi 적층(용량증가).
70B급 모델을 단일 GPU에 올리는 것이 현실이 되었다.
더 큰 모델을 한 GPU에 탑재하여, multi-GPU 통신 감소

HBM3E → HBM4

구조 변화 세대
인터페이스가 2배로 증가(1024 → 2048bit)하고

메모리 컨트롤러가 base die로 이동한다.

의미:
- GPU 설계 단순화
- 커스텀 HBM 가능
- 전력 효율 개선

AI 인프라 체감:
- NVLink 트래픽 감소
- shard 전략 변화
- latency 안정

이 시점부터는
GPU 수를 늘려 성능을 확보하는 구조에서
GPU 하나가 처리할 수 있는 모델 체급을 키우는 구조로 바뀐다.

표로 만들면...

세대인프라	체감
HBM2	모델을 여러 GPU에 강제로 분산
HBM3	대형 모델 학습 가능
HBM3E	70B급 단일 GPU 처리 현실화
HBM4	multi-GPU 의존도 감소
HBM5	메모리가 연산 일부 담당 가능

ㅁ 인프라 관점에서의 변화 – 분산에서 단일 노드로

HBM 용량이 커질수록 KV cache를 로컬에 유지할 수 있고
HBM 대역폭이 커질수록 GPU idle이 줄어든다.

그 결과

multi-GPU shard 구조 → single GPU 중심 구조

로 서빙 방식이 단순해진다.

latency는 안정되고 NVLink 트래픽은 감소한다.

ㅁ 세대 진화의 본질 – 통신을 줄이는 역사

HBM의 발전은 세 가지로 정리된다.

대역폭 증가 → GPU idle 제거
용량 증가 → 모델 local 탑재
통신 감소 → 클러스터 구조 단순화

즉 속도의 문제가 아니라
데이터 이동을 줄여 온 과정이다.

ㅁ 다음 단계 – PIM이 의미하는 것

HBM까지는 데이터를 빠르게 이동시키는 기술이다.
PIM은 데이터를 이동시키지 않는 기술이다.

이 단계가 되면 메모리는 저장 장치가 아니라 연산 장치가 된다.

컴퓨팅의 중심이 GPU에서 메모리로 이동하게 된다.

ㅁ HBM 세대별 비교

구분	HBM2 / 2E	HBM3	HBM3E	HBM4 (차세대)	HBM5 (로드맵)
세대 시기	~2020	2022	2023~현재	2025~	2027~예상
핵심 역할	GPU 메모리 대역폭 확보	AI 학습 대응	LLM 대응 본격화	GPU 구조 변화 시작	메모리 중심 컴퓨팅 준비
핀 속도 (per pin)	~3.6Gbps	~6.4Gbps	~9.6Gbps	~13Gbps	16Gbps+ 예상
인터페이스 폭	1024-bit	1024-bit	1024-bit	2048-bit	2048-bit 이상 가능
스택당 대역폭	~410GB/s	~819GB/s	~1.2TB/s	~2TB/s	3TB/s+ 예상
최대 용량 (stack)	8~16GB	16GB	24~36GB	48~64GB+	100GB+ 가능성
적층 높이	4~8-Hi	8-Hi	12-Hi	16-Hi 이상	더 높은 적층
전력 효율	개선 시작	개선	LLM 대응 수준	대역폭 대비 효율 증가	구조적 변화 목표
메모리 컨트롤러 위치	GPU 내부	GPU 내부	GPU 내부	Base die 이동	메모리 쪽 연산 가능성
패키징	2.5D 인터포저	동일	동일	고급 패키징 필수	광인터커넥트 가능성
주요 사용처	HPC / 초기 AI	AI 학습	LLM 학습·추론	차세대 AI GPU	메모리 중심 AI

ㅁ 마무리 – LLM 인프라는 메모리 구조의 진화다

LLM 시대의 병목은 연산이 아니라 데이터 이동이다.

HBM은 DRAM을 쌓은 기술이 아니라
GPU가 멈추지 않게 만드는 초광폭 데이터 통로다.

세대 진화는 클럭 상승이 아니라
시스템 구조를 바꾸는 방향으로 진행되고 있다.

[독후감] 부의 대이동

기록하는 백앤드개발자 — Sun, 15 Feb 2026 23:10:31 +0900

ㅁ 이 책을 읽게 된 이유

이 책은 단순한 투자서가 아니라,
환율·금리·채권·달러·금이라는 요소들이 어떻게 연결되어 움직이는지를
‘돈의 흐름’이라는 하나의 구조로 설명한다.

개별 자산의 전망을 맞히는 것이 아니라,
위기와 성장 국면에서 자본이 어디로 이동하는지 판단하는 기준을 얻고자 읽었다.

ㅁ 오건영은 누구인가?

오건영은 예측하는 사람이 아니라 구조를 설명하는 사람이다
- 특정 시점의 주가나 환율을 맞히는 데 관심이 없다
- 왜 그런 방향으로 움직일 수밖에 없는지를 설명한다
- 결과보다 과정과 연결 관계를 중시한다
그는 시장을 단일 자산으로 보지 않는다
- 환율, 금리, 채권, 주식, 달러, 금을 분리하지 않는다
- 하나의 자산 변화는 다른 자산의 원인이자 결과가 된다
- 항상 ‘자본 이동’이라는 공통 축으로 설명한다
오건영의 설명은 정책과 시장을 구분하는 데서 시작된다
- 기준금리는 중앙은행의 의지다
- 시장금리는 투자자들의 불안과 신뢰다
- 두 금리가 어긋날 때 위기의 신호가 발생한다
그는 위기를 예외가 아니라 반복되는 현상으로 본다
- 금융 위기는 항상 예상 밖의 방식으로 찾아온다
- 하지만 위기 때 강해지는 자산은 반복적으로 등장한다
- 달러와 같은 방어 자산의 역할을 강조한다
달러를 바라보는 관점이 일관되어 있다
- 달러는 미국의 통화이기 이전에 글로벌 시스템의 통화다
- 위기의 원인이 미국이어도 달러 수요는 증가한다
- 달러 패권은 감정이 아니라 구조의 문제로 설명한다
금을 신화화하지 않는다
- 금을 절대적 안전 자산으로 보지 않는다
- 달러 정책과 유동성의 결과물로 해석한다
- 금 역시 타이밍과 환경의 영향을 받는 자산이다
한국 경제를 감정이 아닌 구조로 평가한다
- IMF 외환위기의 기억에만 기대어 판단하지 않는다
- 현재 한국 경제의 외환 구조와 금융 시스템을 근거로 든다
- 원화를 ‘약한 통화’로 단정 짓는 시각을 경계한다
그의 설명 방식은 불안을 낮추는 데 목적이 있다
- 위기를 과장하지 않는다
- 동시에 낙관도 강요하지 않는다
- 이해하면 공포는 줄어든다는 전제를 깔고 설명한다
오건영의 글과 강연이 주는 핵심 태도
- 시장을 맞히려 하지 말 것
- 구조를 이해할 것
- 자산을 분리해서 보지 말 것
- 방어 자산의 의미를 잊지 말 것

ㅁ 이 책의 핵심 메시지

돈의 가치는 절대값이 아니라 항상 비교의 결과다.
환율·금리·채권·주식은 분리된 개념이 아니라 하나의 시스템이다.
위기는 반복되며, 위기 국면에서 강해지는 자산은 정해져 있다.
예측보다 중요한 것은 구조를 이해하고 대비하는 것이다.

ㅁ PART 1 — 기초 지식 정리

환율·금리·채권을 바라보는 기본 프레임

ㅇ 환율은 무엇인가

환율은 한 나라 화폐의 ‘값’이 아니라 두 나라 경제 상태를 비교한 결과다.

물가(인플레이션)
금리
성장률
자본 이동

이 요소들이 종합되어 환율이 결정된다.
따라서 환율 상승이나 하락은 원인이 아니라 결과다.

화폐는 기준 통화가 없는 주식과 같아서, 한 화폐의 가치는 비교를 통해 비교 분석된다.
달러 가치 상승(달러 주식 상승) -> 원화 가치는 상대적 하락한다.

ㅇ 환율과 자산 시장의 관계

외국 자본 유입 → 환율 하락(원화 강세) → 주식 시장 우호적
자본 유출 → 환율 상승(원화 약세) → 주식·부동산 압박

특히 기관·외국인 자금은 주가보다 환율을 먼저 움직이는 경우가 많다.

ㅇ 채권과 금리의 역관계

금리 상승 → 기존 채권 가격 하락
금리 하락 → 기존 채권 가격 상승

국채 역시 안전 자산이지만, 금리 변동 리스크에서 자유롭지 않다는 점을 강조한다.

ㅇ 기준금리와 시장금리의 괴리

기준금리는 정책 신호이고, 시장금리는 불안과 신뢰의 정도를 반영한다.

기준금리 인하 + 시장금리 상승 → 경제에 대한 불안 증가 신호

이때 회사채 스프레드가 확대되며, 이는 위기의 전조 지표로 활용된다.

ㅁ PART 2 — 달러 투자에 대한 관점

ㅇ 달러는 왜 ‘궁극의 안전 자산’인가

금융 위기 때마다 반복되는 현상:

위기의 진원지 → 미국
위기의 해결 수단 → 달러 유동성

위기 상황에서 달러는 문제의 원인이면서 동시에 피난처가 된다.

p71 은행들이 보유하고 있는 주택 담보 대출 증서들을 담보로 해서 하나의 채권을 만드는 겁니다. 이걸 '자산유동화 증권'이라고 불러요.
p72 자산유동화 증권을 모아 모기지 채권을 발행함. 문제는 집값이 하락하면서 금융 기관들이 손실이 발생함.
금융사(투자자대출) -> 부동산 하락 -> 투자금 회수 -> 현금 확보 -> 자산가치 하락

요약

금융 위기의 진원지가 미국인 경우가 많음에도, 해결 수단이 달러가 되는 이유는 글로벌 금융 시스템 자체가 달러를 중심으로 설계되어 있기 때문이다. 세계의 부채, 결제, 담보, 안전자산 기준이 모두 달러에 묶여 있다.
달러는 문제의 원인이면서 동시에 피난처가 된다. 문제를 만든 통화이지만, 그 문제를 수습할 수 있는 유일한 통화이기 때문이다. 이 점에서 오건영은 달러를 ‘궁극의 안전 자산’이라고 설명한다.
미국 국채와 달러가 동시에 안전자산으로 기능하기 때문이다. 위기 국면에서 투자자들은 신용 위험이 가장 낮고, 언제든 현금화 가능한 자산을 찾는다. 그 조건을 충족하는 거의 유일한 자산이 미국 국채이며, 국채 매입 과정에서 자연스럽게 달러 수요가 증가한다.
달러 부족(dollar shortage) 현상 때문이다. 글로벌 금융기관과 기업들은 달러로 빚을 내고, 달러로 결제한다. 위기가 발생하면 위험 회피가 급격히 강화되면서 달러 대출이 위축되고, 기존 달러 부채를 상환하려는 수요가 폭증한다. 이 순간 시장에는 “달러가 모자라는 상황”이 발생하고, 달러 가치는 급등한다.
미국 중앙은행(Fed)만이 달러를 무제한으로 공급할 수 있는 주체다. 위기가 심화되면 Fed는 기준금리 인하, 양적완화, 달러 스왑라인 등을 통해 전 세계에 달러 유동성을 공급한다. 이 기능은 다른 나라 중앙은행이 대체할 수 없다. 그래서 위기의 원인이 미국에서 시작되었더라도, 시스템을 안정시키는 역할 역시 미국과 달러가 맡게 된다.
이 구조는 신뢰의 문제다. 위기 상황에서는 “누가 잘못했는가”보다 “누가 끝까지 책임질 수 있는가”가 중요해진다. 미국은 세계 최대의 경제 규모, 군사력, 금융 시장을 갖고 있고, 달러는 그 신뢰를 바탕으로 글로벌 최종 결제 수단 역할을 한다. 감정적으로는 미국 책임론이 제기되지만, 자본은 결국 가장 안전한 곳으로 이동한다.

문제를 만든 통화이지만, 그 문제를 수습할 수 있는 유일한 통화이기 때문이다.
이 점에서 오건영은 달러를 ‘궁극의 안전 자산’이라고 설명한다.

ㅁ PART 3 — 금 투자에 대한 관점

ㅇ 금은 정말 안전 자산인가?

금은 세기를 거듭하여서도 부의 축적 자원으로 사용되었다. 그래서 금은 안전 자산으로 인식되지만, 가격은 주식처럼 크게 변동한다.

특히

- 달러가 급등하면 금이 약세가 되고,

- 저금리,유동성 과잉이 되면 금이 강세가 된다.

금의 안전성은 절대적 개념이 아니다.

ㅇ 원자재로서의 금

p234 금의 3가지 특성 정의: 원자재, 실물화폐, 귀금속

금은 다른 원자재와 달리 공급이 제한적이며, 산업 수요보다 가치 저장 수단 성격이 강하다.

귀금속으로서 심리적 신뢰 존재한다.

ㅇ 시장을 움직이는 실물 화폐, 금의 비밀

p257.
- 달러 공급이 늘어서 달러 가치 하락 -> 금값 상승(달러 신뢰 바닥)

- 달러 공급 축소, 달러 가치 상승 -> 금값 하락

달러 강세이면 금이 약세이고, 달러 약세 및 저금리 장기화되면 금의 매력의 증가한다.

p 262

금은 안전 자산이 아니고, 실물 화폐의 성격을 갖고 있는 자신이다. 달러가 강해지면 주식시장이 무너지는데, 금은 포트폴리오 방어 효과를 주지 못한다. 결국 금의 방향성은 달러 정책과 유동성 환경에 크게 좌우 된다.

ㅁ PART 4 — 최종 정리

ㅇ 경기 침체 시나리오

- 달러 강세
- 자산 가격 조정
- 금리 변동성 확대
- 신용 스프레드 확대
-> 위기에 강한 자산의 역할이 중요해진다.

ㅇ 경기 회복 시나리오
- 무역 갈등 완화
- 자산 시장 분산 투자 환경
- 단일 자산 베팅의 위험 증가

ㅁ 에필로그

p347

이 책 전반에 걸쳐서 달러 투자는 '포트폴리오의 보험 컨셉'에서 접근. 금은 화폐 가치의 하락으로부터 내 투자 포트폴리오를 지킬 수 있는 자산이다. 어디까지나 전체 투자 포트폴리오에서 금과 달러를 감안할 필요가 있다. 특정 자산에 몰빵하지 말고, 주식, 채권을 나누고, 주시고가 채권의 분산만으로 커버할 수 없는 위기가 올 때에 금과 달러 자산이 큰 도움을 줄 수 있다.

ㅁ 마무리

나는 오건영의 설명 방식이 설득력을 가지는 이유가 다음과 같다고 본다.
그는 달러와 금을 이론이나 신념으로 설명하지 않는다.

실제 금리 변화, 달러 인덱스, 국채 수익률, 위기 당시의 자본 흐름 같은 실질적인 데이터의 맥락을 짚어가며

왜 그런 움직임이 나타났는지를 연결한다.

그래서 독자는 단순히 “달러가 안전하다”는 결론을 받아들이는 것이 아니라,

어떤 조건에서 달러가 강해지고 어떤 환경에서 금이 주목받는지를 스스로 이해하게 된다.

결국 그는 자산을 추천하는 사람이 아니라,

차트를 읽는 사고방식을 훈련시키는 사람에 가깝다고 느껴진다.

[AI] LLM 학습 노트 공개 - Transformer부터 RAG까지, 그리고 운영 가능한 AI 시스템을 향해

기록하는 백앤드개발자 — Tue, 10 Feb 2026 06:09:10 +0900

[AI] Peterica의 AI공부와 비젼 정리

ㅁ 들어가며

나는 백엔드 개발자로 시작했고, DevOps와 SRE 성격의 업무를 거치며 서비스 운영을 경험해 왔다.

그러다 최근 LLM 기반 시스템을 직접 설계하면서 관점이 바뀌었다.

AI는 더 이상 “모델 호출”이 아니라
운영 대상 시스템이라는 생각이 들기 시작했다.

그래서 개인적으로 LLM 학습 노트를 만들었다.
단순 이론 정리가 아니라, 실제 서비스를 만들고 운영한다는 관점에서 정리한 기록이다.

ㅁ 왜 LLM 학습 노트를 만들었나

처음에는 RAG 구현이 목적이었다.

하지만 파고들수록 느꼈다.

Retriever 품질은 Embedding과 Chunking에서 결정되고
RAG 성능은 VectorDB 튜닝과 Reranking에서 갈리며
최종 응답 품질은 결국 Transformer 구조와 Prompt 설계로 돌아온다

각각이 따로 존재하는 게 아니라, 하나의 파이프라인이었다.

그래서 다음 흐름으로 학습을 재구성했다.

Transformer → Embedding → VectorDB → RAG → Quantization

“모델”이 아니라 시스템 전체 흐름으로 이해하는 것이 목표였다.

ㅁ Month 1 학습 구성 요약

ㅇ Week 1: Transformer 완전 이해

주제	핵심 내용
[AI] Attention 메커니즘 — LLM은 어떻게 ‘중요한 정보’를 골라내는가	Self-Attention, Q/K/V, Multi-Head
[AI] Transformer Encoder-Decoder 구조 - Attention 다음 단계, 메커니즘에서 시스템으로	Encoder/Decoder 구조, Cross-Attention
[AI] KV Cache — LLM은 어떻게 ‘생각의 흐름’을 기억하는가	KV Cache 원리, 메모리 계산, 최적화

ㅇ Week 1 마무리 — Transformer 완전 이해
Week 1의 목표는 단순히 Transformer 구조를 외우는 게 아니었다.

Attention, Encoder–Decoder, KV Cache를 따라가다 보니
결국 하나의 질문으로 수렴했다.

“LLM은 어떻게 문맥을 이해하고, 생각을 이어가는가?”

답은 의외로 단순했다.

사람은 감각적으로 의미를 연결하고,
Transformer는 그 과정을 벡터와 확률로 계산한다.

Encoder는 문장을 의미 공간으로 압축하고,
Decoder는 그 공간 위에서 다음 토큰을 만들어내며,
KV Cache는 이미 지나온 사고 흐름을 기억한다.

표현 방식만 다를 뿐,
과거 맥락을 참고하고
현재 상태를 재해석하며
다음 생각을 만들어간다는 점에서
사람과 모델은 놀라울 만큼 닮아 있다.

그래서 내가 느낀 “Transformer 완전 이해”란,
모델 구조를 아는 것이 아니라
사람의 이해 방식이 어떻게 벡터로 구현되는지를 체감하는 과정이었다.

이제부터는 모델이 아니라,
이 의미 흐름이 Embedding, VectorDB, RAG로 어떻게 확장되는지를 살펴보려 한다.

ㅇ Week2: Embedding & Vector Database

주제	핵심 내용
[AI] Embedding 기초 - Transformer가 만든 의미를 저장하는 방법	임베딩 모델 비교, 선택 가이드
[AI] Chunking Strategy - 청크 전략과 크기 최적화, RAG 품질의 출발점	청크 전략, 크기 최적화
[AI] Vector Similarity — RAG에서 “가장 중요한 수학”	Cosine/Dot/L2 메트릭
[AI] HNSW - ANN부터 파라미터 튜닝까지, RAG 검색 성능의 진짜 핵심	HNSW 알고리즘, 파라미터 튜닝
[AI] Weaviate Usage - VectorDB를 “검색 엔진”이 아니라 “의미 저장소”로 쓰는 법	Weaviate 사용법, 하이브리드 검색
[AI] RAG용 VectorDB 튜닝	프로덕션 튜닝, 모니터링

[AI] Embedding부터 VectorDB까지, Week2 학습 내용 정리

ㅇ Week 3: RAG 구현 및 튜닝

문서	핵심 내용
[AI] RAG 파이프라인 전체 구조	RAG 파이프라인 전체 구조
[AI W3] RAG 기초 - Retriever(벡터, 키워드, Hybrid)	Dense/Sparse/Hybrid 검색
[AI W3] RAG 기초 - Ranker의 필요성	Cross-Encoder, Reranking
[AI W3] Reader(LLM) 프롬프트 설계와 Hallucination을 다루는 방법	LLM 프롬프트 설계, Hallucination 방지
05_End_To_End_RAG_Practice.md	실습 결과, 평가 지표

ㅇ Week 4: 양자화 & 모델 최적화

문서	핵심 내용
01_Quantization_Concepts	GPTQ/AWQ/GGUF, 양자화 원리
02_4bit_8bit_Performance	비트별 성능 비교, 품질 평가

중요한 건 “각 기술”이 아니라
이 기술들이 어떻게 연결되는지였다.

ㅁ RAG를 검색 기능이 아니라 지식 수명주기로 보기

실습을 하면서 가장 크게 바뀐 관점은 이것이다.

RAG는 검색 시스템이 아니다.
지식 수명주기 시스템이다.

그래서 다음 구조를 기본 전제로 잡았다.

사람이 검증한 SSOT(Single Source of Truth)
벡터는 파생 데이터
지식 변경 시 재임베딩 가능
Agent가 컨텍스트를 구성
실행 결과는 다시 지식으로 환류

즉,

지식 생성 → 정제 → 저장 → 검색 → 재생산

이 흐름이 끊기지 않아야 한다.

ㅁ 다음 단계: Multi-Agent + AI DevOps

Month 1은 “AI 기본기 + RAG”였다.

Month 2부터는 다음으로 확장한다.

Multi-Agent 구조
Tool Calling
Policy Chain / Guardrail
LLM Gateway

그리고 Month 3에서는

GPU Inference
KServe / Triton
OTEL 기반 LLM Tracing
Token Cost 모델링
SLO 설계

즉,

AI DevOps + Observability

단순히 모델을 잘 쓰는 게 아니라,
AI 서비스를 운영 가능한 플랫폼으로 만드는 것이 목표다.

ㅁ 마무리

이 학습 노트는 결과물이 아니라 과정 기록이다.

설계하고, 실패하고, 다시 구조를 바꾸는 반복 속에서
“내가 만들고 싶은 시스템의 형태”가 조금씩 명확해지고 있다.

나는 더 잘 코딩하는 개발자가 되고 싶은 게 아니라,

시스템을 설계하고
운영하고
진화시키는 엔지니어가 되고 싶다.

앞으로 Month 2, Month 3도 차근히 정리해 공유할 예정이다.

같은 고민을 하는 분들에게 참고가 되길 바란다.

[AI W3] Reader(LLM) 프롬프트 설계와 Hallucination을 다루는 방법

기록하는 백앤드개발자 — Tue, 10 Feb 2026 00:15:00 +0900

[AI] LLM 학습 노트 공개 - Transformer부터 RAG까지, 그리고 운영 가능한 AI 시스템을 향해

ㅁ 들어가며

RAG를 처음 붙였을 때 가장 쉽게 드는 생각은 이거다.

“문서는 잘 검색되는데, 왜 답변은 여전히 애매할까?”

Retriever도 튜닝했고, Ranker도 붙였고, 모델도 바꿔봤다.

그런데도 답변 품질은 기대만큼 올라가지 않는다.

이 지점에서 많은 사람이 LLM 성능을 의심한다.

하지만 실제로 문제의 원인은 대부분 Reader 단계,
정확히 말하면 프롬프트와 컨텍스트 구성에 있다.

이번 글에서는
RAG의 마지막 단계인 Reader를 단순한 “모델 호출”이 아니라
품질을 결정하는 최종 시스템 레이어로 바라보며,
프롬프트 설계와 Hallucination 문제를 어떻게 다뤄야 하는지 정리해본다.

ㅁ Reader는 왜 중요한가

RAG 파이프라인을 한 줄로 요약하면 이렇다.

Retriever → Ranker → Reader

앞단에서 아무리 좋은 문서를 가져와도
Reader가 그 문서를 제대로 읽지 못하면
RAG의 가치는 사라진다.

Reader의 역할은 단순하다.

주어진 컨텍스트를 바탕으로 답변을 생성하는 것.

하지만 이 단순한 역할 때문에 오히려 가장 많은 책임을 떠안는다.

문서가 많으면 많다고 문제고,
문서가 적으면 적다고 문제고,
문서가 애매하면 Hallucination이 발생한다.

그래서 Reader는
“LLM을 잘 고르는 문제”가 아니라
LLM이 사고할 수 있는 범위를 어떻게 제한할 것인가의 문제다.

ㅁ 프롬프트 설계의 본질

RAG에서 프롬프트 설계는 말을 예쁘게 쓰는 작업이 아니다.

프롬프트는 Reader에게 다음을 명확히 정의한다.

어떤 문서만 신뢰해야 하는지
문서에 없을 때 어떻게 행동해야 하는지
추론을 어디까지 허용하는지

즉, 프롬프트는
지식의 경계를 설정하는 제어 장치다.

그래서 RAG용 프롬프트에는 반드시 포함되어야 할 메시지가 있다.

제공된 문서만 사용한다
문서에 없는 내용은 답하지 않는다
모르면 모른다고 말한다

이 세 가지가 빠진 프롬프트에서
Hallucination은 구조적으로 발생할 수밖에 없다.

ㅁ Hallucination은 왜 생기는가

Hallucination은 흔히
“모델이 틀린 답을 만든다”라고 설명된다.

하지만 RAG 환경에서의 Hallucination은
대부분 모델 문제가 아니다.

원인은 훨씬 단순하다.

Reader가 참조 가능한 지식의 범위를 모른다
답할 수 없는 상황에 대한 규칙이 없다

이 상태에서 LLM은 침묵하는 대신 추론을 선택한다.

그래서 Hallucination은 모델 결함이 아니라
컨텍스트 경계가 흐릿할 때 발생하는 정상 동작에 가깝다.

ㅁ Lost in the Middle 문제

Reader를 다룰 때 반드시 고려해야 할 특성이 있다.

LLM은
컨텍스트의 처음과 끝에 있는 정보를
중간보다 더 잘 활용한다.

문서가 길어질수록 가장 중요한 정보가 중간에 묻히는 문제가 발생한다.

이게 바로 Lost in the Middle 현상이다.

그래서 RAG에서는 무조건 많은 문서를 넣는 것이 정답이 아니다.

정말 중요한 문서만 남기고

문서 수를 Top-3~5 수준으로 제한하고

필요하면 요약해서 전달한다

Reader에게 중요한 건
문서의 “양”이 아니라
집중할 수 있는 구조다.

ㅁ Context Window는 자원이 아니라 제약이다

Context Window가 커졌다고 해서
문제를 마음대로 밀어 넣을 수 있는 건 아니다.

오히려 컨텍스트가 길어질수록
토큰 비용은 증가하고
핵심 정보 활용률은 떨어진다.

그래서 Reader 단계에서는 항상 토큰 예산을 기준으로 생각해야 한다.

시스템 프롬프트
사용자 질의
문서 컨텍스트
답변 여유

이 네 가지가 하나의 고정된 예산 안에서 경쟁한다.

결국 Reader 튜닝이란

정보를 얼마나 줄일 수 있는가의 싸움이 된다.

ㅁ Reader는 생각보다 단순하다

많은 RAG 실패 사례를 보면 LLM에게 너무 많은 걸 기대하고 있다.

하지만 Reader는 의미를 “판단”하는 주체가 아니다.

판단은 Retriever와 Ranker에서 끝나야 하고
Reader는 그 결과를 언어로 표현할 뿐이다.

컨텍스트가 정확하면
모델은 생각보다 안정적으로 답한다.

반대로 컨텍스트가 흔들리면
어떤 모델을 써도 결과는 흔들린다.

그래서 Hallucination을 줄이는 가장 확실한 방법은
모델을 바꾸는 게 아니라
Reader 앞단을 정제하는 것이다.

ㅁ 핵심 개념 한 줄 정의

개념	정의
Reader	검색된 문서를 기반으로 답변을 생성하는 LLM
Context Window	LLM이 한 번에 처리할 수 있는 최대 토큰 수
Grounding	답변을 검색된 문서에 근거하도록 하는 기법
Citation	답변에 출처 문서를 명시하는 것
Hallucination	LLM이 문서에 없는 내용을 지어내는 현상
Lost in the Middle	긴 컨텍스트 중간에 있는 정보를 잘 활용하지 못하는 현상

ㅁ 마무리 – Reader를 시스템으로 바라본다는 것

Reader를 이해한다는 것은 프롬프트 템플릿을 외운다는 뜻이 아니다.

어디까지를 지식으로 인정할 것인가
언제 답변을 포기할 것인가
문서를 어떻게 배치할 것인가

이 결정들을 시스템 레벨에서 설계하는 것이다.

RAG에서 좋은 답변은 LLM이 만들어내는 게 아니다.

좋은 답변은
잘 정의된 컨텍스트와
명확한 사고 경계에서 나온다.

Reader는 그 경계를 지키는 마지막 관문이다.

[AI W3] RAG 기초 - Ranker의 필요성

기록하는 백앤드개발자 — Mon, 9 Feb 2026 06:43:26 +0900

[AI] LLM 학습 노트 공개 - Transformer부터 RAG까지, 그리고 운영 가능한 AI 시스템을 향해

ㅁ 들어가며 - Retriever 다음에 반드시 필요한 이유

앞선 글에서 Retriever를 정리하였다. Retriever는 빠르지만, 정확하지는 않다.

VectorDB 검색이든 BM25든, Retriever의 역할은 어디까지나 “후보군을 넓게 가져오는 것”이다.

보통 구조는 다음과 같다.

Retriever: 관련 있어 보이는 문서 Top-50 ~ 100
Ranker: 그중에서 정말 중요한 문서 Top-5 ~ 10

이 두 단계를 분리하지 않으면 속도와 정확도를 동시에 만족시키기 어렵다.

이번 글에서는
왜 Ranker가 필요한지,
그리고 Cross-Encoder 기반 Reranking이 왜 사실상 표준이 되었는지를 정리해본다.

ㅁ 왜 Ranker가 필요한가

Retriever 단계의 특징을 정리하면 명확하다.

속도 우선
대규모 문서 풀에서도 빠르게 검색
대신 순위 품질은 “대략적”

이 구조에서 자주 발생하는 문제는 이것이다.

정답 문서는 Top-100 안에는 있는데,
상위에 오지 않는다

LLM은 보통 상위 몇 개 문서만 사용한다.

즉, 정답이 있어도 아래에 깔려 있으면 없는 것과 같다.

그래서 중간에 한 단계가 더 필요해진다.

Retriever: “관련 있을 법한 문서 모으기”
Ranker: “이 중에서 진짜 중요한 순서 다시 매기기”

이 분리가 바로 RAG 검색 품질을 한 단계 끌어올리는 핵심이다.

ㅁ Bi-Encoder vs Cross-Encoder

이 차이를 이해하면 왜 Ranker가 느리지만 정확한지 바로 납득된다.

ㅇ Bi-Encoder (Retriever)

질의와 문서를 각각 따로 인코딩
벡터 간 유사도로 비교
빠르고 확장성 높음
대신 세밀한 문맥 비교는 어려움

ㅇ Cross-Encoder (Ranker)

질의와 문서를 한 번에 입력
토큰 단위 Attention으로 직접 비교
느리지만 훨씬 정확함

직관적으로 말하면,

Bi-Encoder는
“이 질문이랑 이 문서가 비슷해 보이네?”
Cross-Encoder는
“질문의 이 부분이 문서의 이 문장과 정확히 연결되네”

라는 차이다.

그래서 구조는 자연스럽게 이렇게 나뉜다.

Bi-Encoder → 대량 후보 추출
Cross-Encoder → 소수 후보 정밀 정렬

ㅁ Cross-Encoder 기반 Reranking 흐름

RAG 파이프라인에서 Ranker는 보통 이런 식으로 동작한다.

Retriever로 Top-K 문서 검색 (예: 100개)
질의-문서 쌍을 Cross-Encoder에 입력
관련도 점수 계산
점수 기준으로 재정렬
상위 N개만 LLM에 전달

핵심은 단순하다.

Ranker는 검색 결과를 “줄이는” 단계가 아니라
“순서를 바로잡는” 단계다.

ㅁ 주요 Reranker 모델 정리

실무에서 자주 쓰이는 모델만 정리해보면 다음과 같다.

ms-marco-MiniLM 계열
- 가볍고 빠름
- 영어 중심
- POC나 응답 속도가 중요한 환경에 적합
bge-reranker-v2-m3
- 다국어 지원
- 정확도 높음
- 온프레미스/자체 서빙에 적합
Cohere / Jina Rerank
- API 기반
- 운영 편의성 높음
- 비용 고려 필요

선택 기준은 결국 이 두 가지다.

문서 수와 언어
허용 가능한 지연 시간

ㅁ 성능 튜닝 관점에서의 Ranker

Ranker는 무조건 많이 쓰는 게 답이 아니다.

실무에서 자주 쓰는 기준은 다음 정도다.

Retriever: Top-50 ~ 100
Ranker 결과: Top-5 ~ 10
Ranker 지연 시간: 100~200ms 내

그리고 반드시 지켜야 할 원칙이 하나 있다.

**Ranker는 전체 검색 품질을 바꾸지

ㅁ 마무리

Ranker는 Retriever가 가져온 후보 문서를 정밀하게 재정렬하는 단계이다.

Cross-Encoder는 질의와 문서를 함께 인코딩해 높은 정확도를 제공

프로덕션 RAG는 Retriever(속도) + Ranker(정확도) 구조가 기본이 된다.

[AI W3] RAG 기초 - Retriever(벡터, 키워드, Hybrid)

기록하는 백앤드개발자 — Mon, 9 Feb 2026 06:12:29 +0900

[AI] LLM 학습 노트 공개 - Transformer부터 RAG까지, 그리고 운영 가능한 AI 시스템을 향해

ㅁ 들어가며

“LLM이 똑똑하면 답변도 좋아지겠지.”

하지만 실제로 RAG를 운영해보면, 품질 문제의 원인은 거의 항상 같은 지점에서 시작된다.

Retriever가 잘못된 문서를 가져온다.

아무리 좋은 LLM을 써도, 아무리 프롬프트를 다듬어도, 입력 컨텍스트가 틀리면 결과는 틀릴 수밖에 없다.

RAG에서도 결국 이 원칙이 그대로 적용된다.

Garbage In, Garbage Out

이번 글에서는 RAG 파이프라인의 첫 단계인
Retriever를 중심으로,

Dense 검색
Sparse 검색
Hybrid 검색

이 세 가지 방식이 왜 등장했고, 실무에서는 왜 Hybrid가 사실상 기본이 되었는지를 정리해본다.

ㅁ Retriever란 무엇인가

Retriever는 RAG 파이프라인의 첫 번째 단계다.

역할은 단순하다.

질의와 관련된 문서를 빠르게 찾아오는 것

하지만 이 “빠르게”와 “관련된”이라는 조건이 Retriever를 가장 어려운 컴포넌트로 만든다.

Retriever는 보통 다음 구조를 가진다.

질의와 문서를 각각 인코딩하는 Bi-Encoder 구조
대규모 문서 집합에서 Top-K 후보를 빠르게 검색
정확도보다 Recall을 우선하는 설계

즉, Retriever의 목표는 정답을 고르는 것이 아니라, 정답을 포함할 후보군을 놓치지 않는 것이다.

ㅁ Dense Retrieval — 의미를 기준으로 찾는다

Dense Retrieval은 임베딩 벡터 간의 유사도를 기준으로 문서를 검색한다.

작동 흐름은 비교적 단순하다.

질의를 임베딩 모델로 벡터화
사전에 계산된 문서 벡터들과 유사도 계산
가장 가까운 Top-K 문서 반환

이 방식의 핵심은 “같은 의미를 다른 표현으로 말해도 찾을 수 있다”는 점이다.

동의어, 유사 표현, 문장 구조가 달라도 의미가 비슷하면 검색된다.

그래서 일반적인 QA나 대화형 검색에서는 Dense Retrieval이 강력하다.

하지만 단점도 명확하다.

정확한 키워드 매칭에 약함
고유명사, 숫자, 코드 토큰에 취약
임베딩 모델 품질에 크게 의존

Dense 검색만으로 RAG를 구성하면, “비슷한 말은 찾는데, 정작 정확한 문서는 놓치는” 상황이 자주 발생한다.

ㅁ Sparse Retrieval — 키워드를 기준으로 찾는다

Sparse Retrieval은 BM25와 같은 키워드 기반 검색 방식이다.

이 방식은 의미를 이해하지 않는다. 대신 단어의 출현 빈도와 희귀성을 이용한다.

그래서 다음과 같은 경우에 강하다.

정확한 용어가 중요한 검색
법률, 계약, 정책 문서
코드, 함수명, 설정 키워드

BM25의 장점:

동작 방식이 직관적이다
결과를 설명하기 쉽다
계산이 빠르고 안정적이다

반면 단점도 분명하다.

의미적 유사성은 전혀 고려하지 않는다
동의어에 약하다
오타나 표현 변화에 취약하다

즉, Sparse 검색은 “정확한 단어가 맞을 때는 강하지만, 문맥에는 둔감하다.”

ㅁ Hybrid Search — 현실적인 타협이 아니라 기본 전제

Dense와 Sparse는 서로의 단점이 너무 명확하다.

그래서 실무에서는 자연스럽게 Hybrid Search로 수렴한다.

Hybrid Search의 핵심은 단순하다.

Dense: 의미를 놓치지 않기 위해
Sparse: 정확한 키워드를 놓치지 않기 위해

두 점수를 결합해 최종 순위를 만든다.

가장 흔한 방식은 선형 결합이다.

Dense 점수에 가중치를 주고, Sparse 점수에 나머지 가중치를 준다.

도메인에 따라 가중치는 달라진다.

일반 QA: 의미와 키워드 균형
법률/코드: 키워드 비중 증가
대화형 QA: 의미 비중 증가

중요한 점은, Hybrid는 “고급 옵션”이 아니라 프로덕션 RAG의 기본 형태라는 것이다.

ㅁ Retriever와 ANN — 빠른 검색은 근사다

Dense Retrieval이 가능하려면 대규모 벡터를 빠르게 검색할 수 있어야 한다.

여기서 등장하는 개념이 ANN(Approximate Nearest Neighbor)이다.

RAG에서 사용하는 벡터 검색은 정확한 최근접 탐색이 아니다.

대신,

빠른 속도
충분한 Recall

을 목표로 한 근사 검색이다.

실무에서는 HNSW가 사실상 표준처럼 쓰인다.

검색 속도와 품질의 균형
튜닝 가능한 파라미터
다양한 VectorDB에서 지원

Retriever 품질 문제는 결국 HNSW 파라미터 튜닝 문제로 이어지는 경우가 많다.

[AI] HNSW - ANN부터 파라미터 튜닝까지, RAG 검색 성능의 진짜 핵심

ㅁ 마무리 - Retriever는 선택지가 아니라 설계 영역이다

Retriever를 단순히 “검색 모듈 하나”로 보면 RAG는 계속 흔들린다.

Retriever는 다음 요소들이 수렴하는 지점이다.

Embedding
Chunking
Similarity Metric
ANN 인덱스
VectorDB 설정

그래서 RAG 품질은 모델보다, 프롬프트보다, Retriever 설계에서 가장 크게 갈린다.

Dense / Sparse / Hybrid 검색을 이해한다는 것은 기능을 고르는 게 아니라,

RAG 파이프라인의 첫 단추를 제대로 끼우는 일이다.

[AI] RAG 파이프라인 전체 구조

기록하는 백앤드개발자 — Mon, 9 Feb 2026 05:31:14 +0900

[AI] LLM 학습 노트 공개 - Transformer부터 RAG까지, 그리고 운영 가능한 AI 시스템을 향해

ㅁ 들어가며

RAG(Retrieval-Augmented Generation)를 처음 접했을 때는 구조가 단순해 보인다.

질문을 받고 → 문서를 찾고 → LLM에게 넘긴다.

그래서 자연스럽게 이렇게 생각하게 된다.

“LLM만 잘 고르고, 임베딩만 잘 쓰면 되는 거 아닐까?”

하지만 실제로 RAG를 붙여서 몇 번만 질의응답을 반복해보면
금방 다른 감각을 얻게 된다.

답변이 애매하다
근거 문서가 엉뚱하다
모델을 바꿔도 품질이 크게 나아지지 않는다

이때 문제는 대부분 LLM이 아니다.

RAG는 모델 기술이 아니라 아키텍처 문제에 가깝다.
이번 글에서는 RAG를 기능이 아닌 시스템 파이프라인으로 바라보며,
왜 구조 이해가 중요한지 정리해보려 한다.

ㅁ RAG를 한 줄로 요약하면

Retriever → Ranker → Reader

Retriever: 관련 문서를 빠르게 찾는다
Ranker: 그중에서 정말 중요한 문서를 고른다
Reader: 선택된 문서를 읽고 답변을 생성한다

중요한 점은 LLM(Reader)은 마지막 단계라는 것이다.
앞단이 흔들리면, 아무리 좋은 모델을 써도 결과는 흔들린다.

ㅁ Retriever - RAG 품질이 시작되는 지점

RAG 품질을 좌우하는 가장 중요한 컴포넌트는 Retriever다.

그리고 Retriever는 하나의 모듈이 아니다.
여러 설계 결정이 겹쳐진 결과물이다.

Retriever를 구성하는 요소를 풀어보면 다음과 같다.

문서를 어떻게 나눌 것인가 (Chunking)
의미를 어떻게 벡터로 표현할 것인가 (Embedding)
무엇을 “가깝다”고 판단할 것인가 (Similarity)
얼마나 정밀하게 탐색할 것인가 (ANN / HNSW)
이 모든 것을 어떻게 저장하고 운영할 것인가 (VectorDB)

즉, Retriever는
Week 2에서 다뤘던 모든 요소가 수렴하는 지점이다.

그래서 RAG에서 검색 품질이 낮을 때
모델보다 먼저 Retriever를 의심해야 한다.

ㅁ Dense, Sparse, 그리고 Hybrid Search

Retriever를 구현하는 방식은 크게 세 가지로 나뉜다.

Dense Retrieval: 벡터 유사도 기반 검색
Sparse Retrieval: BM25 같은 키워드 기반 검색
Hybrid Search: 두 방식을 결합

Dense 검색은 의미를 잘 잡지만,
고유명사나 숫자, 정확한 키워드에는 약하다.

반대로 Sparse 검색은 키워드에는 강하지만
의미적 유사성은 놓치기 쉽다.

그래서 실무에서는 대부분
Hybrid Search가 기본 전제가 된다.

이 단계의 목표는 단 하나다.

“정답을 포함할 가능성이 있는 후보군을 최대한 놓치지 않는 것”

ㅁ Ranker - 빠른 검색과 정확한 판단의 분리

Retriever는 속도가 우선이다.
그래서 결과는 “대략 맞는 후보군” 수준이다.

여기서 필요한 것이 Ranker(Reranker)다.

Ranker는 질의와 문서를 함께 비교해
정확한 순서를 다시 매긴다.

Retriever: 빠른 후보 생성 (Recall 중심)
Ranker: 정밀한 재정렬 (Precision 중심)

이 구조 덕분에
RAG는 속도와 정확도를 동시에 확보할 수 있다.

실무에서 RAG 품질이 한 단계 올라가는 순간은
대부분 Reranking을 붙였을 때다.

ㅁ Reader - LLM은 생각보다 단순하다

많은 경우 LLM이 너무 많은 책임을 떠안고 있다.

하지만 Reader의 역할은 명확하다.

주어진 컨텍스트를 바탕으로 답변을 생성하는 것

컨텍스트가 정확하면 모델은 비교적 안정적으로 답한다.

반대로 컨텍스트가 틀리면 환각은 구조적으로 발생한다.

그래서 Hallucination 문제는 프롬프트보다 검색과 컨텍스트 구성 문제인 경우가 많다.

ㅁ RAG는 검색 기능이 아니라 지식 파이프라인이다

RAG를 제대로 운영하려면
검색 기능이 아니라 지식 수명주기로 봐야 한다.

원본 문서는 SSOT(Source of Truth)
벡터는 언제든 재생성 가능한 파생 데이터
지식 변경 → 재임베딩 → 재인덱싱 가능해야 함

이 관점이 없으면 운영 중인 RAG는 빠르게 망가진다.

ㅁ 마무리 - RAG 아키텍처를 이해한다는 것

RAG를 이해한다는 것은 모델을 하나 더 붙이는 방법을 아는 게 아니다.

어디서 의미가 결정되는지
어디서 품질이 갈리는지
어디가 튜닝 포인트인지

이 흐름을 구조로 이해하는 것이다.

그래서 RAG 아키텍처의 핵심은 단순하다.

좋은 답변은 LLM이 아니라,
좋은 검색 파이프라인에서 시작된다.

[AI] RAG용 VectorDB 튜닝

기록하는 백앤드개발자 — Sun, 8 Feb 2026 17:30:45 +0900

[AI] LLM 학습 노트 공개 - Transformer부터 RAG까지, 그리고 운영 가능한 AI 시스템을 향해

ㅁ 들어가며

RAG를 처음 설계할 때는 자연스럽게 LLM과 Embedding에 시선이 간다.
하지만 실제로 RAG를 붙여서 질의응답을 반복해보면,
어느 순간 이런 느낌을 받게 된다.

“모델은 괜찮은데, 답변이 뭔가 애매하다”

이때 많은 경우 문제는 LLM이 아니다.
VectorDB 설정, 더 정확히 말하면 검색 튜닝에 있다.

이번 글에서는
RAG 파이프라인에서 VectorDB가 어떤 역할을 하고,
왜 튜닝이 성능을 좌우하는지,
그리고 어떤 기준으로 설정을 조정해야 하는지를 정리해보려 한다.

ㅁ RAG에서 VectorDB가 병목이 되는 이유

RAG의 흐름을 단순화하면 다음과 같다.

질문 → 임베딩 → VectorDB 검색 → 컨텍스트 구성 → LLM 응답

이 중 VectorDB는 단순한 저장소가 아니다.
검색 품질과 응답 속도를 동시에 책임지는 지점이다.

여기서 항상 충돌하는 두 가지 지표가 있다.

검색 정확도 (Recall)
응답 지연 (Latency)

검색 범위를 넓히면 더 정확해지지만 느려지고,
빠르게 응답하면 관련 문서를 놓치기 쉽다.

그래서 VectorDB 튜닝의 본질은

Recall과 Latency 사이의 균형점을 찾는 일
이라고 볼 수 있다.

ㅁ HNSW, RAG 검색의 사실상 표준

현재 대부분의 VectorDB는
HNSW(Hierarchical Navigable Small World) 알고리즘을 사용한다.

HNSW는 모든 벡터를 전부 비교하지 않고도,
그래프 탐색을 통해 근사 최근접 이웃(ANN) 을 빠르게 찾는 방식이다.

중요한 점은
HNSW는 “알고리즘 하나”라기보다
파라미터에 따라 성격이 완전히 달라지는 구조라는 것이다.

같은 데이터, 같은 임베딩이라도 설정값에 따라 결과 품질이 크게 달라진다.

ㅁ RAG에서 꼭 이해해야 할 핵심 파라미터

HNSW 튜닝에서 실제로 중요한 값은 많지 않다.
하지만 의미를 잘못 이해하면 튜닝 방향이 틀어진다.

ㅇ 튜닝을 위한 핵심 개념 한 줄 정의

개념	정의
ef (efConstruction)	HNSW 인덱스 빌드 시 탐색 범위 (높을수록 정확, 느림)
ef (efSearch)	HNSW 검색 시 탐색 범위 (높을수록 정확, 느림)
M (maxConnections)	HNSW 그래프의 연결 수 (높을수록 정확, 메모리 증가)
Recall@K	상위 K개 중 실제 관련 문서 비율
QPS	초당 처리 쿼리 수 (Queries Per Second)

efConstruction
인덱스를 만들 때 얼마나 정성 들여 구성할지를 결정한다.
빌드 시간과 인덱스 품질에 영향을 주며,
검색 성능에는 간접적으로 작용한다.

개발 단계에서는 낮게,
프로덕션에서는 한 번만 높게 설정하는 경우가 많다.

efSearch
검색 시 탐색하는 후보 벡터 수를 의미한다.
값이 커질수록 더 넓게 탐색하고, Recall은 좋아지지만 응답은 느려진다.

RAG 품질이 낮다고 느껴질 때
가장 먼저 조정해볼 수 있는 파라미터다.

M
각 노드가 가질 수 있는 연결 수를 의미한다.
그래프가 촘촘해질수록 검색 품질은 좋아지지만
메모리 사용량이 선형적으로 증가한다.

운영 환경에서는 보통
메모리 예산을 기준으로 상한을 먼저 정한다.

ㅁ Recall과 Latency, 피할 수 없는 선택

VectorDB 튜닝을 하다 보면 반드시 마주치는 현실이다.

efSearch를 올리면 → 정확하지만 느려진다
M을 올리면 → 정확하지만 메모리를 더 쓴다

그래서 중요한 것은
최대 성능이 아니라, 서비스 요구사항에 맞는 성능이다.

RAG는 연구용 시스템이 아니라 운영 대상 시스템이기 때문이다.

ㅁ 청크 크기와 VectorDB 튜닝의 관계

VectorDB 설정만 바꾼다고 모든 문제가 해결되지는 않는다.
청크 전략이 함께 맞지 않으면 효과가 제한적이다.

작은 청크
- 검색은 정밀하지만 컨텍스트가 잘게 쪼개진다
큰 청크
- 컨텍스트는 풍부하지만 검색 정확도가 떨어질 수 있다

일반적인 RAG에서는
256~512 토큰 + overlap 구성이 가장 안정적인 경우가 많았다.

VectorDB 튜닝과 청크 전략은 항상 함께 봐야 한다.

ㅁ 프로덕션 관점에서의 튜닝 기준

운영 환경에서는 한 번의 튜닝으로 끝나지 않는다.

지속적으로 확인해야 할 지표는 다음과 같다.

p50 / p95 / p99 검색 Latency
Recall@K 추정치
QPS 증가 시 성능 변화
메모리 사용량

정적인 설정값보다 중요한 것은 조정 가능한 구조와 관측 가능한 지표다.

ㅁ Week 2를 관통하며 정리한 결론

Week 2를 관통하며 하나의 결론에 도달했다.

Embedding, Chunking, Similarity, HNSW를 각각 따로 보면 개별 기술처럼 보이지만,
실제 RAG에서는 이 모든 요소가 Retriever라는 하나의 품질로 수렴한다.

RAG 품질은
모델보다, Embedding보다, Prompt보다
Retriever 설계에서 가장 크게 갈린다.

그리고 Retriever의 품질은 결국 다음 요소들로 정리된다.

- Chunking 전략
- Similarity 메트릭
- ANN(HNSW) 파라미터
- VectorDB 인덱스 설정과 운영 전략

즉, RAG용 VectorDB 튜닝은
선택 가능한 옵션이 아니라 처음부터 전제로 깔고 가야 할 필수 설계 영역이다.

ㅁ 마무리

RAG 품질이 기대에 미치지 못할 때,
많은 경우 가장 먼저 LLM이나 임베딩 모델을 의심한다.

하지만 실제로는
VectorDB 설정 하나로 결과가 극적으로 달라지는 경우가 많다.

VectorDB는 단순한 저장소가 아니라,
RAG의 검색 품질을 결정하는 핵심 컴포넌트다.

모델을 바꾸기 전에,
VectorDB 튜닝부터 점검해보는 것이 운영 관점에서 훨씬 합리적인 선택일 수 있다.

[AI] Embedding부터 VectorDB까지, Week2 학습 내용 정리

기록하는 백앤드개발자 — Sun, 8 Feb 2026 16:55:40 +0900

[AI] LLM 학습 노트 공개 - Transformer부터 RAG까지, 그리고 운영 가능한 AI 시스템을 향해

ㅁ 들어가며

Week 2에서는 Embedding부터 VectorDB까지,
RAG 시스템의 검색 품질을 결정하는 핵심 요소들을 하나씩 정리해 왔다.

처음에는 단순히
“임베딩을 만들고, 벡터 검색을 하면 되겠지”라고 생각했다.

하지만 실제로 파고들어 보니 전혀 아니었다.

Embedding
→ Chunking
→ Vector Similarity
→ ANN(HNSW)
→ VectorDB 구조와 튜닝

이 모든 요소가 하나의 검색 파이프라인으로 연결되어 있었고,
어느 하나라도 잘못 설계되면 RAG 품질은 바로 무너졌다.

이번 글에서는
그동안 쪼개서 정리했던 내용을 다시 묶어,

Week 2: Embedding & Vector Database를 총체적으로 어떻게 이해하게 되었는지
정리해 보려고 한다.

ㅁ Week 2의 출발점: “의미를 어떻게 저장할 것인가”

Week 2의 시작은 아주 단순한 질문이었다.

Transformer가 만들어낸 ‘의미’를
우리는 어디에, 어떤 형태로 저장해야 할까?

이 질문에 대한 답으로 가장 먼저 정리한 글이 아래였다.

[AI] Embedding 기초 — Transformer가 만든 의미를 저장하는 방법

이 글에서 정리한 핵심은 이것이다.

임베딩은 단순한 숫자 배열이 아니다
문장, 문단, 문서의 의미 좌표다
VectorDB는 이 좌표를 저장하고 탐색하는 시스템이다

즉,
RAG에서 검색이란 “문서를 찾는 행위”가 아니라
의미 공간에서 가까운 좌표를 찾는 문제였다.

이것은 마치 우리가 생각을 할 때에 그 흐름이 어느 주제와 가깝다고 느끼는 것을 의미 공간으로 표현한다.

ㅁ Chunking: VectorDB 성능은 여기서 이미 결정된다

Embedding을 이해하고 나니,
다음 질문은 자연스럽게 이어졌다.

그럼, 무엇을 하나의 벡터로 만들 것인가?

이 질문이 바로 Chunking 문제다.

이를 정리한 글이 다음이다.

[AI] Chunking Strategy — 청크 전략과 크기 최적화, RAG 품질의 출발점

이 과정을 통해 확실히 느낀 점은 하나였다.

Chunking은 전처리가 아니라 Retriever 설계 그 자체다.

Chunk가 너무 작으면 → 의미는 정확하지만 맥락이 깨지고
Chunk가 너무 크면 → 맥락은 좋지만 검색 정확도가 떨어진다

즉,
Chunking은 Recall과 Context 품질 사이의 첫 번째 트레이드오프였다.

ㅁ Vector Similarity: “가장 중요한 수학”

Chunk를 만들고 벡터를 저장했다면, 이제 남은 질문은 이것이다.

“가깝다”는 걸 어떻게 정의할 것인가?

이를 다룬 글이 다음이다.

[AI] Vector Similarity — RAG에서 ‘가장 중요한 수학’

Cosine, Dot Product, L2 Distance는 모두 “두 벡터가 얼마나 비슷한가”를 재는 방법이지만,

"무엇을 기준으로 비슷하다고 판단하느냐"가 다르다.

Cosine Similarity는 벡터의 방향만 본다. 길이는 무시하고, 같은 방향을 향하면 비슷하다고 본다.

그래서 문서 길이가 다르더라도 의미만 비교하고 싶을 때 적합하다.

Dot Product는 방향과 함께 벡터의 크기까지 반영한다. 같은 방향이면서 크기가 클수록 점수가 커지기 때문에, 의미 유사성과 동시에 “강도”나 “중요도”까지 포함한 비교에 가깝다.

반면 L2 Distance는 완전히 다른 관점이다. 두 벡터 사이의 물리적인 거리를 잰다. 좌표 공간에서 얼마나 멀리 떨어져 있는지를 보는 방식이라, 값의 스케일에 매우 민감하다.

직관적으로 말하면,

Cosine은 “같은 방향을 보고 있나”,

Dot은 “같은 방향 + 얼마나 세게인가”,

L2는 “서로 얼마나 떨어져 있나”를 묻는 질문이다.

RAG나 VectorDB에서 Cosine이 많이 쓰이는 이유는,

우리가 보통 의미의 방향을 비교하고 싶지,

문장의 길이나 벡터 크기 자체를 비교하고 싶은 경우는 드물기 때문이다.

Cosine, Dot Product, L2 Distance를 정리하면서

한 가지 중요한 사실을 깨달았다.

대부분의 임베딩 모델은 방향 정보가 핵심이다
RAG 검색에서는 크기보다 의미 방향이 중요하다
그래서 Cosine Similarity가 사실상 표준처럼 쓰인다

그리고 더 중요한 결론은 이것이었다.

임베딩이 L2 정규화되어 있다면
Cosine, Dot Product, L2 Distance는 거의 같은 의미를 가진다.

즉,
모델 학습 방식과 메트릭 선택은 분리해서 볼 수 없다.

ㅁ ANN과 HNSW: 정확한 검색은 불가능하다

Vector Similarity를 이해하고 나니
또 하나의 현실적인 벽을 마주하게 된다.

벡터가 수백만 개라면,
매번 정확한 최근접 탐색이 가능할까?

대답은 명확하다.

불가능하다.

그래서 등장하는 개념이 ANN(Approximate Nearest Neighbor)이고,
그중 실무에서 가장 많이 쓰이는 구조가 HNSW다.

이를 정리한 글이 다음이다.

[AI] HNSW — ANN부터 파라미터 튜닝까지, RAG 검색 성능의 진짜 핵심

이 글을 통해 관점이 완전히 바뀌었다.

VectorDB 검색은 정확한 검색이 아니다
항상 Recall과 Latency의 트레이드오프 위에 있다
ef, M 같은 파라미터는 “옵션”이 아니라 품질 레버다

즉,
RAG에서 “검색이 느리다 / 잘 못 찾는다”는 문제는
대부분 HNSW 튜닝 문제로 귀결된다.

ㅁ VectorDB: 검색 엔진이 아니라 “의미 인프라”

여기까지 이해하고 나서야
비로소 VectorDB를 제대로 바라볼 수 있게 되었다.

이를 Weaviate를 기준으로 정리한 글이 다음이다.

[AI] Weaviate Usage — VectorDB를 ‘검색 엔진’이 아니라 ‘의미 저장소’로 쓰는 법

이 글을 쓰면서 확신하게 된 점은 이것이다.

VectorDB는 데이터베이스라기보다
의미 공간을 유지·탐색하는 인프라에 가깝다.

벡터는 파생 데이터다
원본 문서가 SSOT(Source of Truth)다
재임베딩과 재인덱싱은 언제든 가능해야 한다

즉,
VectorDB는 RAG 파이프라인에서
후보 생성기(Retriever) 역할을 맡는다.

ㅁ 그래서, RAG용 VectorDB 튜닝이 왜 중요한가

Week 2를 통해 Embedding부터 VectorDB까지의 흐름을 정리하며 한 가지 결론에 도달했다.

RAG 품질은
모델, Embedding, Prompt보다
Retriever 설계에서 가장 크게 갈린다.

그리고 Retriever의 품질은 결국 다음 요소들로 수렴한다.

문서를 어떻게 나누는가 (Chunking 전략)
의미를 어떻게 비교하는가 (Similarity 메트릭)
얼마나 정밀하게 탐색하는가 (ANN / HNSW 파라미터)
이를 어떤 기준으로 운영하는가 (VectorDB 인덱스와 튜닝 전략)

즉, VectorDB는 단순한 저장소가 아니라
RAG 검색 품질을 결정하는 핵심 설계 영역이다.

그리고 RAG용 VectorDB 튜닝은 ‘옵션’이 아니라 필수 설계 영역이다.

이 결론을 바탕으로 실제 RAG 환경에서 VectorDB를 어떻게 튜닝하고 운영해야 하는지를
[AI] RAG용 VectorDB 튜닝에 정리하였다.

[AI] Weaviate Usage - VectorDB를 “검색 엔진”이 아니라 “의미 저장소”로 쓰는 법

기록하는 백앤드개발자 — Sun, 8 Feb 2026 16:03:23 +0900

[AI] LLM 학습 노트 공개 - Transformer부터 RAG까지, 그리고 운영 가능한 AI 시스템을 향해

ㅁ 들어가며

앞선 글에서 Embedding, Vector Similarity, HNSW까지 정리했다면,
이제 실제 VectorDB를 어떻게 쓰는지가 남는다.

이번 글에서는 Weaviate를 기준으로,

스키마 설계
데이터 삽입 흐름
벡터 검색
하이브리드 검색(BM25 + Vector)

을 정리한다.

중요한 점은 이것이다.

Weaviate는 단순한 벡터 저장소가 아니라,
“의미 기반 데이터 모델링 + 검색 엔진” 에 가깝다.

ㅁ 왜 Weaviate인가

VectorDB는 많다.
Qdrant, Milvus, Pinecone 등 선택지는 충분하다.

일전에 [AI] RAG구성을 위한 FAISS란?에서 FAISS를 정리하기도 하였다.

[AI] IntentFlow 프로젝트 회고 및 소개에서 실제로 사용해 보기도 하였다.

Weaviate의 특징은 다음이다.

스키마 기반 데이터 모델
GraphQL 중심 쿼리
자동 벡터화 모듈
하이브리드 검색을 네이티브로 지원

특히 RAG 관점에서는
BM25 + Vector를 자연스럽게 섞을 수 있다는 점이 크다.

즉,

키워드 검색과 의미 검색을
“둘 중 하나”가 아니라
“같이” 가져갈 수 있다.

ㅁ 기본 구조 이해하기

Weaviate는 관계형 DB처럼 Class 기반 스키마를 가진다.

개념을 간단히 정리하면:

Class: 테이블
Property: 컬럼
Object: 로우
Vectorizer: 자동 임베딩 모듈

RAG용 문서 저장 시 보통 이런 구조를 쓴다.

content (텍스트)
source (파일명)
chunk_id (청크 번호)

즉, Chunk 단위 객체를 저장하는 방식이다.

ㅁ 로컬 실행 (Docker)

version: '3.4'

services:
  weaviate:
    image: semitechnologies/weaviate:1.24.1
    ports:
      - "8080:8080"
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      DEFAULT_VECTORIZER_MODULE: 'text2vec-openai'
      ENABLE_MODULES: 'text2vec-openai,generative-openai'
      OPENAI_APIKEY: ${OPENAI_API_KEY}
      CLUSTER_HOSTNAME: 'node1'
    volumes:
      - weaviate_data:/var/lib/weaviate

volumes:
  weaviate_data:

실행:

docker-compose up -d

확인:

curl http://localhost:8080/v1/meta

ㅁ Python 클라이언트 연결

import weaviate

client = weaviate.Client("http://localhost:8080")
print(client.is_ready())

ㅁ 스키마 정의

RAG용 Document 클래스 예시는 다음과 같다.

class_obj = {
    "class": "Document",
    "vectorizer": "text2vec-openai",
    "properties": [
        {
            "name": "content",
            "dataType": ["text"]
        },
        {
            "name": "source",
            "dataType": ["string"]
        },
        {
            "name": "chunk_id",
            "dataType": ["int"]
        }
    ]
}

client.schema.create_class(class_obj)

여기서 핵심은:

content 필드는 자동으로 임베딩된다.

즉, 애플리케이션에서 직접 embedding을 만들지 않아도 된다.

ㅁ 데이터 삽입

단일 삽입도 가능하지만, 실무에서는 반드시 batch를 쓴다.

with client.batch as batch:
    batch.batch_size = 100
    for doc in documents:
        batch.add_data_object(
            data_object={
                "content": doc["content"],
                "source": doc["source"],
                "chunk_id": doc["chunk_id"]
            },
            class_name="Document"
        )

이 단계에서 Weaviate는:

텍스트 벡터화
HNSW 인덱싱
객체 저장

을 자동으로 처리한다.

ㅁ 벡터 검색

result = (
    client.query
    .get("Document", ["content", "source"])
    .with_near_text({"concepts": ["RAG system architecture"]})
    .with_limit(5)
    .do()
)

질문을 넣으면:

쿼리를 벡터화
HNSW로 근접 벡터 탐색
Top-K 반환

전형적인 Dense Retrieval 흐름이다.

ㅁ 하이브리드 검색 (BM25 + Vector)

Weaviate의 핵심 기능.

result = (
    client.query
    .get("Document", ["content", "source"])
    .with_hybrid(
        query="RAG pipeline",
        alpha=0.5
    )
    .with_limit(5)
    .do()
)

alpha 의미:

0.0 → BM25 only
1.0 → Vector only
0.5 → 균형

실무에서는 보통 0.4~0.6 사이에서 시작한다.

이 방식의 장점은:

키워드 정확도 유지
의미 검색 보완

즉,
Sparse + Dense를 자연스럽게 결합한다.

ㅁ 메타데이터 필터링

.with_where({
    "path": ["source"],
    "operator": "Equal",
    "valueString": "rag_guide.md"
})

RAG에서는 보통:

source
doc_type
tenant

같은 필드를 함께 필터링한다.

Retriever는 항상 “의미 + 조건”을 동시에 고려해야 한다.

ㅁ 운영 관점 팁

실무에서 중요한 포인트만 정리하면:

반드시 batch insert 사용
HNSW ef 값 튜닝
자주 쓰는 필드는 필터 인덱싱
alpha는 온라인 실험으로 결정
벡터는 파생 데이터로 취급 (원본 문서가 SSOT)

VectorDB는 검색 엔진이 아니다.

의미 공간 인덱스다.

ㅁ RAG 파이프라인에서 Weaviate의 위치

전체 흐름은 항상 같다.

Document
→ Chunk
→ Weaviate 저장
→ Hybrid Retrieval
→ Rerank
→ LLM

Weaviate는 이 중 “의미 좌표계 + 후보 생성” 을 담당한다.

최종 품질은 Reranker와 Prompt에서 결정되지만,
Retriever 품질이 바닥이면 그 위는 아무 의미가 없다.

ㅁ 마무리

Weaviate를 써보면서 느낀 점은 이것이다.

VectorDB는 데이터베이스가 아니라 의미 인프라다.

RAG 품질은 모델보다,

Embedding보다,

Chunking보다,

Retriever 설계에서 가장 크게 갈린다.

그리고 Weaviate는
그 Retriever를 꽤 높은 수준으로 구성할 수 있게 해준다.

[AI] HNSW - ANN부터 파라미터 튜닝까지, RAG 검색 성능의 진짜 핵심

기록하는 백앤드개발자 — Sun, 8 Feb 2026 15:01:20 +0900

[AI] LLM 학습 노트 공개 - Transformer부터 RAG까지, 그리고 운영 가능한 AI 시스템을 향해

ㅁ 들어가며

ANN과 HNSW는 VectorDB를 활용한 RAG 구현의 “심장”이다.

Embedding은 의미를 벡터로 바꿔주고,
Vector Similarity는 거리를 계산해 주지만,

수백만 개 벡터 중에서 실제로 무엇을 얼마나 빨리 찾을 수 있느냐는
결국 ANN 인덱스가 결정한다.

그 중심에 있는 알고리즘이 바로 HNSW다.

이번 글에서는 다음 흐름으로 정리해 보려 한다.

ANN이 무엇인지
왜 Brute-force 검색이 불가능한지
HNSW가 어떻게 문제를 해결하는지
그리고 실무에서 중요한 파라미터(M, ef)를 어떻게 바라봐야 하는지

ㅁ ANN이란 무엇인가

ANN은 Approximate Nearest Neighbor의 약자다.
직역하면 “근사 최근접 이웃 탐색”.

완벽한 정답 대신, 충분히 가까운 결과를 매우 빠르게 찾는 방식

벡터 검색에서 정확한 최근접 이웃(Exact NN)을 찾으려면 모든 벡터와 거리를 계산해야 한다.

벡터가 N개라면:

시간 복잡도: O(N)
100만 개 → 가능
1억 개 → 거의 불가능

RAG에서는 이런 규모가 기본이다. 그래서 우리는 선택을 해야 한다.

100% 정확한 검색을 포기하고,
95~98% 정도의 Recall을 얻는 대신
수천 배 빠른 검색을 택한다.

이게 ANN의 철학이다.

ㅁ 왜 HNSW가 필요할까

VectorDB는 단순 저장소가 아니다.

의미 공간 탐색기다.

질문 벡터가 들어오면:

가장 가까운 의미 좌표들을 찾고
그 결과를 LLM에 넘긴다

문제는 “어떻게 빠르게 찾느냐”다.

대표적인 방식은 세 가지다.

Flat (Brute-force)
IVF
HNSW

Flat은 정확하지만 느리고,
IVF는 빠르지만 품질 손실이 있고,
HNSW는 속도와 Recall의 균형이 가장 좋다.

그래서 대부분의 VectorDB가 기본 인덱스로 HNSW를 채택한다.

ㅁ HNSW 한 줄 요약

HNSW(Hierarchical Navigable Small World)는
계층적 그래프 구조를 이용해
고차원 벡터 공간을 빠르게 탐색하는 ANN 알고리즘이다.

핵심 아이디어는 이것이다.

위에서는 대충 찾고
아래에서 정밀하게 찾는다

지도 앱과 매우 비슷하다.

고속도로 → 일반도로 → 골목길

ㅁ HNSW의 구조 — 왜 “계층적 그래프”인가

HNSW는 여러 레벨의 그래프로 구성된다.

상위 레벨: 노드 수 적음, 연결 길음 (대략 탐색)
하위 레벨: 모든 노드 존재, 촘촘한 연결 (정밀 탐색)

검색 흐름은 다음과 같다.

최상위 레벨에서 시작
greedy하게 더 가까운 노드로 이동
더 이상 개선이 없으면 한 레벨 내려감
최하위 레벨에서 후보를 충분히 탐색
상위 K개 반환

이 구조 덕분에 탐색 깊이는 O(log N) 수준으로 줄어든다.

ㅁ HNSW의 핵심 파라미터 3가지

HNSW 튜닝의 본질은 딱 세 개다.

M
ef_construction
ef_search

이 세 값이 Recall / Latency / Memory를 모두 결정한다.

ㅁ M — 그래프의 밀도

M은 각 노드가 가질 수 있는 최대 이웃 수다.

작으면: 메모리 적음, Recall 낮음
크면: 메모리 큼, Recall 높음

직관적으로:

M은 “길의 개수”다.

길이 많을수록 목적지에 도달할 확률은 높아지지만,
지도는 무거워진다.

실무 기준:

RAG 기본: 16~32
프로덕션 권장: 24

ㅁ ef_construction — 인덱스 품질

인덱스를 만들 때
각 벡터가 연결될 후보를 얼마나 넓게 볼지 정하는 값이다.

낮으면: 빌드 빠름, 그래프 품질 낮음
높으면: 빌드 느림, 그래프 품질 높음

중요한 포인트:

ef_construction은 인덱스 생성 시에만 사용된다.
즉, 한 번 제대로 만들어 두는 게 중요하다.

권장 범위:

128 ~ 200

ㅁ ef_search — 검색 품질 (런타임 조절 가능)

검색 시 탐색할 후보 개수다.

이 값이 클수록:

Recall 상승
Latency 증가

작을수록:

빠르지만 부정확

핵심 장점:

ef_search는 쿼리마다 바꿀 수 있다.

즉,

일반 질문: ef_search=100
고품질 질문: ef_search=200

같은 식의 동적 튜닝이 가능하다.

RAG 권장 시작점:

ef_search = 100

ㅁ 실무에서 추천하는 기본 세트

RAG 기준 최소 출발점:

M = 24
ef_construction = 200
ef_search = 100

여기서 시작해서:

Recall 측정
느리면 ef_search 감소
품질 부족하면 ef_search 증가
그래도 부족하면 M 증가 (재인덱싱 필요)

이 순서가 가장 현실적이다.

ㅁ 중요한 정리

HNSW는 “알고리즘”이 아니라
“트레이드오프 컨트롤러”에 가깝다.

항상 세 가지를 교환한다.

Recall
Latency
Memory

완벽한 값은 없다.

서비스 요구사항에 맞는 균형점을 찾는 게 전부다.

ㅁ RAG 관점에서 다시 보기

RAG 파이프라인은 이렇게 이어진다.

Transformer
→ Embedding
→ Chunking
→ Vector Similarity
→ ANN(HNSW)
→ Retriever
→ Reranker
→ LLM

여기서 HNSW는 Retriever의 실제 성능을 결정한다.

아무리 좋은 임베딩을 써도, HNSW가 엉성하면 결과는 바로 무너진다.

ㅁ 마무리

처음에는 ANN이 그냥 “빠른 검색 기술”이라고 생각했다.

지금은 이렇게 느낀다.

HNSW는 RAG의 검색 품질을 설계하는 도구다.

모델보다,
프롬프트보다,
심지어 임베딩보다 먼저 봐야 할 것이
ANN과 HNSW 파라미터다.

RAG는 모델 문제가 아니라 시스템 문제다.

그리고 HNSW는 그 시스템의 중심에 있다.

[AI] Vector Similarity — RAG에서 “가장 중요한 수학”

기록하는 백앤드개발자 — Sun, 8 Feb 2026 01:00:23 +0900

[AI] LLM 학습 노트 공개 - Transformer부터 RAG까지, 그리고 운영 가능한 AI 시스템을 향해

ㅁ 들어가며

Embedding 글에서 이야기했던 핵심은 이것이었다.

Transformer가 만든 의미를 벡터로 “저장”했다면,
이제 남은 문제는 하나다.

이 벡터들을 어떻게 비교할 것인가.

많은 RAG 튜토리얼은 “임베딩하고 VectorDB에 넣으면 된다”에서 끝난다.

하지만 실제로 시스템을 만들어 보면 곧 느끼게 된다.

모델보다,
임베딩보다,
심지어 Chunking보다도

Similarity Metric이 검색 품질을 크게 좌우한다는 사실을.

Vector Similarity는 단순한 계산 공식이 아니다.

RAG에서 Vector Similarity는 곧,

의미를 어떻게 해석할 것인가에 대한 설계다.

ㅁ Vector Similarity란 무엇인가

Vector Similarity는 두 벡터가 얼마나 “가까운지”를 계산하는 방식이다.

조금 더 정확히 말하면,

두 문장이 의미 공간에서 얼마나 비슷한 위치에 있는지를 측정하는 방법이다.

중요한 점은 이것이다.

임베딩 벡터 자체보다 더 중요한 것은
그 벡터를 비교하는 방식이다.

같은 임베딩을 써도,
Similarity Metric이 달라지면 검색 결과가 달라진다.

그래서 Vector Similarity는 검색 알고리즘이 아니라
의미 해석 방식에 가깝다.

ㅁ 대표적인 세 가지 유사도 메트릭

실무에서 가장 많이 쓰이는 메트릭은 세 가지다.

Cosine Similarity
Dot Product
L2 Distance

수식보다 직관이 중요하다.

ㅁ Cosine Similarity — 방향만 본다

Cosine Similarity는 두 벡터의 각도를 비교한다.

크기는 무시하고,
방향만 본다.

즉,

두 문장이 같은 “의미 방향”을 가리키고 있는지를 판단한다.

그래서 문서 길이나 정보량의 영향을 덜 받는다.

실무에서 RAG에 가장 널리 쓰이는 이유도 여기에 있다.

문서가 길어도
Chunk 크기가 조금 달라도

의미 패턴만 비슷하면 가까운 것으로 판단된다.

대부분의 텍스트 임베딩 모델이 Cosine 기준으로 사용되는 것도 같은 이유다.

ㅁ Dot Product — 방향 + 크기

Dot Product는 방향뿐 아니라 벡터 크기까지 함께 반영한다.

직관적으로 보면,

의미가 비슷하면서, 정보량이 많은 쪽이 더 크게 평가된다.

추천 시스템이나 랭킹 모델에서 자주 사용된다.

다만 텍스트 RAG에서는 주의가 필요하다.

Chunk가 길어질수록 값이 커질 수 있기 때문이다.

정규화를 하지 않으면
“길이가 긴 문서가 유리해지는” 현상이 발생할 수 있다.

ㅁ L2 Distance — 실제 공간 거리

L2 Distance는 두 벡터 사이의 실제 유클리드 거리를 잰다.

좌표 간의 절대 거리다.

클러스터링이나 이상 탐지에는 직관적이지만,
고차원 텍스트 임베딩에서는 안정성이 떨어질 수 있다.

그래서 일반적인 문서 RAG에서는 Cosine보다 덜 쓰인다.

ㅁ 중요한 사실 — 정답은 없다

Vector Similarity에서 가장 중요한 사실은 이것이다.

어느 메트릭이 “더 좋다”는 정답은 없다.

대신, 항상 다음을 함께 고려해야 한다.

임베딩 모델이 어떤 방식으로 학습됐는지
벡터가 정규화되어 있는지
Chunk 크기
문서 길이
언어 특성

예를 들어,

L2 정규화를 한 벡터에서는:

Cosine Similarity = Dot Product
L2 Distance도 Cosine과 수학적으로 연결된다

즉, 조건에 따라 세 메트릭은 사실상 같은 의미가 되기도 한다.

그래서 Similarity 선택은 공식 문제가 아니라
시스템 조건에 맞춘 설계 문제다.

ㅁ 실무에서 느낀 가장 큰 차이

직접 RAG 파이프라인을 만들면서 가장 크게 느낀 점은 이것이었다.

Embedding 모델을 바꿔도 품질 변화는 크지 않았다.
Chunking을 바꾸면 체감이 됐다.
Similarity를 바꾸면 결과가 즉각 달라졌다.

그래서 요즘은 이렇게 생각한다.

LLM 성능보다 Embedding,
Embedding보다 Chunking,
Chunking보다 Similarity 설계가 더 중요하다.

Vector Similarity는 Retriever의 심장이다.

Retriever 품질이 곧 RAG 품질이다.

ㅁ VectorDB는 검색 엔진이 아니다

Embedding 글에서도 이야기했지만,
다시 정리하면 이렇다.

VectorDB는 검색 엔진이 아니다.

의미 공간 탐색기다.

흐름은 항상 같다.

질문 → 벡터화
→ 거리 계산
→ 가장 가까운 의미 좌표 선택

SQL처럼 조건을 필터링하는 게 아니라,
지도에서 가장 가까운 지점을 찾는 구조다.

그래서 Similarity Metric은

“정렬 옵션”이 아니라
지도 좌표계를 어떻게 정의하느냐의 문제다.

ㅁ Similarity는 RAG 전체 파이프라인의 일부다

Vector Similarity는 단독으로 존재하지 않는다.

항상 이 흐름 안에 있다.

Transformer → Embedding → Chunking
→ Vector Similarity → Retriever
→ Reranker → LLM

Similarity는 Retriever의 중심이고, Retriever는 RAG 품질의 핵심이다.

그래서 Similarity를 이해하지 못하면 RAG를 이해했다고 보기 어렵다.

ㅁ 마무리

Similarity는 수학이 아니라 설계다

Vector Similarity는 공식 암기 문제가 아니다.

의미를 어떻게 나누고,
어떻게 비교하고,
어떻게 연결할 것인가에 대한 설계 문제다.

좋은 RAG는 모델에서 나오지 않는다.

의미를 다루는 방식에서 나온다.

[AI] Chunking Strategy - 청크 전략과 크기 최적화, RAG 품질의 출발점

기록하는 백앤드개발자 — Fri, 6 Feb 2026 22:00:11 +0900

[AI] LLM 학습 노트 공개 - Transformer부터 RAG까지, 그리고 운영 가능한 AI 시스템을 향해

ㅁ 들어가며

Embedding 글을 정리하면서 자연스럽게 다음 질문에 도달했다.

“그래서, 우리는 무엇을 벡터로 저장하는가?”

Embedding은 의미를 벡터로 만든다.
하지만 Chunking은 그 이전 단계다.

Chunking은 단순히 텍스트를 자르는 기술이 아니라,
LLM이 이해할 수 있는 의미 단위를 설계하는 작업이다.

RAG 품질을 이야기할 때 Retriever나 모델 성능을 먼저 떠올리기 쉽지만,
실제로는 Chunking 단계에서 이미 상당 부분이 결정된다.

ㅁ Chunking이 RAG 품질을 좌우하는 이유

VectorDB는 문서를 검색하지 않는다.
Chunk 단위의 의미 벡터를 검색한다.

즉,

Chunk는 검색의 최소 단위이고
Chunk는 LLM이 다시 읽게 될 지식 조각이다.

RAG 파이프라인을 단순화하면 이렇게 된다.

Chunk → Embedding → Vector Similarity → Retriever → Prompt Context → LLM

이 흐름의 출발점이 바로 Chunking이다.

그래서 나는 이렇게 정리하게 되었다.

RAG 품질은 Retriever가 아니라, Chunking에서 이미 방향이 정해진다.

ㅁ Chunk Size Trade-off - 크기 최적화의 본질

Chunk 크기를 정할 때 항상 마주치는 딜레마다.

Chunk가 너무 크면:

하나의 벡터 안에 여러 의미가 섞이고
cosine similarity가 희석되며
검색 정확도가 떨어진다.

Chunk가 너무 작으면:

특정 키워드는 잘 잡히지만
문맥이 끊기고
LLM이 전체 흐름을 복원하기 어려워진다.

결국 Chunk size는 단순한 성능 옵션이 아니라,
의미 해상도를 조절하는 문제에 가깝다.

사람이 글을 읽을 때도 문장 하나씩이 아니라
문단 단위로 이해하듯,
LLM에게도 적절한 의미 덩어리가 필요하다.

ㅁ 대표적인 Chunking 전략

실무에서 자주 사용하는 방식은 크게 세 가지다.

Fixed-size Chunking
N 토큰 단위로 기계적으로 자르는 방식이다.
가장 단순하지만 의미 경계를 무시하기 때문에 가장 위험하다.
PoC 단계에서는 빠르지만, 프로덕션에서는 한계가 명확하다.
Overlap Chunking
이전 Chunk 일부를 다음 Chunk에 포함시켜 문맥 손실을 완화한다.
다만 중복 Embedding 비용이 발생한다.
Overlap은 보험이지 해결책은 아니다.
구조 기반 Chunking (문단 / 섹션)
사람이 읽는 구조 그대로 나누는 방식이다.
대부분의 문서에서 가장 자연스럽고 안정적이다.

중요한 점은 이것이다.

최적의 Chunking은 항상 콘텐츠 구조에 의존한다.

기술 문서, 블로그 글, API 스펙, Q&A 데이터는
각각 다른 Chunk 전략이 필요하다.

ㅁ Chunking과 Embedding은 하나의 문제다

Embedding 모델이 아무리 좋아도 Chunk가 엉망이면 RAG는 실패한다.

Chunking과 Embedding은 항상 함께 설계해야 한다.

Chunk는 의미 단위를 정의하고
Embedding은 그 의미를 벡터로 고정한다.

그래서 Chunking은 RAG 파이프라인의 첫 설계 포인트다.

모델 튜닝 전에,
VectorDB 전에,
반드시 먼저 고민해야 할 영역이다.

ㅁ 실무 기준 Chunk 설계 시작점

완벽한 정답은 없다. 항상 실측이다.

다만 경험적으로 다음 정도에서 시작하는 경우가 많다.

기술 문서: 300~500 tokens + overlap 50~100
블로그 / 에세이: 문단 기반
API 문서: 섹션 단위
Q&A 데이터: 질문과 답변을 하나의 Chunk로 묶기

그리고 반드시 확인해야 할 것은:

실제 검색 결과가 의미적으로 맞는지
LLM이 Chunk를 읽고 충분한 컨텍스트를 복원하는지

Chunking은 설정이 아니라 실험이다.

ㅁ Chunking은 지식 모델링이다

점점 느끼게 된 건 이것이다.

Chunking은 텍스트 분할이 아니라,
지식을 어떻게 나눌지 결정하는 작업이다.

사람도 책을 읽을 때:

목차
문단
문맥

단위로 사고한다.

RAG도 결국 같은 구조를 요구한다.

Chunking은
“이 시스템이 지식을 어떤 형태로 기억할 것인가”에 대한 설계다.

ㅁ 마무리

Embedding에서 배운 것은:

의미는 벡터라는 사실이다.

Chunking에서 깨닫는 것은:

벡터 이전에 의미 단위가 존재한다는 점이다.

Transformer가 실시간 사고라면,
Embedding은 기억이고,
Chunking은 그 기억의 구조다.

[AI] 온톨로지에서 Agentic GraphRAG까지 - “관계 기반 AI”가 필요한 이유

기록하는 백앤드개발자 — Thu, 5 Feb 2026 22:53:19 +0900

[AI] LLM 학습 노트 공개 - Transformer부터 RAG까지, 그리고 운영 가능한 AI 시스템을 향해

ㅁ 들어가며

요즘 RAG는 거의 기본 옵션이 되었다. 문서를 임베딩하고, 벡터 검색으로 관련 내용을 찾아 LLM에 넘긴다.

그런데 이상하다.

검색은 되는데, 답은 종종 부정확하다.
문장은 가져오지만, 맥락은 놓친다.
관련 문서는 찾는데, “왜”라는 질문에는 약하다.

이번 세미나는 이 문제를 정면으로 다뤘다.

핵심 메시지는 단순했다.

텍스트 중심 RAG의 한계를 넘기려면,
의미를 문장이 아니라 ‘개념과 관계’로 설계해야 한다.

그리고 그 흐름은 이렇게 정리된다.

Ontology → Knowledge Graph → GraphRAG → Agentic GraphRAG

이 글은 그 전체 파이프라인을 시스템 관점에서 정리한 기록이다.

ㅁ 한 장으로 보는 전체 구조

강의에서 반복적으로 강조된 흐름은 다음과 같다.

Ontology (설계도) → Knowledge Graph (실제 데이터) → GraphRAG (관계 기반 검색) → Agentic GraphRAG (질문별 전략 선택)

온톨로지는 의미의 설계도다.
지식 그래프는 그 설계도 위에 실제 데이터를 얹은 구조다.
GraphRAG는 관계를 따라 정보를 찾는다.
Agentic GraphRAG는 질문을 보고 어떻게 찾을지까지 스스로 결정한다.

중요한 건, 이 네 단계가 서로 독립된 기술이 아니라는 점이다.
앞 단계가 부실하면, 뒤 단계는 성립하지 않는다.

ㅁ Ontology — 사람이 아는 것을, 시스템이 알게 만드는 방법

온톨로지는 단순한 데이터 모델이 아니다.

사람들 사이에서 이미 합의된 개념과 규칙을

컴퓨터가 이해할 수 있도록 명시적으로 구조화한 의미 모델이다.

예를 들면 이런 것들이다.

고객이 무엇인지
문서가 어떤 단위로 구성되는지
어떤 개념이 다른 개념의 선행 조건인지

사람에게는 상식이지만,
시스템에게는 반드시 설계가 필요한 영역이다.

강의에서 인상 깊었던 부분은 이것이었다.

온톨로지는 단순 스키마가 아니라,

추론 가능한 규칙 집합

이라는 점이다.

A가 B에 속하고,
B가 C에 속하면,
시스템은 A가 C에 속한다고 “추론”할 수 있어야 한다.

이게 바로 온톨로지가 필요한 이유다.

ㅁ Knowledge Graph — 설계도가 데이터가 될 때

온톨로지가 설계도라면,
지식 그래프는 그 설계도를 실제 데이터로 채운 상태다.

Entity, Relation, Property.

이 세 가지를 중심으로 도메인을 그래프로 표현한다.

여기서 중요한 포인트는 이것이다.

그래프 DB(예: Neo4j)를 쓰는 것이 목적이 아니라, 도메인을 구조화하는 것이 목적이다.

그래프는 기술이 아니라 표현 방식이다.

어떤 개체가 있고, 그 사이에 어떤 관계가 있으며, 그 관계가 어떤 의미를 갖는지를 드러내는 방식.

이 구조가 명확해야, 이후 단계가 가능해진다.

ㅁ GraphRAG — Vector 검색이 놓치는 것들

기존 Vector RAG는 이렇게 동작한다.

문서를 청크로 나눈다
임베딩한다
질문과 가장 가까운 벡터를 찾는다

문제는 이 구조가 관계를 모른다는 것이다.

Vector RAG는 “비슷한 문장”은 찾지만,
“연결된 의미”는 추론하지 못한다.

GraphRAG는 다르다.

감독 → 영화 → 배우
문서 → 섹션 → 개념
컴포넌트 → 라이선스 → 원본 URL

이처럼 관계를 따라가며 정보를 찾는다.

그래서 multi-hop 질문이 가능해진다.

정리하면 이렇게 표현할 수 있다.

Vector RAG가 “가까운 문장”을 찾는다면,
GraphRAG는 “연결된 의미”를 따라간다.

ㅁ Agentic GraphRAG — 검색 방식까지 AI에게 맡기다

여기서 한 단계 더 나아간 것이 Agentic GraphRAG다.

기존 GraphRAG는 파이프라인이 고정돼 있다.

하지만 Agentic GraphRAG는 다르다.

질문을 보고,

문서 그래프를 쓸지
도메인 그래프를 쓸지
Cypher를 몇 번 실행할지

이 모든 걸 에이전트가 판단한다.

즉, AI는 이제 답만 생성하지 않는다.

어떻게 찾을지도 스스로 결정한다.

이를 위해 Tool Calling, Planning, Retry Loop 같은 구조가 도입되고,
LangChain, LangGraph 같은 프레임워크가 활용된다.

이 단계부터 RAG는 단순 검색 시스템이 아니라,
동적 의사결정 파이프라인이 된다.

ㅁ 내가 느낀 가장 중요한 인사이트

ㅇ Graph는 코딩 문제가 아니라 도메인 문제다

온톨로지에서 Agentic GraphRAG까지 — “관계 기반 AI”가 필요한 이유

그래프 품질은 코드가 아니라 도메인 이해도에서 나온다.

어떤 관계가 중요한지,
어떤 질문이 들어올지,

이걸 설계하는 사람이 결국 시스템 정확도를 결정한다.

ㅇ Chunking + Embedding 이후의 세계

Vector는 의미 좌표다.
Graph는 의미 구조다.

둘은 대체 관계가 아니라 보완 관계다.

Embedding으로 “가까움”을 만들고, Graph로 “이유”를 만든다.

3. Agent는 자동화가 아니라 전략화다

Agent는 단순히 일을 대신 해주는 존재가 아니다.

질문마다 검색 전략을 바꾸는
지능형 오케스트레이터에 가깝다.

ㅁ 이 구조가 실무에서 의미하는 것

이 구조는 단순 챗봇 이야기가 아니다.

문서 검증, 정책 판단, 컴플라이언스, 기술 의사결정 등
모두 같은 패턴으로 확장된다.

예를 들면:

컴포넌트 → 라이선스 → 원본
문서 → 섹션 → 개념
규칙 → 조건 → 결과

이제 RAG는 검색 시스템이 아니라, 의사결정 파이프라인이 된다.

ㅁ 마무리

Vector 다음은 Graph, 그 다음은 Agent

정리하면 이렇게 이어진다.

Ontology: 사고 구조
Graph: 기억 구조
Agent: 판단 구조

LLM이 똑똑해지는 시대가 아니라,
우리가 AI를 설계해야 하는 시대가 왔다.

[AI] Embedding 기초 — Transformer가 만든 의미를 저장하는 방법

기록하는 백앤드개발자 — Thu, 5 Feb 2026 02:01:41 +0900

[AI] LLM 학습 노트 공개 - Transformer부터 RAG까지, 그리고 운영 가능한 AI 시스템을 향해

ㅁ 들어가며

Transformer를 공부하면서 가장 인상 깊었던 점은
LLM이 언어를 “이해”한다기보다, 의미를 벡터로 변환해 계산한다는 사실이었다.

Attention과 Encoder–Decoder 구조를 따라가다 보니 하나의 질문으로 이어졌다.

그렇다면 이 벡터는 모델 안에서만 존재하는 걸까?

Embedding은 바로 그 답이다.

Embedding은 Transformer 내부에서 만들어진 의미를 모델 밖으로 꺼내는 과정이다.

즉, 추론용 의미 표현을 저장과 검색이 가능한 형태로 바꾸는 단계다.

ㅁ Embedding은 기억을 만드는 기술이다

Encoder는 문장을 벡터 공간에서 의미 구조로 압축한다.

하지만 그 출력은 일시적이다. 추론이 끝나면 사라진다.

Embedding은 다르다.

문장, 문서, 혹은 토큰을 고정 길이 벡터로 변환해 저장한다.

나는 Embedding을 이렇게 이해하게 되었다.

Encoder가 “생각”이라면,
Embedding은 “기억”이다.

사람도 글을 읽고 나면 모든 문장을 그대로 외우지 않는다. 대신 요약된 인상을 남긴다.

Embedding도 마찬가지다. 문서 전체를 하나의 벡터로 요약해 의미 좌표 하나로 남긴다.

ㅁ 좋은 Embedding이란 무엇인가

Embedding의 본질은 단순하다.

같은 의미는 가까이,
다른 의미는 멀리.

이 두 가지만 만족하면 된다.

그래서 실제 품질은
모델 크기보다 다음에 더 크게 좌우된다.

어떤 텍스트 단위로 나누었는지 (Chunking)
어떤 유사도 기준을 쓰는지
벡터 차원과 비용을 어떻게 균형 잡았는지

실무에서 느낀 건,

LLM 성능보다
Embedding + 검색 설계가 RAG 품질을 더 크게 좌우한다는 점이다.

ㅁ Vector Similarity는 의미 거리다

Embedding 벡터 자체보다 중요한 건

그 벡터를 어떻게 비교하느냐다.

Cosine similarity는 방향을 본다.
Dot product는 방향과 크기를 함께 본다.

L2 distance는 실제 공간 거리를 잰다.

수학적으로는 다르지만, 개념적으로는 모두 같다.

“이 두 문장이 얼마나 비슷한가?”

VectorDB는 검색 엔진이 아니다.

의미 공간을 탐색하는 시스템이다.

질문을 벡터로 바꾸고, 가장 가까운 의미 좌표들을 찾는 구조다.

ㅁ 임베딩 모델은 ‘정답’이 아니라 ‘선택’이다

임베딩 모델을 비교해 보면 각각 장단점이 분명하다.

API 기반 모델은 빠르게 시작할 수 있지만 비용과 외부 의존이 생긴다.
오픈소스 모델은 자유도가 높지만 인프라 운영 부담이 따른다.
다국어 모델은 범용성이 좋고,
영어 특화 모델은 성능이 더 좋을 수 있다.

중요한 건 “최고 성능”이 아니라,

내 시스템 조건에 맞는 선택이다.

프라이버시가 중요한가?
GPU 인프라가 있는가?
한국어 비중은 얼마나 되는가?
문서 길이는 긴가 짧은가?

Embedding은 모델 문제가 아니라
아키텍처 문제에 가깝다.

ㅁ Chunking은 기술이 아니라 의미 설계다

Embedding을 하다 보면 곧 느끼게 된다.

모델보다 Chunking 전략이 더 중요하다는 것을.

너무 크면 의미가 희석되고,
너무 작으면 문맥이 깨진다.

Chunk는 단순 분할이 아니라,

의미 단위를 어떻게 정의하느냐의 문제다.

사람이 문서를 읽을 때 문단 단위로 이해하듯,
RAG에서도 비슷한 사고가 필요하다.

ㅁ Transformer와 Embedding의 연결

Week 1에서 배운 Transformer는 실시간 의미 계산기였다.

Embedding은 그 계산 결과를
영구 저장 가능한 형태로 만든다.

그리고 VectorDB는
이 벡터들을 모아 둔 의미 지도다.

정리하면 이렇게 이어진다.

의미 생성 (Transformer)
→ 의미 고정 (Embedding)
→ 의미 저장 (VectorDB)
→ 의미 검색 (Retriever)
→ 의미 재해석 (Encoder + Decoder)

이 흐름 위에 RAG가 올라간다.

ㅁ 마무리

Embedding을 이해했다는 건 벡터 차원을 외웠다는 뜻이 아니다.

의미를 좌표로 바꾸고,
그 좌표를 다시 활용하는 구조를 이해했다는 뜻이다.

Transformer가 사고 구조라면,
Embedding은 그 사고를 외부 세계에 남기는 방식이다.

다음 단계에서는
이 의미 좌표들이 어떻게 검색되고,
RAG 파이프라인 안에서 다시 LLM으로 돌아오는지를 살펴보려 한다.

원본 문서들은 계속 LLM 학습 노트에 정리하고, 블로그에는 이렇게 사고 흐름 중심으로 풀어볼 예정이다.