Рабочий процесс с ИИ

Этот проект создан с помощью Claude Code. Большинство заявлений «создано с помощью ИИ» заканчиваются на ярлыке. Здесь — полная картина: что знает ИИ, как устроены сессии, как выглядит промптинг на практике и где человек проводит черту. Если вы сами работаете с ИИ или просто хотите узнать, как это выглядит на самом деле, — это для вас.

Что знает ИИ

У Claude Code есть файл постоянной памяти, который переносит контекст между сессиями. Вместо того чтобы заново изучать кодовую базу в каждом разговоре, он продолжает с того места, где мы остановились. Вот что в нём содержится (в очищенном виде):

Идентичность проекта

Название приложения, расположение исходного кода, лицензия, идентификатор приложения
Связь форков: апстрим — En Croissant от Francisco Salgueiro, мы поддерживаем собственный форк независимо
Причина форка: мейнтейнер апстрима отклонил функцию TTS, что справедливо — разные видения одного и того же проекта

Правила сборки

Только pnpm — npm ломает vanillaExtract (белый экран при запуске, без ошибок, просто ничего)
Требуется Node.js 22+ (Vite 7 нуждается в crypto.hash)
Всегда выполнять pnpm format && pnpm lint:fix перед коммитом
Закрыть приложение перед перезаписью бинарного файла (“Text file busy”)
После перемещения директорий с исходным кодом — cargo clean для очистки устаревших ссылок на пути

Знание архитектуры

Какие файлы отвечают за какие функции (атомы в atoms.ts, навигация по дереву в tree.ts, движок TTS в tts.ts)
Почему всем атомам TTS нужен getOnInit: true (императивное чтение через store.get() до подписки React)
Как работает кэш аудио (ключи вида provider:voiceId:lang:text)
Исправление координат chessground выполнено на стороне CSS, а не через форк библиотеки
Структура данных: что где хранится, что является симлинком, что сохраняется после перезапуска приложения

Чего он не знает

Память не содержит API-ключей, паролей или учётных данных. Она ссылается на места их хранения (имена атомов в localStorage), но никогда — на сами значения. ИИ генерирует код, который считывает ключи из настроек — он никогда не видит и не обрабатывает реальные секреты.

Какие инструкции получает ИИ

Помимо файла памяти, Claude Code следует правилам, заложенным в его систему:

Не усложнять. Вносить только те изменения, которые непосредственно запрошены. Исправление бага не требует наведения порядка в окружающем коде. Три похожие строки кода лучше преждевременной абстракции.
Не выдумывать URL. Никогда не фабриковать ссылки или эндпоинты.
Читать перед редактированием. Никогда не предлагать изменения в код, который не был прочитан.
Предпочитать редактирование созданию. Не создавать новые файлы без крайней необходимости.
Никаких уязвимостей. Следить за инъекциями, XSS и проблемами из OWASP top 10.
Спрашивать при неуверенности. Если инструкция неоднозначна — спросить, а не угадывать.
Семь раз отмерь, один раз отрежь. Деструктивные операции (force push, reset —hard, удаление файлов) требуют явного одобрения человека.

Как писать хорошие промпты

Разница между полезным взаимодействием с ИИ и бесполезным почти всегда определяется промптом.

Будьте конкретны в том, что вам нужно. Не «исправь баг», а «ключ кэша TTS не включает имя провайдера, поэтому при переключении с ElevenLabs на Google воспроизводится кэшированное аудио ElevenLabs вместо генерации нового».

Включайте контекст, которого у ИИ нет. ИИ может прочитать ваш код, но не может прочитать ваши мысли. «Пользователь сообщил, что координаты на доске перепутаны» менее полезно, чем «CSS в chessgroundBaseOverride.css содержит перепутанные горизонтали и вертикали — в оригинале Francisco они были в обратном порядке».

Обозначьте ограничения. «Не создавай новые файлы», «используй существующий паттерн атомов» или «это должно работать без API-ключа» — указывайте ИИ, где проходят границы.

Скажите, чего вы не хотите. «Не добавляй обработку ошибок для случаев, которые не могут произойти» или «не рефактори окружающий код» предотвращают чрезмерное усложнение — самый распространённый режим отказа ИИ.

Паттерн таков: намерение + контекст + ограничения. Освойте его — и ИИ станет кратно полезнее.

Режим планирования: использование одного Claude для промптинга другого

Claude Code имеет «режим планирования», который отделяет размышление от действия. В режиме планирования ИИ читает файлы, исследует кодовую базу и составляет план — но не пишет код. Вы просматриваете план, корректируете его, а затем переключаетесь в режим реализации, где ИИ выполняет задуманное.

Почему это работает? Потому что самая сложная часть любой задачи программирования — не написание кода. Это определение того, какой код писать: какие файлы менять, каким паттернам следовать, какие граничные случаи существуют. Режим планирования полностью посвящает внимание этому вопросу, прежде чем будет написана хотя бы одна строка.

Пример из этого проекта: когда мы перестраивали меню «Помощь» для добавления выбора языка, в сессии режима планирования мы исследовали, как работают меню Tauri, какие атомы уже существуют, как просмотрщик документации разрешает пути к ресурсам и как выглядит API диалога подтверждения. К моменту переключения в режим реализации у ИИ была полная карта изменений. Никаких фальстартов.

По сути, вы используете один экземпляр ИИ как старшего архитектора, а другой — как разработчика. Одна и та же модель, разные роли.

Как устроены сессии

Типичная сессия выглядит так:

Человек формулирует намерение. «Добавить примечание о кэшировании в раздел KittenTTS.» «Убрать телеметрию PostHog.» «Оценки качества неправильные, вот какими они должны быть.»
ИИ читает соответствующие файлы. Он не гадает, что в файле. Он читает его, понимает текущее состояние, затем предлагает изменения. Несколько файлов читаются параллельно, когда они независимы.
ИИ вносит изменение. Точечные правки в существующих файлах. Не переписывание — хирургические модификации, сохраняющие всё вокруг.
Человек проверяет. Каждая правка показывается до записи на диск. Человек одобряет, отклоняет или перенаправляет. «Нет, это слишком мягко — скажи, что оно реально паршивое.» «Перенеси этот абзац выше.» «Я имел в виду не это.»
Коммит по команде. ИИ никогда не коммитит по собственной инициативе. Человек говорит «коммит» или «коммит и пуш». Коммиты включают Co-Authored-By: Claude Opus 4.6 — всегда с указанием авторства, никогда скрытно.

Контекстные окна и точки сохранения

У каждого разговора с ИИ есть контекстное окно — общий объём текста, который он может удерживать в памяти одновременно. Когда разговор становится достаточно длинным, старые сообщения сжимаются, чтобы освободить место.

Две стратегии: держать разговоры сфокусированными (одна задача на разговор) и использовать точки сохранения (Claude Code сохраняет стенограммы в виде JSONL-файлов, от которых можно возобновить работу с полным восстановлением контекста). Файл памяти служит другой цели — это постоянная база знаний, которая сохраняется между всеми разговорами.

Что предлагает ИИ и что попадает в релиз

Первое предложение ИИ редко становится финальной версией. Типичный обмен:

ИИ набрасывает что-то разумное
Человек говорит «слишком корпоративно», «будь прямее» или «это неправильно, вот почему»
ИИ корректирует
Человек одобряет

Вкус, тон и окончательное решение — всегда за человеком. ИИ обеспечивает скорость: чтение файлов, понимание контекста, точные правки по всей кодовой базе, которую он удерживает в памяти. Человек обеспечивает суждение: что строить, как это должно ощущаться, когда остановиться.

Навыки и слеш-команды

Claude Code поддерживает «навыки» (skills) — переиспользуемые промпты, хранящиеся в виде markdown-файлов в директории .claude/commands/. Они вызываются слеш-командой, например /translate-docs.

В этом проекте используется навык /translate-docs, который автоматизирует перевод документации на несколько языков. Файл навыка содержит полные инструкции: какие файлы переводить, какой формат использовать, как обрабатывать блоки кода и ссылки, какой тон поддерживать. Вместо того чтобы каждый раз всё это объяснять, вы просто набираете /translate-docs, и ИИ точно знает, что делать.

Навыки кодируют процесс, а не просто информацию. Вы можете создавать их для любого повторяющегося рабочего процесса: запуск тестов, деплой, ревью PR, обновление списков изменений.

Принципы написания кода

Полный документ с принципами находится в репозитории по адресу .claude/01_UNIVERSAL_PRINCIPLES.md. Он начинался как Clean Code Роберта Мартина (2008) с дополнениями для эпохи ИИ. Затем мы провели честный разговор о том, что по-прежнему актуально, а что — нет.

Что вечно

Имена, раскрывающие намерение. Всегда. Навсегда.
Функция делает одну вещь. Реальный принцип — связность, а не размер.
Без побочных эффектов. По-прежнему главный источник большинства багов.
Комментарии объясняют «почему», а не «что».
Единственная ответственность. У модуля должна быть одна причина для изменения.
Программируйте на интерфейсы, а не на реализации.
Не глотайте ошибки. Каждая ошибка — это информация.
Эмерджентный дизайн: проходит все тесты, без дублирования, выражает намерение, минимизирует сложность. Именно в таком порядке.

Что зависит от контекста

Эти принципы обоснованы, но конкретные правила отражают мир до ИИ или специфику конкретного языка. Мы применяем дух, а не букву:

DRY. Дублирование, которое расходится со временем, опасно. Но извлечение каждого повторяющегося паттерна в абстракцию создаёт косвенность, которая может быть хуже. Иногда три читаемые строки прямо здесь лучше преждевременной абстракции в другом файле.
Строгий церемониал TDD. Принцип — поставляйте протестированный код, будьте уверены, что он работает — не обсуждается. Церемониал — тест должен существовать до кода — был разработан для рабочего процесса, где люди печатают медленно. Пишите тесты. Убедитесь, что они проходят. Что появилось первым — тест или код — менее важно, чем существование обоих.
Правило бойскаута. «Оставь стоянку чище, чем нашёл» — да. Но бойскаут убирал стоянку, а не весь лес. Исправляй то, к чему прикасаешься. Не рефактори всю структуру файла, потому что изменил в нём одну строку.

Дополнения эпохи ИИ

Руководство на основе принципов масштабируется лучше, чем правила. Принцип допускает суждение; правило хрупко.
Если агент это построил, агент может это поддерживать. Сохраняйте контекст разговоров и артефакты. Документируйте процесс разработки, а не только результат.
Ясность важнее хитроумности. Система, которая это построила, должна уметь восстановить логику рассуждений и корректно внести изменения. Явная структура лучше крошечных хитроумных абстракций.
Может ли это стать инфраструктурой? Инструмент решает проблему для вас. Инфраструктура позволяет другим строить поверх неё. Проектируйте соответственно.

Где человек проводит черту

ИИ — это инструмент. Замечательно хороший. Но есть вещи, которые он не делает:

Продуктовые решения. Какие функции строить, что убрать, каким должно быть ощущение от приложения. «Оценка качества System TTS должна быть “сносно”, потому что оно реально паршивое» — это человеческое суждение, основанное на реальном прослушивании.
Вкус. ИИ может писать чистую прозу, но голос проекта, решение быть прямолинейным в оценке качества, выбор явно отдать должное Francisco — это человеческие решения.
Этика. Удаление PostHog не было задачей рефакторинга. Это было: «страница настроек говорит, что мы не собираем телеметрию, но в коде есть активный API-ключ PostHog. Это ложь. Исправь.» ИИ выполнил. Человек выявил проблему и счёл её важной.
Шахматы. Доску не волнуют ваши инструменты.

Зачем мы это рассказываем

Потому что «создано с помощью ИИ» стало пустой фразой. Все это говорят. Никто не показывает. Интересный вопрос — не в том, участвовал ли ИИ, а в том, как он участвовал и что реально привнёс человек.

Вот ответ. Человек приносит видение, вкус, суждение и ответственность. ИИ приносит скорость, память и неутомимую готовность читать сообщения об ошибках Rust в два часа ночи.

Ни один из них не построит это в одиночку. Оба указаны в авторах. Таковы условия.

En Parlant~ — форк En Croissant от Francisco Salgueiro, созданный с помощью Claude Code от Anthropic.