Вы просите Claude Code сделать шахматы в браузере. Открываете страницу: доска на месте, фигуры расставлены, пешка послушно движется за мышью. Можно играть. Но для проверки вы тянете её сразу на три клетки вперёд - и она там остаётся. Потом пробуете походить чёрными два раза подряд. Страница снова не возражает.
До этих двух ходов проект выглядел почти готовым. Теперь выясняется, что главное ещё не работает: никто не проверяет правила. Можно попросить агента запретить пешке такой ход. Но следом придётся разобраться с очередностью, шахом, рокировкой, превращением пешки. После каждого исправления остаётся вопрос: какое условие вы ещё забыли?
В этот момент полезно остановиться и поискать готовый код для этой задачи. Правила шахмат уже реализованы в библиотеке chess.js. Ей можно передать ход и получить результат проверки. Тогда собственный код отвечает за понятную связку: взять действие с доски, проверить его через библиотеку и показать правильное положение фигур.
Остаётся доставить библиотеку в браузер и включить её в работу страницы. Один из способов - загрузить её по ссылке через CDN. Ниже разберём, как это устроено и почему появившаяся в коде ссылка ещё не означает, что пешка перестала ходить куда угодно.
Что делает библиотека
Библиотека - это чужой код, который вы подключаете к своему проекту, чтобы не писать заново уже написанное. chess.js ровно такой случай: она знает, как ходит каждая фигура, что такое шах и рокировка, умеет перечислить все допустимые ходы из текущего положения и сказать, закончилась партия или нет.
И тут легко попасть в ловушку: подключить библиотеку и ждать, что игра заработает. Не заработает. Библиотека держит правила и положение партии у себя в памяти, она ничего не рисует и вообще не подозревает, что на странице есть доска.
| Кто | За что отвечает | Что будет, если этого нет |
|---|---|---|
Библиотека chess.js | правила и текущее положение партии: какие ходы возможны, чей ход, закончилась ли игра | ходы никто не проверяет, доска разрешает что угодно |
| Интерфейс страницы | доска, фигуры, перетаскивание, подсветка клеток | играть не во что: правила есть, а трогать их нечем |
| Связующий код | передаёт сделанный ход в библиотеку и перерисовывает доску по её ответу | правила и картинка живут отдельно и никак не влияют друг на друга |
Посмотрите, что происходит при обычном ходе. Вы тянете пешку с e2 сразу на e5. Интерфейс видит перетаскивание, связующий код спрашивает у библиотеки "такой ход допустим?", библиотека отвечает "нет" - и связующий код возвращает фигуру обратно на e2. Если этот вопрос никто не задал, пешка спокойно встанет на e5: рисовать её там странице ничего не мешает.
Обе ветки заканчиваются одним действием: связующий код показывает положение из библиотеки. После допустимого хода оно уже новое, после недопустимого остаётся прежним, поэтому фигура возвращается на исходную клетку.
Отсюда вывод про формулировку поручения. Просьба "подключи chess.js" выполнима буквально - появится строчка загрузки, и на этом всё. Просить надо связку: ход с доски уходит в библиотеку, ответ библиотеки решает, двигать фигуру или нет, а положение после хода берётся из состояния библиотеки, а не из того, куда вы отпустили мышь.
Их легко перепутать, потому что и то и другое "подключают". Skill меняет поведение самого агента - расширяет его инструкции, добавляет ему умение. Библиотека агента не касается вовсе: это код внутри вашего приложения, он выполняется у пользователя в браузере. Агент может её подключить, но работает она потом и без него.
Как браузер получает код через CDN
Файл библиотеки надо откуда-то взять. Можно скачать его и положить рядом со своей страницей, а можно указать в коде страницы ссылку на этот файл у внешнего сервиса. Для этого часто используют CDN (Content Delivery Network, сеть доставки содержимого). Это сеть серверов, которые отдают файлы пользователям из разных мест. Через CDN доставляют, например, картинки, стили и JavaScript-библиотеки. В нашем примере файл библиотеки отдаёт сервис 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 можно только импортом; обычный тег <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-страницы можно сразу указать, что вы хотите сохранить существующий способ запуска.
Подключи chess.js по выбранному CDN-адресу с фиксированной версией.
Сохрани существующий способ запуска страницы. Свяжи библиотеку
с доской: передавай ей каждый ход и показывай позицию из её состояния.
При недопустимом ходе возвращай фигуру на исходную клетку.
Покажи, где добавлено подключение и где обрабатывается ответ библиотеки.Здесь два отдельных результата: браузер получил библиотеку, а действия на доске начали проходить через её правила. Попросив показать оба места в коде, вы сможете увидеть, что именно агент добавил.
Проверить результат в браузере
Наличие ссылки в HTML подтверждает только правку файла. Следующее поручение помогает проверить саму загрузку и поведение игры.
Открой страницу и проверь загрузку chess.js во вкладке Network
панели разработчика. Проверь ошибки в Console. Затем из начальной
позиции попробуй e2-e5: ход должен быть отклонён, пешка остаться на e2.
После этого сделай e2-e4: ход должен пройти, очередь перейти к чёрным.
Сообщи, что наблюдал на каждом шаге. Если у тебя нет доступа к браузеру,
дай мне короткие шаги проверки и укажи, что сам не проверял.Во вкладке Network видны сетевые запросы страницы, в Console - сообщения и ошибки её кода. Если файл загрузился, но пешка всё равно проходит на e5, искать причину нужно уже в обработке хода. Замена CDN-ссылки сама по себе эту связь не исправит.
Разобраться с ошибкой загрузки
При сбое передайте агенту точный текст ошибки из Console и адрес неудачного запроса из Network. Так он сможет проверить конкретную причину, а не перебирать ссылки.
После подключения библиотеки страница выдаёт ошибку.
Текст из Console: [вставьте сообщение целиком].
URL и результат запроса в Network: [вставьте адрес и статус].
Проверь, доступен ли файл, подходит ли его формат для нашего импорта
и совпадают ли имена в коде с документацией выбранной версии.
Сначала назови причину на основе этих данных, затем внеси минимальную
правку и повтори проверку. Не меняй одновременно CDN, версию и код игры.Текст в квадратных скобках замените своими данными. Если запроса библиотеки в Network вообще нет, так и напишите: это тоже полезная зацепка. После исправления повторите проверку двух ходов, чтобы убедиться, что заработала вся связка.
Предусмотреть недоступность CDN
Если библиотека не загрузилась, активная доска может создать ложное впечатление, что играть всё ещё можно. Попросите агента сделать это состояние понятным пользователю.
Обработай ситуацию, когда chess.js не удалось загрузить с CDN.
Пока библиотека не готова, не разрешай делать ходы. При ошибке покажи
понятное сообщение и возможность повторить загрузку страницы.
Проверь поведение при заблокированном запросе к CDN, а затем после
снятия блокировки. Учти кеш: простое отключение сети может оставить
доступной ранее загруженную копию. Опиши, как именно проверял сбой.Такую проверку удобнее проводить отдельно от обычной партии. В результате вы должны увидеть два понятных состояния: библиотека доступна и ходы проверяются; загрузка не удалась и страница объясняет, почему пока нельзя играть.