브라우저 프로젝트의 라이브러리와 CDN

Claude Code에 브라우저에서 체스를 만들라고 요청했다고 해 보세요. 페이지를 열면 체스판도 있고 말도 배치되어 있으며, 폰은 마우스를 따라 얌전히 움직입니다. 게임을 할 수 있겠죠. 그런데 확인하려고 폰을 한 번에 세 칸 앞으로 끌어다 놓아도 그 칸에 그대로 놓입니다. 이번에는 흑으로 두 번 연속 움직여 봅니다. 페이지는 또 아무런 제지도 하지 않습니다.

이 두 수를 두기 전까지는 프로젝트가 거의 완성된 것처럼 보였습니다. 이제야 핵심 기능이 아직 작동하지 않는다는 사실이 드러납니다. 규칙을 확인하는 코드가 없는 거죠. 에이전트에게 폰의 그런 이동을 막아 달라고 할 수는 있습니다. 하지만 다음에는 차례, 체크, 캐슬링, 폰의 승격도 처리해야 합니다. 하나씩 고칠 때마다 또 묻게 됩니다. 어떤 조건을 빠뜨렸을까요?

이럴 때는 잠시 멈추고 이 문제에 쓸 수 있는 기존 코드를 찾아보는 편이 좋습니다. 체스 규칙은 chess.js 라이브러리에 이미 구현되어 있습니다. 이 라이브러리에 수를 전달하면 유효한지 확인한 결과를 받을 수 있습니다. 그러면 직접 작성할 코드는 명확하게 연결하는 역할만 합니다. 체스판에서 동작을 가져와 라이브러리로 확인하고, 말의 올바른 위치를 화면에 표시하면 됩니다.

이제 라이브러리를 브라우저로 가져와 페이지에서 사용하도록 연결해야 합니다. 한 가지 방법은 CDN 링크를 통해 불러오는 것입니다. 아래에서 그 과정과, 코드에 링크가 생겼다고 해서 폰이 마음대로 움직이지 않게 되는 건 아닌 이유를 살펴보겠습니다.

라이브러리의 역할

라이브러리는 이미 작성된 코드를 다시 만들지 않도록 프로젝트에 연결해 쓰는 다른 사람의 코드입니다. chess.js가 바로 그런 라이브러리입니다. 각 말의 움직임과 체크, 캐슬링을 알고 있고 현재 위치에서 가능한 수를 모두 나열하거나 게임이 끝났는지 알려줄 수 있습니다.

여기서 라이브러리를 연결하기만 하면 게임이 작동할 거라고 기대하는 실수에 빠지기 쉽습니다. 그렇지 않습니다. 라이브러리는 규칙과 게임 상태를 메모리에 보관할 뿐, 화면에 아무것도 그리지 않습니다. 페이지에 체스판이 있다는 사실도 알지 못합니다.

일반적인 수를 둘 때 어떤 일이 일어나는지 보겠습니다. 폰을 e2에서 e5로 바로 끌어 보세요. 인터페이스가 드래그를 감지하면 연결 코드가 라이브러리에 "이 수가 유효한가요?"라고 묻습니다. 라이브러리는 "아니요"라고 답하고, 연결 코드는 말을 e2로 돌려놓습니다. 이 확인 과정이 없다면 폰은 그대로 e5에 놓입니다. 페이지가 그 위치에 말을 그리지 못할 이유는 없으니까요.

두 경우 모두 마지막 동작은 같습니다. 연결 코드가 라이브러리의 게임 상태를 체스판에 표시합니다. 유효한 수라면 위치가 바뀌고, 유효하지 않으면 기존 상태를 유지하므로 말은 원래 칸으로 돌아옵니다.

이제 요청을 어떻게 써야 할지 알 수 있습니다. "chess.js를 연결해 줘"라고만 하면 말 그대로 로딩 코드 한 줄이 추가되고 그걸로 끝입니다. 필요한 건 전체 연결 과정입니다. 체스판에서 둔 수를 라이브러리에 전달하고, 응답에 따라 말을 움직일지 결정하며, 수를 둔 뒤의 위치는 마우스를 놓은 곳이 아니라 라이브러리의 상태에서 가져오도록 요청하세요.

CDN으로 브라우저에 코드를 전달하는 방법

라이브러리 파일을 가져올 방법이 필요합니다. 파일을 다운로드해 페이지 옆에 둘 수도 있고, 페이지 코드에 외부 서비스의 파일 링크를 적을 수도 있습니다. 이때 자주 사용하는 것이 CDN(Content Delivery Network, 콘텐츠 전송 네트워크)입니다. 여러 지역의 사용자에게 파일을 전달하는 서버 네트워크죠. 이미지, 스타일, JavaScript 라이브러리 등을 CDN으로 전달합니다. 이 예제에서는 jsDelivr가 라이브러리 파일을 제공합니다.

페이지를 열면 브라우저가 코드를 읽다가 라이브러리 링크를 발견합니다. 해당 주소로 파일을 요청하고 다운로드한 다음, 라이브러리를 사용하는 페이지 코드를 실행합니다. 라이브러리는 사용자의 브라우저에서 작동합니다. CDN은 코드를 전달할 뿐이고, 체스 수의 유효성 확인은 여러분의 기기에서 이루어집니다.

그림의 테두리는 브라우저와 외부 서비스를 구분합니다. 파일을 불러온 뒤 라이브러리는 페이지 안에 있으므로 연결 코드도 그곳에서 라이브러리를 사용합니다. 수를 둘 때마다 CDN에 요청을 보낼 필요는 없습니다.

chess.js는 다음과 같이 연결합니다.

<script type="module">
  import { Chess } from 'https://cdn.jsdelivr.net/npm/chess.js@1.4.0/+esm'

  const chess = new Chess()
  console.log(chess.fen())
  // rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
</script>

여기서 중요한 점은 세 가지입니다. 첫째는 type="module"입니다. 라이브러리가 ES 모듈로 제공되므로 Chess를 가져오려면 import를 사용해야 합니다. 일반적인 <script src="..."> 태그는 이 파일을 해석하지 못하고 내부의 export에서 오류가 납니다. 일부 라이브러리는 모듈을 사용하지 않는 구형 배포 형태도 제공합니다. 이 경우 일반 태그만으로 충분하고, 페이지에 전역 변수가 자동으로 생깁니다. chess.js에는 그런 빌드가 없으므로 방법은 하나뿐입니다.

둘째는 주소에 버전 번호가 포함되어 있다는 점입니다. chess.js@1.4.0처럼요. 연결 방법과 메서드 이름은 링크에 지정된 버전의 문서를 기준으로 해야 합니다. 버전 번호가 없는 주소는 언젠가 다른 파일을 가리키게 되며, 이전 문서를 기준으로 작성한 코드는 작동을 멈춥니다.

셋째는 가장 눈에 잘 띄지 않는 부분, 주소 끝의 /+esm입니다. 장식이 아니라 CDN에 파일을 모듈 형식으로 제공해 달라는 표시입니다. 이를 빼면 같은 주소에서 다른 빌드가 전달되어 import가 모듈을 찾지 못합니다.

게임을 전부 만들지 않고도 라이브러리가 제대로 로드되는지 확인할 수 있습니다. 같은 <script type="module">에 몇 줄을 추가한 다음 브라우저 개발자 도구의 Console 탭을 여세요(F12 또는 Ctrl+Shift+I).

// 흰 폰은 e2에서 e5로 바로 이동할 수 없습니다
try {
  chess.move('e5')
} catch (error) {
  console.log('수가 거부되었습니다:', error.message) // Invalid move: e5
}

chess.move('e4')          // 이 수는 라이브러리가 허용합니다
console.log(chess.turn()) // b, 흑 차례

콘솔에 시작 위치가 표시되고, 유효하지 않은 수가 거부되며, e4 이후 흑의 차례가 표시되면 파일이 제대로 로드되어 규칙이 작동하는 것입니다. 이제 이 규칙을 체스판과 연결하면 됩니다.

한 가지 오해를 막기 위해 덧붙이겠습니다. CDN을 사용해도 네트워크 의존성은 사라지지 않습니다. 브라우저가 캐시에 저장된 파일을 재사용할 수 있으므로 페이지를 열 때마다 다시 다운로드하는 것은 아닙니다. 하지만 사용할 수 있는 사본이 없고 CDN에도 접속할 수 없다면 라이브러리를 불러오지 못해 게임에서 규칙을 적용할 수 없습니다.

Claude Code와 함께 사용하는 방법

"CDN으로 라이브러리를 연결해 줘"라고만 요청하면 파일을 어디서 가져올지, 어떤 버전을 고를지, 이 페이지에서 어떻게 불러올지, 결과를 어떻게 확인할지 여러 결정을 에이전트에게 맡기게 됩니다. 이런 결정은 요청에 직접 적어 두는 편이 좋습니다. 아래에는 상황별 프롬프트가 있습니다. 전부 사용할 필요는 없습니다.

연결할 링크 선택하기

에이전트가 라이브러리를 제안하면 우선 프로젝트에서 어떻게 연결할지 조사해 달라고 요청하세요. 그러면 구체적인 주소와 그 주소를 선택한 이유를 받을 수 있습니다.

내 페이지가 어떻게 구성되어 있는지 살펴보고 chess.js가 이미 연결되어 있는지도 확인해 줘.
라이브러리와 jsDelivr 문서에서 브라우저에 적합한 CDN 로딩 방법을 찾아봐.
버전이 고정된 URL을 제안하고 주소의 각 부분이 무엇을 뜻하는지 설명해 줘.
문서 링크도 함께 제시해 줘. 아직 코드는 변경하지 마.
문서를 확인할 수 없었다면 그 사실을 알려 줘.

응답에서 버전 번호와 연결 방법, 선택 이유를 확인하세요. "작동하는 링크입니다"라는 말만으로는 부족합니다. 에이전트가 문서와 주소를 대조했는지, 해당 파일이 페이지에 맞는지 알 수 없으니까요.

체스판에 라이브러리 연결하기

주소를 정했다면 에이전트에게 눈에 보이는 결과가 나오도록 요청하세요. 간단한 HTML 페이지라면 기존 실행 방식은 유지하라고 미리 알려 줄 수 있습니다.

선택한 CDN 주소를 사용해 고정 버전의 chess.js를 연결해 줘.
현재 페이지를 실행하는 방식은 그대로 유지해.
라이브러리를 체스판에 연결해서 매 수를 라이브러리에 전달하고,
라이브러리 상태에 있는 위치를 화면에 표시해 줘.
유효하지 않은 수를 두면 말을 원래 칸으로 되돌려.
라이브러리를 불러오는 코드를 추가한 곳과 라이브러리 응답을 처리하는 곳을 보여 줘.

여기에는 두 가지 결과가 있습니다. 브라우저가 라이브러리를 받아야 하고, 체스판의 동작이 라이브러리 규칙을 따라야 합니다. 코드에서 두 부분을 모두 보여 달라고 하면 에이전트가 무엇을 추가했는지 직접 확인할 수 있습니다.

브라우저에서 결과 확인하기

HTML에 링크가 있다는 사실은 파일을 수정했다는 것만 보여 줍니다. 다음 요청으로 실제 로딩과 게임 동작을 확인할 수 있습니다.

페이지를 열고 개발자 도구의 Network 탭에서 chess.js가 로드되는지 확인해 줘.
Console 탭의 오류도 확인해.
시작 위치에서 e2-e5를 시도해 봐. 수가 거부되고 폰이 e2에 남아 있어야 해.
그다음 e2-e4를 둬. 수가 허용되고 흑의 차례로 넘어가야 해.
각 단계에서 관찰한 내용을 알려 줘. 브라우저에 접근할 수 없다면
내가 직접 확인할 수 있는 짧은 절차를 알려 주고, 직접 확인하지 못했다고 밝혀 줘.

Network 탭에서는 페이지의 네트워크 요청을 볼 수 있고, Console에는 코드의 메시지와 오류가 표시됩니다. 파일은 로드됐는데도 폰이 e5로 이동한다면 수를 처리하는 부분에서 원인을 찾아야 합니다. CDN 링크만 바꿔서는 이 연결 문제가 고쳐지지 않습니다.

로딩 오류 해결하기

오류가 발생하면 Console의 정확한 오류 메시지와 Network에서 실패한 요청의 주소를 에이전트에게 전달하세요. 그러면 링크를 이것저것 바꾸는 대신 구체적인 원인을 확인할 수 있습니다.

라이브러리를 연결한 뒤 페이지에서 오류가 발생해.
Console 메시지: [메시지 전체를 여기에 붙여 넣기].
Network 요청 URL과 결과: [주소와 상태를 여기에 붙여 넣기].
파일에 접근할 수 있는지, 우리 import 방식에 맞는 형식인지,
코드의 이름이 선택한 버전의 문서와 일치하는지 확인해 줘.
이 데이터를 바탕으로 먼저 원인을 말한 다음, 최소한으로 수정하고
다시 확인해. CDN과 버전, 게임 코드를 한꺼번에 바꾸지 마.

대괄호 안의 문구를 실제 데이터로 바꾸세요. Network에 라이브러리 요청이 전혀 없다면 그것도 그대로 알려 주세요. 중요한 단서가 됩니다. 수정한 뒤에는 두 수를 다시 확인해 전체 연결이 제대로 작동하는지 살펴보세요.

CDN에 접속할 수 없는 상황 대비하기

라이브러리가 로드되지 않았는데 체스판이 활성화되어 있으면, 계속 게임을 할 수 있다는 착각을 줄 수 있습니다. 사용자에게 이 상태가 분명하게 보이도록 에이전트에게 요청하세요.

CDN에서 chess.js를 불러오지 못하는 상황을 처리해 줘.
라이브러리가 준비될 때까지 수를 둘 수 없게 해.
오류가 발생하면 이해하기 쉬운 메시지와 페이지를 다시 로드하는 방법을 보여 줘.
CDN 요청이 차단된 상태와 차단을 해제한 뒤의 동작을 확인해.
캐시도 고려해. 네트워크를 끄기만 하면 이전에 로드된 사본이 그대로 쓰일 수 있어.
실패 상황을 어떻게 확인했는지 설명해 줘.

이 확인은 일반적인 게임과 분리해서 진행하는 편이 좋습니다. 결과에서 두 가지 상태를 명확히 확인해야 합니다. 라이브러리를 사용할 수 있어 수를 검증하는 상태, 그리고 로딩에 실패해 페이지가 당장은 게임을 할 수 없는 이유를 설명하는 상태입니다.