Працоўны працэс з ШІ

Гэты праект быў створаны з дапамогай 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.» «Ацэнкі якасці няправільныя, вось якімі яны павінны быць.»
ШІ чытае адпаведныя файлы. Ён не здагадваецца, што ў файле. Ён чытае яго, разумее бягучы стан, а потым прапаноўвае змены. Некалькі файлаў чытаюцца паралельна, калі яны незалежныя.
ШІ робіць змену. Мэтанакіраваныя праўкі існуючых файлаў. Не перапісванне — хірургічныя мадыфікацыі, якія захоўваюць усё вакол.
Чалавек правярае. Кожная праўка паказваецца да запісу на дыск. Чалавек зацвярджае, адхіляе або перанакіроўвае. «Не, гэта занадта мякка — скажы, што яно рэальна кепскае.» «Перамясці гэты абзац вышэй.» «Гэта не тое, што я меў на ўвазе.»
Коміт па камандзе. ШІ ніколі не коміціць па ўласнай ініцыятыве. Чалавек кажа «commit» або «commit and push». Коміты ўключаюць Co-Authored-By: Claude Opus 4.6 — заўсёды з указаннем аўтарства, ніколі не ўтоена.

Кантэкстныя вокны і кропкі захавання

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

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

Што прапаноўвае ШІ супраць таго, што выходзіць у рэліз

Першая прапанова ШІ рэдка з’яўляецца канчатковай версіяй. Тыповы абмен:

ШІ піша нешта разумнае
Чалавек кажа «занадта карпаратыўна» або «будзь больш прамым» або «гэта няправільна, вось чаму»
ШІ карэктуе
Чалавек зацвярджае

Густ, тон і фінальнае рашэнне — заўсёды за чалавекам. ШІ забяспечвае хуткасць — чытае файлы, разумее кантэкст, робіць дакладныя праўкі па ўсёй кодавай базе, якую можа ўтрымліваць у памяці. Чалавек забяспечвае меркаванне — што будаваць, як гэта павінна адчувацца, калі спыніцца.

Навыкі і слэш-каманды

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.