LangChain 팀이 Claude Code를 특정 라이브러리에 특화된 코딩 에이전트로 만들기 위해 실험한 결과, 압축된 가이드 문서(Claude.md)가 단순한 문서 접근 도구보다 훨씬 효과적이라는 놀라운 사실을 발견했습니다.
코딩 에이전트의 딜레마
ChatGPT나 Claude 같은 AI 코딩 도구들은 React나 Django처럼 유명한 라이브러리 코드를 작성할 때는 정말 뛰어납니다. 학습 데이터에 충분한 예시가 있기 때문이죠. 하지만 커스텀 라이브러리나 내부 API, 최신 버전의 프레임워크를 만나면 갑자기 헤맵니다.
이 문제는 라이브러리 개발팀에게는 더욱 절실합니다. LangChain과 LangGraph를 개발하는 LangChain 팀 역시 마찬가지였죠. 자신들이 만든 라이브러리의 코드를 Claude Code가 제대로 작성할 수 있도록 만들고 싶었습니다.
네 가지 실험 설정
LangChain 팀은 Claude 4 Sonnet을 기반으로 네 가지 다른 구성을 테스트했습니다.
Claude Vanilla: 기본 설정 그대로의 Claude Code
Claude + MCP: MCPDoc 서버를 연결해 문서에 접근할 수 있는 버전
Claude + Claude.md: LangGraph 전용 가이드 파일을 포함한 버전
Claude + MCP + Claude.md: 가이드 파일과 문서 서버를 모두 제공한 버전
가장 흥미로운 것은 MCP 서버의 역할입니다. 이 도구는 llms.txt 파일을 통해 라이브러리 문서에 직접 접근할 수 있게 해줍니다. 언뜻 보면 더 많은 정보에 접근할 수 있으니 당연히 성능이 좋을 것 같죠.
Claude.md의 비밀
하지만 결과는 예상과 달랐습니다. Claude.md 파일이 포함된 설정이 단순한 MCP 서버보다 훨씬 좋은 성과를 냈습니다. 이 파일에는 무엇이 들어있었을까요?
LangGraph 라이브러리 사용법을 압축적으로 정리한 내용이었습니다. 프로젝트 구조 요구사항부터 시작해서 create_react_agent나 supervisor 패턴 같은 핵심 기능의 샘플 코드까지 포함되어 있었죠.
특히 중요했던 부분은 함정과 안티패턴에 대한 가이드였습니다. Claude가 자주 실수하는 부분들을 미리 짚어준 거예요. 잘못된 interrupt() 사용법이나 타입 가정 오류 같은 것들 말이죠.
왜 압축된 정보가 더 효과적일까?
실험 결과를 보면 흥미로운 패턴을 발견할 수 있습니다. MCP 도구만 있을 때는 Claude가 문서를 한두 번만 조회하고 멈춰버렸습니다. 표면적인 설명만 보고 더 깊이 파지 않은 거죠.
반면 Claude.md가 있을 때는 훨씬 적극적으로 추가 정보를 찾으려 했습니다. 웹 검색도 더 자주 사용했고요. 이는 가이드 파일의 각 섹션 끝에 추가 참고용 URL을 적어둔 덕분이었습니다.
결국 Claude.md + MCP 조합이 가장 좋은 결과를 만들어냈습니다. 기본 지식을 제공하면서 동시에 필요할 때 더 자세한 정보에 접근할 수 있게 한 거죠.
실제 성능은 어땠을까?
팀은 세 가지 실제 태스크로 성능을 측정했습니다. Text-to-SQL 에이전트 구축, 회사 정보 리서치 에이전트 만들기, 그리고 기존 메모리 에이전트 수정하기였습니다.
각 태스크마다 연기 테스트(기본 기능 확인), 요구사항 테스트(특정 기능 검증), 그리고 코드 품질 평가(LLM-as-a-Judge 사용)를 진행했습니다.
결과는 명확했습니다. Claude + Claude.md + MCP 구성이 가장 높은 점수를 받았고, 흥미롭게도 Claude + Claude.md만으로도 Claude + MCP보다 좋은 성능을 보였습니다.
실무진을 위한 가이드
이 연구 결과를 바탕으로 여러분의 프로젝트에 적용할 수 있는 실용적인 방법들을 정리해보겠습니다.
1. Claude.md부터 시작하세요
가장 비용 효율적이면서도 효과적인 방법입니다. 작성할 때 이런 내용들을 포함하세요.
핵심 개념과 기능: 라이브러리의 독특한 기능과 일반적인 사용 패턴
샘플 코드: 자주 사용되는 기능들의 완전한 예시 코드
함정과 주의사항: AI가 자주 실수하는 부분들을 미리 경고
참고 문서 링크: 각 섹션 끝에 더 자세한 정보를 찾을 수 있는 URL 추가
예를 들어 LangGraph의 경우 비동기 작업이나 Streamlit 통합 시 asyncio 처리 방법을 상세히 설명했습니다. 이런 부분에서 Claude가 자주 실패했거든요.
2. 문서 도구는 보조 수단으로
MCPDoc 같은 문서 접근 도구는 분명 도움이 됩니다. 하지만 만능이 아닙니다. 큰 llms.txt 파일을 그대로 던져주면 오히려 컨텍스트 창이 꽉 차서 비용만 늘어날 수 있어요.
더 스마트한 검색 기능을 구현하는 것이 좋습니다. 전체 문서 내용이 아니라 관련 있는 부분만 가져오는 방식으로요.
3. 실패 사례를 분석하세요
실제로 돌려보고 실패한 케이스들을 수집해서 가이드에 반영하는 것이 중요합니다. LangChain 팀도 반복적으로 실패하는 패턴들을 발견하고 Claude.md에 추가했거든요.
특히 디버깅 방법이나 개발 서버 설정 같은 실무적인 부분도 포함시키세요. 이런 부분에서 에러가 나면 Claude Code가 요청을 제대로 보내서 결과를 확인할 수 있습니다.
MCPDoc 서버 직접 사용해보기
LangChain 팀이 개발한 MCPDoc 서버는 오픈소스로 공개되어 있습니다. Cursor, Windsurf, Claude Desktop, Claude Code 등 다양한 IDE에서 사용할 수 있어요.
설치는 간단합니다. uv가 설치되어 있다면 다음 명령어로 바로 테스트할 수 있습니다:
uvx --from mcpdoc mcpdoc \
--urls "LangGraph:https://langchain-ai.github.io/langgraph/llms.txt" \
--transport sse \
--port 8082 \
--host localhost각 IDE별로 설정하는 방법도 자세히 문서화되어 있으니 관심 있으신 분들은 직접 시도해보세요.
결론
이 연구가 보여주는 핵심 메시지는 명확합니다. AI에게 모든 정보를 다 던져주는 것보다는, 잘 정리된 핵심 가이드를 제공하는 것이 훨씬 효과적이라는 겁니다.
내부 라이브러리나 커스텀 프레임워크를 다루는 개발팀이라면 Claude.md 파일 하나만 제대로 만들어도 코딩 에이전트의 성능을 크게 향상시킬 수 있습니다. 물론 문서 접근 도구와 결합하면 더욱 강력해지고요.
참고자료:
Comments