🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

이 글은 Claude Code를 LangGraph·LangChain 같은 도메인 특화 라이브러리에 더 잘 맞추기 위해 실험한 설정들을 비교하고, 압축된 지침 파일과 필요 시 문서를 조회하는 도구를 함께 쓰는 방식이 가장 좋은 결과를 냈다고 설명한다.

📌 핵심 요약

• 일반적인 코딩 에이전트는 널리 쓰이는 라이브러리 코드 생성에는 강하지만, 커스텀 라이브러리·새 버전·내부 API·니치 프레임워크처럼 학습 데이터가 적은 영역에서는 성능이 떨어진다.
• LangChain 팀은 Claude Code가 LangGraph와 LangChain 코드를 더 잘 작성하도록 만들기 위해 기본 Claude, MCP 문서 도구 연결, Claude.md 지침 파일, Claude.md와 MCP 조합의 네 가지 구성을 실험했다.
• 단순히 원문 문서나 llms.txt를 많이 제공하는 방식은 기대만큼 효과적이지 않았고, 오히려 컨텍스트 창을 빠르게 채우며 에이전트가 중요한 정보를 가려내기 어렵게 만들었다.
• 가장 큰 효과는 핵심 개념, 구현 패턴, 흔한 실수, 디버깅 지침을 압축해 담은 Claude.md에서 나왔으며, 여기에 MCPDoc 문서 조회 도구를 결합했을 때 가장 강한 결과가 나왔다.
• 평가에는 스모크 테스트, 작업 요구사항 테스트, LLM-as-a-Judge 기반 코드 품질 평가가 함께 사용됐고, 결과는 기능 동작뿐 아니라 설계 선택과 프레임워크 관례 준수까지 반영했다.

🧩 주요 포인트

1. 일반적인 코딩 에이전트는 널리 쓰이는 라이브러리 코드 생성에는 강하지만, 커스텀 라이브러리·새 버전·내부 API·니치 프레임워크처럼 학습 데이터가 적은 영역에서는 성능이 떨어진다.
2. LangChain 팀은 Claude Code가 LangGraph와 LangChain 코드를 더 잘 작성하도록 만들기 위해 기본 Claude, MCP 문서 도구 연결, Claude.md 지침 파일, Claude.md와 MCP 조합의 네 가지 구성을 실험했다.
3. 단순히 원문 문서나 llms.txt를 많이 제공하는 방식은 기대만큼 효과적이지 않았고, 오히려 컨텍스트 창을 빠르게 채우며 에이전트가 중요한 정보를 가려내기 어렵게 만들었다.
4. 가장 큰 효과는 핵심 개념, 구현 패턴, 흔한 실수, 디버깅 지침을 압축해 담은 Claude.md에서 나왔으며, 여기에 MCPDoc 문서 조회 도구를 결합했을 때 가장 강한 결과가 나왔다.
5. 평가에는 스모크 테스트, 작업 요구사항 테스트, LLM-as-a-Judge 기반 코드 품질 평가가 함께 사용됐고, 결과는 기능 동작뿐 아니라 설계 선택과 프레임워크 관례 준수까지 반영했다.

🧠 상세 정리

1. 도메인 특화 코딩 에이전트가 필요한 이유

글은 코딩 에이전트가 대중적인 라이브러리에는 강하지만, 커스텀 라이브러리나 최신 버전, 내부 API, 니치 프레임워크에서는 충분히 잘 작동하지 않는다는 문제에서 출발한다. 이는 도메인 특화 라이브러리나 기업 내부 코드베이스를 다루는 팀에게 직접적인 장애가 된다. LangChain 팀은 LangGraph와 LangChain을 개발하는 입장에서, Claude Code가 해당 라이브러리의 관례와 추상화를 더 잘 이해하고 올바른 코드를 생성하도록 만드는 방법을 실험했다. 핵심 결론은 원문 문서를 그대로 많이 주는 것보다, 고품질로 압축된 기본 지식과 필요할 때 세부 문서를 조회할 수 있는 도구를 결합하는 방식이 가장 효과적이었다는 것이다.

2. 실험한 네 가지 Claude Code 구성

실험은 Claude 4 Sonnet을 일관된 모델로 사용해 네 가지 Claude Code 구성을 비교하는 방식으로 진행됐다. 첫 번째는 아무 수정 없이 사용하는 기본 Claude Code였고, 두 번째는 문서 접근을 위해 MCPDoc 서버를 연결한 Claude + MCP 구성이었다. 세 번째는 LangGraph에 특화된 상세 지침 파일인 Claude.md를 제공한 구성이었으며, 네 번째는 Claude.md와 MCPDoc 서버를 모두 제공한 조합이었다. 이 비교 구조는 단순 도구 연결, 압축된 지침, 그리고 두 방식의 결합이 각각 코드 생성 성능과 품질에 어떤 차이를 만드는지 확인하기 위한 것이다.

3. MCPDoc 서버와 문서 접근 방식

팀은 코딩 에이전트가 임의의 라이브러리 문서에 접근할 수 있도록 MCPDoc 서버를 만들었다. 이 오픈소스 MCP 서버는 사용 가능한 llms.txt 파일 URL을 알려주는 list_doc_sources와 특정 llms.txt 파일을 읽는 fetch_docs라는 두 도구를 제공한다. 실험에서는 LangGraph와 LangChain의 Python 및 JavaScript 문서에 접근할 수 있도록 구성했으며, 다른 사용자는 자신이 쓰는 라이브러리의 llms.txt URL을 MCP 설정에 넣어 같은 방식을 적용할 수 있다. 다만 결과적으로 문서 접근 도구만 제공하는 방식은 충분하지 않았고, 문서가 많을수록 컨텍스트가 빠르게 차는 문제가 드러났다.

4. Claude.md에 담은 압축 지식의 역할

Claude.md는 LangGraph 라이브러리 가이드로 작성됐으며, 새 프로젝트를 시작할 때 특히 중요한 정보를 압축해 담는 역할을 했다. 여기에는 파일을 새로 만들기 전에 코드베이스를 검색해야 한다는 요구, 올바른 export 패턴, 배포 모범 사례처럼 프로젝트 구조와 관련된 지침이 포함됐다. 또한 create_react_agent, supervisor 패턴, dynamic handoff를 위한 swarm 패턴 등 단일 에이전트와 멀티 에이전트 시스템을 만들 때 필요한 기본 구성 요소의 예시 코드도 들어갔다. 스트리밍과 human-in-the-loop처럼 LLM이 자주 어려워한 구현에는 더 자세한 가이드가 추가됐다.

5. 실패 패턴과 안티패턴을 지침에 반영한 방식

글은 Claude.md에서 특히 가치 있었던 부분으로 흔한 실수와 안티패턴을 체계적으로 정리한 점을 강조한다. 예를 들어 잘못된 interrupt() 사용, 틀린 상태 업데이트 패턴, 타입 가정 오류, 지나치게 복잡한 구현 같은 문제가 포함됐다. 이런 실수는 LLM이 오래된 라이브러리 사용법을 끌어오거나 다른 프레임워크의 패턴과 혼동하면서 자주 발생했다고 설명한다. Claude.md에는 구조화 출력 검증, 올바른 메시지 처리, 프레임워크 통합 디버깅 패턴 같은 LangGraph 특화 코딩 표준도 포함됐고, 각 섹션 끝에는 추가 탐색을 위한 문서 URL과 탐색 지침이 붙었다.

6. 평가 프레임워크: 기능보다 코드 품질까지 측정

평가의 목표는 단순히 코드가 동작하는지를 넘어서 무엇이 코드 품질에 가장 크게 기여하는지 측정하는 것이었다. 글은 Pass@k 같은 일반 지표가 기능성은 잡아내지만, 특정 맥락의 모범 사례나 설계 품질까지 반영하기 어렵다고 본다. 그래서 작업별 평가 하네스를 만들어 기본 동작, 작업 요구사항, 코드 품질과 구현 방식을 함께 확인했다. 스모크 테스트는 컴파일 여부, .invoke() 메서드 노출, 예상 입력 상태 처리, AIMessage 같은 예상 출력 구조 반환을 확인했고, 작업 요구사항 테스트는 배포 설정 파일, 외부 API 요청, 작업별 단위 테스트 등을 검증했다.

7. LLM-as-a-Judge 기반 코드 품질 평가

코드 품질과 구현 평가는 이진 테스트로 포착하기 어려운 요소를 보기 위해 LLM-as-a-Judge를 사용했다. 팀은 각 작업에 대해 전문가가 작성한 코드를 검토하고, 작업별 루브릭을 만든 뒤 Claude Sonnet 4를 temperature 0으로 설정해 생성 코드를 평가했다. 객관 체크는 특정 노드의 존재, 올바른 그래프 구조, 모듈 분리, 테스트 파일 부재 같은 사실을 boolean으로 판단하고 가중합으로 점수를 냈다. 주관 평가는 전문가 코드와 사람의 컴파일·런타임 오류 주석을 참고해 정확성 위반과 품질 우려를 critical, major, minor 등 심각도별로 분류하고, 심각도별 벌점을 빼는 방식으로 점수를 계산했다.

8. 결과와 핵심 교훈

결과에서 가장 흥미로운 점은 Claude.md만 제공한 구성이 MCP만 제공한 구성보다 더 좋은 성과를 냈다는 것이다. MCP 서버가 더 많은 문서를 제공할 수 있었음에도, 트레이스상 Claude가 MCP 도구를 기대만큼 자주 호출하지 않았고, 여러 연결 문서가 필요한 작업에서도 대개 한 번만 호출한 뒤 표면적인 설명에 머무르는 경우가 많았다. 반면 Claude.md와 MCP를 함께 제공하면 Claude.md의 섹션별 참조 URL과 탐색 지침이 도구 사용을 더 잘 유도해 문서를 더 효과적으로 읽게 했다. MCP 단독도 점수를 약 10%포인트 높이는 데 도움이 됐지만, 작업 완수와 코드 품질에는 핵심 개념·주의점·원칙을 담은 Claude.md의 영향이 더 컸고, 최종적으로는 Claude.md와 MCP 조합이 가장 강한 결과를 보였다.

🧾 핵심 주장 / 시사점

• 도메인 특화 코딩 에이전트의 성능은 문서 접근권 자체보다, 무엇이 중요한지 먼저 알려주는 압축된 방향성에 크게 좌우된다.
• Claude.md나 Agents.md 같은 지침 파일은 단순 사용법 모음이 아니라 반복 실패 사례, 안티패턴, 디버깅 절차를 축적하는 운영 자산으로 설계할 때 효과가 커진다.
• 문서 도구는 단독으로 쓰기보다 핵심 가이드와 함께 배치해야 하며, 특히 방대한 문서를 그대로 넣는 방식은 비용과 컨텍스트 효율 측면에서 불리할 수 있다.

✅ 액션 아이템

• 도메인 특화 라이브러리에서 성능이 약한 커스텀·내부 API·신규 버전 구간을 우선 대상으로 정의한다.
• 원문 문서나 llms.txt 대량 제공을 줄이고, 핵심 개념·구현 패턴·실수·디버깅 지침을 압축한 Claude.md를 정비한다.
• Claude.md와 MCPDoc 조합에서 검증된 방식으로 실험 환경을 구성하고 스모크·요구사항·LLM-as-a-Judge 평가를 동시에 적용한다.

❓ 열린 질문

• 일반 에이전트 성능이 약한 영역을 기준 없이 전면 확대하면 오히려 효율이 떨어질 가능성은 어디까지인가?
• 핵심만 담은 Claude.md를 만들 때 어느 범위까지를 '핵심'으로 두고 어떤 정보를 제외해야 컨텍스트 소모를 줄일 수 있을까?
• MCPDoc 조회 의존도를 높일수록 문서 창고 의존이 커지는데, 스모크·요구사항·LLM-as-a-Judge 평가에서 실패 시 우선 조정할 기준은 무엇인가?