에이전트 설계 + LangChain·LangGraph 비교 — Claude Code 가 같은 문제를 어떻게 푸는가

에이전트 설계 + 효율적 활용 + LangChain/LangGraph 비교

작성일: 2026-04-27

1. 공용 에이전트 설계

1.1 두 종류의 에이전트

종류	위치	특징	예시
역할형 (role-based)	~/.claude/agents/ 전역	도메인 비종속	PM, Reviewer, Refactor, Meta
도메인형 (domain-bound)	<project>/.claude/agents/	그 환경에 강하게 묶임	DBA(PG), Ops(systemd)

interpark의 8개를 분류하면:
- 역할형: PM, Reviewer, Refactor, Meta → 전역 후보
- 반-도메인 (골격 공통, 명령은 다름): Dev, Debug → 골격은 전역, 구체는 CLAUDE.md 위임
- 순수 도메인: DBA, Ops → 프로젝트 내부

1.2 공용 에이전트 작성 5원칙

1. 절대 경로/명령어를 박지 말 것 — tail -f /home/jai/cron_sh/... 대신 "프로젝트의 주 로그 파일을 tail" 같이 추상화하고, 구체 경로는 CLAUDE.md로 위임.
2. 입출력 인터페이스 명시 — 보고서 표준 양식이 있어야 다른 에이전트가 결과를 읽을 수 있음.
3. 호출 시점/비호출 시점 명시 — 메인이 라우팅하기 쉬워짐.
4. 권한 좁히기 — Reviewer는 Edit/Write 빼고 Read/Grep만. 권한 분리가 안전 장치.
5. 자기완결 컨텍스트 — 에이전트는 메인 대화를 모름. 호출 시 모든 정보 명시.

1.3 전역 + 프로젝트 덮어쓰기 패턴

~/.claude/agents/dev.md                   ← 일반 Dev (간결한 원칙만)
<project>/.claude/agents/dev.md           ← 프로젝트 전용 (검증 명령 추가)

가까운 쪽이 우선. 프로젝트 dev.md가 없으면 전역 fallback.

2. 효율적 활용

2.1 모드 시스템 — 비용 절약 1순위

모드	호출 수	적용
Direct	0	한 줄 수정, 단순 조회
Light	1	단일 파일
Full	3~6	다중 파일/스키마

요청 받자마자 모드 선언 + 사용자에게 알리기. 사용자가 정정할 기회 제공.

2.2 병렬 호출

서로 의존성 없는 조사는 한 메시지에 여러 Agent 호출 동시 발사. 출력 A를 봐야 입력 B가 정해지면 순차, 아니면 병렬.

2.3 컨텍스트 격리

에이전트는 별도 컨텍스트 윈도우에서 동작. 메인은 최종 보고서만 받음.
- 거대 로그 분석 → 에이전트 위임 → 메인은 200단어 요약만
- 광범위 코드 탐색 → Explore 에이전트 → 핵심 경로만

자문: "메인이 직접 봐야 하나, 에이전트 요약으로 충분한가"

2.4 상태를 파일로 외부화

에이전트끼리 직접 대화 못 함 → 파일이 메시지함:

PM   → work/0427_xxx/PLAN.md
Dev  → reports/dev.md (PLAN 읽고 작업)
Meta → learnings/0427_xxx.md (PLAN + reports 읽고 정리)

매번 새 컨텍스트지만 파일을 통해 비동기 협업. LangGraph의 "상태 그래프"가 푸는 문제를 마크다운 파일로 해결.

2.5 재사용 우선

새 에이전트 만들기 전 자문: "기존 Refactor/Debug에 호출 시점 한 줄 추가하면 안 되나?" 에이전트 수가 늘면 라우팅이 어려워지고 사용자도 헷갈림.

3. LangChain / LangGraph 같은 외부 프레임워크

3.1 정의

도구	한 줄 요약
LangChain	LLM 호출을 체인으로 엮는 라이브러리. 프롬프트/도구/메모리/벡터검색 표준화
LangGraph	상태 그래프 엔진. 노드(에이전트) + 엣지(분기) + 상태(메모리)로 멀티 에이전트 흐름 정의
유사군	LlamaIndex (RAG), CrewAI, AutoGen (MS)

3.2 장점

1. 모델 비종속 — OpenAI/Anthropic/Google/로컬 통합
2. 세밀한 제어 — 코드로 분기 로직 정의
3. 상태 영속화 — PG/Redis 백엔드, 며칠짜리 잡 가능
4. 자체 호스팅 — 인프라/데이터 통제
5. 에코시스템 — 벡터DB, 옵저버빌리티(LangSmith) 묶음
6. 백엔드 통합 — FastAPI 같은 서비스 코드 안에서 호출하기 좋음

3.3 단점

1. 추상화 폭발 — Runnable, Chain, LCEL 등 자체 용어 학습 곡선
2. 버전 격변 — v0.1 → v0.2 API 갈아엎음. production 의존으로 부담
3. 디버깅 어려움 — 추상화 레이어 多, 실패 추적 어려움
4. 모델 특화 기능 손실 — Claude의 prompt caching, extended thinking, vision이 일반화에서 깎임
5. 운영 부담 — 자체 호스팅 시 인프라/모니터링 책임
6. 과한 무게 — 단일 작업/단일 모델이면 SDK 직접 호출이 빠르고 명확

3.4 언제 합당한가

• ✅ 사용자 향 제품 백엔드에 LLM 내장 (FastAPI/Next.js)
• ✅ 여러 모델 동시 운영 (가격 비교, 폴백, 라우팅)
• ✅ 명시적 상태 머신 (며칠짜리 승인 흐름 등)
• ✅ 자체 호스팅 강제 환경 (보안/규제)
• ❌ 개발 도구로 LLM 사용 → Claude Code가 압도적
• ❌ markdown으로 충분한 워크플로우

4. Claude Code의 자체 해결책 (외부 도구 vs Claude Code)

LangChain/Graph는 라이브러리로, Claude Code는 모델/CLI/프로토콜 레벨에서 같은 문제를 해결.

문제	외부 도구	Claude Code
도구 호출	Tool 추상, JSON schema 수동	API 레벨 native tool use, MCP 표준
멀티 에이전트	LangGraph 상태 그래프, 코드 작성	Agent 도구 + markdown + 파일 핸드오프
장기 메모리	Memory + 외부 벡터DB	CLAUDE.md, 메모리 시스템, prompt cache
워크플로우 자동화	Chain 정의 → 실행	Slash commands, Skills, Hooks
재사용 컴포넌트	PyPI 패키지	Plugins (.claude 묶음 배포)
프롬프트 캐싱	캐시 키 직접 관리	API 레벨 자동 캐싱
파일/코드 조작	Tool 직접 정의	Read/Edit/Write/Grep/Bash 빌트인
컨텍스트 한계	직접 자르기/요약	자동 압축, sub-agent 격리
권한/안전	직접 sandbox	settings allowlist, hooks 게이팅
상태 저장	DB 백엔드	파일 시스템 + git

4.1 핵심 통찰

LangChain/Graph는 "임의의 LLM을 어떻게든 일하게 만드는 라이브러리".
Claude Code는 "Anthropic 모델 + 표준 디렉토리 + 표준 프로토콜".

→ LangGraph 100줄 Python = Claude Code 마크다운 한 페이지.
→ 대신 LangGraph는 모델 자유도/운영 통제권. Claude Code는 Anthropic 모델 위주.

4.2 MCP의 의미

• 문제: 모든 LLM/에이전트 도구가 외부 시스템(DB/API/파일) 연결을 자기 식으로 정의 → 표준 부재
• LangChain: 자기 플러그인 시스템 (langchain-community)
• Anthropic: MCP 오픈 프로토콜 공개 → 클라이언트(Claude/IDE/타사)가 어느 MCP 서버든 연결

MCP는 langchain-tools/OpenAI plugins 같은 폐쇄 표준이 아니라 공통 표준을 노림. 장기적으로 가장 큰 차이가 될 가능성.

연관 개념

• 컨벤션 over 컨피규레이션 (Rails 철학)
• Unix 파이프 (작은 도구 + 표준 인터페이스 = 무한 조합)
• LSP ↔ MCP (둘 다 IDE/클라이언트가 다양한 백엔드를 일관 인터페이스로 쓰게 함)
• Actor 모델 (메시지 = 파일, 액터 = 에이전트)