Agent on Yarang's Tech Lair

Show HN: Semble – 에이전트를 위한 토큰 효율적인 코드 검색 엔진 구현

Mon, 18 May 2026 09:00:38 +0900

최근 LLM(Large Language Model)을 활용한 에이전트 시스템을 개발하면서 가장 큰 병목 현상 중 하나는 바로 ‘코드 검색’이었습니다. 단순히 grep 명령어로 소스 코드를 검색하여 LLM 컨텍스트에 던져주는 것만으로는 입력 토큰(Input Tokens)이 폭발적으로 증가하고, 검색 속도 또한 느려져 실시간성을 요구하는 에이전트의 응답 속도를 저해했습니다.

Hacker News에서 논의된 ‘Show HN: Semble’ 프로젝트는 이러한 문제를 해결하는 아주 흥미로운 접근 방식을 제시합니다. 일반적인 grep 도구 대비 98%나 적은 토큰을 사용하여 코드를 검색한다는 것인데요. 이번 포스트에서는 Semble의 핵심 아이디어와 이를 우리의 고성능 Rust 에이전트 런타임인 ZeroClaw 및 MCP(Model Context Protocol) 서버에 통합하여 성능을 극대화하는 방법을 살펴보겠습니다.

기존 검색 방식의 문제점: grep과 LLM의 궁합

기존의 blog-api-server나 여러 MCP 도구에서 코드를 검색할 때 주로 정규표현식 기반의 grep 라이브러리를 사용했습니다. 하지만 이 방식은 LLM 에이전트와 함께 사용할 때 치명적인 단점이 있습니다.

토큰 낭비: grep은 검색어가 포함된 전체 라인을 반환합니다. 긴 라인이나 불필요한 주석이 포함된 경우, LLM은 실제 코드보다 잡음(Noise)을 더 많이 처리해야 합니다.
의미 이해 부족: 단순 문자열 매칭이므로 ‘카멜 케이스’, ‘스네이크 케이스’ 등의 뉘앙스를 이해하지 못합니다. 예를 들어 getUser를 검색했을 때 get_user는 놓칠 수 있습니다.
비용 증가: LLM API 호출 비용은 입력 토큰 수에 비례합니다. 불필요한 코드가 컨텍스트에 포함되면 비용이 그만큼 증가합니다.

Semble의 접근 방식: 구조와 의미의 분리

Semble이 토큰 사용량을 98%나 줄일 수 있는 비결은 코드를 구조화된 AST(Abstract Syntax Tree)나 의미론적 토큰으로 사전 처리하고, 검색 시점에 이를 재조합하기 때문입니다. 핵심은 **‘코드를 문자열이 아닌 데이터로 다룬다’**는 것입니다.

우리는 이 개념을 확장하여 ZeroClaw 아키텍처 내에 CodeIndexer 모듈을 설계했습니다.

ZeroClaw 통합: 고성능 인덱서 구현

ZeroClaw는 Rust 기반이므로 메모리 안전성과 속도를 보장합니다. 여기에 Semble 영감을 받은 인덱서를 구현해 보겠습니다.

1. 데이터 구조 정의

먼저 코드를 저장할 구조를 정의합니다. 파일의 내용 전체를 저장하는 대신, 심볼(Symbol)과 메타데이터만 저장합니다.

use std::collections::HashMap;
use serde::{Serialize, Deserialize};

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct CodeSymbol {
 pub id: String,
 pub name: String,
 pub kind: SymbolKind, // Function, Struct, Variable 등
 pub file_path: String,
 pub start_line: usize,
 pub end_line: usize,
 pub signature: String, // 함수 시그니처나 타입 정의
}

#[derive(Debug, Serialize, Deserialize, Clone)]
pub enum SymbolKind {
 Function,
 Struct,
 Enum,
 Variable,
 Module,
}

// 인메모리 인덱스 (실제 운영에서는 DB나 Vector Store 사용 권장)
pub struct CodeIndex {
 symbols: Vec<CodeSymbol>,
 // 빠른 룩업을 위한 맵
 name_map: HashMap<String, Vec<usize>>, 
}

2. 인덱싱 로직 (Parsing)

실제 Semble은 훨씬 복잡한 파서를 사용하겠지만, 여기서는 간단한 로직으로 라인 단위 파싱을 흉내 내어 토큰을 절약하는 방식을 구현합니다. 주석이나 공백을 제거하고 핵심 정의만 캡처합니다.

impl CodeIndex {
 pub fn new() -> Self {
 Self {
 symbols: Vec::new(),
 name_map: HashMap::new(),
 }
 }

 // 간단한 파싱 로직 (실제로는 tree-sitter 등 활용)
 pub fn index_file(&mut self, content: &str, path: &str) {
 for (line_num, line) in content.lines().enumerate() {
 // 함수 정의 패턴 예시: "fn name(...)"
 if line.trim().starts_with("fn ") {
 let signature = line.split('{').next().unwrap_or(line).trim();
 let name = signature
 .strip_prefix("fn ")
 .unwrap()
 .split('(')
 .next()
 .unwrap()
 .trim();

 let symbol = CodeSymbol {
 id: format!("{}:{}", path, line_num),
 name: name.to_string(),
 kind: SymbolKind::Function,
 file_path: path.to_string(),
 start_line: line_num,
 end_line: line_num + 10, // 대략적인 범위 추정
 signature: signature.to_string(),
 };

 self.add_symbol(symbol);
 }
 // Struct, impl 등에 대한 패턴 매칭 추가 가능...
 }
 }

 fn add_symbol(&mut self, symbol: CodeSymbol) {
 let idx = self.symbols.len();
 self.symbols.push(symbol);
 self.name_map
 .entry(symbol.name.clone())
 .or_insert_with(Vec::new)
 .push(idx);
 }
}

3. MCP 도구를 위한 검색 인터페이스

이제 MCP 클라이언트가 호출할 수 있는 검색 함수를 만듭니다. 이 함수는 전체 코드가 아닌 signature와 핵심 ID만 반환하도록 하여 토큰을 아낍니다.

impl CodeIndex {
 pub fn search(&self, query: &str) -> Vec<CodeSymbol> {
 self.symbols
 .iter()
 .filter(|s| s.name.to_lowercase().contains(&query.to_lowercase()))
 .cloned()
 .collect()
 }

 // LLM 컨텍스트를 위해 최적화된 포맷으로 변환
 pub fn to_llm_context(&self, results: Vec<CodeSymbol>) -> String {
 results
 .iter()
 .map(|s| format!(
 "File: {}, Line: {}\nSymbol: {}\nDefinition: {}\n",
 s.file_path, s.start_line, s.name, s.signature
 ))
 .collect::<Vec<_>>()
 .join("\n---\n")
 }
}

성능 비교 및 토큰 절약 효과

예를 들어, blog-api-server에서 get_post라는 함수를 찾는다고 가정해 봅시다.

기존 grep 방식: main.rs의 100줄 중 해당 함수가 포함된 20줄을 모두 반환. (주석, 로직 등 포함)
ZeroClaw 인덱서 방식: File: src/main.rs, Line: 45, Symbol: get_post, Definition: async fn get_post(id: i32) -> Result<Post>만 반환.

결과적으로, LLM은 필요한 메타데이터만 전달받으므로 **“이 함수의 내부 구현을 보여줘”**라고 재요청하거나, 메타데이터만으로도 충분한 추론을 수행할 수 있습니다. 불필요한 코드를 읽지 않기 때문에 토큰 사용량이 획기적으로 줄어듭니다.

결론: 에이전트 생태계를 위한 최적화

Semble에서 영감을 받은 이 접근 방식은 단순히 검색 속도를 높이는 것을 넘어, LLM 에이전트와 코드베이스 간의 통신 비용과 효율성을 최적화합니다. 특히 blog-api-server의 로깅 개선이나 모니터링 시스템처럼 대규모 코드베이스를 다루는 환경에서는 필수적입니다.

다음 단계로, 단순 텍스트 매칭을 넘어 **Vector Embedding(벡터 임베딩)**을 결합하여 의미론적 검색(Semantic Search)이 가능하도록 ZeroClaw의 통신 프로토콜을 확장할 예정입니다. 이를 통해 에이전트가 “사용자 인증 관련 로직"을 검색했을 때, auth라는 키워드가 없어도 login, verify, session 등의 함수를 유연하게 찾아낼 수 있게 될 것입니다.

고성능 에이전트 런타임을 구축하신다면, 단순히 파일을 읽는 것에서 벗어나 코드를 ‘이해’하는 인덱서 구축을 고려해 보세요. 토큰 비용 절감과 응답 속도 개선이라는 두 마리 토끼를 잡을 수 있습니다.

참고 자료

Show HN: Semble – Code search for agents that uses 98% fewer tokens than grep
ZeroClaw Architecture Documentation
Rust Tree-sitter Binding Guide

개발 생산성 17배 극대화: DeepSeek V4와 Claude Code로 구축하는 저비용 AI 에이전트 루프

Mon, 04 May 2026 09:01:31 +0900

개발 생산성 17배 극대화: DeepSeek V4와 Claude Code로 구축하는 저비용 AI 에이전트 루프

최근 Hacker News에 DeepClaude라는 흥미로운 프로젝트가 소개되었습니다. Claude Code의 에이전트 루프(Agent Loop) 기능에 DeepSeek V4 Pro를 결합하여 기존 대비 17배 낮은 비용으로 동일한 성능을 내는 하이브리드 아키텍처입니다.

이 글에서는 단순히 흥미로운 소식을 전달하는 것에 그치지 않고, 실제 개발 환경에서 Claude Code와 DeepSeek V4를 연동하여 비용 효율적인 AI 코딩 어시스턴트를 구축하는 방법을 구체적으로 다루겠습니다. 특히, MCP(Model Context Protocol)를 활용해 깃허브(GitHub)와 파일 시스템을 제어하는 방법까지 포함하여 완성도 있는 가이드를 제공합니다.

1. 왜 DeepSeek V4와 Claude Code인가?

Claude Code는 강력한 ‘에이전트 루프’ 기능을 제공합니다. AI가 스스로 코드를 작성하고, 실행하고, 오류를 수정하며 목표를 달성할 때까지 반복하는 자동화 프로세스입니다. 하지만 고품질의 Sonnet 모델을 지속적으로 사용하기에는 비용 부담이 큽니다.

여기서 DeepSeek V4 Pro가 등장합니다. DeepSeek V4는 최근 오픈소스 진영에서 가장 주목받는 모델 중 하나로, 복잡한 추론(Reasoning) 능력은 물론 코드 생성에서도 뛰어난 성능을 보여줍니다. 무엇보다 가성비가 압도적입니다.

DeepClaude 접근법의 핵심 전략:

플래너(Planner): 작업을 분석하고 계획 수립에는 기존 Claude 모델 사용 (일회성 사용)
워커(Worker): 실제 코드 작성 및 수정 반복문(Run Loop)에는 DeepSeek V4 사용 (다량 사용)

이 구조를 통해 전체 비용을 17/1로 줄이면서도 작업 완료도는 유지할 수 있습니다.

2. 사전 준비: MCP 서버 환경 구성

이 아키텍처를 구현하기 위해서는 AI가 로컬 환경의 파일을 읽고 쓸 수 있어야 합니다. 이를 위해 이전 포스트에서 다룬 MCP 서버 개념을 응용하여 설정하겠습니다.

2.1. MCP 설정 파일 구성 (`mcp_config.json`)

AI 에이전트가 프로젝트 폴더에 접근할 수 있도록 설정합니다. 로컬에 mcp_config.json 파일을 생성하고 아래 내용을 작성하세요.

{
 "mcpServers": {
 "filesystem": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Projects/DeepAgent"],
 "env": {
 "ALLOWED_DIRECTORIES": "/Users/yourname/Projects/DeepAgent"
 }
 },
 "github": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-github"]
 }
 }
}

filesystem: 에이전트가 코드를 생성하고 수정할 경로를 지정합니다.
github: (선택 사항) 깃허브 이슈나 PR을 생성하려면 토큰 환경 변수가 필요할 수 있습니다.

3. DeepSeek V4와 Claude Code 연동 구현

이제 실제 코드를 작성하여 두 모델을 오가며 작업을 수행하는 파이썬 스크립트를 구현해 보겠습니다. 이 스크립트는 ‘하이브리드 에이전트’의 핵심 로직입니다.

3.1. 의존성 설치

pip install openai anthropic

3.2. 하이브리드 에이전트 코드 구현 (`hybrid_agent.py`)

이 코드는 Anthropic API와 **OpenAI 호환 API(DeepSeek)**를 혼용하여 사용합니다.

import os
import json
from openai import OpenAI
from anthropic import Anthropic

# 설정: API 키는 환경 변수로 관리하세요
DEEPSEEK_API_KEY = os.getenv("DEEPSEEK_API_KEY")
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")

def create_hybrid_agent(task_description: str, max_iterations: int = 5):
 """
 DeepSeek V4(Worker)와 Claude(Planner)를 결합한 하이브리드 에이전트 함수
 """
 
 # 1. 모델 클라이언트 초기화
 # DeepSeek V4는 OpenAI SDK를 통해 접근 (예시)
 worker_client = OpenAI(
 api_key=DEEPSEEK_API_KEY,
 base_url="https://api.deepseek.com/v1" # 실제 엔드포인트 확인 필요
 )
 planner_client = Anthropic(api_key=ANTHROPIC_API_KEY)

 print(f"[System] 작업 시작: {task_description}")
 
 # 2. Claude(Planner)에게 초기 계획 수립 요청
 planning_prompt = f"""
 당신은 소프트웨어 아키텍트입니다. 다음 작업을 수행하기 위한 구체적인 단계별 계획을 세워주세요.
 작업: {task_description}
 
 응답은 JSON 형식의 단계 리스트로만 해주세요.
 예: {{"steps": ["파일 생성", "로직 구현", "테스트 실행"]}}
 """
 
 try:
 message = planner_client.messages.create(
 model="claude-3-5-sonnet-20241022",
 max_tokens=1024,
 messages=[{"role": "user", "content": planning_prompt}]
 )
 plan_text = message.content[0].text
 print(f"[Planner] 계획 수립 완료: {plan_text}")
 except Exception as e:
 print(f"[Error] 계획 수립 실패: {e}")
 return

 # 3. DeepSeek V4(Worker) 루프 실행
 current_context = f"작업 목표: {task_description}\n계획: {plan_text}"
 
 for i in range(max_iterations):
 print(f"\n--- Loop {i+1}/{max_iterations} (Worker: DeepSeek V4) ---")
 
 try:
 response = worker_client.chat.completions.create(
 model="deepseek-chat", # DeepSeek V4 모델명
 messages=[
 {"role": "system", "content": "당신은 계획에 따라 코드를 작성하고 수정하는 전문 개발자입니다."},
 {"role": "user", "content": current_context}
 ],
 temperature=0.3
 )
 
 worker_output = response.choices[0].message.content
 print(f"[Worker] 실행 결과:\n{worker_output[:500]}...\n") # 출력 요약
 
 # (실제 구현 시 여기서 MCP 툴을 호출하여 파일을 쓰거나 커맨드를 실행함)
 # file_system_tool.write_file(path="main.py", content=worker_output)
 
 # 종료 조건 확인 (예: "TASK_COMPLETE" 키워드)
 if "완료" in worker_output or "TASK_COMPLETE" in worker_output:
 print("[System] 작업이 성공적으로 완료되었습니다.")
 break
 
 # 피드백 루프를 위한 컨텍스트 업데이트
 current_context += f"\n\n이전 시도 결과:\n{worker_output}\n\n계속해서 진행하거나 오류를 수정하세요."
 
 except Exception as e:
 print(f"[Error] Worker 실행 중 오류 발생: {e}")
 break

# 실행 예시
if __name__ == "__main__":
 create_hybrid_agent(
 task_description="Next.js API 핸들러를 작성하여 /hello 엔드포인트를 생성하고, TypeScript 타입 검증을 포함해주세요."
 )

3.3. 코드 설명

Planner (Claude): anthropic 라이브러리를 사용하여 사용자의 요구사항을 분석하고, 작업의 순서를 정의합니다. 이 과정은 한 번만 발생하므로 고비용 모델을 사용해도 전체 비용에 큰 영향이 없습니다.
Worker (DeepSeek V4): openai 라이브러리를 통해 DeepSeek API를 호출합니다. max_iterations만큼 루프를 돌며 코드를 생성하고, 가상의 피드백(또는 실제 실행 결과)을 받아 수정을 거듭합니다. 이 부분이 가장 많은 토큰을 소비하는 곳입니다.

4. 트러블슈팅 및 팁

1. DeepSeek API 호환성: DeepSeek V4 Pro는 현재 OpenAI SDK와 호환되는 방식으로 제공되는 경우가 많지만, 베이스 URL(Base URL) 설정이 필요할 수 있습니다. (예: https://api.deepseek.com) 공식 문서를 확인해 주세요.

2. 컨텍스트 윈도우(Context Window): DeepSeek 모델은 보통 128k 이상의 긴 컨텍스트 윈도우를 지원합니다. 이는 긴 코드베이스를 분석하거나 대화 기록을 유지하기에 매우 유리합니다. 반복문(Loop)이 돌면서 컨텍스트가 길어지더라도 성능 저하가 적습니다.

3. MCP 통합: 위 파이썬 코드는 단순 예시입니다. 실제로는 mcp_config.json에 정의된 서버와 통신하여 파일 시스템에 접근해야 합니다. 이를 위해 stdio를 통해 MCP 서버와 통신하는 클라이언트 로직을 hybrid_agent.py 내부에 구현해야 완전한 자동화가 가능합니다.

5. 결론: 비용과 성능의 균형

개발자에게 AI는 단순한 채팅창이 아니라 **‘행동하는 에이전트’**가 되어가고 있습니다. 하지만 무비용으로 GPT-4o나 Claude Sonnet을 남용하는 것은 현실적이지 않습니다.

DeepSeek V4와 같은 고성능 오픈소스 모델을 **‘Worker’**로 두고, 고비용 모델을 **‘Planner’**로 활용하는 하이브리드 전략은, 향후 AI 에이전트 개발의 표준적인 패턴이 될 것입니다.

지금 바로 위 코드를 테스트해 보시고, 귀하의 개발 워크플로우에 17배의 효율성을 더해보세요.

멀티모델 AI 에이전트 팀 설계: 조합형 아키텍처와 5팀 계층 구조

Mon, 30 Mar 2026 00:31:36 +0900

개요

블로그 시스템 구축을 위해 14명의 AI 전문가, 5개 팀, 4개 LLM 모델로 구성된 멀티모델 에이전트 팀을 설계했습니다. 핵심은 두 가지입니다.

조합형 에이전트(Composed Agent): 역할 정의와 실행 프로필을 분리해 재사용성 극대화
계층형 브릿지 리더십: 상위팀-하위팀 간 기술 리드의 이중 소속으로 소통 병목 해결

이 글에서는 최종 구조, 모델 배분 전략, 조합형 아키텍처 설계 과정을 공유합니다.

배경: 왜 멀티모델인가

하나의 LLM으로 모든 작업을 처리하면 두 가지 문제가 발생합니다.

비용: Claude Opus 수준의 모델로 14명 전문가를 실행하면 비용이 통제 불가능
적합성: 설계에는 빠른 추론이, 보안 분석에는 깊은 논리가, 구현에는 안정적인 코딩이 필요

그래서 작업 성격에 맞춰 모델을 분배했습니다.

최종 팀 구조

5개 팀, 14명 전문가, 4개 모델로 구성됩니다.

graph TD
 subgraph UPPER["상위팀 — 조정 팀 (steering-team) · consensus"]
 ORC["오케스트레이터
relay:steering-orchestrator"]
 DES["설계자
gemini:gemini-2.5-flash"]
 SEC["보안 검토자
codex:gpt-4o"]
 STL["백엔드 기술 리드
relay:developer-zai"]
 FTL["프론트엔드 기술 리드
relay:developer-zai"]
 DTL["데스크탑 기술 리드
relay:developer-zai"]
 INF["인프라 네트워크
gemini:gemini-2.5-flash"]
 SAD["서버 관리자
relay:developer-zai"]
 end

 subgraph LOWER_BE["백엔드 팀 · leader_decides"]
 BTL["백엔드 기술 리드"]
 BDEV["백엔드 개발자"]
 end

 subgraph LOWER_FE["프론트엔드 팀 · leader_decides"]
 FTL2["프론트엔드 기술 리드"]
 FDEV["프론트엔드 개발자"]
 FUX["UX 디자이너"]
 end

 subgraph LOWER_DT["데스크탑 팀 · leader_decides"]
 DTL2["데스크탑 기술 리드"]
 DDEV["데스크탑 개발자"]
 DUX["UX 디자이너"]
 end

 subgraph LOWER_INFRA["인프라 팀 · leader_decides"]
 SAD2["서버 관리자 (리더)"]
 INET["클라우드 네트워크"]
 DBA["DB 아키텍트"]
 end

 UPPER -.->|bridge| LOWER_BE
 UPPER -.->|bridge| LOWER_FE
 UPPER -.->|bridge| LOWER_DT
 UPPER -.->|bridge| LOWER_INFRA

 BTL --> BDEV
 FTL2 --> FDEV
 FTL2 --> FUX
 DTL2 --> DDEV
 DTL2 --> DUX
 SAD2 --> INET
 SAD2 --> DBA

팀별 상세

팀	유형	의사결정	리더	팀원 수
조정 팀	upper	consensus	오케스트레이터	8명 (브릿지 포함)
백엔드 팀	lower	leader_decides	백엔드 기술 리드	2명
프론트엔드 팀	lower	leader_decides	프론트엔드 기술 리드	3명
데스크탑 팀	lower	leader_decides	데스크탑 기술 리드	3명
인프라 팀	lower	leader_decides	서버 관리자	3명

인프라 팀 분리 결정

초기 설계에서는 DB 아키텍트와 서버 관리자가 백엔드 팀에 포함되어 있었습니다. 하지만 작업 공간(Workspace) 기준으로 분리했습니다.

graph LR
 subgraph 백엔드팀
 B["API 코드 작성
FastAPI, Python
workspace: VS Code / SSH"]
 end

 subgraph 인프라팀
 S["서버 관리
Docker, Ubuntu, Nginx
workspace: SSH 터미널"]
 N["클라우드 네트워크
Cloudflare Dashboard
workspace: 웹 콘솔"]
 D["DB 관리
PostgreSQL, 마이그레이션
workspace: psql / SSH"]
 end

 B -.->|API 배포| S
 B -.->|쿼리 최적화| D

분리 이유: 작업 공간이 다르면 같은 팀에 두는 것보다 분리하는 것이 자연스럽습니다.

모델 배분 전략

pie title 모델별 전문가 수
 "relay:developer-zai (GLM)" : 10
 "gemini:gemini-2.5-flash" : 2
 "codex:gpt-4o" : 1
 "zai:glm-4" : 1

모델	전문가 수	용도	선택 이유
relay:developer-zai	10명	구현, 운영, 리드	비용 효율적, 안정적 코딩
gemini:gemini-2.5-flash	2명	설계, 인프라 네트워크	빠른 응답, 외부 API 호출 용이
codex:gpt-4o	1명	보안 검토	높은 추론 능력, OWASP 지식
zai:glm-4	1명	컨텍스트 압축	무료 티어, 텍스트 요약 특화

10명의 구현 전문가를 GLM(저비용 모델)에 배정하여 전체 비용의 60-70%를 절감했습니다.

조합형 에이전트 아키텍처 (Composed Agent Pattern)

이번 설계의 핵심 혁신은 역할 정의(Expert)와 실행 프로필(Definition)의 분리입니다.

기존 방식의 문제

기존에는 역할과 실행 로직이 결합되어 변경 시 전체 재작성이 필요하고 재사용이 불가능했습니다.

조합형 방식

graph TD
 DEF["Definition
백엔드 개발자"]
 DEF --> BASE["Base: backend-core"]
 DEF --> CAP["Capabilities:
rest-api, crud, auth-jwt"]
 DEF --> PLAT["Platform: fastapi"]
 DEF --> POL["Policy: blog-default"]

 BASE --> |"조합"| RUN["런타임 에이전트"]
 CAP --> |"조합"| RUN
 PLAT --> |"조합"| RUN
 POL --> |"조합"| RUN

모듈 구조

agent-library/
├── definitions/ ← 14개 에이전트 정의
├── modules/
│ ├── base/ ← 6개 기본 모듈
│ ├── capabilities/ ← 15개 역량 모듈
│ ├── platforms/ ← 5개 플랫폼 모듈
│ └── policies/ ← 1개 정책
└── runs/ ← 실행 이력

장점

재사용성: rest-api 역량 모듈은 백엔드 개발자와 기술 리드가 공유
플랫폼 교체: platform: fastapi를 platform: django로 변경하면 즉시 전환
역량 확장: 새 역량 모듈을 추가하고 Definition에 연결만 하면 됨
정책 통일: 모든 에이전트가 동일한 blog-default 정책을 따름

전문가-Definition 매핑

전문가	Definition	Base	Capabilities	Platform
백엔드 개발자	backend-developer	backend-core	rest-api, crud, auth-jwt	fastapi
백엔드 기술 리드	backend-tech-lead	backend-core	rest-api, crud, code-review	fastapi
프론트엔드 개발자	frontend-developer	frontend-core	markdown-renderer, list-filter-sort	nextjs
서버 관리자	server-administrator	server-core	docker-management, nginx-config, postgres-admin	ubuntu
인프라 네트워크	infra-network-admin	infra-core	dns-management, ssl-certificates, rate-limiting	cloudflare
보안 검토자	security-auditor	specialist-core	security-audit	fastapi
컨텍스트 압축	context-compressor	specialist-core	context-compression	markdown

TLS 인증서 전략: Cloudflare Origin CA

프로덕션 환경의 TLS 인증서로 Let’s Encrypt 대신 Cloudflare Origin CA를 선택했습니다.

sequenceDiagram
 participant Client as 방문자
 participant CF as Cloudflare (Proxy)
 participant Nginx as Nginx (Origin)
 participant API as FastAPI

 Client->>CF: HTTPS 요청
 CF->>CF: Cloudflare 관리 인증서로 종료
 CF->>Nginx: Origin CA 인증서로 암호화
 Nginx->>API: HTTP (로컬)
 API-->>Nginx: 응답
 Nginx-->>CF: Origin CA로 암호화
 CF-->>Client: 응답

항목	Let’s Encrypt	Cloudflare Origin CA
유효 기간	90일 (갱신 필요)	15년 (갱신 불필요)
발급 방식	ACME 자동화 필요	Dashboard에서 수동 발급
복잡도	certbot 설정	인증서 파일 복사만

프로덕션 아키텍처:

Oracle Cloud ARM (4 OCPU, 24GB)
├── PostgreSQL (호스트 직접 설치)
├── Docker Compose
│ ├── blog-api (FastAPI)
│ ├── blog-frontend (Next.js standalone)
│ ├── MinIO (S3 호환 스토리지)
│ └── Nginx (Cloudflare Origin CA)
└── Cloudflare Proxy (Full Strict SSL)

Relay 플러그인: 에이전트 호출 메커니즘

팀 구조는 Relay 플러그인을 통해 Claude Code에서 실행됩니다.

sequenceDiagram
 participant User as 사용자
 participant Claude as Claude Code
 participant Plugin as Relay Plugin
 participant MCP as MCP 서버
 participant LLM as 외부 LLM

 User->>Claude: /relay:invoke-agent
 Claude->>Plugin: 전문가 slug로 정의 로드
 Plugin->>Plugin: Definition 조합 (base + capabilities + platform + policy)
 Plugin->>Plugin: backed_by 확인

 alt relay:developer-zai
 Plugin->>Claude: 내부 에이전트 실행
 else gemini:*
 Plugin->>MCP: gemini_mcp 서버 호출
 MCP->>LLM: Gemini API
 LLM-->>MCP: 응답
 MCP-->>Plugin: 결과
 else codex:*
 Plugin->>MCP: codex_mcp 서버 호출
 MCP->>LLM: OpenAI API
 LLM-->>MCP: 응답
 MCP-->>Plugin: 결과
 end

 Plugin-->>Claude: 최종 결과
 Claude-->>User: 응답

backed_by 네임스페이스

네임스페이스	MCP 서버	용도
`relay:developer-zai`	내부 에이전트	구현, 운영 (저비용)
`relay:steering-orchestrator`	내부 에이전트	조율, 최종 결정
`gemini:gemini-2.5-flash`	gemini_mcp	설계, 외부 API
`codex:gpt-4o`	codex_mcp	보안 분석
`zai:glm-4`	zai_mcp	컨텍스트 압축

설계 결정 이력

결정	대안	선택 이유
인프라 팀 분리	백엔드 팀에 포함	작업 공간이 다름 (SSH vs IDE)
Cloudflare Origin CA	Let’s Encrypt	15년 유효, 갱신 불필요
PostgreSQL 호스트 설치	Docker 컨테이너	단일 서버에서 메모리 효율 우선
조합형 에이전트	단일 정의 에이전트	모듈 재사용성, 플랫폼 교체 용이
GLM 다수 배정	Claude 다수 배정	60-70% 비용 절감

회고: 설계하며 배운 것

1. “완벽한 구조"보다 “실행 가능한 구조”

팀 구조, 모델 배정, 인프라 설정을 완벽하게 설계하려다 보면 시작조차 못 합니다.

2. 작업 공간이 곧 팀 경계

코드를 작성하는 사람과 서버를 관리하는 사람은 물리적 작업 환경이 다르고, 그것이 자연스러운 팀 경계가 됩니다.

3. 조합형 아키텍처의 가치

14명의 전문가, 5개 팀, 4개 모델이 얽히는 환경에서는 모듈 분리가 필수적입니다.

4. 비용은 설계 단계에서 결정된다

“이 작업에 꼭 고비용 모델이 필요한가?“를 매번 물어보면 자연스럽게 비용이 최적화됩니다.

다음 단계

Phase 1 구현 착수: DB, Auth, Post/Category CRUD, Docker
팀 운영 경험 공유: 실제 실행 중 겪은 문제와 해결 과정
성능 모니터링: 모델별 응답 시간, 비용 대비 품질 분석

이 글은 Claude Code + Relay 플러그인을 활용한 AI 에이전트 팀 구성 경험을 정리한 것입니다.

[Claude Code] 팀 에이전트 통신 아키텍처

Sat, 28 Feb 2026 14:07:38 +0900

Claude Code 팀 에이전트 간 통신 아키텍처 설계

개요

Claude Code에서 여러 AI 에이전트가 협업할 때 효율적인 통신 방식이 필요합니다. 이 글에서는 Discord와 연동된 서버 모니터링 팀을 구축하며 설계한 통신 아키텍처를 공유합니다.

문제 정의

Claude Code에는 두 가지 유형의 에이전트가 있습니다:

Python 프로세스 (Daemon)
- Discord Gateway, user_comm_daemon 등
- 항상 실행 중, 파일 시스템 접근 가능
LLM Agent (Task로 생성)
- gcp-monitor, oci-monitor, alert-manager 등
- SendMessage 도구 사용, Claude Code 네이티브 통신

이 두 유형 간의 통신이 필요했습니다.

고려한 방식들

1. 파일 기반 메시지 큐 (기존)

장점: 구현 단순, 의존성 없음
단점: 지연 (~1초), 파일 관리 필요

2. WebSocket

장점: 실시간 양방향 통신
단점: 서버/클라이언트 구현 필요

3. gRPC

장점: 강력한 타입 체크, 스트리밍
단점: proto 파일 관리, 높은 복잡도

4. SQLite 메시지 허브 (채택)

장점: 빠름 (~10ms), 트랜잭션, 추가 의존성 없음
단점: 단일 머신에서만 동작

최종 아키텍처

┌─────────────────────────────────────────────────────────────────┐
│ SQLite Message Hub (messages.db) │
│ ~/.claude/teams/{team}/messages.db │
└───────────────────────────┬─────────────────────────────────────┘
 │
 ┌───────────────────┼───────────────────┐
 ↓ ↓ ↓
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Discord │ │ Python │ │ LLM │
│ Gateway │ │ Daemon │ │ Agent │
│ (직접 접근) │ │ (직접 접근) │ │ (MCP Tool) │
└──────────────┘ └──────────────┘ └──────────────┘

SQLite Message Hub 구조

메시지 테이블

CREATE TABLE messages (
 id INTEGER PRIMARY KEY AUTOINCREMENT,
 message_id TEXT UNIQUE NOT NULL,
 sender TEXT NOT NULL,
 recipient TEXT, -- NULL = broadcast
 message_type TEXT DEFAULT 'message',
 content TEXT NOT NULL,
 priority TEXT DEFAULT 'normal',
 metadata TEXT DEFAULT '{}',
 status TEXT DEFAULT 'pending',
 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
 processed_at TIMESTAMP,
 expires_at TIMESTAMP
);

에이전트 상태 테이블

CREATE TABLE agent_status (
 agent_name TEXT PRIMARY KEY,
 status TEXT DEFAULT 'offline',
 last_heartbeat TIMESTAMP,
 metadata TEXT DEFAULT '{}'
);

통신 방식

LLM Agent ↔ LLM Agent

SendMessage 사용 (Claude Code 네이티브)
자동 관리, idle notification 제공

Python ↔ LLM Agent

SQLite Hub + MCP Tool
Python은 직접 SQLite 접근
LLM Agent는 MCP Tool로 접근

MCP Server 구현

LLM Agent를 위한 MCP 도구들:

@server.list_tools()
async def list_tools():
 return [
 Tool(name="team_send_message", ...),
 Tool(name="team_read_messages", ...),
 Tool(name="team_broadcast", ...),
 Tool(name="team_get_status", ...),
 Tool(name="team_update_status", ...),
 ]

메시지 플로우 예시

1. Discord 사용자: "안녕"
 ↓
2. Discord Gateway → SQLite: INSERT message
 ↓
3. user_comm Daemon → SQLite: SELECT pending
 ↓
4. user_comm → SQLite: INSERT response
 ↓
5. Discord Gateway → SQLite: SELECT response
 ↓
6. Discord 채널: "안녕하세요! 👋"

성능 비교

방식	지연 시간	안정성	복잡도
파일 기반	~1000ms	보통	낮음
WebSocket	~5ms	높음	중간
SQLite	~10ms	높음	낮음

결론

SQLite Message Hub + MCP Server 조합이 Claude Code 팀 에이전트 통신에 가장 적합했습니다:

낮은 지연: 파일 기반보다 100배 빠름
안정성: 트랜잭션으로 데이터 무결성 보장
단순함: 추가 의존성 없이 Python 내장 sqlite3 사용
유연성: Python과 LLM Agent 모두 동일한 데이터 소스 사용

코드

핵심 컴포넌트:

message_hub.py: SQLite Message Hub
team_comm_mcp_server.py: MCP Server
discord_gateway.py: Discord 연동 게이트웨이
user_comm_daemon.py: 메시지 처리 데몬

영어 버전: English Version

[ZeroClaw] 소개 - 고성능 Rust 에이전트 런타임

Fri, 27 Feb 2026 19:30:00 +0900

ZeroClaw 소개: 고성능 Rust 에이전트 런타임

ZeroClaw는 Rust로 구축된 고성능 자율 에이전트 런타임으로, AI 기반 애플리케이션에서 속도, 효율성, 안정성이 필요한 개발자를 위해 설계되었습니다.

핵심 기능

성능 우선

Rust 네이티브: 가능한 한 할당 없음
Tokio 기반 Async/await: 효율적인 동시 작업
스트리밍 지원: 실시간 응답 스트리밍

확장성

Trait + Factory 아키텍처: Trait 구현으로 확장
25개 이상의 내장 도구: Shell, 파일 작업, 메모리, 브라우저, HTTP
플러그인 친화적: 코어 수정 없이 Provider, Channel, Tool 추가 가능

기본 보안

샌드박스 지원: Firejail, Bubblewrap, Landlock, Docker
페어링 프로토콜: 6자리 CSPRNG 코드
비밀 저장소: ChaCha20-Poly1305 AEAD 암호화

멀티 플랫폼

20개 이상의 메시징 채널: Telegram, Discord, Slack, WhatsApp, Signal, Matrix
13개 이상의 LLM Provider: OpenAI, Anthropic, Gemini, Ollama, Bedrock, OpenRouter

빠른 시작

cargo install zeroclaw
zeroclaw config init
zeroclaw run --channel telegram

아키텍처

ZeroClaw Agent
├── Providers (OpenAI, Anthropic, Gemini, Ollama)
├── Channels (Telegram, Discord, Slack, WhatsApp)
├── Tools (Shell, File, Memory, Browser, HTTP)
├── Memory (SQLite, PostgreSQL, Markdown)
└── Security (Policy, Sandbox, Secret Store)

로드맵

1단계: 향상된 멀티 에이전트 (진행 중)
2단계: 더 많은 통합
3단계: 엔터프라이즈 기능

영어 버전: English Version

[Multi-Agent] 통신 플랫폼 설계 고찰

Sat, 21 Feb 2026 21:00:00 +0900

들어가며

AI 에이전트 시스템이 발전하면서 단일 에이전트에서 멀티 에이전트 시스템으로의 전환이 가속화되고 있습니다. 이 글에서는 멀티 에이전트 간의 효율적인 통신을 위한 플랫폼 아키텍처를 설계하는 방법에 대해 고찰합니다.

1. 아키텍처 개요

멀티 에이전트 플랫폼은 크게 Orchestrator, Message Bus, 그리고 다양한 특화된 에이전트들로 구성됩니다.

Multi-Agent Architecture

핵심 컴포넌트

컴포넌트	역할
Orchestrator	태스크 조율, 에이전트 스케줄링
Message Bus	에이전트 간 통신 중계
State Store	공유 상태 관리
Task Queue	우선순위 기반 작업 큐
Agents	특화된 작업 수행

2. 통신 프로토콜 설계

에이전트 간 통신은 비동기 메시지 패싱을 기반으로 설계합니다.

Message Protocol

통신 흐름

Publish: 에이전트가 태스크 요청을 메시지 버스에 발행
Route: 버스가 적절한 에이전트에게 메시지 라우팅
Accept: 대상 에이전트가 태스크 수락
Acknowledge: 버스가 요청자에게 수락 확인
Execute: 에이전트가 실제 작업 수행
Result: 결과를 버스에 발행
Deliver: 버스가 결과를 요청자에게 전달

3. 메시지 구조

확장 가능하고 타입 안전한 메시지 구조를 설계합니다.

Message Structure

메시지 엔벌로프

{
 "header": {
 "message_id": "uuid-v4",
 "timestamp": "2026-02-21T12:00:00Z",
 "source_agent": "agent-research-01",
 "target_agent": "agent-writer-01",
 "message_type": "TASK_REQUEST"
 },
 "metadata": {
 "priority": "normal",
 "ttl": 3600,
 "correlation_id": "parent-uuid"
 },
 "payload": {
 "content_type": "json",
 "encoding": "utf-8",
 "data": {
 "task": "summarize",
 "content": "..."
 }
 }
}

메시지 타입

타입	용도
`TASK_REQUEST`	작업 요청
`TASK_RESULT`	작업 결과
`STATUS_UPDATE`	상태 변경 알림
`HEARTBEAT`	생존 확인
`QUERY`	정보 조회
`RESPONSE`	조회 응답

4. 에이전트 상태 관리

각 에이전트는 명확한 상태 머신을 가집니다.

State Management

상태 전이

IDLE → RECEIVING → PROCESSING → EXECUTING → COMPLETED → IDLE
 ↘ ↘ ↘
 ERROR ──────→ retry ──→ IDLE

상태별 동작

상태	동작
IDLE	새 태스크 대기
RECEIVING	메시지 수신 및 검증
PROCESSING	태스크 분석 및 준비
EXECUTING	실제 작업 수행
COMPLETED	결과 전송 및 정리
ERROR	오류 처리 및 재시도

5. 통신 패턴

5.1 Request-Response

동기식 1:1 통신 패턴입니다.

# Request
response = await bus.request(
 target="agent-code-01",
 message=TaskRequest(task="generate_code", spec={...}),
 timeout=30
)

# Response
return TaskResult(status="success", data=generated_code)

비동기식 1:N 통신 패턴입니다.

# Subscribe
@bus.subscribe("research.completed")
async def handle_research_result(message):
 # 연구 결과 처리
 pass

# Publish
await bus.publish(
 topic="research.completed",
 message=ResearchResult(data={...})
)

5.3 Broadcast

전체 에이전트에게 알림을 보낼 때 사용합니다.

# Broadcast
await bus.broadcast(
 message=SystemAlert(
 level="warning",
 message="High load detected"
 )
)

6. 핵심 설계 원칙

6.1 느슨한 결합 (Loose Coupling)

에이전트는 서로의 내부 구현을 알지 못해야 합니다. 메시지 인터페이스를 통해서만 통신합니다.

6.2 내결함성 (Fault Tolerance)

class Agent:
 async def execute_with_retry(self, task, max_retries=3):
 for attempt in range(max_retries):
 try:
 return await self.execute(task)
 except Exception as e:
 if attempt == max_retries - 1:
 await self.transition_to(State.ERROR)
 raise
 await asyncio.sleep(2 ** attempt) # Exponential backoff

6.3 확장성 (Scalability)

수평적 확장: 동일한 역할의 에이전트를 추가
로드 밸런싱: 메시지 버스에서 자동 분배
샤딩: 태스크 타입별로 에이전트 그룹 분리

6.4 관찰 가능성 (Observability)

# 메트릭 수집
@metrics.track
async def process_message(self, message):
 with metrics.timer("process_duration"):
 result = await self.handle(message)
 metrics.increment("messages_processed")
 return result

7. 구현 고려사항

7.1 메시지 직렬화

포맷	장점	단점
JSON	가독성, 호환성	크기, 성능
Protocol Buffers	성능, 스키마	복잡성
MessagePack	JSON 호환, 크기	도구 지원

7.2 백프레셔 (Backpressure)

class Agent:
 def __init__(self, max_concurrent=10):
 self.semaphore = asyncio.Semaphore(max_concurrent)

 async def process(self, message):
 async with self.semaphore:
 return await self.handle(message)

7.3 데드레터 큐 (Dead Letter Queue)

처리 실패한 메시지를 별도 큐로 이동시켜 분석 및 재처리합니다.

8. 결론

멀티 에이전트 통신 플랫폼은 다음 요소들이 핵심입니다:

유연한 메시지 구조: 다양한 통신 시나리오 지원
명확한 상태 관리: 예측 가능한 에이전트 동작
다양한 통신 패턴: 요청-응답, 발행-구독, 브로드캐스트
내결함성 설계: 재시도, 타임아웃, 에러 처리

이러한 원칙들을 기반으로 확장 가능하고 신뢰할 수 있는 멀티 에이전트 시스템을 구축할 수 있습니다.

참고 자료

영어 버전: English Version

Agent on Yarang's Tech Lair

Show HN: Semble – 에이전트를 위한 토큰 효율적인 코드 검색 엔진 구현

기존 검색 방식의 문제점: grep과 LLM의 궁합

Semble의 접근 방식: 구조와 의미의 분리

ZeroClaw 통합: 고성능 인덱서 구현

1. 데이터 구조 정의

2. 인덱싱 로직 (Parsing)

3. MCP 도구를 위한 검색 인터페이스

성능 비교 및 토큰 절약 효과

결론: 에이전트 생태계를 위한 최적화

참고 자료

개발 생산성 17배 극대화: DeepSeek V4와 Claude Code로 구축하는 저비용 AI 에이전트 루프

개발 생산성 17배 극대화: DeepSeek V4와 Claude Code로 구축하는 저비용 AI 에이전트 루프

1. 왜 DeepSeek V4와 Claude Code인가?

2. 사전 준비: MCP 서버 환경 구성

2.1. MCP 설정 파일 구성 (mcp_config.json)

3. DeepSeek V4와 Claude Code 연동 구현

3.1. 의존성 설치

3.2. 하이브리드 에이전트 코드 구현 (hybrid_agent.py)

3.3. 코드 설명

4. 트러블슈팅 및 팁

5. 결론: 비용과 성능의 균형

멀티모델 AI 에이전트 팀 설계: 조합형 아키텍처와 5팀 계층 구조

개요

배경: 왜 멀티모델인가

최종 팀 구조

팀별 상세

인프라 팀 분리 결정

모델 배분 전략

조합형 에이전트 아키텍처 (Composed Agent Pattern)

기존 방식의 문제

조합형 방식

모듈 구조

장점

전문가-Definition 매핑

TLS 인증서 전략: Cloudflare Origin CA

Relay 플러그인: 에이전트 호출 메커니즘

backed_by 네임스페이스

설계 결정 이력

회고: 설계하며 배운 것

1. “완벽한 구조"보다 “실행 가능한 구조”

2. 작업 공간이 곧 팀 경계

3. 조합형 아키텍처의 가치

4. 비용은 설계 단계에서 결정된다

다음 단계

[Claude Code] 팀 에이전트 통신 아키텍처

Claude Code 팀 에이전트 간 통신 아키텍처 설계

개요

문제 정의

고려한 방식들

1. 파일 기반 메시지 큐 (기존)

2. WebSocket

3. gRPC

4. SQLite 메시지 허브 (채택)

최종 아키텍처

SQLite Message Hub 구조

메시지 테이블

에이전트 상태 테이블

통신 방식

LLM Agent ↔ LLM Agent

Python ↔ LLM Agent

MCP Server 구현

메시지 플로우 예시

성능 비교

결론

코드

[ZeroClaw] 소개 - 고성능 Rust 에이전트 런타임

ZeroClaw 소개: 고성능 Rust 에이전트 런타임

핵심 기능

성능 우선

확장성

기본 보안

멀티 플랫폼

빠른 시작

아키텍처

로드맵

[Multi-Agent] 통신 플랫폼 설계 고찰

들어가며

1. 아키텍처 개요

핵심 컴포넌트

2.1. MCP 설정 파일 구성 (`mcp_config.json`)

3.2. 하이브리드 에이전트 코드 구현 (`hybrid_agent.py`)