Робочий процес з ШІ

Цей проєкт створено за допомогою Claude Code. Більшість заяв «створено з ШІ» обмежуються лише ярликом. Тут — повна картина: що знає ШІ, як працюють сесії, як виглядає промптинг на практиці та де проходить межа людського контролю. Якщо ви самі створюєте щось за допомогою ШІ або вам просто цікаво, як це насправді виглядає, — це для вас.

Що знає ШІ

Claude Code має файл постійної пам’яті, який зберігає контекст між сесіями. Замість того щоб щоразу заново досліджувати кодову базу, він продовжує з того місця, де ми зупинилися. Ось що в ньому міститься (очищена версія):

Ідентичність проєкту

Назва застосунку, розташування вихідного коду, ліцензія, ідентифікатор застосунку
Зв’язок із форком: upstream — це En Croissant від Francisco Salgueiro, ми підтримуємо власний форк незалежно
Чому існує форк: мейнтейнер upstream відхилив функцію 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.» «Рейтинги якості неправильні, ось якими вони мають бути.»
ШІ читає відповідні файли. Він не вгадує, що міститься у файлі. Він читає його, розуміє поточний стан, а потім пропонує зміни. Кілька файлів читаються паралельно, коли вони незалежні.
ШІ вносить зміну. Точкові правки існуючих файлів. Не переписування — хірургічні модифікації, що зберігають усе навколо.
Людина перевіряє. Кожна правка показується до того, як потрапляє на диск. Людина затверджує, відхиляє або перенаправляє. «Ні, це занадто м’яко — скажи, що воно реально відстійне.» «Пересунь цей абзац вище.» «Я мав на увазі не це.»
Коміт за командою. ШІ ніколи не комітить з власної ініціативи. Людина каже «commit» або «commit and push». Коміти містять Co-Authored-By: Claude Opus 4.6 — завжди зазначено авторство, ніколи не приховано.

Контекстні вікна та точки збереження

Кожна розмова з ШІ має контекстне вікно — загальний обсяг тексту, який він може утримувати в пам’яті одночасно. Коли розмова стає достатньо довгою, старіші повідомлення стискаються, щоб звільнити місце.

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

Що ШІ пропонує vs. що потрапляє в реліз

Перша пропозиція ШІ рідко є фінальною версією. Типовий обмін:

ШІ пише щось прийнятне
Людина каже «занадто корпоративно», «будь прямішим» або «це неправильно, ось чому»
ШІ коригує
Людина затверджує

Смак, тон і фінальне рішення — завжди за людиною. ШІ забезпечує швидкість — читання файлів, розуміння контексту, внесення точних правок по всій кодовій базі, яку він утримує в пам’яті. Людина забезпечує судження — що будувати, як це має відчуватися, коли зупинитися.

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

Claude Code підтримує «навички» — повторно використовувані промпти, збережені як 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.