들어가며: 일단 해보고, 에러 나면 고치는 AI
요즘 클로드코드(Claude Code)와 함께 사이드 프로젝트를 진행하고 있다. CVAT라는 오픈소스 이미지 어노테이션 도구의 API를 내가 만들고 있는 시스템과 연결하는 작업이다.
CVAT은 컴퓨터 비전 분야에서 가장 널리 쓰이는 어노테이션 플랫폼 중 하나로, 이미지와 비디오에 바운딩 박스나 폴리곤 같은 라벨을 붙이는 도구다. REST API를 제공하기 때문에 외부 시스템과 연동이 가능한데, 문제는 이 API가 꽤 방대하고 버전마다 세부 스펙이 다르다는 점이었다.
클로드코드에게 CVAT API 연동 코드를 맡겼을 때, 그 작업 패턴은 대략 이랬다.
나도 한동안 이 흐름을 자연스럽게 따라갔다. AI가 코드를 쓰고, 에러를 보고, 고치는 과정이 빠르니까 그게 효율적이라고 느꼈다. 하지만 수정 횟수가 쌓이면서, 뭔가 근본적으로 잘못되었다는 느낌이 들기 시작했다.
클로드코드는 아주 당당하게 "의심"을 하고, "추론"을 해서 "일단 코드를 만들고 본다"
새로운 외부 서비스와 연동할 때, 숙련된 개발자라면 가장 먼저 API 문서를 펼친다. 엔드포인트가 뭐가 있는지, 인증은 어떻게 하는지, 요청과 응답 포맷이 어떤지 먼저 파악한 뒤에 코드를 쓴다. 모르는 상태에서 일단 호출해보고 에러를 보면서 역추적하는 건 최후의 수단이지, 첫 번째 전략이 아니다.
클로드코드는 정반대로 하고 있었다. 학습 데이터에 포함된 (아마도 오래된 버전의) CVAT 관련 지식을 기반으로 코드를 추측해서 작성하고, 실행 결과를 보고 수정하는 방식이었다. 그러니까 엔드포인트 경로가 달라졌거나, 파라미터 이름이 바뀌었거나, 인증 방식이 변경된 부분을 전부 시행착오로 찾아내고 있었던 셈이다.
Context7이란 무엇인가
이 문제를 해결해준 것이 바로 Context7 MCP다.
Context7은 Upstash에서 만든 MCP(Model Context Protocol) 서버로, AI 코딩 어시스턴트가 라이브러리나 프레임워크의 최신 공식 문서를 실시간으로 참조할 수 있게 해주는 도구다.
핵심 아이디어는 간단하다. LLM의 학습 데이터에는 마감 시점이 있다. 오늘 릴리즈된 라이브러리 버전의 API는 LLM이 알 수 없다. Context7은 이 간극을 메운다. 프롬프트에 "use context7"이라는 한 마디만 추가하면, AI가 해당 라이브러리의 최신 공식 문서를 가져와서 그것을 기반으로 코드를 작성한다.
Context7이 제공하는 두 가지 도구
Context7 MCP 서버는 두 가지 핵심 도구를 제공한다.
라이브러리 이름을 입력하면, Context7이 인식할 수 있는 고유 라이브러리 ID로 변환한다. 예를 들어 "nextjs"라고 입력하면 /vercel/next.js 같은 ID를 돌려준다.
라이브러리 ID와 질문을 넣으면, 해당 라이브러리의 최신 문서에서 관련 내용을 찾아 반환한다. 단순히 문서 전체를 던져주는 게 아니라, 질문과 관련성이 높은 부분을 선별해서 제공한다.
기존 방식과의 차이
"React에서 서버 컴포넌트 만들어줘" → AI가 학습 데이터에 있는 (어쩌면 2년 전의) 문법으로 코드를 작성 → 실행 → 에러 → "아, 이 API는 deprecated 됐구나" → 수정 → 또 에러...
"React에서 서버 컴포넌트 만들어줘, use context7" → AI가 React 최신 공식 문서를 먼저 참조 → 현재 버전에 맞는 정확한 코드 작성
탭을 전환해서 문서를 복사할 필요도 없고, 존재하지 않는 API에 대한 환각도 없다.
내 경험: CVAT API 연동에 Context7을 적용하다
다시 내 프로젝트 이야기로 돌아오자.
시행착오를 반복하던 중, "사람처럼 문서부터 읽히자"는 생각이 떠올랐다. 마침 클로드코드에 Context7 MCP를 연결해둔 상태였다.
쏟아진 수정사항들
클로드코드가 CVAT의 최신 API 명세를 읽고 나서, 기존 코드에서 발견한 문제들이 줄줄이 나왔다. 한두 개가 아니었다.
그동안 "에러 → 수정 → 에러 → 수정"을 반복하면서 하나씩 고쳤던 문제들이, 문서를 먼저 읽히는 것만으로 한 번에 드러난 것이다. 시행착오로 세 시간 동안 잡던 것을 문서 한 번 읽히는 것으로 몇 분 만에 정리할 수 있었다.
더 중요한 건 시행착오로는 발견하기 어려웠을 문제들도 같이 잡혔다는 점이다. "실행하면 에러가 나는 코드"는 금방 고칠 수 있지만, "실행은 되지만 잘못된 방식으로 동작하는 코드"는 나중에 훨씬 큰 문제를 일으킨다. API 명세를 기반으로 코드를 검토하니까 이런 잠재적 버그들까지 사전에 잡아낼 수 있었다.
교훈: AI에게도 "작업 순서"가 필요하다
이 경험에서 얻은 가장 큰 깨달음은, AI도 사람과 같은 작업 순서를 따라야 더 좋은 결과를 낸다는 것이다.
사람이 개발할 때 지키는 기본 원칙들이 있다.
문서를 먼저 읽는다.
전체 구조를 파악한 뒤에 코드를 작성한다.
한 번에 완성하려 하지 않고, 작은 단위로 확인한다.
AI 코딩 어시스턴트에게도 이런 원칙이 적용되어야 한다. 하지만 기본 상태의 AI는 이런 절차를 스스로 밟지 않는다. 학습 데이터 안에서 답을 찾으려 하고, 모르면 추측한다. 그래서 우리가 명시적으로 "문서부터 읽어"라고 말해줘야 한다.
Context7 같은 MCP가 있으면 이 지시가 실제로 동작한다. "문서 읽어"라고 말하면 진짜 최신 문서를 가져와서 읽을 수 있으니까.
Context7 설치하기
Context7은 설치도 간단하다. 클로드코드를 사용한다면, 터미널에서 한 줄이면 된다.
claude mcp add context7 -- npx -y @upstash/context7-mcp사실...코드 입력도 필요 없다. 그냥 클로드코드에게 "Context7 MCP 깔아서 전역에 연결 시켜" 한마디 하면 된다.
Cursor, VS Code, Windsurf 등 MCP를 지원하는 대부분의 에디터에서 사용 가능하다.
한 발 더: 자동으로 Context7을 호출하게 만들기
이건 클로드에게 context7 쓴다고 하니 알려주는 팁인데, 괜찮은 것 같아서 추가 한다.
매번 프롬프트에 "use context7"을 붙이는 것도 번거로울 수 있다. 클로드코드라면 프로젝트 루트의 CLAUDE.md 파일에 다음과 같은 규칙을 추가하면, 라이브러리 관련 질문에 자동으로 Context7을 호출하도록 설정할 수 있다.
Always use context7 when I need code generation, setup or configuration steps, or library/API documentation.이렇게 하면 별도로 지시하지 않아도 AI가 알아서 문서를 참조한 뒤 코드를 작성한다.
마치며: AI 시대에 더 중요해진 "기본기"
돌이켜보면 이 경험의 핵심은 도구가 아니라 사고방식에 있었다.
AI가 코드를 대신 작성해주는 시대가 왔지만, 좋은 코드를 만드는 원칙은 변하지 않았다. "문서부터 읽는다"라는 너무나 당연한 원칙이, AI를 활용할 때도 여전히 유효하다는 걸 다시 한번 확인한 것이다.
AI 코딩 어시스턴트는 강력하지만, 스스로 알아서 최선의 절차를 밟지는 않는다. 그래서 우리의 역할이 중요하다. AI에게 "뭘 만들어줘"만 말하는 것이 아니라, "어떤 순서로 만들어줘"까지 안내해줘야 한다. 그리고 Context7 같은 MCP는 그 안내를 실제로 실행 가능하게 만들어주는 다리 역할을 한다.
다음에 AI와 함께 외부 API를 연동할 일이 있다면,
"일단 해봐" 대신 "문서부터 읽고 해봐"라고 말해보길 권한다.
그 한 마디가 만들어내는 차이는 생각보다 크다.
