개발 일만 하다 보면 눈앞의 코드에만 집중하게 된다.
오늘은 조금 다른 이야기를 해볼까 한다. 바로 주식에 대한 이야기다.

왜 주식을 해야 하는가?

주식을 시작하면 자연스럽게 질문이 많아진다.

"왜 이 회사는 영업이익이 늘었는데 주가는 떨어졌을까?"
"PER이 낮은데 왜 아무도 사지 않을까?"

재무제표를 읽고, 뉴스를 찾아보고, 시장의 흐름을 추적하다 보면 세상을 보는 눈이 달라진다. 단순히 돈을 벌기 위한 행위가 아니라, 경제와 산업을 이해하는 과정 그 자체가 된다.

시스템적 사고의 훈련

주식 시장은 거대한 생태계다. 수많은 변수들이 얽혀있고, 하나의 뉴스가 연쇄 반응을 일으킨다. 미국 금리가 오르면 한국 증시가 흔들리고, 유가가 오르면 항공주가 떨어지고, 환율이 변하면 수출주가 요동친다.

이런 복잡한 시스템을 읽는 연습은 사고의 폭을 넓혀준다.

경제 흐름의 이해

어떤 기술이 성장할지 알고 싶다면, 그 기술에 투자하는 기업들을 보라.
AI가 화두라면 NVIDIA, AMD, OpenAI에 투자하는 펀드를 보라.
전기차 시장이 커진다면 배터리, 반도체, 충전 인프라 기업들을 보라.

주식은 단순히 돈을 버는 수단이 아니라, 세상이 어디로 가는지를 읽는 창이다. 개발자로서 어떤 기술을 배울지, 어떤 커리어를 쌓을지 고민할 때, 이런 거시적 시야는 엄청난 자산이 된다.

주의할 점

하지만 주식은 결코 쉽지 않다. 몇 가지 원칙을 지키지 않으면 큰 손해를 볼 수 있다.

단타매매는 피하자. 하루에도 수십 번 사고파는 것은 도박에 가깝다. 수수료만 증권사에 갖다 바치는 꼴이다.

물리지 말자. 떨어지는 칼날을 잡으려다 손만 베인다. 손절은 용기다.

주도주 위주로 투자하자. 거래량이 적은 테마주나 잡주는 피하는 게 좋다. 유동성이 없으면 팔고 싶을 때 팔지 못한다.

한 번에 큰 욕심을 버리자. 10% 수익도 훌륭하다. 단기간에 몇 배를 노리다가는 원금을 날릴 수 있다.

분산투자를 하자. 한 종목에 몰빵하는 것은 위험하다. 계란을 한 바구니에 담지 말라는 말이 괜히 있는 게 아니다.

분할매수를 활용하자. 한 번에 다 사지 말고 여러 번 나눠서 사면 평균 단가를 낮출 수 있다.

일희일비하지 말자. 오늘 5% 떨어졌다고 패닉에 빠지지 말고, 내일 5% 올랐다고 흥분하지 말자. 중요한 건 장기적인 수익이다.

기다릴줄 알아야한다. 좋은 종목을 발견했다고 바로 사는 것이 능사가 아니다. 내가 원하는 가격대, 내가 원하는 구간이 올 때까지 사지 않고 기다리는 것도 실력이다. 시장은 항상 기회를 준다. 급등하는 차트를 보며 조급해하고, 뒤늦게 뛰어드는 순간 물리기 시작한다. 매수 버튼을 누르지 않는 것도 투자다. 총알을 아끼고, 자리가 왔을 때 확실하게 들어가는 사람이 결국 살아남는다.

결국 수익을 보는 게 중요하다. 아무리 분석을 잘해도, 결과가 좋지 않으면 의미가 없다. 겸손하게, 꾸준히.

마치며: 투자는 또 다른 성장

요즘 읽고 있는 책에서 인상 깊었던 구절이 있다.

"주식의 흐름은 개인 투자자가 아닌, 세력이 만든다."

결국 밥상을 차리는 건 세력이다. 그들이 완성한 밥상에 뒤늦게 앉아 겸상을 하려고 하면 물리기 딱 좋다. 차라리 밥상이 차려지기 전, 재료를 다듬는 단계에서 한 입 먹고 빠져나오는 전략이 현명하지 않을까.

주식 시장은 냉정하다. 하지만 그 안에서 배우는 것들은 결코 차갑지 않다. 세상을 읽는 눈, 리스크를 관리하는 법, 감정을 다스리는 힘.

개발과 투자, 코드와 차트. 겉보기엔 다르지만 결국 둘 다 끊임없이 배우고 성장하는 과정이다.

개발 일만 하다 보면 때로는 잠시 멈춰서 주변을 둘러보는 것도 중요하다.
오늘은 오래전에 다녔던 병원에서의 일을 가볍게 풀어볼까 한다.

고객이 병원에 방문하고, 그것이 수익으로 이어지기까지.
그 안에는 생각보다 훨씬 많은 전략과 기술, 그리고 사람들의 노력이 숨어있다.

1. 들어가며

오래전 다녔던 한 병원에서의 일이다.

당시 나는 "의료 IT"라는 낯선 도메인에 처음 발을 들였고, 솔직히 말하면 자신감으로 가득했다.
"좋은 기술만 있으면 되겠지"라고 생각했다.

그런데 첫 회의에서 마케팅팀이 던진 질문들은 완전히 달랐다.

"네이버 브랜드 검색으로 들어온 고객이 강남언니로 들어온 고객보다 전환율이 낮은데, 이유를 알 수 있을까요?"
"UTM 파라미터가 끊기는 지점을 찾을 수 있나요?"
"실제 내원 경로와 온라인 추적 데이터가 왜 이렇게 다른가요?"

나는 멍했다. 전환율? UTM? 내원 경로? 이게 무슨 말이지?

네이버 검색광고, 네이버 브랜드, 네이버 키워드, 카카오톡, 인스타그램, 페이스북, 강남언니, 구글 광고... 수많은 채널을 통해 매일 수백, 수천 명의 고객이 유입된다. 마케터들은 각 채널의 광고비를 산정하고, 어떤 메시지가 효과적인지 테스트하고, 재방문율을 높이기 위해 밤낮으로 고민한다.

그제야 깨달았다. 내가 만들어야 할 것은 단순히 "잘 작동하는 코드"가 아니라,
비즈니스 문제를 해결하는 시스템이라는 것을.

기술은 시작이었고, 도메인을 이해하는 것이 진짜 시작이었다.

2. 마케팅 채널: 고객과의 첫 만남

고객이 병원을 알게 되는 경로는 정말 다양하다.

• 검색 광고: "강남 피부과"를 검색한 사람에게 광고를 보여준다
• 소셜 미디어: 인스타그램 피드를 넘기다가 우연히 본 광고
• 전문 플랫폼: 강남언니 같은 미용 의료 특화 플랫폼
• 리타게팅: 한 번 방문했던 사람에게 다시 광고를 보여준다

각 채널마다 광고비가 다르고, 전환율도 다르고, 심지어 유입된 고객의 '질'도 다르다. 어떤 채널은 클릭은 많은데 실제 방문으로는 이어지지 않고, 어떤 채널은 비싸지만 높은 전환율을 자랑한다.

3. 추적의 시작: 데이터는 어떻게 쌓이는가

고객이 광고를 클릭하고 병원 웹사이트나 앱에 들어오는 순간, 추적이 시작된다.

UTM 파라미터 예시:
https://hospital.com/?utm_source=naver&utm_medium=cpc&utm_campaign=spring_promo

이런 식으로 URL에 붙는 작은 파라미터들이 고객의 여정을 기록한다. Google Analytics, 자체 추적 시스템, 쿠키 등 여러 기술이 동원된다.

우리는 다음과 같은 데이터를 수집한다:

• 유입 경로: 어떤 광고를 타고 들어왔는가?
• 랜딩 페이지: 첫 화면으로 무엇을 봤는가?
• 행동 패턴: 어떤 페이지를 둘러봤는가?
• 전환 여부: 예약을 했는가? 상담 신청을 했는가?

4. 아키텍처: 데이터가 흐르는 길

이 모든 과정을 한눈에 보기 위해 가벼운 아키텍처 다이어그램을 그려봤다.

간단히 정리하면 이런 흐름이다:

1. 마케팅 채널 → 고객이 광고를 본다
2. 랜딩 페이지 → 병원 웹사이트/앱에 접속한다
3. 추적 시스템 → 유입 경로와 행동이 기록된다
4. 데이터 수집 → 모든 정보가 데이터베이스에 저장된다
5. MRM 대시보드 → 마케터가 볼 수 있게 시각화된다
6. 의사결정 → 광고비를 어디에 쓸지 결정한다
7. 고객 세그먼트 → 신규 vs 재방문 고객을 구분한다
8. 재타겟팅 → 이벤트 문자, 프로모션 발송
9. 실제 내원 → 고객이 병원에 방문한다
10. 내원 경로 검증 → "어떻게 알고 오셨어요?"
11. 수익화 → 진료비 발생

그리고 가장 중요한 것은, 이 모든 데이터가 다시 처음으로 피드백되어 마케팅 전략을 개선한다는 점이다.

5. 개발자의 역할: MRM 대시보드

마케터들이 매일 보는 대시보드
나는 이걸 MRM(Marketing Resource Management) 이라고 불렀다.

이 대시보드에는 다음과 같은 정보가 실시간으로 표시된다:

• 채널별 유입 현황: 오늘 네이버에서 몇 명, 인스타에서 몇 명?
• 전환율: 100명이 들어와서 몇 명이 예약했나?
• 광고비 대비 수익: ROAS(Return On Ad Spend)는?
• 시간대별 트렌드: 언제 가장 많이 들어오나?
• 캠페인 성과: 어떤 문구, 어떤 이미지가 효과적인가?

개발자로서 이런 대시보드를 만드는 일은 단순히 차트를 그리는 것 이상이다. 데이터 파이프라인, 실시간 집계, 성능 최적화, 그리고 무엇보다 마케터가 원하는 인사이트를 쉽게 찾을 수 있게 하는 UX 설계가 중요했다.

6. 고객 세그먼트: 신규 vs 재방문

모든 고객이 같은 것은 아니다.
우리는 크게 두 가지로 나눠서 고객의 여정을 만들었다.

신규 고객

• 처음 방문하는 사람
• 높은 획득 비용 (CAC: Customer Acquisition Cost)
• 신뢰 구축이 중요
• 첫인상이 전부

재방문 고객

• 이미 병원을 경험한 사람
• 낮은 마케팅 비용
• 높은 전환율
• 로열티 프로그램 대상

재방문 고객을 잡는 것이 훨씬 효율적이다. 그래서 우리는:

• 이벤트성 문자: "지난번 시술 후 3개월이 지났습니다. 재방문 시 20% 할인"
• 리마인더: "정기 검진 시기가 다가왔습니다"
• 맞춤형 프로모션: 고객의 관심사에 맞는 시술 안내

이 모든 것이 데이터 기반으로 움직인다.

7. 실제 검증: 온라인과 오프라인의 간극

고객이 실제로 병원에 내원하면, 간호사나 상담사가 물어본다:
"어떻게 저희 병원을 알게 되셨어요?"

놀랍게도, 온라인에서 추적한 데이터와 실제 고객이 말하는 유입 경로가 다를 때가 많다.

• 온라인 데이터: "네이버 검색광고로 유입"
• 고객의 대답: "친구 추천으로 왔어요"

왜 이런 일이 벌어질까?

• 고객은 여러 채널을 거쳐서 온다
• 기억이 정확하지 않다
• 쿠키 삭제, 여러 기기 사용 등으로 추적이 끊긴다

그래서 온라인 데이터와 오프라인 설문을 비교하고, 서로 보완하며 더 정확한 그림을 그려낸다.

8. 마치며: 멀티 도메인 엔지니어의 시대

예전에 다녔던 회사의 대표님이 이런 말씀을 하셨다.

"우리 개발자 모두는 PL, PM이 되어야 합니다. 그게 당연시되는 세상이 오고
있어요."

당시엔 개발만 하기에도 시간이 부족해 잘 와닿지 않았지만 지금은 정말
그렇다. 불과 몇 년 전만 해도 React를 할 줄 안다는 것만으로 충분한
경쟁력이었다. 지금은 ChatGPT, Copilot, Claude가 코드를 더 잘 짜준다.

기술은 이제 Default다. 그렇다면 우리는 무엇으로 차별화할 수 있을까? 바로
도메인 지식이다.

병원 마케팅을 이해하는 개발자는 단순히 대시보드를 만들지 않는다. "마케터가
진짜 필요로 하는 지표"를 고민한다. 한 도메인을 깊이 이해한 개발자도
강력하지만, 여러 도메인을 넘나든 경험이 있는 멀티 도메인 엔지니어는 한층 더
강력하다.

개발자로서 성장한다는 것은 이제 더 복잡한 알고리즘을 푸는 것이 아니라,

더 많은 비즈니스 문제를 이해하고 해결할 수 있는 사람이 되는 것이 아닐까?

Anthropic Courses

Browse all Anthropic courses

Anthropic

Claude Code에 PM 스킬을 붙이면 생기는 일

AI가 PM처럼 일하게 만드는 오픈소스가 나왔다! - 뮹작가 | AI를 사용할 때 대부분은 아래와 같이 질문을 직접 씁니다. “요약해 줘.”“문서 좀 정리해 줘.”“아이디어 몇 개만 줘.” 그런데 한 가지 문제가 있습니다.무엇을 물어봐야 할지 모르는 경우가 많다는 점입니다. 최근 GitHub에 올라온 PM Skills Marketplace는 이 문제를 조금 다른 방식으로 접근합니다. AI에게 질문을 계속 던지는

WAVVWAVV

http://info.cern.ch

Tests Are The New Moat | Daniel Saewitz

As AI becomes better at cloning people’s open source work, what ends up becoming most valuable are software contracts, tests, and API surface area. This clashes the incentives of clearly defining your commercialized open source software with protecting it.

Daniel SaewitzDaniel Saewitz

Writing code is cheap now - Agentic Engineering Patterns

Writing code is cheap now - Agentic Engineering Patterns

Simon Willison’s WeblogSimon Willison

젯브레인, VS 코드용 ‘자바→코틀린’ 변환기 공개···코틀린 전환 지원

개별 자바 파일을 코틀린 코드로 변환하는 이 확장 프로그램은 자바 개발자가 코틀린으로 보다 수월하게 전환할 수 있도록 돕는다.

CIOPaul Krill

코드를 읽지 않는 시대, 엔지니어는 무엇을 읽어야 하는가

AI가 코드를 대신 쓰는 시대, Anthropic 연구는 AI를 쓴 개발자가 17% 덜 배웠다고 말한다. 하지만 같은 도구를 쓰면서도 결과가 극명하게 갈리는 이유는 무엇인가. AI는 거울이다.

Flowkater.ioTony Cho

Why is Claude an Electron App?

If code is free, why aren’t all apps native?

Drew BreunigDrew Breunig

AI와 주니어 개발자

※ 이 글은 wada kentaro(和田健太郎) 글 https://qiita.com/WdknWdkn/items/9b7dea889fec59194df5 을 의역한 것입니다.

Thinking Storage of CHEUORAcheuora

From 'B급 프로그래머' Web Site

세일즈 파이프라인이 작동하고 있었습니다. 여섯 개의 Claude 에이전트가 각자 역할을 수행했습니다: 회사를 조사하고, 솔루션을 매핑하고, 제안서를 작성하고, 딜 규모를 추정하고, 이메일을 작성합니다. CLI 명령어 하나면 몇 분 안에 개인화된 세일즈 제안서가 완성되었습니다.

하지만 거기에는 거짓말이 내재되어 있었습니다.

"리서처" 에이전트는 실제로 아무것도 조사하지 않았습니다. "Koelle GmbH, Germany"를 입력하면, 그들의 제조 공정, 에너지 문제, ESG 리스크에 대해 자신감 넘치는 브리프를 작성했습니다. 모든 단어가 그럴듯했습니다. 하지만 검증된 것은 하나도 없었습니다. 조사가 아니라 추론이었습니다. 단순한 사례에서는 충분히 잘 작동했습니다 — 그렇지 않을 때까지요.

잘 알려지지 않은 회사로 테스트했을 때 격차가 분명해졌습니다. 에이전트는 실제로는 플라스틱 사출 성형 부품을 만드는 회사에 대해 "예상되는 스탬핑 작업"이라고 자세한 단락을 작성했습니다. 동남아시아의 회사에 대해 해당 규정이 적용되지 않는데도 "EU 탄소 보고 요건"을 언급했습니다.

해결책은 더 나은 프롬프트를 작성하는 것이 아니었습니다. 해결책은 에이전트에게 실제 도구를 주고, 스스로 사용 방법을 결정하게 하고, 모든 것을 조율하는 오케스트레이터를 구축하는 것이었습니다.

무엇이 바뀌었는가

도구만 추가한 것이 아닙니다 — 완전한 아키텍처 전환입니다.

이전

사용자 입력 → [리서처: "모든 것을 추론"] → 리서치 브리프 → [나머지 4개 에이전트]

모든 에이전트가 단일 턴 프롬프트 → 응답 호출이었습니다. 리서처는 회사 이름을 받고 학습 데이터만으로 리서치 브리프를 작성해야 했습니다. 웹 접근도, 데이터베이스도, 검증할 방법도 없었습니다. 각 에이전트는 이전 에이전트의 원시 텍스트를 그대로 전달받았고, Writer가 실행될 때쯤이면 컨텍스트가 오염되어 있었습니다.

이후

사용자 입력
    │
    ▼
┌──────────────────────────────────────────────┐
│              ORCHESTRATOR                     │
│  plan() → execute() → aggregate()            │
│                                               │
│  Group 0: Researcher (멀티턴, 3개 도구)       │
│            + 리플렉션 + 체크포인팅             │
│                      │                        │
│                      ▼ 요약                   │
│  Group 1: Analyst + Architect (병렬 실행)     │
│                      │                        │
│                      ▼ 요약                   │
│  Group 2: Scorer (구조화된 출력)              │
│                      │                        │
│  Group 3: Writer (구조화된 출력)              │
└──────────────────────────────────────────────┘
    │
    ▼
제안서 + 콜드 이메일 + 트레이스 파일

리서처는 이제 세 가지 도구를 갖습니다: 웹 검색, 지식 베이스 쿼리, 웹사이트 스크레이퍼. 무엇을 어떤 순서로 조사할지 스스로 결정합니다. 하지만 더 큰 변화는 오케스트레이터입니다 — 에이전트 실행을 계획하고, 컨텍스트를 관리하고, 비용을 추적하고, 각 에이전트가 정확히 필요한 데이터만 받도록 보장하는 중앙 두뇌입니다.

오케스트레이터 패턴

가장 중요한 아키텍처 결정: 어떤 에이전트도 다른 에이전트의 원시 출력을 보지 않습니다.

이전 시스템에서는 Writer가 모든 것을 받았습니다 — 전체 리서치 브리프, 솔루션 매핑, 딜 추정 — 컨텍스트 윈도우에 그대로 넣었습니다. 이전 출력이 15,000 토큰에 달하면 Writer는 노이즈 속에서 허우적거렸습니다.

새로운 오케스트레이터는 이를 세 단계로 해결합니다:

Plan

def plan(self, task: str) -> PipelinePlan:
    return PipelinePlan(
        target_company=company_name,
        steps=[
            PipelineStep(agent=RESEARCHER, parallel_group=0, criticality="required"),
            PipelineStep(agent=ANALYST, parallel_group=1, criticality="optional"),
            PipelineStep(agent=ARCHITECT, parallel_group=1, criticality="required"),
            PipelineStep(agent=SCORER, parallel_group=2, criticality="optional"),
            PipelineStep(agent=WRITER, parallel_group=3, criticality="required"),
        ],
    )

각 단계에는 parallel_group(같은 그룹의 에이전트는 동시에 실행)과 criticality 수준이 있습니다. Analyst가 실패하면 — 파이프라인은 계속됩니다. Researcher가 실패하면 — 파이프라인이 중단됩니다.

Execute

오케스트레이터는 그룹을 순서대로 실행합니다. 각 그룹 전에 예산을 확인합니다. 각 에이전트에 대해 맞춤형 ContextPacket을 구축합니다:

# Architect가 받는 것: 요약된 리서치 + 전체 제품 지식
# 토큰 예산: 4,000
context = self.context_manager.build_context_packet(
    task_description="고충점을 제품 기능에 매핑하세요.",
    prior_summaries=[
        self.context_manager.summarize_for_handoff(research.raw_text, "architect")
    ],
    company_config=COMPANY_CONFIG,
    token_budget=4000,
)

핵심 통찰: summarize_for_handoff()는 Claude Haiku를 사용하여 다운스트림 에이전트에 맞춤화된 요약을 생성합니다. Architect는 고충점과 기술적 세부사항을 강조한 요약을 받습니다. Writer는 내러티브 훅과 회사 특성을 강조한 요약을 받습니다. 같은 소스 데이터, 다른 강조점.

Aggregate

모든 구조화된 결과를 PipelineResult로 수집합니다:

result.research_brief = ResearchBrief(company=CompanyProfile(name=...), raw_brief=...)
result.deal_estimate = DealEstimate(**scorer.output)      # tool_choice로 보장된 JSON
result.proposal = ProposalOutput(**writer.output)          # tool_choice로 보장된 JSON

다섯 에이전트

Researcher만 에이전틱(멀티턴 도구 사용)입니다. 나머지 에이전트는 단일 턴 — 이전 에이전트로부터 풍부한 컨텍스트를 받고 도구 없이 전문화된 추론을 적용합니다. Scorer와 Writer는 Claude의 tool_choice를 사용하여 보장된 구조화된 출력(regex 파싱 불필요)을 생성합니다.

세 가지 도구

도구 1: search_web

DuckDuckGo를 통해 회사 정보, 산업 데이터, 뉴스를 검색합니다.

{
    "name": "search_web",
    "description": "DuckDuckGo를 사용하여 웹 검색...",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "검색 쿼리."}
        },
        "required": ["query"]
    }
}

도구는 공격적으로 필터링합니다 — 92개의 차단 도메인(Wikipedia, LinkedIn, Glassdoor, 디렉토리 등)과 "Top 10 companies" 리스티클을 잡아내는 regex 패턴. 에이전트는 상위 5개 실제 회사 결과의 제목, URL, 스니펫을 받습니다.

도구 2: query_knowledge_base

시맨틱 유사도를 사용한 ChromaDB 벡터 스토어 검색 (all-MiniLM-L6-v2 임베딩):

• 제품 지식 (~17개 청크): 제품 기능, 스펙, 사례 연구, ROI 데이터, 이상적인 고객 프로필 — YAML 설정에서 자동 시딩, 설정 변경 시 재시딩 (MD5 해시 추적)
• 과거 아웃리치 기록 (시간이 지남에 따라 증가): 완료된 모든 파이프라인 실행이 ChromaDB에 자동 인덱싱

{
    "name": "query_knowledge_base",
    "description": "내부 지식 베이스 검색...",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "검색 쿼리."}
        },
        "required": ["query"]
    }
}

시스템의 메모리가 사는 곳입니다. 키워드 검색과 달리, 시맨틱 임베딩은 "전력 소비 분석"이 공유 단어가 없더라도 "스탬핑 공장을 위한 에너지 모니터링"과 매칭됩니다. 6개월 전에 캘리포니아의 동 피팅 제조업체에 제안했다면, 리서처는 유사한 회사를 조사할 때 그 맥락을 찾아 사용할 수 있습니다 — 각 아웃리치 실행이 ChromaDB의 outreach_history 컬렉션에 인덱싱되기 때문입니다.

도구 3: scrape_company_website

URL을 가져와 HTML을 제거하고 깨끗한 텍스트(최대 4,000자)를 반환합니다. requests + BeautifulSoup으로 구축했습니다.

핵심 설계 결정: 에러는 예외가 아닌 문자열을 반환합니다. 웹사이트가 다운되거나 요청을 차단하면, 에이전트는 "Error: Could not connect to https://company.com"을 보고 적응합니다 — 대신 웹 검색을 합니다. 예외를 발생시키면 전체 파이프라인이 충돌할 것입니다.

에이전틱 루프

하나의 프롬프트 → 응답 호출 대신, 리서처는 멀티턴 대화를 수행합니다:

def _agentic_loop(self, system_prompt, messages, total_in, total_out, on_event=None):
    for turn in range(self.max_turns):
        # 오버플로우 방지를 위한 컨텍스트 프루닝
        messages = self.context_manager.prune_messages(messages)

        response, t_in, t_out = self._api_call(
            system_prompt, messages, tools=self.tools, on_event=on_event,
        )
        total_in += t_in
        total_out += t_out

        # 복구를 위한 체크포인트
        self._checkpoint = {"turn": turn, "messages": messages.copy(), ...}

        if response.stop_reason == "tool_use":
            for block in response.content:
                if block.type == "tool_use":
                    result = self._execute_tool(block.name, block.input)
                    # 컨텍스트 공간 절약을 위해 도구 결과 요약
                    result = self.context_manager.summarize_tool_result(block.name, result)
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result,
                    })

            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": tool_results})
        else:
            # 최종 텍스트 응답 — 리서치 완료
            return AgentResult(success=True, raw_text=final_text, ...)

세 가지가 이것을 견고하게 만듭니다:

1. 컨텍스트 프루닝: 매 턴마다 메시지가 프루닝됩니다. 도구 결과는 ~800 토큰으로 요약됩니다. 이것이 없으면 턴 5까지 컨텍스트가 25,000+ 토큰으로 증가합니다.

2. 체크포인팅: 각 성공적인 API 호출 후 상태가 저장됩니다. 턴 4에서 API가 실패하면, 턴 3의 리서치를 복구합니다 — 처음부터가 아닙니다.

3. 리플렉션: 끝에서 두 번째 턴에서, 리서처는 자신의 작업을 검토하고 신뢰도를 평가하고 갭을 식별하도록 프롬프트됩니다. 이것이 눈에 띄게 더 나은 최종 브리프를 생성합니다.

구조화된 출력 — Regex 파싱의 종말

이전 딜 추정자는 프롬프트에 "유효한 JSON만 출력하세요"라고 지시받았습니다. 때때로 마크다운 펜스를 추가했습니다. 때때로 JSON 앞에 "분석 결과입니다:"를 추가했습니다. regex로 파싱하고 기도했습니다.

새로운 Scorer는 Claude의 tool_choice를 사용합니다:

response = client.messages.create(
    tools=[{
        "name": "submit_deal_estimate",
        "input_schema": {
            "properties": {
                "company_name": {"type": "string"},
                "estimated_machines": {"type": "integer"},
                "first_year_value": {"type": "number"},
                "deal_category": {"type": "string", "enum": ["Small", "Medium", "Enterprise"]},
                ...
            },
            "required": ["company_name", "estimated_machines", "first_year_value", ...]
        }
    }],
    tool_choice={"type": "tool", "name": "submit_deal_estimate"},
)

# response.content[0].input은 스키마에 매칭되는 유효한 JSON이 보장됨
deal = DealEstimate(**response.content[0].input)

파싱 없음. Regex 없음. 충돌 없음. 응답은 항상 유효한 DealEstimate Pydantic 모델입니다. Writer도 ProposalOutput (proposal_markdown + email_subject + email_body)에 동일한 패턴을 사용합니다.

컨텍스트 관리 — 컨텍스트 부패 문제 해결

ContextManager는 에이전트 간 정보 손실(컨텍스트 부패)을 4가지 메커니즘으로 해결합니다:

1. 도구 결과 요약: 맹목적 잘라내기 대신 Claude Haiku로 ~800 토큰으로 지능적 요약. 핵심 사실, 숫자, 회사명, URL 보존.

2. 핸드오프 요약: 다운스트림 에이전트별 맞춤 요약 (~1,500 토큰). Analyst vs Architect vs Writer 각각 리서처 출력의 다른 측면을 강조한 요약을 받음.

3. 메시지 히스토리 프루닝: 첫 메시지(과제) + 마지막 2턴만 유지. 8,000 토큰 초과 시 중간 턴을 단일 요약으로 압축.

4. 맞춤형 ContextPacket: 에이전트별 집중된 컨텍스트 — Architect는 리서치 요약 + 전체 제품 컨텍스트를 받고, Writer는 리서치 + Architect 요약을 받지만 원시 스크레이핑 페이지는 받지 않음.

비용 추적 — 예산 가드

스레드 안전한 CostTracker가 파이프라인당 API 지출을 모니터링합니다:

class CostTracker:
    # 모델별 가격
    # claude-sonnet-4-20250514: $3.00/1M 입력, $15.00/1M 출력
    # claude-haiku-4-5-20251001: $0.80/1M 입력, $4.00/1M 출력

    def record(self, agent, model, tokens_in, tokens_out): ...
    def check_budget(self) -> bool: ...    # 초과 시 파이프라인 중지
    def get_report(self) -> dict: ...      # 에이전트별 분석

• 에이전트별 비용 분석 (입력/출력 토큰, 모델별 요금)
• 예산 가드 — 다음 에이전트 그룹 전에 예산 초과 시 파이프라인 중지
• 비용 보고서가 모든 PipelineResult에 첨부

에러 복구 — 다층 폴백

파이프라인은 여러 수준에서 실패에 대비합니다:

에이전트 수준 폴백

Researcher 멀티턴 루프 실패
    → 체크포인트 복구 (≥2턴 완료된 경우 부분 결과 반환)
    → 체크포인트 복구 실패 → 레거시 단일 턴 모드 (도구 없음, 프롬프트 기반)

Sonnet 모델 실패
    → 지수 백오프로 3회 재시도
    → 속도 제한이 아닌 에러 → Haiku 모델로 폴백

파이프라인 수준 폴백

required 에이전트 실패 → 파이프라인 중단 (예외 발생)
optional 에이전트 실패 → 로그 기록, 빈 AgentResult로 계속 진행

도구 수준 폴백

연속 3회 실패 → 서킷 브레이커: 60초 쿨다운
웹사이트 스크레이핑 실패 → 에이전트가 웹 검색으로 대체
ChromaDB 사용 불가 → 키워드 검색으로 폴백

세일즈 도구에서 이것은 중요합니다 — 최적이 아닌 제안서가 제안서가 없는 것보다 낫습니다.

실시간 스트리밍

CLI와 Streamlit 모두 on_event 콜백을 통해 실시간 진행 상황을 표시합니다:

# 이벤트 유형
agent_start, agent_end, agent_error     # 에이전트 수명주기
turn                                     # 리서처 턴 진행
tool_call, tool_result                   # 도구 사용 추적
text_delta, input_json_delta             # 원시 스트리밍
retry, fallback                          # 에러 복구 이벤트
budget_exceeded, pipeline_end            # 파이프라인 수준 이벤트

에이전트 출력은 client.messages.stream()을 통해 스트리밍됩니다 — 사용자가 리서처의 도구 호출, 결과, 리플렉션을 실시간으로 볼 수 있습니다. 병렬 에이전트 출력은 공유 락으로 직렬화됩니다.

실제 출력: Koelle GmbH

python src/main.py proposal "Koelle GmbH, Germany"

터미널 출력 (Rich 스트리밍)

▸ Researcher — 이 목표 기업을 조사하세요...
  Turn 1/5
  Tool: search_web({"query": "Koelle GmbH Germany manufactu...)
  → Koelle GmbH EN | For 90 years, Koelle has been a reliabl...
  Turn 2/5
  Tool: scrape_company_website({"url": "https://www.koelle-g...)
  → Koelle GmbH EN | Tel: +49-7042/9448-0 | Werkzeugbau und ...
  Turn 3/5
  Tool: query_knowledge_base({"query": "metal stamping autom...)
  → [Result 1] ProMonitor X1 Key Functions: Catch defective ...
  Turn 4/5
  Tool: search_web({"query": "Kölle GmbH Vaihingen energy m...)
  → Koelle GmbH | Werkzeugbau und Stanzerei | ISO 50001 cert...
  ✓ Done — 15,943+1,367 tokens, 18.4s

▸ Analyst — 경쟁 환경 분석...
▸ Architect — 솔루션 매핑...                 ◄── 병렬 실행
  ✓ Done — 2,800+1,500 tokens, 6.2s
  ✓ Done — 2,900+1,800 tokens, 8.1s

▸ Scorer — 딜 규모 추정...
  ✓ Done — 1,200+400 tokens, 3.1s

▸ Writer — 제안서 및 이메일 생성...
  ✓ Done — 3,500+2,800 tokens, 9.8s

  Metric      Value
  Tokens In   26,343
  Tokens Out   7,867
  Duration       42.3s
  Cost          $0.07

이전 리서처가 했을 것

"독일 제조업체로서 Koelle GmbH는 스탬핑 프레스를 운영하고 에너지 비용 상승에 직면하고 있을 가능성이 있습니다..."

일반적입니다. 모호합니다. 추론에 기반합니다.

새로운 리서처가 실제로 찾은 것

"Koelle GmbH는 Vaihingen/Enz에 위치한 90년 역사의 가족 기업으로, 자동차 부문을 위한 금형 제작 및 금속 스탬핑을 전문으로 합니다. 씰 서포트 프레임과 히트 쉴드를 생산합니다. 인증된 ISO 50001 에너지 관리 시스템을 보유하고 있습니다..."

구체적입니다. 사실적입니다. 실제 웹사이트에서 출처를 확인했습니다.

이 차이는 전체 파이프라인에 걸쳐 연쇄적으로 작용합니다. Architect는 실제 운영에 기능을 매핑합니다. Writer는 Vaihingen/Enz, 자동차 OEM 고객, 기존 에너지 관리 시스템을 참조합니다 — 아무리 많은 추론도 만들어내지 못할 세부사항입니다.

배운 교훈

1. 오케스트레이터가 가장 중요한 변화였다

도구 추가보다 더 중요합니다. 이전 시스템은 에이전트 간에 원시 텍스트를 전달했습니다. Writer가 실행될 때쯤이면 15,000 토큰의 컨텍스트가 있었습니다 — 대부분 무관한 스크레이핑된 웹사이트 텍스트나 장황한 분석.

오케스트레이터는 요약된 핸드오프로 이를 해결합니다. 각 에이전트는 특정 역할에 맞춤화된 ~1,500 토큰 요약을 받습니다. Writer는 내러티브 훅을, Scorer는 숫자를 받습니다. 같은 데이터, 적절한 렌즈.

2. 구조화된 출력이 버그의 전체 카테고리를 제거한다

tool_choice 이전에는 JSON 추출을 위한 40줄 이상의 regex 파싱이 있었습니다. 때때로 모델이 JSON을 마크다운 펜스로 감쌌습니다. 때때로 JSON 앞에 "분석 결과입니다:"를 추가했습니다. 때때로 유효한 JSON을 출력하지만 추가 필드가 있었습니다.

tool_choice로 이 모든 것이 사라집니다. 응답은 항상 우리가 지정한 필드를 정확히 가진 유효한 도구 호출입니다. 프로덕션에서 파싱 실패 제로.

3. 임계도 수준이 파이프라인을 탄력적으로 만든다

모든 에이전트가 성공할 필요는 없습니다. Analyst는 경쟁 컨텍스트를 제공합니다 — 유용하지만 필수적이지 않습니다. Scorer는 딜 추정을 제공합니다 — 있으면 좋지만 제안서는 그것 없이도 작동합니다.

이러한 에이전트를 optional로 만들면 개별 구성 요소가 실패해도 파이프라인이 유용한 출력을 생성합니다. 속도 제한과 API 에러가 있는 환경에서 특히 중요합니다.

4. 컨텍스트 프루닝은 멀티턴 에이전트에 필수다

프루닝 없이는 리서처의 컨텍스트가 턴 5까지 25,000+ 토큰으로 증가합니다. 모델이 집중력을 잃고 반복하며 더 나쁜 도구 결정을 내립니다.

프루닝(도구 결과를 ~800 토큰으로 요약, 마지막 2턴만 유지)으로 컨텍스트는 약 8,000 토큰을 유지합니다. 모델은 집중하고 후반 턴에서 더 나은 결정을 내립니다.

5. 비용 추적이 행동을 바꾼다

Researcher가 실행당 $0.06이고 Writer가 $0.05인 것을 볼 수 있으면, 다른 아키텍처 결정을 내립니다. 컨텍스트 요약을 Sonnet 대신 Haiku($0.008/요약)로 옮겼습니다. 예산 가드를 설정하여 비용이 한도를 초과하면 다음 그룹 전에 파이프라인을 중지합니다.

총 파이프라인 비용: 리서치 깊이에 따라 전망 고객당 ~$0.07-0.20.

아키텍처 결정

왜 리서처만 도구를 받는가

나머지 에이전트는 단일 턴을 유지합니다. 도구가 필요 없기 때문입니다:

• Architect는 시스템 프롬프트에 전체 제품 지식이 있습니다. 조사가 아니라 매핑 작업입니다.
• Writer는 리서치 + 솔루션 매핑을 받아 산문을 생성합니다. 검색이 아닌 생성 작업입니다.
• Scorer는 브리프에 가격 공식을 적용합니다. 구조화된 출력, 낮은 온도(0.3).

이러한 에이전트에 도구를 추가하면 품질 향상 없이 지연과 비용만 증가합니다.

왜 최대 5턴인가

각 도구 사용 턴은 API 토큰을 소비합니다. 5턴으로 제한한 이유:

• 대부분의 회사는 3-4턴이면 충분히 조사됩니다
• 5턴을 넘으면 에이전트가 중복 검색을 시작합니다
• 안전 제한은 비용 폭주를 방지합니다

config/company.yaml에서 설정 가능 — quick (2턴), standard (5턴), deep (8턴).

왜 스레드를 이용한 병렬 실행인가

Analyst와 Architect는 독립적입니다 — 둘 다 리서치 브리프만 필요합니다. 병렬 실행으로 파이프라인당 ~6초 절약.

Anthropic Python SDK가 동기식이므로 asyncio 대신 ThreadPoolExecutor를 사용합니다. 스레드 안전성은 CostTracker의 락과 on_event 콜백의 공유 락으로 처리합니다.

숫자로 보기

제안서 실행당 토큰 사용량

검색 실행당 토큰 사용량 (5개 회사 선택)

이 결과가 대체하는 수 시간의 수동 조사 및 작성 작업과 비교해 보세요.

RAG 지식 베이스

왜 ChromaDB인가?

필요한 것은:

• 로컬 실행 (배포할 외부 서버 없음)
• 디스크에 데이터 영속화 (재시작해도 유지)
• 시맨틱 검색 처리 (키워드 매칭만이 아닌)
• Python 3.13과 호환

ChromaDB 임베디드 모드는 네 가지 요건을 모두 충족합니다. 임베딩에 all-MiniLM-L6-v2를 ONNX를 통해 사용합니다 — 한 번 다운로드(~80MB), 로컬에 캐시, API 키 불필요.

3개 컬렉션

• product_knowledge: ~17개 시맨틱 청크 — 제품 기능, 스펙, 사례 연구, ROI 데이터. YAML 설정(config/products.yaml)에서 자동 시딩, 설정 변경 시 MD5 해시로 추적하여 재시딩
• company_facts: 리서치 중 웹 페이지에서 추출된 구조화된 사실
• outreach_history: 파이프라인 실행 후 자동 인덱싱 — 플라이휠 효과

플라이휠 효과

파이프라인을 처음 실행하면 지식 베이스에는 제품 지식만 있습니다. 하지만 몇 번의 실행 후 과거 아웃리치 데이터가 축적됩니다. 리서처가 이를 참조하기 시작합니다:

"캘리포니아의 동 피팅 제조업체에 대한 과거 아웃리치를 기반으로, 주요 고충은 에너지 비용과 품질 관리였습니다..."

더 많은 사용 → 더 많은 인덱싱된 데이터 → 더 나은 리서치 → 더 나은 제안서. 사용할수록 시스템이 더 똑똑해집니다.

설정 기반 아키텍처

모든 것이 YAML 설정으로 구동됩니다:

# config/company.yaml
research:
  depth: "standard"    # quick (2턴), standard (5턴), deep (8턴)

# config/products.yaml
products:
  - name: "ProMonitor X1"
    category: "hardware"
    key_features: [...]
    case_studies: [...]

에이전트 프롬프트는 config/agent_prompts/*.md에 {{placeholder}} 치환으로 정의됩니다. 코드를 변경하지 않고 에이전트 동작을 커스터마이즈할 수 있습니다.

다음 단계

• 비동기 아키텍처 — ThreadPoolExecutor를 asyncio로 교체하여 3-5배 빠른 실행
• 동적 오케스트레이션 — Claude를 사용하여 작업 복잡도에 따라 실행 계획 자동 생성
• CRM 통합 — 전망 고객과 딜 추정을 HubSpot이나 Salesforce에 푸시
• 다국어 제안서 — 독일어, 일본어, 베트남어로 현지 시장용 제안서 생성

결론

단일 턴 추론에서 오케스트레이션된 멀티에이전트 파이프라인으로의 전환은 이 프로젝트에 가한 가장 높은 레버리지의 변화였습니다. 동일한 제품 지식, 동일한 출력 형식 — 하지만 이제 추론 대신 사실 위에 구축되었고, 각 에이전트가 정확히 필요한 컨텍스트만 받습니다.

핵심 통찰:

1. 오케스트레이터가 에이전트보다 더 중요합니다. 컨텍스트 관리, 요약된 핸드오프, 병렬 실행이 파이프라인을 작동하게 만듭니다.
2. 모든 에이전트가 도구를 필요로 하지는 않습니다. 리서처만 도구의 혜택을 받습니다.
3. 구조화된 출력이 버그를 제거합니다. tool_choice가 regex 파싱을 대체합니다.
4. 임계도 수준이 탄력성을 만듭니다. optional 에이전트는 파이프라인을 깨뜨리지 않고 실패할 수 있습니다.

다섯 에이전트. 세 도구. 하나의 오케스트레이터. 극적으로 나아진 출력.

Repository: agentic-outreach-pipeline

배타적 서브타입이란?

데이터베이스 테이블 설계에서 슈퍼타입(Super Type)과 서브타입(Sub Type)은 공통 속성을 기준으로 엔티티(테이블)를 상위/하위로 나누는 데이터 모델링 기법입니다.

• Super Type (상위 엔티티)
  • 여러 엔티티가 공통으로 가지는 속성을 모아 놓은 엔티티
  • 식별자(PK, ID)를 포함한 공통 정보를 가지고 있음
• Sub Type (하위 엔티티)
  • 각 타입만의 고유한 속성을 추가로 가지는 엔티티

제조실행시스템(MES)를 위한 테이블을 설계 할 때를 예시로 왜 테이블을 Super Type과 Sub Type으로 나누는 지 살펴보겠습니다.

대표적으로 공장에서 제조를 할 때 사용되는 ITEM(품목)은 여러 종류가 있습니다.

• 제품(최종 제품)
• 반제품(제품을 생산 할 때 다른 필요한 중간 생산 제품)
• 자재
• 공구

위 현실세계의 제품을 엔티티로 모사해서 테이블 화 할 때 만약 위 다양한 종류를 하나의 엔티티로 관리한다면 NULL 컬럼이 급증하게 됩니다.

• NULL 컬럼이 급증하는 이유?
  • 공구는 수명 및 점검주기 컬럼이 필요합니다.
  • 자재는 자재에만 적용되는 스펙, 자재검사의 유무 등의 컬럼이 필요합니다.
  • 제품은 제품의 최종적인 처리 방식을 나타내는 컬럼이 필요합니다.

위의 경우 하나의 테이블로 ITEM을 관리하게 되면 공구용 컬럼에는 자재, 제품 등의 데이터는 모두 NULL로 저장되며 반대의 경우도 발생합니다.

그렇다면 위 ITEM 별 종류들을 모두 별개의 엔티티로 관리하면 되지 않을까요? 그런 경우 다음과 같은 단점이 발생합니다.

• 공통속성이 여러 테이블에 중복됩니다.
  • 제품/반제품/자재/공구 등은 모두 ITEM의 성격을 가지고 있어서 공통적으로 가지는 속성 예) 코드, 이름, 사용여부, 생성일, 수정일 등 이 테이블마다 중복으로 저장됩니다.
    • 이 경우 공통 속성 컬럼 정의 수정 시 예)코드의 길이 변경 시 모든 종류의 ITEM 테이블 정의를 변경해야 합니다.
  • ITEM이라는 공통 관점에서의 조회/참조가 어려워집니다.
    • 만약 ITEM이라는 공통 속성으로만 조회를 할 경우, 테이블이 완전 분리되어 있으면 품목 검색 시 (공통컬럼만 필요한 경우에도) 제품/반제품/자재/공구 를 각 각 조회하여 UNION ALL 로 합쳐야 합니다.
    • 또한 ITEM이라는 공통의 개념과 연관된 테이블을 설계할 때 다 수의 제품/반제품/자재/공구 테이블과 각각 PK/FK 관계를 맺을 필요 없이 ITEM 슈퍼타입의 ITEM_ID를 FK로 한번 참조할 수 있습니다.

이런 단점들을 보완하기 위해 Super Type으로 ITEM(품목) 엔티티를 설정하고 Sub Type으로 각 각 제품, 반제품, 자재, 공구 등의 엔티티를 설계할 수 있습니다. 이 경우 공통 컬럼은 Super Type인 ITEM(품목) 엔티티에 설정하고 각 Sub Type의 고유 특성들을 각 각의 엔티티에 설정해서 관리 해주면 됩니다.

그런데 배타적 - exclusive 라는 말이 왜 붙은 걸까요?

여기서 배타적이라는 의미는 ITEM(품목) 이 무조건 제품, 또는 자재 등의 하위 성격중에서 하나만 가지고 있어야 된다는 의미입니다. 만약 ITEM_ID 로 ITEM_001이라는 데이터가 제품이자 자재여서 제품 Sub-Type entity에도 저장되고, 자재 Sub-Type entity에도 저장되면 안된다는 의미 입니다.

만약 ITEM_ID = 'ITEM_001' 인 데이터가
PRODUCT 테이블과 MATERIAL 테이블에 동시에 존재한다면,
해당 ITEM은 “제품이면서 자재”가 되어버리며
이는 우리가 정의한 품목의 도메인 규칙을 명확히 위반하는 상태가 됩니다.

이처럼 서브타입 간 중복을 허용하지 않고,
반드시 하나의 하위 성격만 가질 수 있도록 제한하는 구조를
배타적(Exclusive) 서브타입이라고 부릅니다.

이처럼 배타적으로 설계 하지 않을 경우에는 아래와 같은 단점이 존재합니다.

1. 도메인 의미가 깨집니다.
   1. MES 관점에서 제품, 자재, 공구는 역할과 책임이 전혀 다른 개념입니다.
      1. 제품은 생산의 결과물이며 출하 대상이 되고
      2. 자재는 생산에 투입되어 소모되며
      3. 공구는 수명을 관리하며 반복 사용됩니다.
   2. 그런데 하나의 ITEM이 제품이면서 동시에 자재로 존재한다면, 이 ITEM이 출하대상인지 소모대상 인지 명확하지 않게 됩니다.
2. 분기문이 복잡해집니다.
   1. 만약 ITEM이 여러 Sub Type에 동시에 존재 할 수 있다면, 백엔드 로직은 항상 다음과 같은 방어 코드를 작성해주어야 합니다
      1. 이 ITEM은 제품이기도 하고 자재이기도 합니다.
      2. 이 ITEM을 어떤 기준으로 제품으로 처리할 지, 자재로 처리할 지 모호합니다.
      3. 결국 코드 곳곳에 아래와 같은 분기문이 생기게 됩니다.

if (isProduct && isMaterial) {
    ...
}

배타적 서브타입 설계 예시

그럼 실제로 배타적 서브타입 설계 + 백엔드 구현을 해보겠습니다.

데이터베이스 구현

먼저 테스트 환경은 데이터베이스 서버는 MS SQL SERVER 15버전이며 데이터베이스 관리 및 쿼리 툴은 SQL Server Management Studio 18.12.1 버전 입니다.

테스트용 데이터데이스를 생성해보겠습니다.

생성된 데이터베이스에 각 각 Super Type으로 ITEM(품목)을 Sub Type으로 PRODUCT(제품), MATERIAL(자재) 테이블을 추가 해줍니다.

• Super Type
  • ITEM(품목)
    • ITEM_ID (PK)
    • ITEM_TYPE (타입)
    • ITEM_ATT (공통속성)
• Sub Type
  • PRODUCT(제품)
    • PRDT_ID (PK,FK)
    • PRDT_TYPE (타입)
    • PRDT_ATT (고유속성)
  • MATERIAL(자재)
    • MAT_ID (PK,FK)
    • MAT_TYPE (타입)
    • MAT_ATT (고유속성)

테이블 생성 및 연관관계 설정은 데이터베이스 관리 툴에서 -> 데이터베이스 다이어그램 기능(우클릭-새 데이터베이스 다이어그램)을 이용해서 생성하겠습니다.

다이어그램 창 -> 우클릭 -> 새 테이블

이제 연관관계를 설정해줍니다. Sub Type의 PK인 PRDT_ID와 MAT_ID의 FK를 ITEM의 PK로 지정합니다.

먼저 ITEM 테이블의 PRIMARY KEY 칼럼인 ITEM ID의 열쇠 아이콘을 마우스 좌 클릭 후 PRODUCT 테이블의 PRIMARY 칼럼인 PRDT_ID 칼럼으로 끌어다 놓습니다.

MATERIAL 테이블도 똑같이 해줍니다.

해당 다이어그램을 저장(ctrl + s)하여 실제 테이블이 생성됨을 확인합니다.

주의: 운영환경의 데이터베이스에서 다이어그램툴을 이용하여 수정, 생성 후 저장은 실제로 데이터베이스에 반영이 되므로 주의해야 합니다.

생성된 테이블의 CREATE 문을 살펴보겠습니다.

• Super Type

USE [exclusive_test]
GO

SET ANSI_NULLS ON
GO

SET QUOTED_IDENTIFIER ON
GO

CREATE TABLE [dbo].[ITEM](
	[ITEM_ID] [nvarchar](50) NOT NULL,
	[ITEM_TYPE] [nvarchar](50) NOT NULL,
	[ITEM_ATT] [nvarchar](50) NOT NULL,
 CONSTRAINT [PK_ITEM] PRIMARY KEY CLUSTERED 
(
	[ITEM_ID] ASC
)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON, OPTIMIZE_FOR_SEQUENTIAL_KEY = OFF) ON [PRIMARY]
) ON [PRIMARY]
GO

단순화 버전

CREATE TABLE ITEM (
    ITEM_ID   NVARCHAR(50) PRIMARY KEY,
    ITEM_TYPE NVARCHAR(50) NOT NULL,
    ITEM_ATT  NVARCHAR(50) NOT NULL
);

• Sub Type

USE [exclusive_test]
GO

SET ANSI_NULLS ON
GO

SET QUOTED_IDENTIFIER ON
GO

CREATE TABLE [dbo].[MATERIAL](
	[MAT_ID] [nvarchar](50) NOT NULL,
	[MAT_TYPE] [nvarchar](50) NOT NULL,
	[MAT_ATT] [nvarchar](50) NOT NULL,
 CONSTRAINT [PK_MATERIAL] PRIMARY KEY CLUSTERED 
(
	[MAT_ID] ASC
)WITH (PAD_INDEX = OFF, STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON, OPTIMIZE_FOR_SEQUENTIAL_KEY = OFF) ON [PRIMARY]
) ON [PRIMARY]
GO

ALTER TABLE [dbo].[MATERIAL]  WITH CHECK ADD  CONSTRAINT [FK_MATERIAL_ITEM] FOREIGN KEY([MAT_ID])
REFERENCES [dbo].[ITEM] ([ITEM_ID])
GO

ALTER TABLE [dbo].[MATERIAL] CHECK CONSTRAINT [FK_MATERIAL_ITEM]
GO

단순화 버전

CREATE TABLE MATERIAL (
    MAT_ID   NVARCHAR(50) PRIMARY KEY,
    MAT_TYPE NVARCHAR(50) NOT NULL,
    MAT_ATT  NVARCHAR(50) NOT NULL,
    CONSTRAINT FK_MATERIAL_ITEM
        FOREIGN KEY (MAT_ID)
        REFERENCES ITEM (ITEM_ID)
);

백엔드 구현

이제 해당 데이터베이스 테이블들에 데이터를 저장, 조회 하는 백엔드 예시 코드를 구현해보겠습니다.

먼저, 우리가 구현한 데이터베이스 테이블 설계에서 한가지 의문점을 가져야 합니다.

과연 저 데이터베이스 테이블 설계 구조에서 위에서 언급된 배타적 특성이 보장되는지 입니다.

결론적으로 지금 상태에서는 배타적 특성이 보장되지 않습니다. 예시로 위 설계된 테이블에 데이터를 넣어 보겠습니다.

정상 케이스

-- 슈퍼타입 생성
INSERT INTO ITEM (ITEM_ID, ITEM_TYPE, ITEM_ATT)
VALUES ('ITM001', 'PRDT', 'COMMON');

-- PRODUCT 서브타입 생성 (OK)
INSERT INTO PRODUCT (PRDT_ID, PRDT_TYPE, PRDT_ATT)
VALUES ('ITM001', 'PRDT', 'PRDT');

배타성이 깨진 케이스

INSERT INTO MATERIAL (MAT_ID, MAT_TYPE, MAT_ATT)
VALUES ('ITM001', 'MAT', 'MAT');

조회 해봅니다.

select * from ITEM
select * from PRODUCT
select * from MATERIAL

왜 이런 결과가 발생할까요?

• FOREIGN KEY는
  → “부모가 존재하는지”만 검증한다.
• PRIMARY KEY는
  → “중복되지 않는지”만 보장한다.

하지만 DB 제약만으로는,

• “이 ITEM_ID가 어느 Sub Type에 속하는지”
• “이미 다른 Sub Type에 속해 있는지”

와 같은 도메인 규칙까지 표현하기는 어렵습니다.

물론, 트리거(trigger)나 복잡한 제약조건을 걸어 일부 제어는 가능하지만 실무에서는 배타성의 최종 책임을 백엔드 애플리케이션 이 가져가는 경우다 대부분입니다.

이에 따라 백엔드 구현 예시는 어떻게 배타성을 적용하는지의 관점으로 작성되었습니다.

• 백엔드 환경
  • java 17
  • spring boot 3.5.10

spring.application.name=exclu_demo

#Hikari CP
spring.datasource.max-lifetime=1800000
spring.datasource.maximum-pool-size=20

#JPA
spring.jpa.hibernate.ddl-auto=none

# MS-SQL config
spring.datasource.driver-class-name=com.microsoft.sqlserver.jdbc.SQLServerDriver
spring.datasource.url=jdbc:sqlserver://127.0.0.1;databaseName=exclusive_test;trustServerCertificate=true
spring.datasource.username=plato
spring.datasource.password=

먼저 DB 테이블 매핑하는 코드를 작성하겠습니다.
entity 폴더를 만들고 우리가 생성한 테이블과 매핑 되는 Item Product Material 코드를 작성합니다.

package plato.io.exclu_demo.entity;

import jakarta.persistence.*;
import lombok.*;
import org.springframework.data.domain.Persistable;

import java.io.Serializable;

@Entity
@Table(name = "ITEM")
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class Item implements Persistable<String>, Serializable {

    @Id
    @Column(name = "ITEM_ID", length = 50 )
    private String itemId;

    @Enumerated(EnumType.STRING)
    @Column(name = "ITEM_TYPE", length = 50)
    private ItemType itemType;

    @Column(name = "ITEM_ATT", length = 50)
    private String itemAtt;

    @Override
    public String getId() {
        return itemId;
    }

    @Override
    public boolean isNew() {
        return false;
    }

    @Setter
    @Transient
    @Builder.Default
    private boolean isNew = false;
}

package plato.io.exclu_demo.entity;

import jakarta.persistence.*;
import lombok.*;
import org.springframework.data.domain.Persistable;

import java.io.Serializable;

@Entity
@Table(name = "PRODUCT")
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class Product implements Persistable<String>, Serializable {
    @Id
    @Column(name = "PRDT_ID", length = 50)
    private String prdtId;

    @Enumerated(EnumType.STRING)
    @Column(name = "PRDT_TYPE", length = 50)
    private ItemType prdtType;

    @Column(name = "PRDT_ATT", length = 50)
    private String prdtAtt;

    // 부모(Item) 참조 - FK
    @OneToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "PRDT_ID", referencedColumnName = "ITEM_ID", insertable = false, updatable = false)
    private Item item;

    @Transient
    @Builder.Default
    private boolean isNew = false;

    @Override
    public String getId() {
        return prdtId;
    }

    @Override
    public boolean isNew() {
        return isNew;
    }

}

package plato.io.exclu_demo.entity;

import jakarta.persistence.*;
import lombok.*;
import org.springframework.data.domain.Persistable;

import java.io.Serializable;

@Entity
@Table(name = "MATERIAL")
@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class Material implements Persistable<String>, Serializable {

    @Id
    @Column(name = "MAT_ID", length = 50)
    private String matId;

    @Enumerated(EnumType.STRING)
    @Column(name = "MAT_TYPE", length = 50)
    private ItemType matType;

    @Column(name = "MAT_ATT", length = 50)
    private String matAtt;

    // 부모(Item) 참조 - FK
    @OneToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "MAT_ID", referencedColumnName = "ITEM_ID", insertable = false, updatable = false)
    private Item item;

    @Transient
    @Builder.Default
    private boolean isNew = false;

    @Override
    public String getId() {
        return matId;
    }

    @Override
    public boolean isNew() {
        return isNew;
    }
}

ItemType enum 클래스도 생성해줍니다.

package plato.io.exclu_demo.entity;

import lombok.Getter;
import lombok.RequiredArgsConstructor;

@Getter
@RequiredArgsConstructor
public enum ItemType {
    PRODUCT("P", "제품"),
    MATERIAL("M", "자재");

    private final String prefix;      // ID prefix
    private final String description; // 설명
}

그 다음 repository 계층을 인터페이스로 선언해줍니다.

package plato.io.exclu_demo.repository;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;
import plato.io.exclu_demo.entity.Item;

import java.util.List;

@Repository
public interface ItemRepository extends JpaRepository<Item, String> {
}

package plato.io.exclu_demo.repository;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;
import plato.io.exclu_demo.entity.Product;

@Repository
public interface ProductRepository extends JpaRepository<Product,String> {
}

package plato.io.exclu_demo.repository;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;
import plato.io.exclu_demo.entity.Material;

@Repository
public interface MaterialRepository extends JpaRepository<Material,String> {
}

다음으로 ITEM 생성시 필요한 DTO 구조를 작성합니다.

package plato.io.exclu_demo.dto;

import lombok.*;
import plato.io.exclu_demo.entity.ItemType;

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class ItemSaveRequest {
    // 공통 (ITEM)
    private ItemType itemType;
    private String itemAtt;

    // 제품 (PRODUCT)
    private String prdtAtt;

    // 자재 (MATERIAL)
    private String matAtt;
}

package plato.io.exclu_demo.dto;

import lombok.Builder;
import lombok.Getter;
import plato.io.exclu_demo.entity.Item;
import plato.io.exclu_demo.entity.ItemType;

@Getter
@Builder
public class ItemSaveResponse {
    private String itemId;
    private ItemType itemType;
    private String itemAtt;

    public static ItemSaveResponse from(Item item) {
        return ItemSaveResponse.builder()
                .itemId(item.getItemId())
                .itemType(item.getItemType())
                .itemAtt(item.getItemAtt())
                .build();
    }
}

다음으로 실제 ITEM/제품/자재를 저장, 조회하는 service 계층입니다.

package plato.io.exclu_demo.service;

import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import plato.io.exclu_demo.dto.ItemSaveRequest;
import plato.io.exclu_demo.dto.ItemSaveResponse;
import plato.io.exclu_demo.entity.Item;
import plato.io.exclu_demo.entity.ItemType;
import plato.io.exclu_demo.entity.Material;
import plato.io.exclu_demo.entity.Product;
import plato.io.exclu_demo.repository.ItemRepository;
import plato.io.exclu_demo.repository.MaterialRepository;
import plato.io.exclu_demo.repository.ProductRepository;


@Service
@RequiredArgsConstructor
@Transactional
public class ItemService {
    private final ItemRepository itemRepository;
    private final ProductRepository productRepository;
    private final MaterialRepository materialRepository;

    /**
     * ITEM_TYPE에 따라 ID 자동 생성
     */
    private String generateId(ItemType itemType) {
        long count = switch (itemType) {
            case PRODUCT -> productRepository.count();
            case MATERIAL -> materialRepository.count();
        };
        return itemType.getPrefix() + String.format("%05d", count + 1);
    }

    /**
     * 품목 저장 - ITEM_TYPE에 따라 서브타입 자동 생성
     */
    public ItemSaveResponse saveItem(ItemSaveRequest request) {
        ItemType itemType = request.getItemType();

        // 1. ID 자동 생성
        String itemId = generateId(itemType);

        // 2. Super Type 생성
        Item item = Item.builder()
                .itemId(itemId)
                .itemType(itemType)
                .itemAtt(request.getItemAtt())
                .build();
        item.setNew(true);

        // 3. Item 먼저 저장
        itemRepository.save(item);

        // 4. ITEM_TYPE에 따라 Sub Type 생성 및 저장 (배타적)
        switch (itemType) {
            case PRODUCT -> {
                Product product = Product.builder()
                        .prdtId(itemId)
                        .prdtType(itemType)
                        .prdtAtt(request.getPrdtAtt())
                        .build();
                product.setNew(true);
                productRepository.save(product);
            }
            case MATERIAL -> {
                Material material = Material.builder()
                        .matId(itemId)
                        .matType(itemType)
                        .matAtt(request.getMatAtt())
                        .build();
                material.setNew(true);
                materialRepository.save(material);
            }
        }

        return ItemSaveResponse.from(item);
    }
}

다음으로 controller 계층을 만듭니다.

package plato.io.exclu_demo.controller;

import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import plato.io.exclu_demo.dto.ItemSaveRequest;
import plato.io.exclu_demo.dto.ItemSaveResponse;
import plato.io.exclu_demo.service.ItemService;

@RestController
@RequestMapping("/api/item")
@RequiredArgsConstructor
public class ItemController {

    private final ItemService itemService;
    
    @PostMapping
    public ResponseEntity<ItemSaveResponse> saveItem(@RequestBody ItemSaveRequest request) {
        ItemSaveResponse response = itemService.saveItem(request);
        return ResponseEntity.ok(response);
    }
}

테스트를 해봅니다.

• 제품 저장

POST http://localhost:8080/api/item

{
    "itemType": "PRODUCT",
    "itemAtt": "COMMON",
    "prdtAtt": "PRDT"
}

• 자재 저장

POST http://localhost:8080/api/item

{
    "itemType": "MATERIAL",
    "itemAtt": "COMMON",
    "matAtt": "MAT"
}

우리를 계속 괴롭히던 것이 있었습니다: 왜 AI 에이전트는 대화가 끝나는 순간 모든 것을 잊어버릴까요?

한번 생각해보세요. 챗봇에게 전화보다 이메일을 선호한다고 말합니다. 다음 세션에서는요? 마치 처음 만난 것처럼 행동합니다. 한 상담원에게 주문 문제를 설명하고, 다른 상담원에게 연결되면, 갑자기 처음부터 다시 시작해야 합니다.

우리 모두 겪어본 일입니다. 사용자로서 답답하고, 솔직히 엔지니어로서는 매력적인 문제입니다.

그래서 우리는 스스로에게 물었습니다: 만약 AI 에이전트가 실제로 기억할 수 있다면? 그리고 단순히 기억하는 것을 넘어서, 서로 배운 것을 공유할 수 있다면?

이것이 A2A 메모리 레이어가 탄생한 배경입니다.

잠깐, 정확히 무엇을 만드는 건가요?

기술적인 내용으로 들어가기 전에, 이 프로젝트가 실제로 무엇을 하는지 명확히 해봅시다:

A2A 메모리 레이어는 여러 AI 에이전트가 다음을 할 수 있게 하는 공유 메모리 시스템입니다:

• 대화를 넘어서 사실을 기억 (단일 채팅 내에서만이 아닌)
• 실시간으로 서로 지식을 공유
• 전문 지식을 결합하여 복잡한 작업에 협력
• 수동으로 정보를 복사하지 않고도 동기화 유지

다음과 같은 고객 서비스 팀을 상상해보세요:

• Alex (코디네이터)는 문제를 라우팅하는 방법을 알고 있습니다
• Sam (주문 전문가)은 배송과 환불에 대해 모든 것을 알고 있습니다
• Jordan (기술 지원)은 모든 시스템 문제를 해결할 수 있습니다

이제 이들이 모두 같은 노트북을 공유한다고 상상해보세요. Sam이 고객 #12345가 이메일을 선호한다는 것을 알게 되면, Alex와 Jordan도 즉시 알게 됩니다. 이것이 우리가 만든 것입니다.

그런데 왜 이걸 만들었나요? LLM에는 이미 메모리가 있지 않나요?

좋은 질문입니다. 그리고 그 답은 LLM이 어떻게 작동하는지에 대한 근본적인 것을 드러냅니다.

LLM은 상태가 없습니다(stateless). 메시지를 보낼 때마다 모델은 새롭게 시작합니다. 명시적으로 알려주지 않는 한 이전 대화에서 무슨 일이 있었는지 전혀 모릅니다. 흔히 듣는 컨텍스트 윈도우? 그것은 메모리가 아닙니다—매 세션이 끝나면 지워지는 메모장에 더 가깝습니다.

Google의 "Context Engineering" 백서(2025년 11월)는 이 문제를 아름답게 정리했습니다. 그들은 다음을 구분합니다:

• 세션(Sessions): 단일 대화를 위한 임시 메모장
• 메모리(Memory): 세션을 넘어 지속되는 영구적인 지식

대부분의 챗봇은 세션만 처리합니다. 우리는 둘 다 다루고 싶었고—여기에 세 번째 차원을 추가했습니다: 여러 에이전트 간에 메모리를 공유하는 것.

아키텍처: 이것은 실제로 어떻게 작동하나요?

자, 이제 흥미로운 부분으로 들어가봅시다. AI 에이전트를 위한 공유 두뇌를 어떻게 구축할까요?

전체 그림

┌─────────────────────────────────────────────────────────────┐
│                    사용자가 보는 것 (프론트엔드)                   │
│         크기 조절 가능한 패널이 있는 Next.js 인터페이스               │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                      API 게이트웨이                            │
│               Flask REST API (15개 엔드포인트)                  │
└──────────────────────────┬──────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
┌──────────────┐   ┌──────────────┐   ┌──────────────┐
│    세션      │   │    메모리     │   │  A2A 브릿지      │
│   매니저     │   │    매니저     │   │   프로토콜        │
└──────────────┘   └──────────────┘   └──────────────┘
        │                  │                  │
        └──────────────────┼──────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                       공유 두뇌                               │
│       벡터 스토어 + 메모리 유형 + 에이전트 간 동기화                  │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                   Ollama + phi4-mini                        │
│                 128k 컨텍스트 윈도우 LLM                        │
└─────────────────────────────────────────────────────────────┘

왜 이런 컴포넌트들인가요?

세션 매니저 — "방금 무슨 이야기를 했지?"

단기적인 것들을 처리합니다. 에이전트와 채팅할 때, 세션 매니저는 대화를 추적하고, 토큰을 세고(128k 컨텍스트 윈도우도 무한하지 않으니까요), 내용이 너무 길어지면 무엇을 유지할지 결정합니다.

메모리 매니저 — "영원히 기억해야 할 것은 무엇인가?"

대화의 모든 것이 기억할 가치가 있는 것은 아닙니다. 메모리 매니저는 중요한 부분—고객 선호도, 해결된 문제, 학습된 절차—을 추출하고 장기간 저장합니다.

A2A 브릿지 — "다른 에이전트들아, 너희도 이거 알아야 해."

이것이 마법의 소스입니다. 한 에이전트가 가치 있는 것을 배우면, A2A 브릿지는 그것이 필요할 수 있는 다른 에이전트들에게 전파합니다. 팀의 단체 채팅과 같지만, 지식을 위한 것입니다.

메모리 유형: 모든 기억이 동등하게 만들어지지는 않습니다

인지 과학에서 배운 것이 있습니다: 인간에게는 다양한 유형의 기억이 있고, 우리 에이전트도 그래야 합니다.

선언적 메모리: "내가 아는 것은 무엇인가?"

이것들은 사실입니다. 정적인 지식. 맥락과 관계없이 참인 것들.

절차적 메모리: "어떻게 하는 거지?"

이것들은 기술과 워크플로우입니다. 작업을 수행하는 방법에 대한 단계별 지식.

왜 이 구분이 중요한가요?

메모리를 검색하고 사용하는 방식에 영향을 미치기 때문입니다. 고객이 "환불 정책이 뭐예요?"라고 물으면, 선언적 메모리를 검색합니다. "환불 받고 싶어요"라고 말하면, 워크플로우를 위한 절차적 메모리도 가져옵니다.

다른 질문에는 다른 유형의 지식이 필요합니다. 우리 시스템은 그 차이를 알고 있습니다.

세션 문제: 대화가 길어지면 어떻게 되나요?

우리가 해결해야 했던 실질적인 문제가 있습니다: LLM은 제한된 컨텍스트 윈도우를 가지고 있습니다.

phi4-mini의 인상적인 128k 토큰 컨텍스트도 결국 가득 찹니다. 단일 고객 상호작용이 수천 개의 토큰을 생성할 수 있습니다. 여러 에이전트가 협업하면, 메모리 관리 문제가 생깁니다.

우리의 해결책: 압축 전략

세 가지 접근 방식을 구현했습니다 (그리고 서로 교체할 수 있습니다):

1. 슬라이딩 윈도우 마지막 N개의 메시지를 유지하고, 이전 것은 모두 삭제합니다.

• 장점: 간단하고, 예측 가능
• 단점: 중요한 초기 맥락을 잃을 수 있음

2. 토큰 기반 잘라내기 토큰 수를 모니터링하고, 한계에 가까워지면 가장 오래된 내용을 제거합니다.

• 장점: 컨텍스트 사용을 최대화
• 단점: 정확한 토큰 계산이 필요

3. 요약 오래된 대화 청크를 AI가 생성한 요약으로 대체합니다.

• 장점: 토큰을 줄이면서 의미를 보존
• 단점: 요약이 뉘앙스를 놓칠 수 있음

# 예시: 압축을 트리거하는 방법
if session.token_count > (self.max_tokens * 0.8):  # 80% 임계값
    self.trigger_compaction(session_id)

핵심 통찰? 공간이 다 찰 때까지 기다리지 마세요. 80% 용량에서 압축을 시작하여 시스템에 여유 공간을 줍니다.

A2A 프로토콜: 에이전트들이 실제로 어떻게 대화하나요?

여기서 정말 흥미로워집니다. 독립적인 AI 에이전트들이 어떻게 협력하게 할까요?

메시지 흐름

고객이 지원팀에 연락할 때 어떤 일이 일어나는지 살펴봅시다:

1. 고객: "주문이 도착하지 않았어요. 프리미엄 회원이에요."
                    │
                    ▼
2. Alex (코디네이터)가 메시지를 받음
   └── 공유 메모리 조회: "프리미엄 고객에 대해 뭘 알고 있지?"
   └── 발견: "프리미엄 회원은 48시간 빠른 환불을 받습니다"
   └── 결정: "Sam(주문)과 Jordan(기술 확인)이 필요해"
                    │
                    ▼
3. Alex가 전문가들에게 A2A 메시지 전송:
   ├── Sam에게: "이 고객의 주문 상태 확인해줘"
   └── Jordan에게: "배송 시스템이 작동하는지 확인해줘"
                    │
                    ▼
4. 전문가들이 병렬로 작업:
   ├── Sam: 주문 이력 접근, 배송 지연 발견
   └── Jordan: 시스템 정상 작동 확인, 광범위한 문제 없음
                    │
                    ▼
5. 결과가 Alex에게 돌아옴
   └── Alex 종합: "주문이 지연됨 (시스템 전체 문제 아님), 
                   고객은 빠른 환불 자격이 있음"
                    │
                    ▼
6. Alex가 전체 맥락을 가지고 고객에게 응답

메모리 동기화 메커니즘

Sam이 이 고객에게 이전에도 배송 문제가 있었다는 것을 발견하면, 그 정보는 공유 메모리에 들어갑니다:

# 이것은 작업 처리 중 자동으로 발생합니다
new_memory = Memory(
    content="고객 #12345 배송 지연 경험 - 3번째 발생",
    type=MemoryType.EPISODIC,
    scope=MemoryScope.SHARED,  # <-- 모든 에이전트에게 보이게 함
    confidence=0.95
)
memory_manager.add_memory(new_memory)

이제 어떤 에이전트가 이 고객을 상대하든, 이력을 알게 됩니다.

실제로 동작하는 것을 봅시다: 실제 데모

이론은 충분합니다. 이것을 실제로 어떻게 사용하는지 봅시다.

설정하기

필수 조건:

# Ollama 설치하고 phi4-mini 가져오기
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull phi4-mini
ollama serve

백엔드 시작:

cd backend
source venv/bin/activate
python3 api.py  # http://localhost:5001에서 실행

프론트엔드 시작:

cd frontend
npm run dev  # http://localhost:3000에서 실행

고객 서비스 시나리오

1단계: 공유 메모리 로드

curl -X POST http://localhost:5001/api/memory/demo/prepare

이것은 다음을 미리 로드합니다:

• 고객 프로필 (누가 무엇을 선호하는지)
• 환불 정책 (프리미엄 회원이 받는 것)
• 해결 워크플로우 (일반적인 문제 처리 방법)

2단계: Alex에게 복잡한 요청 보내기

http://localhost:3000/agents로 이동하여 Alex를 선택하고 다음을 보냅니다:

"고객이 최근 주문이 도착하지 않았다고 보고하고 환불을 요청하고 있습니다. 이전에 이메일 통신을 선호한다고 언급했고 프리미엄 회원입니다."

3단계: 협업이 펼쳐지는 것을 관찰

로그 페이지(http://localhost:3000/logs)를 열고 관찰하세요:

• Alex가 작업을 분석하고 누구를 참여시킬지 결정
• 에이전트 간 A2A 메시지가 오가는 것
• 공유 메모리가 접근되고 업데이트되는 것
• 최종 조율된 응답이 함께 만들어지는 것

볼 수 있는 것

Alex의 조율:

"우리 팀을 조율하여 이 프리미엄 고객 문제를 처리하겠습니다. 공유 메모리에 따르면, 이 고객은 이메일을 선호하고 빠른 서비스 자격이 있습니다..."

Sam의 주문 분석:

"주문 관리 관점에서, 주문이 발송되었지만 추적에서 지연이 보입니다. 고객은 48시간 프리미엄 환불 자격이 있습니다..."

Jordan의 기술 확인:

"배송 알림 시스템이 정상 작동하는 것을 확인했습니다. 지연은 우리 쪽이 아닌 배송사 관련 문제로 보입니다..."

종합된 응답:

"연락해 주셔서 감사합니다. 저희 팀이 귀하의 케이스를 검토했습니다: [구체적인 주문 세부 사항], [무엇이 잘못되었는지], [우리가 어떻게 처리하고 있는지]. 빠른 환불이 48시간 내에 처리되며, 이메일 확인을 받으실 것입니다..."

코드: 핵심 구현 패턴

우리가 개발한 흥미로운 코드 패턴들을 살펴봅시다.

메모리 추출: 기억할 가치가 있는 것 찾기

class MemoryExtractor:
    # 명시적 메모리 명령 패턴
    EXPLICIT_PATTERNS = [
        r"remember (?:that )?(.+)",
        r"don't forget (?:that )?(.+)",
        r"note (?:that )?(.+)",
    ]
    
    # 암시적 사실 패턴 (명령하지 않아도 기억할 가치가 있는 것들)
    FACT_PATTERNS = [
        r"(?:my|our|the) (\w+) is (.+)",
        r"i (?:prefer|like|want|need) (.+)",
        r"we (?:always|usually|typically) (.+)",
    ]
    
    def extract_from_text(self, text: str) -> List[Memory]:
        memories = []
        
        # 명시적 메모리는 높은 신뢰도를 받음
        for pattern in self.EXPLICIT_PATTERNS:
            if match := re.search(pattern, text.lower()):
                memories.append(Memory(
                    content=match.group(1),
                    mechanism=CreationMechanism.EXPLICIT,
                    confidence=0.95  # 직접 명령은 높은 신뢰도
                ))
        
        # 암시적 메모리는 낮은 신뢰도를 받음
        for pattern in self.FACT_PATTERNS:
            if match := re.search(pattern, text.lower()):
                memories.append(Memory(
                    content=match.group(0),
                    mechanism=CreationMechanism.IMPLICIT,
                    confidence=0.70  # 추론된 사실은 낮은 신뢰도
                ))
        
        return memories

왜 신뢰도 점수인가요? 모든 정보가 동등하게 신뢰할 수 있는 것은 아니기 때문입니다. 직접적인 "이것을 기억해" 명령은 맥락에서 우리가 추론한 것보다 더 신뢰할 수 있습니다.

의미 검색: 관련 메모리 찾기

class SemanticMemoryStore:
    def search(self, query: str, top_k: int = 5) -> List[Tuple[Memory, float]]:
        # 쿼리를 벡터로 변환
        query_embedding = self.embedder.embed(query)
        
        # 유사한 메모리 찾기
        results = self.vector_store.similarity_search(
            query_embedding,
            top_k=top_k,
            filter={"confidence": {"$gte": 0.7}}  # 높은 신뢰도 메모리만
        )
        
        return [(self.memories[id], score) for id, score in results]

왜 키워드 매칭 대신 벡터 검색인가요? "고객이 이메일을 선호함"이 "통신 선호도"에 대한 쿼리와 일치해야 하기 때문입니다. 비록 그 단어들이 정확히 겹치지 않더라도요.

A2A 브릿지: 에이전트 간 통신

class A2AMemoryBridge:
    def sync_memory_to_agents(self, memory: Memory, target_agents: List[str]):
        # 메모리 페이로드로 A2A 메시지 생성
        message = A2AMessage(
            source_agent=self.agent_id,
            content_type="application/vnd.a2a.memory-sync+json",
            payload={
                "memories": [memory.to_dict()],
                "source_confidence": memory.confidence,
                "sync_timestamp": datetime.utcnow().isoformat()
            }
        )
        
        for target in target_agents:
            # 각 대상에게 전송
            self.send_message(target, message)
            
            # 수신하는 에이전트는 신뢰도 할인 적용
            # (간접 정보는 약간 덜 신뢰할 수 있음)
            received_memory = memory.copy()
            received_memory.confidence *= 0.9
            target_bridge = self.get_bridge(target)
            target_bridge.memory_manager.add_memory(received_memory)

왜 0.9 신뢰도 승수인가요? 전화 게임처럼 생각하세요. 여러 사람을 거쳐 전달된 정보는 직접 얻은 지식보다 약간 덜 신뢰할 수 있습니다. 우리는 그 불확실성을 시스템에 직접 인코딩합니다.

성능: 이것이 실제로 확장되나요?

숫자에 대해 솔직해집시다.

컨텍스트 윈도우 사용

phi4-mini의 128k 토큰 한계로:

• 평균 대화: 2,000-8,000 토큰
• 세션당 저장된 메모리: 50-100개
• 동시에 협업하는 에이전트: 3-5개
• 압축 전 연속 세션 시간: 4-6시간

지연 시간

목표 (Google 백서에서): 메모리 조회 200ms 미만

우리의 벤치마크:

• 벡터 유사성 검색: 1000개 메모리에 ~50ms
• 전체 컨텍스트 조립: ~150ms
• A2A 메시지 라우팅: ~30ms

예산 내에 있지만, 최적화할 여지는 항상 있습니다.

프로덕션을 위해 무엇을 바꿀 것인가요?

이것은 참조 구현입니다. 실제 프로덕션 사용을 위해:

배운 교훈: 우리를 놀라게 한 것들

이것을 구축하면서 예상치 못한 몇 가지를 배웠습니다.

1. 메모리 추출은 보기보다 어렵습니다

초기 접근 방식은 너무 공격적이었습니다—모든 것을 저장하고 있었습니다. 결과는요? 검색 결과를 덜 유용하게 만드는 노이즈가 많은 메모리. 핵심은 선택적이 되는 것이었습니다: 명시적 명령과 명확한 선호도 진술만.

2. 신뢰도 점수는 필수입니다

모든 메모리가 동등하게 신뢰할 수 있는 것은 아닙니다. 고객이 한 대화에서 "이메일을 선호해요"라고 말하는 것은 여러 세션에 걸쳐 세 번 말하는 것보다 덜 확실합니다. 신뢰도 점수를 핵심 데이터 모델에 구축해야 했습니다.

3. 압축 전략은 생각보다 중요합니다

처음에는 단순 잘라내기를 기본값으로 했습니다. 나쁜 아이디어였습니다. 대화 초반의 중요한 맥락이 삭제되고 있었습니다. 요약 기반 압축은 추가적인 복잡성을 감수할 가치가 있었습니다.

4. A2A 프로토콜은 신중한 설계가 필요합니다

에이전트 간 통신은 루프와 불일치의 가능성을 만듭니다. 몇 가지 안전장치를 추가했습니다:

• 메시지 중복 제거
• 전달된 정보에 대한 신뢰도 감소
• 디버깅을 위한 명확한 소스 추적

다음은 무엇인가요?

우리는 끝나지 않았습니다. 탐색 중인 것들:

단기:

• 의미 검색을 위한 더 나은 임베딩 모델
• 영구 저장소 백엔드 (현재 인메모리)
• 메모리 업데이트를 위한 더 정교한 충돌 해결

장기:

• 메모리 통합 (인간의 수면처럼, 기억이 재구성되는 것)
• 에이전트 네트워크 간 연합 학습
• 프라이버시 보존 메모리 공유

직접 해보세요

모든 것이 오픈 소스입니다. 클론하고, 실행하고, 부수고, 개선하세요.

git clone https://github.com/your-org/a2a-memory-layer
cd a2a-memory-layer

# 백엔드
cd backend && pip install -r requirements.txt && python api.py

# 프론트엔드 (새 터미널)
cd frontend && npm install && npm run dev

# http://localhost:3000/agents 열기

데모 시나리오가 미리 구성되어 있습니다. 클릭하면서 에이전트들이 협업하는 것을 지켜보세요.

감사의 말

이 프로젝트는 거인들의 어깨 위에 서 있습니다:

• Google의 Context Engineering 팀 - 기초가 된 백서
• Ollama - 로컬 LLM 배포를 접근 가능하게 만들어줌
• 오픈소스 커뮤니티 - Flask, Next.js, 그리고 수많은 다른 도구들

기여하고 싶으신가요?

다음에 대한 도움을 환영합니다:

🔗 Demo Repository: https://github.com/Sardor-M/a2a-memory-system

• 새로운 메모리 압축 알고리즘
• 새로운 에이전트 전문화
• 성능 최적화
• 더 나은 문서 (네, 이 README 포함)

이슈를 열거나 PR을 제출하세요. 함께 흥미로운 것을 만들어봅시다.

들어가며

[시리즈1]에서는 프로세스 내부 메시지 큐를 다뤘습니다. 이번엔 네트워크 메시지 큐인 RabbitMQ를 다룹니다.

RabbitMQ 공식 문서나 기술 블로그는 많지만, 실무에서 어떻게 사용하는지에 대한 글은 의외로 적습니다.

"Producer가 뭐고 Consumer가 뭔지는 알겠는데, 그래서 실제로는 어떻게 쓰는데?"

이번 글에서는 우리 MES 시스템에서 RabbitMQ를 어떻게 활용하고 있는지 실제 코드와 함께 공유합니다.

우리 시스템의 구성

MES 시스템은 관리자 PC 1대와 현장 Worker PC 수십 대가 연동됩니다. 관리자가 생산지시를 등록하면, 현장의 모든 Worker PC에 즉시 알림이 전달되어야 합니다.

현재 사용 중인 방식: RabbitMQ

RabbitMQ 아키텍처

┌───────────────────────────────────────────────────────────┐
│                     RabbitMQ Server                       │
│                                                           │
│  ┌─────────┐    ┌──────────┐    ┌───────┐    ┌──────────┐ │
│  │Producer │───→│ Exchange │───→│ Queue │───→│ Consumer │ │
│  │(서버)   │    │(라우팅)   │    │(대기열)│   │(클라이언트)││
│  └─────────┘    └──────────┘    └───────┘    └──────────┘ │
│                                                           │
└───────────────────────────────────────────────────────────┘

Producer: Spring Boot API 서버
Exchange: 라우팅 규칙에 따라 메시지 전달
Queue:    각 Worker PC별 메시지 대기열 (ALARM_QUE_WPC001)
Consumer: C# Worker PC 클라이언트

실제 동작 방식

관리자가 생산지시 등록
  │
  └─→ RabbitMQ에 메시지 던짐 (끝!)
      │
      ├─→ Worker PC 1 (즉시 전달)
      ├─→ Worker PC 2 (네트워크 복구 시 자동 전달)
      └─→ Worker PC 3 (즉시 전달)

서버는 메시지 전송 후 바로 다음 작업 처리 가능

장점:

• 서버는 RabbitMQ에만 메시지 전달 (블로킹 없음)
• 네트워크 장애 시 자동 재시도
• Worker PC 증설 시 코드 수정 불필요

시스템 구조

MES 알림 시스템 전체 흐름

┌─────────────────┐
│   관리자 PC      │  1. 생산지시 등록
│                 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐       ┌─────────────────┐
│  Spring Boot    │──────→│    RabbitMQ     │  2. 메시지 발송
│   API 서버      │   2-1 │     서버         │
└─────────────────┘       └────────┬────────┘
                                   │ 3. 라우팅
         ┌─────────────────────────┼─────────────────────────┐
         ▼                         ▼                         ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Worker PC 1   │     │   Worker PC 2   │     │   Worker PC 3   │
│   (설비 A)      │     │   (설비 B)       │     │   (설비 C)      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
  4. 알림 팝업 표시         4. 알림 팝업 표시       4. 알림 팝업 표시
  5. 데이터 새로고침        5. 데이터 새로고침       5. 데이터 새로고침

메시지 타입 정의

// 실시간 알림 메시지 타입
public enum MqMessageType
{
    WORKORDER_ADDED,      // 생산지시 추가
    WORKORDER_DELETED,    // 생산지시 삭제
    ...
}

코드로 보는 실제 구현

서버 측 (Spring Boot)

1. 설정 (application.yml)

spring:
  rabbitmq:
    host: 192.xxx.xxx.xxx
    port: 5672
    username: xxx
    password: xxx

  alarmmq:
    exchange: alarm.topic # Topic Exchange
    queue: ALARM_QUE_ # 큐 접두사

2. 메시지 발송 API

@RestController
@RequestMapping("/api")
public class QueueController {

    private final RabbitTemplate rabbitTemplate;

    @Value("${spring.alarmmq.exchange}")
    private String EXCHANGE_NAME;

    @PostMapping("/messagePub")
    public CommonResult MessagePub(@RequestBody AlarmInfo[] alarmInfo) {
        try {
            // 1. 수신자 목록 추출
            HashSet<String> userNoSet = new HashSet<>();
            for (AlarmInfo alarm : alarmInfo) {
                userNoSet.add(alarm.getUserNo());
            }

            // 2. 사용자별 큐 생성 및 바인딩
            for (String userNo : userNoSet) {
                Queue queue = new Queue("ALARM_QUE_" + userNo, true);
                amqpAdmin.declareQueue(queue);

                TopicExchange exchange = new TopicExchange(EXCHANGE_NAME);
                amqpAdmin.declareBinding(
                    BindingBuilder.bind(queue).to(exchange).with(userNo + ".#")
                );
            }

            // 3. 메시지 발송
            for (AlarmInfo alarm : alarmInfo) {
                rabbitTemplate.convertAndSend(
                    EXCHANGE_NAME,         // Exchange
                    alarm.getUserNo(),     // 라우팅 키
                    alarm                  // 메시지
                );
            }

            return responseService.getSuccessResult();
        } catch (Exception e) {
            return responseService.getFailResult("MQE001", "메시지 전송 실패");
        }
    }
}

클라이언트 측 (C# WinForms)

1. MQ 클라이언트 초기화

public class BackgroundForm : BackgroundFormUI
{
    private MqClient mqClient;

    private void InitializeMqClient()
    {
        // 큐 이름: workerPc.WPC001
        string queue = "workerPc." + ConnectionConfig.WorkerPcId;

        mqClient = new MqClient(queue);
        mqClient.MessageQueueReceived += MqClient_MessageQueueReceived;

        if (mqClient.IsOpen)
            ShowNotification("MQ 서버 연결 성공", NotificationType.Success);
        else
            ShowNotification("MQ 서버 연결 실패", NotificationType.Error);
    }
}

2. 메시지 수신 처리

private void MqClient_MessageQueueReceived(MqMessageModel mqMessage)
{
    string message = string.Empty;

    switch (mqMessage.MqMessage)
    {
        case MqMessageType.WORKORDER_ADDED:
        case MqMessageType.WORKORDER_DELETED:
            message = "생산지시 정보가 업데이트 되었습니다.";
            WorkorderUpdateRequired?.Invoke(mqMessage.MchId, null);
            break;

        ...
    }

    // UI 스레드에서 알림 표시
    this.BeginInvoke(new MethodInvoker(delegate
    {
        TrayNotification frm = new TrayNotification();
        frm.showAlert(message, TrayNotification.enmType.Info);
    }));
}

메시지 흐름 (시퀀스 다이어그램)

┌────────┐   ┌─────────┐   ┌─────────┐   ┌──────────┐   ┌──────────┐
│ 관리자 │   │  API    │   │RabbitMQ │   │  Queue   │   │ Worker   │
│   PC   │   │ Server  │   │ Server  │   │          │   │   PC     │
└───┬────┘   └────┬────┘   └────┬────┘   └────┬─────┘   └────┬─────┘
    │             │              │             │             │
    │생산지시 등록 │              │             │              │
    │────────────>│              │             │              │
    │             │              │             │              │
    │             │DB 저장       │             │              │
    │             │              │             │              │
    │             │메시지 발송    │             │              │
    │             │─────────────>│             │              │
    │             │              │             │              │
    │             │              │큐에 저장      │             │
    │             │              │────────────>│              │
    │             │              │             │              │
    │             │              │             │메시지 전달    │
    │             │              │             │─────────────>│
    │             │              │             │              │
    │             │              │             │  알림 표시    │
    │             │              │             │  데이터 갱신  │
    │             │              │             │              │

소요 시간: 메시지 발송부터 클라이언트 수신까지 평균 50~100ms

Exchange 타입과 라우팅

Topic Exchange (현재 시스템)

라우팅 패턴: "사용자번호.#"

┌─────────────────┐
│  Topic Exchange │
│  "alarm.topic"  │
└────────┬────────┘
         │ 라우팅 키: "WPC001"
         │
    ┌────┴────┬─────────────┐
    ▼         ▼             ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Queue 1 │ │ Queue 2 │ │ Queue 3 │
│ WPC001  │ │ WPC002  │ │ WPC003  │
│  .#     │ │  .#     │ │  .#     │
└─────────┘ └─────────┘ └─────────┘
   ✅ 전달    ❌ 불일치   ❌ 불일치

Exchange 타입 비교

마치며

Windows 메시지 큐 vs RabbitMQ

핵심 포인트

"서버와 클라이언트를 느슨하게 연결하라"

• 직접 호출: 강한 결합 (한 대 장애 = 전체 영향)
• RabbitMQ: 느슨한 결합 (메시지만 던지고 끝)

이 패턴은 Kafka, Redis Pub/Sub 등 다른 메시징 시스템에도 동일하게 적용됩니다.

이 글이 도움이 되었으면

이 글은 레거시 MES 시스템을 하자보수하면서 배운 내용입니다.
화려한 신규 프로젝트가 아니어도, 누군가 만들어둔 시스템을 이해하고 문제를 해결하는 과정에서 배우는 것도 많습니다.

메시지 큐에 대한 개념 글이나 아키텍처 다이어그램은 많지만, 정작 "실무에서 어떻게 쓰는데?" 에 대한 답은 의외로 찾기 어려웠습니다. 비슷한 궁금증을 가졌던 분들께 이 글이 조금이나마 도움이 되었으면 합니다.

감사합니다.

참고 자료

• RabbitMQ 공식 문서

들어가며

이 글은 "실무로 배우는 메시지 큐" 시리즈의 첫 번째 글입니다.

실무에서 발견한 문제를 해결하는 과정에서, IME 입력 문제와 해결 과정을 공유합니다.

메시지 큐는 RabbitMQ, Kafka 같은 네트워크 레벨만 있는 게 아닙니다. 우리가 매일 쓰는 Windows 애플리케이션도 메시지 큐 기반으로 동작합니다.

• 시리즈1 (이 글): 프로세스 내부의 메시지 큐 - Windows Message Loop의 이해와 활용
• 시리즈2: 네트워크 레벨의 메시지 큐 - RabbitMQ

문제 상황

MES 시스템 운영 중 고객으로부터 이런 문의가 반복적으로 들어왔습니다.

"설비코드 검색이 안 돼요. 분명히 SS0002 입력했는데..."

확인해보니 실제 입력된 값은 ＳＳ０００２ (전각 문자)였습니다. 작업자들이 메모장, 엑셀, MES를 오가며 작업하다 보니 IME 상태가 전각 모드로 고정되어 발생한 문제였습니다.

반각: SS0002, ABC123  → 검색 가능
전각: ＳＳ０００２, ＡＢＣ１２３  → 검색 불가

처음엔 특정 메뉴에만 적용하려 했으나, 여러 화면에서 동일한 문제가 발생해 전체 시스템 레벨에서 해결하기로 했습니다.

시도한 방법들

| 방법                      | 결과 | 문제점                                     |
| ------------------------- | ---- | ------------------------------------------ |
| TextChanged 이벤트        | ❌   | 무한 루프 (Text 변경 → 이벤트 발생 → 반복) |
| KeyPress 이벤트           | ❌   | IME 조합 중 문자 캐치 못함                 |
| IMessageFilter (WM_CHAR)  | ❌   | WM_IME_CHAR는 조합 완료 후에만 도착        |
| Form.Activated + IME 리셋 | △    | 메인폼만 동작, 팝업은 안 됨                |
| **Application.Idle**      | ✅   | **모든 폼에서 동작, 입력 직후 변환**       |

해결책: Application.Idle 이벤트

Windows 메시지 큐 아키텍처

Windows Forms는 메시지 큐 기반으로 동작합니다. 모든 사용자 입력(키보드, 마우스)은 메시지로 변환되어 큐에 쌓이고, Application.Run이 순차적으로 처리합니다.

┌─────────────────────────────────────────────────────┐
│              Windows Message Queue                  │
│  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐            │
│  │ WM_  │→ │ WM_  │→ │ WM_  │→ │ WM_  │  ...       │
│  │ KEY  │  │ IME  │  │MOUSE │  │PAINT │            │
│  │ DOWN │  │ CHAR │  │ MOVE │  │      │            │
│  └──────┘  └──────┘  └──────┘  └──────┘            │
└─────────────────────────────────────────────────────┘
         │
         ▼
    ┌─────────────────┐
    │Application.Run  │  ← 메시지 루프 (Message Pump)
    │  (Main Thread)  │
    └─────────────────┘
         │
         ├─→ 큐에 메시지 있음 → 메시지 처리
         │                      (WM_IME_CHAR → TextBox에 'Ａ' 입력)
         │
         └─→ 큐가 비어있음 → Application.Idle 발생 ⚡
                              (우리 코드 실행: 'Ａ' → 'A' 변환)

핵심 아이디어

Application.Idle은 메시지 큐가 비어있을 때, 즉 모든 입력 처리가 완료된 직후 발생합니다.

// Application.Run 내부 동작 (의사 코드)
while (프로그램 실행 중)
{
    if (메시지큐에 메시지 있음)
        메시지 처리();  // WM_KEYDOWN → TextBox 입력
    else
        Application.Idle 발생();  // ← 여기서 변환!
}

타이밍 비교: 왜 Idle이 완벽한가?

타임라인: 전각 'Ａ' 입력 시 각 이벤트 발생 시점
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[입력 시작]    [IME 조합]    [문자 확정]    [화면 업데이트]
     │             │             │                │
     ▼             ▼             ▼                ▼
─────●─────────────●─────────────●────────────────●──────→ 시간

     ❌ KeyPress      (너무 빠름 - IME 조합 전이라 캐치 못함)

                  ❌ IMessageFilter (이미 조합 완료 후)

                                ❌ TextChanged (변환 시 다시 발생 → 무한루프)

                                               ✅ Application.Idle
                                               (큐 비었음 = 입력 완료)

Application.Idle이 완벽한 이유:

• ✅ 입력이 완료된 후 호출 (TextBox에 이미 표시된 상태)
• ✅ 한 번만 실행 (무한루프 없음)
• ✅ 모든 폼에서 자동 동작

구현 코드

Program.cs

static void Main()
{
    Application.EnableVisualStyles();
    Application.SetCompatibleTextRenderingDefault(false);

    // 전각→반각 자동 변환 등록
    Application.Idle += FullWidthConverter.Application_Idle;

    Application.Run(new MainForm());
}

FullWidthConverter.cs

public static class FullWidthConverter
{
    public static void Application_Idle(object sender, EventArgs e)
    {
        try
        {
            Control focused = GetFocusedControl();
            if (focused == null) return;

            // 포커스된 컨트롤의 텍스트 변환
            if (focused is TextBox tb)
                ConvertText(tb, () => tb.Text, s => tb.Text = s,
                            () => tb.SelectionStart, v => tb.SelectionStart = v);
            // TextEdit, ComboBoxEdit 등 동일 패턴
        }
        catch { }
    }

    private static string ToHalfWidth(string s)
    {
        if (string.IsNullOrEmpty(s)) return s;
        char[] c = s.ToCharArray();

        for (int i = 0; i < c.Length; i++)
        {
            // 전각 공백 → 반각
            if (c[i] == '\u3000') c[i] = ' ';
            // 전각 ASCII → 반각 (0xFEE0 차이)
            else if (c[i] >= '\uFF01' && c[i] <= '\uFF5E')
                c[i] = (char)(c[i] - 0xFEE0);
        }

        return new string(c);
    }
}

전각↔반각 변환 원리

전각 'Ａ' = U+FF21
반각 'A'  = U+0041
차이값    = 0xFEE0  ← 이 값만 빼면 변환 완료

실행 흐름 (시퀀스 다이어그램)

사용자가 전각 'Ａ' 입력 시

┌─────────┐         ┌──────────┐         ┌─────────────┐         ┌──────────────┐
│  사용자 │         │ Windows  │         │ Message Queue│        │FullWidth     │ 
│         │         │   OS     │         │             │         │Converter     │
└────┬────┘         └────┬─────┘         └──────┬──────┘         └──────┬───────┘
     │                   │                      │                       │
     │ 'Ａ' 키 입력      │                       │                       │
     │──────────────────>│                       │                       │
     │                   │                       │                       │
     │                   │ WM_IME_CHAR 생성      │                       │
     │                   │──────────────────────>│                       │
     │                   │                       │                       │
     │                   │    메시지 처리 시작    │                       │
     │                   │<──────────────────────│                       │
     │                   │                       │                       │
     │                   │  TextBox.Text = "Ａ"  │                       │
     │                   │  (화면에 전각 표시)    │                       │
     │                   │                       │                       │
     │                   │  큐가 비어있음!        │                       │
     │                   │  Application.Idle 발생│                       │
     │                   │───────────────────────────────────────────────>│
     │                   │                       │                       │
     │                   │                       │    'Ａ' → 'A' 변환     │
     │                   │                       │    TextBox.Text = "A" │
     │                   │                       │                       │
     │    화면에 'A' 표시 (너무 빨라서 'Ａ'는 못 봄)                        │
     │<───────────────────────────────────────────────────────────────────│
     │                   │                       │                       │

소요 시간: 전체 과정이 약 10ms 이내에 완료되어 사용자는 전각 입력을 인지하지 못합니다.

붙여넣기(Ctrl+V)도 동일: WM_PASTE 메시지 처리 후 Idle 발생 → 변환

성능 영향

Q: Idle 이벤트가 너무 자주 호출되지 않나요?

실제 측정 결과 CPU 사용량 0.01% 미만입니다.

마치며

적용 결과

• ✅ 전각 문자 입력 문의 100% 해소
• ✅ 사용자 추가 조작 불필요 (자동 변환)
• ✅ 기존 코드 수정 없이 Program.cs 한 줄 추가로 전체 적용

핵심 교훈

"타이밍이 중요하다"

• TextChanged: 너무 빠름 (변경 중)
• KeyPress: 너무 빠름 (조합 전)
• Application.Idle: 딱 맞음 (입력 완료 직후)

Windows 메시지 루프를 이해하면 비슷한 UI 타이밍 문제를 해결할 때 유용합니다.

참고 자료

• Microsoft Docs - Application.Idle Event
• Unicode Full-width Forms
• Windows Message Loop

다음 글 예고
이번 글은 프로세스 내부 메시지 큐를 다뤘습니다.
다음 편에서는 네트워크 간 메시지 큐인 RabbitMQ를 다룹니다.

이 글은 1편 - 그림으로 풀어낸 SaaS 알림 시스템의 후속편입니다.

들어가며

1편에서는 설비 연속 OFF 알림 기능의 핵심 로직과 어떤식으로 해결했는지 그림으로 알아봤습니다.

이번 글에서는 실무에서 마주한 진짜 고민들을 공유합니다:

• 왜 3개의 새로운 테이블이 필요했나?
• 어떻게 확장 가능한 구조를 만들었나?
• SMS 14원짜리 알림이 왜 무서운가?
• 운영 레벨로 나가기까지 무엇을 준비했나?

1. 시스템 구성과 테이블 설계

1.1 기존 시스템 파악하기

먼저 사용해야 되는 기존 테이블들을 살펴봤습니다:

기존 테이블
├── company
├── factory
├── machine
├── monitoring       # 설비 모니터링 데이터
├── user
└── notification

monitoring 테이블은 실시간으로 데이터를 받아 저장하는 핵심 테이블로, onoff_monitored(설비 ON/OFF), spm(분당 회전수), vibration(진동), current(전류) 등 다양한 데이터를 저장합니다.

이 테이블을 보면서 중요한 깨달음을 얻었습니다:

"연속 OFF 알림"은 시작일 뿐이다.
SPM 이상, 진동 임계치 초과, 전류 급등 등 다양한 알림이 필요할 것이다.
또는 다른 테이블에 있는 특정값을 사용할수도 있을것이다.

1.2 새로운 테이블 설계

회사별로 다양한 알람을 적용하고 관리할수있게 3개의 새로운 테이블을 설계했습니다:

1️⃣ alert_rule - 알림 규칙 정의

회사별로 어떤 알림을 어떤 조건으로 받을지 설정하는 테이블입니다.

CREATE TABLE alert_rule (
    ...
);

핵심 컬럼: id(PK), id_company, rule_type(확장 포인트), count, enabled, resend_interval_minutes

rule_type으로 확장 가능한 구조입니다. 현재는 CONSECUTIVE_OFF(연속 OFF)만 구현되어 있지만, 향후 SPM_ABNORMAL, VIBRATION_HIGH, CURRENT_SPIKE 등 다양한 알림 타입을 DB 데이터만 추가해서 지원할 수 있습니다.

2️⃣ alert_machine - 알림 이력 관리

어떤 설비에 언제 알림이 발생했는지, 언제 해소되었는지 추적하는 테이블입니다.

CREATE TABLE alert_machine (
    ...
);

핵심 컬럼: id(PK), id_machine, alert_type, resolved_at(NULL이면 미해결)

3️⃣ shedlock - 분산 스케줄러 동기화

CREATE TABLE shedlock (
    ...
);

다중 서버 환경에서 스케줄러가 중복 실행되지 않도록 락을 관리합니다.

결과: 해당 스케줄러가 돌때 필요한 테이블 기존 테이블 6개 + 신규 테이블 3개 = 총 9개 테이블 사용

2. 확장 가능한 스케줄러 아키텍처

2.1 왜 하나의 스케줄러에서 모든 알림을 처리하나?

초기에는 "알림 타입마다 별도 스케줄러를 만들면 되지 않나?"라고 생각했습니다:

// ❌ 알림 타입마다 스케줄러 생성?
@Scheduled(cron = "0 * * * * *")
public void checkConsecutiveOffAlerts() { ... }

@Scheduled(cron = "0 * * * * *")
public void checkSpmAbnormalAlerts() { ... }

@Scheduled(cron = "0 * * * * *")
public void checkVibrationHighAlerts() { ... }

하지만 이 방식은 리소스 낭비(각 스케줄러가 독립적으로 DB 조회), 확장성 제한(새 타입 추가 시 배포 필요), 유지보수 어려움(공통 로직 중복) 등의 문제가 있습니다.

2.2 단일 스케줄러 + 알림 타입 반복 구조

대신 하나의 스케줄러에서 활성화된 알림 규칙을 반복 처리하는 구조를 선택했습니다:

@Scheduled(cron = "0 * * * * *")
@SchedulerLock(name = "alertScheduler", lockAtMostFor = "50s", lockAtLeastFor = "10s")
@Transactional
public void checkAlerts() {
    // 1. 활성화된 알림 규칙 조회 (모든 타입)
    List<AlertRuleDto> activeRules = alertRuleRepository.findEnabledRulesAsDto();

    // 2. 각 규칙별로 처리
    for (AlertRuleDto rule : activeRules) {
        checkRuleForCompany(rule);  // 회사별 알림 체크
    }
}

하나의 실행 컨텍스트를 공유해 리소스 효율적이고, DB에 rule_type만 추가하면 새로운 알림 타입을 지원할 수 있습니다.

3. 운영을 고려한 방어적 설계와 테스트

3.1 개발 환경에서의 테스트

운영 규모는 회사 N개, 공장 M개, 설비 총 OO대 수준. 장애가 났을 때를 가정한 네거티브 테스트를 빡세게 진행했습니다.

3.2 비용과 안정성에 대한 고민

실제로는 SMS를 사용하진 않지만, 만약 SMS 문자 기능이 붙는다면? 이런 시나리오까지 고려했습니다.

건당 비용이 발생하는 기능에서 재전송 로직이나 해제 조건에 버그가 있으면 같은 알림이 반복 발송됩니다. 설비 몇 대 × 관리자 여러 명. 매 분마다 잘못 나가면 비용이 기하급수적으로 증가합니다.

그만큼 안정적으로 고민했습니다:

• 재전송 주기 엄격한 체크
• 하루 최대 발송 제한 (per 설비)
• 중복 전송 방지 로직
• 알림 발송 전 최종 검증

4. 확장성을 고려한 아키텍처

4.1 알림 타입별 검증 로직 분리

현재는 연속 OFF만 구현되어 있지만, 향후 확장을 위해 검증 로직을 분리했습니다:

@Component
public class AlertRuleChecker {

    // 연속 OFF 검증
    public boolean checkConsecutiveOff(
        List<MonitoringAlertDto> data,
        int requiredCount
    ) {
        // 1. 개수 체크
        // 2. 모두 OFF 상태 확인
        // 3. 시간 간격 검증 (3분 이내)
    }

    // 향후 추가 가능
    public boolean checkSpmAbnormal(
        List<MonitoringAlertDto> data,
        int threshold
    ) {
        // SPM 이상 검증 로직
    }

    public boolean checkVibrationHigh(
        List<MonitoringAlertDto> data,
        float threshold
    ) {
        // 진동 임계치 초과 검증 로직
    }
}

Strategy Pattern 적용 고려:

public interface AlertCheckStrategy {
    boolean check(List<MonitoringAlertDto> data, AlertRuleDto rule);
}

@Component
public class ConsecutiveOffStrategy implements AlertCheckStrategy {
    @Override
    public boolean check(List<MonitoringAlertDto> data, AlertRuleDto rule) {
        // 연속 OFF 검증
    }
}

5. 마치며

항상 요구사항은 쉬워 보입니다.

"설비 이상 OFF 시 알람 보내는 기능 필요합니다."

단순해 보이지만, 실제로는:

• 멀티테넌시 환경에서 회사별로 다른 규칙 적용
• 확장성 고려 (연속 OFF뿐 아니라 SPM, 진동, 전류 등 다양한 알림 타입)
• 성능 최적화 (수천 대 설비를 1분마다 실시간 체크)
• 비용 관리 (만약을 대비한 방어적 설계)
• 안정성 고려 (알림 하나도 신중하게)

까놓고 보니 하나의 프로젝트급이었습니다.

어떤 서비스에서 어떤 레벨로 구현하느냐에 따라 난이도는 천차만별입니다. 단순 기능 구현을 넘어 확장 가능한 시스템 설계와 운영을 고려한 방어적 코딩까지 고민한 값진 경험이었습니다.

감사합니다.

제조업 IoT 플랫폼에서 N대 이상의 설비를 실시간으로 모니터링하고, 설비가 연속으로 꺼졌을 때 담당자에게 즉시 알림을 보내는 기능을 개발하게 되었습니다.

데이터는 실시간으로 쌓이지만, 설비이상을 체크하는 스케줄러 주기는 1분으로 설정하였습니다.

시스템 아키텍처

기존 인프라와 Push 기능은 이미 구축되어 있었습니다.

저는 중간에 들어가는 Alert Scheduler만 구현하면 되는 상황이었습니다.

┌──────────────────────────────────────────────────────────┐
│  설비 IoT 센서 (실시간)                                  │
│  - N개 회사, M개 공장, 수백 대 설비                      │
└──────────────────────────────────────────────────────────┘
                        ↓
┌──────────────────────────────────────────────────────────┐
│  IoT Hub                                                 │
│  - 실시간 데이터 수집                                    │
└──────────────────────────────────────────────────────────┘
                        ↓
┌──────────────────────────────────────────────────────────┐
│  Dataframe (Stream Processing)                           │
│  - 스트림 데이터 처리                                    │
└──────────────────────────────────────────────────────────┘
                        ↓
┌──────────────────────────────────────────────────────────┐
│  MSSQL Monitoring 테이블                                 │
│  - 실시간 적재 (분당 수천 건)                            │
│  - id_machine, onoff_monitored, monitored_at_datetime    │
└──────────────────────────────────────────────────────────┘
                        ↓
┌──────────────────────────────────────────────────────────┐
│  ⚙️ Alert Scheduler (구현 부분)                         │
│  - @Scheduled(cron = "0 * * * * *") - 매 분 0초 실행    │
│  - ShedLock: 다중 인스턴스 중복 실행 방지                │
│  - 연속 OFF 검증 + 3-Way 분기 처리                       │
└──────────────────────────────────────────────────────────┘
                        ↓
        ┌───────────────┴───────────────┐
        ↓                               ↓
┌─────────────────────┐      ┌──────────────────────┐
│  Notification DB    │      │  Mobile App Push     │
│  (웹 알림)          │      │  (Expo)              │
│  - 기존 인프라 활용 │      │  - 기존 인프라 활용  │
└─────────────────────┘      └──────────────────────┘

도메인 구조: Company → Factory → Machine (3-Tier 멀티테넌시)

핵심 서비스 로직 순서도

매 1분마다
  ↓
┌─────────────────────────────────────┐
│ 1. 활성화된 Alert Rule 조회         │
│    (회사별 알림 규칙)               │
└─────────────────────────────────────┘
  ↓
┌─────────────────────────────────────┐
│ 2. 각 Company별 처리                │
│    ┌─────────────────────────────┐ │
│    │ ① 설비 ID 목록 조회         │ │
│    │ ② 모니터링 데이터 배치 조회 │ │
│    │ ③ 알림 상태 배치 조회       │ │
│    │ ④ 메모리 그룹핑             │ │
│    └─────────────────────────────┘ │
└─────────────────────────────────────┘
  ↓
┌─────────────────────────────────────┐
│ 3. 각 설비별 처리                   │
│    ┌─────────────────────────────┐ │
│    │ 연속 OFF 검증               │ │
│    │   - 데이터 개수 체크        │ │
│    │   - 모두 OFF 상태?          │ │
│    │   - 시간 간격 3분 이내?     │ │
│    └─────────────────────────────┘ │
└─────────────────────────────────────┘
  ↓
조건 충족 시
  ↓
┌─────────────────────────────────────┐
│ 4. 3-Way 분기                       │
│    - 재전송 주기 도래? → 재발송    │
│    - 신규 알림? → 발송              │
│    - 재전송 대기? → 스킵            │
└─────────────────────────────────────┘
  ↓
┌─────────────────────────────────────┐
│ 5. 알림 발송                        │
│    - DB 저장 (웹)                   │
│    - Expo Push (모바일)             │
└─────────────────────────────────────┘
  ↓
┌─────────────────────────────────────┐
│ 6. Bulk 알림 해제                   │
│    (조건 해소된 설비)               │
└─────────────────────────────────────┘

핵심 개선: N+1 → 배치 쿼리

Before: N+1 지옥

for (AlertRule rule : activeRules) {
    for (Machine machine : getMachines(rule.getCompanyId())) {
        ...
    }
}

회사 × 설비 × 쿼리 = 수천 번의 DB 호출 → 스케줄러 실행 시간 오버

After: 배치 쿼리 + 메모리 그룹핑

private void checkRuleForCompany(AlertRuleDto rule) {
    // 1. Company에 속한 설비 ID 조회
    List<String> machineIds = machineRepository
        .findMachineIdsByCompanyId(rule.getIdCompany(), "Y");

    if (machineIds.isEmpty()) return;

    // 2. 모니터링 데이터 조회 및 그룹핑
    Map<String, List<MonitoringAlertDto>> dataByMachine =
        fetchMonitoringDataByMachine(machineIds, rule.getCount());

    // 3. 알림 상태 조회 (2회)
    List<String> machineIdsWithAlerts = alertMachineRepository
        .findMachineIdsWithUnresolvedAlerts(machineIds, rule.getRuleType());

    LocalDateTime resendThreshold = LocalDateTime.now()
        .minusMinutes(rule.getResendIntervalMinutes());
    Map<String, AlertMachineDto> resendAlertMap =
        fetchAlertsNeedingResend(machineIds, rule.getRuleType(), resendThreshold);

    // 4. 각 설비별 알림 조건 체크 및 처리
    List<String> machineIdsToResolve = processAlertsForMachines(
        machineIds, rule, dataByMachine, machineIdsWithAlerts, resendAlertMap);

    // 5. 알림 일괄 해제
    bulkResolveAlerts(machineIdsToResolve, rule.getRuleType());
}

핵심 메서드 분리 (단일 책임 원칙):

// 모니터링 데이터 조회 + 그룹핑
private Map<String, List<MonitoringAlertDto>> fetchMonitoringDataByMachine(
    List<String> machineIds, int count) {
        ...
}

// 재전송 필요한 알림 조회
private Map<String, AlertMachineDto> fetchAlertsNeedingResend(
    List<String> machineIds, String alertType, LocalDateTime threshold) {
        ...
}

// 각 설비 처리
private List<String> processAlertsForMachines(...) {
    List<String> machineIdsToResolve = new ArrayList<>();
        ...
}

연속 OFF 검증: "진짜 연속인가?"

3단계 필터링

public boolean checkConsecutiveOff(List<MonitoringAlertDto> data, int count) {
    // ① 개수 체크
    if (data.size() < count) return false;

    // ② 모두 OFF?
    boolean allOff = data.stream()
        .allMatch(d -> "N".equals(d.getOnoffMonitored()) ||
                       "0".equals(d.getOnoffMonitored()));
    if (!allOff) return false;

    // ③ 시간 간격 3분 이내? (연속성 검증)
    for (int i = 0; i < data.size() - 1; i++) {
        long minutes = Duration.between(
            data.get(i+1).getMonitoredAt(),
            data.get(i).getMonitoredAt()
        ).toMinutes();

        if (minutes > 3) return false;  // 간격 초과 = 연속 아님
    }
    return true;
}

시각화:

✅ 연속 OFF (알림 발송)          ❌ 간격 초과 (알림 미발송)
━━━━━━━━━━━━━━━━━━━━━          ━━━━━━━━━━━━━━━━━━━━━
10:03  N (OFF)                  10:10  N (OFF)
      ↕ 1분                            ↕ 5분 ✗
10:02  N (OFF)                  10:05  N (OFF)
      ↕ 1분                            ↕ 5분 ✗
10:01  N (OFF)                  10:00  N (OFF)

왜 3분? 1분, 2분은 애매해서 일단 3분으로 설정했고, 언제든 바꿀 수 있음.

재전송 로직 & 알림 발송

처리 흐름

연속 OFF 감지
  ↓
┌──────────────────────────────────────┐
│ 3-Way 분기                           │
│                                      │
│ resendAlert 존재?                    │
│   ├─ Yes → 재전송 (기존 해제+신규)    │
│   └─ No                              │
│        └─ hasExistingAlert?          │
│             ├─ No → 신규 알림         │
│             └─ Yes → 스킵 (재전송 대기)│
└──────────────────────────────────────┘
  ↓
┌──────────────────────────────────────┐
│ PushNotificationService              │
│ (기존 인프라 재사용)                 │
│                                      │
│ • Notification DB 저장 (웹)         │
│ • Expo Push 발송 (모바일)           │
└──────────────────────────────────────┘

타임라인:

Day 1 10:00  신규 알림 발송 🔔
Day 1~3      스킵 (재전송 대기)
Day 4 10:00  재알림 발송 🔔 (3일 경과)
Day 5 14:00  설비 ON → 자동 해제 ✅

최종 성과

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
항목                Before    After
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DB 쿼리              수천      수 회
실행 시간            45초      2초
1분 주기 유지        ❌        ✅
알림 지연            수 분     실시간
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

핵심 교훈

1. 복잡한 로직은 단일 책임으로 분리

생각보다 로직이 복잡해서 checkRuleForCompany() 하나에 다 넣으면 수백줄 메서드가 됨.

단일 책임 원칙으로 메서드 분리:

• fetchMonitoringDataByMachine(): 데이터 조회 + 그룹핑
• fetchAlertsNeedingResend(): 재전송 대상 조회
• processAlertsForMachines(): 각 설비 처리
• bulkResolveAlerts(): 일괄 해제

각 메서드가 하나의 책임만 → 테스트, 유지보수 쉬워짐.

2. 단순해 보이는 기능도 SaaS에서는 복잡도 증가

처음엔 "설비 몇번 꺼지면 알림 보내기"라는 단순한 기능으로 생각했지만, SaaS 환경에서는:

• 멀티테넌시 (회사별 데이터 격리)
• 실시간성 요구사항 (1분 주기)
• 재전송 로직 (3-Way 분기)
• False Positive 방지 (연속성 검증)

등으로 복잡도가 급증했습니다. 순서도와 아키텍처 다이어그램을 그려가며 설계하니 놓칠 수 있는 엣지 케이스를 사전에 발견할 수 있었고, 커뮤니케이션도 훨씬 수월했습니다.

마치며

단순한 알림 시스템도 실시간성, 정확성, 성능을 모두 충족하려면 복잡도가 급증합니다.

특히 제조업 IoT 환경에서는 1분의 지연도 큰 손실로 이어지고, False Positive는 신뢰도 하락, N+1은 시스템 마비를 야기합니다.

이 글이 비슷한 문제를 겪는 분들께 도움이 되길 바랍니다.

감사합니다.

이한수, InfoBank Partner

• 스타트업
  • 자유로움, 행복, 만족하는 삶
  • TIPS 정부 지원
  • 집중
  • Always 수익 개선
  • Like Sports (배려, 매너, 열정과 노력, 승복과 존중)

공성배, Megazone Vice P

• Ai Native
  • 실행속도
  • 비용 통제
• MIT 최근 통계
  • 95% Projects failed
• AI
  • C Level의 편향된 지식 경계
  • Culture Problem
  • 비지니스 요구사항을 확실히 아는 것이 중요
  • 고객 사례
    • RAG based Chatbot
    • BI
• Megazone, AI Ready
  • Governance
  • 변화 관리 (Culture)
  • 윤리경영 인증
  • 정형적인 방법이 아닌 고객사 Fit에 맞는 코칭 필요 (Like Golf Teaching)

지슨, 국정원

• 무선 보안
• 보안은 생존 (국정원)
• 최근 통신사 해킹
  • 최신 해킹기술 사용
• 무선 백도어 해킹
  • 실시간 모니터링 필요
  • 스파이칩 H/W (초소형 CPU, 무선통신 모듈)
    • 2 ~13Km 떨어진 곳에서 직접 교신 가능 by 해커
• Ai Poisoning
• 미래는 Physical AI
• 과거 사례
  • 2014년, USB 백도어 (Cotton Mouth, 2억 ~ 3억$ 개발비),
    • 미 NSA에서 우방국에 설치, 13Km 떨어진 거리에서 조종 가능 (1:1 교신)
    • USB에 스파이칩 포함
    • 케이블을 안테나로 사용
  • 2024년, 특전사 육군 대위 간첩사건
    • 경제적 어려움 (온라인 도박)
    • 북한이 포섭
    • 군 내부망(KJCCS)에 Poison Tab(USB) 연결 요청
• 미한일 대응 전략
  • 미국: 하드웨어 리스크 완전 제거 (자국산 장비만 사용)
  • 일본: 검증 장비 도입
  • 한국: 24시간 항시 모니터링. 이상주파수 탐지
• 무선 백도어
  • Wifi 이외 주파수 사용
  • 서버실, 데이터 센터, 생산라인 등 어디에서나 접근 가능
• 미국 911 사고 원인
  • 상상력의 부재 (충분히 가능한 위협)

서은국, 심리학

• 인간은 Rational Animal?
  • 인간은 자신의 내면적 경험에 압도된다.
  • 인간은 감정적인 것에 엄청난 영향을 받는다.
    • 예) 깨끗하게 키운 벌레를 못 먹는 이유 (역겨움)
  • 왜 감정은 동물에게만 있나?
    • 움직임에 대한 판단을 하기 위해 (생존하기 위해) - 진화 심리학
• 행복의 조건 중 제일 중요한 것
  • 풍성한 사회적 경험
• 인간의 호불호는 논리적이지 않다.
  • Love will find the reason.
  • 이유는 나중에 만들어진다.
• AI가 인간의 미묘한 감정을 이해할 수 있을까?
• AI와의 Interaction은 장기적으로 비용을 치룬다. 진짜 경험이 아니다.
  • 복잡한 문제를 만들 수 있다. 예측 불허
    • 예) GPT와 법적문제 (미국, 자살)
• 인간은 생명 유지를 위해 말도 안 될 정도록 감정적인 사회적 존재이다.'라는 말을 AI에게 해 주고 싶다.

Toss B

• 내부자 보안사고 문제 방지해야 (협력업체, 계약직 etc)
• Governance vs Management
• 개인정보 안정성 확보 (과징금: 매출의 4%)
• 가시성
  • 위험 정보자산 식별
    • 과기정통부, CISO 등록
      • 현재 약 3만개 회사
    • 사용하는 Cloud, SaaS Solution, 오픈소스도 식별해야
    • 자산관리 시스템 구축 (물리적, 가상)
• Forbes Best Banks (ISO, ISMS etc)
• 374(31), 408
  • 8.3%
  • White Hacker, 2
  • Chapter, 145
• Chapter(Horizonal), Silo(Vertical)
• 정보보호 공시
• 감사업무 매뉴얼 - 금감원 사이트 참조
• Chapter 협업
  • 계열사 Chapter Meeting 공식화 (대면)
  • CISO, Hacker (Monthly, Weekly), Leader exists

AI to AI Security, 이태훈, MGRV, CISO

• 2024
  • Mckinsey 60억$ (vs Open AI 58억$, 2005년 200억$)
    • Agents 12,000개
  • Philosophy
    • AI 흔적도 기록되어야...
    • Trust Geometry
  • 이제 사용자가 아니라 Agent가 호출한다.
    • 권한 상속이 너무 크다
    • 의도(Intent)가 남지 않는다
    • 공백 (책임, 가시성)
  • 대처법
    • Agent 사이에 얇은 Brocker 두기
      • 라우팅 및 버전 중재 etc
      • Data Firewall
    • 방어 Layer
      • 누가?
      • 적법?
      • 과다 노출 막기
        • 민감 토큰 탐지 (마스킹, 비식별, 샘플링)

전력 사용량 비교 서비스를 구현하며 배운 BFF 패턴, 비동기 병렬 처리, 그리고 사용자 경험 설계 이야기

들어가며

전력 사용량 비교 분석 기능을 개발하면서 흥미로운 고민에 직면했습니다. 클라이언트에게 4가지 서로 다른 데이터를 제공해야 하는데, 각각을 독립적인 API로 개발할지, 아니면 하나의 API로 통합해서 제공할지 결정해야 했습니다.

API 설계 방향

결론부터 말하자면, 단일 API 응답으로 설계했습니다:

외부 API는 '전력데이터 개방 포털 시스템' 특정 API 를 사용했고 편의상 C API(외부)라고 부르겠습니다.

GET /api/v1/ooo-power-usage/comparison?year=2025&month=9&factoryId=F001

// 주의: 2025년 11월 기준, C API는 9월까지의 데이터만 제공
// (현재 월 기준 2개월 이전 데이터만 조회 가능)

응답:
{
  "regionManufacturingAvg": {...},  // 지역 제조업 평균 (C API #1)
  "totalManufacturingAvg": {...},   // 전국 제조업 평균 (C API #2)
  "machine365CustomerAvg": {...},   // 우리 고객사 평균 (DB #1)
  "currentCustomer": {...}          // 현재고객 데이터 (DB #2)
}

참고: 2025년 11월 기준, C API는 현재 월로부터 2개월 이전 데이터까지만 조회 가능합니다. (11월이면 9월까지만 조회 가능)

BFF란 Backend For Frontend의 약자로, 말 그대로 프론트엔드를 위한 백엔드를 의미합니다. 즉, 프론트엔드를 요구사항에 맞게 구현하기 위해 도움을 주는 백엔드라고 간단하게 정의했습니다.

해결해야 할 과제

하지만 이 간단해 보이는 API 하나에 예상보다 많은 난관이 숨어있었습니다.

백엔드 문제:

• 2개의 C API 호출 (C API)
• 2개의 DB 조회 (내부 데이터베이스)
• C API는 응답 시간이 불안정 (50ms ~ 5초)
• 전체 응답 시간 3초 이내
• C API는 year-month 조회시 700KB 대용량 JSON 응답

프론트엔드 문제:

• C API는 2개월 이전 데이터만 제공 (11월이면 9월까지)
• 9월 데이터 없으면 자동으로 8월 재시도 필요
• Toast 표시 타이밍 제어 (무분별한 에러 메시지 방지)

이 글에서는 백엔드의 CompletableFuture 병렬 처리, 700KB JSON 최적화, Timeout + Fallback 전략과 프론트엔드의 자동 재시도 UI, Toast Message 제어를 통해 어떻게 풀스택으로 해결했는지 공유합니다.

초기 아키텍처 설계 고민

문제 1: C API는 2개월 이전 데이터만 조회 가능

C API를 분석하면서 중요한 제약사항을 발견했습니다:

"API 호출로 조회 가능한 데이터는 2개월 이전 데이터만 제공됨"

예: 현재가 2025년 11월이라면, 9월까지의 데이터만 조회 가능 (10월, 11월 데이터는 없음)

이는 최신 데이터 분석이 불가능하고, 실시간 비교가 어렵다는 의미였습니다.

전략 검토

전략 A: DB에 미리 적재 (배치 수집) ❌

장점: 과거 데이터 분석 및 활용 가능
단점:

• DB 용량 증가
• 배치 Job 장애 시 데이터 누락 위험
• 초기 히스토리 수집 작업 필요
• 운영 복잡도 증가

전략 B: 파일 시스템에 저장 ❌

/data/C/
  └── 2024/
      ├── 11.json (11월 데이터)
      └── 12.json (12월 데이터)

장점: DB 부하 없음, 백업 간단
단점:

• 검색/조회 성능 낮음
• 파일 관리 복잡도 증가
• 확장성 제한

전략 C: API + 캐싱만 사용 (최종 선택) ✅

필요한 데이터만 API 호출

- Spring Cache (메모리)
- Timeout + Fallback 전략

장점:

• 구현 단순 (배치 Job 불필요)
• 인프라 비용 절감
  단점:
• API 장애 시 서비스 영향

최종 결정: API + 캐싱 전략

결정 이유:

1. 요구사항: 현재 시점에서는 "특정 연월 데이터 비교"만 필요 (2개월 이전 데이터 활용)
2. 복잡도 최소화: 배치 Job, DB 테이블 추가 등 인프라 불필요
3. 캐싱으로 성능 보완: Spring Cache로 API 호출 횟수 98% 감소

요구사항 분석

비즈니스 요구사항

사용자가 자신의 공장 전력 사용량을 다른 데이터와 비교하고 싶어함:

1. 현재 공장 지역 제조업 평균과 비교 (예: 경기도 제조업 평균)
2. 전국 제조업 평균과 비교
3. M365 전체 고객사 평균과 비교
4. 현재 공장 실제 데이터

시스템 아키텍처

전체 구조 (SOLID 원칙 적용)

┌─────────────────────────────────────────────────────────────┐
│                  Client (Nextjs)                            │
│  GET /api/v1/ooo-power-usage/comparison                     │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│  PowerUsageComparisonController (SpringBoot)                │
│       @GetMapping("/comparison")                            │
└────────────────────────┬────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│         PowerUsageComparisonService (오케스트레이터)         │
│  ✅ 단일 책임: 여러 데이터 소스 조합 (비즈니스 로직)          │
└────────────┬────────────────────────────┬───────────────────┘
             │                            │
             │ 의존성 주입                 │ 의존성 주입
             │                            │
┌────────────▼──────────┐     ┌──────────▼───────────────────┐
│ CApiDataService       │     │ CBillRepository          │
│ (C API 전담)          │     │ (DB 조회 전담)               │
│ ✅ SRP 준수           │     │ ✅ SRP 준수                  │
│                       │     │                              │
│ - getRegionAvg()      │     │ - getMachine365Avg()         │
│ - getTotalAvg()       │     │ - getCurrentCustomer()       │
│ - JSON 파싱 (totData) │     │                              │
│ - 캐싱                │     │                              │
└────────────┬──────────┘     └──────────────────────────────┘
             │
┌────────────▼──────────┐
│ CApiClient            │
│ (HTTP 통신 전담)       │
│ ✅ SRP 준수           │
│                       │
│ - RestTemplate        │
│ - Timeout 설정        │
│ - 에러 핸들링          │
└────────────┬──────────┘
             │
             │ 700KB JSON
             ▼
┌─────────────────────────────────────┐
│ C API Server (External)             │
│ ⚠️ 2개월 이전 데이터만 제공          │
│ ⚠️ 11월 기준 → 9월까지만 조회 가능   │
│ ⚠️ 응답 시간 불안정 (50ms~5초)       │
└─────────────────────────────────────┘

데이터 플로우: 병렬 처리 vs 순차 처리

시간축 →

방법 1: 순차 처리 (❌ Bad)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│ API #1 (Region)  │ 800ms │
                    │ API #2 (Total)   │ 900ms │
                                        │ DB #1 │ 100ms │
                                                │ DB #2 │ 50ms │
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total: 800 + 900 + 100 + 50 = 1,850ms


방법 2: 병렬 처리 (✅ Good)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
│ API #1 (Region)  │ 800ms │
│ API #2 (Total)   │ 900ms │ ← 병렬 실행
                            │ DB #1 │ 100ms │
                                    │ DB #2 │ 50ms │
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total: max(800, 900) + 100 + 50 = 1,050ms
개선율: 43% 단축 🚀

핵심 구현 과정

1. 700KB 대용량 JSON 응답 최적화

문제 상황

C API에 연/월을 던져서 전국 제조업 전력 사용량을 조회하면, 단일 API 호출로 700KB가 넘는 JSON이 반환됩니다.

문제:

• totData만 필요한데, data 필드(650KB) 전체를 객체로 만들면 메모리 낭비
• 동시 100명 접속 시: 700KB × 100 = 70MB

해결 방법: JsonParser 스트리밍 파싱

Jackson의 JsonParser를 활용하여 totData만 선택적으로 파싱합니다.

결과: 메모리 사용량 93% 감소

예) 동시 100명 접속 시:

• Before: 700KB × 100 = 70MB
• After: 50KB × 100 = 5MB (14배 개선)

2. CompletableFuture를 활용한 병렬 처리

문제 상황

해결 방법: CompletableFuture 병렬 실행

핵심 포인트:

• CompletableFuture.supplyAsync(): 별도 스레드에서 비동기 실행
• CompletableFuture.allOf().join(): 모든 작업 완료 대기
• .join(): 완료된 결과 가져오기 (블로킹)

3. Timeout + Fallback 캐시 전략

문제 상황

C API는 응답 시간이 불안정합니다:

• 평균: 80ms
• 최대: 5초 이상
• 일시적 장애 발생 가능

사용자는 3초 이상 기다리면 이탈합니다.

해결 방법: 3단계 Fallback 전략

┌────────────────────────────────────────────────┐
│  Level 1: API 호출 (3초 타임아웃)               │
│  정상 응답 시 → 즉시 반환                       │
└────────┬───────────────────────────────────────┘
         │ (Timeout or Error)
         ▼
┌────────────────────────────────────────────────┐
│  Level 2: Cache Fallback                       │
│  이전에 성공한 응답이 캐시에 있으면 반환          │
└────────┬───────────────────────────────────────┘
         │ (Cache Miss)
         ▼
┌────────────────────────────────────────────────┐
│  Level 3: Empty Data                           │
│  빈 데이터 반환 (나머지 데이터는 정상 제공)      │
└────────────────────────────────────────────────┘

구현: 지역별 데이터 조회

캐시 조회 헬퍼 메서드

프론트엔드: 사용자 경험을 위한 자동 Fallback UI

백엔드에서 BFF 패턴으로 4개 데이터 소스를 통합했지만, 프론트엔드에서도 해결해야 할 문제가 있습니다.

핵심 문제: C API는 2개월 이전 데이터만 제공합니다. 11월에 접속한 사용자가 9월 데이터를 기대하지만, 9월 데이터가 없을 수 있습니다.
그럼 조용히 8월 데이터라도 보여줘야 합니다.

1. 자동 재시도 로직: 9월 → 8월

조용한 Fallback

2. Toast 표시 타이밍 제어

복잡한 케이스 분기:

결과:

• ✅ 9월 없음 → 조용히 8월 재시도 (Toast 없음)
• ✅ 8월도 없음 → Toast 표시
• ✅ 사용자는 한 번만 Toast 봄 (친절!)

3. 동적 월 선택 제약 (UX개선)

문제: C API는 2개월 이전 데이터만 제공합니다.

11월 접속 시:

• 2025년 선택 → 1~9월만 선택 가능 ✅
• 2024년 선택 → 1~12월 전체 선택 가능 ✅
• 10월, 11월 선택 비활성화 ✅

결과:

• ✅ 사용자가 불가능한 월 선택 못함 (UX 개선)
• ✅ "데이터 없음" 에러 메시지 사전 차단

마치며

개발을 시작할 때, 간단해 보이는 요구사항이 있었습니다:
"4가지 전력 사용량 데이터를 비교해서 보여주세요."

하지만 뚜껑을 열어보니:

백엔드 (BFF 패턴):

1. 아키텍처: YAGNI 원칙(필요한 작업만해라)으로 DB 저장 대신 API + 캐싱 선택
2. 성능: CompletableFuture 병렬 처리로 50% 응답 시간 단축
3. 메모리: JsonParser 스트리밍으로 93% 메모리 절약
4. 안정성: Timeout + Fallback 캐시로 99% 가용성 달성
5. 비용: 캐싱으로 C API 호출 90% 감소

프론트엔드 (UX 설계):

6. 자동 재시도: 9월→8월 조용한 Fallback으로 에러 메시지 90% 감소
7. Toast 제어: 케이스별 분기로 사용자 혼란 방지
8. 동적 제약: 불가능한 월 선택 차단

이 모든 제약을 풀어가는 과정에서, 단순히 API를 만든 게 아니라 완전한 경험을 설계했습니다.

이 글이 기술 스택의 경계를 넘어 더 나은 경험을 만드는 데 영감이 되기를 바라며 마무리하겠습니다.

Claude Code는 Anthropic의 공식 CLI 도구로, MCP(Model Context Protocol)를 통해 다양한 외부 도구와 연동할 수 있습니다. 이 가이드에서는 Claude Code와 Obsidian을 연동하여 AI 에이전트가 여러분의 노트를 읽고 편집할 수 있도록 설정하는 방법을 소개합니다.

MCP(Model Context Protocol)란?

MCP는 AI 모델이 외부 데이터 소스 및 도구와 상호작용할 수 있게 해주는 표준 프로토콜입니다. Claude Code는 MCP를 통해 다음과 같은 작업이 가능합니다:

• 파일 시스템 접근
• 데이터베이스 연동
• API 호출
• Obsidian vault 관리

Obsidian이란?

Obsidian은 마크다운 기반의 강력한 지식 관리 도구입니다. 다음과 같은 특징이 있습니다:

핵심 특징

1. 로컬 우선(Local-first): 모든 노트가 여러분의 컴퓨터에 일반 마크다운 파일로 저장됩니다. 데이터 소유권이 완전히 여러분에게 있습니다.

2. 양방향 링크(Bidirectional Links): [[노트 제목]] 형식으로 노트 간 연결을 만들 수 있으며, 역링크도 자동으로 추적됩니다.

3. 그래프 뷰(Graph View): 노트 간의 연결 관계를 시각적으로 확인할 수 있어, 아이디어 간 관계를 한눈에 파악할 수 있습니다.

4. 플러그인 생태계: 강력한 커뮤니티 플러그인 시스템으로 기능을 확장할 수 있습니다.

5. 개인 지식 베이스: 프로젝트 문서, 학습 노트, 업무 일지, 아이디어 메모 등을 체계적으로 관리할 수 있습니다.

실제 활용 사례

Obsidian은 다음과 같은 용도로 널리 사용됩니다:

• 프로젝트 관리: 작업 일지, 마일스톤, 이슈 트래킹
• 기술 문서화: API 문서, 시스템 아키텍처, 코드 분석
• 학습 노트: 강의 내용, 책 요약, 연구 자료
• 개인 위키: 레시피, 여행 계획, 독서 목록
• Zettelkasten: 영구 노트 작성을 통한 지식 축적

Obsidian과 Claude Code 연동의 장점

1. 컨텍스트 인식 기반 AI 응답

Claude Code가 여러분의 Obsidian vault에 접근할 수 있으면, 축적된 지식을 바탕으로 더 정확하고 맥락에 맞는 답변을 제공합니다.

작동 원리:

사용자: "지난주 작업 내용을 바탕으로 이번 주 계획을 세워줘"

Claude Code → MCP → Obsidian vault
         ↓
"Project 관리/2025-10-19 작업 일지.md" 읽기
"레거시 분석/생산관리 레거시 화면 분석.md" 참조
         ↓
프로젝트 맥락을 이해한 상태에서 답변 생성

2. 프로젝트 지식 베이스 활용

여러분이 Obsidian에 정리해둔 모든 문서가 Claude의 작업 컨텍스트가 됩니다.

실제 예시 (현재 연결된 vault 기준):

사용자: "생산 모듈 마이그레이션할 때 주의할 점이 뭐야?"

Claude가 자동으로 참조:
- "생산 모듈 마이그레이션 가이드.md"
- "Project 관리/DevExpress 마이그레이션 프로젝트.md"
- "레거시 분석/화면/생산관리 레거시 화면 분석.md"
- "Migration/마이그레이션 이슈 트래킹.md"

→ 프로젝트별 특수 상황을 반영한 맞춤 답변 제공

3. 일관된 문서 관리

Claude가 여러분의 문서 구조와 작성 스타일을 학습하여 일관된 형식으로 문서를 생성하고 수정합니다.

예시:

사용자: "오늘 작업 일지를 작성해줘"

Claude가:
1. 기존 작업 일지 템플릿 분석
   ("Project 관리/2025-10-19 작업 일지.md" 참조)
2. 동일한 구조와 형식으로 새 파일 생성
3. 프로젝트별 진행 상황 자동 반영

4. 지식 그래프 구축 및 연결

Claude가 노트 간의 관계를 이해하고 자동으로 관련 문서를 연결합니다.

작동 방식:

사용자: "MES 데이터베이스 스키마에 대한 인덱스 페이지 만들어줘"

Claude가:
1. vault 전체 검색으로 관련 파일 발견
   - "MES 데이터베이스 스키마.md"
   - "MES 데이터베이스 DDL.sql"
   - "Backend/백엔드 API 테이블 및 Controller 매핑.md"
2. 자동으로 양방향 링크 생성
3. 카테고리별로 정리된 인덱스 페이지 생성

5. 반복 작업 자동화

정형화된 작업을 Claude에게 맡겨 시간을 절약할 수 있습니다.

활용 예시:

• 일일 스탠드업 리포트 생성: 작업 일지를 분석해 요약 생성
• 주간/월간 리뷰: 기간별 작업 내용 취합 및 분석
• 문서 업데이트 추적: 변경된 API나 스키마 관련 문서 자동 업데이트
• 태그 정리: 일관된 태그 체계로 자동 정리

6. 프로젝트 전체 맥락 파악

대규모 프로젝트에서 특히 유용합니다.

시나리오:

사용자: "생산 모듈에서 사용하는 모든 API 엔드포인트를 정리해줘"

Claude가:
1. "Backend/생산 모듈 백엔드 API 분석.md" 읽기
2. "Project 관리/API 변경 사항.md" 참조
3. "레거시 분석" 폴더 전체 스캔
4. 모든 정보를 종합하여 완전한 API 목록 생성

→ 여러 문서에 흩어진 정보를 한 번에 통합

7. RAG(Retrieval-Augmented Generation) 구현

Obsidian vault는 사실상 개인화된 RAG 시스템이 됩니다.

원리:

일반 Claude:
질문 → AI 모델 → 일반적인 답변

Claude + Obsidian MCP:
질문 → vault에서 관련 문서 검색 → AI 모델 + 실제 문서 내용 → 정확한 맞춤 답변

장점:

• 프로젝트 특정 용어와 컨텍스트 반영
• 실제 데이터 기반 답변 (환각 감소)
• 회사/팀 고유의 워크플로우 이해

필요 조건

• Claude Code 설치
• Obsidian 설치

Obsidian MCP 플러그인 설치

이 방식은 Obsidian 플러그인을 통해 MCP 서버를 구동하는 방식입니다. 별도의 Node.js 환경이나 npm 설치가 필요 없습니다.

1. 플러그인 다운로드

GitHub releases 페이지에서 최신 버전의 플러그인 파일을 다운로드합니다.

필요한 파일 3개:

• main.js
• manifest.json
• styles.css

다운로드 명령어 (Windows PowerShell 또는 Git Bash):

# 플러그인 디렉토리 생성
mkdir -p "C:\path\to\your\vault\.obsidian\plugins\obsidian-claude-code-mcp"
cd "C:\path\to\your\vault\.obsidian\plugins\obsidian-claude-code-mcp"

# 파일 다운로드
curl -L -O https://github.com/iansinnott/obsidian-claude-code-mcp/releases/download/1.1.8/main.js
curl -L -O https://github.com/iansinnott/obsidian-claude-code-mcp/releases/download/1.1.8/manifest.json
curl -L -O https://github.com/iansinnott/obsidian-claude-code-mcp/releases/download/1.1.8/styles.css

macOS/Linux:

# 플러그인 디렉토리 생성
mkdir -p ~/Documents/ObsidianVault/.obsidian/plugins/obsidian-claude-code-mcp
cd ~/Documents/ObsidianVault/.obsidian/plugins/obsidian-claude-code-mcp

# 파일 다운로드
curl -L -O https://github.com/iansinnott/obsidian-claude-code-mcp/releases/download/1.1.8/main.js
curl -L -O https://github.com/iansinnott/obsidian-claude-code-mcp/releases/download/1.1.8/manifest.json
curl -L -O https://github.com/iansinnott/obsidian-claude-code-mcp/releases/download/1.1.8/styles.css

중요: C:\path\to\your\vault 또는 ~/Documents/ObsidianVault를 실제 Obsidian vault 경로로 변경하세요.

2. Obsidian에서 플러그인 활성화

1. Obsidian을 실행합니다
2. 설정(Settings) → 커뮤니티 플러그인(Community plugins)으로 이동
3. "Claude Code MCP" 플러그인을 찾아 활성화합니다
4. 플러그인 설정에서 MCP 서버 설정을 확인합니다

3. Claude Code CLI로 MCP 연결

Obsidian 플러그인이 활성화되면 로컬 MCP 서버가 포트 22360에서 실행됩니다. Claude CLI 명령어로 간단하게 연결할 수 있습니다:

claude mcp add --transport sse obsidian http://localhost:22360/sse

명령어 설명:

• claude mcp add: MCP 서버를 추가하는 명령어
• --transport sse: SSE(Server-Sent Events) 전송 방식 사용
• obsidian: MCP 서버의 이름 (원하는 이름으로 변경 가능)
• http://localhost:22360/sse: Obsidian 플러그인이 실행하는 MCP 서버 주소

중요:

• Obsidian이 실행되고 플러그인이 활성화된 상태에서 이 명령어를 실행하세요
• 연결이 성공하면 Claude Code에서 Obsidian vault에 접근할 수 있습니다

3.1 Vault의 Path확인 하는 방법

3.2 연동이 잘 되었는지 확인 하기

사용 가능한 기능

Obsidian MCP 연동을 통해 Claude Code에서 다음 작업이 가능합니다:

1. Vault 파일 목록 조회

vault의 모든 파일을 보여줘

Claude가 mcp__obsidian__get_workspace_files 도구를 사용하여 vault의 모든 파일을 나열합니다.

2. 파일 내용 읽기

"프로젝트 관리/작업 일지.md" 파일을 읽어줘

Claude가 mcp__obsidian__view 도구를 사용하여 특정 파일의 내용을 읽습니다.

3. 파일 내용 수정

"작업 일지.md"의 TODO 섹션에 새로운 태스크를 추가해줘

Claude가 mcp__obsidian__str_replace 또는 mcp__obsidian__insert 도구를 사용하여 파일을 편집합니다.

4. 새 파일 생성

"Blog" 폴더에 새로운 블로그 글을 작성해줘

Claude가 mcp__obsidian__create 도구를 사용하여 새 파일을 생성합니다.

5. 현재 활성 파일 가져오기

지금 열려있는 파일을 분석해줘

Claude가 mcp__obsidian__get_current_file 도구를 사용하여 Obsidian에서 현재 열려있는 파일을 가져옵니다.

실제 사용 예시

예시 1: 일일 작업 일지 자동화

오늘 날짜로 새로운 작업 일지를 만들어줘. 템플릿은 기존 작업 일지를 참고해.

Claude가:

1. 기존 작업 일지 파일을 읽어 템플릿 확인
2. 오늘 날짜로 새 파일 생성
3. 템플릿 적용

예시 2: 노트 정리 및 링크 추가

"프로젝트 A" 관련 파일들을 찾아서 인덱스 페이지를 만들어줘

Claude가:

1. 프로젝트 A 관련 파일 검색
2. 인덱스 파일 생성
3. 각 파일로의 링크 추가

예시 3: 콘텐츠 분석 및 요약

이번 주 작업 일지들을 분석해서 주간 리포트를 작성해줘

Claude가:

1. 이번 주 작업 일지 파일들 조회
2. 각 파일 내용 읽기
3. 요약 및 주간 리포트 생성

고급 활용 팁

1. Obsidian API 직접 사용

mcp__obsidian__obsidian_api 도구를 통해 Obsidian의 TypeScript API를 직접 호출할 수 있습니다:

Obsidian API를 사용해서 모든 태그를 찾아줘

2. 파일 패턴 필터링

파일 목록 조회 시 패턴을 지정할 수 있습니다:

"*.md" 패턴으로 마크다운 파일만 보여줘

3. 특정 라인 범위 읽기

큰 파일의 경우 특정 라인만 읽을 수 있습니다:

"데이터베이스 스키마.md"의 100번째 줄부터 200번째 줄까지 읽어줘

보안 고려사항

• MCP 서버는 vault에 대한 전체 읽기/쓰기 권한을 가집니다
• 민감한 정보가 포함된 vault는 주의해서 사용하세요
• 설정 파일에 경로가 올바른지 확인하세요

문제 해결

MCP 서버가 연결되지 않을 때

1. Obsidian 플러그인 확인:

   • Obsidian 설정 → 커뮤니티 플러그인에서 "Claude Code MCP"가 활성화되어 있는지 확인
   • 플러그인이 목록에 없다면 파일이 올바른 위치에 있는지 확인:
     • .obsidian/plugins/obsidian-claude-code-mcp/ 폴더 확인
     • main.js, manifest.json, styles.css 3개 파일이 모두 있는지 확인

2. Obsidian 재시작:

   • Obsidian을 완전히 종료하고 다시 시작
   • 플러그인 로드 중 오류 메시지가 있는지 확인

3. Claude Code 재시작:

   • mcp_config.json 설정 후 Claude Code를 재시작해야 적용됩니다

4. 플러그인 설정 확인:

   • Obsidian에서 플러그인 설정을 열어 MCP 서버 상태 확인
   • 설정에서 실제 config 디렉토리 경로를 확인할 수 있습니다

파일을 찾을 수 없을 때

• 파일 경로는 vault root를 기준으로 상대 경로로 지정
• 예: "Blog/article.md" (앞에 / 없음)
• Obsidian이 실행 중이어야 MCP 서버가 작동합니다

플러그인이 목록에 나타나지 않을 때

• 커뮤니티 플러그인이 활성화되어 있는지 확인:
  • 설정 → 커뮤니티 플러그인 → "제한 모드 해제(Turn off restricted mode)"
• 플러그인 폴더 이름이 정확한지 확인: obsidian-claude-code-mcp
• Obsidian 개발자 콘솔(Ctrl+Shift+I)에서 에러 메시지 확인

권한 오류

• Obsidian이 vault 폴더에 대한 읽기/쓰기 권한이 있는지 확인
• 중요: Obsidian이 실행 중이어야 MCP 서버가 작동합니다

결론

Claude Code와 Obsidian의 MCP 연동은 노트 관리를 자동화하고 AI의 도움을 받아 더 효율적으로 지식을 관리할 수 있게 해줍니다. 일일 작업 일지 작성, 노트 정리, 콘텐츠 분석 등 다양한 작업을 자동화할 수 있습니다.

이 강력한 도구를 활용하여 여러분의 지식 관리 워크플로우를 한 단계 업그레이드해보세요!

참고 자료

• Claude Code 공식 문서
• MCP 프로토콜 문서
• Obsidian API 문서
• Obsidian Claude Code MCP 플러그인
• 플러그인 최신 릴리즈