Claude Code: Up and Running, глава 4: Когда vibe coding недостаточно
Главная мысль: демо показывает, что приложение сработало один раз, а тесты проверяют его каждый раз. Просьба добавить тесты заодно заставляет агента навести порядок в коде. Чтобы решения пережили конец сессии, их записывают в файлы вроде CLAUDE.md и следят за бюджетом context window.
О чём глава
Заголовок раздела «О чём глава»В главе 3 lyrics-trainer научился помнить строку, и автор проверил это руками в браузере. Глава 4 объясняет, как превратить такое демо в cabin — скромный, но надёжный проект. Темы: тесты и рефакторинг, тонкий слой для DOM (DOM glue), память проекта, контекст как бюджет, AGENTS.md и /add-dir.
Демо — это не тест
Заголовок раздела «Демо — это не тест»Ручная проверка сохранения в главе 3 полезна, но это демо. Автор считает демо самым дорогим и ненадёжным способом проверки: оно не проверяет граничные случаи и сбои, а разработчик, который хочет увидеть успех, редко пытается систему сломать. Демо доказывает, что приложение сработало один раз, пока вы смотрели. Тесты же запускаются автоматически и сравнивают результат с известным ответом.
При этом автор не требует теста на каждую строку. Его правило: тестируйте то, что нужно тестировать, то есть обязательные условия, сбои и граничные случаи. Трудность в одном: решить, что именно стоит проверять. Например, CSS тренажёра не нужен unit test (тест одной функции без остальной системы), а номеру строки, переходу с последней строки на первую и запасному варианту для испорченного сохранения тесты нужны.
Вопрос, который меняет код
Заголовок раздела «Вопрос, который меняет код»Глядя на приложение, сделанное через vibe coding, автор первым делом ищет тесты. Обычно их нет, и тогда агента просят их добавить. Часто это запускает рефакторинг, то есть изменение устройства кода без изменения поведения. Запрос в нашем пересказе:
Добавь автоматические тесты для lyrics-trainer. Нужны как минимум тесты напереход к следующей строке, переход с последней строки на первую,продолжение с позиции из localStorage и возврат к строке 0, еслисохранённый индекс испорчен.
Поведение в браузере не меняй. Обойдись без фреймворков.Сначала покажи, какие тесты хочешь добавить. Если текущая структура мешаетих написать, объясни почему и предложи самое маленькое изменение.Запрос не говорит, как менять код: автор рассчитывает, что агент сам предложит вынести JavaScript из файла, где смешаны разметка, стили, клики и localStorage.
Спросите агента, почему код трудно тестировать
Заголовок раздела «Спросите агента, почему код трудно тестировать»На вопрос «почему это неудобно тестировать?» Claude Code отвечает так. Вся логика находится в блоке <script> внутри index.html, и импортировать её нельзя. Даже чистое правило «после строки 13 из 14 идёт строка 0» склеено с кликом, записью в localStorage и обновлением DOM. Проверить его можно только end-to-end тестом с имитацией браузера и клика, а такой тест медленный и хрупкий. Решение — вынести логику в модуль, который получает зависимости параметрами, и оставить сверху тонкий слой для DOM.
Отсюда вывод автора: первый клиент кода — это тест, ведь он должен вызвать функцию, не таща за собой всё приложение. Если код трудно тестировать, им, скорее всего, трудно и пользоваться. В режиме doghouse (маленький проект для себя) этот сигнал можно игнорировать, а в cabin уже нельзя: от кода могут зависеть другие.
Рефакторинг ради тестов
Заголовок раздела «Рефакторинг ради тестов»Приложение умеет шесть вещей: показать строку, перейти к следующей, вернуться к первой после последней, сохранить индекс, продолжить с него и проигнорировать испорченный индекс. Это список для тестов и скрытый план архитектуры: функции делятся на навигацию, сохранение и вывод на страницу.
DOM glue — это тонкий код, который находит элементы страницы, вешает обработчики и вызывает настоящую логику. На схеме слева исходный файл, справа модули: зелёные проверяются тестами без браузера.

В прогоне автора Claude Code сначала предложил ещё меньшую структуру: встроенный тест-раннер Node и один общий файл с логикой. Для просьбы «самое маленькое» это разумно, но автору нужна была структура со схемы, и он поправил агента:
Сделай по схеме тестируемости: lineTrainer.js для навигации по строкам,storage.js для сохранения, main.js для связки с DOM, Vitest для unit-тестов.Оставь код маленьким, но держи эти обязанности раздельно.lyrics-trainer/ CLAUDE.md index.html package.json src/ lineTrainer.js storage.js texts.js main.js test/ lineTrainer.test.js storage.test.jsУрок в том, что «самое маленькое» — не волшебное слово. Если структура меньше, чем нужно вашей цели или соглашениям репозитория, скажите об этом и уточните, какая структура нужна.
Маленькое тестируемое ядро
Заголовок раздела «Маленькое тестируемое ядро»Ядро выглядит скучно, и автор считает это плюсом. Каждая функция делает одно дело и ничего не знает о кнопках, CSS и localStorage. Это принцип единственной ответственности (Single Responsibility Principle) из SOLID. Наша версия:
// Ядро: правила навигации по строкам. Не знает ни про DOM, ни про localStorage.
// Любое плохое значение (не число, меньше 0, за концом текста) превращаем в 0.export function normalizeIndex(value, length) { const index = Number(value); if (!Number.isInteger(index) || index < 0 || index >= length) { return 0; } return index;}
export function createLineTrainer(lines, startIndex = 0) { let index = normalizeIndex(startIndex, lines.length); return { currentLine: () => lines[index], currentIndex: () => index, // После последней строки возвращаемся к первой. next() { index = (index + 1) % lines.length; return lines[index]; }, };}В модуле сохранения главное решение — хранилище приходит параметром. Приложение передаёт браузерный localStorage, а тест передаёт заглушку с теми же методами getItem и setItem. Так вопрос «что значит сохранить» отделён от вопроса «где браузер хранит данные», и к этому агента подтолкнула именно просьба о тестах.
// Сохранение позиции. Хранилище передаём параметром:// в браузере это localStorage, в тестах — простой объект-заглушка.import { normalizeIndex } from "./lineTrainer.js";
export const DEFAULT_KEY = "lyricsTrainer.lineIndex";
export function loadSavedIndex(storage, lineCount, key = DEFAULT_KEY) { return normalizeIndex(storage.getItem(key), lineCount);}
export function saveIndex(storage, index, key = DEFAULT_KEY) { storage.setItem(key, String(index));}Тесты такие же простые:
it("после последней строки возвращается к первой", () => { const trainer = createLineTrainer(lines, lines.length - 1); expect(trainer.next()).toBe(lines[0]); expect(trainer.currentIndex()).toBe(0);});Полный проект с index.html, main.js и тестами лежит в scripts/claude-code-code/ch04_lyrics_trainer.
Тонкий слой для DOM должен быть скучным
Заголовок раздела «Тонкий слой для DOM должен быть скучным»После рефакторинга main.js только создаёт тренажёр с сохранённым индексом, а по клику вызывает next(), сохраняет индекс и перерисовывает строку. Он всё ещё трогает DOM и localStorage, но правил в нём нет. Поэтому, если упадёт браузерный тест, сразу понятно, где искать: в связке со страницей или в логике.
Запустите тесты, потом посмотрите на всё приложение
Заголовок раздела «Запустите тесты, потом посмотрите на всё приложение»Автор удивился, что Claude Code не запустил новые тесты сам, пока его не попросили. Если у вас так же, попросите запустить npm test. У автора вышло 2 файла и 15 тестов за 129 мс. Наша версия из 9 тестов выводит:
Test Files 2 passed (2) Tests 9 passed (9)Браузер должен получать модули JavaScript по HTTP, поэтому страницу теперь открывают не двойным щелчком по файлу, а через локальный сервер: npm start.
Если тесты падают, попросите агента их починить:
Набор тестов Vitest падает. Прочитай вывод, объясни вероятную причину,потом исправь код и тесты, пока всё не пройдёт. Поведение в браузерене меняй. В конце перечисли, что изменил и что проверил.Слова «объясни причину» важны: иначе агент может убрать симптом и не назвать допущение, которое к нему привело. Для таких циклов есть команда /loop, но новые модели обычно и сами повторяют попытки, пока все тесты не пройдут.
После зелёных тестов автор просит агента снова посмотреть на всё приложение: состояние, пробелы в тестах, имена, доступность и места, где одностраничной структуре тесно. Менять ничего нельзя, нужен только отчёт, где у каждой проблемы указаны важность и рекомендация. Запрос о тестах сужает внимание агента до ближайших проблем, а такой обзор снова расширяет его до дизайна.
Сколько тестов достаточно, помогает оценить покрытие кода тестами (code coverage). Автор не гонится за 100%, а тесты, жёстко привязанные к реализации, считает вредными: они мешают будущему рефакторингу. Позже автор подключит SonarCloud с порогом покрытия около 80% и его MCP server, чтобы Claude Code сам получал результаты.
Память проекта: CLAUDE.md
Заголовок раздела «Память проекта: CLAUDE.md»Рефакторинг дал модули, тесты и решения, но с концом сессии ничего из этого не сохранится само. Для этого нужна память проекта (project memory). Claude Code хранит её в текстовом файле CLAUDE.md. Таких файлов может быть несколько: в корне проекта, в .claude проекта, в ~/.claude пользователя и в подпапках. При старте сессии Claude Code объединяет всю иерархию.
Файл можно создать командой /init и потом поправить. Длинным он быть не должен, потому что целиком загружается в контекст каждой сессии. Хороший CLAUDE.md — минимальный набор инструкций, с которым агент ведёт себя последовательно. Наша версия для тренажёра:
# Lyrics Trainer
Браузерное приложение: учим текст из общественного достояния по одной строке.Без фреймворков, логика вынесена в тестируемые модули.
## Архитектура- `index.html` — оболочка страницы.- `src/` — модули с логикой, их покрывают тесты.- `src/main.js` — только связка с DOM.- Тесты лежат в `test/` и запускаются через Vitest.
## Команды- `npm test` — unit-тесты.- `npm start` — локальный сервер на http://localhost:8000.
## Соглашения- Сначала простые модули JavaScript, фреймворк — только по явной просьбе.- API браузера прячем за маленькими функциями, чтобы ядро тестировалось.- Без шага сборки.
## Порядок работы- Перед заметным изменением предложи план.- После новой функции запусти тесты и посмотри на всё приложение целиком.Автор предупреждает: не складывайте в CLAUDE.md всё, что знаете. Пишите факты о проекте и постоянные инструкции, а остальное выносите в файлы и подключайте @-импортом (строка @docs/testing.md). README.md пишут для людей, поэтому не дублируйте в нём инструкции для агента.
Два вида памяти
Заголовок раздела «Два вида памяти»CLAUDE.md пишете вы, а auto memory — это заметки, которые Claude пишет себе сам по вашим поправкам и повторяющимся приёмам. Автор советует представлять себе не один файл памяти, а слои, которые попадают в сессию.

Слева слои от общего к конкретному, справа их вклад в контекст. Что важно помнить:
| Слой | На что обратить внимание |
|---|---|
| Пользователь и организация | Опасно, если локальную привычку записали как общее правило |
| Пути | Правила загружаются вместе с подходящими файлами и после сжатия контекста могут пропасть |
auto memory | Лежит в ~/.claude/projects/<project>/memory/ на вашей машине, в git не попадает, общая для всех worktree репозитория |
Ваш prompt | Обычно самый сильный сигнал, он перебивает размытый унаследованный контекст |
Память — это контекст, а не жёсткое ограничение (enforcement). Она повышает шанс правильного поведения, но не заменяет права, hooks и sandbox из главы 5. Правила для части путей, например tests/**/*.js, кладут в .claude/rules/.
Проверяют память командой /memory: она показывает загруженные CLAUDE.md и правила, включает auto memory и открывает её папку. Автор описывает типичный сбой. В Python-части репозитория Claude узнал, что «мы предпочитаем pytest», а потом предложил pytest для JavaScript-кода на Vitest. Это похоже на случайную ошибку, но, скорее всего, унаследованный контекст применили слишком широко. Запустите /memory, исправьте или удалите заметку в auto memory, сузьте правило в ~/.claude/CLAUDE.md или запишите, что здесь используют Vitest, в память проекта или в правило для путей с тестами JavaScript.
Контекст — это бюджет
Заголовок раздела «Контекст — это бюджет»Каждый запрос несёт всё, что было в сессии: разговор, файлы, вывод команд, сводки и CLAUDE.md. По опыту сообщества, качество ответов падает по мере заполнения context window, даже если всё помещается. У предела Claude Code сам сжимает контекст, но это может случиться посреди задачи, и важные для вас детали пропадут. Ручная команда /compact тоже теряет детали, зато момент выбираете вы.
Перед сжатием полезно запустить /context. Она показывает в токенах и процентах, сколько занимают system prompt, инструменты, память, skill, разговор и сколько места свободно.

С окном 200K сжатие случается часто. С окном 1M оно реже, но если ответы стали хуже, а в контексте уже 300–400K токенов, сжать стоит и при свободном месте. Важное заранее сохраните в файл, а /compact дайте цель:
/compact Сохрани текущую архитектуру lyrics-trainer, план тестов, решениеобойтись без фреймворков, граничные случаи localStorage и открытые задачи.После сжатия попросите контрольную сводку и поправьте её, пока не сработало автоматическое сжатие:
Перечисли, что ты считаешь верным о проекте сейчас: архитектура, командадля тестов, незаконченная работа и решения, к которым не возвращаемсябез моей просьбы.Альтернатива: AGENTS.md
Заголовок раздела «Альтернатива: AGENTS.md»С именами файлов есть историческая ловушка. Anthropic первой назвала файл CLAUDE.md, Google для Gemini CLI (теперь Antigravity CLI) выбрала GEMINI.md, а OpenAI с Codex предложила общий стандарт AGENTS.md. Google согласилась, и Antigravity читает оба файла. Anthropic, по крайней мере на момент написания книги, нет. Поэтому Claude Code читает AGENTS.md, только если его подключить @-импортом:
@AGENTS.md
## Заметки для Claude Code
- Если context window почти полон, перед большим рефакторингом делай /compact.- Перед широкими изменениями используй plan mode.- Команды бери из AGENTS.md, если этот файл не говорит иначе.Команда /init, скорее всего, сама перенесёт нужное из AGENTS.md в новый CLAUDE.md, но это стоит проверить. Главный урок автора: память — не магия, а просто файлы. Если они устарели, размыты или не загружаются, пользы от них нет. «Память» здесь — не RAM, а файлы на диске, которые переживают конец сессии.
Другие папки в проекте: /add-dir
Заголовок раздела «Другие папки в проекте: /add-dir»Иногда нужно расширить не знания агента, а саму границу проекта: фронтенд лежит рядом с API, библиотека — рядом с приложением, а новый проект делают по образцу старого. По умолчанию агент работает только в текущей папке, но команда /add-dir ../my-other-project добавляет в сессию ещё одну. Добавленная папка тоже занимает контекст.
Так автор переносит GitHub workflow между репозиториями с учебными слайдами. Этот workflow собирает PDF из слайдов и публикует его как релиз. Автор один раз сделал его в одном репозитории, а в каждом следующем подключает исходный репозиторий через /add-dir и просит Claude Code настроить ту же автоматизацию. Описывать это в пользовательском CLAUDE.md незачем: процесс нужен только в репозиториях с учебными материалами.
Итоги главы
Заголовок раздела «Итоги главы»- Демо доказывает, что приложение сработало один раз, а тесты проверяют его каждый раз.
- Тестируют обязательные условия, сбои и граничные случаи, а не всё подряд.
- Просьба добавить тесты часто ведёт к рефакторингу: логика уходит в модули, которые проверяются без браузера.
- Зависимости вроде
localStorageлучше передавать параметром, чтобы в тесте их заменила заглушка. CLAUDE.mdдолжен быть коротким, аauto memoryнужно проверять через/memory.- Память — это контекст, а не
enforcement. - Контекст — это бюджет: смотрите
/contextи сжимайте сами через/compactс целью.
Ключевые термины
Заголовок раздела «Ключевые термины»| Термин | Значение |
|---|---|
| тестируемое ядро | Логика отдельно от интерфейса, её проверяют без браузера |
тонкий слой для DOM (DOM glue) | Связывает страницу с ядром, своих правил не содержит |
CLAUDE.md | Инструкции, которые вы пишете сами |
auto memory | Заметки, которые Claude пишет себе сам |
сжатие контекста (compact) | История заменяется сводкой, часть деталей теряется |
Что это значит на практике
Заголовок раздела «Что это значит на практике»- Выносите преобразования
pipelineв чистые функции, а подключение к базе передавайте параметром, тогда pytest проверит логику без хранилища. - В
CLAUDE.mdрепозитория с dbt запишите команды и соглашения по именам, но запрет трогать prod делайте правами.
Вопросы для самопроверки
Заголовок раздела «Вопросы для самопроверки»- Почему проверка руками в браузере — это демо, а не тест?
- Почему просьба добавить тесты часто ведёт к рефакторингу?
- Зачем
storage.jsполучает хранилище параметром? - Что положить в
CLAUDE.md, а что вынести в другие файлы? - Когда разумно сжать контекст, хотя место в окне ещё есть?
Предыдущая: Как говорить с Claude Code.