Ai on Yarang's Tech Lair

RubyLLM: 레일러스를 위한 통합 AI 인터페이스 가이드

Thu, 25 Jun 2026 09:01:07 +0900

RubyLLM: 레일러스를 위한 통합 AI 인터페이스 가이드

최근 AI 기능을 애플리케이션에 통합하는 것은 선택이 아닌 필수가 되었습니다. 하지만 OpenAI, Anthropic, Google 등 다양한 공급자(Vendor)의 API를 각각 호출하는 방식은 코드의 복잡도를 높이고 유지보수를 어렵게 만듭니다. 다행히 최근 Hacker News를 통해 화제가 된 RubyLLM 같은 도구가 등장하여, Ruby와 Rails 생태계에 통합된 AI 개발 환경을 제공하고 있습니다.

이번 포스트에서는 RubyLLM을 활용해 Ruby on Rails 애플리케이션에서 주요 LLM 공급자를 단일 인터페이스로 관리하고 실전에서 활용하는 방법을 알아보겠습니다.

RubyLLM이란?

RubyLLM은 Ruby 및 Rails 프레임워크에서 사용할 수 있는 경량화된 AI 클라이언트 라이브러리입니다. 이 라이브러리의 핵심 강점은 ‘Provider Agnostic(공급자 독립적)’ 설계입니다. 개발자는 특정 벤더의 SDK에 의존하지 않고, RubyLLM이 제공하는 표준화된 메서드를 통해 여러 AI 모델을 유연하게 호출할 수 있습니다.

주요 특징은 다음과 같습니다:

다양한 공급자 지원: OpenAI(GPT), Anthropic(Claude), Google(Gemini) 등 주요 모델을 단일 gem으로 관리
Rails 친화적: ActiveRecord와 같은 친숙한 패턴의 API 제공
스트리밍 지원: 실시간 응답 생성을 위한 스트리밍 인터페이스 내장

프로젝트 설정

먼저 Gemfile에 RubyLLM을 추가하고 설치합니다. (현재 최신 버전을 가정합니다)

# Gemfile
gem 'ruby_llm'

번들로 설치한 후, 환경 변수를 통해 API 키를 설정합니다. Rails의 credentials.yml.enc나 .env 파일을 활용하는 것이 좋습니다.

# .env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

기본 사용법: Chat 인터페이스

RubyLLM을 사용하면 가장 기본적인 텍스트 생성 작업을 매우 직관적으로 구현할 수 있습니다. 다음은 Rails 컨트롤러나 서비스 객체 내에서 LLM을 호출하는 예제입니다.

1. OpenAI GPT-4o 호출

require 'ruby_llm'

# 클라이언트 초기화
client = RubyLLM::Client.new

response = client.chat(
 model: "gpt-4o",
 messages: [
 { role: "system", content: "당신은 친절한 어시스턴트입니다." },
 { role: "user", content: "Rust 언어의 주요 특징을 설명해주세요." }
 ]
)

puts response.content
# => "Rust는 메모리 안전성, 고성능, 그리고 안전한 동시성을 중점적으로 설계된 시스템 프로그래밍 언어입니다..."

2. 모델 간 간편 전환 (Vendor Lock-in 방지)

비즈니스 요구사항이 변경되어 OpenAI에서 Google의 Gemini로 전환해야 한다면, 모델 이름과 키만 변경하면 됩니다. 코드 구조는 그대로 유지됩니다.

# 기존 코드 유지, 모델명만 변경
gemini_response = client.chat(
 model: "gemini-1.5-pro",
 messages: [
 { role: "system", content: "당신은 기술 블로거입니다." },
 { role: "user", content: "ZeroClaw 아키텍처에 대해 요약해줘." }
 ]
)

실전 활용: 스트리밍 응답 구현하기

사용자 경험(UX)을 위해서는 생성형 AI의 답변을 한 번에 기다리는 것보다, 타자를 치듯이 실시간으로 보여주는 스트리밍 방식이 선호됩니다. RubyLLM은 블록(Proc)을 통해 이를 쉽게 구현합니다.

다음은 Rails의 Turbo Stream과 함께 사용하여 실시간으로 화면에 텍스트를 출력하는 서비스 클래스 예제입니다.

# app/services/ai_streaming_service.rb
class AiStreamingService
 def initialize(user_message)
 @user_message = user_message
 end

 def call
 client = RubyLLM::Client.new
 
 # OpenAI 스트리밍 호출
 client.chat(
 model: "gpt-4o-mini",
 messages: [{ role: "user", content: @user_message }],
 stream: proc { |chunk| 
 # 수신된 텍스트 덩어리(chunk)를 처리
 # 예: Rails 채널을 통해 클라이언트로 브로드캐스트
 ActionCable.server.broadcast "ai_channel", { content: chunk }
 
 # 또는 로그 출력
 print chunk
 $stdout.flush
 }
 )
 end
end

이 패턴을 사용하면 LLM이 토큰을 생성할 때마다 클라이언트 브라우저로 즉시 전송하여, 마치 ChatGPT를 사용하는 것과 같은 부드러운 경험을 제공할 수 있습니다.

결론: Ruby 생태계의 AI 개발 트렌드

과거 Ruby는 AI 개발 영역에서 파이썬(Python)에 비해 뒤처진다는 평가를 받기도 했습니다. 그러나 RubyLLM과 같은 프레임워크의 등장은 ‘AI 모델 자체를 개발하는 것’이 아니라 ‘AI 모델을 활용하는 애플리케이션’을 구축하는 데 있어 Ruby가 여전히 강력한 경쟁력을 가짐을 보여줍니다.

특히 우리 팀(ZeroClaw)이 추구하는 에이전트 런타임 구현에 있어, Ruby의 높은 생산성과 RubyLLM의 유연한 추상화 계층을 결합한다면, 복잡한 멀티 에이전트 시스템을 더 빠르게 프로토타이핑하고 구축할 수 있을 것입니다.

Python 생태계의 LangChain이나 LlamaIndex가 대중화된 것처럼, Ruby 생태계에서도 RubyLLM이 표준처럼 자리 잡을 가능성이 매우 높아 보입니다. Rails 개발자라면 지금 당장 테스트 프로젝트에서라도 이 도구를 적용해 보시길 권장합니다.

참고 자료

RubyLLM GitHub Repository (가상의 링크)
OpenAI API Documentation
Google Gemini API Documentation

Rust 기반 MCP 서버 구축하기: ZeroClaw 아키텍처 활용

Tue, 09 Jun 2026 09:00:48 +0900

Rust 기반 MCP 서버 구축하기: ZeroClaw 아키텍처 활용

최근 AI 에이전트 생태계에서 **Model Context Protocol (MCP)**는 표준 인터페이스로 자리 잡고 있습니다. 저희 팀의 ZeroClaw 프로젝트와 같은 고성능 런타임 환경에서 MCP 서버를 구축할 때, Rust의 안전성과 속도는 필수적인 요소입니다. 이번 포스트에서는 실무적으로 바로 적용할 수 있는 Rust 기반 MCP 서버의 구조를 설계하고, 실제 코드를 통해 구현 방법을 살펴보겠습니다.

1. MCP 서버의 핵심 요구사항

AI 모델이 데이터에 접근하기 위해 MCP 서버는 다음 세 가지 핵심 기능을 수행해야 합니다.

리소스 발견 (Discovery): 모델이 사용할 수 있는 데이터(파일, API 등)의 목록을 제공
리소스 접근 (Access): 요청받은 데이터의 실제 내용을 효율적으로 반환
도구 실행 (Tool Execution): 모델의 지시에 따라 시스템 내부에서 동작을 수행

Rust는 특히 Zero-cost abstractions와 강력한 비동기 런타임(tokio) 덕분에 대규모 요청을 처리하는 MCP 서버에 최적입니다.

2. 아키텍처 설계: ZeroClaw 스타일

단순한 RPC 호출을 넘어, 우리는 이벤트 기반 아키텍처를 채택하여 확장성을 확보합니다. 구조는 다음과 같습니다.

Transport Layer: stdio 또는 WebSocket을 통한 메시지 송수신 (JSON-RPC 2.0)
Handler Layer: 요청을 라우팅하고 검증하는 계층
Core Logic: 실제 비즈니스 로직 (파일 시스템 접근, DB 조회 등)

3. 실전 코드 예제

가장 대중적인 트랜스포트인 stdio(표준 입출력) 기반의 간단한 MCP 서버를 작성해 보겠습니다. 이 예제는 LLM이 로컬 파일 시스템의 로그를 읽을 수 있게 해주는 기능을 구현합니다.

3.1. 의존성 설정 (`Cargo.toml`)

Rust의 생태계를 활용하기 위해 직렬화와 비동기 처리를 위한 크레이트를 추가합니다.

[dependencies]
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
async-trait = "0.1"

3.2. 핸들러 트레이트 정의

MCP 표준에 맞춰 Tool과 Resource를 처리할 공통 인터페이스를 정의합니다. 이는 추후 ZeroClaw 런타임에 통합하기 쉽게 만듭니다.

use serde_json::Value;
use async_trait::async_trait;

#[async_trait]
pub trait McpHandler {
 async fn handle(&self, params: Value) -> Result<Value, String>;
 fn name(&self) -> &str;
}

3.3. 로그 읽기 도구 구현

이제 실제로 서버 내부의 파일을 읽어서 AI 모델에 전달하는 로직을 구현합니다.

use std::fs;
use std::path::Path;

pub struct LogReaderTool;

#[async_trait]
impl McpHandler for LogReaderTool {
 fn name(&self) -> &str {
 "read_logs"
 }

 async fn handle(&self, params: Value) -> Result<Value, String> {
 // 1. 파라미터 검증 및 추출
 let file_path = params.get("path")
 .and_then(|v| v.as_str())
 .ok_or("Missing 'path' parameter".to_string())?;

 // 2. 보상: 경로 조작 방지 (SandBoxing)
 // 실제 운영 환경에서는 chroot나 전용 가상 디렉토리를 사용해야 합니다.
 if !file_path.ends_with(".log") {
 return Err("Only .log files are allowed".into());
 }

 // 3. 파일 시스템 접근 (동기식 I/O를 비동기 컨텍스트로 래핑)
 let content = fs::read_to_string(file_path)
 .map_err(|e| format!("Failed to read file: {}", e))?;

 // 4. 결과 포맷팅
 Ok(serde_json::json!({
 "status": "success",
 "content": content,
 "lines": content.lines().count()
 }))
 }
}

3.4. 메인 루프 및 JSON-RPC 서버

LLM과의 통신을 담당하는 메인 루프입니다. 표준 입력에서 JSON-RPC 요청을 읽고, 처리 결과를 표준 출력으로 내보냅니다.

use tokio::io::{AsyncBufReadExt, BufReader};
use tokio::io::{AsyncWriteExt, BufWriter};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
 let stdin = tokio::io::stdin();
 let stdout = tokio::io::stdout();
 let mut reader = BufReader::new(stdin).lines();
 let mut writer = BufWriter::new(stdout);

 let tool = Arc::new(LogReaderTool);

 // LLM이나 호스트로부터 요청이 들어올 때마다 처리
 while let Ok(Some(line)) = reader.next_line().await {
 if line.trim().is_empty() { continue; }

 if let Ok(json_req) = serde_json::from_str::<Value>(&line) {
 let method = json_req.get("method").and_then(|m| m.as_str()).unwrap_or("");
 let id = json_req.get("id");

 if method == "tools/call" || method == "tools/invoke" {
 let params = json_req.get("params").cloned().unwrap_or(Value::Null);
 
 // 비즈니스 로직 실행
 let result = tool.handle(params).await;
 
 let response = match result {
 Ok(data) => serde_json::json!({
 "jsonrpc": "2.0",
 "id": id,
 "result": data
 }),
 Err(e) => serde_json::json!({
 "jsonrpc": "2.0",
 "id": id,
 "error": { "code": -32000, "message": e }
 })
 };
 
 writer.write_all(response.to_string().as_bytes()).await?;
 writer.write_all(b"\n").await?;
 writer.flush().await?;
 }
 }
 }
 Ok(())
}

4. 최적화 및 배포 고려사항

위 코드는 기본적인 골격이지만, ZeroClaw와 같은 프로덕션 환경에서는 다음 사항을 고려해야 합니다.

에러 타입 구체화: String 대신 구체적인 thiserror나 anyhow 기반의 에러 타입을 사용하여 디버깅을 용이하게 하세요.
보안 샌드박싱: std::fs 대신 가상 파일 시스템(VFS) 라이브러리를 사용하여, 에이전트가 시스템 전체에 접근하는 것을 막아야 합니다.
Graceful Shutdown: tokio의 signal 모듈을 활용하여 인터럽트 신호(SIGTERM)를 처리하고, 진행 중인 파일 작업을 안전하게 종료해야 합니다.

5. 결론

Rust는 타입 안전성과 메모리 관리 능력 덕분에 신뢰할 수 있는 MCP 서버를 구축하는 데 최적의 언어입니다. 위 코드를 바탕으로 blog-api-server나 모니터링 시스템과 연동한다면, AI 모델이 직접 시스템 로그를 분석하고 패치를 제안하는 완전한 자동화 사이클을 구축할 수 있습니다.

다음 포스트에서는 이 MCP 서버를 ZeroClaw 런타임 위에서 어떻게 에이전트화하고, 다른 서비스와 통신하는지 다루겠습니다.

AI 에이전트 신뢰성 강화: Forge Guardrails와 MCP 통합 가이드

Wed, 20 May 2026 09:00:35 +0900

AI 에이전트 신뢰성 강화: Forge Guardrails와 MCP 통합 가이드

최근 LLM(Large Language Model)을 활용한 에이전트 시스템이 급격히 발전하고 있습니다. Hacker News에서는 “Forge – Guardrails take an 8B model from 53% to 99% on agentic tasks"라는 흥미로운 사례가 화제가 되었습니다. 이는 모델의 파라미터 수를 늘리는 것보다, 적절한 **가드레일(Guardrails)**을 적용하는 것이 특정 작업의 성공률을 비약적으로 높일 수 있음을 시사합니다.

저희 팀에서 진행 중인 ZeroClaw 및 MCP(Model Context Protocol) 기반 프로젝트들에 있어 에이전트의 신뢰성은 필수적입니다. 이번 포스트에서는 오픈소스 가드레일 프레임워크인 Forge의 개념을 살펴보고, 이를 기존 MCP 아키텍처에 통합하여 에이전트의 안정성을 확보하는 구체적인 방법을 소개합니다.

문제 정의: 자율성의 딜레마

에이전트에게 자율성을 부여할수록 예상치 못한 행동을 할 위험이 커집니다. 예를 들어, 블로그 게시글을 생성하라는 MCP 요청이 있을 때, 에이전트가 시스템 명령어를 실행하거나 허용되지 않은 API를 호출하려 시도할 수 있습니다.

기존의 [blog-api-server] 구현에서는 프롬프트 엔지니어링과 간단한 JSON 스키마 검증으로 이를 방어하려 했으나, 복잡한 멀티 에이전트 환경에서는 한계가 있었습니다. 이를 해결하기 위해 입력과 출력을 사전에 필터링하는 L1 가드레일 레이어를 도입하기로 결정했습니다.

솔루션: Guardrails 패턴 적용

Forge가 보여주듯, 에이전트 작업의 성공률(53% → 99%)을 높이는 핵심은 실행 전 검증입니다. 우리는 에이전트가 LLM으로부터 응답을 받아 사용자에게 전달하거나 도구(Tool)를 실행하기 전, 중간 계층에서 이를 검증하는 구조를 설계했습니다.

아키텍처 개요

기존 MCP 클라이언트와 LLM 사이에 Validator 계층을 두어 다음을 수행합니다.

입력 검증 (Input Validation): 사용자의 요청이 시스템 정책을 위반하지 않는지 확인 (예: 공격적인 프롬프트 필터링).
출력 검증 (Output Validation): LLM이 생성한 JSON이나 함수 호출 인자가 스키마에 부합하는지 확인.

실전 코드 예제: Rust로 구현하는 안전장치

ZeroClaw의 Rust 환경에서 가벼운 출력 검증기를 구현해 보겠습니다. 복잡한 외부 라이브러리 없이, serde와 regex를 활용하여 LLM이 생성한 코드 실행 명령을 안전하게 감싸는 예제입니다.

1. 검증 로직 구현하기

먼저, 에이전트가 생성한 명령어가 안전한지 판별하는 간단한 검증기입니다.

use regex::Regex;
use serde::{Deserialize, Serialize};

// 에이전트가 생성할 수 있는 명령어 구조
#[derive(Debug, Serialize, Deserialize)]
struct AgentCommand {
 tool_name: String,
 parameters: String,
}

pub struct Guardrail;

impl Guardrail {
 // 위험한 문자열 필터링 (간단한 예시)
 fn is_dangerous(input: &str) -> bool {
 let dangerous_patterns = vec!["rm -rf", "sudo", "eval", "__import__"];
 dangerous_patterns.iter().any(|&pat| input.contains(pat))
 }

 // 명령어 실행 전 검증 로직
 pub fn validate_command(cmd: &AgentCommand) -> Result<&AgentCommand, String> {
 // 1. 도구 이름 화이트리스트 확인
 let allowed_tools = vec!["blog_post", "search", "read_file"];
 if !allowed_tools.contains(&cmd.tool_name.as_str()) {
 return Err(format!("허용되지 않은 도구 사용 시도: {}", cmd.tool_name));
 }

 // 2. 파라미터 내 위험 키워드 검사
 if Self::is_dangerous(&cmd.parameters) {
 return Err("파라미터에 잠재적으로 위험한 명령어가 포함되어 있습니다.".to_string());
 }

 // 3. 안전하다면 명령어 승인
 Ok(cmd)
 }
}

2. 에이전트 루프에 통합하기

이제 검증기를 MCP 서버의 요청 처리 루프에 연결합니다. 에이전트가 응답을 생성하면, 실제 시스템이 이를 실행하기 전에 Guardrail을 거쳐야 합니다.

// 가상의 에이전트 실행 함수
fn execute_agent_task(llm_output: &str) -> Result<String, String> {
 // 1. LLM 출력 파싱 (실제로는 JSON 파싱 등)
 // 여기서는 간단히 파싱되었다고 가정합니다.
 let command = AgentCommand {
 tool_name: "blog_post".to_string(),
 parameters: "title: 'Hello World'".to_string(),
 };

 // 2. 가드레일 통과 전
 println!("[System] LLM 응답 수신: {}", command.tool_name);

 // 3. 가드레일 검증 실행
 let safe_command = Guardrail::validate_command(&command)?;

 // 4. 검증된 명령어 실행
 println!("[System] 안전한 명령어 실행 중...");
 // 실제 도구 실행 로직 (예: 블로그 API 호출)
 Ok("게시글이 성공적으로 생성되었습니다.".to_string())
}

fn main() {
 // 정상 케이스
 match execute_agent_task("valid_response") {
 Ok(msg) => println!("성공: {}", msg),
 Err(e) => println!("차단됨: {}", e),
 }

 // 비정상 케이스 시뮬레이션
 let malicious_cmd = AgentCommand {
 tool_name: "system_shell".to_string(), // 화이트리스트에 없음
 parameters: "rm -rf /".to_string(),
 };

 match Guardrail::validate_command(&malicious_cmd) {
 Ok(_) => println!("오류: 해커가 침입했습니다!"),
 Err(e) => println!("보호됨: {}", e), // "보호됨: 허용되지 않은 도구 사용 시도: system_shell"
 }
}

효과 및 전망

이러한 L1 방어선을 구축함으로써 우리는 다음과 같은 이점을 얻을 수 있습니다.

안정성 향상: Forge 사례처럼 8B 모델도 충분히 안전하게 활용할 수 있어 추론 비용 절감.
투명성 확보: 에이전트가 왜 특정 작업을 거부했는지 로그를 통해 명확히 파악 가능.
유지보수성: 보안 정책이 변경되어도 Guardrail 모듈만 수정하면 됨.

앞으로 ZeroClaw 프로젝트에서는 이 검증 로직을 비동기 런타임에 통합하여, 멀티 에이전트 간 통신([Discord MCP], [Cloud Monitor]) 시에도 실시간으로 안전성을 모니터링할 계획입니다.

단순히 모델의 성능을 높이는 것에 집착하기보다, 이처럼 시스템 레벨에서의 안전장치를 어떻게 설계하느냐가 AI 에이전트를 실제 프로덕션에 배포하는 관건이 될 것입니다.

이 글은 ZeroClaw 및 MCP 관련 아키텍처 설계 문서들을 참고하여 작성되었습니다.

Computer Use API vs Structured Output: 비용 효율적인 LLM 구현 전략

Wed, 06 May 2026 09:00:48 +0900

Computer Use API vs Structured Output: 비용 효율적인 LLM 구현 전략

최근 Hacker News에서 흥미로운 기사를 접했습니다. **[Computer Use is 45x more expensive than structured APIs]**라는 제목의 글입니다. Anthropic의 최신 기능인 ‘Computer Use’는 AI가 컴퓨터 화면을 보고 마우스와 키보드를 조작하여 사용자 대신 작업을 수행할 수 있게 해줍니다. 마치 철권(Tekken) 게임에서 AI가 플레이어를 대신해 콤보를 입력하는 것처럼 매우 매력적입니다.

하지만 이 기능의 구현 비용은 기존의 **Structured Output(JSON 모드 등)**을 사용할 때보다 무려 45배나 높다는 분석이 나왔습니다.

이번 포스트에서는 왜 이런 격차가 발생하는지, 그리고 우리가 개발하는 **Multi-Agent 시스템(예: ZeroClaw)**에서 이 비용 문제를 어떻게 지혜롭게 해결할 수 있을지 현실적인 코드와 함께 분석해 보겠습니다.

1. 비용 격차의 원인 분석

Computer Use (GUI 기반 접근)

‘Computer Use’는 본질적으로 VNC(RDP) 원격 제어와 유사합니다. AI는 매 턴마다 다음을 수행해야 합니다.

화면 캡처: 고해상도 이미지를 다운로드합니다. (토큰 비용 급증)
시각적 처리: 이미지를 이해하기 위해 대규모 Vision 모델을 실행합니다.
좌표 계산: 버튼의 위치를 픽셀 단위로 계산합니다.
액션 실행: 마우스 클릭/키보드 입력을 전송합니다.

이 과정에서 단순한 텍스트 응답 대신 수백만 개의 ‘시각적 토큰’이 소모됩니다.

Structured Output (API 기반 접근)

반면, 우리가 블로그 API 서버나 MCP(Model Context Protocol)를 통해 구성하는 전통적인 방식은 훨씬 효율적입니다.

텍스트 입력: 시스템 상태나 사용자 의도가 텍스트로 전달됩니다.
논리적 추론: LLM이 텍스트를 파싱하여 의사결정을 내립니다.
직접 호출: tool_use 블록을 통해 함수를 직접 실행합니다. (이미지 처리 불필요)

2. 실용적인 해결책: 하이브리드 아키텍처

모든 작업을 Computer Use로 처리하는 것은 낭비입니다. 우리는 ZeroClaw나 MCP 블로그 자동화 프로젝트에서 배운 **‘도구 분리의 원칙’**을 적용해야 합니다.

전략: 도구 사용 우선순위

1순위: Native API (Structured Output)
- 데이터베이스 조회, API 호출, 파일 생성 등 명확한 로직은 항상 함수 호출로 처리.
2순위: Browser Automation (Playwright/Selenium)
- 복잡한 DOM 조작이 필요하나, 백엔드 API가 없는 경우. (이미지보다 HTML 트리를 파싱하는 것이 저렴)
최후의 수단: Computer Use (Vision)
- 캡차가 있거나, 동영상 편집 프로그램처럼 DOM 접근이 불가능한 오래된 레거시 소프트웨어만 대상으로 함.

3. 코드 예제: 비용 최적화된 Agent 구현

Python을 사용하여 LLM이 API 호출(Structured)과 브라우저 제어(Browser)를 선택적으로 사용하도록 만드는 예제를 작성해 보겠습니다. Computer Use는 아직 특정 클라우드 환경에 종속되어 있으므로, 가장 현실적인 대안인 **Playwright(HTML 기반)**와 API 호출을 비교하는 코드를 소개합니다.

시나리오: 블로그 게시글 자동 발행

LLM 에이전트에게 “최신 기술 뉴스를 요약하고 내 블로그에 발행해"라고 요청한다고 가정해 봅시다.

구조적 접근 (Structured Output + API)

import json
from typing import Literal

# 1. 도구 정의 (API 방식)
tools = [
 {
 "type": "function",
 "function": {
 "name": "create_blog_post",
 "description": "블로그에 새 글을 발행합니다. (가장 저렴하고 빠름)",
 "parameters": {
 "type": "object",
 "properties": {
 "title": {"type": "string"},
 "content": {"type": "string"},
 "tags": {"type": "array", "items": {"type": "string"}}
 },
 "required": ["title", "content"]
 }
 }
 },
 {
 "type": "function",
 "function": {
 "name": "search_web_browser",
 "description": "웹 브라우저를 제어하여 정보를 검색합니다. (API가 없을 때 사용)",
 "parameters": {
 "type": "object",
 "properties": {
 "query": {"type": "string"}
 },
 "required": ["query"]
 }
 }
 }
]

# 2. 에이전트 실행 로직 (시뮬레이션)
def run_agent(user_query: str):
 # 단계 1: LLM에게 도구 사용 요청 (실제로는 OpenAI/Anthropic API 호출)
 # LLM 응답 시뮬레이션: create_blog_post 도구 선택
 llm_response = {
 "tool": "create_blog_post",
 "arguments": {
 "title": "Gemma 4 가속화 기술",
 "content": "구글의 최신 모델 Gemma은 멀티-토큰 예측을 통해...",
 "tags": ["AI", "Google"]
 }
 }

 # 단계 2: 로컬 함수 실행 (Vision 필요 없음)
 if llm_response['tool'] == 'create_blog_post':
 print(f"[API 실행] 블로그 글 발행: {llm_response['arguments']['title']}")
 # 실제로는 여기서 requests.post('https://blog-api.com/posts', ...) 호출
 return {"status": "success", "cost": "0.0001 USD"}

print(run_agent("블로그에 글 써줘"))

이 방식은 텍스트만 주고받으므로 매우 저렴합니다.

비구조적 접근 (Computer Use 시뮬레이션 - 비용 상승)

만약 우리가 블로그 API를 사용하지 않고 Computer Use로 웹 브라우저를 띄워 글을 쓴다고 상상해 보세요.

# Computer Use 방식의 의사코드 (비용 폭발 구간)
def run_computer_use_agent():
 # 1. 화면 캡처 (1024x768 이미지 -> 약 1,100 토큰 소모)
 screenshot = capture_screen()
 print(f"[Vision] 화면 분석 중... (토큰 1,100개 소모)")

 # 2. LLM 추론: "로그인 버튼을 찾아라"
 action = llm_vision_inference(screenshot, prompt="Find the login button")
 # 결과: {"x": 500, "y": 300, "action": "click"}
 print(f"[Action] 마우스 이동 및 클릭: {action}")

 # 3. 다시 화면 캡처 및 입력 필드 분석
 screenshot = capture_screen()
 print(f"[Vision] 입력 필드 분석 중... (토큰 1,100개 소모)")
 
 # ... (반복적인 캡처와 추론)
 return {"status": "success", "cost": "0.05 USD"} 
 # API 방식(0.0001 USD) 대비 약 500배 비용 발생 가능

4. ZeroClaw 및 MCP 아키텍처 적용 가이드

우리가 진행 중인 **ZeroClaw(고성능 Rust 에이전트)**나 Discord MCP 프로젝트에서 이 원칙을 적용하면 다음과 같은 설계가 나옵니다.

MCP (Model Context Protocol) 표준 준수:
- 가능한 모든 자원(파일 시스템, 데이터베이스, 클라우드 리소스)을 MCP Server로 노출시켜 LLM이 Structured JSON으로 제어하게 하십시오.
- 예: Discord 메시지를 보낼 때, 브라우저를 띄우는 것이 아니라 discord_mcp.send_message() 함수를 호출하도록 유도합니다.
Prompt Engineering:
- 시스템 프롬프트에 명확히 선언하십시오.
- “당신은 화면을 보는 것이 아니라 도구를 호출해야 합니다. 사용자의 요청을 처리하기 위해 먼저 available_tools 리스트를 확인하고, 함수 호출이 가능한지 우선 확인하십시오.”
Fallback 메커니즘:
- MCP Server나 API가 죽었을 때만, 혹은 반드시 시각적 확인이 필요할 때만 ‘Computer Use’ 또는 ‘Browser Automation’ 에이전트를 깨우는 2단계 구조를 만드십시오.

5. 결론

AI 에이전트를 개발할 때 ‘Computer Use’는 마치 ‘스위스 군용 칼’과 같습니다. 모든 것을 할 수 있지만, 나사를 하나 조일 때마다 거대한 칼을 꺼내면(화면을 캡처면) 비용이 막대합니다.

우리는 **‘적재적소’**의 도구를 사용해야 합니다. 대부분의 작업은 **Structured Output(API)**으로 해결하고, 정말 어쩔 수 없는 상황에만 Vision/GUI 기능을 사용하는 전략을 취한다면, 45배의 비용 차이를 우리의 이익으로 돌릴 수 있을 것입니다.

앞으로 진행될 ZeroClaw 프로젝트의 통신 프로토콜 설계에서도 이 비용 효율성을 최우선 가이드라인으로 삼겠습니다.

개발 생산성 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배의 효율성을 더해보세요.

MCP 서버 시작하기: Claude Code와 통합하는 첫 번째 도구 만들기

Sun, 03 May 2026 10:47:00 +0900

MCP 서버 시작하기: Claude Code와 통합하는 첫 번째 도구 만들기

MCP(Model Context Protocol)는 Claude Code 및 다른 AI 도구와 통합할 수 있는 강력한 프로토콜입니다. 이 가이드에서는 첫 번째 MCP 서버를 만드는 과정을 단계별로 안내합니다.

MCP란 무엇인가?

MCP는 AI 에이전트가 외부 도구와 리소스에 접근할 수 있게 하는 표준 프로토콜입니다. 주요 특징:

표준화된 인터페이스: 다양한 도구를 통일된 방식으로 통합
리소스 공유: 파일, 데이터베이스 등의 리소스를 안전하게 접근
확장성: 새로운 도구를 쉽게 추가 가능

기본 MCP 서버 구조

// mcp-server-template.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server(
 {
 name: 'my-mcp-server',
 version: '1.0.0'
 },
 {
 capabilities: {
 tools: {},
 resources: {}
 }
 }
);

// 도구 등록 예시
server.setRequestHandler(ListToolsRequestSchema, async () => ({
 tools: [
 {
 name: 'my_tool',
 description: '내 도구 설명',
 inputSchema: {
 type: 'object',
 properties: {
 param1: {
 type: 'string',
 description: '파라미터 설명'
 }
 },
 required: ['param1']
 }
 }
 ]
}));

// 서버 시작
const transport = new StdioServerTransport();
await server.connect(transport);

실전 예제: 간단한 계산기 MCP 서버

// calculator-mcp-server.ts
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';

const server = new Server(
 { name: 'calculator-server', version: '1.0.0' },
 { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
 tools: [
 {
 name: 'calculate',
 description: '기본 수학 연산 수행',
 inputSchema: {
 type: 'object',
 properties: {
 expression: {
 type: 'string',
 description: '계산할 수식 (예: "2 + 2")'
 }
 },
 required: ['expression']
 }
 }
 ]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
 if (request.params.name === 'calculate') {
 const expression = request.params.arguments?.expression as string;
 try {
 // 안전한 계산을 위해 Function 대신 eval 사용
 const result = Function(`"use strict"; return (${expression})`)();
 return {
 content: [{
 type: 'text',
 text: `결과: ${result}`
 }]
 };
 } catch (error) {
 return {
 content: [{
 type: 'text',
 text: `계산 오류: ${error}`
 }],
 isError: true
 };
 }
 }
 return { content: [] };
});

Claude Code 설정

MCP 서버를 Claude Code에 등록하려면 ~/.config/claude/settings.json을 수정합니다:

{
 "mcpServers": {
 "calculator": {
 "command": "node",
 "args": ["/path/to/calculator-mcp-server.js"]
 }
 }
}

리소스 제공하기

// 리소스 리스트 제공
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
 resources: [
 {
 uri: 'calc://history',
 name: '계산 기록',
 description: '최근 계산 이력',
 mimeType: 'application/json'
 }
 ]
}));

// 리소스 내용 제공
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
 if (request.params.uri === 'calc://history') {
 return {
 contents: [{
 uri: request.params.uri,
 mimeType: 'application/json',
 text: JSON.stringify({ history: [] })
 }]
 };
 }
 throw new Error('리소스를 찾을 수 없습니다');
});

보안 고려사항

입력 검증: 모든 사용자 입력을 검증하고 제한
권한 제한: 최소 권한 원칙 적용
에러 처리: 민감 정보가 에러 메시지에 노출되지 않도록 주의
속도 제한: 과도한 요청을 방지하는 레이트 리밋 구현

배포 및 테스트

# 서버 빌드
npm run build

# 로컬 테스트
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/server.js

# Claude Code에 통합 후 테스트
# 설정 파일 reload 후 Claude Code에서 도구 사용

다음 단계

더 복잡한 도구와 리소스 추가
프롬프트 템플릿 구현
에러 핸들링 개선
로깅 및 모니터링 추가

MCP 서버 개발은 Claude Code의 기능을 확장하고 자동화를 강화하는 훌륭한 방법입니다. 작은 프로젝트부터 시작하여 점진적으로 기능을 확장해보세요.

참고 자료

블로그 AI 자동 댓글 시스템 구축기 (1/3) — 아키텍처와 구현

Sun, 03 May 2026 01:00:00 +0900

개요

블로그 댓글에 AI가 자동으로 응답하는 시스템을 구축했습니다. 독자가 블로그 포스트에 댓글을 남기면, AI 어시스턴트가 포스트 컨텍스트를 분석하여 기술적으로 정확하면서도 친절한 답변을 자동으로 생성합니다.

이 시리즈는 3부작으로 구성됩니다:

1부 (이 글): 전체 아키텍처 설계와 핵심 코드 구현
2부: 파일 기반 인증, 권한 관리, 보안 강화
3부: systemd 배포, nginx 프록시, 트러블슈팅

시스템 아키텍처

전체 데이터 흐름

독자 댓글 작성
 ↓
[giscus] → GitHub Discussions에 댓글 생성
 ↓
[GitHub Webhook] → HTTP POST 전송
 ↓
[nginx reverse proxy] → 헤더 포워딩
 ↓
[Flask Worker] → 시그니처 검증 → 댓글 분석
 ↓
[Claude Code CLI] → AI 응답 생성
 ↓
[GitHub GraphQL API] → Discussion에 답변 게시
 ↓
[giscus] → 블로그에 답변 표시

이 아키텍처에서 핵심은 giscus가 GitHub Discussions를 댓글 저장소로 사용한다는 점입니다. 따라서 GitHub Webhook으로 새 댓글 이벤트를 수신하고, 같은 GitHub API로 응답을 게시할 수 있습니다.

구성 요소

구성 요소	역할	기술
giscus	블로그 댓글 위젯	GitHub Discussions 기반
GitHub Webhook	이벤트 전달	`discussion_comment` 이벤트
nginx	리버스 프록시	헤더 포워딩, SSL 터미네이션
Flask Worker	웹훅 수신 및 처리	Python, Flask, Flask-Limiter
Claude Code	AI 응답 생성	`--print` 모드 CLI 호출
GitHub GraphQL	응답 게시	Mutation API

giscus 설정

Hugo 블로그에 giscus를 통합하려면 hugo.toml에 다음 설정이 필요합니다:

[params]
 [params.comments]
 enabled = true
 provider = "giscus"
 [params.comments.giscus]
 repo = "yarang/blogs"
 repoId = "YOUR_REPO_ID"
 category = "General"
 categoryId = "YOUR_CATEGORY_ID"
 mapping = "pathname"
 strict = "0"
 reactionsEnabled = "1"
 emitMetadata = "0"
 inputPosition = "bottom"
 lang = "ko"
 theme = "noborder_gray"

mapping = "pathname"은 포스트 URL 경로를 기준으로 Discussion을 매핑합니다. 이렇게 하면 각 블로그 포스트마다 독립적인 Discussion이 생성됩니다.

GitHub Webhook 구성

GitHub 리포지토리 Settings > Webhooks에서:

Payload URL: https://your-domain/webhook
Content type: application/json
Secret: HMAC-SHA256 서명용 시크릿 (보안 편에서 상세히 다룸)
Events: Discussion comments 선택

Webhook은 댓글이 생성될 때마다 discussion_comment 이벤트를 Flask 워커로 전송합니다.

Flask 워커 구현

프로젝트 구조

auto-comment-worker/
├── scripts/
│ └── auto-comment-worker.py # 메인 워커
├── deploy/
│ └── auto-comment-worker.service # systemd 서비스
├── venv/ # Python 가상환경
└── logs/
 └── audit.log # 감사 로그

핵심 의존성

from flask import Flask, request, jsonify
from flask_limiter import Limiter
from flask_limiter.util import get_remote_address
from marshmallow import Schema, fields, validate, ValidationError

Flask: 경량 웹 프레임워크로 Webhook 엔드포인트 제공
Flask-Limiter: 속도 제한으로 남용 방지 (분당 10회)
marshmallow: 요청 스키마 검증으로 안전한 데이터 파싱

웹훅 엔드포인트

@app.route('/webhook', methods=['POST'])
@limiter.limit("10 per minute")
def github_webhook():
 """GitHub Webhook 수신"""
 # 1. 시그니처 검증
 signature = request.headers.get('X-Hub-Signature-256')
 if not verify_webhook_signature(request.data, signature):
 log_audit('SIGNATURE_INVALID', {'ip': request.remote_addr})
 return jsonify({'status': 'unauthorized'}), 401

 # 2. 요청 스키마 검증
 schema = WebhookSchema()
 try:
 payload = schema.load(request.json)
 except ValidationError as err:
 return jsonify({'status': 'invalid'}), 400

 # 3. 댓글 정보 추출 및 필터링
 comment = payload.get('comment', {})
 discussion = payload.get('discussion', {})
 original_author = comment.get('user', {}).get('login', '사용자')

 # 블로그 소유주의 댓글이면 무시
 if _is_blog_owner(original_author):
 return jsonify({'status': 'owner_comment_ignored'}), 200

 # AI가 생성한 댓글이면 무시 (무한 루프 방지)
 if _is_ai_generated_comment(comment.get('body', '')):
 return jsonify({'status': 'ai_comment_ignored'}), 200

 # 4. AI 응답 생성 및 게시
 discussion_graphql_id = get_discussion_graphql_id(
 repo_owner, repo_name, discussion_number
 )
 context = f"제목: {discussion_title}\n\n내용: {discussion_body}"
 reply = analyze_comment(context, comment_body)
 post_reply_graphql(discussion_graphql_id, comment_body, original_author, reply)

핵심 흐름은 4단계입니다:

시그니처 검증: HMAC-SHA256으로 요청이 GitHub에서 왔는지 확인
스키마 검증: marshmallow로 페이로드 구조 검증
필터링: 블로그 소유주와 AI 자신의 댓글을 무시 (무한 루프 방지)
응답: Claude Code로 AI 응답 생성 후 GraphQL API로 게시

무한 루프 방지

AI가 생성한 댓글에 다시 AI가 응답하면 무한 루프에 빠집니다. 이를 방지하기 위해 마커 기반 감지를 사용합니다:

def _is_ai_generated_comment(body: str) -> bool:
 """AI가 생성한 댓글인지 식별"""
 ai_markers = [
 '🤖 AI 어시스턴트',
 'AI 어시스턴트',
 'AgentForge',
 'Claude Code로 자동 생성',
 '자동 생성되었습니다'
 ]
 body_lower = body.lower()
 return any(marker.lower() in body_lower for marker in ai_markers)

AI 응답을 게시할 때 반드시 이 마커들 중 하나를 본문에 포함합니다:

body = f"""---
**🤖 AI 어시스턴트**

{safe_reply}

*이 댓글은 AgentForge + Claude Code로 자동 생성되었습니다.*
---
"""

Claude Code CLI 호출

Claude Code의 --print 모드를 사용하여 비대화형으로 AI 응답을 생성합니다:

def analyze_comment(context: str, comment: str) -> str:
 """AgentForge 설정으로 Claude Code 실행"""
 prompt = f"""## 블로그 포스트 문맥
{context[:2000]}

## 독자 댓글
{comment}

이 댓글에 대한 응답을 작성해주세요.
- 기술 블로그 어시스턴트로서 전문적이면서 친절하게
- 200자 이내로 간결하게
- 필요한 경우 추가 정보나 링크 제시
"""

 cmd = [
 CLAUDE_CODE_PATH,
 '--settings', AGENTFORGE_CONFIG,
 '--print', prompt
 ]

 result = run(cmd, capture_output=True, text=True, timeout=60)

 if result.returncode == 0 and result.stdout.strip():
 return result.stdout.strip()

 return "의견 감사합니다! 기술적인 부분에 대해 더 논의해보면 좋을 것 같습니다. 🙏"

--settings 플래그로 AgentForge 전용 설정 파일을 지정합니다. 이 설정 파일에서 모델, 토큰 제한 등을 관리할 수 있습니다.

--print 플래그는 Claude Code를 비대화형 모드로 실행하여 결과를 stdout으로 출력합니다. 대화형 모드와 달리 프롬프트-응답 한 번으로 종료됩니다.

GitHub GraphQL API 통합

giscus는 GitHub Discussions를 사용하므로, 응답도 GitHub GraphQL API로 게시해야 합니다.

Discussion GraphQL ID 조회:

def get_discussion_graphql_id(repo_owner, repo_name, discussion_number):
 query = """
 query($owner: String!, $name: String!, $number: Int!) {
 repository(owner: $owner, name: $name) {
 discussion(number: $number) {
 id
 }
 }
 }
 """
 variables = {
 "owner": repo_owner,
 "name": repo_name,
 "number": discussion_number
 }

 response = requests.post(
 GITHUB_API_URL,
 json={"query": query, "variables": variables},
 headers={
 "Authorization": f"Bearer {GITHUB_TOKEN}",
 "Content-Type": "application/json"
 },
 timeout=10
 )

 if response.status_code == 200:
 data = response.json()
 return data["data"]["repository"]["discussion"]["id"]
 return None

Webhook 페이로드에는 Discussion의 REST API ID만 포함됩니다. 하지만 댓글을 게시하려면 GraphQL Node ID가 필요합니다. 따라서 먼저 GraphQL 쿼리로 Discussion의 Node ID를 조회한 뒤, 이를 사용하여 댓글을 게시합니다.

응답 게시 (Mutation):

def post_reply_graphql(discussion_graphql_id, original_comment, original_author, reply):
 query = """
 mutation($discussionId: ID!, $body: String!) {
 addDiscussionComment(input: {
 discussionId: $discussionId, body: $body
 }) {
 comment { id, databaseId }
 }
 }
 """
 # ... (요청 전송)

addDiscussionComment mutation은 Discussion 전체에 새 댓글을 추가합니다. 특정 댓글에 대한 답글(reply)이 아니라 Discussion 레벨의 댓글입니다.

입력 Sanitization

사용자 댓글은 외부 입력이므로 반드시 sanitize합니다:

def sanitize_comment(body: str) -> str:
 """사용자 입력 sanitization"""
 if not body:
 return body
 body = re.sub(r'<[^>]+>', '', body) # HTML 태그 제거
 body = html.escape(body) # HTML 엔티티 이스케이프
 body = body[:1000] # 길이 제한
 return body

XSS 공격을 방지하기 위해 HTML 태그를 제거하고, 남은 특수 문자를 이스케이프하며, 길이를 1000자로 제한합니다.

감사 로그

보안 이벤트를 추적하기 위한 감사 로그를 남깁니다:

def log_audit(event_type: str, details: dict):
 """보안 이벤트 감사 로그 기록"""
 with open(AUDIT_LOG, 'a') as f:
 f.write(json.dumps({
 'timestamp': datetime.utcnow().isoformat(),
 'event': event_type,
 'details': details
 }) + '\n')

기록하는 이벤트 유형:

SIGNATURE_INVALID: 웹훅 시그니처 검증 실패
INVALID_PAYLOAD: 잘못된 요청 페이로드
WEBHOOK_RECEIVED: 웹훅 수신 성공
AI_RESPONSE_SENT: AI 응답 게시 완료

마무리

이번 1부에서는 giscus, GitHub Webhook, Flask 워커, Claude Code CLI, GitHub GraphQL API를 연결하는 전체 아키텍처와 핵심 구현 코드를 다뤘습니다.

다음 2부에서는 이 시스템의 보안 강화 — 파일 기반 인증 관리, 파일 권한 검증, HMAC-SHA256 시그니처 검증 등을 상세히 다룹니다.

이 글은 AgentForge 블로그 자동 댓글 시스템 시리즈의 1부입니다.

멀티모델 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 에이전트 팀 구성 경험을 정리한 것입니다.

서버 관리의 효율을 높이는 도구: Server Status Checker Skill 소개

Mon, 09 Mar 2026 00:30:00 +0900

서버 관리의 효율을 높이는 도구: Server Status Checker Skill 소개

관리하는 서버가 점점 늘어나고 있나요?

서버마다 일일이 SSH로 접속하여 상태를 확인하는 일은 시간 낭비입니다. 여러 서버의 CPU, 메모리, 디스크 사용량을 한눈에 파악할 수 있다면 업무 효율이 크게 향상될 것입니다.

저도 그런 문제를 겪었습니다. 그래서 만들었습니다.

문제: 서버 모니터링의 반복 작업

DevOps 엔지니어나 시스템 관리자라면 한 번쯤 겪는 상황입니다:

서버별 SSH 접속 반복
top, htop, df 명령어 일일이 실행
엑셀이나 노션에 수동으로 상태 기록
서버 증가시 마다 관리 스크립트 수정

이 과정은 시간 낭비이자, 실수를 유발할 수 있는 반복 작업입니다.

해결책: Server Status Checker Skill

Server Status Checker는 Claude Code용 스킬로, SSH config 파일을 기반으로 모든 서버의 상태를 병렬로 확인합니다.

주요 기능

기능	설명
SSH config 자동 파싱	`~/.ssh/config` 파일에서 서버 목록 자동 발견
실시간 상태 확인	CPU, Memory, Disk, Uptime, Load 정보 수집
병렬 연결	asyncssh로 빠른 상태 확인 (초 단위)
그룹별 분류	GCP, OCI, GitHub, Blog, Local 등으로 자동 분류
온라인/오프라인 상태	✓ / ✗ 로 직관적인 상태 표시

사용법

# 전체 서버 상태 확인
/server-status-checker

# 특정 서버만 확인
/server-status-checker --server mini01

# JSON 형식으로 출력
/server-status-checker --json

# 상세 에러 메시지
/server-status-checker --verbose

출력 예시

=== Server Status Report ===

[GCP 서버]
✗ gcp-ajou-ec1 - Offline (Authentication failed)
✗ gcp-fcoinfup-ec1 - Offline (Authentication failed)

[OCI Ajou]
✓ oci-ajou-ec1 - Online
 CPU: 15.2% | Memory: 62.3% | Disk: 45.8%
 Uptime: 15 days | Load: 1.23 1.45 1.38
 OS: Ubuntu 22.04 LTS

[로컬 서버]
✓ mini01 - Online
 CPU: 6.7% | Memory: 45.2% | Disk: 5.0%
 Uptime: 2 days | Load: 2.17 2.11 1.94
 OS: macOS 26.3.1

기술적 세부사항

SSH Config 파싱

~/.ssh/config 파일을 파싱하여 다음 정보를 자동 추출합니다:

Host (호스트명)
HostName (IP 주소 또는 도메인)
User (사용자명)
Port (포트번호)
IdentityFile (SSH 키 경로)

비동기 병렬 처리

Python asyncssh 라이브러리를 활용하여 모든 서버에 동시에 접속합니다:

async def check_server(host: str):
 # SSH 접속 및 명령 실행
 result = await asyncssh.connect(...)
 return status

30대의 서버를 순차적으로 확인하면 5분이 걸리지만, 병렬 처리시 30초 내에 완료됩니다.

그룹 자동 분류

서버 이름 패턴을 기반으로 자동 분류합니다:

그룹	패턴	예시
GCP	`gcp-` 접두사	gcp-ajou-ec1, gcp-fcoinfup-ec1
OCI Ajou	`oci-ajou-` 접두사	oci-ajou-ec1
OCI Fcoinfup	`oci-fcoinfup-` 접두사	oci-fcoinfup-ec1
GitHub	`github-as-` 접두사	github-as-actions
Blog	`blog`	blog
Local	`mini`, `mac`	mini01, macbook-pro

시스템 메트릭 수집

각 서버에서 다음 정보를 수집합니다:

Linux:

CPU: /proc/stat 또는 psutil.cpu_percent()
Memory: /proc/meminfo 또는 psutil.virtual_memory()
Disk: psutil.disk_usage()
Uptime: /proc/uptime 또는 psutil.boot_time()
Load: /proc/loadavg 또는 os.getloadavg()

macOS:

CPU: psutil.cpu_percent()
Memory: psutil.virtual_memory()
Disk: psutil.disk_usage()
Uptime: psutil.boot_time()
Load: os.getloadavg()

GitHub 공개

이 스킬은 오픈소스로 공개되어 있습니다.

🔗 GitHub: https://github.com/yarang/skill-server-status-checker

설치 방법

git clone https://github.com/yarang/skill-server-status-checker.git
cp -r skill-server-status-checker ~/.claude/skills/server-status-checker

비즈니스 가치

측면	개선 효과
시간 절약	서버 확인 시간 90% 단축 (5분 → 30초)
실시간 모니터링	즉각적인 서버 상태 파악
중앙화된 관리	SSH config 단일 파일로 모든 서버 관리
자동화	반복 작업 제거로 인적 실수 최소화

활용 사례

1. 일일 서버 건강 확인

매일 아침 /server-status-checker 명령 하나로 모든 서버 상태를 확인합니다.

2. 장애 대응

장애 발생시 즉시 오프라인 서버를 식별하고 조치를 취합니다.

3. 용량 계획

디스크 사용량 추이를 모니터링하여 미리 용량 확보를 계획합니다.

4. 성능 모니터링

CPU와 메모리 사용량을 추적하여 병목 지점을 파악합니다.

결론

Server Status Checker는 단순한 서버 상태 확인 도구가 아닙니다. DevOps 엔지니어와 시스템 관리자가 반복 작업에서 벗어나 핵심 업무에 집중할 수 있도록 돕는 생산성 도구입니다.

SSH config라는 표준화된 설정 파일을 활용하고, 병렬 처리를 통해 빠르게 결과를 제공합니다. 이제 서버 한 대 한 대에 접속할 필요 없이, 한 번의 명령으로 모든 서버의 건강 상태를 파악하세요.

AI와 자동화를 통해 시스템 관리의 효율성을 높이고, 우리는 더 중요한 문제에 집중할 수 있습니다.

관련 프로젝트:

domain-checker - 도메인 등록 가능 여부 확인 도구

태그: #DevOps #서버모니터링 #오픈소스 #Claude #AI #생산성 #SSH

영어 버전: English Version

개발자 생산성을 높이는 도구: Domain Checker Skill 소개

Mon, 09 Mar 2026 00:20:00 +0900

개발자 생산성을 높이는 도구: Domain Checker Skill 소개

새로운 프로젝트를 시작할 때 가장 먼저 고민하는 것은 무엇일까요? 바로 “도메인 이름"입니다.

가장 원하는 이름이 .com이나 .ai에 이미 등록되어 있다면? 그때마다 whois 사이트들을 일일이 방문하셨나요?

저도 그랬습니다. 그래서 만들었습니다.

문제: 도메인 검색의 반복 작업

스타트업 창업자나 개발자라면 한 번쯤 겪는 상황입니다:

원하는 도메인이 이미 등록됨
whois 사이트 10번 방문
엑셀에 수동으로 비교표 작성
대안 도메인명 머리로 고민

이 과정은 시간 낭비이자, 창의력을 갉아먹는 반복 작업입니다.

해결책: Domain Checker Skill

Domain Checker는 Claude Code용 스킬로, 도메인 등록 가능 여부를 실시간으로 확인하고 비용을 비교합니다.

주요 기능

기능	설명
빠른 병렬 조회	8개 주요 TLD를 동시에 확인
3단계 폴백	RDAP → whois → DNS (신뢰성 보장)
대안 자동 추천	원하는 도메인이 모두 등록된 경우 대안 자동 탐색
비용 비교표	TLD별 연간 비용 및 최소 계약 기간 표시
마크다운 보고서	상세 결과 보고서 자동 생성

사용법

# 기본 조회
/domain-checker myapp

# 결과 예시
🔍 도메인 검색: myapp*
 🔴 myapp.com (~$13/년)
 🔴 myapp.ai (~$75/년)
 🟢 myapp.io (~$38/년) ← 등록 가능!

조회 대상 TLD

TLD	연간 비용	최소 계약	특징
.com	~$13	1년	범용, 최고 인지도
.ai	~$75	2년	AI 프로젝트 특화
.io	~$38	1년	테크 스타트업 선호
.net	~$14	1년	.com 대안
.co	~$28	1년	스타트업 인기
.dev	~$13	1년	개발자 타겟
.tech	~$12	1년	기술 관련, 저가
.app	~$14	1년	앱 서비스 특화

기술적 세부사항

3단계 폴백 메커니즘

1. RDAP API → 가장 정확, 빠름
2. whois CLI → RDAP 실패 시 폴백
3. DNS NS 조회 → 최후 수단

대안 도메인 추천

모든 주요 도메인이 등록된 경우 자동으로 대안을 탐색합니다:

탐색 패턴:

접두사: get, try, use, go, my, the
접미사: hq, app, hub, lab, pro

예시: myapp → getmyapp.ai, myapp-hq.io, trymyapp.com

비동기 병렬 처리

Python 비동기 프로그래밍을 활용하여 8개 TLD를 동시에 조회하므로 2초 내에 결과를 확인할 수 있습니다.

실제 사용 예시

/domain-checker ai

결과:

# 🌐 도메인 검색 보고서: `ai`

## 요약
| 항목 | 결과 |
|------|------|
| 검색 도메인 | `ai` |
| 조회 TLD 수 | 8개 |
| 🟢 등록 가능 | **0개** |
| 🔴 이미 등록됨 | 8개 |

## 💡 대안 도메인명 추천
`ai`의 변형 중 등록 가능한 도메인입니다.

| 도메인 | 연간 비용 | 비고 |
|--------|-----------|------|
| `ai-hq.ai` | ~$75/년 | AI 특화 (최소 2년 계약) |
| `ai-hq.io` | ~$38/년 | 테크 스타트업 선호 |

GitHub 공개

이 스킬은 오픈소스로 공개되어 있습니다.

🔗 GitHub: https://github.com/yarang/skill-domain-checker

설치 방법

git clone https://github.com/yarang/skill-domain-checker.git
cp -r skill-domain-checker ~/.claude/skills/domain-checker

비즈니스 가치

측면	개선 효과
시간 절약	도메인 검색 시간 90% 단축 (10분 → 1분 이내)
비용 효율	TLD별 비교로 최적 선택 지원
문서화	자동 생성된 보고서로 팀 공유 용이
생산성	반복 작업 자동화로 핵심 문제 집중

결론

Domain Checker는 단순한 도메인 검색 도구가 아닙니다. 개발자와 창업가가 반복 작업에서 벗어나 진짜 중요한 문제에 집중할 수 있도록 돕는 생산성 도구입니다.

AI와 자동화를 통해 일상의 작은 불편함을 해소하고, 우리는 더 큰 가치를 창출할 수 있습니다.

관련 프로젝트:

server-status-checker - SSH config 기반 서버 상태 확인 도구

영어 버전: 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

[LLM] 프롬프트 잘 작성하는 방법

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

들어가며

LLM(Large Language Model)을 효과적으로 활용하기 위해서는 좋은 프롬프트를 작성하는 것이 필수적입니다. 이 글에서는 프롬프트 엔지니어링의 핵심 원칙과 실전 패턴을 정리합니다.

좋은 프롬프트의 핵심 원칙

1. 명확성 (Clarity)

모호한 표현을 피하고 구체적으로 작성하세요.

나쁜 예:

좋은 코드를 작성해줘

좋은 예:

Python으로 이진 탐색 트리를 구현해줘.
insert, search, delete 메서드를 포함하고,
시간 복잡도는 O(log n)이어야 해.

2. 컨텍스트 제공 (Context)

LLM이 작업을 이해하는 데 필요한 배경 정보를 제공하세요.

나는 React 초보자야.
useState와 useEffect의 차이점을 예제 코드와 함께 설명해줘.

3. 역할 부여 (Role Playing)

특정 전문가의 관점에서 응답하도록 설정하세요.

당신은 10년 경력의 시니어 백엔드 개발자입니다.
마이크로서비스 아키텍처의 장단점을 설명해주세요.

4. 출력 형식 지정 (Output Format)

원하는 응답 형태를 명시하세요.

다음 내용을 마크다운 표로 정리해줘:
- 언어별 특징
- 장단점
- 사용 사례

프롬프트 패턴

Chain of Thought (사고 과정)

복잡한 문제는 단계별로 생각하도록 유도하세요.

이 문제를 단계별로 생각해보자:
1. 먼저 문제를 분석하고
2. 해결 방법을 고민한 후
3. 최종 답변을 작성해

Few-Shot Learning

예시를 제공하여 원하는 형태를 학습시키세요.

다음 형식으로 요약해줘:

입력: "오늘 날씨가 좋다"
출력: 긍정, 날씨

입력: "회의가 너무 길었다"
출력: 부정, 업무

입력: "새로운 프로젝트를 시작했다"
출력: ?

구조화된 프롬프트

복잡한 작업은 섹션으로 나누어 작성하세요.

## 목표
사용자 인증 API를 설계한다

## 요구사항
- JWT 토큰 사용
- Refresh token 로테이션
- Rate limiting 적용

## 출력
1. API 엔드포인트 명세
2. 시퀀스 다이어그램
3. 보안 고려사항

자주 하는 실수

실수	문제점	해결책
너무 긴 프롬프트	핵심이 흐려짐	핵심만 간결하게
모호한 지시	예상과 다른 결과	구체적인 예시 제공
컨텍스트 누락	부정확한 답변	배경 정보 추가
형식 미지정	가독성 저하	출력 형식 명시

실전 체크리스트

프롬프트 작성 전 확인하세요:

목표가 명확한가?
필요한 컨텍스트를 포함했는가?
출력 형식을 지정했는가?
제약사항을 명시했는가?
예시가 도움이 될 것인가?

마무리

좋은 프롬프트는 명확하고, 구체적이며, 필요한 컨텍스트를 제공합니다. 연습을 통해 프롬프트 작성 실력을 향상시키세요.

참고 자료

영어 버전: English Version

Ai on Yarang's Tech Lair

RubyLLM: 레일러스를 위한 통합 AI 인터페이스 가이드

RubyLLM: 레일러스를 위한 통합 AI 인터페이스 가이드

RubyLLM이란?

프로젝트 설정

기본 사용법: Chat 인터페이스

1. OpenAI GPT-4o 호출

2. 모델 간 간편 전환 (Vendor Lock-in 방지)

실전 활용: 스트리밍 응답 구현하기

결론: Ruby 생태계의 AI 개발 트렌드

참고 자료

Rust 기반 MCP 서버 구축하기: ZeroClaw 아키텍처 활용

Rust 기반 MCP 서버 구축하기: ZeroClaw 아키텍처 활용

1. MCP 서버의 핵심 요구사항

2. 아키텍처 설계: ZeroClaw 스타일

3. 실전 코드 예제

3.1. 의존성 설정 (Cargo.toml)

3.2. 핸들러 트레이트 정의

3.3. 로그 읽기 도구 구현

3.4. 메인 루프 및 JSON-RPC 서버

4. 최적화 및 배포 고려사항

5. 결론

AI 에이전트 신뢰성 강화: Forge Guardrails와 MCP 통합 가이드

AI 에이전트 신뢰성 강화: Forge Guardrails와 MCP 통합 가이드

문제 정의: 자율성의 딜레마

솔루션: Guardrails 패턴 적용

아키텍처 개요

실전 코드 예제: Rust로 구현하는 안전장치

1. 검증 로직 구현하기

2. 에이전트 루프에 통합하기

효과 및 전망

Computer Use API vs Structured Output: 비용 효율적인 LLM 구현 전략

Computer Use API vs Structured Output: 비용 효율적인 LLM 구현 전략

1. 비용 격차의 원인 분석

Computer Use (GUI 기반 접근)

Structured Output (API 기반 접근)

2. 실용적인 해결책: 하이브리드 아키텍처

전략: 도구 사용 우선순위

3. 코드 예제: 비용 최적화된 Agent 구현

시나리오: 블로그 게시글 자동 발행

구조적 접근 (Structured Output + API)

비구조적 접근 (Computer Use 시뮬레이션 - 비용 상승)

4. ZeroClaw 및 MCP 아키텍처 적용 가이드

5. 결론

개발 생산성 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. 결론: 비용과 성능의 균형

MCP 서버 시작하기: Claude Code와 통합하는 첫 번째 도구 만들기

MCP 서버 시작하기: Claude Code와 통합하는 첫 번째 도구 만들기

MCP란 무엇인가?

기본 MCP 서버 구조

실전 예제: 간단한 계산기 MCP 서버

Claude Code 설정

리소스 제공하기

보안 고려사항

배포 및 테스트

다음 단계

참고 자료

블로그 AI 자동 댓글 시스템 구축기 (1/3) — 아키텍처와 구현

개요

시스템 아키텍처

전체 데이터 흐름

구성 요소

giscus 설정

GitHub Webhook 구성

Flask 워커 구현

프로젝트 구조

핵심 의존성

웹훅 엔드포인트

무한 루프 방지

Claude Code CLI 호출

GitHub GraphQL API 통합

3.1. 의존성 설정 (`Cargo.toml`)

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

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